baekenough/deep-plan

Deep Plan Skill

Research-validated planning that eliminates the gap between research assumptions and actual code. Orchestrates a 3-phase cycle: Discovery Research → Reality-Check Planning → Plan Verification.

Teams-compatible — works both from the main conversation (R010) and inside Agent Teams members. When used in Teams, the member directly executes the 3-phase workflow without Skill tool invocation.

Usage

/deep-plan <topic-or-issue>
/deep-plan "implement caching layer for API responses"
/deep-plan #325 new authentication system
/deep-plan Rust async runtime migration

Problem Solved

Research-only analysis (like /research) produces findings based on assumptions about the codebase. These assumptions often diverge from reality:

| Assumption | Reality | Impact | |------------|---------|--------| | "Feature X is missing" | Already implemented | Wasted effort on duplicate work | | "Pattern Y is needed" | Partially exists | Over-engineering existing code | | "Library Z is required" | Already a dependency | Unnecessary integration effort |

/deep-plan solves this by cross-referencing research findings against actual code before committing to a plan.

Architecture — 3 Phases

Phase 1: Discovery Research

Invoke the /research skill internally for comprehensive topic analysis.

Phase 1: Discovery Research
├── Skill(research, args="<topic>")
├── 10-team parallel analysis (3 batches × 4/4/2)
├── Cross-verification loop (opus + codex)
├── ADOPT / ADAPT / AVOID taxonomy
└── Output: research report (artifact)

Execution:

• Orchestrator mode: Delegates to /research skill via Skill(research, args="<topic>").
• Teams mode: Executes the research workflow inline (see Teams Mode section). The member spawns research teams directly as sub-agents.

The executor waits for completion before proceeding to Phase 2.

Output: Full research report with ADOPT/ADAPT/AVOID taxonomy.

Phase 2: Reality-Check Planning

Ground-truth the research findings against the actual codebase.

Phase 2: Reality-Check Planning
├── EnterPlanMode
├── Explore agents (up to 3 parallel)
│   ├── Explore 1: Verify ADOPT items exist/don't exist
│   ├── Explore 2: Check ADAPT items for current state
│   └── Explore 3: Validate AVOID alternatives
├── Gap analysis table
├── Refined plan (real gaps only)
└── ExitPlanMode → user approval

Steps:

1. Enter Plan Mode: EnterPlanMode to activate planning context

2. Codebase Exploration: Spawn up to 3 Explore agents in parallel to verify research assumptions:

   • Each ADOPT item: Does it already exist? Partially implemented?
   • Each ADAPT item: What is the current state to adapt from?
   • Each AVOID item: Are the alternatives already available?

3. Gap Analysis: Build a reconciliation table:

   | Research Finding | Actual Code State | Gap Type | Action |
   |-----------------|-------------------|----------|--------|
   | "No caching"    | Redis client exists | Overestimate | Remove from plan |
   | "Need auth middleware" | No auth layer | Real gap | Keep in plan |
   | "Migrate to v3" | Already on v3.1 | Overestimate | Remove from plan |
   | "Add rate limiting" | Basic limiter exists | Partial gap | Adapt existing |
   

