
/deep-plan, a Claude Code plugin

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
- The Deep Trilogy
- Why deep-plan?
- When to Use
- Quick Start
- How It Works
- Installation
- Usage
- Workflow Steps
- Output Files
- Configuration
- Environment Variables
- Requirements
- Best Practices
- Security & Privacy
- Troubleshooting
- Testing
- Project Structure
- Contributing
- Changelog
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 │
│ │
└───────────────────────────────────────────────────────────────────┘
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