chore: improve CI workflows with Node.js setup and linting tools

- Add .nvmrc for consistent Node.js version across workflows
- Pre-install markdownlint-cli2 and prettier with npm caching
- Enhance PR template with testing section, version checklist, chore type
- Add track_progress and more allowed tools to @claude workflow
- Improve review instructions with structured steps and inline comments

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: sjnims

.github/pull_request_template.md

@@ -4,13 +4,14 @@
 
 ## Type of Change
 
-<!-- Mark the relevant option with an "x" -->
+<!-- Labels are applied automatically by our semantic labeler. Mark the option that best describes your change: -->
 
 - [ ] Bug fix (non-breaking change that fixes an issue)
 - [ ] New feature (non-breaking change that adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 - [ ] Documentation update (improvements to README, CLAUDE.md, or component docs)
 - [ ] Refactoring (code change that neither fixes a bug nor adds a feature)
+- [ ] Chore (maintenance tasks: dependencies, CI, tooling)
 - [ ] Test (adding or updating tests)
 - [ ] Configuration change (changes to .markdownlint.json, plugin.json, etc.)
 
@@ -31,13 +32,13 @@
 ## Motivation and Context
 
 <!-- Why is this change required? What problem does it solve? -->
-<!-- If it fixes an open issue, please link to the issue here using one of these formats: -->
+<!-- If it fixes an open issue, link to the issue using one of these formats: -->
 <!-- Fixes #123 - closes issue when PR merges -->
 <!-- Closes #123 - same as Fixes -->
 <!-- Resolves #123 - same as Fixes -->
 <!-- Related to #123 - links without closing -->
 
-Fixes # (issue)
+Fixes #
 
 ## How Has This Been Tested?
 
@@ -46,7 +47,7 @@ Fixes # (issue)
 **Test Configuration**:
 
 - Claude Code version:
-- GitHub CLI version: `gh --version`
+- GitHub CLI version:
 - OS:
 - Testing repository: <!-- public repo you tested with, if applicable -->
 
@@ -84,7 +85,22 @@ Fixes # (issue)
 - [ ] Scripts are executable (`chmod +x`)
 - [ ] Scripts use `${CLAUDE_PLUGIN_ROOT}` for portable paths
 
-### Component-Specific Checks
+### Testing
+
+- [ ] I have tested the plugin locally with `claude --plugin-dir plugins/plugin-dev`
+- [ ] I have tested the full workflow (if applicable)
+- [ ] I have verified GitHub CLI integration works (if applicable)
+- [ ] I have tested in a clean repository (not my development repo)
+- [ ] I have run relevant validation scripts (validate-agent.sh, validate-command.sh, validate-hook-schema.sh, etc.)
+
+### Version Management (if applicable)
+
+- [ ] I have updated `plugins/plugin-dev/.claude-plugin/plugin.json` (source of truth)
+- [ ] I have updated `.claude-plugin/marketplace.json` (metadata.version AND plugins[0].version)
+- [ ] I have updated `CLAUDE.md` (Quick Reference section)
+- [ ] I have updated CHANGELOG.md with relevant changes
+
+## Component-Specific Checks
 
 <!-- Only relevant if you modified commands, skills, agents, or hooks -->
 
@@ -123,33 +139,25 @@ Fixes # (issue)
 <details>
 <summary><strong>Hooks</strong> (click to expand)</summary>
 
-- [ ] Hook uses correct event type (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification)
+- [ ] Hook uses correct event type (PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification)
 - [ ] Matchers are properly configured for tool filtering
 - [ ] Hook type is appropriate (prompt for LLM-driven, command for scripts)
 - [ ] Prompt-based hooks have clear, focused instructions
 - [ ] Command-based hooks handle errors gracefully
 
 </details>
 
-### Testing
-
-- [ ] I have tested the plugin locally with `claude --plugin-dir plugins/plugin-dev`
-- [ ] I have tested the full workflow (if applicable)
-- [ ] I have verified GitHub CLI integration works (if applicable)
-- [ ] I have tested in a clean repository (not my development repo)
-- [ ] I have run relevant validation scripts (validate-agent.sh, validate-command.sh, validate-hook-schema.sh, etc.)
+## Example Output (if applicable)
 
-### Version Management (if applicable)
+<!-- Add example CLI output, command results, or JSON to demonstrate your changes -->
 
-- [ ] I have updated version numbers in all version files:
-  - [ ] `plugins/plugin-dev/.claude-plugin/plugin.json` (source of truth)
-  - [ ] `.claude-plugin/marketplace.json` (metadata.version AND plugins[0].version)
-  - [ ] `CLAUDE.md` (Quick Reference section)
-- [ ] I have updated CHANGELOG.md with relevant changes
+```text
+# Example: paste relevant output here
+```
 
 ## Screenshots (if applicable)
 
-<!-- Add screenshots to help explain your changes -->
+<!-- Before/after screenshots or GIFs showing UI changes or visual differences -->
 
 ## Additional Notes
 
@@ -179,3 +187,7 @@ Fixes # (issue)
 - [ ] Labels are appropriate for the change type
 - [ ] Version numbers are updated in all version files (if applicable)
 - [ ] CHANGELOG.md is updated (if applicable)
+
+---
+
+<!-- TIP: Use draft PRs for work-in-progress changes that need early feedback -->

.github/workflows/claude-pr-review.yml

@@ -34,6 +34,22 @@ jobs:
           fetch-depth: 1
           persist-credentials: false
 
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: Cache npm tools
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        id: claude-pr-review-npm-tools-cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-lint-tools-v1
+
+      - name: Install linting tools
+        if: steps.claude-pr-review-npm-tools-cache.outputs.cache-hit != 'true'
+        run: npm install -g markdownlint-cli2 prettier
+
       - name: Review PR with Claude
         uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34
         with:
@@ -47,12 +63,34 @@ jobs:
             - PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }}
             - Author: ${{ github.event.pull_request.user.login }}
             - Base: ${{ github.event.pull_request.base.ref }}
