/starting-an-implementation-plan

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