starting-an-implementation-plan skill

---
name: starting-an-implementation-plan
description: Use when beginning implementation from a design plan - orchestrates branch creation, detailed planning, and hands off to execution with all necessary context
user-invocable: false
---

# Starting an Implementation Plan

## Overview

Orchestrate the transition from design document to executable implementation through planning and execution handoff.

**Core principle:** Branch -> Plan -> Execute. Isolate work, create detailed tasks, hand off to execution.

**Announce at start:** "I'm using the starting-an-implementation-plan skill to create the implementation plan from your design."

## REQUIRED: Design Plan Path

**DO NOT GUESS.** If the user has not provided a path to a design plan, you MUST ask for it.

Use AskUserQuestion:
```
Question: "Which design plan should I create an implementation plan for?"
Options:
  - [list any design plans you find in docs/design-plans/]
  - "Let me provide the path"
```

If `docs/design-plans/` doesn't exist or is empty, ask the user to provide the path directly.

**Never assume, infer, or guess which design plan to use.** The user must explicitly tell you.

## The Process

This skill has three steps:

1. **Branch Setup:** Select and create branch for implementation
2. **Planning:** Create detailed implementation plan
3. **Execution Handoff:** Direct user to execute the plan

**Step 0: Create orchestration task tracker**

Use TaskCreate to track the orchestration steps:

```
TaskCreate: "Branch setup"
(conditional) TaskCreate: "Read project implementation guidance from [absolute path]"
  → TaskUpdate: addBlockedBy: [Branch setup]
  → (only if .ed3d/implementation-plan-guidance.md exists)
TaskCreate: "Create implementation plan"
  → TaskUpdate: addBlockedBy: [Branch setup] (or [Read guidance] if it exists)
TaskCreate: "Re-read starting-an-implementation-plan skill (restore context)"
  → (DO NOT set blockedBy yet - will be updated after granular tasks are created)
TaskCreate: "Execution handoff"
  → TaskUpdate: addBlockedBy: [Re-read skill]
```

**CRITICAL: The "Re-read skill" task must be re-pointed AFTER writing-implementation-plans creates the Finalization task.** See "After Planning: Update Dependencies" below.

The "Create implementation plan" task wraps the granular tasks created by writing-implementation-plans. The "Re-read skill" step ensures context is restored after potential compaction before handoff.

### Branch Setup

Mark "Branch setup" task as in_progress.

Before planning, set up the branch and workspace for implementation work.

Extract the **slug** from the design plan filename (everything after `YYYY-MM-DD-`, excluding `.md`). For example, `oauth2-svc-authn` from `2025-01-18-oauth2-svc-authn.md`.

This slug is used for:
1. Implementation plan directory name (`docs/implementation-plans/YYYY-MM-DD-{slug}/`)
2. Worktree directory name (`.worktrees/{slug}`)
3. **Scoping all AC identifiers** — every acceptance criterion uses the format `{slug}.AC{N}.{M}`

The slug ensures AC identifiers are globally unique across multiple plan-and-execute rounds.

**Step 1: Ask about worktree**

**REQUIRED: Use AskUserQuestion tool**

Ask:
```
Question: "Do you want to use a git worktree for this implementation?"
Options:
  - "Yes - create worktree" (isolated workspace in .worktrees/[friendly-name])
  - "No - work in current directory" (standard branch workflow)
```

**Step 2: Set up workspace based on choice**

**If user chooses "Yes - create worktree":**

1. **REQUIRED SUB-SKILL:** Use ed3d-plan-and-execute:using-git-worktrees
2. **CONDITIONAL SKILLS:** Activate any project-specific git worktree skills if they exist
3. Announce: "I'm using the using-git-worktrees skill to create an isolated workspace."
4. Ask user which branch to use for the worktree:
   ```
   Question: "Which branch should I use for this worktree?"
   Options:
     - "[friendly-name]" (e.g., oauth2-svc-authn)
     - "$(whoami)/[friendly-name]" (e.g., ed/oauth2-svc-authn)
   ```
5. Create worktree:
   - Default location (unless directed otherwise): `$repoRoot/.worktrees/[friendly-name]`
   - Branch from main/master
   - Follow using-git-worktrees skill for safety verification and setup
