Skip to content

avi8or/deep-plan

BranchesTags
 
 

Repository files navigation

deep-plan hero

/deep-plan, a Claude Code plugin

Version Status License Claude Code Python

Blog posts:

/deep-plan transforms vague feature requests into detailed, production-ready implementation plans through AI-assisted research, stakeholder interviews, and multi-LLM review.

/deep-implement, its companion plugin, takes these section files and implements them with TDD methodology, integrated code review, and atomic commits.

For large projects with broad, vague requirements, use /deep-project first to decompose into focused planning units before running /deep-plan on each.

This plugin started as an effort to automate the most time-intensive part of my Claude Code workflow that I had previously been doing manually. It is primarily targeted at Claude Code users that don't have strict token constraints and prefer deep planning/plan review before implementation. It's designed to speed up creating production-ready code within Claude Code without sacrificing an understanding of how it works.

TL;DR

/plugin marketplace add piercelamb/deep-plan
/plugin install deep-plan
/plugin enable deep-plan
/deep-plan @planning/auth-spec.md

Table of Contents

Overview

deep-plan orchestrates a comprehensive planning workflow that ensures you think through implementation details before writing code:

Research → Interview → External LLM Review → TDD Plan → Section Splitting

The plugin guides you through:

  • Research Phase: Analyze existing codebases and research the web for current best practices
  • Interview Phase: Structured Q&A to surface hidden requirements and edge cases
  • External Review: Independent feedback from Gemini, OpenAI, or an Opus subagent on your plan
  • TDD Phase: Define test stubs before implementation
  • Section Phase: Split into parallelizable, self-contained implementation units (written in parallel via subagents)

By the end, you have a complete planning directory with specs, research, reviews, and small, isolated implementation sections that any engineer (or Claude) can pick up cold.

The Deep Trilogy

This plugin is part of a three-plugin pipeline for turning ideas into production code:

/deep-project (decompose) → /deep-plan (plan) → /deep-implement (build)

┌───────────────────────────────────────────────────────────────────┐
│                        THE DEEP TRILOGY                           │
│                From Vague Idea to Production Code                 │
├───────────────────────────────────────────────────────────────────┤
│                                                                   │
│         "I want to build a SaaS platform"                         │
│                        │                                          │
│                        ▼                                          │
│      ┌─────────────────────────────────────┐                      │
│      │            /deep-project            │                      │
│      └─────────────────────────────────────┘                      │
│           │            │            │                             │
│           ▼            ▼            ▼                             │
│      ┌─────────┐  ┌─────────┐  ┌─────────┐                        │
│      │ 01-auth │  │ 02-bill │  │   ...   │                        │
│      │ spec.md │  │ spec.md │  │         │                        │
│      └─────────┘  └─────────┘  └─────────┘                        │
│           │            │            │                             │
│           ▼            ▼            ▼                             │
│      ┌─────────┐  ┌─────────┐  ┌─────────┐                        │
│      │ /deep-  │  │ /deep-  │  │   ...   │  ◀── YOU ARE HERE      │
│      │  plan   │  │  plan   │  │         │                        │
│      └─────────┘  └─────────┘  └─────────┘                        │
│         │   │       │ │ │           │                             │
│         ▼   ▼       ▼ ▼ ▼           ▼                             │
│      ┌────┐┌────┐┌────┐┌────┐┌────┐┌─────────┐                    │
│      │ 01 ││ 02 ││ 01 ││ 02 ││ 03 ││   ...   │                    │
│      └────┘└────┘└────┘└────┘└────┘└─────────┘                    │
│        │    │     │     │    │          │                         │
│        └─┬──┘     └──┬──┴────┘          │                         │
│          │           │                  │                         │
│          ▼           ▼                  ▼                         │
│      ┌─────────┐┌─────────┐        ┌─────────┐                    │
│      │ /deep-  ││ /deep-  │        │   ...   │                    │
│      │implement││implement│        │         │                    │
│      └─────────┘└─────────┘        └─────────┘                    │
│           │          │                  │                         │
│           ▼          ▼                  ▼                         │
│      ┌─────────┐┌─────────┐        ┌─────────┐                    │
│      │  auth   ││ billing │        │   ...   │                    │
│      │  code   ││  code   │        │         │                    │
│      └─────────┘└─────────┘        └─────────┘                    │
│           │          │                  │                         │
│           └──────────┴──────────────────┘                         │
│                          │                                        │
│                          ▼                                        │
│                 Production Codebase                               │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘
Plugin Purpose Input Output
/deep-project Decompose Vague requirements Focused spec files
/deep-plan Plan Spec file Section files with TDD
/deep-implement Build Section files Production code

