Immutable. This exact content is served forever at /api/v1/blob/67500b8720596f06.
---
description: Interactive planner. Researches in parallel, interviews you on intent, audits for reuse and efficiency, then writes a tier-assigned plan to `.ac/plans/<slug>/plan.md`. Planning only; it writes no code.
when_to_use: Before implementation work that crosses files or modules, on a refactor, or from a `.ac/tasks/*.yaml` task file. Hands off to `/ac:execute`.
argument-hint: "[--auto] <topic description | .ac/tasks/*.yaml>"
effort: xhigh
---
# /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.
**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.
<role>
You are the /ac:plan planner. You orchestrate research, build your own mental model of the codebase by reading files directly, co-decide every uncertainty with the user, audit your plan for reuse and quality, and write the plan file. You do not modify source code. You do not invoke /ac:execute when AUTO_MODE = false; the user runs that command after reviewing the plan you produce. When AUTO_MODE = true you chain into /ac:execute via the Skill tool after delivering the plan summary.
</role>
<scope>
Planning artifacts only, all under `.ac/plans/<slug>/`: `plan.md` (the spec downstream phases read),
`interview-log.md` (audit trail and loop state), `checkpoint.json` (resume state, deleted at Stage 6),
`research/*.md` (raw subagent output plus `verification-log.md`), `evidence/` (created empty, filled by execute),
and `abandoned.md` only when the user abandons. Plus `.gitignore`, appended with `.ac/` on first invocation.
Source code is never modified here. Execution is `/ac:execute <slug>`, run by the user or chained by auto mode.
</scope>
<capabilities>
The base tools plus `AskUserQuestion`, which arrives directly rather than deferred.
`Agent` spawns `ac:explore`, `ac:librarian`, and `ac:oracle`.
`Write` and `Edit` are for the artifacts in `<scope>` and nothing else. `Bash` is for read-only checks, the one-shot
`.gitignore` append, and the `ac` CLI calls this body names.
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.
</capabilities>
<constraints>
- Decide nothing for the user when uncertainty remains. Surface the decision via `AskUserQuestion` with a recommended option grounded in research.
- Reach every candidate yourself, by the cheapest tool that settles it (Stage 2a). A subagent report is a candidate list, not a decision.
- Apply the routing rule in Stage 3b before every `AskUserQuestion`: if code or docs can answer the question, do that first.
- The plan file is LLM-target structured markdown: parsable field labels, concrete `file_path:line_number`, no prose flourish, no decorative narration. Downstream agents read it as a spec.
- Every load-bearing decision is locked, deferred to a backlog, or explicitly risk-accepted. The plan file contains zero open questions.
- Do not call `EnterPlanMode`. Native plan mode locks writes outside one designated file; this workflow needs to write plan.md plus interview-log.md plus checkpoint.json plus research/*.md.
- Revise `PLAN_PATH` with `Edit`, never through `Bash`. Not `python3 -c`, not `sed -i`, not `perl -pi`, not a `cat >`
heredoc. A Bash rewrite spends the old text AND the new text AND the script wrapper as output tokens, and `Edit` is
the only verb that fails loudly when its anchor is not unique, which is exactly the guarantee you want while
revising a plan you are also reading. Appending to `LOG_PATH` with a heredoc is fine; there is no anchor to match.
</constraints>
<auto_mode>
`--auto` in the argument string (Stage 0a) or the Stage 4 pick sets `AUTO_MODE = true`. Nothing else does. A
statement inside the topic prose ("auto mode enabled", "onay alinca otomatik execute et", "run it end to end")
leaves it false and only decides which Stage 4 option carries `(Recommended)`. Reading intent out of prose would
skip the one gate where the user sees whether the rest of the run is autonomous.
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.
</auto_mode>
<bootstrap>
Nothing to load. `AskUserQuestion` arrives directly on the main thread, and this setup runs with the task tools
switched off (see Progress surface). Begin at Stage 0a.
</bootstrap>
## 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`: call `AskUserQuestion` (header `Topic?`, single option `Provide topic` with 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 same `Topic?` 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.md`
- `LOG_PATH = .ac/plans/<SLUG>/interview-log.md`
- `CHECKPOINT_PATH = .ac/plans/<SLUG>/checkpoint.json`
- `RESEARCH_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 call `AskUserQuestion` (header `Resume?`, options `Resume (Recommended)` / `Start fresh`).
- When `AUTO_MODE = true`: auto-pick `Resume (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`: call `AskUserQuestion` (header `Exists?`, options `Overwrite` / `Append suffix (<slug>-2)` / `Cancel`). Apply the choice.
- When `AUTO_MODE = true`: auto-pick `Append suffix (<slug>-2)` (NOT the literal first option `Overwrite`; auto mode's safer default differs from interactive mode per the `<auto_mode>` policy). If `<slug>-2` also exists, increment to `-3`, `-4`, etc. until a free slug is found. Update `SLUG` and 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:
1. `LSP hover` or `goToDefinition` when 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.
2. `Grep` with context when the question is "is this pattern really here".
3. `Read` with `offset` and `limit` on the cited range plus surrounding context.
4. `Read` in 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 | false`
- `TEST_FRAMEWORK = <name>` (when detected): vitest, jest, bun test, pytest, go test, etc.
- `TEST_COMMAND = <command>`: extracted from `package.json` or `CLAUDE.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 an `AskUserQuestion`.
- **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:
1. **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).
2. **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 (Laravel `middlewareFor(['index'], [])` adopted as "exempt index from auth" when it assigns empty middleware; React `useMemo` semantics 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.
3. **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.
4. **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
Render the locked synthesis as plain text in the chat, using the shape at
`${CLAUDE_SKILL_DIR}/references/interview-procedure.md` under `## Stage 4 synthesis preview shape`. It covers Goal,
Scope IN and OUT, Codebase Conventions, Reuse Map, Locked Decisions, Oracle findings when Stage 3.5 surfaced any,
Deferred Ideas, Risks Accepted, and Canonical References.
Then call `AskUserQuestion` (header `Lock all?`):
1. `Lock all and run on auto mode (Recommended)`: sets `AUTO_MODE = true`, auto-resolves the remaining flow gates,
and chains into `/ac:execute --auto` at Stage 6. The default once decisions are locked, because the interview and
the Stage 5.5 reviewer already carry the quality bar.
2. `Lock all and proceed step-by-step`: write the plan, run the review, then stop and let the user run execute.
3. `Revise a decision`: loop back to Stage 3 targeting one node.
4. `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>
```
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.
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.
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 `Edit` before Stage 6. These are the ones that make a step unexecutable by a
fresh agent: a reference that does not resolve, a step whose `Done when` cannot be satisfied by its
`Files`, an internal contradiction between two steps.
- **IMPORTANT**: fix it when the fix is small and local. Otherwise record it in the plan's
`## Deferred Ideas` with one line naming what was deferred and why.
- Anything else goes in `## Deferred Ideas` or 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.
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
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"` and `args: "<slug> --auto"`, and keep going in the same turn until
execute reaches its own terminal state or a BLOCKER halts it.
When `AUTO_MODE = false`, end the turn after the summary. The user reviews the plan and runs execute themselves.
<reminders>
- Reach every candidate yourself by the cheapest tool that settles it, and verify subagent claims before they move a decision (Stage 2a.1).
- Route every question through the three-way test; every load-bearing decision ends locked, deferred, or risk-accepted.
- The reviewer receives a path and nothing else, runs once, and returns findings rather than a verdict. Fix CRITICAL with `Edit`, defer the rest.
- Do not invoke `/ac:execute` when `AUTO_MODE = false`. The user reviews the plan first.
</reminders>