Stop Guessing Scope! Use deep-project to Decompose Ideas

What if I told you that the #1 reason software projects fail isn't bad code, isn't missing tests, and isn't even wrong technology choices? It's something far more insidious—something that strikes before a single line of code gets written. I'm talking about vague, poorly scoped requirements that spiral into endless rework, integration nightmares, and that soul-crushing moment when you realize your "simple SaaS platform" has mutated into an unmanageable hydra of interconnected dependencies.

Sound familiar? You've been there. We all have.

You open Claude Code with a brilliant idea: "Build me a complete SaaS platform with auth, billing, dashboards, and an API." Claude nods enthusiastically. Hours later, you're drowning in assumptions, missing critical relationships between components, and watching your implementation fracture into inconsistent pieces that refuse to play nice together. The result? Coordination chaos. Rework hell. Deadlines blown.

But what if there was a secret weapon that could interview you, extract your mental model, and automatically decompose that vague ambition into laser-focused, independently plannable components? Enter piercelamb/deep-project—the Claude Code plugin that's making senior engineers whisper about a revolution in how we scope software. This isn't just another planning tool. It's the missing first step in a three-plugin pipeline that takes you from fuzzy idea to production code with surgical precision. And today, I'm pulling back the curtain on exactly how it works—and why you might never start a project the old way again.

What is deep-project?

deep-project is a Claude Code plugin created by Pierce Lamb that performs something deceptively simple yet profoundly powerful: it transforms vague, high-level software requirements into well-scoped planning units through an AI-assisted interview and decomposition workflow. Think of it as a project therapist that forces you to articulate what you actually want before you start building.

The plugin sits at the foundation of the "Deep Trilogy"—a three-plugin pipeline for turning ideas into production code:

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

Pierce built this after experiencing the pain firsthand. He tried feeding a broadly scoped project directly into /deep-plan and watched it struggle. The epiphany? At a certain level of vagueness—"Build me an app that does X, Y, and Z"—the optimal approach isn't to plan everything at once. It's to split that fuzzy idea into distinct major components first, then plan each one thoroughly. /deep-project is the plugin that makes that splitting process effortless.

Currently at version 0.2.1 and in beta, it's already gaining traction among developers who've tasted the productivity gains of proper decomposition. The plugin is written in Python 3.11+, distributed through the Claude Code marketplace, and licensed under MIT. No external API keys required—unlike its sibling /deep-plan.

Why is it trending now? Because the industry is waking up to a brutal truth: we're spectacularly bad at scoping our own ambitions. Tools that force structure before implementation are becoming essential as projects grow more complex and distributed teams need clearer boundaries.

Key Features That Make It Irresistible

Let's dissect what makes deep-project genuinely powerful—not just in theory, but in the trenches of real development work.

Adaptive Interview Engine — This isn't a static form. The plugin conducts a structured Q&A that adapts to your responses, probing deeper where your requirements are fuzzy and moving quickly where you're already clear. It extracts your mental model of the project—those implicit assumptions you didn't even know you were making. The interview transcript gets preserved as deep_project_interview.md, creating an audit trail of your evolving understanding.

Intelligent Split Analysis — Here's where the magic happens. The plugin analyzes whether your project genuinely benefits from multiple planning units or should remain a single focused component. It doesn't blindly split everything—it judges. This prevents the opposite failure mode: over-fragmentation that creates unnecessary coordination overhead.

Dependency Mapping & Execution Ordering — The hidden killer of multi-component projects isn't the components themselves—it's the implicit dependencies between them. deep-project surfaces these relationships explicitly, creating a dependency graph that informs your execution order. Build the auth system before the billing integration? Obviously. But what about the subtle dependency between your admin dashboard and your API versioning strategy? That's where this shines.

Automatic Spec Generation — Each split gets its own focused spec.md file, ready to feed directly into /deep-plan. No manual copy-pasting. No format wrestling. The specs inherit context from your interview while maintaining independence—each one is self-contained enough for focused planning sessions.