+            - Dependencies: markdownlint-cli2 and prettier are pre-installed globally
+
+            > **Note**: The `component-validation` workflow runs in parallel and validates plugin component
+            > structure (frontmatter fields, JSON schema, etc.). Focus your review on content quality,
+            > best practices, and issues beyond structural validation.
 
             ## Instructions
-            1. Get the PR diff to understand what changed
-            2. If any `.md` files were changed, run `npx markdownlint-cli2 <files>` to check for style issues
-            3. Review the changes against the criteria below
-            4. Post a summary comment with your findings
+
+            ### Step 1: Run Quality Checks
+            Run these checks and note any failures:
+            - `markdownlint-cli2 <changed-md-files>` - Markdown style issues
+            - `prettier --check <changed-md-files>` - Formatting issues
+            - `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh` - Shell script issues (if scripts changed)
+
+            ### Step 2: Review the Diff
+            Run `gh pr diff ${{ github.event.pull_request.number }}` to see all changes.
+
+            ### Step 3: Provide Feedback
+
+            **For specific line-level issues**, use inline comments. Target:
+            - Missing or invalid YAML frontmatter fields
+            - Imperative voice violations in commands ("You should" instead of "Do")
+            - Missing trigger phrases in skill descriptions
+            - `<example>` block formatting issues in agents
+            - Shell script issues (shellcheck findings)
+            - Security concerns
+
+            **For general observations**, post a summary comment.
 
             ## Review Criteria
 
@@ -62,25 +100,28 @@ jobs:
             - **Agents** (`agents/*.md`): Verify <example> blocks for triggering, appropriate tool restrictions.
             - **Hooks** (`hooks/hooks.json`): Validate event types and matcher patterns.
 
-            ### Markdown Quality (run prettier and markdownlint-cli2)
-            Run `npx prettier` and `npx markdownlint-cli2` on changed `.md` files. Key markdown rules enforced:
+            ### Shell Scripts (if changed)
+            - Run shellcheck on any changed `.sh` files in `plugins/plugin-dev/skills/*/scripts/`
+            - Flag any shellcheck errors or warnings
+
+            ### Markdown Quality
+            Key markdown rules enforced:
             - ATX-style headers (`#` not underlines)
             - Dash-style lists (`-` not `*` or `+`)
             - 2-space indentation for nested lists
             - Fenced code blocks (not indented)
-            Include any lint errors in your review under a "Markdown Linting" section.
 
             ### Documentation
             - README.md updates if user-facing changes
             - CLAUDE.md updates if development process changes
 
             ## Output Format
-            Post a PR comment with your review. Structure it as:
-            1. **Summary**: One-line assessment (looks good / needs changes / has concerns)
-            2. **What's Good**: Positive aspects of the PR
-            3. **Suggestions**: Improvements or issues found (if any)
-            4. **Checklist Verification**: Confirm key items are addressed
+            1. Post inline comments for specific issues found in the diff
+            2. Post a summary comment with:
+              - **Verdict**: ✅ Looks good / ⚠️ Needs changes / 🔍 Has concerns
+              - **Quality Checks**: Results from markdownlint, prettier, shellcheck (pass/fail with details)
+              - **What's Good**: Positive aspects of the PR
+              - **Suggestions**: General improvements (not covered by inline comments)
 
             Be constructive and helpful. Focus on significant issues, not nitpicks.
-            If the PR looks good, say so briefly - don't invent problems.
-          claude_args: '--model claude-opus-4-5-20251101 --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*),Bash(npx markdownlint-cli2:*),Bash(npx prettier:*),Read,Glob,Grep"'
+          claude_args: '--model claude-opus-4-5-20251101 --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*),Bash(markdownlint-cli2:*),Bash(prettier:*),Bash(shellcheck:*),Read,Glob,Grep"'

.github/workflows/claude.yml

@@ -50,22 +50,39 @@ jobs:
       contents: write # Write access for pushing branches
       pull-requests: write
       issues: write
-      id-token: write
       actions: read # Required by claude-code-action to access workflow run data
+      id-token: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 20
 
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: Cache npm tools
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        id: at-claude-npm-tools-cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-lint-tools-v1
+
+      - name: Install linting tools
+        if: steps.at-claude-npm-tools-cache.outputs.cache-hit != 'true'
+        run: npm install -g markdownlint-cli2 prettier
+
       - name: Run Claude Code
         id: claude
         uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           use_commit_signing: true
+          track_progress: true
           additional_permissions: |
             actions: read
           claude_args: |
             --model claude-opus-4-5-20251101
-            --allowedTools "Read,Glob,Grep,Task,Bash(gh pr:*),Bash(gh issue:*),Bash(gh run:*),mcp__github_inline_comment__create_inline_comment,mcp__github_ci__get_ci_status,mcp__github_ci__download_job_log"
+            --allowedTools "Read,Edit,Write,Glob,Grep,Task,Bash(gh pr:*),Bash(gh issue:*),Bash(gh run:*),Bash(gh release:*),Bash(markdownlint-cli2:*),Bash(prettier:*),Bash(shellcheck:*),mcp__github_inline_comment__create_inline_comment,mcp__github_ci__get_ci_status,mcp__github_ci__download_job_log"

.nvmrc

@@ -0,0 +1 @@
+25.3.0