Skip to content
Back to search

deep-plan

Claude Code plugin that transforms vague requirements into detailed implementation plans via research, interviews, and multi-LLM review.

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-plan/badge.svg)](/listings/piercelamb--deep-plan)

HTML

<a href="/listings/piercelamb--deep-plan"><img src="/api/listings/piercelamb--deep-plan/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 spec file, run the command, answer questions.

**1. Create a spec file:**

*Option A: Use your editor* — Create `planning/auth-spec.md` with your feature description.

*Option B: Command line:*

mkdir -p planning
cat > planning/auth-spec.md << 'EOF'
# Authentication Feature
Add OAuth2 login with Google and GitHub providers.
Store sessions in Redis. Use JWT for API authentication.
EOF

Spec files can be as dense or as sparse as you like. I've used `/deep-plan` with a few bullet points and also used it with structured, thorough documents.

**2. Run deep-plan:**

/deep-plan @planning/auth-spec.md

**3. Follow the prompts** through Research → Interview → Review → Output

That's it. Your planning directory will contain a complete implementation plan with TDD stubs and parallelizable sections.

> **Token & Cost Note**: This workflow is token-intensive (research, multi-turn interview, review). Run `/compact` before starting. If using external LLM reviews (Gemini/OpenAI), those will incur API costs on your accounts.

