auto-plan

name	auto-plan
description	Turn an approved spec into ordered slices. Use when framing is accepted and planning begins.
metadata	{"stage":"plan"}

auto-plan

Planning controller. Turns approved framing into ordered slices with verification commands.

First action: run node .agent/.automaton/scripts/get-context.mjs from the project root.

Preamble

auto-plan builds the smallest plan that makes execution safe while preserving the approved scope. It does not write code or broaden scope beyond the approved spec.

Loading discipline: hold SPEC.md, review state, and source files needed for accurate slices. Read wider project files when understanding existing code informs slice boundaries or verification commands. Read .agent/.automaton/references/CONTEXT-BUDGET.md when wider reads threaten context pressure. When a lookup would otherwise pull wide reads into context, dispatch the read-only automaton-librarian (see .agent/.automaton/references/LIBRARIAN.md): it returns evidence, you keep the decision.

Artifact discipline: PLAN.md is the reloadable execution index, not the whole implementation dossier. Keep PLAN.md compact enough to re-read. For large coherent work, summarize slices in PLAN.md and link optional detail files under .agent/work/<change>/slices/. Split only for independent outcomes, not because one coherent plan has many requirements.

Quality Gate

Before finalizing PLAN.md:

• Give every material slice a concrete output.
• Attach a verification command to every material slice.
• Name the execution topology: default continuation path, explicit checkpoints, subagent routes, and any parallel-safe groups.
• Remove vague tasks that do not define done.
• Read references/quality.md when the plan leaves execution decisions to the implementer.

Do

Context Loading

