deep-project
Claude Code plugin that transforms vague software ideas into individual, ready-to-be-planned components
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-project)HTML
<a href="/listings/piercelamb--deep-project"><img src="/api/listings/piercelamb--deep-project/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 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.
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": "./",
- "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": {
- "source": "url",
- "url": "https://github.com/piercelamb/deep-plan.git"
- },
- "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 · 446 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- 
- # /deep-project, a Claude Code plugin
- 
- 
- 
- 
- 
- > **Blog posts:**
- > - [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-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`](https://github.com/piercelamb/deep-plan).
- This plugin is the first step in the deep planning pipeline. After decomposition, each unit can be fed to [`/deep-plan`](https://github.com/piercelamb/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-plan`ned.
- ## 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](#overview)
- - [The Deep Trilogy](#the-deep-trilogy)
- - [Why deep-project?](#why-deep-project)
- - [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)
- - [Requirements](#requirements)
- - [Best Practices](#best-practices)
- - [Troubleshooting](#troubleshooting)
- - [Testing](#testing)
- - [Project Structure](#project-structure)
- - [Contributing](#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`](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 here with `/deep-project`
- - **Single focused feature?** Skip to [`/deep-plan`](https://github.com/piercelamb/deep-plan)
- - **Already have section files?** Skip to [`/deep-implement`](https://github.com/piercelamb/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:*
- ```bash
- 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 │
- ├─────────────────────────────────────────────────────────────────┤
- │ │
- │ /deep-project @requirements.md │
- │ │ │
- │ ▼ │
- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
- │ │ Interview │ ──▶ │ Split │ ──▶ │ Dependency │ │
- │ │ (adaptive) │ │ Analysis │ │ Mapping │ │
- │ └──────────────┘ └──────────────┘ └──────────────┘ │
- │ │ │
- │ ▼ │
- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
- │ │ Spec │ ◀── │ Directory │ ◀── │ User │ │
- │ │ Generation │ │ Creation │ │ Confirmation │ │
- │ └──────────────┘ └──────────────┘ └──────────────┘ │
- │ │ │
- │ ▼ │
- │ ┌──────────────────────────────────────────────────────────┐ │
- │ │ 01-auth/spec.md 02-billing/spec.md 03-dashboard/... │ │
- │ │ (Focused planning units ready for /deep-plan) │ │
- │ └──────────────────────────────────────────────────────────┘ │
- │ │
- └─────────────────────────────────────────────────────────────────┘
- ```
- ## Installation
- ### Prerequisites
- - [Claude Code](https://claude.ai/code) installed
- - [uv](https://docs.astral.sh/uv/) (Python package manager)
- - Python 3.11+
- ### Install via Marketplace (Recommended)
- **Option A: CLI commands**
- ```
- /plugin marketplace add piercelamb/deep-project
- /plugin install deep-project
- /plugin enable deep-project
- ```
- **Option B: Via UI**
- ```
- /plugin marketplace add piercelamb/deep-project
- /plugin install deep-project
- /plugins
- ```
- Then scroll to "Installed", find `deep-project`, and click "Enable".
- > **Already installed `/deep-plan` 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-project` 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-project.git /path/to/deep-project
- ```
- ```json
- {
- "plugins": {
- "paths": ["/path/to/deep-project"]
- }
- }
- ```
- **Option B: Via --plugin-dir flag (development/testing)**
- ```bash
- git clone https://github.com/piercelamb/deep-project.git /path/to/deep-project
- claude --plugin-dir /path/to/deep-project
- ```
- ## Usage
- ### Basic Invocation
- ```
- /deep-project @path/to/requirements.md
- ```
- The requirements file can be as detailed or vague as you like. The planning directory is inferred from the requirements file's parent directory.
- ### Resuming
- If the workflow is interrupted (context limit, user pause), re-run with the same requirements file:
- ```
- /deep-project @planning/requirements.md
- ```
- The plugin detects existing artifacts and resumes from the appropriate step.
- ## Workflow Steps
- | Phase | What Happens |
- |-------|--------------|
- | **Setup** | Validate input, check for existing session, initialize |
- | **Interview** | Adaptive Q&A to understand project scope and relationships |
- | **Split Analysis** | Determine if project benefits from multiple units |
- | **Dependency Mapping** | Identify relationships and execution order |
- | **User Confirmation** | Present proposed structure for approval |
- | **Directory Creation** | Create numbered split directories |
- | **Spec Generation** | Write focused spec.md for each split |
- ## Output Files
- After running deep-project, your planning directory contains:
- ```
- planning/
- ├── requirements.md # Your original input
- ├── deep_project_interview.md # Interview transcript
- ├── project-manifest.md # ★ Split structure & dependencies
- └── splits/
- ├── 01-auth-system/
- │ └── spec.md # Focused spec for auth
- ├── 02-billing/
- │ └── spec.md # Focused spec for billing
- └── 03-dashboard/
- └── spec.md # Focused spec for dashboard
- ```
- ### project-manifest.md
- The manifest contains:
- - Overview of all splits
- - Dependency graph
- - Recommended execution order
- - Machine-readable SPLIT_MANIFEST block
- ## Requirements
- - Claude Code
- - Python >= 3.11
- - uv package manager
- ### Python Dependencies
- Managed via `pyproject.toml` - no external API keys required (unlike `/deep-plan`).
- ## Best Practices
- 1. **Start with high-level requirements** - Don't over-specify. The interview surfaces details.
- 2. **Answer interview questions thoroughly** - Your mental model shapes the decomposition.
- 3. **Review the manifest carefully** - This is where you catch scope issues before they cascade.
- 4. **Prefer more splits over fewer** - Smaller, focused units are easier to plan and implement.
- 5. **Map dependencies explicitly** - Integration issues come from implicit assumptions.
- ## Troubleshooting
- ### "Requirements 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-step
- **Issue**: Context limit or manual interruption
- **Solution**:
- - Re-run `/deep-project @requirements.md`
- - The plugin detects completed steps and resumes
- ### "Session state conflict detected"
- **Issue**: Existing files conflict with current requirements
- **Solution**:
- - Choose "Start fresh" to begin new analysis
- - Or "Resume" to continue from where you stopped
- - If requirements changed significantly, start fresh
- ## Testing
- Run the test suite:
- ```bash
- cd /path/to/deep-project
- uv run pytest tests/
- ```
- ## Project Structure
- ```
- deep_project/
- ├── .claude-plugin/
- │ ├── plugin.json # Plugin metadata
- │ └── marketplace.json # Marketplace listing
- ├── LICENSE # MIT License
- ├── README.md # This file
- ├── pyproject.toml # Python dependencies
- ├── hooks/
- │ └── hooks.json # Session hooks
- ├── scripts/
- │ ├── checks/ # Setup & validation scripts
- │ ├── hooks/ # Hook implementations
- │ └── lib/ # Shared utilities
- ├── skills/
- │ └── deep-project/
- │ ├── SKILL.md # Main skill definition
- │ └── references/ # Protocol documents
- └── 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
- ## Version
- 0.2.1
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.