• No escape hatch: Run full Phase 3 (create → review → fix)
• Impl plan with "review first": Skip 3.1 (creation), start at 3.2 (review)
• Impl plan with "treat as ready": Skip entire Phase 3, proceed to Phase 4

3.1 Create Implementation Plan

Subagent MUST invoke writing-plans using the Skill tool.

Task (or subagent simulation):
  description: "Create impl plan for [feature name]"
  prompt: |
    First, invoke the writing-plans skill using the Skill tool.
    Then follow its complete workflow to create the implementation plan.

    ## Context for the Skill

    Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    User's parallelization preference: [maximize/conservative/ask]
    - If maximize: group independent tasks into parallel groups
    - If conservative: default to sequential

    Save implementation plan to: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md

3.2 Review Implementation Plan

Subagent MUST invoke implementation-plan-reviewer using the Skill tool.

Task (or subagent simulation):
  description: "Review impl plan"
  prompt: |
    First, invoke the implementation-plan-reviewer skill using the Skill tool.
    Then follow its complete workflow to review the implementation plan.

    ## Context for the Skill

    Implementation plan location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Parent design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    Return the complete findings report with remediation plan.

3.3 Present Review and Handle Approval Gate

Same approval gate logic as Phase 2.3. Reference the autonomous_mode preference.

3.4 Fix Implementation Plan

Subagent MUST invoke executing-plans using the Skill tool.

Task (or subagent simulation):
  description: "Fix impl plan"
  prompt: |
    First, invoke the executing-plans skill using the Skill tool.
    Then use its workflow to systematically fix the implementation plan.

    ## Context for the Skill

    Review findings to address:
    [Paste complete findings report and remediation plan]

    Implementation plan location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Parent design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    ## Fix Quality Requirements (AUTONOMOUS MODE)

    You MUST apply the most complete and correct fix for each finding:
    - Address ALL items: critical, important, minor, AND suggestions
    - For each finding, choose the fix that produces the highest quality result
    - Fix underlying issues, not just surface symptoms
    - Ensure fixes maintain traceability to design document
    - Pay special attention to interface contracts between parallel work
    - When in doubt, err on the side of more thorough treatment
    - Never apply band-aid fixes when proper solutions are available

    Commit changes when done.

3.4.5 Execution Mode Analysis & Selection

Step 1: Calculate Estimated Context Usage

Use the token estimation formulas from $SPELLBOOK_DIR/tests/test_implement_feature_execution_mode.py:

TOKENS_PER_KB = 350
BASE_OVERHEAD = 20000
TOKENS_PER_TASK_OUTPUT = 2000
TOKENS_PER_REVIEW = 800
TOKENS_PER_FACTCHECK = 500
TOKENS_PER_FILE = 400
CONTEXT_WINDOW = 200000

def estimate_session_tokens(design_context_kb, design_doc_kb, impl_plan_kb, num_tasks, num_files):
    design_phase = (design_context_kb + design_doc_kb + impl_plan_kb) * TOKENS_PER_KB
    per_task = TOKENS_PER_TASK_OUTPUT + TOKENS_PER_REVIEW + TOKENS_PER_FACTCHECK
    execution_phase = num_tasks * per_task
    file_context = num_files * TOKENS_PER_FILE
    return BASE_OVERHEAD + design_phase + execution_phase + file_context

Parse the implementation plan to count:

• num_tasks: Count all - [ ] Task N.M: lines
• num_files: Count all unique files mentioned in "Files:" lines
• num_parallel_tracks: Count all ## Track N: headers

Calculate file sizes:

• design_context_kb: Size of research findings + discovery wizard notes
• design_doc_kb: Size of design document
• impl_plan_kb: Size of implementation plan

Step 2: Recommend Execution Mode

def recommend_execution_mode(estimated_tokens, num_tasks, num_parallel_tracks):
    usage_ratio = estimated_tokens / CONTEXT_WINDOW

    if num_tasks > 25 or usage_ratio > 0.80:
        return "swarmed", "Feature size exceeds safe single-session capacity"

    if usage_ratio > 0.65 or (num_tasks > 15 and num_parallel_tracks >= 3):
        return "swarmed", "Large feature with good parallelization potential"

    if num_tasks > 10 or usage_ratio > 0.40:
        return "delegated", "Moderate size, subagents can handle workload"

    return "direct", "Small feature, direct execution is efficient"

Execution Modes:

• swarmed: Generate work packets, spawn separate Claude sessions per track

  • Use when: Large features, >25 tasks, >65% context usage, or good parallelization (>15 tasks + 3+ tracks)
  • Behavior: Proceed to Phase 3.5 and 3.6, then EXIT this session

• sequential: Generate work packets, work through one track at a time in new sessions

  • Use when: Large features but poor parallelization
  • Behavior: Proceed to Phase 3.5 and 3.6, then EXIT this session
  • Note: Currently maps to "swarmed" mode with manual track execution

• delegated: Stay in this session, delegate heavily to subagents

  • Use when: Medium features, 10-25 tasks, 40-65% context usage
  • Behavior: Skip Phase 3.5 and 3.6, proceed directly to Phase 4

