deep-plan

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
═══════════════════════════════════════════════════════════════
Error: {error}

Please fix the issue and re-run: /deep-plan @path/to/your-spec.md
═══════════════════════════════════════════════════════════════

Do not continue. Wait for user to fix the issue and re-invoke.

Common errors:

• "Spec file not found" → User provided a path to a file that doesn't exist
• "Spec file is empty" → User provided an empty file with no content
• "Expected a spec file, got a directory" → User provided a directory path instead of a file

Handle conflict (if present):

If conflict is present in output, this means CLAUDE_CODE_TASK_LIST_ID was set and the task list already has tasks. Use AskUserQuestion:

• Question: "CLAUDE_CODE_TASK_LIST_ID is set to '{task_list_id}' which already contains {existing_task_count} tasks. Proceeding will overwrite these tasks with the deep-plan workflow. Continue?"
• Options:
• "Proceed and overwrite existing tasks" - Re-run with --force flag
• "Exit" - Stop here, user can unset CLAUDE_CODE_TASK_LIST_ID and retry

If user chooses "Exit": Stop and tell user to unset CLAUDE_CODE_TASK_LIST_ID If user chooses "Proceed": Re-run setup-planning-session.py with --force flag added.

Handle no task list ID (mode == "no_task_list"):

If mode == "no_task_list", this is a fatal error. The workflow cannot proceed without a task list ID. Use AskUserQuestion:

Question: "Cannot proceed: No task list ID available. The SessionStart hook may not have run. How would you like to proceed?"
Options:
  - "Start a fresh session" (Recommended) - Exit Claude and start a new session
  - "Show troubleshooting steps" - Display the error_details.troubleshooting steps

If user chooses "Start a fresh session":

Please exit this Claude session and start a new one. The SessionStart hook
will capture the session ID on startup.

Command: claude --plugin-dir <plugin_path>

If user chooses "Show troubleshooting steps": Display each item from error_details.troubleshooting and STOP.

DO NOT PROCEED past step 4 if this error occurs.

Verify tasks are visible:

After the script completes successfully, run TaskList to verify the workflow tasks are visible. The output tasks_written shows how many task files were written.

Reading session context: After task writing, the task list includes context ta