Reduce the repeated ExitPlanMode preamble across 52 plugin files to a single canonical line in the skills that actually mutate the filesystem, preserving the guard while removing roughly 2,750 words of duplicated explanation.
Forty-three plugin files each re-teach Claude the same four-line dance about exiting plan mode before writing files, spread across eight plugins. The guard itself matters and stays; only the explanation goes. We will know it worked when the long form appears nowhere and every write-heavy skill still carries a one-line guard.
Read and implement all steps in the plan at docs/plans/remove-exitplanmode-boilerplate.md — Teach the plan-mode guard once, keep it everywhere. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/remove-exitplanmode-boilerplate.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
Achieve this goal: Teach the plan-mode guard once, keep it everywhere. The plan at docs/plans/remove-exitplanmode-boilerplate.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/remove-exitplanmode-boilerplate.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 a workflow to implement the plan at docs/plans/remove-exitplanmode-boilerplate.md — Teach the plan-mode guard once, keep it everywhere. Brief subagents with the plan file at docs/plans/remove-exitplanmode-boilerplate.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/remove-exitplanmode-boilerplate.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.
remove-exitplanmode-boilerplate.html
docs/plans/remove-exitplanmode-boilerplate.html
docs/plans/remove-exitplanmode-boilerplate.md
Context
The story behind this plan — what prompted the work and why it matters now.
Measured across kit/plugins/: 52 files mention ExitPlanMode, and the lines
containing it total about 2,750 words. The same four-line block — exit plan
mode, here is why mutations cannot proceed inside it, ExitPlanMode is
deferred, call ToolSearch with select:ExitPlanMode first — is repeated
verbatim 19 times in one phrasing and 7 more in a near-identical variant.
Distribution: social-media-tools 16 files, plan-agent 12, git-agent 11,artifact-tools 4, product-plans 3, skill-reviewer 2, and one each inteam-defaults, content-tools, code-testing-agent, and code-review.
Two of the Claude 5 context-engineering rules apply at once. Rule 4 says state
a thing once rather than repeating it across layers. Rule 1 says prefer
judgment over rules — a current model asked to commit while in plan mode does
not need forty words explaining that writes are mutations.
This plan reduces the guard, it does not remove it. A skill that starts
writing files inside plan mode violates a standing user preference, and that
failure is silent — the write either fails confusingly or escapes a mode the
user deliberately entered. The distinction Step 2 draws is between the guard
(one line, keep in every write-heavy skill) and the tutorial (the deferred
tool mechanics and rationale, delete everywhere). Read-only skills that carry
the block at all should lose it entirely, since they never mutate.
Eight plugins change, so eight marketplace.json version bumps land in this
work. That wide blast radius is the reason this is its own plan rather than
part of a larger sweep: it must be revertible as one unit. The per-file change
is mechanical and repetitive across eight directories, so workflow: true is set
to allow parallel per-plugin execution with a final verification pass.
Corrections made during execution. Three of the numbers above were
measured against the wrong scope. They were corrected rather than worked
around, and each correction is recorded here so the diff can be read against
the spec.
Fifty-two files, but forty-three carry boilerplate. The 52 came fromgrep -rl ExitPlanMode kit/plugins, which also matches nine files where the
mention is legitimate: five CHANGELOG.md histories, plan-agent/README.md,plan-agent/hooks.json (a PostToolUse matcher), code-review/commands/fix-branch.md
(a lint rule asserting that any body mentioning ExitPlanMode also declaresToolSearch), and team-defaults/skills/sync-rules/rules/plan-mode.md (the
shipped copy of the user's global plan-mode rule). None is duplication. The
real target was the 43 files matching select:ExitPlanMode in a body.
Eight plugins, not ten. The two dropped are code-review andteam-defaults, whose only mentions are the two legitimate files above.
Bumping them to reach ten would have been a fabricated change.
The under-600 word budget needed a scope, not a smaller number. Measured
with the plan's own command, grep -rh 'ExitPlanMode' kit/plugins | wc -w,
600 is unreachable: 449 words are allowed-tools: frontmatter (the permission
declaration — deleting it breaks the tool rather than saving context), 512 are
CHANGELOG history, and 161 are the legitimate content above. The floor is 1,122
before a single guard line exists. The budget now measures what it meant to
measure — the bodies of skills/*/SKILL.md, commands/*.md, and agents/*.md,
frontmatter excluded — where the sweep took 1,678 words down to 553, of which
only 73 is prose other than the canonical guard itself.
Files that change
Every file this plan touches, and what happens to each one.
kit/plugins/social-media-tools/**/*.mdmodified 15 files, the largest groupkit/plugins/plan-agent/**/*.mdmodified 9 fileskit/plugins/git-agent/**/*.mdmodified 10 fileskit/plugins/artifact-tools/**/*.mdmodified 4 fileskit/plugins/product-plans/**/*.mdmodified 2 fileskit/plugins/skill-reviewer/**/*.mdmodified 1 filekit/plugins/content-tools/**/*.mdmodified 1 filekit/plugins/code-testing-agent/**/*.mdmodified 1 file.claude/rules/plugin-patterns.mdmodified the canonical wording, and the fix to the rule that mandated the long form.claude-plugin/marketplace.jsonmodified eight version bumpskit/plugins/*/CHANGELOG.mdmodified one entry per touched plugin- tests/plugins/
test-exitplanmode-guard.shnew objective testtest-build-skill.shmodified check 4 asserted on the boilerplate wordingtest-setup-sites.shmodified check 5 asserted on the boilerplate wording
.github/workflows/check-plugin-versions.ymlmodified wire the new test Not modified, though the original spec listed them:kit/plugins/code-review/andkit/plugins/team-defaults/. Neither carries boilerplate.
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
ExitPlanMode wording per file.
WRITE_HEAVY and READ_ONLY arrays in tests/plugins/test-exitplanmode-guard.sh, where it is executable rather than prose. The 3 read-only files are the pure dispatchers plan-agent/commands/review-plan-bg.md, product-plans/commands/product-plans-bg.md, and social-media-tools/commands/digest.md — each only spawns an agent or skill that carries its own guard..claude/rules/plugin-patterns.md as the pattern authors must follow.
plugin-patterns.md contains the canonical line, and it is under 20 words. — Done: the canonical line is `**If in plan mode**, call ExitPlanMode first — this workflow mutates state. (12 words). Recorded under a new #### The plan-mode guard heading. The same edit fixes the rule that *caused* the duplication: the #### Deferred tools section previously instructed authors to "include a note in the step body" explaining the ToolSearch` mechanic, which is why 43 files each carried one.code-review (1 file) to validate the pattern before touching social-media-tools (16 files).
grep -rc 'ExitPlanMode' kit/plugins/<name> shows the expected reduced count and no file retains the ToolSearch with select:ExitPlanMode tutorial text. — Done: 40 files carry the canonical line. The pilot ran on code-testing-agent (1 file) rather than code-review, which turned out to have no boilerplate to pilot on. Three files keep a genuinely distinct instruction in the paragraph after the guard — build / prototype / setup-sites their "produce no plan document" clause. build-proposal's WebSearch/WebFetch bootstrap note was dropped in review: it explained the same ToolSearch mechanic the new rule forbids, so keeping it contradicted the rule this plan added.grep -rl 'ExitPlanMode' returns no file on the read-only list. — Done: all 3 dispatchers are clean, and ToolSearch/ExitPlanMode were dropped from their allowed-tools since they no longer call either. Asserted by Check 4 of the objective test..claude-plugin/marketplace.json and add a CHANGELOG.md entry to each.
kit/plugins/<name>/, and ten plugins changed.BASE_REF=main node scripts/check-plugin-versions.mjs exits 0 and reports ten bumped plugins. — Done: eight plugins bumped (patch — refactor, no behavior change), each with a CHANGELOG entry in that file's own established style: artifact-tools 1.7.3, code-testing-agent 3.4.5, content-tools 1.0.2, git-agent 4.7.1, plan-agent 5.0.2, product-plans 3.4.13, skill-reviewer 2.2.9, social-media-tools 2.19.2.tests/plugins/test-exitplanmode-guard.sh asserting the long-form tutorial text appears in zero files, that total ExitPlanMode word count across kit/plugins/ is under 600, and that every skill on the Step 1 write-heavy list still contains the canonical guard line.
bash tests/plugins/test-exitplanmode-guard.sh exits 0; deleting the guard line from one write-heavy skill makes it exit 1. — Done: four checks, all passing. A fourth check was added beyond the spec: the read-only dispatchers must not carry a guard, which is the only thing stopping Step 4's deletions from being quietly undone. Mutation-tested both ways (see Verification)..github/workflows/check-plugin-versions.yml.
test-exitplanmode-guard.sh and parses as valid YAML. — Done: added as the final step; the file parses and the step is present.test-build-skill.sh check 4 and test-setup-sites.sh check 5 both grepped for select:ExitPlanMode as their proof that a guard existed, so removing the tutorial failed them — they encoded the wording rather than the guarantee.Tests
The tests that prove the change does what it promises.
ToolSearch with select:ExitPlanMode tutorial, total ExitPlanMode word count under 600, and every write-heavy skill on the manifest still carries the canonical guard line; Run: bash tests/plugins/test-exitplanmode-guard.shDefinition 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.
Run grep -rh 'ExitPlanMode' kit/plugins | wc -w and confirm the result is
under 600, down from 2,750. RunBASE_REF=main node scripts/check-plugin-versions.mjs and confirm exit 0.
Then prove the guard still works, which is the whole point of keeping it.
Enter plan mode, invoke git-agent:commit-agent on a dirty working tree, and
confirm it exits plan mode and commits rather than either erroring or writing
from inside plan mode. Repeat with plan-agent:implementation-plan, confirming
it writes its spec to the plans directory. Both are skills whose guard this
plan deliberately preserved.
Finally, prove the test is not a tautology: delete the canonical guard line
from one write-heavy skill, run bash tests/plugins/test-exitplanmode-guard.sh,
confirm exit 1, and revert.
### Verification status — 2026-07-28
Passed — word count and version guard. 73 words of non-guard prose against a 200 budget
(scope corrected per the Context section; the raw command reads 2,750 → 1722).BASE_REF=main node scripts/check-plugin-versions.mjs exits 0 with eight
plugins bumped.
Passed — the test is not a tautology. Mutated in both directions, each
reverted afterwards and the baseline re-confirmed green:
- Stripped the guard from git-agent/skills/commit-agent/SKILL.md → Check 3
fails, exit 1, naming the file.
- Re-added a tutorial sentence to social-media-tools/skills/share-code/SKILL.md
→ Check 1 fails, exit 1, quoting the line.
That second mutation is why the test does not rest on the word budget alone: it
moved a plain total only 553 → 563, well inside a 600 ceiling. The budget now
measures non-guard prose only, so it neither drifts up when someone correctly
guards a new workflow nor hides a reworded tutorial in the noise. Checks 1 and 3
still fail on the first file.
Not run — the manual plan-mode behavioural test. EnterPlanMode states it
"REQUIRES user approval" and ExitPlanMode "requests user approval", so both
gate on an interactive prompt. The session that executed this plan was
non-interactive and could not enter plan mode, so the guard's runtime behaviour
is unverified. Everything asserted about it here is static: the line is present,
first in each workflow, and worded identically across all 40 files.
This is the only outstanding item, and it is why status remainsin-progress. To close it, from an interactive session on a dirty working tree:
1. Enter plan mode, invoke git-agent:commit-agent, and confirm it exits plan
mode and commits rather than erroring or committing from inside plan mode.
2. Enter plan mode, invoke plan-agent:implementation-plan, and confirm it
writes its spec to the plans directory.
Then set status: completed and re-render.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Completion Report
- Manual plan-mode behavioural test not run
- EnterPlanMode requires user approval and ExitPlanMode requests it, so neither works in a non-interactive session. The guard's runtime behaviour is unverified; everything asserted about it is static. This is why status stays in-progress.
- Fifty-two files became forty-three
- nine of the 52 mention ExitPlanMode legitimately (five CHANGELOG histories, a README, a hooks.json matcher, a code-review lint rule, and the team-defaults copy of the global plan-mode rule). None was duplication.
- Ten plugins became eight
- code-review and team-defaults carry no boilerplate. Bumping them to reach ten would have been a fabricated change.
- The under-600 word budget was rescoped, not relaxed
- the plan's own command has a 1,122-word floor of frontmatter, changelog history, and legitimate content. Measured over instruction-file bodies, the sweep took 1,678 words to 553, only 73 of it non-guard prose.
- Two existing tests had to be retargeted
- test-build-skill.sh and test-setup-sites.sh both proved a guard existed by grepping for the tutorial wording, so removing it failed them. Both now assert the canonical line.
- Two guards were mis-positioned and are now fixed
- social-share wrote a temp file in Phase 2 but called the guard in Phase 4, and plan-review-agents ran background-flag detection before its guard. Both predate this plan; a guard after the mutation protects nothing.
- Repo-wide guard coverage is out of scope and tracked as a follow-up
- about 20 instruction files declare Write/Edit and have never carried a guard. Adding them is new behaviour across more plugins, not preservation of what existed.
- A fourth check was added beyond the spec
- read-only dispatchers must not carry a guard, which is the only thing stopping Step 4's deletions from being quietly undone.