starting-an-implementation-plan

What this skill does

# 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