deep-plan
Claude Code plugin that transforms vague requirements into detailed implementation plans via research, interviews, and multi-LLM review.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/piercelamb--deep-plan)HTML
<a href="/listings/piercelamb--deep-plan"><img src="/api/listings/piercelamb--deep-plan/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
> **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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 89 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "piercelamb-plugins",
- "description": "Claude Code plugins by Pierce Lamb",
- "version": "1.1.7",
- "owner": {
- "name": "Pierce Lamb",
- "url": "https://github.com/piercelamb"
- },
- "plugins": [
- {
- "name": "deep-project",
- "description": "Split vague project requirements into well-scoped units for /deep-plan",
- "version": "0.2.1",
- "author": {
- "name": "piercelamb",
- "url": "https://github.com/piercelamb"
- },
- "source": {
- "source": "url",
- "url": "https://github.com/piercelamb/deep-project.git"
- },
- "category": "development",
- "homepage": "https://github.com/piercelamb/deep-project",
- "tags": ["planning", "decomposition", "project-management", "requirements"]
- },
- {
- "name": "deep-plan",
- "description": "AI-assisted deep planning with research, interview, external LLM review, and TDD approach",
- "version": "0.3.2",
- "author": {
- "name": "piercelamb",
- "url": "https://github.com/piercelamb"
- },
- "source": "./",
- "category": "development",
- "homepage": "https://github.com/piercelamb/deep-plan",
- "tags": ["planning", "tdd", "architecture", "llm-review", "implementation"]
- },
- {
- "name": "deep-implement",
- "description": "Implement code from /deep-plan sections with TDD, code review, and git workflow",
- "version": "0.2.1",
- "author": {
- "name": "piercelamb",
- "url": "https://github.com/piercelamb"
- },
- "source": {
- "source": "url",
- "url": "https://github.com/piercelamb/deep-implement.git"
- },
- "category": "development",
- "homepage": "https://github.com/piercelamb/deep-implement",
- "tags": ["implementation", "tdd", "code-review", "git", "workflow"]
- },
- {
- "name": "deep-sota",
- "description": "Paper- and repo-grounded research over the lodestone knowledge base",
- "version": "0.2.1",
- "author": {
- "name": "piercelamb",
- "url": "https://github.com/piercelamb"
- },
- "source": {
- "source": "url",
- "url": "https://github.com/piercelamb/deep-sota.git"
- },
- "category": "research",
- "homepage": "https://github.com/piercelamb/deep-sota",
- "tags": ["research", "arxiv", "rag", "knowledge-base", "lodestone"]
- },
- {
- "name": "lodestone",
- "description": "Local research corpus over arXiv papers, blog posts, and code repos with paper-grounded MCP search/read tools",
- "version": "0.4.0",
- "author": {
- "name": "piercelamb",
- "url": "https://github.com/piercelamb"
- },
- "source": {
- "source": "url",
- "url": "https://github.com/piercelamb/lodestone.git"
- },
- "category": "research",
- "homepage": "https://github.com/piercelamb/lodestone",
- "tags": ["mcp", "arxiv", "rag", "research", "knowledge-base"]
- }
- ]
- }
README.md · README · 552 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- 
- # /deep-plan, a Claude Code plugin
- 
- 
- 
- 
- 
- > **Blog posts:**
- > - [Building /deep-plan](https://pierce-lamb.medium.com/building-deep-plan-a-claude-code-plugin-for-comprehensive-planning-30e0921eb841) - The story behind this plugin
- > - [The Deep Trilogy](https://pierce-lamb.medium.com/the-deep-trilogy-claude-code-plugins-for-writing-good-software-fast-33b76f2a022d) - How the three plugins work together
- > - [What I Learned](https://pierce-lamb.medium.com/what-i-learned-while-building-a-trilogy-of-claude-code-plugins-72121823172b) - Technical lessons from plugin development
- `/deep-plan` transforms vague feature requests into detailed, production-ready implementation plans through AI-assisted research, stakeholder interviews, and multi-LLM review.
- [`/deep-implement`](https://github.com/piercelamb/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`](https://github.com/piercelamb/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](#overview)
- - [The Deep Trilogy](#the-deep-trilogy)
- - [Why deep-plan?](#why-deep-plan)
- - [When to Use](#when-to-use)
- - [Quick Start](#quick-start)
- - [How It Works](#how-it-works)
- - [Installation](#installation)
- - [Usage](#usage)
- - [Workflow Steps](#workflow-steps)
- - [Output Files](#output-files)
- - [Configuration](#configuration)
- - [Environment Variables](#environment-variables)
- - [Requirements](#requirements)
- - [Best Practices](#best-practices)
- - [Security & Privacy](#security--privacy)
- - [Troubleshooting](#troubleshooting)
- - [Testing](#testing)
- - [Project Structure](#project-structure)
- - [Contributing](#contributing)
- - [Changelog](#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 │
- │ │
- └───────────────────────────────────────────────────────────────────┘
- ```
- | Plugin | Purpose | Input | Output |
- |--------|---------|-------|--------|
- | [`/deep-project`](https://github.com/piercelamb/deep-project) | Decompose | Vague requirements | Focused spec files |
- | [`/deep-plan`](https://github.com/piercelamb/deep-plan) | Plan | Spec file | Section files with TDD |
- | [`/deep-implement`](https://github.com/piercelamb/deep-implement) | Build | Section files | Production code |
- **Where to start?**
- - **Vague multi-component project?** Start with [`/deep-project`](https://github.com/piercelamb/deep-project)
- - **Single focused feature?** Start here with `/deep-plan`
- - **Already have section files?** Skip to [`/deep-implement`](https://github.com/piercelamb/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:*
- ```bash
- 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](https://claude.ai/code) installed
- - [uv](https://docs.astral.sh/uv/) (Python package manager)
- - Python 3.11+
- - (Optional) External LLM API key for review:
- - **Gemini**: `GEMINI_API_KEY` ([get one](https://aistudio.google.com/apikey)) or Google Cloud ADC credentials
- - **OpenAI**: `OPENAI_API_KEY` ([get one](https://platform.openai.com/api-keys))
- - 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`:
- ```bash
- git clone https://github.com/piercelamb/deep-plan.git /path/to/deep-plan
- ```
- ```json
- {
- "plugins": {
- "paths": ["/path/to/deep-plan"]
- }
- }
- ```
- **Option B: Via --plugin-dir flag (development/testing)**
- ```bash
- 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](#environment-variables) for all options.
- ```bash
- 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:
- ```json
- {
- "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](https://aistudio.google.com/apikey)
- - `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account JSON
- - Default ADC at `~/.config/gcloud/application_default_credentials.json` ([setup guide](https://cloud.google.com/docs/authentication/application-default-credentials))
- For Vertex AI, also set (or set in `config.json`):
- - `GOOGLE_CLOUD_PROJECT`
- - `GOOGLE_CLOUD_LOCATION`
- ### OpenAI
- - `OPENAI_API_KEY` - [OpenAI API key](https://platform.openai.com/api-keys)
- ## 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](https://pypi.org/project/google-genai/), [openai](https://pypi.org/project/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:
- ```bash
- 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](./LICENSE)
- ## Author
- Pierce Lamb
- ## Changelog
- See [CHANGELOG.md](CHANGELOG.md) for release history.
- ## Version
- 0.3.2
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.