fix(development-productivity): Opus 5 migration -- resolve doc-agent verification contradiction, remove invented numbers

[wkoutre]

Headline: the documentation-agent verification contradiction

agents/documentation.md and agents/claude-docs-initializer.md gave opposite instructions about who verifies generated documentation:

• documentation.md stated verification is an internal phase, never a separate agent call.
• claude-docs-initializer.md mandated invoking documentation-agent as a second-pass verifier per 1-2 file batch, and set requires_verification: true so callers kept invoking the fact-checker regardless of what the other file's prose said.

Resolution: keep documentation.md's inline posture, fix the initializer.

• Removed the mandated documentation-agent second pass (Mission, Steps 2-3 of batch execution, and the MANDATORY VERIFICATION constraint).
• Removed the requires_verification: true flag from the batch-execution output schema.
• Replaced both with per-file unverified_claims: the agent flags each claim it could not confirm, inline, with the check it attempted.

The related incomplete fix in documentation.md

An earlier pass rewrote that file's prose to say verification is inline but left the machinery implementing the old behavior. A prompt's behavior lives in its output schema as much as in its instructions, so all of it is now gone:

Was	Now
quality_score: number # 0-100	removed
quality_analysis: {completeness, accuracy, consistency}, each # 0-100	unverified_claims + known_gaps
accuracy_score in the CLAUDE.md output block	critical_claims_confirmed: boolean + unverified list
(verified_claims / total_claims) * 100 plus severity-point deductions	flag each unconfirmed claim; no score
the accuracy < 70% gate (both occurrences)	gate on any CRITICAL claim being wrong or unconfirmed
Quality Scoring (0-100) with 25%/25%/25%/25% weights	qualitative Reporting Quality

Every one of those demanded a number the model has no measured input for. It fills the required field, fabricates a score, and the score then reads as evidence while being none.

Changes by delta

Delta 1 — Opus 5 self-verifies

• claude-docs-initializer.md: second-agent verification pass removed (above).
• documentation.md: dropped the Completeness Assessment and Consistency Checks subsections (8 bullets re-reading just-written prose). Kept Accuracy Verification — link validation and code-sync checks ground claims against the codebase, which is not the same as re-reading your own work. Retitled to say so.
• commands/claude-init-plus.md: replaced the trailing 4-item verify checklist, plus the block restating the same four items as failure conditions, with the two conditions actually checkable after the fact.
• commands/update-claude-md.md: dropped the Step 10 post-write re-read. Deduplication (Step 6) and the no-[TODO] rule are constraints on the write; the 200-line overflow case was already covered under Error Handling.

Delta 2 — delegation