6. Change to worktree directory
7. Announce: "Worktree created at `.worktrees/[friendly-name]` on branch `[branch-name]`"

**If user chooses "No - work in current directory":**

1. Ask user which branch to use:
   ```
   Question: "Which branch should I use for this implementation?"
   Options:
     - "Use current branch" (stay on current branch, no branch creation)
     - "[friendly-name]" (e.g., oauth2-svc-authn)
     - "$(whoami)/[friendly-name]" (e.g., ed/oauth2-svc-authn)
   ```
2. **If "Use current branch":** Continue with current branch (no git commands)
3. **If branch name provided:**
   - Determine main branch name: Check if `main` or `master` exists
   - Create new branch from main/master: `git checkout -b [branch-name] origin/[main-or-master]`
   - Verify branch created successfully
   - Announce: "Created and checked out branch `[branch-name]` from `origin/[main-or-master]`"
4. **If branch creation fails:** Report error to user and ask if they want to use current branch instead

Mark "Branch setup" task as completed. **THEN proceed to Planning.**

### Check for Implementation Guidance

After branch setup, check for project-specific implementation guidance.

**Check if `.ed3d/implementation-plan-guidance.md` exists:**

Use the Read tool to check if `.ed3d/implementation-plan-guidance.md` exists in the session's working directory.

**If the file exists:**

1. Use TaskCreate to add: "Read project implementation guidance from [absolute path to .ed3d/implementation-plan-guidance.md]"
   - Set this task as blocked by "Branch setup"
   - Update "Create implementation plan" to be blocked by this new task
2. Mark the task in_progress
3. Read the file and incorporate the guidance into your understanding
4. Mark the task completed
5. Proceed to Planning

**If the file does not exist:**

Proceed directly to Planning. Do not create a task or mention the missing file.

**What implementation guidance provides:**
- Coding standards and conventions
- Testing requirements and patterns
- Review criteria beyond defaults
- Project-specific quality gates

### Planning

Mark "Create implementation plan" task as in_progress.

**REQUIRED SUB-SKILL:** Use ed3d-plan-and-execute:writing-implementation-plans

Announce: "I'm using the writing-implementation-plans skill to create the detailed implementation plan."

The writing-implementation-plans skill will:
- Verify scope (<=8 phases from design plan)
- Verify codebase state with investigator
- Create phase-by-phase implementation tasks
- Validate each phase with user before proceeding
- Write implementation plan to `docs/implementation-plans/`

**Output:** Complete implementation plan written to files, on appropriate branch.

Mark "Create implementation plan" task as completed.

### After Planning: Update Dependencies

**CRITICAL: Update the "Re-read skill" task to be blocked by Finalization.**

The granular tasks are now created. Find the Finalization task ID and update dependencies:

```
TaskUpdate: "Re-read starting-an-implementation-plan skill"
  → addBlockedBy: [Finalization task ID]
```

This ensures the task list shows the correct order:
```
✔ #1 Branch setup
✔ #2 Create implementation plan
✔ #5 Phase 1A: Read [Phase Name] from /path/to/design.md
✔ #6 Phase 1B: Investigate codebase for Phase 1
...
✔ #N Finalization: Run code-reviewer...
◻ #3 Re-read skill › blocked by #N
◻ #4 Execution handoff › blocked by #3
```

### Restore Context (Before Handoff)

Mark "Re-read starting-an-implementation-plan skill (restore context)" task as in_progress.

**CRITICAL: Re-read this skill before proceeding to handoff.**

After potentially long planning work (especially if context compaction occurred), re-read this skill file to ensure you have accurate instructions for the execution handoff:

```bash
# Re-read this skill to restore context
cat /path/to/plugins/ed3d-plan-and-execute/skills/starting-an-implementation-plan/SKILL.md
```

Or use the Read tool on the skill file path.

**Why this matters:** After compaction, you may have lost details about the handoff process. Re-reading ensures you provide correct absolute paths and instructions.

Mark "Re-read starting-an-implementation-plan skill" task as completed.

### Execution Handoff

Mark "Execution handoff" task as in_progress.

After planning is complete, hand off to execution.

**Do NOT invoke execute-plan directly.** The user needs to /clear context first.

**Step 1: Capture and verify absolute paths**

Before outputting the handoff instructions, you MUST run these commands to get real, verified paths:

```bash
# Get absolute path to current working tree root
git rev-parse --show-toplevel
```

Capture this output as `WORKING_ROOT`.

Then construct and verify the implementation plan path exists:

```bash
# Verify implementation plan directory exists
# Replace YYYY-MM-DD-feature-name with the actual plan directory name
ls -d "${WORKING_ROOT}/docs/implementation-plans/YYYY-MM-DD-feature-name"
```

**Both commands must succeed.** If the plan directory doesn't exist, something went wrong during planning — investigate before proceeding.

**Step 2: Provide copy-paste instructions with verified absolute paths**

Use the actual paths you captured and verified in Step 1. Example output:

```
Implementation plan complete!

Ready to execute? This requires fresh context to work effectively.

**IMPORTANT: Copy the command below BEFORE running /clear (it will erase this conversation).**

(1) Copy this command now:

/ed3d-plan-and-execute:execute-implementation-plan /Users/ed/project/.worktrees/oauth2-feature/docs/implementation-plans/2025-01-17-oauth2-feature/ /Users/ed/project/.worktrees/oauth2-feature/

(2) Clear your context:

/clear

(3) Paste and run the copied command.

The execute-implementation-plan command will implement the plan task-by-task with code review between tasks.
```

**Use the real paths from Step 1, not placeholders.** The example above shows the format — substitute your actual verified paths.

**Why absolute paths:** After /clear, Claude Code returns to the original session directory (often the repo root, not the worktree). Absolute paths ensure execution happens in the correct directory regardless of where /clear returns.

**Why /clear instead of continuing:**
- Execution needs fresh context to work effectively
- Long conversations accumulate context that degrades quality
- /clear gives the execution phase a clean slate

Mark "Execution handoff" task as completed.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Invoking execute-implementation-plan directly | Provide copy-paste instructions instead |
| Not warning user to copy command before /clear | Always warn: "Copy this BEFORE running /clear" |
| Using relative paths in handoff command | Run bash commands to get absolute paths, verify they exist |
| Outputting placeholder paths like `[WORKING_ROOT]` | Output real paths from `git rev-parse --show-toplevel` and `ls -d` |
| Not verifying plan directory exists | Always `ls -d` the full plan path before outputting command |
| Passing phase_01.md instead of directory | Pass the directory so all phases execute |
| Forgetting to mention /clear | Always tell user to /clear before execute |
| Skipping "Re-read skill" step before handoff | Always re-read this skill to restore context post-compaction |
| Not creating orchestration tasks at start | Create Branch setup, Planning, Re-read, Handoff tasks in Step 0 |
| Not re-pointing "Re-read skill" after planning | Must update addBlockedBy to Finalization task, not "Create implementation plan" |

## Integration with Workflow

This skill sits between design and execution:

```
Design Plan (in docs/design-plans/)
  -> User runs /start-implementation-plan with design path

Starting Implementation Plan (this skill)
  -> Step 0: Create orchestration tasks
    -> [ ] Branch setup
    -> [ ] Create implementation plan
    -> [ ] Re-read skill (restore context)
    -> [ ] Execution handoff

  -> Branch Setup [tracked task]
    -> Ask if user wants worktree
    -> If yes: invoke using-git-worktrees
    -> If no: ask which branch, create if needed

  -> Planning [tracked task wrapping granular tasks]
    -> Invoke writing-implementation-plans
    -> Creates granular tasks per phase (NA, NB, NC, ND)
    -> Creates Finalization task (code review, fix ALL issues)
    -> Write to docs/implementation-plans/

  -> After Planning: Update Dependencies
    -> Re-point "Re-read skill" to be blocked by Finalization task
    -> Ensures correct execution order in task list

  -> Restore Context [tracked task, blocked by Finalization]
    -> Re-read this skill file
    -> Ensures handoff instructions are accurate post-compaction

  -> Execution Handoff [tracked task]
    -> Run `git rev-parse --show-toplevel` for absolute paths
    -> Verify plan directory exists
    -> Output command with verified absolute paths
    -> Provide /clear command

Execute Implementation Plan (next step)
  -> Reads implementation plan
  -> Implements task-by-task
  -> Code review between tasks
```

**Purpose:** Bridge design and execution with appropriate branch isolation, granular task tracking that survives compaction, and context restoration.