implement-plan

name	implement-plan
description	Execute a plan from _plans/, implementing steps, checking off tasks, running tests, and documenting fixes
user-invocable	true
origin	template

Implement Plan

Execute an implementation plan from _plans/, working through each step, updating the plan as you go, and running tests to verify.

This skill combines the "implement" and "run" phases into one — you build it, run it, test it, fix it, and the plan documents everything that happened.

Arguments

The user provides the plan file to implement. For example:

• /implement-plan _plans/20260409-auth-ui.plan.md
• /implement-plan auth-ui (shorthand — resolve to the matching .plan.md file in _plans/)
• /implement-plan (no argument — if only one plan has status: draft or status: in-progress, use that)

Steps

1. Load the Plan

1. Read the plan file from _plans/
2. If the user gave a shorthand (no path or partial name), find the matching .plan.md file
3. If no argument and multiple draft/in-progress plans exist, ask the user which one
4. Parse the frontmatter and step list
5. Identify which steps are already checked (- [x]) and which are pending (- [ ])

2. Read Per-Repo Instructions

For each repo listed in the plan's repos frontmatter:

1. Check if repos/<name>/CLAUDE.md exists — if so, read and follow it
2. Check if repos/<name>/AGENTS.md exists — if so, read and follow it
3. These instructions supplement the root CLAUDE.md and govern how code is written in that repo

3. Set Status to In-Progress

Update the plan file's frontmatter:

status: in-progress

4. Implement Each Step

For each unchecked step (- [ ]), in order:

1. Read the step — understand the task, files, and pseudocode
2. Implement it — write the actual code
   • Follow the plan as guidance, not strict requirements
   • If the plan's approach won't work, adapt — but document why
   • Follow the coding standards and per-repo instructions
   • Respect read/write separation: only modify files in one repo at a time
3. Mark it done — update the plan file: change - [ ] to - [x]
4. Add notes if needed — if you discovered something unexpected, adapted the approach, or made a decision not in the original plan, add a **Notes** line under the step:

   - [x] Step 3: Add OAuth endpoint
     - **Task**: Create POST /api/auth/google
     - **Files**: `repos/backend-api/src/routes/auth.ts`
     - **Pseudocode**: Validate token, create session
     - **Notes**: Used existing session middleware instead of creating new one. Added rate limiting per security best practice.
   

IMPORTANT: Update the plan file after EACH step, not at the end. If the session is interrupted, the plan shows exactly where things stand.

5. Run and Test

After all implementation steps are complete:

1. Run the application — start it up, verify it launches without errors
2. Run existing tests — make sure nothing is broken
3. Run new tests — if the plan included test steps, verify they pass
4. If using Playwright MCP — for frontend work, use browser automation to verify UI changes

6. Fix Issues

If tests fail or the app has issues:

1. Diagnose — read errors, check logs, identify root cause
2. Fix — make the necessary changes
3. Document in the plan — add new checked steps at the end:

   - [x] Fix: Corrected token validation logic
     - **Notes**: The OAuth token response format changed in v2. Updated parser to handle both formats.
   

4. Re-run tests — verify the fix works
5. Repeat until everything passes

7. Complete the Plan

When all steps pass and tests are green:

1. Update the plan file's frontmatter:

   status: completed
   

2. Report to the user:
   • Summary of what was implemented
   • Any deviations from the original plan (with reasons)
   • Any fixes that were needed
   • Test results
   • Suggested next step (e.g., "Ready for code review" or "Run /commit-all-repos to commit")

Error Handling

• Plan file not found: List available plans in _plans/ and ask the user to pick one
• All steps already checked: Tell the user the plan is already implemented. Ask if they want to re-run validation.
• Blocked on user decision: If a step says user intervention is needed, stop and ask. Add the decision to the plan once resolved.
• Implementation diverges significantly from plan: Pause and inform the user. Let them decide whether to continue or revise the plan first.

Notes

• Treat the plan as guidance, not gospel — adapt when reality doesn't match the plan
• The plan is a living document. Update it as you go, not after the fact.
• Every decision, deviation, and fix should be documented in the plan
• When complete, the plan serves as a record of what happened — useful for code reviews and future reference
• If working across multiple repos, commit each repo separately following read/write separation