deep-plan

deep-plan

A personal Claude Code skill for deep, co-authored planning of non-trivial work. It fans research three ways in parallel, surfaces every meaningful sub-decision as a multi-option AskUserQuestion, runs targeted deep web research per chosen option, runs an adversarial critique pass that tries to refute the plan before you approve it, and produces an AI-consumable plan file inside your repo. A companion /deep-plan:deep-plan-execute command then turns that plan into real harness tasks and drives a test-first implementation loop.

The user is a co-author of the plan, not a reviewer. The skill never silently picks between meaningful options. A depth: argument scales how hard it works, from a quick single pass to an exhaustive multi-wave run.

Workflow

flowchart TD
    Start(["/deep-plan [optional slug hint]"]) --> P0
    P0[Phase 0: Bootstrap<br/>git toplevel, plans_dir, session state,<br/>stale-draft detection]
    P0 --> P1[Phase 1: Parallel Triangulation]
    P1 --> A1[dp-explore-codebase<br/>haiku, parallel]
    P1 --> A2[dp-research-shallow<br/>haiku, parallel]
    P1 --> A3[dp-source-ingest<br/>sonnet, conditional]
    A1 --> CP1
    A2 --> CP1
    A3 --> CP1
    CP1{Checkpoint 1<br/>scope confirm via AskUserQuestion}
    CP1 -->|reframe| P1
    CP1 -->|confirm| P2
    P2[Phase 2: Decision Surfacing<br/>draft plan born, decisions appended live,<br/>sequential AskUserQuestion in dependency order]
    P2 --> P3[Phase 3: Targeted Deep Research<br/>parallel, capped at 4]
    P3 --> A4[dp-research-deep<br/>sonnet, one per decision branch]
    A4 --> P3a{contradiction?}
    P3a -->|yes, re-ask| P2
    P3a -->|no| P4
    P4[Phase 4: Synthesis & Verification<br/>perspective fan-out + sandbox POCs]
    P4 --> A5[dp-plan-perspective<br/>inherit, parallel up to 3]
    A5 --> P46[Phase 4.6: Adversarial critique]
    P46 --> A6[dp-plan-critic<br/>inherit, refutes the plan]
    A6 --> P46d{material gaps?}
    P46d -->|fix inline| P4
    P46d -->|reverses a decision| P2
    P46d -->|clean| CP2
    CP2{Checkpoint 2<br/>walk plan via AskUserQuestion,<br/>THE approval gate}
    CP2 -->|refine task| P4
    CP2 -->|change decision| P2
    CP2 -->|approve| P5[Phase 5: in-place archive split<br/>+ post-approval handoff]
    P5 --> Compact["Recommend /compact<br/>user triggers manually"]
    Compact --> Exec["/deep-plan:deep-plan-execute<br/>load_tasks.py -> TaskCreate -> addBlockedBy -> TDD loop"]

Quick start

In Claude Code:

/plugin marketplace add tsadoq/claude-better-plan
/plugin install deep-plan@claude-better-plan

Then in any project:

/deep-plan add a rate limiter to the API

Optional arguments (parsed from the prompt; order-free):

/deep-plan slug:rate-limiter depth:exhaustive add a rate limiter to the API

• depth: shallow | standard | exhaustive -- scales fan-out and effort. shallow runs explore + shallow research only, skips deep research, one perspective, one quick critique pass. standard (default) is the full workflow with one critique loop. exhaustive runs multiple research waves, three perspectives, and loops the critique until it finds nothing material (cap 3 rounds).
• slug: my-name -- an explicit archive-slug hint; otherwise the slug is derived from the topic.

After approval and /compact, hand the plan to implementation:

/deep-plan:deep-plan-execute            # newest plan in the project plans_dir
/deep-plan:deep-plan-execute path/to/plan.md

It parses the plan's ## Tasks, creates one harness task per task (TaskCreate), wires Depends on into addBlockedBy (TaskUpdate), then implements each task test-first in dependency order. It refuses to start while ## Open questions is non-empty. Requires Claude Code >= v2.1.142 for the Task dependency API.

To install from a local checkout while developing:

/plugin marketplace add /absolute/path/to/claude-better-plan
/plugin install deep-plan@claude-better-plan

File layout

This repo is a Claude Code marketplace that ships exactly one plugin (deep-plan). The repo root is also the plugin root. Runtime data lives at $XDG_STATE_HOME/deep-plan/ (default ~/.local/state/deep-plan/) and is never git-tracked.