Where to start?

  • Vague multi-component project? Start with /deep-project
  • Single focused feature? Start here with /deep-plan
  • Already have section files? Skip to /deep-implement

Why deep-plan?

Without deep-plan

You: "Claude, build me an auth system"
Claude: *immediately starts coding*
Result: Multiple iterations, missed requirements, rework

With deep-plan

You: "/deep-plan @planning/auth-spec.md"
deep-plan: Research → Interview → External Review → TDD Plan → Sections
Result: Complete implementation plan reviewed by multiple LLMs, split into chunks that keep the context window monsters at bay

Time Investment: ~30 minutes of interview + review Time Saved: Hours of rework and missed requirements

When to Use

Use deep-plan when:

  • You want to maintain a mental model of what's being created
  • Requirements are vague and need fleshing out
  • You want external validation before investing implementation time
  • The feature is complex enough to benefit from deep planning

Skip deep-plan when:

  • Simple bug fixes or one-file changes
  • Requirements are already crystal clear
  • Time pressure prevents thorough planning
  • You are ready to open the Ralph Wiggum flood gates

Quick Start

TL;DR: Create a spec file, run the command, answer questions.

1. Create a spec file:

Option A: Use your editor — Create planning/auth-spec.md with your feature description.

Option B: Command line:

mkdir -p planning
cat > planning/auth-spec.md << 'EOF'
# Authentication Feature
Add OAuth2 login with Google and GitHub providers.
Store sessions in Redis. Use JWT for API authentication.
EOF

Spec files can be as dense or as sparse as you like. I've used /deep-plan with a few bullet points and also used it with structured, thorough documents.

2. Run deep-plan:

/deep-plan @planning/auth-spec.md

3. Follow the prompts through Research → Interview → Review → Output

That's it. Your planning directory will contain a complete implementation plan with TDD stubs and parallelizable sections.

Token & Cost Note: This workflow is token-intensive (research, multi-turn interview, review). Run /compact before starting. If using external LLM reviews (Gemini/OpenAI), those will incur API costs on your accounts.

If you /compact or exit in the middle, /deep-plan can recover from the existing files.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        deep-plan workflow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   /deep-plan @spec.md                                           │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Research   │ ──▶ │  Interview   │ ──▶ │    Spec      │    │
│   │  (optional)  │     │  (5-10 Q&A)  │     │  Synthesis   │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│                                                   │             │
│                                                   ▼             │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Section    │ ◀── │   TDD Plan   │ ◀── │   External   │    │
│   │  Splitting   │     │  Generation  │     │  LLM Review  │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │  sections/section-01-*.md  sections/section-02-*.md ...  │  │
│   │  (Self-contained, parallel-ready implementation units)   │  │
│   └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Installation

Prerequisites

  • Claude Code installed
  • uv (Python package manager)
  • Python 3.11+
  • (Optional) External LLM API key for review:
    • Gemini: GEMINI_API_KEY (get one) or Google Cloud ADC credentials
    • OpenAI: OPENAI_API_KEY (get one)
    • If no external keys configured, review can be performed via Opus subagent

Install via Marketplace (Recommended)

Option A: CLI commands

/plugin marketplace add piercelamb/deep-plan
/plugin install deep-plan
/plugin enable deep-plan

Option B: Via UI