• commands/claude-init-plus.md: added an explicit instruction against one-subagent-per-package fan-out, naming the reason. The command's Hierarchy Deduplication rule requires knowing what was written at every other level; a subagent cannot see what a sibling wrote, so each one independently decides a repo-wide convention is worth stating and writes it. Nothing reports a failure, because every individual file still looks correct. Discovery is read-only and explicitly still parallelizable; generation is not.
• skills/generate-tests/*: added when-NOT-to-delegate guidance. The agent list is a menu of what is available, not a sequence to work through.

Delta 3 — recall filters

• documentation.md: HIGH (verify when time permits) reads to Opus 5 as license to skip. Now HIGH (verify; if you cannot, flag the claim inline), same for the LOW tier, and the matrix header says it sets work order rather than granting permission to skip a tier.
• agents/agent-tester.md, agents/prompt-engineer.md: neither had any coverage instruction in its findings section. Both now say to report every genuine finding, mark severity and confidence, and not drop the uncertain or low-severity ones. Added the same to agents/researcher.md and agents/test-writer.md.
• Stripped decorative CRITICAL:/MANDATORY emphasis where it was not load-bearing.

Delta 4 — unbounded deliverables

• claude-docs-initializer.md: coordinationContext capped at 200 words — the highest-cost one here, since it feeds another agent's context.
• agents/researcher.md (800 words), agents/agent-tester.md (600 words, narrative sections only), agents/test-writer.md (400 words). Each bound explicitly excludes data (test bodies, logs, enumerated lists) so it does not cause dropped findings.
• Kept the "under 200 lines per CLAUDE.md" convention everywhere it appears — that IS the fix, not an instance of the problem.

Invented numbers

File	Was	Now
skills/generate-tests/gen-tests-guide.md	required coverage: number in a skill whose allowed-tools has no Bash	coverage | 'not_measured' plus coverageSource; reported only when a coverage tool actually ran
skills/generate-tests/SKILL.md	"Write test files with full coverage" — no Write tool, no Bash	returns artifacts; names untested behaviors
agents/prompt-engineer.md	expected_impact: <percentage_improvement>, clarity_score, effectiveness_prediction	prose unless derived from supplied performance_data or an executed run; the whole Effectiveness Measurement section is gated on measured input
agents/researcher.md	total_cost_ownership, migration_complexity, scored comparison_matrix	cited sources or an explicit "unestimated"; weighted totals only over cited measurements
agents/agent-tester.md	coverage percentages of an unenumerable whole; overall_score: 0-100; dimension_scores	counts against an enumerated list plus named gaps; per-dimension findings with a not_tested state

Stale facts

• prompt-engineer.md:18: target_model examples were "gpt-4", "claude-3", "llama-2". claude-3 was never a valid API model id. Replaced, with a note preferring the bare opus/sonnet/haiku aliases since they self-update.
• prompt-engineer.md: frequency_penalty and presence_penalty are OpenAI-only and 400 against the Anthropic Messages API. The parameter table is now split by provider. Also flagged that temperature is rejected alongside thinking on Claude 5 — precisely the analytical/reasoning case where the old table recommended a low temperature — pointing at thinking: {type: "adaptive"}, and noted budget_tokens is not accepted on Claude 5.
• skills/optimize-prompt/SKILL.md:47: "GPT-4 best practices" replaced with provider-neutral guidance plus those concrete constraints.

Broken references

context-loader-agent, security-analyzer-agent, performance-analyzer-agent, and agent-orchestrator-agent all live in development-codebase-tools, but generate-tests referenced them bare — including inside allowed-tools, where a bare name does not resolve cross-plugin. All now use development-codebase-tools:<agent-name>. Verified every agent name in this plugin against frontmatter name: on disk; the rest resolve correctly.

Out-of-scope defect fixed in passing

• commands/update-claude-md.md:16 — a dangling sentence fragment (constraint, or workflow decision. duplicated from the line above) left by a bad edit.

Findings in the brief that did not exist

Reported rather than worked around:

• skills/mermaid-diagram, skills/diagram-excalidraw, skills/daily-standup — none exist in this plugin. Its six skills are audit-dependencies, generate-document, generate-tests, optimize-prompt, research-topic, update-claude-docs. The verification-ceremony findings for those three could not be acted on here.
• skills/claude-init-plus, skills/update-claude-md — these are commands (commands/*.md), not skills. Fixed at their real paths.
• skills/update-claude-md/SKILL.md:16 dangling fragment — no such file. The fragment is real but lives at commands/update-claude-md.md:16; fixed there.
• agents/documentation.md "12 items" — there was no 12-item trailing checklist. The closest match was three 4-bullet Quality Analysis subsections; two were self-review and were removed, one was grounding and was kept.
• researcher.md "TCO in dollars and migration effort in person-weeks" — the file never names those units; the fields are total_cost_ownership: TCO analysis including hidden costs and migration_complexity: Effort required to switch technologies. The defect is real (both invite unmeasured figures) but the brief's wording overstated what the file says.

Version bump

packages/plugins/development-productivity/.claude-plugin/plugin.json 2.4.1 -> 2.5.0 (MINOR), and the matching row in the root CLAUDE.md. The two agreed at 2.4.1 before this change — no drift here, unlike the sibling plugin.

Test plan

$ node scripts/validate-plugin.cjs packages/plugins/development-productivity
  ✓ plugin.json: development-productivity v2.5.0
  ✓ package.json: @uniswap/development-productivity
  ✓ project.json: development-productivity
  ✓ skills/: 6 item(s)
  ✓ agents/: 6 item(s)
  ✓ commands/: 2 item(s)
  ✓ hooks/: 2 item(s)
Validation PASSED

$ bunx markdownlint-cli2 --fix "packages/plugins/development-productivity/**/*.md"
markdownlint-cli2 v0.20.0 (markdownlint v0.40.0)
Linting: 200 file(s)
Summary: 0 error(s)

$ bunx nx format:write --uncommitted
(no output — nothing left to reformat)

The lefthook pre-commit gate ran on all three commits:

✔️ format  ✔️ lint  ✔️ lint-markdown  ✔️ test  ✔️ typecheck  ✔️ update-lockfile