• direct: Stay in this session, minimal delegation

  • Use when: Small features, <10 tasks, <40% context usage
  • Behavior: Skip Phase 3.5 and 3.6, proceed directly to Phase 4

Step 3: Present Recommendation

Analysis Results:
- Tasks: [num_tasks]
- Files: [num_files]
- Parallel tracks: [num_parallel_tracks]
- Estimated tokens: [estimated_tokens] ([usage_ratio]% of context window)

Recommended execution mode: [mode]
Reason: [reason]

[If mode is "swarmed" or "sequential":]
This feature is large enough to benefit from parallel execution across separate sessions.
Proceeding to generate work packets and spawn worker sessions.

[If mode is "delegated" or "direct":]
This feature can be executed efficiently in this session.
Proceeding to Phase 4: Implementation.

Step 4: Store Execution Mode

Store the execution mode in SESSION_PREFERENCES:

SESSION_PREFERENCES.execution_mode = mode
SESSION_PREFERENCES.estimated_tokens = estimated_tokens
SESSION_PREFERENCES.feature_stats = {
    "num_tasks": num_tasks,
    "num_files": num_files,
    "num_parallel_tracks": num_parallel_tracks
}

Step 5: Route to Next Phase

• If execution_mode is "swarmed" or "sequential": Proceed to Phase 3.5
• If execution_mode is "delegated" or "direct": Skip to Phase 4

3.5 Generate Work Packets

Prerequisites:

• execution_mode must be "swarmed" or "sequential"
• Implementation plan must be finalized and committed
• PROJECT_ROOT must be determined (from git or current directory)

Step 1: Extract Tracks from Implementation Plan

Use the track extraction logic from $SPELLBOOK_DIR/tests/test_implement_feature_execution_mode.py:

def extract_tracks_from_impl_plan(impl_plan_content):
    """
    Parse implementation plan to find:
    - Track headers: ## Track N: <name>
    - Dependencies: <!-- depends-on: Track 1, Track 3 -->
    - Tasks: - [ ] Task N.M: Description
    - Files: Files: file1.ts, file2.ts
    """
    tracks = []
    current_track = None

    for line in impl_plan_content.split('\n'):
        # Track header: ## Track N: <name>
        if line.startswith('## Track '):
            if current_track:
                tracks.append(current_track)

            parts = line[9:].split(':', 1)  # Skip "## Track "
            track_id = int(parts[0].strip())
            track_name = parts[1].strip().lower().replace(' ', '-')

            current_track = {
                "id": track_id,
                "name": track_name,
                "depends_on": [],
                "tasks": [],
                "files": []
            }

        # Dependency comment: <!-- depends-on: Track 1, Track 3 -->
        elif current_track and line.strip().startswith('<!-- depends-on:'):
            deps_str = line.strip()[16:-4]  # Extract "Track 1, Track 3"
            for dep in deps_str.split(','):
                dep = dep.strip()
                if dep.startswith('Track '):
                    dep_id = int(dep[6:])
                    current_track["depends_on"].append(dep_id)

        # Task item: - [ ] Task N.M: Description
        elif current_track and line.strip().startswith('- [ ] Task '):
            task = line.strip()[6:]  # Remove "- [ ] "
            current_track["tasks"].append(task)

        # Files line: Files: file1.ts, file2.ts
        elif current_track and line.strip().startswith('Files:'):
            files_str = line.strip()[6:].strip()  # Remove "Files:"
            files = [f.strip() for f in files_str.split(',')]
            current_track["files"].extend(files)

    if current_track:
        tracks.append(current_track)

    return tracks

Read the implementation plan and extract all tracks.

Step 2: Create Work Packet Directory

WORK_PACKET_DIR="$HOME/.claude/work-packets/$FEATURE_SLUG"
mkdir -p "$WORK_PACKET_DIR"

Step 3: Generate Work Packet Files

For each track, create a work packet markdown file:

File: $WORK_PACKET_DIR/track-{id}-{name}.md

# Work Packet: Track {id} - {name}

**Feature:** {feature-slug}
**Track:** {id} of {total-tracks}
**Dependencies:** {comma-separated list of track IDs or "None"}

## Context

This work packet is part of a larger feature implementation split across multiple tracks for parallel execution.

### Project Information
- Project root: {PROJECT_ROOT}
- Branch: feature/{feature-slug}/track-{id}
- Worktree: {worktree-path}

### Parent Documents
- Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-{feature-slug}-design.md
- Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-{feature-slug}-impl.md

### Track Dependencies

{If track has dependencies:}
This track depends on the following tracks being completed first:
{For each dependency:}
- Track {dep-id}: {dep-name}
  - Status: Check manifest.json for current status
  - Branch: feature/{feature-slug}/track-{dep-id}

{If no dependencies:}
This track has no dependencies and can be started immediately.

## Tasks

{For each task in this track:}
### {task}

{If files are specified for this task:}
Files to modify/create:
{list of files}

{If no files specified:}
Refer to implementation plan for file locations.

