Deep Planning

Multi-session planning workspace generator. Turns a too-big problem into a planning/ folder with per-component stubs, then provides a guided deep-dive flow across recurring sessions until the plan is buildable.

When to use

• A problem is too complex to plan end-to-end in one session
• A scoping doc exists but the next step is decomposition + deep design, not execution
• Returning to an in-progress planning workspace and need to know what to tackle next
• Wrapping a planning session and need clean handoff notes for next time

When to use spec-creator DESIGN mode instead (the seam)

If the work is one buildable automation / app / backend that can be designed in a single session (30 to 60 min), it does not need a multi-session planning workspace. Use the spec-creator skill's DESIGN mode: a collaborative, evidence-driven facilitation (output-first, prove-with-subagents, fail-first FMEA) that produces one spec. deep-planning sits above that: it is for problems too big for one session, and it decomposes a large system into components. Each component that is itself a buildable automation can be handed down to spec-creator DESIGN mode for its own spec.

QUICK mode vs. the other single-session options. QUICK (below) is the upstream reasoning step: a single-session first-principles pass that decides what the right thing even is and writes an execution-ready doc. It sits before the seam, not on it. The three near neighbours, kept distinct:

• spec-creator DESIGN produces a build spec for software. QUICK is upstream of it: QUICK's doc is often the input you hand to DESIGN (or to meta-builder) to execute.
• The action-plan skill sequences a thing you've already decided on. QUICK is where the deciding happens; if all that's left is ordering known steps, use action-plan instead.
• Full INIT is for problems too big for one session. QUICK is the opposite: one-session-sized, closed out today, no workspace.

Use QUICK when the problem is one-session-sized but you need to think it through before acting. Common downstream: skill / primitive restructuring, a process redesign, a focused refactor.

Operating stance

Two rules apply in every mode:

• First principles + simplicity. Before proposing a decomposition, choosing between options, or compiling steps - decompose to irreducibles, name assumptions, and justify each added layer of complexity against a concrete near-term use. Default to the simplest thing that satisfies the constraint. See PATTERNS.md - First principles & simplicity.
• ASCII diagrams for structural questions. Component dependency graphs, phase/flow ordering, and build sequences render as inline ASCII (monospace-safe, under 80 chars wide, labeled arrows, one-line caption). Prose is the default; diagrams earn their place when the reader needs to see shape at a glance. See PATTERNS.md - ASCII diagrams.

Modes

Mode Detection

If the user passes a positional argument (quick, init, guide, dive, extend, status, done, ship) treat it as authoritative.

Otherwise infer from intent:

• "think this through", "reason through", "quick plan", "help me decide what to do about X", one-session-sized problem to figure out before acting → quick
• "set up", "scope this", "this is too big", "decompose" → init
• "continue planning", "what's next", "next component", no specific component named → guide
• "deep-dive {N}", "let's tackle component {N}" → dive
• "add a component", "add a track", "extend this plan", "reopen X", "add to a finished/shipped project" → extend
• "where are we", "status", "progress overview" → status
• "wrap up", "close out", "session done", "log this session" → done
• "ready to build", "compile the plan", "ship to implementation" → ship
• Ambiguous → ask which mode.

Then load the matching modules/MODE-{NAME}.md and execute.

Project index & slug resolution

A master register of all planning projects lives at:

workspace/_system/_planning-index.md

Created automatically by INIT (or any mode that needs it) if absent. Every mode except INIT accepts an optional project slug as the final positional arg:

/deep-planning guide leads-supabase-migration
/deep-planning dive 01 leads-supabase-migration
/deep-planning status agentic-campaign-pipeline
/deep-planning done
/deep-planning ship leads-supabase-migration

Resolution rules (apply to guide / dive / extend / status / done / ship):

1. Slug provided → look up the project's planning folder via the index and operate on that workspace.
2. No slug + only one Active project → use it silently.
3. No slug + multiple Active projects → list them from the index and ask which.
4. No slug + zero Active projects → tell the user No active planning project. Run /deep-planning init to create one, or pass a slug from the Shipped section.

EXTEND exception: its REOPEN sub-operation targets a project in the Planned or Shipped section, not Active. For extend, resolve the slug with index.py find {slug} (which scans every section) rather than path (Active-only), so a sealed project can be found and reopened.

Index file shape:

• ## Active - projects with ⚪ / 🟡 components. Cols: slug, project, depth, status, progress, last session, next up, path.
• ## Queued (not yet initialized) - placeholders before INIT runs. Cols: slug, project, notes.
• ## Shipped - projects whose implementation/ is ready. Cols: slug, project, depth, shipped date, path (with both planning + implementation links).
• ## Archived - abandoned or superseded projects.

