implement-plan

> THIS SESSION IS AN ORCHESTRATOR. YOU MUST NEVER IMPLEMENT CODE DIRECTLY.

The Orchestration Hierarchy

```

implement-plan (this session - ORCHESTRATOR)

│

│ ⛔ NEVER writes code

│ ⛔ NEVER uses Write/Edit tools

│ ⛔ NEVER creates files

│

└── implement-phase (ORCHESTRATOR for phase)

│

│ ⛔ NEVER writes code

│ ⛔ NEVER uses Write/Edit tools

│ ⛔ NEVER creates files

│

└── Subagents (DO the actual work)

│

✅ Write code

✅ Create files

✅ Run tests

✅ Fix issues

```

What This Session Does

| DO | DO NOT |

|----|--------|

| Read plan and prompts | Write code |

| Discover phase prompts | Create files |

| Invoke implement-phase skill | Use Write/Edit tools |

| Track plan-level progress | Implement directly |

| Present results to user | Fix issues directly |

| Handle user confirmation | Run implementation commands |

Enforcement

If you find yourself about to use Write, Edit, or NotebookEdit tools in this session:

```

⛔ STOP - You are violating the orchestrator pattern

✅ INSTEAD - Delegate to implement-phase which will spawn subagents

```

---

```

implement-plan (this skill - plan orchestrator)

│

├── Phase 1 → implement-phase → [implementation, verification, review, ADR, sync]

│ ↓

│ [user confirmation]

│ ↓

├── Phase 2 → implement-phase → [implementation, verification, review, ADR, sync]

│ ↓

│ [user confirmation]

│ ↓

├── Phase N → implement-phase → [...]

│ ↓

└── Final Verification & Summary

```

This Skill (implement-plan)

• Read and understand the full plan
• Sequence phases correctly
• Delegate each phase to implement-phase
• Handle user confirmation between phases
• Track overall plan progress
• Generate final completion report

Delegated to implement-phase

• All implementation work
• Exit condition verification
• Code review
• ADR compliance
• Plan file synchronization

• Implementing pre-approved technical plans or specifications
• Executing phased development work with defined success criteria
• Following structured implementation guides with verification steps
• Resuming partially-completed implementation work

Current Mode: Guided Execution

Each phase requires user confirmation before proceeding to the next. This is the default, safe mode.

```

Phase 1 → implement-phase → ✅ Complete → [USER CONFIRMS] → Phase 2 → ...

```

Future Mode: Autonomous Execution

> Note: This mode is planned but not yet implemented. When enabled, the entire plan will execute without pauses between phases.

```

Phase 1 → Phase 2 → Phase 3 → ... → Final Report

```

Autonomous mode will require:

• Explicit user opt-in: "implement the entire plan autonomously"
• Stricter quality gates
• Comprehensive rollback capability
• Detailed execution log

When given a plan path or asked to implement a plan:

1. Locate and Read Plan

```

1. Find the plan file (docs/plans/, thoughts/plans/, or specified path)
2. Read the ENTIRE plan - full context is essential
3. Identify total number of phases
4. Extract task_list_id from plan metadata (for multi-session support)
5. Check for existing Tasks (TaskList shows progress from previous sessions)

```

Multi-Session Support:

If the plan has a task_list_id in its metadata, ensure you're using the same task list:

```bash

CLAUDE_CODE_TASK_LIST_ID=plan-2026-01-24-feature-name claude

```

This enables multiple sessions to share progress on the same plan.

2. Discover Phase Prompts

Check for pre-generated prompts from the prompt-generator skill:

```

# Check common prompt locations

1. Glob("docs/prompts/phase-*.md") # Standard location
2. Glob("prompts/phase-*.md") # Alternative location

# Match prompts to phases by number

phase-1-*.md → Phase 1

phase-2-*.md → Phase 2

...

```

Prompt Discovery Output:

```

● Prompt Discovery:

Found: docs/prompts/phase-1-foundation.md → Phase 1

Found: docs/prompts/phase-2-data-pipeline.md → Phase 2

Found: docs/prompts/phase-3-agent-system.md → Phase 3

Missing: Phase 4 (no prompt found)

Note: Phases with prompts will use pre-generated instructions.

Phases without prompts will use plan file directly.

```

3. Read Related Context

