Align the seven plan-reviewer-*.md agent definitions in the plan-agent plugin with the proven product-plans sibling pattern: change the frontmatter key from allowed-tools: to tools:, narrow Bash to Bash(git *), and append the "Teammate-only" clause to every agent description. Bump plan-agent to 1.10.0 as a PATCH fix for functional correctness.
Read and implement all steps in the plan at docs/plans/fix-review-plan-agent-frontmatter.html — Fix review-plan agent frontmatter and descriptions to match product-plans pattern
fix-review-plan-agent-frontmatter.html
docs/plans/fix-review-plan-agent-frontmatter.html
Context
The review-plan Agent Team skill (v1.9.0) shipped with seven plan-reviewer-*.md agent definitions under kit/plugins/plan-agent/agents/. A post-ship team review (add-plan-review-team-skill-review.html) identified two functional correctness issues and one convention gap by comparing the shipped files against the established product-plans sibling agents:
- Wrong frontmatter key: All seven agents use
allowed-tools:in their YAML frontmatter. The agent runtime readstools:—allowed-tools:is the correct key for skills (SKILL.md), not agents. Everyproduct-plansagent usestools:. The restriction is likely silently ignored as-is. - Unrestricted Bash: The agents grant bare
Bashaccess, which gives reviewers latent write capability. Theproduct-plansagents useBash(git *)to restrict Bash to read-only git commands. - Missing "Teammate-only" clause: The
product-plansagents all end their descriptions with "Teammate-only — designed to run inside an Agent Team led by the plan-review-agents skill; not for standalone invocation." Theplan-agentreviewer agents omit this, meaning they may auto-activate on broader intent matches than intended.
This is a PATCH fix (correctness of existing metadata, no new behavior) per marketplace.md versioning rules. The version bump is 1.9.0 → 1.10.0 since the frontmatter key change affects runtime behavior.
Files to Modify
.claude-plugin/marketplace.jsonmodified bump plan-agent 1.9.0 → 1.10.0- kit/plugins/plan-agent/
CHANGELOG.mdmodified add 1.10.0 entry- agents/
plan-reviewer-architecture.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-completeness.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-testability.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-risk.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-conventions.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-ux.mdmodified frontmatter key + Bash restriction + teammate clauseplan-reviewer-accessibility.mdmodified frontmatter key + Bash restriction + teammate clause
Steps
allowed-tools: to tools: and narrow Bash to Bash(git *) in all 7 agent files
tools:, not allowed-tools: (which is the skill-only key). Bare Bash grants write access to reviewers who should only read; Bash(git *) restricts them to git commands, matching the product-plans pattern.Verify
grep -c '^tools:' kit/plugins/plan-agent/agents/plan-reviewer-*.md returns 7 (one per file). grep 'allowed-tools' kit/plugins/plan-agent/agents/plan-reviewer-*.md returns nothing. grep 'Bash(git \*)' kit/plugins/plan-agent/agents/plan-reviewer-*.md returns 7.product-plans convention. The clause format is: Teammate-only — designed to run inside an Agent Team led by the review-plan skill; not for standalone invocation.Verify
grep -c 'Teammate-only' kit/plugins/plan-agent/agents/plan-reviewer-*.md returns 7. Each description still starts with its original lens-specific text and ends with the teammate clause..claude-plugin/marketplace.json
marketplace.md, this is a MINOR bump (1.9.0 → 1.10.0) since it changes agent activation behavior via the description clause. Set version only in marketplace.json, never in plugin.json.Verify
grep -A3 '"plan-agent"' .claude-plugin/marketplace.json | grep version shows "1.10.0". grep version kit/plugins/plan-agent/.claude-plugin/plugin.json returns nothing. node -e "JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json'))" exits 0.v1.10.0 CHANGELOG entry
Verify
grep '1.10.0' kit/plugins/plan-agent/CHANGELOG.md returns a heading line. The entry lists all three changes (frontmatter key, Bash restriction, teammate clause)./validate-plugin plan-agent and confirm all agent definitions parse correctly with the new tools: key.Verify
validate-plugin reports no errors for plan-agent; node -e "JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json'))" exits 0.Tests
Type: Structural validation (smoke test)
Asserts: All 7 plan-reviewer-*.md files use tools: (not allowed-tools:), grant Bash(git *) (not bare Bash), and include the "Teammate-only" description clause — matching the established product-plans agent convention.
Run: grep -cP '^tools:' kit/plugins/plan-agent/agents/plan-reviewer-*.md (expect all 7 return 1); grep -l 'allowed-tools' kit/plugins/plan-agent/agents/plan-reviewer-*.md (expect no output); grep -c 'Teammate-only' kit/plugins/plan-agent/agents/plan-reviewer-*.md (expect all 7 return 1).
File: .claude-plugin/marketplace.json
Targets: plan-agent entry version and JSON validity
Key cases: version is 1.10.0; JSON parses without error; plugin.json has no version key
Acceptance Criteria
Verification
Structural parity check: Run head -6 kit/plugins/plan-agent/agents/plan-reviewer-*.md and head -6 kit/plugins/product-plans/agents/product-reviewer-*.md side by side. The frontmatter shape should now match: both use tools:, both grant Bash(git *), both have a model: field, and both have descriptions ending with a "Teammate-only" clause.
No regressions: The agent body content (mandate, how-to-review, report-back sections) must be byte-identical to the v1.9.0 versions — only the frontmatter block changes.
JSON validity: node -e "JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json'))" exits 0.
Completion Checklist
Completion Report
No items to report — all requirements met.