/deep-project, a Claude Code plugin
Blog posts:
- The Deep Trilogy - How the three plugins work together
- What I Learned - Technical lessons from plugin development
/deep-project transforms vague, high-level project requirements into well-scoped planning units through AI-assisted interview and decomposition. It ensures you've thought through every major component of the software you want to build and properly scoped them for thorough planning through /deep-plan.
This plugin is the first step in the deep planning pipeline. After decomposition, each unit can be fed to /deep-plan for comprehensive planning with research, external LLM review, and a TDD approach.
I built this after the first time I wanted to put a vague, broadly scoped software project through /deep-plan. I realized that at a certain level of broadness, for e.g., "Build me an app that does x y and z", that the optimal use of /deep-plan would be to split that vague idea into its distinct, major components and /deep-plan each of them. /deep-project is the plugin that allows you to give it very broad, vague ideas and have it tease out context and form the components that should each be /deep-planned.
TL;DR
/plugin marketplace add piercelamb/deep-project
/plugin install deep-project
/plugin enable deep-project
/deep-project @planning/requirements.md
Table of Contents
- Overview
- The Deep Trilogy
- Why deep-project?
- When to Use
- Quick Start
- How It Works
- Installation
- Usage
- Workflow Steps
- Output Files
- Requirements
- Best Practices
- Troubleshooting
- Testing
- Project Structure
- Contributing
Overview
deep-project orchestrates a decomposition workflow that breaks large projects into manageable pieces before detailed planning:
Interview → Split Analysis → Dependency Mapping → Directory Creation → Spec Generation
The plugin guides you through:
- Interview Phase: Structured Q&A to understand your mental model of the project
- Split Analysis: Determine if the project benefits from multiple planning units
- Dependency Discovery: Map relationships between splits
- Spec Generation: Create focused spec files for each unit
By the end, you have a planning directory with a project manifest and numbered split directories, each containing a spec file ready for /deep-plan.
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 │ ◀── YOU ARE HERE │
│ └─────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 01-auth │ │ 02-bill │ │ ... │ │
│ │ spec.md │ │ spec.md │ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ /deep- │ │ /deep- │ │ ... │ │
│ │ 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 here with
/deep-project - Single focused feature? Skip to
/deep-plan - Already have section files? Skip to
/deep-implement
Why deep-project?
Without deep-project
You: "Claude, I need to build a complete SaaS platform"
Claude: *overwhelmed by scope, makes assumptions, misses critical relationships*
Result: Inconsistent implementation, integration issues, rework
With deep-project
You: "/deep-project @planning/saas-requirements.md"
deep-project: Interview → Split Analysis → Manifest → Spec Files
Result:
- 01-auth-system/spec.md
- 02-billing-integration/spec.md
- 03-user-dashboard/spec.md
Each ready for focused /deep-plan sessions
Time Investment: ~15 minutes of interview Time Saved: Hours of coordination and rework from poorly scoped planning
When to Use
Use deep-project when:
- Your project has multiple distinct subsystems
- Requirements are vague and need decomposition
- You want to parallelize planning across multiple focused sessions
- Dependencies between components need explicit mapping
Skip deep-project when:
- The project is already a single, well-defined feature
- Requirements are clear and bounded
- You're doing a bug fix or small enhancement
- You already have well-scoped spec files
- Even in these cases, /deep-project will scope the project to a single component.
Quick Start
TL;DR: Create a requirements file, run the command, answer questions.
1. Create a requirements file:
Option A: Use your editor — Create planning/requirements.md with your project description.
Option B: Command line:
mkdir -p planning
cat > planning/requirements.md << 'EOF'
# My SaaS Platform
Build a complete SaaS platform with:
- User authentication (OAuth, email/password)
- Subscription billing
- Admin dashboard
- User-facing dashboard
- API for third-party integrations
EOF
Requirements files can be as detailed or vague as you like. The interview phase will extract specifics.
2. Run deep-project:
/deep-project @planning/requirements.md
3. Follow the prompts through Interview → Split Analysis → Confirmation → Generation
That's it. Your planning directory will contain numbered split directories with focused spec files.
How It Works
┌─────────────────────────────────────────────────────────────────┐
│ deep-project workflow │
├─────────────────────────────────────────────────────────────────┤
│