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                        │
├─────────────────────────────────────────────────────────────────┤
│