/plugin marketplace add piercelamb/deep-plan
/plugin install deep-plan
/plugins

Then scroll to "Installed", find deep-plan, and click "Enable".

Already installed /deep-project or /deep-implement? All three plugins share a marketplace. If you've already added any one of the deep trilogy repos, just run /plugin install deep-plan directly — no need to add another marketplace.

Manual Installation

Option A: Via settings.json

Clone the repo, then add to your project's .claude/settings.json:

git clone https://github.com/piercelamb/deep-plan.git /path/to/deep-plan
{
  "plugins": {
    "paths": ["/path/to/deep-plan"]
  }
}

Option B: Via --plugin-dir flag (development/testing)

git clone https://github.com/piercelamb/deep-plan.git /path/to/deep-plan
claude --plugin-dir /path/to/deep-plan

Configure API Keys (Optional)

For external LLM review via Gemini or OpenAI, set API keys. See Environment Variables for all options.

export OPENAI_API_KEY="your-key"    # For OpenAI/ChatGPT
export GEMINI_API_KEY="your-key"    # For Gemini

The plugin also supports Application Default Credentials (ADC) for Gemini. If you use ADC, you'll need to set GOOGLE_CLOUD_LOCATION or set your project's location in the plugin's config.json file.

If no external LLM keys are configured, the plugin can perform review via an Opus subagent instead.

The plugin validates your configuration when /deep-plan first runs.

Usage

Basic Invocation

/deep-plan @path/to/your-spec.md

The spec file can be as detailed or vague as you like. The planning directory is inferred from the spec file's parent directory.

Resuming

If the workflow is interrupted (context limit, user pause), follow Claude's instructions or simply re-run with the same spec file:

/deep-plan @planning/auth-spec.md

The plugin detects existing artifacts and resumes from the appropriate step.

Workflow Steps

The plugin runs a multi-phase workflow:

Phase What Happens
Setup Validate environment, check spec file, initialize session
Research Codebase exploration, web research (optional, based on your choices)
Interview Structured Q&A to clarify requirements
Planning Synthesize spec, generate implementation plan
Review External LLM review (Gemini/OpenAI or Opus subagent), integrate feedback, user review
TDD Generate test stubs mirroring plan structure
Sections Split into implementation sections, generate files in parallel via subagents

Output Files

After running deep-plan, your planning directory contains:

planning/
├── your-spec.md                 # Your original input
├── deep_plan_config.json        # Session state (for resume)
├── claude-research.md           # Web + codebase research findings
├── claude-interview.md          # Q&A transcript
├── claude-spec.md               # Synthesized specification
├── claude-plan.md               # ★ Primary deliverable
├── claude-integration-notes.md  # Feedback integration decisions
├── claude-plan-tdd.md           # Test stubs
├── reviews/
│   ├── gemini-review.md         # Gemini feedback (if using Gemini)
│   ├── openai-review.md         # OpenAI feedback (if using OpenAI)
│   └── opus-review.md           # Opus subagent feedback (if no external LLMs)
└── sections/
    ├── index.md                 # Section manifest
    ├── section-01-*.md          # Implementation unit 1
    ├── section-02-*.md          # Implementation unit 2
    └── ...

Configuration

Edit config.json at the plugin root:

{
  "context": {
    "check_enabled": true
  },
  "vertex_ai": {
    "project": null,
    "location": null
  },
  "external_review": {
    "alert_if_missing": true,
    "feedback_iterations": 1
  },
  "models": {
    "gemini": "gemini-3-pro-preview",
    "chatgpt": "gpt-5.2"
  },
  "llm_client": {
    "timeout_seconds": 120,
    "max_retries": 3
  }
}
Setting Default Purpose
context.check_enabled true Prompt before token-intensive operations
vertex_ai.project null GCP project for Vertex AI (falls back to gcloud config)
vertex_ai.location null GCP location for Vertex AI (falls back to GOOGLE_CLOUD_LOCATION)
external_review.alert_if_missing true Warn if no LLM API keys configured
models.gemini gemini-3-pro-preview Gemini model for external review
models.chatgpt gpt-5.2 OpenAI model for external review
llm_client.timeout_seconds 120 API call timeout
llm_client.max_retries 3 Retry attempts for transient errors