Every agent name referenced in this plugin was checked against frontmatter name: on disk:

$ find packages/plugins -path '*/agents/*.md' -exec sh -c 'grep -m1 "^name:" "$1"' _ {} \;

The diff is entirely prompt text plus one version field — no executable behavior in this repo changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ai-toolkit-slack-oauth-backend	Ready	Preview	Aug 5, 2026 11:47pm

[github-actions]

_{● Reviewed · 2026-08-05 23:47 UTC · 2 reviews · view run ↗}

Approved — one wrong model-id fact remains in prompt-engineer.md.

Rewrites the development-productivity prompts for Opus 5: removes the documentation second-pass verification, replaces invented numeric scores with qualitative reporting, splits the parameter guidance by provider, and prefixes cross-plugin agent references; bumps the plugin 2.4.1 → 2.5.0.

Assessment

The sampling-parameter rule is now stated unconditionally at both sites, and the creative_tasks recommendation no longer produces a request that 400s. All cross-plugin agent references in gen-tests-guide.md are prefixed, and both generate-tests frontmatters grant the same full agent set, so the documented orchestration path is dispatchable. Version bump and root table agree at 2.5.0.

Suggestions

• prompt-engineer.md:18 — bare opus/sonnet/haiku are Claude Code shorthands that 404 as API model ids, and claude-opus-5 is the undated alias, not a pinned id; the note inverts the preference. view inline thread →

[github-actions]

📚 Documentation Check ✅

Verdict: Passed

Version bump satisfied.

---

Documentation Review for PR #573.

Version bump (blocking check): PASS. plugin.json for development-productivity went 2.4.1 to 2.5.0, and the root CLAUDE.md version table was updated to match. No new skills, agents, or commands were added (only content and behavior fixes to existing ones), so a minor bump is defensible even though patch would also be reasonable; either way the bump requirement is satisfied.

Plugin CLAUDE.md is up to date: new bullet points reflect the PR's substance (inline verification replacing the requires_verification/fact-checker handoff, the numbers-require-measured-input rule, sequential claude-init-plus generation). File stays under the plugin's 200-line budget (108 lines). plugin.json skills/agents/commands arrays still match directories/files on disk.

README.md needs no update: none of the changed concepts (requires_verification, quality_score, coverage percentages, renamed agent references, sampling-parameter guidance) appear in it.

Non-blocking observation: agents/prompt-engineer.md still has pre-existing sections (clarity_metrics 0-10 scale, Background Information 0-100 percent completeness, Accuracy/Relevance/Completeness/Coherence Score 0-100 percent) that were not touched by this diff but now sit near the newly added measured-input language in the same file, creating an internal inconsistency worth a follow-up pass. No changelog entry, but that is informational only per review config.

✨ No Documentation Updates Needed

All documentation appears to be up to date with the code changes.

---

_{🤖 Generated by Claude Documentation Validator | Mode: suggest}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7845227f07

ℹ️ 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".

[chatgpt-codex-connector]

Allow the orchestration agent before invoking it

For complex /generate-tests runs such as multiple-file, integration/e2e, or --type all, this newly documented path tells the skill to invoke development-codebase-tools:agent-orchestrator-agent, but the allowed tool lists only permit test-writer-agent and development-codebase-tools:context-loader-agent here, and the parent SKILL.md also omits the orchestrator and performance-analyzer-agent used just below. With restricted tools, the model cannot follow the advertised orchestration path for those complex cases; either add the referenced agents to allowed-tools or remove these instructions.

Useful? React with 👍 / 👎.

[github-actions]

⚠️ warning · correctness — The condition is wrong: on the Claude 5 family (and Opus 4.8/4.7), temperature, top_p, and top_k are rejected with a 400 on any request — not only when thinking is enabled. Line 344 then recommends temperature: 0.7-0.9 # valid only when thinking is disabled for creative tasks, so an agent following this table emits a request that fails outright. Drop the creative_tasks temperature row and state the rule unconditionally.

[github-actions]

⚠️ warning · correctness — Same incorrect condition as agents/prompt-engineer.md:315: sampling parameters (temperature/top_p/top_k) are rejected unconditionally on the Claude 5 family, not just when extended thinking is enabled.

Suggested change

	Claude 5 family, `temperature` is rejected when extended thinking is enabled, and
	Claude 5 family, `temperature`/`top_p`/`top_k` are rejected on any request regardless of
	thinking configuration, and `budget_tokens` is not accepted (use `thinking: {type: "adaptive"}`).