If you /compact or exit in the middle, `/deep-plan` can recover from the existing 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. "source": "url",
  21. "url": "https://github.com/piercelamb/deep-project.git"
  22. },
  23. "category": "development",
  24. "homepage": "https://github.com/piercelamb/deep-project",
  25. "tags": ["planning", "decomposition", "project-management", "requirements"]
  26. },
  27. {
  28. "name": "deep-plan",
  29. "description": "AI-assisted deep planning with research, interview, external LLM review, and TDD approach",
  30. "version": "0.3.2",
  31. "author": {
  32. "name": "piercelamb",
  33. "url": "https://github.com/piercelamb"
  34. },
  35. "source": "./",
  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 · 552 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![deep-plan hero](assets/hero.jpeg)
  2. # /deep-plan, a Claude Code plugin
  3. ![Version](https://img.shields.io/badge/version-0.3.2-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. > - [Building /deep-plan](https://pierce-lamb.medium.com/building-deep-plan-a-claude-code-plugin-for-comprehensive-planning-30e0921eb841) - The story behind this plugin
  10. > - [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
  11. > - [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
  12. `/deep-plan` transforms vague feature requests into detailed, production-ready implementation plans through AI-assisted research, stakeholder interviews, and multi-LLM review.
  13. [`/deep-implement`](https://github.com/piercelamb/deep-implement), its companion plugin, takes these section files and implements them with TDD methodology, integrated code review, and atomic commits.
  14. For large projects with broad, vague requirements, use [`/deep-project`](https://github.com/piercelamb/deep-project) first to decompose into focused planning units before running `/deep-plan` on each.
  15. This plugin started as an effort to automate the most time-intensive part of my Claude Code workflow that I had previously been doing manually. It is primarily targeted at Claude Code users that don't have strict token constraints and prefer deep planning/plan review before implementation. It's designed to speed up creating production-ready code within Claude Code without sacrificing an understanding of how it works.
  16. ## TL;DR
  17. ```
  18. /plugin marketplace add piercelamb/deep-plan
  19. /plugin install deep-plan
  20. /plugin enable deep-plan
  21. /deep-plan @planning/auth-spec.md
  22. ```
  23. ## Table of Contents
  24. - [Overview](#overview)
  25. - [The Deep Trilogy](#the-deep-trilogy)
  26. - [Why deep-plan?](#why-deep-plan)
  27. - [When to Use](#when-to-use)
  28. - [Quick Start](#quick-start)
  29. - [How It Works](#how-it-works)
  30. - [Installation](#installation)
  31. - [Usage](#usage)
  32. - [Workflow Steps](#workflow-steps)
  33. - [Output Files](#output-files)
  34. - [Configuration](#configuration)
  35. - [Environment Variables](#environment-variables)
  36. - [Requirements](#requirements)
  37. - [Best Practices](#best-practices)
  38. - [Security & Privacy](#security--privacy)
  39. - [Troubleshooting](#troubleshooting)
  40. - [Testing](#testing)
  41. - [Project Structure](#project-structure)
  42. - [Contributing](#contributing)
  43. - [Changelog](#changelog)
  44. ## Overview
  45. **deep-plan** orchestrates a comprehensive planning workflow that ensures you think through implementation details *before* writing code:
  46. ```
  47. Research → Interview → External LLM Review → TDD Plan → Section Splitting
  48. ```
  49. The plugin guides you through:
  50. - **Research Phase**: Analyze existing codebases and research the web for current best practices
  51. - **Interview Phase**: Structured Q&A to surface hidden requirements and edge cases
  52. - **External Review**: Independent feedback from Gemini, OpenAI, or an Opus subagent on your plan
  53. - **TDD Phase**: Define test stubs before implementation
  54. - **Section Phase**: Split into parallelizable, self-contained implementation units (written in parallel via subagents)
  55. By the end, you have a complete planning directory with specs, research, reviews, and small, isolated implementation sections that any engineer (or Claude) can pick up cold.
  56. ## The Deep Trilogy
  57. This plugin is part of a three-plugin pipeline for turning ideas into production code:
  58. ```
  59. /deep-project (decompose) → /deep-plan (plan) → /deep-implement (build)
  60. ```
  61. ```
  62. ┌───────────────────────────────────────────────────────────────────┐
  63. │ THE DEEP TRILOGY │
  64. │ From Vague Idea to Production Code │
  65. ├───────────────────────────────────────────────────────────────────┤
  66. │ │
  67. │ "I want to build a SaaS platform" │
  68. │ │ │
  69. │ ▼ │
  70. │ ┌─────────────────────────────────────┐ │
  71. │ │ /deep-project │ │
  72. │ └─────────────────────────────────────┘ │
  73. │ │ │ │ │
  74. │ ▼ ▼ ▼ │
  75. │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
  76. │ │ 01-auth │ │ 02-bill │ │ ... │ │
  77. │ │ spec.md │ │ spec.md │ │ │ │
  78. │ └─────────┘ └─────────┘ └─────────┘ │
  79. │ │ │ │ │
  80. │ ▼ ▼ ▼ │
  81. │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
  82. │ │ /deep- │ │ /deep- │ │ ... │ ◀── YOU ARE HERE │
  83. │ │ plan │ │ plan │ │ │ │
  84. │ └─────────┘ └─────────┘ └─────────┘ │
  85. │ │ │ │ │ │ │ │
  86. │ ▼ ▼ ▼ ▼ ▼ ▼ │
  87. │ ┌────┐┌────┐┌────┐┌────┐┌────┐┌─────────┐ │
  88. │ │ 01 ││ 02 ││ 01 ││ 02 ││ 03 ││ ... │ │
  89. │ └────┘└────┘└────┘└────┘└────┘└─────────┘ │
  90. │ │ │ │ │ │ │ │
  91. │ └─┬──┘ └──┬──┴────┘ │ │
  92. │ │ │ │ │
  93. │ ▼ ▼ ▼ │
  94. │ ┌─────────┐┌─────────┐ ┌─────────┐ │
  95. │ │ /deep- ││ /deep- │ │ ... │ │
  96. │ │implement││implement│ │ │ │
  97. │ └─────────┘└─────────┘ └─────────┘ │
  98. │ │ │ │ │
  99. │ ▼ ▼ ▼ │
  100. │ ┌─────────┐┌─────────┐ ┌─────────┐ │
  101. │ │ auth ││ billing │ │ ... │ │
  102. │ │ code ││ code │ │ │ │
  103. │ └─────────┘└─────────┘ └─────────┘ │
  104. │ │ │ │ │
  105. │ └──────────┴──────────────────┘ │
  106. │ │ │
  107. │ ▼ │
  108. │ Production Codebase │
  109. │ │
  110. └───────────────────────────────────────────────────────────────────┘
  111. ```
  112. | Plugin | Purpose | Input | Output |
  113. |--------|---------|-------|--------|
  114. | [`/deep-project`](https://github.com/piercelamb/deep-project) | Decompose | Vague requirements | Focused spec files |
  115. | [`/deep-plan`](https://github.com/piercelamb/deep-plan) | Plan | Spec file | Section files with TDD |
  116. | [`/deep-implement`](https://github.com/piercelamb/deep-implement) | Build | Section files | Production code |
  117. **Where to start?**
  118. - **Vague multi-component project?** Start with [`/deep-project`](https://github.com/piercelamb/deep-project)
  119. - **Single focused feature?** Start here with `/deep-plan`
  120. - **Already have section files?** Skip to [`/deep-implement`](https://github.com/piercelamb/deep-implement)
  121. ## Why deep-plan?
  122. ### Without deep-plan
  123. ```
  124. You: "Claude, build me an auth system"
  125. Claude: *immediately starts coding*
  126. Result: Multiple iterations, missed requirements, rework
  127. ```
  128. ### With deep-plan
  129. ```
  130. You: "/deep-plan @planning/auth-spec.md"
  131. deep-plan: Research → Interview → External Review → TDD Plan → Sections
  132. Result: Complete implementation plan reviewed by multiple LLMs, split into chunks that keep the context window monsters at bay
  133. ```
  134. **Time Investment**: ~30 minutes of interview + review
  135. **Time Saved**: Hours of rework and missed requirements
  136. ## When to Use
  137. **Use deep-plan when:**
  138. - You want to maintain a mental model of what's being created
  139. - Requirements are vague and need fleshing out
  140. - You want external validation before investing implementation time
  141. - The feature is complex enough to benefit from deep planning
  142. **Skip deep-plan when:**
  143. - Simple bug fixes or one-file changes
  144. - Requirements are already crystal clear
  145. - Time pressure prevents thorough planning
  146. - You are ready to open the Ralph Wiggum flood gates
  147. ## Quick Start
  148. > **TL;DR**: Create a spec file, run the command, answer questions.
  149. **1. Create a spec file:**
  150. *Option A: Use your editor* — Create `planning/auth-spec.md` with your feature description.
  151. *Option B: Command line:*
  152. ```bash
  153. mkdir -p planning
  154. cat > planning/auth-spec.md << 'EOF'
  155. # Authentication Feature
  156. Add OAuth2 login with Google and GitHub providers.
  157. Store sessions in Redis. Use JWT for API authentication.
  158. EOF
  159. ```
  160. Spec files can be as dense or as sparse as you like. I've used `/deep-plan` with a few bullet points and also used it with structured, thorough documents.
  161. **2. Run deep-plan:**
  162. ```
  163. /deep-plan @planning/auth-spec.md
  164. ```
  165. **3. Follow the prompts** through Research → Interview → Review → Output
  166. That's it. Your planning directory will contain a complete implementation plan with TDD stubs and parallelizable sections.
  167. > **Token & Cost Note**: This workflow is token-intensive (research, multi-turn interview, review). Run `/compact` before starting. If using external LLM reviews (Gemini/OpenAI), those will incur API costs on your accounts.
  168. If you /compact or exit in the middle, `/deep-plan` can recover from the existing files.
  169. ## How It Works
  170. ```
  171. ┌─────────────────────────────────────────────────────────────────┐
  172. │ deep-plan workflow │
  173. ├─────────────────────────────────────────────────────────────────┤
  174. │ │
  175. │ /deep-plan @spec.md │
  176. │ │ │
  177. │ ▼ │
  178. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  179. │ │ Research │ ──▶ │ Interview │ ──▶ │ Spec │ │
  180. │ │ (optional) │ │ (5-10 Q&A) │ │ Synthesis │ │
  181. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  182. │ │ │
  183. │ ▼ │
  184. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  185. │ │ Section │ ◀── │ TDD Plan │ ◀── │ External │ │
  186. │ │ Splitting │ │ Generation │ │ LLM Review │ │
  187. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  188. │ │ │
  189. │ ▼ │
  190. │ ┌──────────────────────────────────────────────────────────┐ │
  191. │ │ sections/section-01-*.md sections/section-02-*.md ... │ │
  192. │ │ (Self-contained, parallel-ready implementation units) │ │
  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. - (Optional) External LLM API key for review:
  203. - **Gemini**: `GEMINI_API_KEY` ([get one](https://aistudio.google.com/apikey)) or Google Cloud ADC credentials
  204. - **OpenAI**: `OPENAI_API_KEY` ([get one](https://platform.openai.com/api-keys))
  205. - If no external keys configured, review can be performed via Opus subagent
  206. ### Install via Marketplace (Recommended)
  207. **Option A: CLI commands**
  208. ```
  209. /plugin marketplace add piercelamb/deep-plan
  210. /plugin install deep-plan
  211. /plugin enable deep-plan
  212. ```
  213. **Option B: Via UI**
  214. ```
  215. /plugin marketplace add piercelamb/deep-plan
  216. /plugin install deep-plan
  217. /plugins
  218. ```
  219. Then scroll to "Installed", find `deep-plan`, and click "Enable".
  220. > **Already installed `/deep-project` 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-plan` directly — no need to add another marketplace.
  221. ### Manual Installation
  222. **Option A: Via settings.json**
  223. Clone the repo, then add to your project's `.claude/settings.json`:
  224. ```bash
  225. git clone https://github.com/piercelamb/deep-plan.git /path/to/deep-plan
  226. ```
  227. ```json
  228. {
  229. "plugins": {
  230. "paths": ["/path/to/deep-plan"]
  231. }
  232. }
  233. ```
  234. **Option B: Via --plugin-dir flag (development/testing)**
  235. ```bash
  236. git clone https://github.com/piercelamb/deep-plan.git /path/to/deep-plan
  237. claude --plugin-dir /path/to/deep-plan
  238. ```
  239. ### Configure API Keys (Optional)
  240. For external LLM review via Gemini or OpenAI, set API keys. See [Environment Variables](#environment-variables) for all options.
  241. ```bash
  242. export OPENAI_API_KEY="your-key" # For OpenAI/ChatGPT
  243. export GEMINI_API_KEY="your-key" # For Gemini
  244. ```
  245. The plugin also supports Application Default Credentials (ADC) for Gemini. If you use ADC, you'll need to set `GOOGLE_CLOUD_LOCATION` or set your project's location in the plugin's `config.json` file.
  246. If no external LLM keys are configured, the plugin can perform review via an Opus subagent instead.
  247. The plugin validates your configuration when `/deep-plan` first runs.
  248. ## Usage
  249. ### Basic Invocation
  250. ```
  251. /deep-plan @path/to/your-spec.md
  252. ```
  253. The spec file can be as detailed or vague as you like. The planning directory is inferred from the spec file's parent directory.
  254. ### Resuming
  255. If the workflow is interrupted (context limit, user pause), follow Claude's instructions or simply re-run with the same spec file:
  256. ```
  257. /deep-plan @planning/auth-spec.md
  258. ```
  259. The plugin detects existing artifacts and resumes from the appropriate step.
  260. ## Workflow Steps
  261. The plugin runs a multi-phase workflow:
  262. | Phase | What Happens |
  263. |-------|--------------|
  264. | **Setup** | Validate environment, check spec file, initialize session |
  265. | **Research** | Codebase exploration, web research (optional, based on your choices) |
  266. | **Interview** | Structured Q&A to clarify requirements |
  267. | **Planning** | Synthesize spec, generate implementation plan |
  268. | **Review** | External LLM review (Gemini/OpenAI or Opus subagent), integrate feedback, user review |
  269. | **TDD** | Generate test stubs mirroring plan structure |
  270. | **Sections** | Split into implementation sections, generate files in parallel via subagents |
  271. ## Output Files
  272. After running deep-plan, your planning directory contains:
  273. ```
  274. planning/
  275. ├── your-spec.md # Your original input
  276. ├── deep_plan_config.json # Session state (for resume)
  277. ├── claude-research.md # Web + codebase research findings
  278. ├── claude-interview.md # Q&A transcript
  279. ├── claude-spec.md # Synthesized specification
  280. ├── claude-plan.md # ★ Primary deliverable
  281. ├── claude-integration-notes.md # Feedback integration decisions
  282. ├── claude-plan-tdd.md # Test stubs
  283. ├── reviews/
  284. │ ├── gemini-review.md # Gemini feedback (if using Gemini)
  285. │ ├── openai-review.md # OpenAI feedback (if using OpenAI)
  286. │ └── opus-review.md # Opus subagent feedback (if no external LLMs)
  287. └── sections/
  288. ├── index.md # Section manifest
  289. ├── section-01-*.md # Implementation unit 1
  290. ├── section-02-*.md # Implementation unit 2
  291. └── ...
  292. ```
  293. ## Configuration
  294. Edit `config.json` at the plugin root:
  295. ```json
  296. {
  297. "context": {
  298. "check_enabled": true
  299. },
  300. "vertex_ai": {
  301. "project": null,
  302. "location": null
  303. },
  304. "external_review": {
  305. "alert_if_missing": true,
  306. "feedback_iterations": 1
  307. },
  308. "models": {
  309. "gemini": "gemini-3-pro-preview",
  310. "chatgpt": "gpt-5.2"
  311. },
  312. "llm_client": {
  313. "timeout_seconds": 120,
  314. "max_retries": 3
  315. }
  316. }
  317. ```
  318. | Setting | Default | Purpose |
  319. |---------|---------|---------|
  320. | `context.check_enabled` | `true` | Prompt before token-intensive operations |
  321. | `vertex_ai.project` | `null` | GCP project for Vertex AI (falls back to gcloud config) |
  322. | `vertex_ai.location` | `null` | GCP location for Vertex AI (falls back to `GOOGLE_CLOUD_LOCATION`) |
  323. | `external_review.alert_if_missing` | `true` | Warn if no LLM API keys configured |
  324. | `models.gemini` | `gemini-3-pro-preview` | Gemini model for external review |
  325. | `models.chatgpt` | `gpt-5.2` | OpenAI model for external review |
  326. | `llm_client.timeout_seconds` | `120` | API call timeout |
  327. | `llm_client.max_retries` | `3` | Retry attempts for transient errors |
  328. ## Environment Variables
  329. ### Gemini (choose one)
  330. - `GEMINI_API_KEY` - [AI Studio API key](https://aistudio.google.com/apikey)
  331. - `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account JSON
  332. - Default ADC at `~/.config/gcloud/application_default_credentials.json` ([setup guide](https://cloud.google.com/docs/authentication/application-default-credentials))
  333. For Vertex AI, also set (or set in `config.json`):
  334. - `GOOGLE_CLOUD_PROJECT`
  335. - `GOOGLE_CLOUD_LOCATION`
  336. ### OpenAI
  337. - `OPENAI_API_KEY` - [OpenAI API key](https://platform.openai.com/api-keys)
  338. ## Requirements
  339. - Claude Code
  340. - Python >= 3.11
  341. - uv package manager
  342. - (Optional) External LLM API key (Gemini or OpenAI) for external review
  343. ### Python Dependencies
  344. Managed via `pyproject.toml`:
  345. - `google-genai >= 1.0.0`
  346. - `openai >= 1.0.0`
  347. ## Best Practices
  348. 1. **Start with a spec file** - Even a vague one. The interview phase will extract details.
  349. 2. **Answer interview questions thoroughly** - This is where requirements get surfaced.
  350. 3. **Review external feedback critically** - LLM reviewers catch blind spots but may suggest unnecessary complexity.
  351. 4. **Use sections for parallel work** - Each section file is self-contained. Multiple engineers (or Claude sessions) can work in parallel.
  352. 5. **Compact before starting** - The workflow is token-intensive. Start with a fresh or compacted context.
  353. ## Security & Privacy
  354. ### What deep-plan does with your data
  355. - **Spec files**: Read by Claude.
  356. - **Interview answers**: Stored locally in your planning directory and read by Claude.
  357. - **External LLM review**: The integrated plan Claude creates is sent to Gemini/OpenAI for review (you control which LLMs)
  358. ### API Key Handling
  359. Your API keys (`GEMINI_API_KEY`, `OPENAI_API_KEY`) are:
  360. - Read only by `validate-env.sh` to confirm connectivity
  361. - Never logged or transmitted by deep-plan code
  362. - Passed directly to official SDKs ([google-genai](https://pypi.org/project/google-genai/), [openai](https://pypi.org/project/openai/))
  363. ## Troubleshooting
  364. ### "No external LLM configured"
  365. **Issue**: validate-env.sh reports no Gemini or OpenAI auth
  366. **Solution** (choose one):
  367. - Set `GEMINI_API_KEY` or `OPENAI_API_KEY` environment variable
  368. - Configure Google Cloud ADC: `gcloud auth application-default login`
  369. - Continue without external keys—the plugin will offer Opus subagent review instead
  370. ### "Spec file not found"
  371. **Issue**: The @file path doesn't exist
  372. **Solution**:
  373. - Ensure the file path is correct and the file exists
  374. - Use absolute paths if relative paths aren't resolving
  375. ### Workflow interrupted mid-section
  376. **Issue**: Context limit hit during section generation
  377. **Solution**:
  378. - Follow Claude's instructions or
  379. - Re-run `/deep-plan @your-spec.md`
  380. - The plugin detects completed sections and resumes from the next one
  381. ### External review timeout
  382. **Issue**: LLM API calls timing out
  383. **Solution**:
  384. - Increase `llm_client.timeout_seconds` in config.json
  385. - Check your API quotas and rate limits
  386. ## Testing
  387. Run the test suite:
  388. ```bash
  389. cd /path/to/deep-plan
  390. uv run pytest tests/
  391. ```
  392. ## Project Structure
  393. ```
  394. deep_plan/
  395. ├── .claude-plugin/plugin.json # Plugin metadata
  396. ├── config.json # Global configuration
  397. ├── LICENSE # MIT License
  398. ├── README.md # This file
  399. ├── pyproject.toml # Python dependencies
  400. ├── scripts/
  401. │ ├── checks/ # Validation & setup scripts
  402. │ ├── lib/ # Shared utilities
  403. │ └── llm_clients/ # External LLM integration
  404. ├── skills/
  405. │ └── deep-plan/
  406. │ ├── SKILL.md # Main skill definition
  407. │ └── references/ # Protocol documents
  408. ├── prompts/ # LLM review prompts
  409. └── tests/ # Test suite
  410. ```
  411. ## Contributing
  412. Contributions welcome! Please:
  413. 1. Clone the repository
  414. 2. Create a feature branch
  415. 3. Run tests: `uv run pytest tests/`
  416. 4. Submit a pull request
  417. ## License
  418. [MIT](./LICENSE)
  419. ## Author
  420. Pierce Lamb
  421. ## Changelog
  422. See [CHANGELOG.md](CHANGELOG.md) for release history.
  423. ## Version
  424. 0.3.2

Ratings and comments

Sign in to rate this skill.

Sign in

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