fix(claude-setup): migrate docs for Opus 5, stop blind staging

[wkoutre]

Applies the Opus 5 migration audit to packages/plugins/claude-setup/. Every .md under that directory was read in full; only defects were touched.

Deltas addressed

Stale facts (model version)

The plugin recommended Opus 4.8 in three places. All three now say Opus 5:

• README.md — "Boris' Best Practices" bullet.
• references/boris-best-practices.md — the pillar-5 heading (### 5. Opus 4.8 (Most Capable) → ### 5. Opus (Most Capable)).
• references/boris-best-practices.md — the anti-patterns table row (Use Opus 4.8 → Use Opus 5).

Carve-out honored: the Boris quotation on the next line ("The model choice is unambiguous: Opus 4.8 for everything.") is left verbatim. Rewriting the inside of a quotation would falsify the source. An italic editorial note below it records that the current flagship is Opus 5.

Correction to the audit brief: it stated that the anti-patterns table "already says Opus 5." It did not — it said Opus 4.8, same as the other two sites. There was no self-contradiction in the file; all three were uniformly stale.

Delta 4 — output length

Reasoning-effort settings do not shorten authored deliverables; only explicit length instructions do. Report sections that lacked one now have one. Highest priority first (agent reports feed another agent's context):

• references/agent-templates.md — length bounds added to the ## Output Format section of verify-app (40 lines), code-simplifier (40), build-validator (30), code-architect (60), and oncall-guide (40).
• SKILL.md — the inline verify-app and code-simplifier templates now bound their ## Output at 20 lines.
• SKILL.md — the generated CLAUDE.md is bounded at under 200 lines, with the reason stated (it loads into every session in the target repo). This is the plugin's primary deliverable and had no length guidance at all.

Invented numbers

build-validator's report template demanded three numeric fields its own validation steps never produce, so a model filling the required fields would fabricate them and they would read as measured:

• Build time: [X seconds] — the steps never time the build.
• Bundle size: [X KB] ([+/- Y KB] from main) — the delta requires a base-branch build the template never instructs.
• Vulnerabilities: [npm audit results] — npm audit is never run; only npm ls.

Each is now explicitly conditional on the measurement having actually happened, and the report section instructs omitting a line rather than guessing a value. Total dependencies: X was dropped (unmeasured and not actionable). Counts that are derived from real tool output (X passed, Y failed, Files modified, Lines removed) were left alone — arithmetic over measured inputs is fine.

Deltas audited and found absent

Reported rather than invented:

• Delta 1 (verification ceremony) — no mandated pre-think phases, no trailing self-review over just-written output, no second-agent verification pass. The verify-app template's checks run real build/test/typecheck/lint commands and report their results, which is grounding, not ceremony. Kept as-is.
• Delta 2 (delegation) — no agent-count floors, quotas, or "spawn N agents" instructions anywhere in this plugin. Nothing to convert.
• Delta 3 (recall filters / emphasis) — no discovery-time filters. review-changes is already coverage-first (report every issue found, summarize downstream). The remaining Do NOT / Never emphasis marks real constraints (git add ., not marking ready while a check fails), not decoration.
• Broken references — every agent, skill, command, and tool name in this plugin refers to a template the wizard creates in the user's repo, not to a dispatch target in this marketplace. No fabricated dispatch names. allowed-tools in SKILL.md lists only real tools; no MultiEdit, no budget_tokens, no OpenAI-only sampling params.

Version bump

1.0.5 → 1.1.0 (minor). The length bounds and the omit-unmeasured-fields rule change what the generated agents and CLAUDE.md do, not just the wording of the docs. Root CLAUDE.md version table updated in the same commit.

CLAUDE.md and README.md component lists were checked and needed no update: no skill, agent, or command was added, removed, or renamed.

Test plan

• bunx nx format:write --uncommitted — clean; normalized agent-templates.md, that normalization is in the commit.
• bunx markdownlint-cli2 --fix "packages/plugins/claude-setup/**/*.md" — Linting: 200 file(s), Summary: 0 error(s), exit 0.
• Pre-commit (lefthook) — all six gates green: format, lint, lint-markdown, test, typecheck, update-lockfile.
• grep -rn "Opus 4" packages/plugins/claude-setup/ — one remaining hit, the Boris quotation, intentionally preserved.

🤖 Generated with Claude Code

AI-Generated Description

Summary

Applies the Opus 5 migration audit to packages/plugins/claude-setup/, plus one credential-adjacent
fix found in the same read: the quick-commit template told users to git add -A. Every .md under
the plugin was read in full; only defects were touched. 7 files, +31/-15.

Stale model version

The plugin recommended Opus 4.8 in three places. All three now say Opus 5:

• README.md — the "Boris' Best Practices" bullet.
• references/boris-best-practices.md — the pillar-5 heading (### 5. Opus 4.8 (Most Capable) → ### 5. Opus (Most Capable)).
• references/boris-best-practices.md — the anti-patterns table row (Use Opus 4.8 → Use Opus 5).
  Carve-out honored: the Boris quotation on the next line ("The model choice is unambiguous: Opus
  4.8 for everything.") is left verbatim — rewriting the inside of an attributed quotation would
  falsify the source. An italic editorial note below it records that the current flagship is Opus 5.
  This matches the exemption already taken in chore(workflows): update model references to claude-opus-5 #558.

Output length

Reasoning-effort settings do not shorten authored deliverables; only an explicit length instruction
does. Report sections that lacked one now have one, agent reports first since they feed another
agent's context:

• references/agent-templates.md — bounds added to the ## Output Format of verify-app (40 lines), code-simplifier (40), build-validator (30), code-architect (60), and oncall-guide (40).
• SKILL.md — the inline verify-app and code-simplifier templates now bound their ## Output at 20 lines.
• SKILL.md — the generated CLAUDE.md is bounded at under 200 lines, with the reason stated (it loads into every session in the target repo). This is the plugin's primary deliverable and had no length guidance at all.

Invented numbers

build-validator's report template required three numeric fields its own validation steps never
produce, so a model filling the required fields would fabricate them — and they would read as
measured:

Field	Why it could only be guessed
Build time: [X seconds]	the steps never time the build
Bundle size: [X KB] ([+/- Y KB] from main)	the delta needs a base-branch build the template never instructs
Vulnerabilities: [npm audit results]	npm audit is never run; only npm ls
Each is now explicitly conditional on the measurement having happened, and the section says to omit a
line rather than guess. Total dependencies: X was dropped (unmeasured and not actionable). Counts
that are derived from real tool output (X passed, Y failed, Files modified, Lines removed)
were left alone — arithmetic over measured inputs is fine.

Quick-commit staged blind

references/command-templates.md is the source for the slash commands the wizard writes into a
user's repo. Its /quick-commit template said:

git add -A

git add -A sweeps in untracked files the user never reviewed — build artifacts, local scratch
files, and .env files that a missing .gitignore entry left visible. The template's own mitigation
was a one-line "Note: This stages everything," which does not stop the command it just prescribed.
This contradicted the plugin in three other places, including line 50 of the same file (Never use git add .), SKILL.md:166, references/claude-md-examples.md:27, and the git add .
anti-patterns row in boris-best-practices.md. So this was an internal inconsistency, not a missing
convention — the correct form was already modeled 250 lines up.
The template now stages named files and states why, so the pattern does not get reintroduced as a
"simplification." /commit-push-pr remains the pointer for the fuller review flow.

Deltas audited and found absent

Reported rather than invented:

• Verification ceremony — no mandated pre-think phases, no trailing self-review over just-written output, no second-agent verification pass. verify-app's checks run real build/test/typecheck/lint commands and report their results, which is grounding, not ceremony.
• Delegation floors — no agent-count minimums, quotas, or "spawn N agents" instructions anywhere in this plugin.
• Recall filters / emphasis — no discovery-time filters. review-changes is already coverage-first. The remaining Do NOT / Never marks real constraints (git add ., not marking ready while a check fails), not decoration.
• Broken references — every agent, skill, command, and tool name here refers to a template the wizard creates in the user's repo, not to a dispatch target in this marketplace, so there are no fabricated dispatch names. allowed-tools in SKILL.md lists only real tools; no MultiEdit, no budget_tokens, no OpenAI-only sampling params.

Correction to the audit brief: it stated the anti-patterns table "already says Opus 5." It did not —
it said Opus 4.8, same as the other two sites. There was no self-contradiction; all three were
uniformly stale.

Version bump

1.0.5 → 1.1.0 (minor). The length bounds, the omit-unmeasured-fields rule, and the staging
change alter what the generated agents and commands do, not just the wording of the docs. Root
CLAUDE.md version table updated in the same commit.
Plugin CLAUDE.md and README.md component lists were checked and need no update: no skill, agent,
or command was added, removed, or renamed.

Test plan

• grep -rn "Opus 4" packages/plugins/claude-setup/ — exactly one hit, the Boris quotation, intentionally preserved
• grep -rn "git add -A" across the plugin — no hits remain
• bunx nx format:write --uncommitted — clean; normalized agent-templates.md, that normalization is in the commit
• bunx markdownlint-cli2 --fix "packages/plugins/claude-setup/**/*.md" — 200 files, 0 errors, exit 0
• Lefthook pre-commit — all six gates green: format, lint, lint-markdown, test, typecheck, update-lockfile

[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:27pm

[github-actions]

📚 Documentation Check ✅

Verdict: Passed

The critical requirement is met: packages/plugins/claude-setup/.claude-plugin/plugin.json was bumped from 1.0.5 to 1.1.0, and the version table in root CLAUDE.md was updated to match. No new skills/agents/commands were added, so no other structural docs (plugin.json arrays, marketplace.json, plugin-level CLAUDE.md) need changes.

---

This PR only touches packages/plugins/claude-setup/ and is documentation-only (skill guidance additions, Opus 4.8→5 wording fixes, git add -A → per-file staging guidance).

Version bump — satisfied: plugin.json version was bumped 1.0.5 → 1.1.0, and the root CLAUDE.md version table (line 99) was updated in the same commit to match. This is the blocking check per the review config (fail_on_missing_version: true) and it passes.

Consistency checks:

• No new skills, agents, or commands were added — packages/plugins/claude-setup/CLAUDE.md's structure/skills list remains accurate as-is, no update needed.
• marketplace.json entry for claude-setup is unaffected (name/source unchanged).
• The one remaining "Opus 4.8" string (references/boris-best-practices.md:67) is inside a direct quote from Boris Cherny, and the diff correctly appends a clarifying note below it rather than editing the quote itself — this is intentional, not a miss.
• The one remaining git add -A string (command-templates.md:308) is inside the new explanatory note about why not to use it — also intentional.

Minor (non-blocking) observation: Per this repo's own semver guidance ("Patch: bug fixes, doc updates, typo fixes" vs "Minor: new skills/agents/commands"), this change set (added guidance sentences, wording fixes) reads more like a patch-level change than a minor one. A 1.0.6 patch bump would have been equally defensible. This is not a correctness problem — a bump was made and the required-file check passes — just flagging the classification as debatable.

Suggestions (1)

💡 Inline suggestions have been posted as review comments. Click "Commit suggestion" to apply each fix directly.

• ℹ️ packages/plugins/claude-setup/.claude-plugin/plugin.json: The changes in this PR (added guidance sentences to SKILL.md/reference docs, wording fixes for Opus 4.8→5, git-add hygiene note) are documentation clarifications rather than new user-facing skills/agents/commands. Per this repo's own versioning rules in CLAUDE.md, that maps to a patch bump rather than minor. Not blocking — a version bump was made and is internally consistent — just a classification note.

---

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

[github-actions]

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

Approved — one warning on the /quick-commit template.

Migrates claude-setup docs from Opus 4.8 to Opus 5, adds output-length bounds to the generated agent templates and CLAUDE.md, makes build-validator's report fields conditional on measurements that actually run, and switches the /quick-commit template from git add -A to per-file staging — with a 1.0.5 → 1.1.0 bump mirrored in the root version table.

Assessment

Each inserted instruction lands where it takes effect: the 200-line CLAUDE.md bound sits outside the template fence (so it instructs the wizard, not the generated file), the inline template bounds sit inside theirs, and the conditionalized build-validator fields match what its validation steps actually produce. The per-file staging change matches the convention /commit-push-pr already uses. The staging behavior changed but its two descriptions didn't — that's the one open item.

Suggestions

• Stale "stage all" description on /quick-commit. The template's frontmatter (line 286) and the wizard's command menu (SKILL.md:140) both still say "stage all"; the frontmatter ships into the generated command file, so it contradicts its own body. view inline thread →
• Pre-existing, not introduced here: early-closing fences in command-templates.md and agent-templates.md put the back half of each template — including text this PR adds — outside the copyable ```markdown block. Worth a follow-up while you're in these files.

[github-actions]

Tip

💬 Commented — see full review in the sticky comment ↑

[github-actions]

⚠️ warning · correctness — Step 2 now stages files individually, but the template's own frontmatter at line 286 still reads description: Stage all changes and commit with a descriptive message. That description ships verbatim into the generated .claude/commands/quick-commit.md, so the command a user ends up with says "stage all" while its body says the opposite.

Note

SKILL.md:140 has the same stale text in the wizard's command menu (Stage all and commit with generated message) — outside this diff's hunks, but it needs the same edit.

[github-actions]

Note

✅ Approved — see full review in the sticky comment ↑