plan

name	plan
description	Implementation plan — tasks, agents, file groups, dependencies. Triggers: "plan" | "plan this" | "implementation plan" | "break it down" | "plan this feature" | "how should we build this" | "make a plan" | "create a plan" | "break this down into tasks" | "task breakdown".

Plan

Success

I := π written ∧ ## Task IDs section ∃ V := ls artifacts/plans/{N}-*.md* ∧ grep "## Task IDs" artifacts/plans/{N}-*.md*

Let: σ := spec artifact π := plan artifact at artifacts/plans/{issue}-{slug}.md τ := tier ∈ {S, F-lite, F-full}

Spec → micro-tasks → agent assignments → plan artifact.

Flow: single continuous pipeline. ¬stop between steps. Decision response → immediately execute next step. Stop only on: Cancel/Abort or Step 6 completion.

/plan --issue 42         Generate plan from spec for issue #42
/plan --spec path        Generate plan from explicit spec path
/plan --issue 42 --audit Show reasoning checkpoint before planning

Pipeline

Step	ID	Required	Verifies via	Notes
1	locate-spec	✓	σ ∃	—
2	plan	✓	τ + agents defined	—
3	refs	—	ref paths noted	—
4	micro-tasks	—	tasks ∃ in π	Tier F only
5	write	✓	π ∃	—
6	approve	✓	git log shows commit	gate

Pre-flight

Success: π written ∧ ## Task IDs section ∃ Evidence: grep "## Task IDs" artifacts/plans/{N}-*.md* Steps: locate-spec → plan → refs → micro-tasks → write → approve ¬clear → STOP + ask: "Do you have a spec to plan from?"

Step 1 — Locate Spec

--issue N → ls artifacts/specs/N-*.md* → read full → extract title, criteria, files. --spec <path> → read directly. ¬found → suggest /spec or /dev. Stop.

Pre-flight: Ambiguity Check

