/deep-plan

name: deep-plan
description: Creates detailed, sectionized, TDD-oriented implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.
license: MIT
compatibility: Requires uv (Python 3.11+), Gemini or OpenAI API key for external review

Deep Planning Skill

Orchestrates a multi-step planning process: Research → Interview → External LLM Review → TDD Plan

CRITICAL: First Actions

**BEFORE using any other tools**, do these in order:

1. Print Intro and Validate Environment

Print intro banner immediately:

⚠️  CONTEXT WARNING: This workflow is token-intensive. Consider compacting first.

═══════════════════════════════════════════════════════════════
DEEP-PLAN: AI-Assisted Implementation Planning
═══════════════════════════════════════════════════════════════
Research → Interview → External LLM Review → TDD Plan

DEEP-PLAN starts by running `validate-env.sh`. This script:
  - Checks env for external LLM auth values
  - Validates external LLM access by running tiny prompt(s) programmatically

SECURITY:
  - `validate-env.sh` reads secret auth values in order to validate LLM access
  - It never publishes these values or exposes them to claude
  
 Note: DEEP-PLAN will write many .md files to the planning directory you pass it

**CRITICAL: Locate plugin root BEFORE running any scripts.**

The SessionStart hook injects `DEEP_PLUGIN_ROOT=<path>` into your context. Look for it now — it appears alongside `DEEP_SESSION_ID` in your context from session startup. Use it as `plugin_root` for all script paths.

**If `DEEP_PLUGIN_ROOT` is in your context**, run validate-env.sh directly:

bash <DEEP_PLUGIN_ROOT value>/scripts/checks/validate-env.sh

**Only if `DEEP_PLUGIN_ROOT` is NOT in your context** (hook didn't run), fall back to search:

find "$(pwd)" -name "validate-env.sh" -path "*/scripts/checks/*" -type f 2>/dev/null | head -1

If not found: `find ~ -name "validate-env.sh" -path "*/scripts/checks/*" -path "*deep*plan*" -type f 2>/dev/null | head -1` Then run: `bash <found_path>`

**Parse the JSON output:**

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "gemini_auth": "api_key",
  "openai_auth": true,
  "plugin_root": "/path/to/plugin"
}

**Store `plugin_root`** from the JSON output - it's used throughout the workflow.

2. Handle Environment Errors

If `valid == false`:

• Show the errors to the user

**If errors are critical** (uv not installed, plugin root not found):

• Stop the workflow. User must fix these before proceeding.

**If errors are ONLY about missing LLM credentials** (gemini_auth is null AND openai_auth is false):

AskUserQuestion:
  question: "No external LLMs configured. How should plan review be handled?"
  options:
    - label: "Use Claude Opus for review (Recommended)"
      description: "Launch an Opus subagent to review the plan"
    - label: "Exit to configure LLMs"
      description: "Stop to set up Gemini/OpenAI credentials"
    - label: "Skip external review"
      description: "Proceed without any external plan review"

**Store the choice as `review_mode`:**

• "Use Claude Opus" → `review_mode = "opus_subagent"`
• "Skip external review" → `review_mode = "skip"`
• Default (LLMs available) → `review_mode = "external_llm"`

Environment validated:
  Gemini: {gemini_auth or "not configured"}
  OpenAI: {openai_auth ? "configured" : "not configured"}
  Review mode: {review_mode}

3. Validate Spec File Input

**Check if user provided @file at invocation AND it's a spec file (ends with `.md`).**

If NO @file was provided OR the path doesn't end with `.md`, output this and STOP:

═══════════════════════════════════════════════════════════════
DEEP-PLAN: Spec File Required
═══════════════════════════════════════════════════════════════

This skill requires a markdown spec file path (must end with .md).
The planning directory is inferred from the spec file's parent directory.

To start a NEW plan:
  1. Create a markdown spec file describing what you want to build
  2. It can be as detailed or as vague as you like
  3. Place it in a directory where deep-plan can save planning files
  4. Run: /deep-plan @path/to/your-spec.md

To RESUME an existing plan:
  1. Run: /deep-plan @path/to/your-spec.md

Example: /deep-plan @planning/my-feature-spec.md
═══════════════════════════════════════════════════════════════

**Do not continue. Wait for user to re-invoke with a .md file path.**

4. Setup Planning Session

**First, check for session_id in your context.** Look for `DEEP_SESSION_ID=xxx` which was set by the SessionStart hook. This appears in your context from when the session started.

Run setup-planning-session.py with the spec file, plugin root, review mode, and session ID:

uv run {plugin_root}/scripts/checks/setup-planning-session.py \
  --file "<file_path>" \
  --plugin-root "{plugin_root}" \
  --review-mode "{review_mode}" \
  --session-id "{DEEP_SESSION_ID}"

**IMPORTANT:** If `DEEP_SESSION_ID` is in your context, you MUST pass it via `--session-id`. This ensures tasks work correctly after `/clear` commands. If it's not in your context, omit `--session-id` (fallback to env var).

Note: `review_mode` is from Step 2. If LLMs are available, use `external_llm` (or omit the flag).

**Parse the JSON output:**

This script: 1. Validates the spec file exists and has content 2. Creates `deep_plan_config.json` in the planning directory with `plugin_root`, `planning_dir`, and `initial_file` 3. Detects whether this is a new or resume session 4. Writes task files directly to `~/.claude/tasks/<task_list_id>/` 5. If `sections/index.md` exists, also writes section tasks (positions 22+)

**If `success == false`:** The script failed validation. Display the error and stop:

═══════════════════════════════════════════════════════════════
DEEP-PLAN: Setup Failed
═════════════════════════════════════