4. Refined Plan: Write implementation plan containing ONLY real gaps:

   • Remove overestimates (already implemented)
   • Adjust partial gaps (adapt, don't rebuild)
   • Prioritize real gaps by impact

5. User Approval: ExitPlanMode presents the refined plan for user review

Phase 3: Plan Verification Research

Validate the refined plan with focused research before implementation begins.

Phase 3: Plan Verification Research
├── 3-team focused verification
│   ├── T1: Technical feasibility
│   ├── T2: Conflict/duplication check
│   └── T3: Test strategy & risk
├── Verdict: PASS or REVISE
├── PASS → implementation advisory
└── REVISE → return to Phase 2

Teams (3 parallel, NOT full 10-team):

| Team | Focus | Verifies | |------|-------|----------| | T1 | Technical feasibility | Can the plan be implemented with current stack/deps? | | T2 | Conflict & duplication | Does the plan conflict with in-flight work or duplicate existing code? | | T3 | Test strategy & risk | Is the plan testable? What are the failure modes? |

Invocation: Phase 3 teams are spawned directly as parallel agents (NOT via Skill(research)). The orchestrator creates 3 focused agents, each with a specific verification mandate derived from the Phase 2 plan.

Model selection: sonnet for teams, opus for synthesis.

Verdict:

• PASS: Plan is verified. Display implementation advisory.
• REVISE: Issues found. Return to Phase 2 with feedback for plan refinement.
• REVISE limit: After 2 REVISE cycles, escalate to user for manual judgment.

Workflow Diagram

User: /deep-plan "topic"
  │
  ├─ Phase 1: Discovery Research
  │   ├─ Skill(research, args="topic")
  │   ├─ 10-team analysis → ADOPT/ADAPT/AVOID
  │   └─ Output: research artifact
  │
  ├─ Phase 2: Reality-Check Planning
  │   ├─ EnterPlanMode
  │   ├─ Explore agents (up to 3 parallel)
  │   ├─ Gap analysis: research vs actual code
  │   ├─ Refined plan (real gaps only)
  │   └─ ExitPlanMode → user approval
  │
  └─ Phase 3: Plan Verification
      ├─ 3-team focused research
      ├─ Verdict: PASS or REVISE
      ├─ PASS → implementation advisory
      └─ REVISE → loop back to Phase 2 (max 2 cycles)

Differentiation

| Skill | Scope | Code Verification | Phases | |-------|-------|-------------------|--------| | /research | Analysis only | None — assumption-based | 1 | | Plan mode | Planning only | Yes — code exploration | 1 | | /structured-dev-cycle | Full implementation | Yes — stage-by-stage | 6 | | /deep-plan | Analysis + Planning + Verification | 3-pass cross-verification | 3 |

/deep-plan fills the gap between research (which lacks code grounding) and implementation (which lacks upfront analysis). It produces a verified plan ready for execution.

Display Format

Before execution:

[Deep Plan] {topic}
├── Phase 1: Discovery Research (10 teams, 3 batches)
├── Phase 2: Reality-Check Planning (up to 3 Explore agents)
└── Phase 3: Plan Verification (3 focused teams)

Estimated phases: 3 | Models: sonnet → opus
Execute? [Y/n]

Phase transitions:

[Deep Plan] Phase 1/3 — Discovery Research
├── Research skill active...
└── Awaiting 10-team results

[Deep Plan] Phase 2/3 — Reality-Check Planning
├── Gap analysis: 6 ADOPT items → 2 real gaps, 4 overestimates
└── Refined plan: 5 action items (down from 12)

[Deep Plan] Phase 3/3 — Plan Verification
├── T1 (feasibility): ✓ PASS
├── T2 (conflicts): ✓ PASS
├── T3 (test/risk): ✓ PASS
└── Verdict: PASS — ready for implementation

Post-Completion Advisory

After PASS verdict:

[Advisory] Verified plan ready for implementation.
├── For complex implementations (10+ files): /structured-dev-cycle
├── For parallel task execution: superpowers:subagent-driven-development
└── For simple tasks (< 3 files): proceed directly

Execution Rules

| Rule | Detail | |------|--------| | Phase 1 | Full /research skill invocation (10 teams) | | Phase 2 | Max 3 parallel Explore agents (R009) | | Phase 3 | Max 3 parallel verification teams (R009) | | Orchestrator only | Main conversation manages all phases (R010) | | Intent display | Show phase plan before execution (R015) | | Ecomode | Auto-activate for team result aggregation (R013) | | REVISE limit | Max 2 cycles before user escalation |

Agent Teams (R018)

When Agent Teams is enabled, Phase 1 and Phase 3 parallel teams SHOULD use Agent Teams instead of individual Agent tool calls:

| Phase | Without Agent Teams | With Agent Teams | |-------|--------------------|--------------------| | Phase 1 | Delegates to /research (handles internally) | Delegates to /research (handles internally) | | Phase 2 | Up to 3 Explore agents via Agent tool | Up to 3 Explore agents via Agent tool (below threshold) | | Phase 3 | 3 agents via Agent tool | 3 agents — at threshold, prefer Agent Teams for coordination |

Phase 1 delegation to /research means Agent Teams decisions are handled by the research skill itself. Phase 3's 3-team verification is at the Agent Teams threshold (3+ agents) and benefits from peer messaging for cross-verification.

Model Selection

| Phase | Component | Model | Rationale | |-------|-----------|-------|-----------| | Phase 1 | Research teams | sonnet | Delegated to /research skill | | Phase 1 | Verification | opus | Delegated to /research skill | | Phase 2 | Explore agents | haiku | Fast codebase search | | Phase 2 | Gap analysis | opus | Complex reconciliation reasoning | | Phase 3 | Verification teams | sonnet | Balanced analysis | | Phase 3 | Synthesis/verdict | opus | Final judgment |

Cost Estimate

| Phase | Approximate Cost | Driver | |-------|-----------------|--------| | Phase 1 | High | Full 10-team /research invocation | | Phase 2 | Low-Medium | Up to 3 Explore agents (haiku) + 1 opus synthesis | | Phase 3 | Medium | 3 sonnet verification teams + 1 opus synthesis | | Total | High | Dominated by Phase 1 research cost |

/deep-plan is designed for high-stakes decisions where plan quality justifies the cost. For quick planning, use EnterPlanMode directly.

Integration

| Component | Integration | |-----------|-------------| | /research | Phase 1 full invocation (via Skill tool or inline in Teams mode) + Phase 3 reduced invocation pattern | | EnterPlanMode/ExitPlanMode | Phase 2 plan creation and user approval | | Explore agents | Phase 2 codebase verification (up to 3 parallel) | | R009 | Phase 1 (10 teams batched), Phase 2 (3 Explore), Phase 3 (3 teams) | | R010 | Orchestrator manages all 3 phases; teams are subagents | | R013 | Ecomode for team result aggregation | | R015 | Phase transition intent display | | result-aggregation | Phase 1 and 3 result formatting | | superpowers:subagent-driven-development | Post-PASS implementation advisory (external plugin) |

Fallback Behavior

| Scenario | Fallback | |----------|----------| | Phase 1 /research fails | Manual analysis, then proceed to Phase 2 | | Phase 2 EnterPlanMode unavailable | Perform analysis without plan mode context | | Phase 3 REVISE ≥ 2 times | Escalate to user for manual judgment | | Explore agent failure | Reduce parallel count, retry with remaining | | Partial team failure | Synthesize from available results, note gaps |

Teams Mode

When running inside an Agent Teams member (not via Skill tool), the deep-plan workflow operates identically but with these adaptations:

How It Works

The orchestrator reads this SKILL.md and includes the deep-plan instructions directly in the Teams member's prompt. The member then:

1. Phase 1: Executes research workflow inline (not via Skill(research)) — spawns 10 research teams as sub-agents
2. Phase 2: Uses EnterPlanMode/ExitPlanMode and Explore agents normally
3. Phase 3: Spawns 3 verification teams as sub-agents
4. Delivers final verified plan via SendMessage to team lead

Prompt Embedding Pattern

# When spawning a Teams member for deep-plan:
Agent(
  name: "planner-1",
  team_name: "my-team",
  prompt: """
  You are a deep-plan agent. Follow the deep-plan skill workflow below:
  {contents of deep-plan/SKILL.md}

  Also follow this research workflow for Phase 1:
  {contents of research/SKILL.md}

  Topic: {user's planning topic}
  Deliver verified plan via SendMessage to team lead when complete.
  """
)

Differences from Orchestrator Mode

| Aspect | Orchestrator Mode | Teams Mode | |--------|------------------|------------| | Invocation | Skill(deep-plan) | Prompt embedding | | Phase 1 research | Skill(research) | Inline execution | | Result delivery | Return to main conversation | SendMessage to team lead | | Plan approval | User via ExitPlanMode | Team lead via SendMessage | | Context isolation | Previously used context: fork | Standard context (no fork) |

Why No context: fork

context: fork was removed to enable Teams compatibility. Fork blocks sub-agent spawning, which is essential for Phase 1 (10 research teams) and Phase 3 (3 verification teams). Without fork, deep-plan operates in the standard context, which is required for both orchestrator and Teams usage.

Artifact Persistence

Phase 1 research artifact is persisted by the /research skill.

Phase 3 verification report is persisted by the final synthesis agent:

.claude/outputs/sessions/{YYYY-MM-DD}/deep-plan-{HHmmss}.md

With metadata header:

---
skill: deep-plan
date: {ISO-8601 with timezone}
query: "{original user query}"
phases_completed: 3
verdict: PASS|REVISE
---