piercelamb/deep-project

Latest recorded source activity: March 5, 2026 at 01:22

SkillsMP catalog refreshed: November 5, 2026 at 19:57

skills collected: 1

GitHub stars: 222
GitHub forks: 30

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/piercelamb/deep-project.

Repository README

Repository README source: README.md

Read the source README

Expand full README

![deep-project hero](assets/hero.jpeg) # /deep-project, a Claude Code plugin ![Version](https://img.shields.io/badge/version-0.2.1-blue) ![Status](https://img.shields.io/badge/status-beta-orange) ![License](https://img.shields.io/badge/license-MIT-green) ![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple) ![Python](https://img.shields.io/badge/python-3.11%2B-blue) > **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

Loading the repository README…

Skills in this repository

Software Developers

1 occupation category · 100% classified

skill

occupation

description

updated

deep-project

Software Developers

Decomposes vague, high-level project requirements into well-scoped planning units for /deep-plan. Use when starting a new project that needs to be broken into manageable pieces.

2026-03-05

Showing 1 of 1 collected skill.