Load the canonical SPEC.md, linked spec detail that carries normative requirements, relevant DESIGN.md, and source files needed to choose slice boundaries, dependencies, and verification commands. Do not ignore linked spec/*.md files when they contain requirement IDs, gap IDs, invariants, audit questions, migration checkpoints, coverage targets, or acceptance detail.

Read .agent/wiki/LEARNINGS.md when it exists: one-line facts earlier changes paid to learn, often constraints slices must respect.

Assess Review State (if reviews exist)

If engineering_review exists in current.json for this change, this is a re-plan: read ## Review: Engineering in the prior PLAN.md and address each correction and approved_with_risks risk in the revised plan.

If the engineering approach is complex or risky, recommend auto-eng-review before execution.

If SPEC.md contains content fields or produces writing, articles, briefs, decks, newsletters, documentation, or proposals, read references/content-planning.md; carry forward channel, source policy, factual risk, and format where they affect execution or verification.

If SPEC.md names requirement IDs, gap IDs, invariants, audit questions, migration checkpoints, or coverage targets, preserve them in PLAN.md and attach them to satisfying slices. Do not collapse traceable requirements into untraceable prose.

Design Slices

Break work into ordered execution units, not topic buckets. Each slice must be:

• Testable: it produces an outcome that can be verified.
• Bounded: it can be executed and verified without loading unrelated slices.
• Independent: it can be executed without loading slices that come after it.
• Checkpointed only for human input: it marks a pause only when a human must act or choose before the next approved slice can start.

Read references/slice-examples.md when uncertain whether a slice is well-designed.

For content slices, also name the artifact target, allowed sources, factual-risk gate, and format constraint so auto-execute does not invent missing context.

Before writing slices, choose the execution topology: serial order, subagent routes, checkpoints, and parallel-safe groups. Continuation is the default after a verified slice; mark a checkpoint only when the agent must pause for human verification, a human decision, or a human action. Parallel-safe means dependencies are independent and write sets are disjoint; default to none. For multi-slice plans, make clear that execution should continue through all approved slices; execution windows are context-management batches, not planned stopping points.

Frame each slice with required fields first, then only the overrides the slice needs:

### Slice N: [Name]

Required:
**Objective:** [one sentence]
**Acceptance criteria:**
- [observable criterion]
**Verification:** [command or check that proves the slice is done]

Defaults, state only when overriding:
**Execution:** direct | subagent recommended | subagent required (default: direct)
**Depends on:** none
**Checkpoint after:** none | human-verify | decision | human-action (default: none)
**Checkpoint reason:** none

Include when useful:
**Touches:** [files, directories, or subsystems]
**Produces:** [specific artifact or state change]
**Detail:** [linked `slices/slice-NNN.md` file]

Rules:

• Every material slice must have a verification command. Verify the exact behavior, not the absence of errors. Include rollback verification for migrations.
• Every material slice must have acceptance criteria; execution cannot verify vibes.
• Use subagent recommended for broad, cross-subsystem, interface, schema, or review-risk work. Use subagent required only for user-requested multi-agent execution or security-critical, production-data, or irreversible-state changes.
• Continuation is the default. Omitted slice fields carry the defaults pinned in .agent/.automaton/references/ARTIFACT-LIFECYCLE.md (Slice Defaults).
• Checkpoint types are defined once in .agent/.automaton/references/ARTIFACT-LIFECYCLE.md (Checkpoint Semantics). Assign a checkpoint only when its definition holds; default to none.
• Keep slices small enough for one session. Move extended instructions to slices/slice-NNN.md; split only for independent outcomes.

Do NOT write PLAN.md if:

• SPEC.md is missing or unreadable.
• The scope is still ambiguous after reading SPEC.md.

If any of these are true, recommend auto-frame and stop.

Write PLAN.md

Write the plan to .agent/work/<change>/PLAN.md.

Core sections (always present):

• Goal: one-line bounded goal or SPEC.md pointer; do not mirror the full SPEC text.
• Ordered slice sequence: dependency order, with linked detail files when needed.
• Execution routing and topology: default continuation path, explicit overrides/checkpoints, and a Parallel-safe groups: line set to none or the slice groups.
• Per-slice verification: one verification command inline on every material slice.

Conditional sections appear only when their trigger applies; omit or mark "n/a" otherwise:

• Architecture approach: introduces a new pattern, non-obvious decision, or cross-system integration. Name the contestable decisions and their tradeoffs plainly; a review can only bite what the plan states. Omit when the design is obvious from SPEC.
• Requirement traceability: SPEC names gap IDs, invariant IDs, audit questions, migration checkpoints, or coverage targets. Omit when the SPEC has no traceable IDs.
• Aggregate verification commands table: ≥ 3 slices or commands not captured per-slice. Per-slice inline suffices for smaller plans (index over transcript).

Apply the Artifact Signal Discipline rules from .agent/.automaton/references/FRAMEWORK.md while writing. Preserve existing ## Review: sections on re-run. Review skills replace their own sections.

Write DESIGN.md (if it earns existence)

Write .agent/work/<change>/DESIGN.md only when all three hold: the decision is hard to reverse, a future reader would be surprised without context, and it resolved a real trade-off between genuine alternatives. Any one missing means the rationale lives in PLAN.md prose. Keep it under 200 lines so it stays a reloadable contract rather than a dossier.

Update State

Run node .agent/.automaton/scripts/sync-status.mjs --canonical-plan ".agent/work/<change>/PLAN.md" --stage plan from the project root. Add --canonical-design ".agent/work/<change>/DESIGN.md" when DESIGN.md was written.

Output

• PLAN.md: written to .agent/work/<change>/PLAN.md
• DESIGN.md: written to .agent/work/<change>/DESIGN.md (if needed)
• .agent/.automaton/state/current.json: records canonical_design (when written), canonical_plan, and stage: plan through sync-status.mjs
• Handoff (always stops): Next: auto-eng-review (optional review) or Next: auto-execute.

Rules

• Prefer the smallest correct design.
• Remove placeholders instead of preserving them.
• Do not broaden scope to cover hypothetical future work.
• Preserve review sections on refresh unless the user explicitly requests consolidation.
• Every material slice must have acceptance criteria and an explicit verification command.