Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/piercelamb--deep-project/badge.svg)](/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

i

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)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "piercelamb-plugins",
  4. "description": "Claude Code plugins by Pierce Lamb",
  5. "version": "1.1.7",
  6. "owner": {
  7. "name": "Pierce Lamb",
  8. "url": "https://github.com/piercelamb"
  9. },
  10. "plugins": [
  11. {
  12. "name": "deep-project",
  13. "description": "Split vague project requirements into well-scoped units for /deep-plan",
  14. "version": "0.2.1",
  15. "author": {
  16. "name": "piercelamb",
  17. "url": "https://github.com/piercelamb"
  18. },
  19. "source": "./",
  20. "category": "development",
  21. "homepage": "https://github.com/piercelamb/deep-project",
  22. "tags": ["planning", "decomposition", "project-management", "requirements"]
  23. },
  24. {
  25. "name": "deep-plan",
  26. "description": "AI-assisted deep planning with research, interview, external LLM review, and TDD approach",
  27. "version": "0.3.2",
  28. "author": {
  29. "name": "piercelamb",
  30. "url": "https://github.com/piercelamb"
  31. },
  32. "source": {
  33. "source": "url",
  34. "url": "https://github.com/piercelamb/deep-plan.git"
  35. },
  36. "category": "development",
  37. "homepage": "https://github.com/piercelamb/deep-plan",
  38. "tags": ["planning", "tdd", "architecture", "llm-review", "implementation"]
  39. },
  40. {
  41. "name": "deep-implement",
  42. "description": "Implement code from /deep-plan sections with TDD, code review, and git workflow",
  43. "version": "0.2.1",
  44. "author": {
  45. "name": "piercelamb",
  46. "url": "https://github.com/piercelamb"
  47. },
  48. "source": {
  49. "source": "url",
  50. "url": "https://github.com/piercelamb/deep-implement.git"
  51. },
  52. "category": "development",
  53. "homepage": "https://github.com/piercelamb/deep-implement",
  54. "tags": ["implementation", "tdd", "code-review", "git", "workflow"]
  55. },
  56. {
  57. "name": "deep-sota",
  58. "description": "Paper- and repo-grounded research over the lodestone knowledge base",
  59. "version": "0.2.1",
  60. "author": {
  61. "name": "piercelamb",
  62. "url": "https://github.com/piercelamb"
  63. },
  64. "source": {
  65. "source": "url",
  66. "url": "https://github.com/piercelamb/deep-sota.git"
  67. },
  68. "category": "research",
  69. "homepage": "https://github.com/piercelamb/deep-sota",
  70. "tags": ["research", "arxiv", "rag", "knowledge-base", "lodestone"]
  71. },
  72. {
  73. "name": "lodestone",
  74. "description": "Local research corpus over arXiv papers, blog posts, and code repos with paper-grounded MCP search/read tools",
  75. "version": "0.4.0",
  76. "author": {
  77. "name": "piercelamb",
  78. "url": "https://github.com/piercelamb"
  79. },
  80. "source": {
  81. "source": "url",
  82. "url": "https://github.com/piercelamb/lodestone.git"
  83. },
  84. "category": "research",
  85. "homepage": "https://github.com/piercelamb/lodestone",
  86. "tags": ["mcp", "arxiv", "rag", "research", "knowledge-base"]
  87. }
  88. ]
  89. }
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)

  1. ![deep-project hero](assets/hero.jpeg)
  2. # /deep-project, a Claude Code plugin
  3. ![Version](https://img.shields.io/badge/version-0.2.1-blue)
  4. ![Status](https://img.shields.io/badge/status-beta-orange)
  5. ![License](https://img.shields.io/badge/license-MIT-green)
  6. ![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple)
  7. ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
  8. > **Blog posts:**
  9. > - [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
  10. > - [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
  11. `/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).
  12. 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.
  13. 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.
  14. ## TL;DR
  15. ```
  16. /plugin marketplace add piercelamb/deep-project
  17. /plugin install deep-project
  18. /plugin enable deep-project
  19. /deep-project @planning/requirements.md
  20. ```
  21. ## Table of Contents
  22. - [Overview](#overview)
  23. - [The Deep Trilogy](#the-deep-trilogy)
  24. - [Why deep-project?](#why-deep-project)
  25. - [When to Use](#when-to-use)
  26. - [Quick Start](#quick-start)
  27. - [How It Works](#how-it-works)
  28. - [Installation](#installation)
  29. - [Usage](#usage)
  30. - [Workflow Steps](#workflow-steps)
  31. - [Output Files](#output-files)
  32. - [Requirements](#requirements)
  33. - [Best Practices](#best-practices)
  34. - [Troubleshooting](#troubleshooting)
  35. - [Testing](#testing)
  36. - [Project Structure](#project-structure)
  37. - [Contributing](#contributing)
  38. ## Overview
  39. **deep-project** orchestrates a decomposition workflow that breaks large projects into manageable pieces *before* detailed planning:
  40. ```
  41. Interview → Split Analysis → Dependency Mapping → Directory Creation → Spec Generation
  42. ```
  43. The plugin guides you through:
  44. - **Interview Phase**: Structured Q&A to understand your mental model of the project
  45. - **Split Analysis**: Determine if the project benefits from multiple planning units
  46. - **Dependency Discovery**: Map relationships between splits
  47. - **Spec Generation**: Create focused spec files for each unit
  48. 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`.
  49. ## The Deep Trilogy
  50. This plugin is part of a three-plugin pipeline for turning ideas into production code:
  51. ```
  52. /deep-project (decompose) → /deep-plan (plan) → /deep-implement (build)
  53. ```
  54. ```
  55. ┌───────────────────────────────────────────────────────────────────┐
  56. │ THE DEEP TRILOGY │
  57. │ From Vague Idea to Production Code │
  58. ├───────────────────────────────────────────────────────────────────┤
  59. │ │
  60. │ "I want to build a SaaS platform" │
  61. │ │ │
  62. │ ▼ │
  63. │ ┌─────────────────────────────────────┐ │
  64. │ │ /deep-project │ ◀── YOU ARE HERE │
  65. │ └─────────────────────────────────────┘ │
  66. │ │ │ │ │
  67. │ ▼ ▼ ▼ │
  68. │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
  69. │ │ 01-auth │ │ 02-bill │ │ ... │ │
  70. │ │ spec.md │ │ spec.md │ │ │ │
  71. │ └─────────┘ └─────────┘ └─────────┘ │
  72. │ │ │ │ │
  73. │ ▼ ▼ ▼ │
  74. │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
  75. │ │ /deep- │ │ /deep- │ │ ... │ │
  76. │ │ plan │ │ plan │ │ │ │
  77. │ └─────────┘ └─────────┘ └─────────┘ │
  78. │ │ │ │ │ │ │ │
  79. │ ▼ ▼ ▼ ▼ ▼ ▼ │
  80. │ ┌────┐┌────┐┌────┐┌────┐┌────┐┌─────────┐ │
  81. │ │ 01 ││ 02 ││ 01 ││ 02 ││ 03 ││ ... │ │
  82. │ └────┘└────┘└────┘└────┘└────┘└─────────┘ │
  83. │ │ │ │ │ │ │ │
  84. │ └─┬──┘ └──┬──┴────┘ │ │
  85. │ │ │ │ │
  86. │ ▼ ▼ ▼ │
  87. │ ┌─────────┐┌─────────┐ ┌─────────┐ │
  88. │ │ /deep- ││ /deep- │ │ ... │ │
  89. │ │implement││implement│ │ │ │
  90. │ └─────────┘└─────────┘ └─────────┘ │
  91. │ │ │ │ │
  92. │ ▼ ▼ ▼ │
  93. │ ┌─────────┐┌─────────┐ ┌─────────┐ │
  94. │ │ auth ││ billing │ │ ... │ │
  95. │ │ code ││ code │ │ │ │
  96. │ └─────────┘└─────────┘ └─────────┘ │
  97. │ │ │ │ │
  98. │ └──────────┴──────────────────┘ │
  99. │ │ │
  100. │ ▼ │
  101. │ Production Codebase │
  102. │ │
  103. └───────────────────────────────────────────────────────────────────┘
  104. ```
  105. | Plugin | Purpose | Input | Output |
  106. |--------|---------|-------|--------|
  107. | [`/deep-project`](https://github.com/piercelamb/deep-project) | Decompose | Vague requirements | Focused spec files |
  108. | [`/deep-plan`](https://github.com/piercelamb/deep-plan) | Plan | Spec file | Section files with TDD |
  109. | [`/deep-implement`](https://github.com/piercelamb/deep-implement) | Build | Section files | Production code |
  110. **Where to start?**
  111. - **Vague multi-component project?** Start here with `/deep-project`
  112. - **Single focused feature?** Skip to [`/deep-plan`](https://github.com/piercelamb/deep-plan)
  113. - **Already have section files?** Skip to [`/deep-implement`](https://github.com/piercelamb/deep-implement)
  114. ## Why deep-project?
  115. ### Without deep-project
  116. ```
  117. You: "Claude, I need to build a complete SaaS platform"
  118. Claude: *overwhelmed by scope, makes assumptions, misses critical relationships*
  119. Result: Inconsistent implementation, integration issues, rework
  120. ```
  121. ### With deep-project
  122. ```
  123. You: "/deep-project @planning/saas-requirements.md"
  124. deep-project: Interview → Split Analysis → Manifest → Spec Files
  125. Result:
  126. - 01-auth-system/spec.md
  127. - 02-billing-integration/spec.md
  128. - 03-user-dashboard/spec.md
  129. Each ready for focused /deep-plan sessions
  130. ```
  131. **Time Investment**: ~15 minutes of interview
  132. **Time Saved**: Hours of coordination and rework from poorly scoped planning
  133. ## When to Use
  134. **Use deep-project when:**
  135. - Your project has multiple distinct subsystems
  136. - Requirements are vague and need decomposition
  137. - You want to parallelize planning across multiple focused sessions
  138. - Dependencies between components need explicit mapping
  139. **Skip deep-project when:**
  140. - The project is already a single, well-defined feature
  141. - Requirements are clear and bounded
  142. - You're doing a bug fix or small enhancement
  143. - You already have well-scoped spec files
  144. - Even in these cases, /deep-project will scope the project to a single component.
  145. ## Quick Start
  146. > **TL;DR**: Create a requirements file, run the command, answer questions.
  147. **1. Create a requirements file:**
  148. *Option A: Use your editor* — Create `planning/requirements.md` with your project description.
  149. *Option B: Command line:*
  150. ```bash
  151. mkdir -p planning
  152. cat > planning/requirements.md << 'EOF'
  153. # My SaaS Platform
  154. Build a complete SaaS platform with:
  155. - User authentication (OAuth, email/password)
  156. - Subscription billing
  157. - Admin dashboard
  158. - User-facing dashboard
  159. - API for third-party integrations
  160. EOF
  161. ```
  162. Requirements files can be as detailed or vague as you like. The interview phase will extract specifics.
  163. **2. Run deep-project:**
  164. ```
  165. /deep-project @planning/requirements.md
  166. ```
  167. **3. Follow the prompts** through Interview → Split Analysis → Confirmation → Generation
  168. That's it. Your planning directory will contain numbered split directories with focused spec files.
  169. ## How It Works
  170. ```
  171. ┌─────────────────────────────────────────────────────────────────┐
  172. │ deep-project workflow │
  173. ├─────────────────────────────────────────────────────────────────┤
  174. │ │
  175. │ /deep-project @requirements.md │
  176. │ │ │
  177. │ ▼ │
  178. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  179. │ │ Interview │ ──▶ │ Split │ ──▶ │ Dependency │ │
  180. │ │ (adaptive) │ │ Analysis │ │ Mapping │ │
  181. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  182. │ │ │
  183. │ ▼ │
  184. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  185. │ │ Spec │ ◀── │ Directory │ ◀── │ User │ │
  186. │ │ Generation │ │ Creation │ │ Confirmation │ │
  187. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  188. │ │ │
  189. │ ▼ │
  190. │ ┌──────────────────────────────────────────────────────────┐ │
  191. │ │ 01-auth/spec.md 02-billing/spec.md 03-dashboard/... │ │
  192. │ │ (Focused planning units ready for /deep-plan) │ │
  193. │ └──────────────────────────────────────────────────────────┘ │
  194. │ │
  195. └─────────────────────────────────────────────────────────────────┘
  196. ```
  197. ## Installation
  198. ### Prerequisites
  199. - [Claude Code](https://claude.ai/code) installed
  200. - [uv](https://docs.astral.sh/uv/) (Python package manager)
  201. - Python 3.11+
  202. ### Install via Marketplace (Recommended)
  203. **Option A: CLI commands**
  204. ```
  205. /plugin marketplace add piercelamb/deep-project
  206. /plugin install deep-project
  207. /plugin enable deep-project
  208. ```
  209. **Option B: Via UI**
  210. ```
  211. /plugin marketplace add piercelamb/deep-project
  212. /plugin install deep-project
  213. /plugins
  214. ```
  215. Then scroll to "Installed", find `deep-project`, and click "Enable".
  216. > **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.
  217. ### Manual Installation
  218. **Option A: Via settings.json**
  219. Clone the repo, then add to your project's `.claude/settings.json`:
  220. ```bash
  221. git clone https://github.com/piercelamb/deep-project.git /path/to/deep-project
  222. ```
  223. ```json
  224. {
  225. "plugins": {
  226. "paths": ["/path/to/deep-project"]
  227. }
  228. }
  229. ```
  230. **Option B: Via --plugin-dir flag (development/testing)**
  231. ```bash
  232. git clone https://github.com/piercelamb/deep-project.git /path/to/deep-project
  233. claude --plugin-dir /path/to/deep-project
  234. ```
  235. ## Usage
  236. ### Basic Invocation
  237. ```
  238. /deep-project @path/to/requirements.md
  239. ```
  240. The requirements file can be as detailed or vague as you like. The planning directory is inferred from the requirements file's parent directory.
  241. ### Resuming
  242. If the workflow is interrupted (context limit, user pause), re-run with the same requirements file:
  243. ```
  244. /deep-project @planning/requirements.md
  245. ```
  246. The plugin detects existing artifacts and resumes from the appropriate step.
  247. ## Workflow Steps
  248. | Phase | What Happens |
  249. |-------|--------------|
  250. | **Setup** | Validate input, check for existing session, initialize |
  251. | **Interview** | Adaptive Q&A to understand project scope and relationships |
  252. | **Split Analysis** | Determine if project benefits from multiple units |
  253. | **Dependency Mapping** | Identify relationships and execution order |
  254. | **User Confirmation** | Present proposed structure for approval |
  255. | **Directory Creation** | Create numbered split directories |
  256. | **Spec Generation** | Write focused spec.md for each split |
  257. ## Output Files
  258. After running deep-project, your planning directory contains:
  259. ```
  260. planning/
  261. ├── requirements.md # Your original input
  262. ├── deep_project_interview.md # Interview transcript
  263. ├── project-manifest.md # ★ Split structure & dependencies
  264. └── splits/
  265. ├── 01-auth-system/
  266. │ └── spec.md # Focused spec for auth
  267. ├── 02-billing/
  268. │ └── spec.md # Focused spec for billing
  269. └── 03-dashboard/
  270. └── spec.md # Focused spec for dashboard
  271. ```
  272. ### project-manifest.md
  273. The manifest contains:
  274. - Overview of all splits
  275. - Dependency graph
  276. - Recommended execution order
  277. - Machine-readable SPLIT_MANIFEST block
  278. ## Requirements
  279. - Claude Code
  280. - Python >= 3.11
  281. - uv package manager
  282. ### Python Dependencies
  283. Managed via `pyproject.toml` - no external API keys required (unlike `/deep-plan`).
  284. ## Best Practices
  285. 1. **Start with high-level requirements** - Don't over-specify. The interview surfaces details.
  286. 2. **Answer interview questions thoroughly** - Your mental model shapes the decomposition.
  287. 3. **Review the manifest carefully** - This is where you catch scope issues before they cascade.
  288. 4. **Prefer more splits over fewer** - Smaller, focused units are easier to plan and implement.
  289. 5. **Map dependencies explicitly** - Integration issues come from implicit assumptions.
  290. ## Troubleshooting
  291. ### "Requirements file not found"
  292. **Issue**: The @file path doesn't exist
  293. **Solution**:
  294. - Ensure the file path is correct and the file exists
  295. - Use absolute paths if relative paths aren't resolving
  296. ### Workflow interrupted mid-step
  297. **Issue**: Context limit or manual interruption
  298. **Solution**:
  299. - Re-run `/deep-project @requirements.md`
  300. - The plugin detects completed steps and resumes
  301. ### "Session state conflict detected"
  302. **Issue**: Existing files conflict with current requirements
  303. **Solution**:
  304. - Choose "Start fresh" to begin new analysis
  305. - Or "Resume" to continue from where you stopped
  306. - If requirements changed significantly, start fresh
  307. ## Testing
  308. Run the test suite:
  309. ```bash
  310. cd /path/to/deep-project
  311. uv run pytest tests/
  312. ```
  313. ## Project Structure
  314. ```
  315. deep_project/
  316. ├── .claude-plugin/
  317. │ ├── plugin.json # Plugin metadata
  318. │ └── marketplace.json # Marketplace listing
  319. ├── LICENSE # MIT License
  320. ├── README.md # This file
  321. ├── pyproject.toml # Python dependencies
  322. ├── hooks/
  323. │ └── hooks.json # Session hooks
  324. ├── scripts/
  325. │ ├── checks/ # Setup & validation scripts
  326. │ ├── hooks/ # Hook implementations
  327. │ └── lib/ # Shared utilities
  328. ├── skills/
  329. │ └── deep-project/
  330. │ ├── SKILL.md # Main skill definition
  331. │ └── references/ # Protocol documents
  332. └── tests/ # Test suite
  333. ```
  334. ## Contributing
  335. Contributions welcome! Please:
  336. 1. Clone the repository
  337. 2. Create a feature branch
  338. 3. Run tests: `uv run pytest tests/`
  339. 4. Submit a pull request
  340. ## License
  341. [MIT](./LICENSE)
  342. ## Author
  343. Pierce Lamb
  344. ## Version
  345. 0.2.1

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.