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:

# 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