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_written > 0: Tasks have been written. Call TaskList to see them.
2. If task_write_error is present: Task write failed - log the error and continue with manual tracking.
3. If no task_list_id: Session ID not available - the SessionStart hook may not have run.

After setup succeeds: Call TaskList to see the implementation tasks.

Understanding the task list:

The task list contains 6 high-level reminders per section:

1. Implement section-NN
2. Run code review subagent for section-NN
3. Perform code review interview for section-NN
4. Update section-NN documentation
5. Commit section-NN
6. Record section-NN completion

Plus a compaction prompt every 2nd section (after 02, 04, 06, etc.).

Context items appear as pending tasks at the start (e.g., plugin_root=/path/..., sections_dir=/path/...).

These are milestones to track progress, not detailed instructions. For the actual workflow steps, always refer to:

• This file (SKILL.md) for the overall orchestration
• The reference documents in references/ for detailed protocols

Mark each task as in_progress when starting: TaskUpdate(taskId=X, status="in_progress") Mark each task as completed when done: TaskUpdate(taskId=X, status="completed")

Implementation Loop

For each incomplete section (in manifest order):

Task milestone mapping:

Note: Step 12 (Mark Complete) is internal task status update. Step 14 (Loop) continues to next section. Context checks only appear after sections 02, 04, 06, etc.

Step 1: Mark In Progress

Update task: TaskUpdate(taskId=X, status="in_progress")

Step 2: Read Section File

Read {section