Plans

Fix review-plan agent frontmatter and descriptions to match product-plans pattern

High todo
2026-06-07 agentics fix High effort
Objective

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.

Implement Read and implement all steps in the plan at docs/plans/fix-review-plan-agent-frontmatter.md — Fix review-plan agent frontmatter and descriptions to match product-plans pattern. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/fix-review-plan-agent-frontmatter.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Fix review-plan agent frontmatter and descriptions to match product-plans pattern. The plan at docs/plans/fix-review-plan-agent-frontmatter.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/fix-review-plan-agent-frontmatter.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/fix-review-plan-agent-frontmatter.md — Fix review-plan agent frontmatter and descriptions to match product-plans pattern. Brief subagents with the plan file at docs/plans/fix-review-plan-agent-frontmatter.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/fix-review-plan-agent-frontmatter.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File fix-review-plan-agent-frontmatter.html
Path docs/plans/fix-review-plan-agent-frontmatter.html
Spec docs/plans/fix-review-plan-agent-frontmatter.md
Definition of done 0 / 7 done

Context

The story behind this plan — what prompted the work and why it matters now.

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 reads tools: — allowed-tools: is the correct key for skills ( SKILL.md ), not agents. Every product-plans agent uses tools: . The restriction is likely silently ignored as-is.

Unrestricted Bash: The agents grant bare Bash access, which gives reviewers latent write capability. The product-plans agents use Bash(git *) to restrict Bash to read-only git commands.

Missing "Teammate-only" clause: The product-plans agents 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." The plan-agent reviewer 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 that change

Every file this plan touches, and what happens to each one.

agentics/
  • .claude-plugin/marketplace.json modified bump plan-agent 1.9.0 → 1.10.0
  • kit/plugins/plan-agent/CHANGELOG.md modified add 1.10.0 entry
  • agents/
    • plan-reviewer-architecture.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-completeness.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-testability.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-risk.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-conventions.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-ux.md modified frontmatter key + Bash restriction + teammate clause
    • plan-reviewer-accessibility.md modified frontmatter key + Bash restriction + teammate clause

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
todo Change allowed-tools: to tools: and narrow Bash to Bash(git *) in all 7 agent files
Why
The agent runtime reads 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.
2
todo Append the "Teammate-only" clause to all 7 agent descriptions
Why
Without this clause, the agents may auto-activate on broad intent matches (e.g. "review my architecture"). The clause signals they are designed for team use only, matching the 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.
3
todo Bump plan-agent to 1.10.0 in .claude-plugin/marketplace.json
Why
The frontmatter key change affects runtime behavior (tool restrictions may now be enforced). Per 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.
4
todo Add a v1.10.0 CHANGELOG entry
Why
Project convention requires a CHANGELOG entry for every version bump. Document the three fixes: frontmatter key correction, Bash narrowing, and teammate-only clause addition.
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).
5
todo Validate the plugin structure
Why
Catch frontmatter, JSON, and registration errors before commit. Run /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

The tests that prove the change does what it promises.

Tier 1 — Code-touching plan (agent definition files affect runtime behavior)
Objective Agent frontmatter matches product-plans pattern 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 ).
Unit marketplace.json version and structure 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

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

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.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Add disable-model-invocation to review-plan SKILL.md

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, add `disable-model-invocation: true` to the frontmatter of `kit/plugins/plan-agent/skills/review-plan/SKILL.md`. The skill spawns a costly Agent Team and mutates plan files, so it should only run when explicitly invoked via `/plan-agent:review-plan`, not on ambient intent matching. Update the README to document this as command-only. Bump the version if this is a separate PR from the frontmatter fix.
Add backup-before-mutation to review-plan workflow

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, update `kit/plugins/plan-agent/skills/review-plan/SKILL.md` Step 7 (Integrate) to copy the plan to `<stem>.bak` before the first Edit call. If any Edit fails, abort remaining edits and report the failure rather than continuing with a half-edited plan. This addresses the "self-mutating file with no backup" risk from the team review. Bump version in marketplace.json and add a CHANGELOG entry.
Add a concrete WCAG rubric to plan-reviewer-accessibility Wish List

Speculative / blue-sky idea &mdash; not on the critical path. Paste into Claude when ready to explore:

Paste this prompt into Claude to execute this follow-up:

Explore enriching the `plan-reviewer-accessibility` agent definition in `kit/plugins/plan-agent/agents/plan-reviewer-accessibility.md` with a concrete WCAG 2.1 AA checklist (contrast ratios, touch targets, focus management, ARIA patterns) so its findings are actionable rather than generic. Compare with the `product-reviewer-accessibility-expert` in the product-plans plugin and the `wcag-compliance-reviewer` plugin for reference. Return a design proposal before implementing.