All modes use scripts/index.py to read/write this file - never parse the markdown table inline. Common operations:

# Get the planning folder for a slug (mode resolution)
uv run ~/.claude/skills/deep-planning/scripts/index.py path {slug}

# List Active project slugs (for disambiguation prompts)
uv run ~/.claude/skills/deep-planning/scripts/index.py active-slugs

# Show the whole index (used by STATUS no-args)
uv run ~/.claude/skills/deep-planning/scripts/index.py list

# Ensure the index exists (INIT calls this first)
uv run ~/.claude/skills/deep-planning/scripts/index.py ensure-exists

# Append a new project to Active (INIT)
uv run ~/.claude/skills/deep-planning/scripts/index.py add-active --slug {S} --project {P} --depth {D} --components {N} --path {PATH} --next-up "{Q}"

# Update an Active row (GUIDE / DIVE / DONE)
uv run ~/.claude/skills/deep-planning/scripts/index.py update {slug} --status {⚪|🟡|🟢} --progress "X / N" --last-session YYYY-MM-DD --next-up "{Q}"

# Move Active → Shipped (SHIP)
uv run ~/.claude/skills/deep-planning/scripts/index.py ship {slug} --shipped YYYY-MM-DD --implementation-path {PATH}

The script auto-detects the workspace root by walking up from CWD looking for workspace/_system/. Pass --workspace-root PATH to override.

Output convention

All active planning workspaces live at:

workspace/_system/deep-planning/{YYYY-MM-DD} - {project-slug}/planning/

This path is relative to the current working directory's workspace - the project you were invoked from - NOT any other workspace. Each workspace keeps its own workspace/_system/deep-planning/ and its own workspace/_system/_planning-index.md. Resolve the root by walking up from CWD to the nearest folder containing workspace/ (or that already has a workspace/_system/); write there. Do not redirect a planning workspace into a different project's _system/ just because that other workspace already holds planning projects or "feels like the hub" - colocating planning with the project it belongs to is the whole point. If CWD has no workspace/ dir yet, create workspace/_system/deep-planning/ under the current project root; never reach into a sibling or parent project. When calling scripts/index.py, pass --workspace-root pointing at the current project root if CWD-walking would land on the wrong workspace.

When SHIP finalizes a project (everything 🟢, all tracks compiled), the entire project folder is moved into the [DONE]/ subfolder:

workspace/_system/deep-planning/[DONE]/{YYYY-MM-DD} - {project-slug}/

The date is the day INIT was run; never overwritten on subsequent sessions or on the move to [DONE]/.

This is enforced - never write a planning workspace anywhere else.

QUICK mode is the exception: it is single-session and produces no workspace. Its one doc lives flat at workspace/_system/deep-planning/quick/{YYYY-MM-DD}-{slug}.md, same workspace-resolution rules, but no {date} - {slug}/ project folder, no planning/, and no master-index row.

INIT, GUIDE, DIVE, and DONE also auto-generate a branded planning.html view inside the planning folder via scripts/render_planning.py. The .md files remain the source of truth; the HTML is a regenerated view layer for easier reading.

Folder shape

planning/ is INIT's output, maintained by GUIDE/DIVE/DONE. implementation/ (or implementation-track-{ID}/ for per-track ships) is SHIP's output, sibling to planning/, consumed by build tools.

workspace/_system/deep-planning/
├── {YYYY-MM-DD} - {project-slug}/      # active project
│   ├── planning/                       # decompose + decide (deep-planning's domain)
│   │   ├── 00_INDEX.md                 # roadmap: status, tracks (optional), dependencies
│   │   ├── _template.md                # blank component for adding mid-flight
│   │   ├── _enablers.md                # small in-scope tasks that ship with the project (backfills, migrations, cleanup)
│   │   ├── _spinoffs.md                # orthogonal sub-projects that surfaced; candidates for future planning workspaces
│   │   ├── _sessions/                  # populated by DONE mode (one .md per session)
│   │   │   └── 2026-04-16.md
│   │   ├── 01_{component-slug}.md      # one per identified component
│   │   ├── 02_{component-slug}.md
│   │   └── ...
│   └── implementation/                 # SHIP's output - multi-step build specs
│       ├── 00_BUILD-INDEX.md           # roadmap of build steps + status
│       ├── _template.md
│       └── 01_{step-slug}.md
├── quick/                             # QUICK mode output: one flat doc per session, no workspace
│   └── {YYYY-MM-DD}-{slug}.md
└── [DONE]/                             # projects fully shipped (all tracks compiled)
    └── {YYYY-MM-DD} - {project-slug}/  # same shape as active, just relocated

