feat(development-planning): migrate prompts for Opus 5 behavior - #568
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
● Reviewed · against Latest: ✅ approved (1) ← prior: 🚨 changes requested (1) ← 🚨 changes requested (2) Note Approved — one warning in Migrates the development-planning plugin's prompts for Opus 5: removes mandated pre-think phases, converts agent-count floors to ceilings, drops a recall filter and a fabricated timeline field, and replaces ~13 nonexistent agent names with real dispatch names. AssessmentThe migration checks out against the repo: all 14 dispatch names in the new Suggestions
Iteration history · 3 reviews2026-08-06 00:03 UTC · ✅ approved · 1 finding ·
|
📚 Documentation Check ✅Verdict: Passed The only plugin touched (development-planning) had its .claude-plugin/plugin.json version bumped (2.0.8 → 2.1.0) and the root CLAUDE.md version table was updated to match (2.1.0). No skills/agents/commands were added, removed, or renamed, so plugin CLAUDE.md/README.md and marketplace.json inventories remain accurate without changes. SummaryPlugin version bump (blocking check): satisfied.
Scope of changes: all 8 remaining changed files are within Inventory/naming impact: none of the changes add, remove, or rename a skill, agent, or command — they rework existing agent instructions (dropping "MANDATORY/CRITICAL" boilerplate, adding a Minor semver judgment call (non-blocking): the Verdict: PASS — required version bump is present and consistent with the root table; no missing CLAUDE.md/README/plugin.json updates identified. ✨ No Documentation Updates NeededAll documentation appears to be up to date with the code changes. 🤖 Generated by Claude Documentation Validator | Mode: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4c719be985
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **If a GitHub MCP server is configured**, use its create-pull-request and update-pull-request tools | ||
| with the title, body, base and head branches. Take the exact tool names from your available-tools | ||
| list. Otherwise use the CLI path below. |
There was a problem hiding this comment.
When the user selects --use-graphite and a GitHub MCP server is also available, these added lines direct the agent to create/update through GitHub MCP before it reaches the Graphite path. Graphite's command reference documents gt submit as the operation that creates or updates PRs for stack branches, so bypassing it can submit an ordinary GitHub PR while leaving the Graphite stack/update flow stale; prefer Graphite MCP/gt submit whenever Graphite mode is selected. Graphite command reference.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 0e86d2a. The --use-graphite branch now comes first in step 6, ahead of the GitHub MCP instruction, so it routes to gt submit whether or not a GitHub MCP server is configured. It also mirrors the Stack Management section: if a Graphite MCP server is present, pass the gt submit command to its command-runner tool, otherwise run it via bash. The GitHub MCP path is now the Otherwise case, with the plain CLI path last.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| | Complex (architecture, major features) | 8-10 | 2-3 | ~400-600 lines | | ||
| Agent and round counts are **ceilings, not quotas**. Staff only the dimensions the task actually raises, and do not spawn an agent for analysis that would finish in a handful of direct tool calls - plan the simple case yourself. | ||
|
|
||
| | Task Type | Agents (max) | Rounds (max) | Plan Length | |
There was a problem hiding this comment.
3. **Collaborative Discussion**: 2-3 rounds of multi-agent refinement, while this table caps Simple at 1 round and Medium at 2. A numbered process step reads as an instruction, so the floor this PR removes survives in the section the model reads first. Reword line 25 to defer to the table — e.g. refinement rounds, up to the ceiling below.
There was a problem hiding this comment.
Fixed in f1721cf. Quick Process step 3 now reads "Multi-agent refinement, up to the round ceiling in the table below" — it no longer states its own count, so the table is the single source for round limits.
| match an agent's frontmatter `name:` fails at dispatch: | ||
|
|
||
| ```bash | ||
| grep -rhE '^name: ' packages/plugins/*/agents/ | sort -u |
There was a problem hiding this comment.
packages/plugins/*/agents/ only resolves inside this repo; the guide runs with the user's project as CWD. In a consumer repo the glob matches nothing, grep exits with empty output, and line 23 has just said an unmatched name "fails at dispatch" — so empty output reads as "this agent doesn't exist, don't dispatch." ${CLAUDE_PLUGIN_ROOT} doesn't fix it either, since context-loader-agent lives in development-codebase-tools. Point the check at the session's own agent inventory instead of the filesystem.
There was a problem hiding this comment.
Fixed in f1721cf. The grep block is gone. The guide now tells the model to confirm the name against the agent inventory available in its own session, and explicitly says not to verify by searching the filesystem (these agents ship from installed plugins, not from the user's project, so a repo-relative search returns nothing even when the agent is available). The naming rule is stated as fact rather than as a command to run: dispatch names come from an agent's frontmatter name:, marketplace agents carry an -agent suffix, and cross-plugin dispatch is plugin-name:agent-name (e.g. development-codebase-tools:security-analyzer-agent). Also confirmed grep -rn 'packages/plugins' packages/plugins/development-planning/ now only hits project.json/package.json, which are repo build config rather than shipped prompt text.
There was a problem hiding this comment.
Caution
4c719be to
f1721cf
Compare
| repo-relative search returns nothing even when the agent is available. | ||
|
|
||
| Dispatch names come from an agent's frontmatter `name:` field; marketplace agents carry an `-agent` | ||
| suffix. Agents from a different plugin are addressed as `plugin-name:agent-name`, for example |
There was a problem hiding this comment.
Task(subagent_type:context-loader-agent) appears 7 times, and this plugin's own CLAUDE.md documents that exact dispatch); the plugin-name:agent-name form exists nowhere else. A model following it rewrites a valid name into one that isn't in the session inventory — which line 25 says fails at dispatch.
| suffix. Agents from a different plugin are addressed as `plugin-name:agent-name`, for example | |
| suffix. Dispatch by the bare `name:` value even when the agent ships from a different plugin. |
There was a problem hiding this comment.
Fixed in 0e86d2a. Resolved in favor of the qualified form, since two plugins can ship an agent with the same name and the prefix is what disambiguates. All 14 table entries are now plugin-name:agent-name, verified against each agent's frontmatter name: on disk rather than guessed: development-codebase-tools owns context-loader, code-explainer, pattern-learner, style-enforcer, security-analyzer, performance-analyzer, refactorer, debug-assistant; development-productivity owns test-writer, documentation, researcher; uniswap-integrations owns migration-assistant, cicd, infrastructure. The three Example Combinations below the table were qualified too, since they had the same problem. The prose now states that every agent listed is cross-plugin and that repo-local agents (.claude/agents/) are the ones addressed bare. The session-inventory check and the do-not-search-the-filesystem instruction are both retained; the inventory check is now called out as what catches an entry whose owning plugin is not installed.
|
@request-claude-review |
|
↻ Reviewing now · view run ↗ This comment will update when the review completes. Findings will appear in the sticky summary above. |
Opus 5 self-verifies, over-delegates, and follows literal instructions more strictly than 4.x, so several patterns in this plugin now cost tokens or suppress real findings. - Remove the mandated pre-think phases from planner and plan-reviewer, plus planner's trailing self-review checklist. - Convert agent-count floors in plan-swarm, plan-implementation, and planning-guide into ceilings, and state when not to delegate at all. - Stop plan-reviewer filtering risks at discovery time; report every finding with a severity and let the reader filter. - Drop the fabricated timeline-estimate field, which had no measured inputs. - Replace ~13 agent names in planning-guide that never existed with the real dispatch names, and fix the /explore reference to explore-codebase. - Replace fabricated mcp__<server>_<tool> names in pr-creator with the real prefix convention and an instruction to read the actual tool list. - Add a length bound to plan-reviewer's review output. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two residues in plan-implementation that undercut the Opus 5 migration: - Quick Process step 3 mandated "2-3 rounds" while the ceiling table below caps Simple at 1 and Medium at 2. The numbered step reads as an instruction, so the floor survived the removal. It now defers to the table. - The agent-existence check grepped `packages/plugins/*/agents/`, a path that exists only in this repo. In a consumer repo it matches nothing, and the adjacent "fails at dispatch" warning then reads as "do not dispatch" - a self-disabling guard. Replaced with the session's own agent inventory, plus the naming rule stated as fact (frontmatter `name:`, `-agent` suffix, cross-plugin `plugin-name:agent-name`). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
f1721cf to
ed83d19
Compare
…re graphite branch planning-guide.md listed 14 agents in bare form while the prose below the table required the plugin-qualified form. All 14 live in other plugins, so the table now uses `plugin-name:agent-name` throughout, matching the prose and disambiguating names that collide across plugins. pr-creator.md routed to a GitHub MCP server before checking --use-graphite, so `gt submit` was unreachable whenever a GitHub MCP server was configured and the Graphite stack went unregistered. The Graphite carve-out now comes first. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
@request-claude-review |
| - Plans being "too concise" if they cover all critical information | ||
|
|
||
| **What SHOULD be Flagged:** | ||
| **What SHOULD be Flagged** (examples, not a closed list - report anything in scope that you find): |
There was a problem hiding this comment.
Missing comprehensive risk matrices (only critical risks should be documented). Unlike the rest of the What-NOT-to-Flag list (which is format scope), this entry is the same discovery-time filter — it contradicts line 36's "report every implementation challenge" instruction and makes the low/medium severity levels at line 80 unreachable. Rewording it to risks belong in the risks field with a severity, not a separate matrix keeps the scope policy without the filter.
There was a problem hiding this comment.
Note
✅ Approved — see full review in the sticky comment ↑
|
↻ Reviewing now · view run ↗ This comment will update when the review completes. Findings will appear in the sticky summary above. |
1 participant
Part of the Opus 5 marketplace migration (one PR per plugin). Opus 5 self-verifies, over-delegates where 4.x under-delegated, and follows literal instructions more strictly — so several patterns in this plugin now cost tokens or actively suppress real findings.
Delta 1 — verification ceremony removed
agents/planner.mdandagents/plan-reviewer.md: dropped the mandated pre-think phases ("MANDATORY DEEP THINKING PHASE: before providing any review you MUST…"). Opus 5 does this without being told.agents/planner.md: dropped the trailing self-review checklist over its own just-written output.Grounding instructions were kept — those constrain claims against reality, which is a different thing from re-reading your own work.
Delta 2 — delegation floors became ceilings
plan-swarm,plan-implementation, andplanning-guide.mdeach carried a "3-10 agents" range with "Simple: 3-4" — a floor of three agents on the simplest plan. All three are now ceilings, stated as ceilings rather than quotas, with an explicit when-not-to-delegate rule.Delta 3 — recall filter removed
plan-reviewer.md's Risk Assessment step said "identify potential implementation challenges (critical ones only)" — a filter applied at discovery time, which makes Opus 5 silently drop real findings. Now it reports every finding with a severity and lets the reader filter.Its "What NOT to Flag" list was deliberately kept: that excludes categories the plan format intentionally omits (test plans, success criteria, risk matrices), which is scope policy, not a recall filter.
Broken references
planning-guide.mdnamed ~13 agents that have never existed (backend-architect,database-optimizer,frontend-developer,cloud-architect, …). Replaced with real dispatch names.pr-creator.mdcarried fabricatedmcp__<server>_<tool>names. Replaced with the real prefix convention plus an instruction to read the actual tool list rather than guess./explorereference toexplore-codebase.Dispatch names come from each agent file's
name:frontmatter, never the filename — every marketplace agent carries an-agentsuffix.Invented numbers
Dropped
plan-reviewer'stimeline-estimatefield. The model has no measured input for it, fills it because the schema requires it, and the fabricated number then reads as an estimate.Delta 4 — output length
Added a length bound to
plan-reviewer's review output.Note: pre-existing version drift
plugin.jsonwas at 2.0.8 while the rootCLAUDE.mdtable said 2.0.7. Both now read 2.1.0 (minor — behavior changes), which incidentally resolves the drift.Test plan
bunx markdownlint-cli2 "packages/plugins/development-planning/**/*.md"—Summary: 0 error(s)across 200 files.nx format:write --uncommittedclean.find packages/plugins -path '*/agents/*.md'+ each file'sname:frontmatter.🤖 Generated with Claude Code
AI-Generated Description
Summary
Part of the Opus 5 marketplace migration (one PR per plugin). Opus 5 self-verifies, over-delegates where 4.x under-delegated, and follows literal instructions more strictly — so several patterns in this plugin now cost tokens or actively suppress real findings.
10 files, +103 / −257. Prompt content only; no code, hooks, or CI.
Delta 1 — verification ceremony removed
agents/planner.mdandagents/plan-reviewer.md: dropped the mandated pre-think phases ("MANDATORY DEEP THINKING PHASE: before providing any review you MUST…"). Opus 5 does this without being told.agents/planner.md: dropped the trailing self-review checklist over its own just-written output.skills/execute-plan/execution-guide.md: dropped "Manual review of changes" from the post-change verification list. The compile/test/lint steps around it are real commands; that line asked the model to re-read its own diff.Grounding instructions were kept — those constrain claims against reality, which is a different thing from re-reading your own work.
Delta 2 — delegation floors became ceilings
plan-swarm,plan-implementation, andplanning-guide.mdeach carried a "3-10 agents" range with "Simple: 3-4" — a floor of three agents on the simplest plan. All three are now ceilings (simple: up to 2, medium: up to 5, complex: up to 10), stated as ceilings rather than quotas, with an explicit rule not to spawn an agent for analysis that would finish in a handful of direct tool calls.Delta 3 — recall filter removed
plan-reviewer.md's Risk Assessment step said "identify potential implementation challenges (critical ones only)" — a filter applied at discovery time, which makes Opus 5 silently drop real findings. It now reports every finding with a severity and lets the reader filter. Therisksoutput field changed shape accordingly (risk+severityper entry), andreview-plan/SKILL.mdwas updated to match.Its "What NOT to Flag" list was deliberately kept: that excludes categories the plan format intentionally omits (test plans, success criteria, risk matrices), which is scope policy, not a recall filter. The "What SHOULD be Flagged" list is now labelled as examples rather than a closed set.
Broken references
planning-guide.mdnamed ~13 agents that have never existed (backend-architect,database-optimizer,frontend-developer,cloud-architect, …). Replaced with a table of real dispatch names, plus thegrepthat regenerates it.pr-creator.mdcarried fabricatedmcp__<server>_<tool>names across ~180 lines of examples, including a pseudo-Python tool-detection block. Replaced with the realmcp__<server>__<tool>prefix convention plus an instruction to read the actual tool list rather than guess./explorereference inreview-plan/SKILL.mdtoexplore-codebase.Dispatch names come from each agent file's
name:frontmatter, never the filename — every marketplace agent carries an-agentsuffix.Two
git add ./git add -Ainstructions inpr-creator.mdbecamegit add <files>, matching the repo rule against blanket staging.Invented numbers
Dropped
plan-reviewer'stimeline-estimatefield. The model has no measured input for it, fills it because the schema requires it, and the fabricated number then reads as an estimate.Delta 4 — output length
Added a ~250-line bound to
plan-reviewer's review output.Note: pre-existing version drift
plugin.jsonwas at 2.0.8 while the rootCLAUDE.mdtable said 2.0.7. Both now read 2.1.0 (minor — behavior changes), which incidentally resolves the drift.Test plan
bunx markdownlint-cli2 "packages/plugins/development-planning/**/*.md"—Summary: 0 error(s)across 200 filesnx format:write --uncommittedcleanplanning-guide.mdtable verified againstgrep -rhE '^name: ' packages/plugins/*/agents/— all 12 resolveCLAUDE.mdtable updated to match🤖 Generated with Claude Code