| name | ai-plan |
| description | Decomposes an approved spec into a phased execution plan with bite-sized tasks, agent assignments, and gate criteria — the contract /ai-build executes. Trigger for 'break this down', 'create a plan', 'what tasks do we need', 'lets start implementing', 'scope changed re-plan'. Hard gate: user approves before /ai-build can run. Not for ambiguous requirements; use /ai-brainstorm instead. Not for execution; use /ai-build instead. |
| effort | high |
| argument-hint | [spec-NNN or topic] |
| model_tier | opus |
| mirror_family | antigravity-skills |
| generated_by | ai-eng sync |
| canonical_source | .claude/skills/ai-plan/SKILL.md |
| edit_policy | generated-do-not-edit |
Plan
Decomposes an approved spec into a phased, patch-ready execution plan — the contract /ai-build executes. HARD GATE: operator approves before /ai-build runs.
/ai-plan # plan from approved spec
/ai-plan --pipeline=hotfix # override classification
/ai-plan --skip-design # skip design routing
Workflow
Principles: §10.6 SDD (approved spec is the contract), §10.3 SOLID (single-concern tasks), §10.5 TDD (RED before GREEN), §10.7 Clean Code (self-review).
- Approval gate (HARD STOP, no escape hatch) — before decomposing, resolve the spec's CANONICAL state. Read
<spec_id> from .ai-engineering/specs/spec.md frontmatter spec: (fallback slug:); run python .ai-engineering/scripts/spec_lifecycle.py status <spec_id>.
- Read spec — load
spec.md; flag missing sections per spec-schema.md.
- Explore (read-only) — current architecture, patterns, affected files.
- Classify pipeline — full / standard / hotfix / trivial (table below).
- Classify executor route — write
execution_route frontmatter: executor: build + safe_next_command: "/ai-build" for single-concern, or executor: autopilot + safe_next_command: "/ai-autopilot" for multi-concern/large. status stays the only approval field; drafts are recommendations. Emit framework_operation detail operation=execution_routed.
- Design routing — invoke
handlers/design-routing.md; capture at .ai-engineering/specs/<spec-id>/design-intent.md under ## Design. --skip-design logs reason + proceeds.
- Identify architecture pattern — read
architecture-patterns.md; pick a canonical pattern or ad-hoc; record under ## Architecture BEFORE decomposition.
- Decompose into tasks — bite-sized (2-5 min), single-agent, single-concern, verifiable, ordered; apply the patch-ready template below (D-131-08 / sub-003).
- Assign agents — capability-match (build = code; verify = read-only; guard = advisory).
- Order phases + gates — TDD pairs: a RED test task before any GREEN implementation task.
- Self-review — spec-reviewer pattern, max 2 iterations.
- Write + STOP — write
.ai-engineering/specs/plan.md, then emit the 6-field value block (Bottom line / Why it matters / What's done / Risk / Next / Details) per .ai-engineering/reference/value-lens.md at the resolved audience level (default full) alongside the safe_next_command, and STOP — operator approves and runs that command. The safe_next_command string itself stays a carve-out (exact, machine-runnable).
Re-plan (plan failed / scope changed, or plan.md holds placeholder content): diff against the existing plan, regenerate affected phases, and preserve completed checkboxes where the task is unchanged.
Output template — patch-ready (D-131-08)
Each task block carries five lines so /ai-build can route mechanical work to the cheap tier:
- [ ] T-N — <task title>- Agent: <build/verify/guard>- Files: <path/to/file:line>- Principles applied: §10.x ... — cite ≥ 1 CANONICAL §10 anchor (e.g. §10.3 SOLID, §10.5 TDD, §10.7 Clean Code).- Patch (deterministic): — a unified-diff hunk when the edit is mechanical (rename, copy, frontmatter add); omit and add prose only when judgment is required.- Gate: <test/check>
Routing: patch present → effort: cheap / model_tier: haiku; patch absent or synthesis hint → effort: mid / model_tier: sonnet; operator --max-effort → effort: high / model_tier: opus.
Plan frontmatter MUST include execution_route.version, spec, executor, automation, concern_count, estimated_files, reason, safe_next_command. Do NOT add approved/approval under execution_route; plan status is the approval source of truth.
Pipeline classification
| Pipeline | Trigger | Steps |
|---|
full | New feature, refactor, >5 files | discover, architecture, risk, test-plan, spec, dispatch |
standard | Enhancement, 3-5 files | discover, risk, spec, dispatch |
hotfix | Bug fix, security patch, <3 files | discover, risk, spec, dispatch |
trivial | Typo, comment, single-line | spec, dispatch |
No-execution protocol
/ai-plan is planning-only. MUST NOT invoke ai-build / /ai-build, modify source, or check off implementation tasks. MAY write plan.md and run read-only exploration. Dispatch the ai-plan agent (.agents/agents/ai-plan.md, the interrogator handle) for any approved spec needing decomposition; hand off to /ai-build only after explicit approval.
Common mistakes
- Planning HOW instead of WHAT.
- Omitting the
Patch (deterministic): block on mechanical edits — costs /ai-build the cheap-tier dispatch.
Examples
User: "the spec is approved, break it down into a phased plan"
/ai-plan
Reads spec.md, runs read-only exploration, decomposes into phases with agent assignments + gates, writes plan.md, emits the value block, and STOPs for approval.
Integration
Called by: user directly, post-/ai-brainstorm approval. Calls: ai-explore agent (codebase context). Transitions to: /ai-build (only after user approves). See also: /ai-brainstorm, /ai-build, /ai-autopilot (multi-concern alternative).
$ARGUMENTS