Resume Capability — Context limits hit? Need to pause and think? The plugin detects existing artifacts and resumes from the appropriate step. This is crucial for complex projects where the interview alone might span multiple sessions.

Machine-Readable Manifest Output — The project-manifest.md contains a SPLIT_MANIFEST block that's parseable by downstream tools. This isn't just documentation—it's a contract between planning and implementation phases.

Use Cases: Where deep-project Absolutely Dominates

1. The "Complete SaaS Platform" Ambition

You're a solo founder with a vision: auth, billing, dashboards, API, third-party integrations. Without deep-project, you dump this on Claude and hope for the best. With deep-project: the interview surfaces that your "billing" actually encompasses three distinct subsystems (subscription management, usage metering, invoice generation), your "dashboard" splits into admin and user-facing variants with different permission models, and your API needs versioning strategy before implementation. You end with 01-auth-system/spec.md, 02-billing-subscriptions/spec.md, 03-billing-metering/spec.md—each plannable in focused 30-minute sessions.

2. Legacy System Modernization

That monolith you're extracting? The boundaries are murky, dependencies are spaghetti, and every "simple" extraction turns into a month-long archaeology expedition. deep-project interviews you about the target architecture, identifies logical service boundaries based on your business capabilities, and maps the safe extraction order that minimizes risk. The dependency graph becomes your migration roadmap.

3. Microservices Decomposition (Without the Microservices Pain)

Not every project needs microservices—but when they do, the decomposition decision is make-or-break. deep-project helps you identify genuine bounded contexts versus artificial splits that'll create distributed monolith hell. The interview phase catches when your "user service" and "profile service" are actually the same context with different read models.

4. Parallel Team Coordination

Multiple developers or teams ready to plan simultaneously? deep-project creates independently scopable units with explicit interfaces. Team A plans auth while Team B plans billing—no stepping on toes, no integration surprises later. The manifest becomes your team contract.

5. Greenfield Projects with Exploratory Scope

You're not sure what you're building yet. The idea is "something in the AI space with documents and collaboration." deep-project doesn't judge your vagueness—it interviews it into clarity. The split analysis might reveal that your "collaboration" feature is actually three different interaction patterns (real-time, async, and review-based) that need separate planning approaches.

Step-by-Step Installation & Setup Guide

Getting deep-project running takes under two minutes. Here's the complete walkthrough.

Prerequisites

Before starting, ensure you have:

