Menu
Use when beginning implementation from a design plan - orchestrates branch creation, detailed planning, and hands off to execution with all necessary context
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when analyzing a large corpus of text, code, or data that exceeds a single agent's effective context - orchestrates parallel Worker subagents, Critic review subagents, and a final Summarizer subagent with task tracking and failure recovery
Use to decide what kind of basic agent you should use
Use when creating a new opencode plugin or setting up plugin structure - provides complete file organization, manifest format, and component definitions for commands, agents, skills, hooks, and MCP servers
Use when creating specialized subagents for opencode or the task tool - covers description writing for auto-delegation, tool selection, prompt structure, and testing agents
Use when creating, releasing, or maintaining an opencode Plugin Marketplace - covers marketplace.json schema, version management, release checklists, changelog conventions, and validation to prevent sync drift between plugin.json and marketplace.json
Use when completing development phases or branches to identify and update AGENTS.md files that may have become stale - analyzes what changed, determines affected contracts and documentation, and coordinates updates
| 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 |
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."
DO NOT GUESS. If the user has not provided a path to a design plan, you MUST ask for it.
Use the question tool:
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.
This skill has three steps:
Step 0: Create orchestration task tracker
Use the todowrite tool to track the orchestration steps. The todo list is flat — express ordering by list order and work top to bottom:
todowrite:
- "Branch setup"
- (conditional) "Read project implementation guidance from [absolute path]"
(only if .ed3d/implementation-plan-guidance.md exists; do after Branch setup)
- "Create implementation plan"
(do after Branch setup — and after reading guidance, if that todo exists)
- "Re-read starting-an-implementation-plan skill (restore context)"
(do NOT start until ALL granular planning tasks, including Finalization, are complete)
- "Execution handoff"
(do after Re-read skill)
CRITICAL: The "Re-read skill" todo must end up positioned AFTER the Finalization task that writing-implementation-plans creates. See "After Planning: Keep Ordering Correct" 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.
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:
docs/implementation-plans/YYYY-MM-DD-{slug}/).worktrees/{slug}){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 the question 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":
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)
$repoRoot/.worktrees/[friendly-name].worktrees/[friendly-name] on branch [branch-name]"If user chooses "No - work in current directory":
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)
main or master existsgit checkout -b [branch-name] origin/[main-or-master][branch-name] from origin/[main-or-master]"Mark "Branch setup" task as completed. THEN proceed to Planning.
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:
todowrite to add: "Read project implementation guidance from [absolute path to .ed3d/implementation-plan-guidance.md]"
If the file does not exist:
Proceed directly to Planning. Do not create a task or mention the missing file.
What implementation guidance provides:
Mark "Create implementation plan" task as in_progress.
REQUIRED SUB-SKILL: Use writing-implementation-plans
Announce: "I'm using the writing-implementation-plans skill to create the detailed implementation plan."
The writing-implementation-plans skill will:
docs/implementation-plans/Output: Complete implementation plan written to files, on appropriate branch.
Mark "Create implementation plan" task as completed.
CRITICAL: Ensure the "Re-read skill" todo comes after the Finalization task.
The granular tasks are now created. Rewrite the todo list with todowrite so "Re-read skill" and "Execution handoff" are the last two items, after Finalization:
✔ Branch setup
✔ Create implementation plan
✔ Phase 1A: Read [Phase Name] from /path/to/design.md
✔ Phase 1B: Investigate codebase for Phase 1
...
✔ Finalization: Run ed3d-code-reviewer...
◻ Re-read skill (after Finalization)
◻ Execution handoff (after Re-read skill)
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 to ensure you have accurate instructions for the execution handoff: use the skill tool to load starting-an-implementation-plan again, or use the read tool on this skill's SKILL.md (its absolute path is shown in the file list when this skill loads).
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.
Mark "Execution handoff" task as in_progress.
After planning is complete, hand off to execution.
Do NOT invoke plan execution directly. The user needs to start a fresh session first.
Step 1: Capture and verify absolute paths
Before outputting the handoff instructions, you MUST run these commands to get real, verified paths:
# 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:
# 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 message below BEFORE running /new (it will leave this conversation).**
(1) Copy this message now:
Use the executing-an-implementation-plan skill with plan directory /Users/ed/project/.worktrees/oauth2-feature/docs/implementation-plans/2025-01-17-oauth2-feature/ and working directory /Users/ed/project/.worktrees/oauth2-feature/
(2) Start a fresh session:
/new
(3) Paste and run the copied message.
The executing-an-implementation-plan skill 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: A fresh session starts in the original project directory (often the repo root, not the worktree). Absolute paths ensure execution happens in the correct directory regardless of where the new session starts.
Why a fresh session instead of continuing:
Mark "Execution handoff" task as completed.
| Mistake | Fix |
|---|---|
| Invoking executing-an-implementation-plan directly | Provide copy-paste instructions instead |
| Not warning user to copy the message before /new | Always warn: "Copy this BEFORE running /new" |
| Using relative paths in handoff message | 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 the message |
| Passing phase_01.md instead of directory | Pass the directory so all phases execute |
| Forgetting to mention /new | Always tell user to start a fresh session before executing |
| 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 todos in Step 0 |
| Leaving "Re-read skill" mis-ordered after planning | It must come after the Finalization task in the todo list, not right after "Create implementation plan" |
This skill sits between design and execution:
Design Plan (in docs/design-plans/)
-> User invokes this skill with the design path
Starting Implementation Plan (this skill)
-> Step 0: Create orchestration todos
-> [ ] 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: Keep Ordering Correct
-> Move "Re-read skill" after the Finalization task in the todo list
-> Ensures correct execution order in task list
-> Restore Context [tracked task, after Finalization]
-> Re-read this skill
-> 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 message with verified absolute paths
-> Tell user to start a fresh session (/new)
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.