## Implementation Instructions

1. **Before starting:**
   - Verify all dependencies are completed (check manifest.json)
   - Ensure you are in the correct worktree directory
   - Read the design document for full context
   - Read the implementation plan to understand how this track fits

2. **For each task:**
   - Follow TDD methodology (invoke test-driven-development skill)
   - Run code review after implementation (invoke requesting-code-review skill)
   - Run claim validation (invoke fact-checking skill)
   - Commit changes with descriptive message

3. **After completing all tasks:**
   - Run full test suite to verify no regressions
   - Update manifest.json status to "completed"
   - Push branch to remote if requested
   - Report completion with commit hashes and test results

## Quality Gates

Every task MUST pass:
1. Tests written FIRST (TDD RED phase)
2. Implementation passes tests (TDD GREEN phase)
3. Code review approval (no critical/important findings)
4. Claim validation (fact-checking confirms accuracy)
5. All tests pass (including existing tests)

Do NOT proceed to next task if any gate fails.

## Reporting

When complete, provide:
- List of commits (with hashes)
- Test results (pass/fail counts)
- Files modified/created
- Any issues encountered
- Recommendations for integration/merge

Step 4: Generate Manifest File

Create $WORK_PACKET_DIR/manifest.json:

def generate_work_packet_manifest(feature_slug, project_root, execution_mode, tracks):
    manifest = {
        "format_version": "1.0.0",
        "feature": feature_slug,
        "created": datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
        "project_root": project_root,
        "execution_mode": execution_mode,
        "tracks": []
    }

    for track in tracks:
        # Generate worktree path in parent directory
        parent_dir = os.path.dirname(project_root)
        worktree_name = f"{os.path.basename(project_root)}-{feature_slug}-track-{track['id']}"
        worktree_path = os.path.join(parent_dir, worktree_name)

        manifest["tracks"].append({
            "id": track["id"],
            "name": track["name"],
            "packet": f"track-{track['id']}-{track['name']}.md",
            "worktree": worktree_path,
            "branch": f"feature/{feature_slug}/track-{track['id']}",
            "status": "pending",
            "depends_on": track["depends_on"]
        })

    return manifest

Write the manifest to $WORK_PACKET_DIR/manifest.json.

Step 5: Create README

Create $WORK_PACKET_DIR/README.md:

# Work Packets: {feature-slug}

Generated: {timestamp}
Execution mode: {execution_mode}

## Overview

This directory contains work packets for parallel implementation of the {feature-slug} feature.
Each track can be executed independently in its own Claude session.

## Manifest

See `manifest.json` for track metadata, dependencies, and status.

## Tracks

{For each track:}
### Track {id}: {name}
- Packet: {packet-filename}
- Dependencies: {list or "None"}
- Status: {pending/in_progress/completed}
- Branch: {branch-name}
- Worktree: {worktree-path}

## Execution Instructions

{If execution_mode is "swarmed":}
For parallel execution, spawn separate Claude sessions for independent tracks:

1. Check track dependencies in manifest.json
2. Start with tracks that have no dependencies
3. For each independent track, spawn a new session (see Phase 3.6)
4. Once dependencies complete, spawn dependent tracks

{If execution_mode is "sequential":}
For sequential execution, work through tracks one at a time:

1. Start with Track 1
2. Complete all tasks in the track
3. Update manifest.json status to "completed"
4. Move to next track
5. Repeat until all tracks complete

## Integration

After all tracks complete, use the worktree-merge skill to integrate work:
- Invoke: worktree-merge skill with manifest.json
- Handles 3-way diffs and dependency-ordered merging
- Produces unified branch ready for PR

Step 6: Present Work Packets

Work packets generated successfully!

Location: $HOME/.claude/work-packets/{feature-slug}/

Files created:
- manifest.json (track metadata and status)
- README.md (execution instructions)
{For each track:}
- track-{id}-{name}.md (work packet)

Summary:
- Total tracks: {count}
- Independent tracks: {count-with-no-deps}
- Dependent tracks: {count-with-deps}

Execution mode: {execution_mode}

Proceeding to Phase 3.6: Session Handoff

Store work packet directory in SESSION_PREFERENCES:

SESSION_PREFERENCES.work_packet_dir = "$HOME/.claude/work-packets/{feature-slug}"
SESSION_PREFERENCES.manifest_path = f"{work_packet_dir}/manifest.json"

3.6 Session Handoff (TERMINAL)

Prerequisites:

• Work packets generated in Phase 3.5
• Manifest file created with track metadata
• All design/planning documents committed

Step 1: Identify Independent Tracks

Parse manifest.json to find tracks with no dependencies (can start immediately):

def get_independent_tracks(manifest_path):
    with open(manifest_path) as f:
        manifest = json.load(f)

    independent = [
        track for track in manifest["tracks"]
        if len(track["depends_on"]) == 0
    ]

    return independent

Step 2: Check for spawn_claude_session MCP Tool

Check if spawn_claude_session MCP tool is available:

# Check available MCP tools
claude mcp list | grep spawn_claude_session

Store result:

