/deep-implement

name: deep-implement
description: Implements code from /deep-plan section files with TDD methodology, code review, and git workflow. Use when implementing plans created by /deep-plan.
license: MIT
compatibility: Requires uv (Python 3.11+), git repository recommended

Deep Implementation Skill

Implements code from /deep-plan section files with integrated review and git workflow.

CRITICAL: First Actions

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

A. Print Intro Banner

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

═══════════════════════════════════════════════════════════════
DEEP-IMPLEMENT: Section-by-Section Implementation
═══════════════════════════════════════════════════════════════
Implements /deep-plan sections with:
  - TDD methodology
  - Code review at each step
  - Git commits with review trails

Usage: /deep-implement @path/to/sections/.

Note: deep-implement creates a large TODO list. Expand your window to avoid flickering
═══════════════════════════════════════════════════════════════

B. Validate Input

Check if user provided @directory argument ending with a path to a `sections/.` directory.

If NO argument or invalid:

═══════════════════════════════════════════════════════════════
DEEP-IMPLEMENT: Sections Directory Required
═══════════════════════════════════════════════════════════════

This skill requires a path to a sections directory from /deep-plan.

Example: /deep-implement @path/to/planning/sections/.

The sections directory must contain:
  - index.md with SECTION_MANIFEST block
  - section-NN-<name>.md files for each section
═══════════════════════════════════════════════════════════════

**Stop and wait for user to re-invoke with correct path.**

C. Discover Plugin Root

**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.

**If `DEEP_PLUGIN_ROOT` is in your context**, use it directly as `plugin_root`. The setup script is at: `<DEEP_PLUGIN_ROOT value>/scripts/checks/setup_implementation_session.py`

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

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

If not found: `find ~ -name "setup_implementation_session.py" -path "*/scripts/checks/*" -path "*deep*implement*" -type f 2>/dev/null | head -1`

**Store the script path.** The plugin_root is the directory two levels up from `scripts/checks/`.

D. Determine Target Directory

The target directory is where implementation code will be written. Check if a previous session exists with a saved target:

# Check for existing config
cat "{sections_dir}/../implementation/deep_implement_config.json" 2>/dev/null | grep -o '"target_dir": "[^"]*"'

**If config exists with target_dir:** Use that value (skip the prompt).

**If no config or no target_dir:** Get current working directory and ask user:

pwd

AskUserQuestion:
  question: "Where should implementation code be written?"
  options:
    - label: "{cwd}"
      description: "Current working directory (Recommended)"
    - label: "Specify path"
      description: "Enter a different absolute path"

If user selects "Specify path", they will type the absolute path.

**Store target_dir** for use in setup script.

E. Run Setup Script

**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 as additional context.

Run the setup script with discovered paths:

uv run {script_path} \
  --sections-dir "{sections_dir}" \
  --target-dir "{target_dir}" \
  --plugin-root "{plugin_root}" \
  --session-id "{DEEP_SESSION_ID}"

If `DEEP_SESSION_ID` is not in your context, omit `--session-id` (setup will fall back to `DEEP_SESSION_ID` env var).

Parse the JSON output.

**If `success == false`:** Display error and stop.

**Session ID diagnostics in output:**

• `session_id`: The session ID being used for tasks
• `session_id_source`: Where it came from ("context", "env", or "none")
• `session_id_matched`: If both context and env were present, whether they matched (useful for debugging)

F. Handle Branch Check

If `is_protected_branch == true` (setup script detects main, master, release/* branches):

AskUserQuestion:
  question: "You're on the {current_branch} branch. Committing here may not be ideal."
  options:
    - label: "Continue on {current_branch}"
      description: "Proceed with implementation on this branch"
    - label: "Exit to create feature branch"
      description: "Stop to create a dedicated branch first"

If user chooses "Exit", stop the workflow.

G. Handle Working Tree Status

If `working_tree_clean == false`:

AskUserQuestion:
  question: "Working tree has {N} uncommitted changes. This may cause issues."
  options:
    - label: "Continue anyway"
      description: "Proceed with implementation (changes may get mixed)"
    - label: "Exit to commit/stash first"
      description: "Stop to handle uncommitted changes"

H. Print Preflight Report

═══════════════════════════════════════════════════════════════
PREFLIGHT REPORT
═══════════════════════════════════════════════════════════════
Target dir:     {target_dir}
Repo root:      {git_root}
Branch:         {current_branch}
Working tree:   {Clean | Dirty (N files)}
Pre-commit:     {Detected (type) | None}
                {May modify files: Yes (formatters) | No | Unknown}
Test command:   {test_command}
Sections:       {N} detected
Completed:      {M} already done
State storage:  {state_dir}
═══════════════════════════════════════════════════════════════

I. Verify Task List

Check the setup output for task status:

1. If `tasks_w