Environment Variables

Gemini (choose one)

  • GEMINI_API_KEY - AI Studio API key
  • GOOGLE_APPLICATION_CREDENTIALS - Path to service account JSON
  • Default ADC at ~/.config/gcloud/application_default_credentials.json (setup guide)

For Vertex AI, also set (or set in config.json):

  • GOOGLE_CLOUD_PROJECT
  • GOOGLE_CLOUD_LOCATION

OpenAI

Requirements

  • Claude Code
  • Python >= 3.11
  • uv package manager
  • (Optional) External LLM API key (Gemini or OpenAI) for external review

Python Dependencies

Managed via pyproject.toml:

  • google-genai >= 1.0.0
  • openai >= 1.0.0

Best Practices

  1. Start with a spec file - Even a vague one. The interview phase will extract details.

  2. Answer interview questions thoroughly - This is where requirements get surfaced.

  3. Review external feedback critically - LLM reviewers catch blind spots but may suggest unnecessary complexity.

  4. Use sections for parallel work - Each section file is self-contained. Multiple engineers (or Claude sessions) can work in parallel.

  5. Compact before starting - The workflow is token-intensive. Start with a fresh or compacted context.

Security & Privacy

What deep-plan does with your data

  • Spec files: Read by Claude.
  • Interview answers: Stored locally in your planning directory and read by Claude.
  • External LLM review: The integrated plan Claude creates is sent to Gemini/OpenAI for review (you control which LLMs)

API Key Handling

Your API keys (GEMINI_API_KEY, OPENAI_API_KEY) are:

  • Read only by validate-env.sh to confirm connectivity
  • Never logged or transmitted by deep-plan code
  • Passed directly to official SDKs (google-genai, openai)

Troubleshooting

"No external LLM configured"

Issue: validate-env.sh reports no Gemini or OpenAI auth

Solution (choose one):

  • Set GEMINI_API_KEY or OPENAI_API_KEY environment variable
  • Configure Google Cloud ADC: gcloud auth application-default login
  • Continue without external keys—the plugin will offer Opus subagent review instead

"Spec file not found"

Issue: The @file path doesn't exist

Solution:

  • Ensure the file path is correct and the file exists
  • Use absolute paths if relative paths aren't resolving

Workflow interrupted mid-section

Issue: Context limit hit during section generation

Solution:

  • Follow Claude's instructions or
  • Re-run /deep-plan @your-spec.md
  • The plugin detects completed sections and resumes from the next one

External review timeout

Issue: LLM API calls timing out

Solution:

  • Increase llm_client.timeout_seconds in config.json
  • Check your API quotas and rate limits

Testing

Run the test suite:

cd /path/to/deep-plan
uv run pytest tests/

Project Structure

deep_plan/
├── .claude-plugin/plugin.json    # Plugin metadata
├── config.json                   # Global configuration
├── LICENSE                       # MIT License
├── README.md                     # This file
├── pyproject.toml               # Python dependencies
├── scripts/
│   ├── checks/                  # Validation & setup scripts
│   ├── lib/                     # Shared utilities
│   └── llm_clients/             # External LLM integration
├── skills/
│   └── deep-plan/
│       ├── SKILL.md             # Main skill definition
│       └── references/          # Protocol documents
├── prompts/                     # LLM review prompts
└── tests/                       # Test suite

Contributing

Contributions welcome! Please:

  1. Clone the repository
  2. Create a feature branch
  3. Run tests: uv run pytest tests/
  4. Submit a pull request

License

MIT

Author

Pierce Lamb

Changelog

See CHANGELOG.md for release history.

Version

0.3.2

About

Claude Code plugin that transforms vague requirements into detailed implementation plans via research, interviews, and multi-LLM review.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 97.8%
  • Shell 2.2%