SESSION_PREFERENCES.has_spawn_tool = <true if found, false otherwise>

Step 3: Generate Session Commands

Use the command generation logic from $SPELLBOOK_DIR/tests/test_implement_feature_execution_mode.py:

def generate_session_commands(manifest_path, track_id, has_spawn_tool):
    if has_spawn_tool:
        return [
            f"# Auto-spawn using MCP tool",
            f"spawn_claude_session --manifest {manifest_path} --track {track_id}"
        ]
    else:
        work_packet_dir = os.path.dirname(manifest_path)
        with open(manifest_path) as f:
            manifest = json.load(f)

        track = next(t for t in manifest["tracks"] if t["id"] == track_id)
        packet_path = os.path.join(work_packet_dir, track["packet"])
        worktree_path = track["worktree"]

        return [
            f"# Manual spawn for Track {track_id}",
            f"cd {worktree_path}",
            f"claude --session-context {packet_path}",
        ]

Step 4: Offer Auto-Launch (if MCP tool available)

If has_spawn_tool is true:

The spawn_claude_session MCP tool is available.
I can automatically launch worker sessions for all independent tracks.

Would you like me to:
1. Auto-launch all {count} independent tracks now
2. Provide manual commands for you to run
3. Launch only specific tracks (you choose which ones)

Please choose an option (1, 2, or 3):

If user chooses option 1 (auto-launch all):

For each independent track:

spawn_claude_session --manifest {manifest_path} --track {track_id}

Present results:

Launched {count} worker sessions:
{For each track:}
- Track {id}: {name} (session ID: {session-id})

Workers are now executing in parallel.

To monitor progress:
- Check manifest.json for track status updates
- Review commits in feature/{feature-slug}/track-{id} branches
- Use `claude session list` to see active sessions

After all tracks complete, merge with:
  claude invoke worktree-merge --manifest {manifest_path}

This orchestrator session is now complete. Exiting.

EXIT this session.

If user chooses option 2 (manual commands):

Skip to Step 5 (provide manual instructions).

If user chooses option 3 (specific tracks):

Which tracks would you like to launch? (comma-separated IDs)
Available independent tracks:
{For each independent track:}
- Track {id}: {name}

Enter track IDs:

After user response, launch specified tracks and present results (same as option 1).

Step 5: Provide Manual Instructions (fallback or user preference)

If has_spawn_tool is false OR user chose manual option:

Work packets are ready for execution!

Location: {work_packet_dir}

## Independent Tracks (can start immediately)

{For each independent track:}
### Track {id}: {name}

Work packet: {work_packet_dir}/track-{id}-{name}.md