```

# Tiered ADR reading (context conservation)

1. Read("docs/decisions/INDEX.md") # Scan all ADRs first
2. Read("docs/decisions/ADR-NNNN.md", limit=10) # Quick Reference of relevant ones
3. Read full ADR only if needed for implementation details

# Read files referenced in plan

1. Load all files mentioned in the plan

```

4. Check Progress via Tasks

```

# Check for existing tasks for this plan

TaskList: Check for tasks matching "Phase N:" pattern

If tasks exist:

- Resume from first non-completed task

- Skip already-completed phases

- Display current progress

If no tasks exist:

- Tasks should have been created by create-plan

- If missing, create them now (see create-plan Phase 7)

```

Task Status Display:

```

Tasks (2 done, 3 open):

✓ #1 Phase 1: Setup

✓ #2 Phase 2: Core Logic

◻ #3 Phase 3: Integration › blocked by #2

◻ #4 Phase 4: Testing › blocked by #3

◻ #5 Phase 5: Documentation › blocked by #4

```

5. Begin Phase Execution

For each phase:

1. Mark task as in_progress: TaskUpdate(task_id, status: "in_progress")
2. Delegate to implement-phase
3. On completion: TaskUpdate(task_id, status: "completed")

```

Skill(skill="implement-phase"): Execute Phase [N] of the implementation plan.

Context:

• Plan: [plan file path]
• Phase: [N] ([Phase Name])
• Task ID: [task_id from TaskList]
• Prompt: [prompt file path, if discovered]
• Previous Phase Status: [Complete/N/A]

Execute all quality gates and return structured result.

```

With Prompt (preferred):

```

Skill(skill="implement-phase"): Execute Phase 2.

Context:

• Plan: docs/plans/trading-platform.md
• Phase: 2 (Data Pipeline)
• Task ID: 2
• Prompt: docs/prompts/phase-2-data-pipeline.md
• Previous Phase Status: Complete

The prompt contains detailed orchestration instructions.

Execute all quality gates and archive prompt on completion.

```

Without Prompt (fallback):

```

Skill(skill="implement-phase"): Execute Phase 4.

Context:

• Plan: docs/plans/trading-platform.md
• Phase: 4 (Integration)
• Task ID: 4
• Prompt: None (use plan directly)
• Previous Phase Status: Complete

No pre-generated prompt. Use plan file for phase details.

```

Before Each Phase

1. Announce the phase about to start
2. Summarize what will be implemented
3. Note any dependencies on previous phases

```

═══════════════════════════════════════════════════════════════

● STARTING PHASE 2: Authentication Service

═══════════════════════════════════════════════════════════════

Objectives:

• Implement login/logout logic
• JWT token generation and validation

Dependencies:

• Phase 1 (Database Schema) must be complete ✅

Delegating to implement-phase...

```

During Phase Execution

The implement-phase skill handles all details:

• Subagent delegation for implementation
• Exit condition verification
• Code review via code-review skill
• ADR compliance checking
• Plan file synchronization

After Each Phase

Receive structured result from implement-phase:

```yaml

PHASE_RESULT:

status: COMPLETE | FAILED | BLOCKED

steps:

implementation: PASS

exit_conditions: PASS

code_review: PASS_WITH_NOTES

adr_compliance: PASS

plan_sync: PASS

manual_verification:

- "Check login flow in browser"

ready_for_next: true

```

User Confirmation Point

After each phase completes, pause for user confirmation:

```

═══════════════════════════════════════════════════════════════

● PHASE 2 COMPLETE: Authentication Service

═══════════════════════════════════════════════════════════════

Results:

✅ Implementation: 3 files created, 2 modified

✅ Exit Conditions: All passed

✅ Code Review: Passed with 2 recommendations

✅ ADR Compliance: Passed

✅ Plan Updated: 8 tasks marked complete

Manual Verification Required:

- [ ] POST /auth/login returns token with expected claims

- [ ] POST /auth/logout invalidates session

Recommendations (non-blocking):

1. Consider using project's CustomLogger

2. Add ADR-0012 reference to plan

───────────────────────────────────────────────────────────────

Please confirm manual verification steps, then respond to

proceed to Phase 3: API Endpoints

═══════════════════════════════════════════════════════════════

```

When implement-phase returns a blocker:

From implement-phase

```yaml

PHASE_RESULT:

status: BLOCKED

blocker: "Existing JWT implementation found in src/legacy/auth.js"

options:

- "Proceed with new implementation"

- "Refactor legacy code"

- "Abort and revise plan"

```