• Claude Code installed and configured
• uv — the modern Python package manager (trust me, it's worth switching from pip)
• Python 3.11 or higher

Verify your Python version:

python --version  # Should show 3.11.x or higher

Install uv if you haven't:

curl -LsSf https://astral.sh/uv/install.sh | sh

Method 1: Marketplace Installation (Recommended)

The fastest path. Open Claude Code and execute:

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

Pro tip: If you've already installed /deep-plan or /deep-implement, all three plugins share the same marketplace. Skip the add step and run /plugin install deep-project directly.

Prefer the UI? Use:

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

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

Method 2: Manual Installation (Development/Customization)

For those who want to hack on the plugin or run a fork:

# Clone the repository
git clone https://github.com/piercelamb/deep-project.git /path/to/deep-project

Via settings.json (project-specific):

{
  "plugins": {
    "paths": ["/path/to/deep-project"]
  }
}

Via command-line flag (one-off testing):

claude --plugin-dir /path/to/deep-project

Verification

Confirm installation:

/deep-project --help

You should see usage instructions. If you get "command not found", double-check that the plugin is enabled via /plugins.

REAL Code Examples from the Repository

Let's examine actual usage patterns from the piercelamb/deep-project repository, with detailed explanations of what each step accomplishes.

Example 1: The Complete TL;DR Workflow

The README's quick-start is deceptively powerful. Here's the exact sequence:

# Add the plugin marketplace (one-time per Claude Code installation)
/plugin marketplace add piercelamb/deep-project

# Install the specific plugin
/plugin install deep-project

# Enable it for use in your session
/plugin enable deep-project

# Execute with your requirements file
/deep-project @planning/requirements.md

What's happening under the hood? The @planning/requirements.md syntax is Claude Code's file reference notation. The plugin receives this file path, validates it exists, then initiates its workflow engine. The planning directory is inferred from the parent directory of your requirements file—so planning/requirements.md means all outputs go to planning/.

Example 2: Creating Requirements Programmatically

For automation enthusiasts or CI/CD pipelines, here's the bash heredoc pattern from the README:

# Create the planning directory structure
mkdir -p planning

# Generate requirements file with inline content
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

Critical detail: The << 'EOF' syntax with quotes prevents variable expansion—your requirements stay exactly as written. This pattern is perfect for project templates or team onboarding scripts where you want consistent starting points.

Example 3: The Core Workflow Architecture

The README's ASCII workflow diagram translates to this execution flow:

/deep-project @requirements.md
         │
         ▼
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │  Interview   │ ──▶ │    Split     │ ──▶ │  Dependency  │
  │  (adaptive)  │     │   Analysis   │     │   Mapping    │
  └──────────────┘     └──────────────┘     └──────────────┘
                                    │
                                    ▼
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │     Spec     │ ◀── │  Directory   │ ◀── │    User      │
  │  Generation  │     │   Creation   │     │ Confirmation │
  └──────────────┘     └──────────────┘     └──────────────┘

Phase breakdown:

• Interview (adaptive): The plugin asks questions, your answers shape follow-ups. It's not linear—if you mention "microservices," it probes service boundaries. If you say "monolith," it asks about module boundaries instead.
• Split Analysis: Determines whether 01-auth, 02-billing, etc., or just a single 01-complete-platform.
• Dependency Mapping: Identifies that billing depends on auth, dashboard depends on both.
• User Confirmation: Critical checkpoint—you review and approve before any files are written.
• Directory Creation & Spec Generation: The mechanical execution of your approved plan.

Example 4: Resuming Interrupted Sessions

The resume capability is a lifesaver for complex projects:

# Original run, interrupted by context limit or manual pause
/deep-project @planning/requirements.md

# Simply re-run with identical arguments
/deep-project @planning/requirements.md

The plugin detects existing artifacts—deep_project_interview.md, partial project-manifest.md—and resumes from the appropriate step. No flags needed. No state management on your part. This is idempotent execution done right.

Example 5: Running the Test Suite

For contributors or those verifying their installation:

# Navigate to plugin directory
cd /path/to/deep-project

# Execute test suite via uv (handles virtual environment automatically)
uv run pytest tests/

Why uv run instead of pytest directly? uv manages dependencies via pyproject.toml and creates isolated environments. No source venv/bin/activate, no dependency conflicts with your system Python. This is modern Python tooling at its cleanest.

Advanced Usage & Best Practices

You've got the basics. Now let's talk about extracting maximum value from deep-project.

Start intentionally vague. Counterintuitive, but the interview phase is designed to surface details. Over-specifying in your requirements file actually reduces the interview's effectiveness—you've already made assumptions the plugin would have challenged. Write "Build a SaaS with auth and billing" not "Build a SaaS with OAuth 2.0 PKCE flow, Stripe Checkout Session integration, and...".

Treat the interview as architecture therapy. The questions aren't bureaucratic overhead—they're forcing functions for clarity. When the plugin asks "How do users interact with the billing system?" it's checking whether you've thought about admin overrides, trial flows, and dunning management. Your thoroughness here directly impacts spec quality.

Review the manifest like your project depends on it—because it does. The project-manifest.md is your last chance to catch scope issues before they cascade into /deep-plan and then into code. Pay special attention to the dependency graph: cycles here mean pain later. If split A depends on B and B depends on A, you've got a bounded context boundary wrong.

Prefer more splits over fewer. The README emphasizes this for good reason. A split that's too large defeats the purpose—you're back to overwhelmed planning sessions. A split that's slightly too small just means a shorter /deep-plan session. Err on the side of granularity.

Map dependencies explicitly, even when they seem obvious. "Auth before billing" is obvious. "API versioning strategy before third-party integrations" is less obvious but equally critical. The explicit mapping prevents implicit assumptions that become integration bugs.

Comparison with Alternatives

Why deep-project wins: It's the only approach that combines AI-assisted discovery with structured, tool-integrated output. Manual decomposition works but requires senior-level experience and discipline. Generic AI chats give you walls of text, not actionable spec files. PM tools plan execution, not architecture. Code-first prototyping is expensive learning.

The 15-minute interview investment pays for itself many times over in prevented rework. And the native pipeline to /deep-plan means your scoping decisions flow directly into test-driven planning—no translation loss.

FAQ: Your Burning Questions Answered

Q: Do I need to use all three Deep Trilogy plugins, or can I use deep-project standalone?

A: deep-project works standalone—its output is standard markdown spec files you can plan however you want. But the magic happens in the pipeline. If you're already using /deep-plan, adding deep-project upstream eliminates the "what do I plan?" friction.

Q: What if my project is actually just a single feature? Should I still use deep-project?

A: The README is explicit here: even for single-feature projects, deep-project will scope it to a single component. You lose nothing, and you gain validation that your "simple" feature is indeed simple. Skip it only when you already have well-scoped spec files.

Q: How does the interview handle changing requirements mid-project?

A: Start fresh with updated requirements. The plugin's resume detection will notice the mismatch and prompt you. The project-manifest.md and interview transcript from your first run become valuable baseline documentation for what's changing.

Q: Is deep-project only for web/SaaS projects?

A: Absolutely not. The interview is domain-agnostic. Mobile apps, data pipelines, embedded systems, ML infrastructure—any software with multiple components benefits from structured decomposition. The plugin's only assumption is that you're building something with distinct parts.

Q: What happens if I disagree with the split analysis?

A: User confirmation is mandatory. The plugin presents its proposed structure for your approval before generating any files. You can request adjustments, merge splits, or add ones it missed. Think of it as a starting point for negotiation, not a dictate.

Q: Are there any API costs or external dependencies?

A: None. Unlike /deep-plan, deep-project requires no external API keys. It operates entirely within Claude Code's context. Your only "cost" is the interview time.

Q: How mature is this? It's only version 0.2.1...

A: Beta status means active development, not instability. Pierce Lamb is iterating based on real usage. The core workflow—interview, split, confirm, generate—is solid and production-ready. Expect enhancements to the interview engine and additional output formats as the ecosystem matures.

Conclusion: The Scoping Revolution Is Here

Here's the uncomfortable truth: we've been building software backwards for decades. We jump to implementation with fuzzy understanding, discover our scope was wrong through painful integration failures, and then retrofit structure onto chaos. piercelamb/deep-project inverts this. It forces clarity before commitment, structure before code, and explicit dependencies before implicit assumptions become bugs.

The 15-minute interview isn't overhead—it's the highest-leverage time you'll spend on your project. Those focused spec files, that dependency graph, that machine-readable manifest? They're not just planning artifacts. They're insurance against the most expensive failure mode in software: building the wrong thing well.

I've seen too many projects crash on the rocks of vague requirements. deep-project is the lighthouse that keeps you off those rocks—and points you toward the /deep-plan harbor where thorough, test-driven planning awaits.

Ready to stop guessing scope? Head to github.com/piercelamb/deep-project, install the plugin, and run your first decomposition. Your future self—staring at clean spec files instead of integration nightmare logs—will thank you.

The Deep Trilogy is waiting. Start with /deep-project.