Commands to spawn worker session:
```bash
# Create worktree
git worktree add {worktree_path} -b {branch_name}

# Start Claude session with work packet
cd {worktree_path}
claude --session-context {work_packet_dir}/track-{id}-{name}.md

{If execution_mode is "swarmed":} You can run these commands in parallel (separate terminals) for concurrent execution.

{If execution_mode is "sequential":} Run these commands one at a time. After each track completes, start the next.

Dependent Tracks (wait for dependencies)

{For each dependent track:}

Track {id}: {name}

Dependencies: Track {dep-ids}

Wait until dependencies complete before starting this track. Check manifest.json for dependency status.

After All Tracks Complete

Integrate the work with worktree-merge:

claude invoke worktree-merge --manifest {manifest_path}

This will:

1. Perform 3-way diffs for all track branches
2. Merge in dependency order
3. Resolve conflicts intelligently
4. Produce unified branch ready for PR

This orchestrator session is now complete.

The implementation plan is ready. Work packets are generated. Execution continues in spawned worker sessions.

Exiting.

EXIT this session.

**Step 6: Terminal Behavior**

<CRITICAL>
After presenting handoff instructions (auto-launch or manual), this session TERMINATES.

Do NOT continue to Phase 4.
Do NOT wait for user input beyond the handoff questions.
Do NOT attempt to execute the implementation.

The orchestrator's job ends here. Workers take over.
</CRITICAL>

Exit with final message:

Orchestration complete. Workers executing. Session ending.

---

## Phase 4: Implementation

<CRITICAL>
This phase executes the implementation plan. Quality gates are enforced after EVERY task.
</CRITICAL>

### 4.1 Setup Worktree(s)

<RULE>Worktree setup depends on the worktree preference.</RULE>

#### If worktree == "single"

Create a single worktree for the entire implementation:

Task (or subagent simulation): description: "Create worktree for [feature name]" prompt: | First, invoke the using-git-worktrees skill using the Skill tool. Then follow its workflow to create an isolated workspace.

## Context for the Skill

Feature name: [feature-slug]
Purpose: Isolated implementation of [feature description]

Return the worktree path when done.

#### If worktree == "per_parallel_track"

<CRITICAL>
Before creating parallel worktrees, setup/skeleton work MUST be completed and committed.
This ensures all worktrees start with shared interfaces, type definitions, and stubs.
</CRITICAL>

**Step 1: Identify Setup/Skeleton Tasks**

Parse the implementation plan to find tasks marked as "setup", "skeleton", or "must complete before parallel work".

**Step 2: Execute Setup Tasks in Main Branch**

Task (or subagent simulation): description: "Execute setup/skeleton tasks" prompt: | First, invoke the test-driven-development skill using the Skill tool. Execute ONLY the setup/skeleton tasks from the implementation plan.

## Context for the Skill

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Tasks to execute: [list setup tasks by number]

These tasks create shared interfaces, type definitions, and stubs that parallel
work will build against. They MUST be committed before creating parallel worktrees.

Commit all setup work when done.

**Step 3: Identify Parallel Groups**

Parse the implementation plan to identify parallel groups and their dependencies:

Example from plan: Parallel Group 1: Tasks 3, 4 (both depend on setup, independent of each other) Parallel Group 2: Task 5 (depends on Tasks 3 and 4)

Creates: worktree_paths = [ { path: "[repo]-group-1-task-3", tasks: [3], depends_on: [] }, { path: "[repo]-group-1-task-4", tasks: [4], depends_on: [] }, { path: "[repo]-group-2-task-5", tasks: [5], depends_on: ["group-1-task-3", "group-1-task-4"] } ]

**Step 4: Create Worktree Per Parallel Track**

For each parallel group, create a worktree:

Task (or subagent simulation): description: "Create worktree for parallel group N" prompt: | First, invoke the using-git-worktrees skill using the Skill tool. Create a worktree for this parallel work track.

## Context for the Skill

Feature name: [feature-slug]-group-N
Branch from: [current branch with setup work committed]
Purpose: Parallel track for [task descriptions]

Return the worktree path when done.

Store all worktree paths in SESSION_PREFERENCES.worktree_paths.

#### If worktree == "none"

Skip worktree creation. Work in current directory.

### 4.2 Execute Implementation Plan

<RULE>Execution strategy depends on parallelization and worktree preferences.</RULE>

#### If worktree == "per_parallel_track" (implies parallelization == "maximize")

Execute each parallel track in its own worktree:

For each worktree in SESSION_PREFERENCES.worktree_paths:

Skip worktrees whose dependencies haven't completed yet

if worktree.depends_on not all completed: continue (will process in next round)

Task (or subagent simulation): description: "Execute tasks in [worktree.path]" run_in_background: true # Run parallel worktrees concurrently prompt: | First, invoke the subagent-driven-development skill using the Skill tool. Execute the assigned tasks in this worktree.

  ## Context for the Skill

  Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
  Tasks to execute: [worktree.tasks]
  Working directory: [worktree.path]

  IMPORTANT: Work ONLY in this worktree directory.
  Do NOT modify files outside this worktree.

  After each task:
  1. Run code review (invoke code-reviewer)
  2. Run claim validation (invoke fact-checking)
  3. Commit changes

  Report when all tasks complete: files changed, test results, commit hashes.

Dispatch all independent worktrees in parallel

Wait for all to complete before processing dependent worktrees

After all parallel tracks complete, proceed to **Phase 4.2.5: Smart Merge**.

#### If parallelization == "maximize" AND worktree != "per_parallel_track"

Standard parallel execution in single directory:

Task (or subagent simulation): description: "Execute parallel implementation" prompt: | First, invoke the dispatching-parallel-agents skill using the Skill tool. Then use its workflow to execute the implementation plan with parallel task groups.

## Context for the Skill

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Working directory: [worktree path or current directory]

Group tasks by their "Parallel Group" field.
After each group completes, trigger code review and claim validation.

#### If parallelization == "conservative" OR "ask"

Sequential execution:

Task (or subagent simulation): description: "Execute sequential implementation" prompt: | First, invoke the subagent-driven-development skill using the Skill tool. Then use its workflow to execute the implementation plan sequentially.

## Context for the Skill

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Working directory: [worktree path or current directory]

Execute tasks one at a time with code review after each.

### 4.2.5 Smart Merge (if worktree == "per_parallel_track")

<CRITICAL>
This phase ONLY runs when parallel worktrees were used.
It merges all worktrees back into a unified branch.
</CRITICAL>

<RULE>Subagent MUST invoke worktree-merge skill using the Skill tool.</RULE>

Task (or subagent simulation): description: "Smart merge parallel worktrees" prompt: | First, invoke the worktree-merge skill using the Skill tool. Then follow its workflow to merge all parallel worktrees.

## Context for the Skill

Base branch: [branch where setup/skeleton was committed]

Worktrees to merge:
[For each worktree in SESSION_PREFERENCES.worktree_paths:]
- Path: [worktree.path]
- Tasks implemented: [worktree.tasks]
- Depends on: [worktree.depends_on]

Interface contracts: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
(See "Interface Contracts" section of the implementation plan)

After successful merge:
1. All worktrees should be deleted
2. Single unified branch should contain all work
3. All tests should pass
4. All interface contracts should be verified

After smart merge completes successfully, proceed to Phase 4.3.

### 4.3 Implementation Task Subagent Template

For each individual implementation task:

Task (or subagent simulation): description: "Implement Task N: [task name]" prompt: | First, invoke the test-driven-development skill using the Skill tool. Then use its workflow to implement this task.

## Context for the Skill

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Task number: N
Working directory: [worktree path or current directory]

Follow TDD strictly as the skill instructs.
Commit when done.

Report: files changed, test results, commit hash, any issues.

### 4.4 Implementation Completion Verification

<!-- SUBAGENT: YES - Self-contained verification. Traces plan items through code, returns findings. -->

<CRITICAL>
This verification runs AFTER each task completes and BEFORE code review.
Catches incomplete work early rather than discovering gaps at the end.
</CRITICAL>

<RULE>Verify implementation completeness before reviewing quality.</RULE>

Task (or subagent simulation): description: "Verify Task N implementation completeness" prompt: | You are an Implementation Completeness Auditor. Your job is to verify that claimed work was actually done - not review quality, just existence and completeness.

## Task Being Verified

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Task number: N
Task description: [from plan]

## Verification Protocol

For EACH item below, trace through actual code to verify existence.
Do NOT trust file names or comments - verify actual behavior.

### 1. Acceptance Criteria Verification

For each acceptance criterion in Task N:
1. State the criterion
2. Identify where in code this should be implemented
3. Read the code and trace the execution path
4. Verdict: COMPLETE | INCOMPLETE | PARTIAL
5. If not COMPLETE: What's missing?

### 2. Expected Outputs Verification

For each expected output (file, function, class, endpoint):
1. State the expected output
2. Verify it exists
3. Verify it has the expected interface/signature
4. Verdict: EXISTS | MISSING | WRONG_INTERFACE

### 3. Interface Contract Verification

For each interface this task was supposed to implement:
1. State the interface contract from the plan
2. Find the actual implementation
3. Compare signatures, types, behavior
4. Verdict: MATCHES | DIFFERS | MISSING

### 4. Behavior Verification (not just structure)

For key behaviors this task should enable:
1. State the expected behavior
2. Trace through code: can this behavior actually occur?
3. Identify any dead code paths or unreachable logic
4. Verdict: FUNCTIONAL | NON_FUNCTIONAL | PARTIAL

## Output Format

```
TASK N COMPLETION AUDIT