[github-actions]

🔵 info · consistency — allowed-tools grants test-writer-agent, development-codebase-tools:context-loader-agent, and :security-analyzer-agent, but gen-tests-guide.md (lines 83, 88) instructs invoking development-codebase-tools:agent-orchestrator-agent and :performance-analyzer-agent, which aren't in the allowlist. The guide's own frontmatter (line 4) disagrees further, omitting the security analyzer too — the two files should agree on what this skill may dispatch.

[github-actions]

Caution

⚠️ Changes requested — see full review in the sticky comment ↑

[wkoutre]

Addressed the review feedback. All four items were real; rebased onto next first (clean, no conflict -- the CLAUDE.md version table kept both the merged uniswap-integrations 2.6.1 row from next and this branch's development-productivity 2.5.0).

Findings 1 & 2 -- the temperature rule had a wrong condition. Both sites said temperature is rejected on Claude 5 when extended thinking is enabled. The actual constraint is stronger and unconditional: temperature, top_p, and top_k are removed on Claude 5 and return a 400 on any request, thinking or not. The conditional phrasing told a caller who leaves thinking off that setting temperature was safe, which is exactly the 400 they were told would not happen.

• agents/prompt-engineer.md -- corrected the rule to unconditional, and rewrote the claude_parameter_recommendations block. The creative_tasks row previously recommended temperature: 0.7-0.9 # valid only when thinking is disabled, a request that would 400; creativity is now steered through the prompt instead.
• skills/optimize-prompt/SKILL.md -- same correction.

Swept both files for any other place presenting sampling params as conditionally allowed; the OpenAI-target block is the only remaining one, which is correct. Kept the existing accurate facts: frequency_penalty/presence_penalty are OpenAI-only and 400 against the Anthropic Messages API, and budget_tokens is rejected on Claude 5 (use thinking: {type: "adaptive"}, with output_config.effort for depth).

Finding 3 -- bare agent names contradicted the same file. skills/generate-tests/gen-tests-guide.md lines 42/51/52 used unprefixed context-loader-agent and security-analyzer-agent in the Orchestration Strategy, while lines 78-81 of that same file state the unprefixed form will not resolve cross-plugin. Both are now development-codebase-tools:<name>. test-writer-agent on lines 48/50 is in this plugin and correctly stays unprefixed. Verified against the frontmatter name: of all 27 marketplace agents rather than guessing.

Suggestion -- allowed-tools was narrower than the instructions. skills/generate-tests/SKILL.md:3 omitted agent-orchestrator-agent and performance-analyzer-agent, which gen-tests-guide.md instructs invoking, and the guide's own frontmatter disagreed with SKILL.md on top of that (it also lacked security-analyzer-agent and Glob). Both frontmatters now grant the same full set, so the skill can actually dispatch what it tells the model to dispatch.

No version bump -- still 2.5.0, since these are fixes to that same unreleased change. bunx nx format:write --uncommitted and bunx markdownlint-cli2 both clean (200 files, 0 errors); pre-commit format/lint/test/typecheck all passed.

One thing left alone deliberately: prompt-engineer.md:575 (If confidence < 80%, provide an alternative approach) is inside an example prompt template and adds an alternative on low confidence rather than filtering findings out at discovery, so it is not the anti-pattern the confidence guidance prohibits.

Superseded by new review

[github-actions]

⚠️ warning · correctness — Bare opus/sonnet/haiku are Claude Code /model shorthands, not Anthropic API model ids — sent as model they return 404. And claude-opus-5 isn't a pinned id; it's the undated alias that already tracks the current release. This line steers the agent toward the invalid form in the file this PR exists to correct.

Suggested change

	- **target_model**: The LLM or agent that will receive the prompt (e.g., "opus", "sonnet", "haiku", "gpt-5.2", "gemini-3-pro"). For Anthropic models prefer the bare aliases (`opus`, `sonnet`, `haiku`), which track the current release, over pinned ids like `claude-opus-5`.
	- **target_model**: The LLM or agent that will receive the prompt (e.g., "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5", "gpt-5.2", "gemini-3-pro"). For Anthropic models use the exact alias from the models table — never append a date suffix, and never send a bare `opus`/`sonnet`/`haiku`, which is a Claude Code shorthand rather than an API model id.

[github-actions]

Note

✅ Approved — see full review in the sticky comment ↑