ai-plan
$
npx mdskill add arcasilesgroup/ai-engineering/ai-plan``` /ai-plan # plan from approved spec /ai-plan --pipeline=hotfix # override classification /ai-plan --skip-design # skip design routing ```
SKILL.md
.github/skills/ai-planView on GitHub ↗
---
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]"
mode: agent
model_tier: opus
mirror_family: copilot-skills
generated_by: ai-eng sync
canonical_source: .claude/skills/ai-plan/SKILL.md
edit_policy: generated-do-not-edit
---
# Plan
## Quick start
```
/ai-plan # plan from approved spec
/ai-plan --pipeline=hotfix # override classification
/ai-plan --skip-design # skip design routing
```
## Workflow
Takes an approved spec and produces a phased execution plan — bite-sized tasks, agent assignments, gate criteria. The plan is the contract `/ai-build` executes. **HARD GATE**: operator must approve before `/ai-build` runs (§10.6 SDD).
1. **Approval gate (HARD STOP, no escape hatch)** — BEFORE reading the spec for decomposition, resolve the active spec's CANONICAL lifecycle state. Read `<spec_id>` from `.ai-engineering/specs/spec.md` frontmatter `spec:` (fallback `slug:`), then run `python .ai-engineering/scripts/spec_lifecycle.py status <spec_id>` to read the sidecar `state`.
- **Sidecar resolves to a known state ≠ `approved`** → HARD STOP. Write NO `plan.md`. Emit exactly:
```
Error: spec-<id> is in '<state>' state.
Complete /ai-brainstorm approval before running /ai-plan.
```
- **No sidecar exists** → fall back to `spec.md` frontmatter `status:`; block (same HARD STOP) unless `status: approved`.
- **Neither sidecar NOR frontmatter `status:` resolves** → this is indeterminate plumbing only (D-161-03): emit a LOUD warning and proceed (fail-open).
- Vocab: sidecar `approved` ⇔ frontmatter `status: approved`. There is NO `--force` / escape hatch — the ONLY bypass is approving the spec via `/ai-brainstorm`.
2. **Read spec** — load `.ai-engineering/specs/spec.md`; flag missing sections per `spec-schema.md`.
3. **Explore codebase** (read-only) — current architecture, patterns, affected files (§10.3 SOLID).
4. **Classify pipeline** — full / standard / hotfix / trivial.
5. **Classify executor route** — write `execution_route` frontmatter: `executor: build` + `safe_next_command: "/ai-build"` for single-concern plans, or `executor: autopilot` + `safe_next_command: "/ai-autopilot"` for multi-concern/large plans. `status` remains the only approval field; draft plans are recommendations only. Emit `framework_operation` detail `operation=execution_routed`.
6. **Design routing** — invoke `handlers/design-routing.md`; capture output at `.ai-engineering/specs/<spec-id>/design-intent.md` under `## Design`. `--skip-design` logs reason and proceeds.
7. **Identify architecture pattern** — read `architecture-patterns.md`; pick a canonical pattern or `ad-hoc`. Record under `## Architecture` BEFORE decomposition.
8. **Decompose into tasks** — bite-sized (2-5 min), single-agent, single-concern, verifiable, ordered. Apply the **exhaustive patch-ready output template** below (D-131-08 / sub-003).
9. **Assign agents** — capability-match (build = code; verify = read-only; guard = advisory).
10. **Order phases** + gate criteria. **TDD pairs** (§10.5): write a RED test task before any GREEN implementation task.
11. **Self-review** (§10.7 Clean Code) — spec-reviewer pattern, max 2 iterations.
12. **Write** to `.ai-engineering/specs/plan.md`, print `safe_next_command`, and **STOP** — operator approves and runs that command.
### Output template — exhaustive patch-ready (D-131-08)
Each task block carries five lines so `/ai-build` can route to the cheap model tier when the work is mechanical:
- `- [ ] T-N — <task title>`
- `- Agent: <build/verify/guard>`
- `- Files: <path/to/file:line>`
- `- Principles applied: §10.x ...` — cite at least one anchor from CANONICAL.md §10 (e.g., §10.3 SOLID, §10.5 TDD, §10.7 Clean Code).
- `- Patch (deterministic):` — include 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>`
Patch hunk present → `/ai-build` dispatches `effort: cheap / model_tier: haiku`. Absent patch 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`, and `safe_next_command`. Do not add `approved`/`approval` under `execution_route`; plan `status` is the approval source of truth.
## Dispatch threshold
Dispatch the `ai-plan` agent for any approved spec needing decomposition. Hand off to `/ai-build` only after explicit user approval. The agent file (`.github/agents/plan.agent.md`) is the interrogator handle; pipeline classification, decomposition rules, and the no-execution protocol live here.
## When to Use
- After `/ai-brainstorm` produces an approved spec.
- When a spec exists but plan.md has placeholder content.
- When re-planning is needed (plan failed, scope changed).
## 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 agent` or `/ai-build` for task execution; MUST NOT modify source code; MUST NOT check off implementation tasks. MAY write `.ai-engineering/specs/plan.md` and run read-only codebase exploration.
## Common Mistakes
- Tasks too large (>5 min) — split them.
- Missing dependencies between tasks.
- Assigning code-write tasks to verify (verify is read-only).
- Not pairing RED/GREEN tasks for TDD.
- Planning implementation details (plan says WHAT, code says HOW).
- Omitting the `Patch (deterministic):` block when the edit is mechanical — costs `/ai-build` the cheap-tier dispatch.
## Examples
### Example 1 — plan from an approved spec
User: "the spec is approved, break it down into a phased plan"
```
/ai-plan
```
Reads `.ai-engineering/specs/spec.md`, runs read-only exploration, decomposes into phases with task assignments + gates, writes `plan.md`, presents for approval.
### Example 2 — re-plan after scope change
User: "scope changed — re-plan from the updated spec"
```
/ai-plan
```
Diffs against the existing plan, regenerates affected phases, preserves completed checkboxes where the task is unchanged.
## 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
More from arcasilesgroup/ai-engineering
- ai-adviseProactive governance advisor — checks standards, decisions, and quality trends during development. Always advisory, NEVER blocks. Three modes: `advise` (post-edit), `gate` (pre-dispatch), `drift` (on-demand decision audit). Trigger for 'governance check', 'advise on this change', 'check for drift', 'is this aligned with active decisions', 'shift-left advisory'. Not for blocking gates — use /ai-verify. Not for narrative code review — use /ai-review.
- ai-analyze-permissionsUse when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot, Antigravity, or Codex.
- ai-animationDesigns motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'gesture design', 'swipe to dismiss', 'easing for this', 'stagger the'. Not for design systems; use /ai-design instead. Not for visual art; use /ai-visual instead. Not for testing animation code; use /ai-test instead.
- ai-autopilotDelivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. Trigger for 'implement spec-NNN end to end', 'autopilot this', 'autonomous delivery', 'decompose and ship', 'run the backlog', 'execute these GitHub issues', 'process the sprint backlog'. Invocation is the approval gate. Not for small or single-concern tasks; use /ai-build instead. Not for ambiguous requirements; use /ai-brainstorm first.
- ai-boardOperates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.
- ai-brainstormForces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. Trigger for 'lets add X', 'how should we handle Y', 'whats the best approach', 'I am thinking about', 'what should we build for'. Not for existing approved specs; use /ai-plan instead. Not for execution; use /ai-build instead.
- ai-branch-cleanupCleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.
- ai-buildCanonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop with one bounded quality-remediation pass on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead. Not for a single function or subcomponent; use /ai-code.
- ai-codeWrites production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Not for tests; use /ai-test instead. Not for debugging; use /ai-debug instead. Not for refactoring; use /ai-simplify instead. Not for executing an approved plan end-to-end; use /ai-build (the gateway).
- ai-commitRuns the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.