Overall: COMPLETE | INCOMPLETE | PARTIAL

ACCEPTANCE CRITERIA:
✓ [criterion 1]: COMPLETE
✗ [criterion 2]: INCOMPLETE - [what's missing]
◐ [criterion 3]: PARTIAL - [what's done, what's not]

EXPECTED OUTPUTS:
✓ src/foo.ts: EXISTS, interface matches
✗ src/bar.ts: MISSING
◐ src/baz.ts: EXISTS, WRONG_INTERFACE - expected X, got Y

INTERFACE CONTRACTS:
✓ FooService.doThing(): MATCHES
✗ BarService.process(): DIFFERS - missing error handling param

BEHAVIOR VERIFICATION:
✓ User can create widget: FUNCTIONAL
✗ Widget validates input: NON_FUNCTIONAL - validation exists but never called

BLOCKING ISSUES (must fix before proceeding):
1. [issue]
2. [issue]

TOTAL: [N]/[M] items complete
```

IMPORTANT: This is about EXISTENCE and COMPLETENESS, not quality.
Code review (next phase) handles quality. You handle "did they build it at all?"

**Gate Behavior:**

IF any BLOCKING ISSUES found:
1. Return to task implementation
2. Fix the incomplete items
3. Re-run completion verification
4. Loop until all items COMPLETE

IF all items COMPLETE:
- Proceed to Phase 4.5 (Code Review)

**What This Catches That Other Gates Miss:**

| Gap Type | Completion Audit | Code Review | Factchecker | Green Mirage |
|----------|-----------------|-------------|-------------|--------------|
| Feature not implemented at all | ✓ | ✗ | ✗ | ✗ |
| Interface differs from spec | ✓ | Maybe | ✗ | ✗ |
| Dead code (exists but unreachable) | ✓ | Maybe | ✗ | ✗ |
| Partial implementation | ✓ | ✗ | ✗ | ✗ |
| Wrong signature/types | ✓ | Maybe | ✗ | ✗ |
| Code quality issues | ✗ | ✓ | ✗ | ✗ |
| Inaccurate comments/docs | ✗ | ✗ | ✓ | ✗ |
| Tests don't test claims | ✗ | ✗ | ✗ | ✓ |

### 4.5 Code Review After Each Task

<!-- SUBAGENT: YES - Self-contained verification task. Fresh eyes, returns verdict + issues only. Saves orchestrator context. -->

<RULE>Subagent MUST invoke code-reviewer using the Skill tool after EVERY task.</RULE>

Task (or subagent simulation): description: "Review Task N implementation" prompt: | First, invoke the code-reviewer skill using the Skill tool. Then follow its workflow to review the implementation.

## Context for the Skill

What was implemented: [from implementation subagent's report]
Plan/requirements: Task N from $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Base SHA: [commit before task]
Head SHA: [commit after task]

Return assessment with any issues found.

If issues found:
- Critical: Fix immediately before proceeding
- Important: Fix before next task
- Minor: Note for later

### 4.5.1 Validate Claims After Each Task

<!-- SUBAGENT: YES - Self-contained verification. Subagent traces claims through code, returns findings only. -->

<RULE>Subagent MUST invoke fact-checking using the Skill tool after code review.</RULE>

Task (or subagent simulation): description: "Validate claims in Task N" prompt: | First, invoke the fact-checking skill using the Skill tool. Then follow its workflow to validate claims in the code just written.

## Context for the Skill

Scope: Files created/modified in Task N only
[List the specific files]

Focus on: docstrings, comments, test names, type hints, error messages.

Return findings with any false claims that must be fixed.

If false claims found: Fix immediately before proceeding to next task.

### 4.6 Quality Gates After All Tasks

<CRITICAL>
These quality gates are NOT optional. Run them even if all tasks completed successfully.
</CRITICAL>

#### 4.6.1 Comprehensive Implementation Completion Audit

<!-- SUBAGENT: YES - Full plan verification. Traces all items through final codebase state. -->

<CRITICAL>
This runs AFTER all tasks complete, BEFORE test suite.
Verifies the ENTIRE implementation plan against final codebase state.
Catches cross-task integration gaps and items that degraded during later work.
</CRITICAL>

<RULE>Per-task verification catches early gaps. This catches the whole picture.</RULE>

Task (or subagent simulation): description: "Comprehensive implementation completion audit" prompt: | You are a Senior Implementation Auditor performing final verification.

The implementation claims to be complete. Your job: verify every item
in the plan actually exists in the final codebase.

## Inputs

Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

## Comprehensive Verification Protocol

### Phase 1: Plan Item Sweep

For EVERY task in the implementation plan:
1. List all acceptance criteria
2. For each criterion, trace through CURRENT codebase state
3. Mark: COMPLETE | INCOMPLETE | DEGRADED

DEGRADED means: passed per-task verification but no longer works
(later changes broke it, code was removed, dependency changed)

### Phase 2: Cross-Task Integration Verification

For each integration point between tasks:
1. Identify: Task A produces X, Task B consumes X
2. Verify Task A's output exists and has correct shape
3. Verify Task B actually imports/calls Task A's output
4. Verify the connection actually works (types match, no dead imports)

Common failures:
- Task B imports from Task A but never calls it
- Interface changed during Task B, Task A's callers not updated
- Circular dependency introduced
- Type mismatch between producer and consumer

### Phase 3: Design Document Traceability

For each requirement in the design document:
1. Identify which task(s) should implement it
2. Verify implementation exists
3. Verify implementation matches design intent (not just exists)

### Phase 4: Feature Completeness

Answer these questions with evidence:
1. Can a user actually USE this feature end-to-end?
2. Are there any dead ends (UI exists but handler missing, etc.)?
3. Are there any orphaned pieces (code exists but nothing calls it)?
4. Does the happy path work? (trace through manually)

## Output Format

```
COMPREHENSIVE IMPLEMENTATION AUDIT

Overall: COMPLETE | INCOMPLETE | PARTIAL

═══════════════════════════════════════
PLAN ITEM SWEEP
═══════════════════════════════════════

Task 1: [name]
✓ Criterion 1.1: COMPLETE
✓ Criterion 1.2: COMPLETE

Task 2: [name]
✓ Criterion 2.1: COMPLETE
✗ Criterion 2.2: DEGRADED - was complete, now broken by [commit/change]

Task 3: [name]
✗ Criterion 3.1: INCOMPLETE - never implemented
◐ Criterion 3.2: PARTIAL - [details]

PLAN ITEMS: [N]/[M] complete ([X] degraded)

═══════════════════════════════════════
CROSS-TASK INTEGRATION
═══════════════════════════════════════

Task 1 → Task 2 (UserService → AuthController):
✓ Interface matches
✓ Actually connected

Task 2 → Task 3 (AuthController → SessionManager):
✗ DISCONNECTED - SessionManager imports AuthController but never calls it

Task 3 → Task 1 (SessionManager → UserService):
✗ TYPE_MISMATCH - expects User, receives UserDTO

INTEGRATIONS: [N]/[M] connected

═══════════════════════════════════════
DESIGN TRACEABILITY
═══════════════════════════════════════

Requirement: "Users can reset password via email"
✗ NOT_IMPLEMENTED - no evidence in codebase

Requirement: "Rate limiting on auth endpoints"
◐ PARTIAL - rate limiter exists but not applied to /login

REQUIREMENTS: [N]/[M] implemented

═══════════════════════════════════════
FEATURE COMPLETENESS
═══════════════════════════════════════

End-to-end usable: YES | NO | PARTIAL
Dead ends found: [list]
Orphaned code: [list]
Happy path: WORKS | BROKEN at [step]

═══════════════════════════════════════
BLOCKING ISSUES
═══════════════════════════════════════

MUST FIX before proceeding:
1. [issue with location]
2. [issue with location]

SHOULD FIX (non-blocking):
1. [issue]
```

**Gate Behavior:**

IF BLOCKING ISSUES found:
1. Return to implementation (dispatch fix subagent)
2. Re-run comprehensive audit
3. Loop until clean

IF clean:
- Proceed to 4.6.2 (Run Full Test Suite)

**Why Both Per-Task AND Comprehensive:**

| What It Catches | Per-Task (4.4) | Comprehensive (4.6.1) |
|-----------------|----------------|----------------------|
| Item never implemented | ✓ Early | ✓ Late (backup) |
| Item degraded by later work | ✗ | ✓ |
| Cross-task integration broken | ✗ | ✓ |
| Design requirement missed entirely | ✗ | ✓ |
| Feature unusable end-to-end | ✗ | ✓ |
| Orphaned/dead code | ✗ | ✓ |

#### 4.6.2 Run Full Test Suite

```bash
# Run the appropriate test command for the project
pytest  # or npm test, cargo test, etc.

If tests fail:

1. Dispatch subagent to invoke systematic-debugging
2. Fix the issues
3. Re-run tests until passing

4.6.3 Green Mirage Audit

Subagent MUST invoke audit-green-mirage using the Skill tool.

Task (or subagent simulation):
  description: "Audit test quality"
  prompt: |
    First, invoke the audit-green-mirage skill using the Skill tool.
    Then follow its workflow to verify tests actually validate correctness.

    ## Context for the Skill

    Test files to audit: [List of test files created/modified in this feature]
    Implementation files: [List of implementation files created/modified]

    Focus on the new code added by this feature.

If audit finds issues:

1. Fix the tests
2. Re-run audit until passing

4.6.4 Comprehensive Claim Validation

Subagent MUST invoke fact-checking using the Skill tool for final comprehensive validation.

Task (or subagent simulation):
  description: "Comprehensive claim validation"
  prompt: |
    First, invoke the fact-checking skill using the Skill tool.
    Then follow its workflow for comprehensive claim validation.

    ## Context for the Skill

    Scope: All files created/modified in this feature
    [Complete list of all files]

    Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md
    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md

    This is the final claim validation gate.
    Cross-reference claims against design doc and implementation plan.
    Catch any claims that slipped through per-task validation.

If false claims or contradictions found:

1. Fix all issues
2. Re-run comprehensive validation until clean

4.6.5 Pre-PR Claim Validation

Before any PR creation, run one final fact-checking pass.

Task (or subagent simulation):
  description: "Pre-PR claim validation"
  prompt: |
    First, invoke the fact-checking skill using the Skill tool.
    Then follow its workflow for pre-PR validation.

    ## Context for the Skill

    Scope: Branch changes (all commits since merge-base with main)

    This is the absolute last line of defense.
    Nothing ships with false claims.

4.7 Finish Implementation

Behavior depends on post_impl preference.

If post_impl == "offer_options"

Task (or subagent simulation):
  description: "Finish development branch"
  prompt: |
    First, invoke the finishing-a-development-branch skill using the Skill tool.
    Then follow its workflow to complete this development work.

    ## Context for the Skill

    Feature: [feature name]
    Branch: [current branch]
    All tests passing: yes
    All claims validated: yes

    Present options to user: merge, create PR, cleanup.

If post_impl == "auto_pr"

1. Push branch to remote
2. Create PR using gh CLI
3. Return PR URL to user

If post_impl == "stop"

1. Announce implementation complete
2. Summarize what was built
3. List any remaining TODOs or known issues

Approval Gate Logic Reference

def handle_review_checkpoint(findings, mode):
    """
    Determines whether to pause for user approval at review checkpoints.
    """

    if mode == "autonomous":
        # Never pause - proceed automatically
        # CRITICAL: In autonomous mode, ALWAYS favor most complete/correct fixes
        if findings:
            dispatch_fix_subagent(
                findings,
                fix_strategy="most_complete",  # Not "quickest" or "minimal"
                treat_suggestions_as="mandatory",  # Not "optional"
                fix_depth="root_cause"  # Not "surface_symptom"
            )
        return "proceed"

    if mode == "interactive":
        # Always pause - wait for user
        if len(findings) > 0:
            present_findings_summary(findings)
            display("Type 'continue' when ready for me to fix these issues.")
            wait_for_user_input()
            dispatch_fix_subagent(findings)
        else:
            display("Review complete - no issues found.")
            display("Ready to proceed to next phase?")
            wait_for_user_acknowledgment()
        return "proceed"

    if mode == "mostly_autonomous":
        # Only pause for critical blockers
        critical_findings = [f for f in findings if f.severity == "critical"]
        if critical_findings:
            present_critical_blockers(critical_findings)
            wait_for_user_input()
        if findings:
            dispatch_fix_subagent(findings)
        return "proceed"

Escape Hatch Reference

Escape hatches allow skipping phases when artifacts already exist.

When escape hatch detected with existing doc, ALWAYS ask user whether to review or treat as ready.

Review first: Jump to the review phase for that doc type, then continue normal flow. Treat as ready: Skip directly past the doc's creation and review phases.

Skills Invoked in This Workflow

Document Locations