Grep \[NEEDS CLARIFICATION in σ (count). count > 0 → present choice Resolve now | Return to spec | Proceed anyway

Step 2 — Plan

Read ${CLAUDE_PLUGIN_ROOT}/references/dev-process.md + σ.

Step 2a-pre — Reasoning Audit (optional)

--audit → after reading σ, present reasoning audit per reasoning-audit.md (plan guidance). → present choice Proceed | Adjust approach | Abort ¬--audit → continue to Step 2a.

2a. Scope: Glob + Grep → files to create/modify + reference features for patterns.

2b. Tier: S | F-lite | F-full per dev-process.md. ∃ artifacts/frames/ ∧ tier field → use it. Else assess from σ complexity.

2c. Agents:

Path prefix	Agent
{frontend.path}, {shared.ui}	frontend-dev
{backend.path}, {shared.types}	backend-dev
{shared.config}, root configs	devops
docs/	doc-writer

Paths from stack.yml. ¬set → file domain heuristics (component/hook → FE; service/controller/route → BE).

Always: tester. Add: architect (new modules), security-auditor (auth/validation), doc-writer (new APIs). τ=S → skip agent assignment (single session).

Intra-domain parallel: ≥3 independent tasks in 1 domain → multiple same-type agents (F-lite ∧ F-full). Shared barrel files → merge into single agent.

Subject-surface cap (per instance): ∀ agent instance, tag each task with 1 subject (e.g. auth, cache, http, migrations, parser, dispatch). Distinct subjects per instance > 2 → force-split into a new instance (backend-dev-A → backend-dev-A + backend-dev-B). Reason: instance ≈ session ≈ context window — too many surfaces dilute focus and tail-degrade output.

2d. Tasks: ∀ task: description, files, agent, dependencies, parallel-safe (Y/N). Order: types → backend → frontend → tests → docs → config.

Budget heuristic (ops estimate): After listing tasks, classify each by cost class and compute estimated tool-call ops. Record in the plan artifact's Wave Structure section as a Budget Table.

Cost classes:

Class	Ops/item	Examples
trivial	1–2	string replace, single grep
bounded	2–3	read + edit known file
judgmental	4–6	read + context + judge + edit
exploratory	8–15	open-ended cross-file search

Rules:

1. Per-task cap: estimated_total_ops > 50 for a task → force-split the task into smaller sub-tasks, or present a user choice Split now | Keep as-is (flag) decision before proceeding.
2. Per-instance cap: after agent_instance assignment, aggregate ops per instance. Σ ops/instance > 50 OR |tasks/instance| > 4 OR distinct subjects/instance > 2 → force-split into a new instance (backend-dev-A → backend-dev-A + backend-dev-B). This catches the case where each task is small but stacking 6 tasks on one agent overflows its context.

2e. Slice Selection (multi-slice only): ≥2 slices → present multi-select 1 option/slice V{N}: {desc} ({files}, {agents}). Default: next unimplemented slice. Respect deps. Re-run /plan for remaining.

2f. Present Plan: → present choice τ, slices, files, agents, tasks with [parallel-safe: Y/N]. Options: Approve | Modify | Cancel Approve → immediately continue to Step 3 (¬stop).

Step 3 — Ref Patterns

Find similar existing feature → read 1–2 files for conventions. Store paths → note in π for Step 4 agent context injection.

Step 4 — Micro-Tasks (Tier F only)

τ=S → skip → Step 5. Read references/micro-tasks.md for complete process.

Summary: Detect σ format (Breadboard+Slices ∨ Success Criteria) → generate micro-tasks with verify commands → detect parallelization → scale task count → consistency check (σ↔tasks bidirectional) → write to π.

Key outputs: micro-tasks with fields below, [P] parallel markers, RED-GATE sentinels per slice.

See references/micro-task-example.md for a worked example.

Micro-Task Fields

Field	Description
Description	Imperative, specific
File path	Target file
Code snippet	Expected shape skeleton
Verify command	Bash confirmation
Expected output	Success criteria
Time estimate	2–5 min (up to 8–10 for atomic ops)
[P] marker	Parallel-safe
Agent	Owner
Agent instance	Named owner (backend-dev-A, tester-B, ...)
Subject	1-word surface tag (auth, cache, http, parser, …) — used for per-instance subject-diversity cap
Spec trace	SC-N ∨ U1→N1→S1
Slice	V1, V2, ...
Phase	RED ∨ GREEN ∨ REFACTOR ∨ RED-GATE
Difficulty	1–5

Step 5 — Write Plan Artifact

Generate architecture sidecars per forge-chart-sidecar.md before writing π.

Write to artifacts/plans/{N}-{slug}-plan.md. Create artifacts/plans/ dir if needed.

Use references/plan-template.md. See references/micro-task-example.md for task formatting.

---
title: "Plan: {title}"
issue: {N}
spec: artifacts/specs/{N}-{slug}-spec.md
complexity: {score}/10
tier: {τ}
generated: {ISO}
---

Include:

• Summary (1–2 sentences)
• Architecture sidecars (forge-chart, see below)
• Bootstrap Context (from analysis if ∃, omit if ¬∃)
• Agents table (agent, task count, files)
• Wave Structure table (see below)
• Consistency Report (covered/total, uncovered, untraced, exemptions)
• Micro-Tasks (grouped by slice/criteria, with RED-GATE sentinels)
• Task Seeding Blueprint (see below)

Forge-Chart Sidecars

Read forge-chart-sidecar.md before generating visuals.

## Architecture must include:

1. Data flow sidecar — {N}-{slug}-data-flow.html (fd-engine architecture): full pipeline — config → loaders → data structures → composition → runtime. Group by file via zones.
2. File × Function map sidecar — {N}-{slug}-file-map.html (fd-engine architecture): functions/classes per file, call edges; test files as consumers.

Link in π (¬inline mermaid, ¬ASCII):

**Data flow:** [{title}](../visuals/{N}-{slug}-data-flow.html)
**File map:** [{title}](../visuals/{N}-{slug}-file-map.html)

Sidecars go AFTER Summary, BEFORE Bootstrap Context.

Wave Structure

After micro-tasks, derive waves from the dependency graph. Name parallel agent instances (tester-A/B, backend-dev-A/B/C, devops-A/B) so /implement can spawn distinct agents per wave. Include this table in π:

## Wave Structure

{N} waves, max {K} parallel agents. Elapsed ~{X} weeks vs ~{Y} sequential.

| Wave | Trigger | Agents | Tasks |
|------|---------|--------|-------|
| 1 | start | {K} ∥ | {agent-A}: T{n} · {agent-B}: T{m} |
| 2 | Wave 1 done | {K} ∥ | ... |

After the wave table, include a Budget Table derived from Step 2d classification — both per-task AND per-instance rollups:

### Budget — per task

| Task | Items | Class | Est. ops | Split? |
|------|-------|-------|----------|--------|
| {task name} | {N} | {class} | {ops} | — |
| {large task} | {N} | exploratory | {ops} | YES — split required |

**Total estimated ops: {total}**

### Budget — per agent instance

| Instance | Tasks | Σ ops | Subjects | Split? |
|----------|-------|-------|----------|--------|
| backend-dev-A | T1, T2, T3 | 18 | auth, sessions | — |
| backend-dev-B | T4, T5, T6, T7, T8 | 36 | cache, http, rate-limit | YES — \|tasks\|=5 > 4 ∧ subjects=3 > 2 |
| tester-A | T9, T10 | 12 | auth | — |

Tasks marked YES — split required (either table) must be resolved (split or DP-approved) before the plan is finalized. Per-instance fails dominate: a single agent loaded with too many distinct subjects must be split even if each individual task is small.

Rules:

• Wave 1 = all tasks with no deps.
• Wave N = tasks whose deps are all in earlier waves.
• Tasks chained within a wave (A→B) on one agent instance → note as T{n}→T{m} in the Tasks column.
• Include total elapsed estimate vs sequential.

Task Seeding Blueprint

After ## Wave Structure, include a ## Task Seeding Blueprint section in π. This is the machine-readable input for /implement task seeding.

## Task Seeding Blueprint

<!-- Used by /implement to seed TaskCreate calls on session start.
     Format: T{n} | agent-instance | blockedBy | subject
     blockedBy refs T-numbers within this list (not session task IDs).
     Agent instances are named (tester-A/B, backend-dev-A/B/C, devops-A/B)
     so parallel tasks map to distinct spawned agents.
     Seed in wave order; within a wave all rows are parallel (∥). -->

### Wave 1 — no deps, {K} agents ∥

| Task | Agent instance | blockedBy | Subject |
|------|---------------|-----------|---------|
| T1 | tester-A | — | {subject} |
| T2 | backend-dev-A | — | {subject} |

### Wave 2 — after Wave 1, {K} agents ∥

| Task | Agent instance | blockedBy | Subject |
|------|---------------|-----------|---------|
| T3 | devops-A | T2 | {subject} |
| T4 | tester-A | T3 | {subject} |

Rules:

• One row per micro-task (including RED-GATE sentinels).
• blockedBy = comma-separated T-numbers (within this blueprint, ¬task IDs).
• agent-instance = named instance; same instance = same agent session in /implement.
• Tasks that chain sequentially on the same agent instance (T11→T12) still get separate rows.
• Wave heading comment states the trigger condition so /implement knows when to start each wave.

Step 6 — Approve + Commit

→ present choice complexity, τ, task count, agents, consistency, slices. Options: Approve | Modify | Return to spec

On Approve → immediately continue to 6a (seed tasks), 6b (persist IDs), 6c (commit). ¬stop between substeps.

Step 6a — Seed Claude Code Tasks

∀ micro-task in π — use the canonical schema from plan-task-schema.md (SSoT for TaskCreate shape + blockedBy wiring).

Cache returned id in {task# → task.id} map.

τ=S → still seed tasks (3–6 is typical). Skip wave/blueprint wiring when π has no slice structure.

Step 6b — Persist Task IDs in Artifact

Append a ## Task IDs section to π before committing:

## Task IDs

<!-- Generated by /plan. Used by /implement to resume tasks on session restart. -->
- T1: {task_id} — {subject}
- T2: {task_id} — {subject}
...

This lets /implement re-attach to tasks after a session restart (TaskList would return empty for new sessions).

Step 6c — Commit

git add artifacts/plans/{N}-{slug}-plan.md artifacts/visuals/ + commit per CLAUDE.md Rule 5.

→ Then Exit — approval lands on a compact pause (recommend /compact before /implement), ¬auto-chain. See Exit.

Edge Cases

Read references/edge-cases.md.

Safety

1. ¬git add -A ∨ git add . — specific files only
2. ¬create issue without user approval
3. Always present plan (2f) before writing artifact
4. Show full task list (¬truncate) when |tasks| > 30

Chain Position

• Phase: Build
• Predecessor: /spec (artifact: artifacts/specs/{N}-{slug}-spec.md)
• Successor: /implement (via compact pause — /dev Step 8b; ¬auto-chain for F-lite/F-full)
• Class: gate (user approval of plan artifact required) → pause (compact recommendation before /implement)

Task Integration

• /dev owns the dev-pipeline task lifecycle externally
• This skill does NOT update its own dev-pipeline task
• Sub-tasks created: plan-tasks (one per micro-task, kind: "plan-task") via Step 6a, IDs persisted in artifact's ## Task IDs section (Step 6b)

Exit

/plan runs only for τ ∈ {F-lite, F-full} (τ=S skips plan) → approval always lands on a compact pause before /implement.

• Approved via /dev: run Steps 6a/6b/6c (seed tasks, persist IDs, commit) → return silently. ¬ask "proceed to /implement?". /dev re-scans → Step 8b compact pause (¬auto-chain): recommends /compact then /implement (or /dev #N) and stops the turn.
• Approved standalone: print the compact recommendation + stop:

  ✓ Plan approved — {n} tasks seeded + committed.
    Recommended: /compact → then /implement --issue {N}  (/dev #{N} ≡ /implement #{N})
  

• Modify requested: loop in-skill, re-present.
• Rejected/aborted: return → /dev marks task cancelled.

$ARGUMENTS