Orchestrator Response

1. STOP further phase execution
2. PRESENT the blocker to user with options
3. AWAIT user decision
4. RESUME or ABORT based on decision

```

⛔ PHASE 2 BLOCKED

Issue: Existing JWT implementation found in src/legacy/auth.js.

The plan specifies creating new jwt.strategy.ts but doesn't

mention legacy code.

Options:

A) Proceed with new implementation, mark legacy for removal

B) Refactor legacy code instead of creating new file

C) Abort and revise the plan

Recommendation: Option A - cleaner separation

How should I proceed?

```

Tasks persist across sessions, enabling seamless resume:

1. Call TaskList - Get all tasks for the plan
2. Find first non-completed task - This is the resume point
3. Verify state - Quick sanity check that previous work exists
4. Continue - Resume from the pending task

```

● Plan Status: Resuming interrupted work

Task Status (from TaskList):

✓ #1 Phase 1: Database Schema - completed

✓ #2 Phase 2: Authentication Service - completed

◻ #3 Phase 3: API Endpoints - in_progress ← Resume here

◻ #4 Phase 4: Testing - pending (blocked by #3)

Resume Point: Phase 3 (API Endpoints)

Continuing from Phase 3...

```

Multi-Session Resume:

```bash

# Start new session with same task list

CLAUDE_CODE_TASK_LIST_ID=plan-2026-01-24-user-auth claude

# Tasks automatically show current progress

# Resume from where any session left off

```

Benefits of Task-based resume:

• Cross-session persistence (tasks survive session restart)
• Multi-session support (share progress across terminals)
• Dependency tracking (blocked tasks visible)
• Clear audit trail of progress

After all phases complete:

```

═══════════════════════════════════════════════════════════════

● PLAN COMPLETE: User Authentication Implementation

═══════════════════════════════════════════════════════════════

Summary:

Phases Completed: 3/3

Files Created: 12

Files Modified: 5

Tests Added: 47

ADRs Created: 1 (ADR-0015)

Quality Gates (all phases):

✅ All exit conditions passed

✅ All code reviews passed

✅ All ADR compliance checks passed

✅ Plan fully synchronized

Final Verification:

- [ ] E2E tests pass: npm run test:e2e

- [ ] API documentation updated

- [ ] Security review checklist complete

═══════════════════════════════════════════════════════════════

Implementation complete. Ready for final review.

═══════════════════════════════════════════════════════════════

```

Progress is tracked via Task tools with cross-session persistence. See [ADR-0001](../../docs/decisions/ADR-0001-separate-plan-spec-from-progress-tracking.md).

| Tracking Method | Scope | Purpose |

|-----------------|-------|---------|

| TaskList/TaskUpdate | Persistent | Track phase-level progress across sessions |

| Plan File | Persistent | Specification document (updated with ✅ on completion) |

| Status Updates | User | Communicate current state |

Task Lifecycle:

```

create-plan → TaskCreate (all phases with dependencies)

↓

implement-plan → TaskUpdate(in_progress) → implement-phase → TaskUpdate(completed)

↓

Resume (any session) → TaskList (find first pending task)

```

Multi-Session Workflow:

```bash

# Session 1: Start implementation

CLAUDE_CODE_TASK_LIST_ID=plan-my-feature claude

> /implement-plan docs/plans/my-feature.md

# ... complete Phase 1, 2 ...

# Session 2: Resume from another terminal

CLAUDE_CODE_TASK_LIST_ID=plan-my-feature claude

> /implement-plan docs/plans/my-feature.md

# Automatically resumes from Phase 3

```

Phase-level tracking is handled by implement-phase using Task tools.

See references/plan-format.md for:

• Standard plan structure and formatting
• Phase organization guidelines
• Exit condition patterns
• Verification step templates

1. Delegate phase execution - Use implement-phase for all phase work
2. Orchestrate, don't implement - This skill coordinates, not codes
3. User confirmation between phases - Pause for human validation (current mode)
4. Trust implement-phase results - Act on structured return values
5. Surface blockers immediately - Don't hide problems from the user
6. Track at plan level - Let implement-phase handle phase-level tracking
7. Prepare for automation - Structure supports future autonomous mode

```

implement-plan

└── implement-phase (required)

├── code-review (required)

└── adr (required for compliance)

```