For track-structured projects, SHIP can compile per-track: each /deep-planning ship --track {ID} produces implementation-track-{ID}/ instead of (or alongside) the default implementation/. The project stays active until every track has shipped.

Planning and implementation are peers: planning decides, implementation executes. The execution itself is done by a separate build tool (e.g., build-os); deep-planning only generates the spec.

Depth tiers

INIT accepts a depth argument that scales the workspace to the problem size. Recorded in the INDEX so GUIDE / DIVE / SHIP read the same setting.

If depth isn't passed, INIT asks once and proposes a recommendation based on the brief (rule of thumb: clear scope + 1 surface = light; multi-surface or unfamiliar = standard; cross-cutting or multi-week = deep). The user can override.

Tracks (optional, for phased shipping)

For projects where some components can ship before others are even planned, INIT can group components into tracks - letter-IDed phases (A, B, C…) each with its own goal and its own SHIP cadence.

When tracks are used:

• Each track has an ID (single uppercase letter), a name, and a one-line goal
• Every component is assigned to exactly one track (track: A in component frontmatter)
• 00_INDEX.md renders components grouped by track
• Dependency edges that cross tracks are flagged in the graph caption (a cross-track dep means the dependent track can't ship until the dependency's track ships)
• /deep-planning ship --track {ID} compiles only that track's components → implementation-track-{ID}/
• The project stays Active in the master index until every track has shipped, at which point the folder moves to [DONE]/ and the row moves to Shipped

The point: ship cheap tracks while expensive ones are still being planned. Today's behavior (no tracks, ship-once) remains the default for everything else.

Enablers and Spinoffs

Two side-channel capture buckets that any DIVE/GUIDE session writes to opportunistically - for things that surface during a component dive but don't belong inside it.

Capture rule. When a "we'll also need to…" comes up mid-dive, decide which bucket it belongs in (in-scope-for-shipping → Enabler; orthogonal future project → Spinoff) and append a one-line row immediately. Don't try to decide it inline; just capture and keep diving. The component file itself stays focused on its key questions and decisions.

STATUS surfacing. Enablers count is shown in the per-project STATUS view (since they ship with the project). Spinoffs are surfaced only at DONE / SHIP time, when promotion decisions are made.

Status taxonomy

Status is manual - set at end of session, not auto-detected. See PATTERNS.md.

Conversation pattern (GUIDE / DIVE)

Both deep-dive modes use the inline-options pattern:

1. Walk through Key questions one at a time (don't dump them all)
2. For structural / flow-shaped questions (3+ moving parts): sketch an ASCII diagram first, then enumerate options that operate on or around it
3. For architecture-shaped questions: state the simplest version that satisfies the constraint before listing options (first-principles check)
4. For each question: present 2-4 options inline as a markdown table or labeled list with a recommended lean and rationale
5. User picks an option, edits one, or writes their own
6. Capture the decision into the component's Decisions section with a one-line rationale
7. New questions surfaced during the dive go to the component's Open section

Full pattern: PATTERNS.md.

Composition

• QUICK ends by handing off to the continue skill (if available in the workspace) to emit a copy-pasteable resume prompt; if continue isn't present, it writes the resume prompt inline. Its execution doc is the input that a fresh session, spec-creator DESIGN, or meta-builder then builds against.
• INIT can call the brainstorming skill as a sub-flow when the problem is fuzzy and component decomposition is non-obvious
• GUIDE / DIVE rely on the inline-options pattern (don't switch to AskUserQuestion - markdown tables in chat work better for comparing options)
• SHIP compiles planning/ into implementation/ - a sibling folder of multi-step build specs. Any build tool (e.g., build-os) reads from implementation/ one step at a time and marks status when each step is complete.
• The full lifecycle: scoping doc → INIT → GUIDE/DIVE/DONE (loop) → SHIP → build tool → working code.

Templates

• templates/00_INDEX.template.md - INIT writes this once; GUIDE/DIVE/DONE update it
• templates/component.template.md - INIT writes one per component; DIVE fills in Decisions
• templates/_enablers.template.md - INIT writes this once (empty); DIVE/GUIDE append rows opportunistically; SHIP reads it
• templates/_spinoffs.template.md - INIT writes this once (empty); DIVE/GUIDE append rows opportunistically; DONE/SHIP review for promotion
• templates/session-log.template.md - DONE writes one per session
• templates/BUILD-INDEX.template.md - SHIP writes this once; the build tool updates step statuses
• templates/step.template.md - SHIP writes one per build step