/ac:plan
Interactive planner that runs entirely on the main thread (Opus 5). Spawns read-only subagents for parallel research, reads referenced code itself, walks the user through every load-bearing decision via AskUserQuestion, audits the plan for reuse and quality before writing, then writes a tier-assigned plan to .ac/plans/<slug>/plan.md.
Request: $ARGUMENTS
Standing rules
These hold for the whole run, including after a compaction. Everything below this block is procedure; these are the bounds. They sit here because a re-attached skill keeps only its first 5,000 tokens after compaction (https://code.claude.com/docs/en/skills.md) and this body is far larger, so a rule further down is gone from context on exactly the long runs that need it.
Turn termination. Your turn ends on exactly one of: an AskUserQuestion call, the Stage 6 plan summary (or, under AUTO_MODE = true, the chained ac:execute run reaching its own terminal state), or a named BLOCKER from <auto_mode>. Nothing else ends it. Never end a turn by describing what you would do next, and never on the Stage 3a or Stage 4
render: both are followed by an AskUserQuestion in the same turn, so stopping after one skips the question. The
Stage 6 summary is the exception and does end the turn, under AUTO_MODE = false. When a turn does end on a
render and the user says "continue", resume at the question that render was leading to rather than at the stage
after it; a stage whose question went unasked did not complete.
Context. Auto-compaction summarizes older turns and the run continues. A filling context window is not a stopping condition and not a reason to defer work to a new session. When the procedure you need has been truncated away, re-invoke the ac:plan skill to restore this body and read .ac/plans/<slug>/checkpoint.json for where the run was.
No loop needs bounding here. Stage 5.5 is one advisory reviewer pass, so nothing on the plan side counts iterations. The only bounded loops left are Stage 3d's stall check, which fires after three non-progress interview turns, and the Stage 1e re-spawn, which allows one retry per subagent.
Progress surface. The files are the surface, and there is no task list. LOG_PATH records every question and answer as it resolves, CHECKPOINT_PATH carries last_stage so a compaction or a restart resumes rather than restarts, and one short line per stage transition is what the user sees live.
This setup runs with CLAUDE_CODE_ENABLE_TASKS=false in ~/.claude/settings.json, a deliberate choice: the task tools' schemas cost roughly 2,500 tokens of context on every turn, which is more than a stage-transition line is worth. Do not write a procedure that depends on them.
Output length. Per-turn user-facing prose: at most 3 lines. The Stage 3a synthesis, the Stage 4 preview, and the Stage 6 summary are the only long surfaces, and their templates fix their shapes. Everything else a later reader needs goes in LOG_PATH or PLAN_PATH, not into the chat. This is a cost rule, not a style one: every token you write stays in context and is re-read as cache on every later turn, so a long run carries each sentence for the rest of its life. A file is read on demand; a sentence in the chat is read hundreds of times.
Source code is never modified here. Execution is /ac:execute <slug>, run by the user or chained by auto mode.
Subagents are separate HTTP calls with their own system prompt and inherit none of your context, so every brief
carries CONTEXT + GOAL + DOWNSTREAM + REQUEST. Drive every chain from here: ac:explore and the four plan-workers
cannot spawn anything (their tools: allowlist omits Agent), and the read-only advisory agents have Agent denied
so their retrieval stays inside the budget you gave them. A chain means the agent reports back and you make the next
call, which is also the only way its cost stays visible.
Auto mode automates system-process flow gates. It never auto-decides user-preference content.
| Call site | Class | Under AUTO_MODE = true |
|---|---|---|
| 0a Topic missing | BLOCKER | surfaces |
| 0e Resume? | flow | auto-pick Resume |
| 0f Plan collision | flow | auto-pick Append suffix, deliberately NOT the first option; preservation beats silent destruction |
| 3a Proceed after synthesis | interview | surfaces |
| 3b.1 TDD node | interview | surfaces |
| 3c Every decision node | interview | surfaces |
| 3d Stalled? | flow | auto-pick Continue |
| 3.5c Oracle returned CRITICAL | BLOCKER | surfaces |
| 4 Lock all | flow | auto-pick Lock all and run on auto mode |
| Stage 5 write fails twice | BLOCKER | surfaces |
| Subagent malformed twice | BLOCKER | surfaces |
Flow gates resolve to the (Recommended) option and emit one heartbeat line, Auto mode: <header> -> <option>.
Interview gates surface whatever the mode, because they are preference content rather than process flow; the Stage 3
recommendations are grounded in Stage 1 research and Stage 2 deep read, and the user picks among them. BLOCKER gates
surface whatever the mode, because they need judgment auto mode cannot supply.
The anti-runaway guards are the loop bounds, not this table: Stage 3d fires after three non-progress
interview turns, and the chained /ac:execute bounds its own side. Heartbeat is one short line
per stage transition and per auto-resolved gate; interview gates emit none, since the user's answer already shows in
the chat.
Stage 0: Setup
0a. Parse the argument
Scan $ARGUMENTS for the --auto flag (anywhere in the string, surrounded by whitespace or at the start/end). If present: set AUTO_MODE = true, strip the flag from $ARGUMENTS, continue with the remaining string. If absent: set AUTO_MODE = false.
If the post-strip $ARGUMENTS is empty:
- When
AUTO_MODE = false: callAskUserQuestion(headerTopic?, single optionProvide topicwith freeform-Other prompt). Wait for input, then continue. - When
AUTO_MODE = true: this is a BLOCKER (auto mode cannot proceed without a topic). Surface the sameTopic?question; the user provides the topic; auto mode resumes after.
If the post-strip $ARGUMENTS matches .ac/tasks/*.yaml, Read the YAML and extract type, User Story, and Acceptance Criteria as the request body. Otherwise treat $ARGUMENTS as a free-form topic.
If AUTO_MODE = true, emit a single user-visible line: Auto mode engaged. Will run end-to-end through planning and execution, halting only on BLOCKER classes.
0b. Derive slug and paths
Read ${CLAUDE_SKILL_DIR}/references/slug-derivation.md and apply it. It carries the seven ordered steps (path-strip, tokenize, Turkish ASCII fold, stopword filter, tech-stack preference, truncate to 5, normalize), the empty-slug fallback, and five worked examples.
Set:
PLAN_DIR = .ac/plans/<SLUG>/PLAN_PATH = .ac/plans/<SLUG>/plan.mdLOG_PATH = .ac/plans/<SLUG>/interview-log.mdCHECKPOINT_PATH = .ac/plans/<SLUG>/checkpoint.jsonRESEARCH_DIR = .ac/plans/<SLUG>/research/EVIDENCE_DIR = .ac/plans/<SLUG>/evidence/PROJECT_DIR_HINT(when step 1 stripped a path): becomes the Recommended default for the Stage 3 D1 project-location decision; user may override during the interview.
0c. Create directory structure
Bash: mkdir -p .ac/plans/<SLUG>/research .ac/plans/<SLUG>/evidence
Directories only. The plan skeleton is scaffolded at Stage 5, not here: Stage 0f checks whether
PLAN_PATH already exists, so writing a skeleton before that check would make the collision branch fire
on every fresh run and silently rename the slug under auto mode.
Idempotent; safe to run on every invocation.
0d. Gitignore guard
In a git repo (git rev-parse --git-dir 2>/dev/null exits 0), run git check-ignore -q .ac/. If non-zero (path not ignored), append .ac/ to .gitignore (create the file if missing) and print one line: Added .ac/ to .gitignore so planning artifacts stay local. Use git add -f to track specific plan files. Skip outside a git repo or when .ac/ is already ignored. The check is idempotent; run it on every invocation.
0e. Resume check
If CHECKPOINT_PATH exists:
- When
AUTO_MODE = false: Read it and callAskUserQuestion(headerResume?, optionsResume (Recommended)/Start fresh). - When
AUTO_MODE = true: auto-pickResume (Recommended)without surfacing the question. Emit one line:Auto mode: Resume detected, restoring from checkpoint.
On Resume: restore working memory from the JSON (locked_decisions, locked_requirements, canonical_refs, deferred_ideas, codebase_state, conventions, reuse_map, last_stage), jump to the stage indicated by last_stage. On Start fresh: delete the checkpoint, continue to 0f.
For the checkpoint JSON schema and write points, read ${CLAUDE_SKILL_DIR}/references/checkpoint-schema.md.
0f. Plan collision check
If PLAN_PATH already exists and no checkpoint was just consumed:
- When
AUTO_MODE = false: callAskUserQuestion(headerExists?, optionsOverwrite/Append suffix (<slug>-2)/Cancel). Apply the choice. - When
AUTO_MODE = true: auto-pickAppend suffix (<slug>-2)(NOT the literal first optionOverwrite; auto mode's safer default differs from interactive mode per the<auto_mode>policy). If<slug>-2also exists, increment to-3,-4, etc. until a free slug is found. UpdateSLUGand all derived paths. Emit one line:Auto mode: collision detected, appended suffix; new slug = <new slug>.
Stage 0 complete.
Stage 1: Codebase Survey + Parallel Research
Goal: ground the request in evidence before asking the user anything. Two-step: the main agent first builds its own coarse mental map of the project (1a), then spawns the parallel research cohort (1b-1d) with briefs anchored in that map, then waits for all (1e). The main agent does not skip 1a; subagent paraphrases stacked on a missing baseline produce shallow plans.
1a-1d. Survey, then fan out
The main agent runs the directory survey itself; it is not delegated. Subagents launch with shallower context, so
you build the map and pass it down through the briefs. Write it to RESEARCH_DIR/00-directory-survey.md.
Read ${CLAUDE_SKILL_DIR}/references/research-fanout.md for the survey command block, the dedicated reuse explore brief, and the brief shape every spawn follows.
dedicated reuse explore brief, and the brief shape every spawn follows.
Counts policy, which governs the fan-out and stays here:
ac:explore: floor 4, target 7, including the dedicated reuse explore. Narrow plans land near the floor, broad ones near the target. One brief per independent angle; do not bundle.ac:librarian: floor 2, target 3. Brief 1 verifies idiomatic patterns against vendor docs, brief 2 covers known bugs and version-combo breakage, brief 3 adds OSS reference examples or a second library.ac:oracle: 1, only when the request signals architecture intent. Advisory and non-blocking; do not gate on it.
Every brief carries a DEPTH and a BUDGET, or the agent falls back to its own default and searches wider than
the angle needs. The reuse angle is one dedicated brief, not a clause added to the others. Issue all spawns in ONE
assistant message with run_in_background: true.
1e. Wait, archive, checkpoint
A subagent returning empty or malformed output gets one re-spawn with a format reminder; a second failure is a
BLOCKER, AskUserQuestion (header Agent fail?, options Retry (Recommended) / Skip this angle / Abandon),
surfaced even under auto mode, because dropping a research angle silently leaves the plan thinner than it claims.
Wait for all spawned agents (collect BackgroundTask outputs or wait for foreground returns). Write each agent's output to RESEARCH_DIR/<agent-type>-<short-slug>.md. The directory survey at RESEARCH_DIR/00-directory-survey.md is already on disk from 1a. Write a checkpoint with last_stage: "1" and the gathered research summary.
Stage 1 complete.
Stage 2: Main-Agent Deep Read
Goal: build your own mental model. Subagents found candidates; you read the code and make decisions. Apply this to every file referenced by Stage 1 results, not just the first.
2a. Read what decides something, not everything referenced
Stage 1 hands you a candidate list. Open what will move a decision, and read enough of it to move that decision, rather than reading every path any agent happened to cite.
The order to reach for, cheapest first:
LSP hoverorgoToDefinitionwhen the question is "does this symbol exist and what is its shape". That is most reuse-candidate questions and it costs a fraction of a file.Grepwith context when the question is "is this pattern really here".Readwithoffsetandlimiton the cited range plus surrounding context.Readin full only when the file is short, or when the decision genuinely turns on the whole shape: an interface you will conform to, a module you will restructure.
Trace call sites with LSP findReferences when a candidate sits in a chain you intend to change.
This is the same correction D2 made on the execute side, and it exists for the same reason: an earlier
version of this stage said to Read every referenced path in full, which admits an entire candidate set
into the context that then carries it for the rest of the planning run. What the stage is actually for
is owning the mental model, and a symbol you confirmed with hover is owned just as well as one you
read 400 lines to confirm.
What has NOT changed: cover every candidate. Reaching each one cheaply is the point; skipping the fourth because the first three were interesting is the failure this paragraph used to guard against, and it still is.
2a.1. Verify before you trust
A subagent report is a claim, not a finding. Before any claim changes a decision, check it against the source:
open the file:line it cites, recount what it counted, grep the quote it quoted, and read the report against its
own tables. Two reports agreeing is not verification when both read the same wrong thing.
Append every refuted or corrected claim to RESEARCH_DIR/verification-log.md with the claim, the check, and the
verdict. The plan then cites verified facts rather than reported ones, and a refuted claim cannot quietly return
after a compaction has summarized away the memory of refuting it.
Verification is yours, on the main thread. Delegating the check to another subagent reproduces the problem it
solves. Procedure at ${CLAUDE_SKILL_DIR}/references/research-verification.md.
2b. Classify codebase state
Sample 2 to 3 representative files and check linter, formatter, and type-checker configs. Tag the codebase with one of:
disciplined: consistent style, configs present, tests cover the surface. Match patterns strictly.transitional: mixed styles, partial migrations visible. Ask which pattern to follow when it matters.legacy: older patterns, gaps in tooling, but coherent within its era.chaotic: no consistent style, no tests. Propose conventions and confirm with the user.greenfield: empty or near-empty. Apply modern best practices.
2c. Extract dominant conventions
Distill these from the files read:
- Naming pattern (camelCase, snake_case, kebab-case per file type)
- Error handling style (throw, Result, try-catch boundaries)
- Comment density (none, WHY-only, docblocks everywhere)
- Type discipline (strict, mixed, untyped)
- File organization (flat, nested, barrel exports)
- Import convention (relative, aliased, absolute)
- Path aliases (the alias-to-directory mapping, plus any mis-form that produces a build error)
- LSP false-positive whitelist (autoload-registered globals and structural hints the executor should skip)
- Test mount discipline (the one canonical mount pattern and any banned API, when test infrastructure exists)
That is nine, and TDD from 2c.1 makes ten. All ten go into the checkpoint and into the plan template's
## Codebase Conventions section verbatim.
Extract all ten, not the first six. The executor now inlines this whole section into every worker briefing and the worker no longer opens the plan, so a convention this stage does not set is a convention no worker ever sees. Omit a field only when it genuinely does not apply, and say so rather than leaving it blank.
2c.1. Test infrastructure detection (drives TDD interview node)
Scan for test infrastructure: package.json scripts containing test, presence of vitest.config.* / jest.config.* / bun.test.* / pytest.ini / equivalent, and a tests/ or __tests__/ directory with non-trivial content. Record:
TEST_INFRA_PRESENT = true | falseTEST_FRAMEWORK = <name>(when detected): vitest, jest, bun test, pytest, go test, etc.TEST_COMMAND = <command>: extracted frompackage.jsonorCLAUDE.md.
This drives the Stage 3 TDD interview node: if TEST_INFRA_PRESENT = true, the planner asks the user whether to use TDD (defaulting to yes, since the infrastructure already exists). If TEST_INFRA_PRESENT = false, the planner asks whether to set up test infrastructure as part of this plan or proceed without tests.
2d. Internal feasibility synthesis
Synthesize internally, not yet shown to the user: what exists today (file:line per similar implementation), the
Reuse Map draft, the delta the request needs that does not exist, codebase fit (High / Medium / Low with a reason),
effort (Small 1-2 files / Medium 3-5 / Large 5+ cross-module), prerequisites, and the risks research surfaced.
Write a checkpoint with last_stage: "2". Stage 2 complete.
Stage 3: Grill-me Interview
Goal: walk down the decision tree with the user until every load-bearing decision is locked. Hybrid walk-down branching plus multiSelect for parallel independent decisions. Every question carries a recommended option grounded in research.
3a-3c. The interview walk-down
Read ${CLAUDE_SKILL_DIR}/references/interview-procedure.md and follow it. It carries the synthesis preview, the
routing rule with its worked examples, the TDD node, and the walk-down with its pruning and batching heuristics.
Three bounds hold whatever that file says, because they govern the whole stage rather than one node:
- The routing rule gates every question. Before anything reaches the user, ask whether code can answer it (read
the file), whether docs can (spawn
ac:librarian), or whether only the user can (preference, business call, value judgment). Only the third class becomes anAskUserQuestion. - Every resolved node writes a checkpoint with
last_stage: "3", so a compaction mid-interview resumes instead of restarting. - Every question and answer appends to
LOG_PATH. The log is the record; working memory is not.
3d. Stall handling
If three consecutive AskUserQuestion turns produce no decision-tree progress (user picks "Other" with hedging, or your follow-up keeps surfacing the same node), call AskUserQuestion (header Stalled?, options Continue (Recommended) / Force-finalize with recommended defaults / Abandon). On Continue: keep going, no further limit. On Force-finalize: lock all remaining unresolved nodes with their recommended options, list them in the plan's ## Risks Accepted section. On Abandon: write .ac/plans/<slug>/abandoned.md with the synthesis and last state, exit.
3e. Convergence
The interview is complete when:
- Every node in the decision tree is locked, deferred to the backlog, or explicitly risk-accepted.
- No question remains that code, docs, or the user has not answered.
- The reuse-vs-build choice is explicit for every new piece of code the plan proposes.
Plan files contain zero open questions. If a decision could not be locked, it is either deferred (out of scope, captured in ## Deferred Ideas) or risk-accepted (kept in scope with the recommended default and a note in ## Risks Accepted).
Write a checkpoint with last_stage: "3-complete". Stage 3 complete.
Stage 3.5: Oracle Sanity Check (trigger-based)
Goal: a planning-time oracle pass that catches design bugs and idiomatic-pattern hallucinations before plan write. Run after Stage 3 interview concludes; evaluate the locked decisions against four trigger conditions. If any fires, spawn ONE ac:oracle in background with a focused brief; findings inline into the Stage 4 Synthesis Preview under a new ### Oracle Sanity-Check Findings subsection. If no trigger fires, skip Stage 3.5 silently (no oracle spawn, no Stage 4 subsection).
3.5a. Trigger evaluation
Evaluate each trigger against the locked decisions, scope, and conventions from Stage 3:
Security-critical surface in scope: the locked plan touches authentication / authorization (login, password, session, token, RBAC, RLS, Policy / Gate, OAuth flow), payment / billing / financial calculation (currency math, charge, refund, invoice, ledger), cryptographic operations (hash, sign, verify, encrypt, decrypt, JWT, HMAC, password hashing), user-input → SQL / shell / file path (injection or traversal surface), or file upload / deserialization (RCE surface).
Composable framework-API pattern adopted from librarian research: the plan adopts a chained call (
.X()->Y()->Z()) that librarian described as idiomatic but has unverified per-method semantics. Composable chains are the highest-frequency hallucination class (LaravelmiddlewareFor(['index'], [])adopted as "exempt index from auth" when it assigns empty middleware; ReactuseMemosemantics adopted from a blog post when the docs say otherwise). Trigger fires when at least one such chain appears in the locked decisions OR the plan's intended Codebase Conventions.Conflicting research signals: Stage 1 librarian or explore returned contradictory recommendations on the chosen path, OR the chosen path's evidence is single-source / low-confidence. Oracle as tie-breaker.
Migration with destructive operations: schema rename,
DROP,TRUNCATE, data-shape change with no rollback path. Production-safety review.
Trigger evaluation is mechanical, match locked decisions and conventions against the surface lists above. If zero triggers fire: proceed silently to Stage 4. If one or more triggers fire: assemble ONE oracle brief targeting the fired triggers and proceed to 3.5b.
3.5b. Oracle brief shape
Spawn one ac:oracle with run_in_background: true, using the brief at
${CLAUDE_SKILL_DIR}/references/research-fanout.md under ## Stage 3.5 oracle brief shape. Include only the GOAL
bullets for the triggers that actually fired.
3.5c. Wait, classify, route
Wait for the oracle, then sort findings by severity.
Any CRITICAL finding is a BLOCKER: surface it before Stage 4 even under auto mode, via AskUserQuestion (header
Oracle CRIT?, options Revise plan (Recommended) back to Stage 3 at the affected decision / Accept as Risk,
which locks the concern into ## Risks Accepted / Abandon, which writes abandoned.md and exits).
A REFUTED premise is its own branch, and it outranks the finding severities. The oracle returns a **Premises**
block classifying the claims your brief rested on. A premise it marks REFUTED, with a quote from the source that
contradicts it, is not a finding about the plan: it is evidence that the research under a locked decision does not
hold, so every decision downstream of it is now unsupported whatever else the oracle said. Surface it before
anything else, naming the premise and the quote, then AskUserQuestion (header Premise failed?, options
Re-research and re-decide (Recommended) back to Stage 1 for that angle only / Revise the decision without new research, when the refutation itself tells you enough / Accept as Risk, which locks it into ## Risks Accepted
with the refutation quoted). A premise marked UNSUPPORTED does not halt; carry it into the Stage 4 preview so the
user sees which claims nobody could source.
IMPORTANT findings do not halt: inline them into the Stage 4 preview under ### Oracle Sanity-Check Findings. No
findings means that subsection is omitted entirely.
When a finding explicitly names a sibling project ("the same gap exists at <sibling>/.../foo.ts:N"), record it in
the plan's ## Cross-Project Observations at Stage 5. This plan absorbs the finding for its own scope only; the
sibling fix is a separate plan with its own interview and review. Never silently fix sibling code.
Append the outcome to LOG_PATH under ## Stage 3.5 Oracle Sanity Check (triggers fired, findings count, routing
if the BLOCKER fired) and write a checkpoint with last_stage: "3.5".
Stage 3.5 complete.
Stage 4: Synthesis Preview
The render and the question are one turn, and the question is the stage. Append the full synthesis to
LOG_PATH, render the short form in the chat, then call AskUserQuestion, all in the same turn.
Measured once: the planner rendered a 908-character summary reading "decisions locked, here is the summary before
I write the plan", ended the turn, and after the user typed "continue" went straight to Stage 5. The Lock all?
gate was never asked, so AUTO_MODE was never set. Length was not the cause and a shorter render would not have
prevented it: the two Stage 3 renders in the same run were 360 and 395 characters and both carried their question
fine, and the planner's own reasoning before the render already said it was moving on to writing the plan. Two
Stage 3 AskUserQuestion rounds had made this one read as redundant, and the whole procedural layer was degrading
at that point in the run (no checkpoint was written either). The forcing function is in Stage 5 rather than here:
plan-scaffold refuses to run without this stage's answer.
Render the locked synthesis in the chat using the shape at
${CLAUDE_SKILL_DIR}/references/interview-procedure.md under ## Stage 4 synthesis preview shape, capped at
roughly 2 KB on the cost grounds the Output length standing rule already argues: the Goal in one line, the Scope
IN and OUT lists, the Locked Decisions table, the hard constraints research produced, and a one-line pointer to
LOG_PATH for the rest. Codebase Conventions, the Reuse Map, the Canonical References and the full Deferred Ideas
list go to LOG_PATH only; they are inputs to the plan file you are about to write, not a decision the user is
being asked to make here.
Then call AskUserQuestion (header Lock all?):
Lock all and run on auto mode (Recommended): setsAUTO_MODE = true, auto-resolves the remaining flow gates, and chains into/ac:execute --autoat Stage 6. The default once decisions are locked, because the interview and the Stage 5.5 reviewer already carry the quality bar.Lock all and proceed step-by-step: write the plan, run the review, then stop and let the user run execute.Revise a decision: loop back to Stage 3 targeting one node.Revise / expand scope: change what is IN or OUT, or pull a deferred idea into v1; loops back to Stage 3.
This is the only gate where the user sees whether the rest of the run is autonomous, so it fires whenever --auto
was absent; auto mode skips it and proceeds as if option 1 were picked.
Stage 4 complete.
Stage 5: Plan Write
Scaffold the skeleton first, then fill it in with Edit:
Bash: node "${CLAUDE_PLUGIN_ROOT}/cli/ac.js" plan-scaffold <SLUG> --auto-mode <true|false>
--auto-mode is required and takes the Stage 4 Lock all? answer: true for option 1, false for option 2.
There is no other source for it and no default. If you do not have that answer, Stage 4 did not complete: go back
and ask its question before scaffolding. The value lands in the plan frontmatter as **Auto mode**:, which is
what Stage 6a reads, so the decision survives a compaction that an in-context variable does not.
The subcommand writes every section heading in template order and no-ops when plan.md already exists, so a
resumed run cannot clobber a filled-in plan. Fill it with Edit; a Write on PLAN_PATH erases the skeleton,
and a second Write erases the first call's output.
Under ## Steps the skeleton carries a worked step stub rather than a <fill> marker. Follow it exactly and
delete it once the real steps are written. The two fields in it that a downstream tool parses rather than reads
are the - [ ] **Step N**: line, which Layer D ticks and the Stop hook counts, and Type, which is one of
code, infra or verification and which the executor routes on with no branch for any other value. Measured
once: a plan written from memory instead of from this shape carried neither, and the executor spent a user gate
and 18 repair edits before its first worker spawned.
Write the plan to PLAN_PATH using the markdown structure at ${CLAUDE_SKILL_DIR}/references/plan-template.md. That file contains the full plan-file shape (frontmatter + all sections + per-step field shape) and the post-write verification + BLOCKER escalation if the write fails twice.
Fill placeholders with concrete content; remove placeholder text inside angle brackets. For tier assignment per step, read ${CLAUDE_SKILL_DIR}/references/model-tiers.md (capability summaries + decision heuristic). For plans with more than 10 steps, use the incremental write protocol described in the template reference.
Write the plan as if no reviewer will look at it. Stage 5.5 is a single advisory pass now, not a loop that will grind a draft into shape, so a plan that arrives there needing work simply ships with the findings deferred. Concretely: every step's Description / Files / Done when / QA / Must NOT is specific enough that a fresh agent can execute without guessing; the Codebase Conventions section captures every project-specific rule the workers need; the Reuse Map names every existing utility the plan leverages; the locked decisions from the interview are reflected in the steps themselves, not assumed. The Stage 5.5 reviewer caps at 3 passes with a stall test; plans that converge in 0-1 are the goal.
Test-driven literal-pattern audit (Stage 5 quality discipline): when a step's Description names a literal regex pattern, a literal config snippet (package.json fragment, tsconfig field, command-line invocation), or a literal API chain (.X().Y().Z()), AND the same step's QA or Done when field lists concrete test inputs that exercise it, execute the pattern against each of those inputs in your head BEFORE plan write. If any listed input would fail the literal as written, either fix the literal in the plan or flag the gap in the step's Description as regex-needs-validation, snippet-needs-validation, or chain-needs-validation. The worker's TDD red phase is the safety net for what this misses; catching it at planning time is cheaper. The template reference carries a worked example of the class of bug this finds.
Negative-test audit (Stage 5 quality discipline): for every Done when criterion that names a shell command, answer one question before plan write: what input would make this report a failure. Run the command in your head against that input. Two shapes cannot answer it and both get flagged in the step's Done when as criterion-needs-negative-test. A flag the tool does not support, where the shell exits non-zero with empty stdout and "returns nothing" reads as clean: grep -P on macOS is the measured case, and rg is the replacement. A pipeline that truncates before the asserted value appears, head being the usual culprit. Then, for any criterion naming a number, read that number against the fixture the same step sets up; when the step's own inputs cannot reach it, the criterion is wrong rather than unmet, so fix the criterion. The template reference carries both failures with their measurements.
Shape gate before the reviewer. Run it once the plan is written:
Bash: node "${CLAUDE_PLUGIN_ROOT}/cli/ac.js" plan-check <SLUG>
It exits 1 and names every deviation the executor would hit: a checkbox count that disagrees with the Steps
frontmatter, a Type outside the three, a worker step with no Tier, a verification step with no Commands or
Evidence, a scaffold placeholder left in place. Fix every ERROR with Edit and re-run until it exits 0. WARN
lines are yours to judge.
This runs before Stage 5.5 because the reviewer reads prose and would spend a pass reporting what one command settles for free. It is also the last point where the fix is cheap: the same defects found at execute time cost a user gate and a repair pass with the run already started.
Stage 5 complete.
Stage 5.5: Independent Review
Goal: one second-eye read of the written plan by a fresh-context subagent that sees only the plan file. It catches what the planner's own context bias hides: stale references after revision, executability from a cold start, tier assignments that drifted while writing.
It is ONE pass and it is advisory. There is no verdict and no loop.
5.5a. Spawn the reviewer
Agent({
subagent_type: "ac:plan-reviewer",
description: "Independent plan review",
prompt: PLAN_PATH
})
The prompt is the path and nothing else. The fresh context IS the second eye; adding your own context to the prompt destroys the property while looking like an optimization.
5.5b. Act on the findings, then move on
The reviewer returns findings tagged CRITICAL or IMPORTANT, with no verdict. You are the filter:
- CRITICAL: fix it with
Editbefore Stage 6. These are the ones that make a step unexecutable by a fresh agent: a reference that does not resolve, a step whoseDone whencannot be satisfied by itsFiles, an internal contradiction between two steps. - IMPORTANT: fix it when the fix is small and local. Otherwise record it in the plan's
## Deferred Ideaswith one line naming what was deferred and why. - Anything else goes in
## Deferred Ideasor is dropped.
After any edit, grep the plan for each string tied to the changed substance and patch every survivor.
One step restates the same rule across Description, Why this tier, Done when, QA, Must NOT and
References, so a single-field edit leaves contradictions behind. This sweep used to be carried by the
loop's later passes; with one pass it has to happen here.
Re-run plan-check after the last edit. A reviewer fix is the likeliest way to break the shape the gate just
confirmed: splitting a step or dropping one changes the count the Steps frontmatter declares, and nothing else
in this stage would notice.
Append the outcome to LOG_PATH under ## Stage 5.5 Review: findings by severity, what was fixed, what
was deferred. Then write a checkpoint with last_stage: "5.5".
Why this is one advisory pass and not a gate
Measured across 26 plans and 88 reviewer runs: 82 REJECT against 5 OKAY, a 94% reject rate, with 69% of
plans hitting the 3-pass cap and 27% exceeding it. Eighty-eight passes produced five approvals, so about
80% of plans left the loop by hitting the cap and having the operator pick Proceed anyway. The override
was already the norm; this stops paying 3.4 Opus passes to reach it.
The 94% was not a quality signal, it was a self-contradiction in the agent: it was told to report everything and let a downstream pass filter, while its own verdict rule blocked on three accumulated IMPORTANT findings, so the downstream filter never ran. Removing the verdict is what lets the reporting instruction work as intended.
The reviewer still catches real defects, which is why it stays: a plan claiming an API registered lazily when it does not, a plan whose auth objective no step actually implemented. Those are CRITICAL findings and they get fixed. What is gone is the machinery that turned every plan into three passes.
Stage 6: Deliver
Delete CHECKPOINT_PATH. The plan is locked and reviewed.
Render the plan summary using the template at ${CLAUDE_SKILL_DIR}/references/plan-summary-template.md. Fill concrete values from the plan file.
Stage 6 complete.
6a. Auto-mode chain
Read **Auto mode**: from the plan frontmatter rather than trusting the in-context AUTO_MODE. Stage 5 wrote it
there from the Stage 4 answer, and the file is what survives a compaction between the two. They agree on any run
that went through Stage 4; when they disagree, the file is right and the variable was lost.
When AUTO_MODE = true, do not end the turn after the summary. Emit one line naming the handoff, then invoke the
ac:execute skill with skill: "ac:execute" a
…(truncated)