| name | dev-implement-plan |
| description | Execute an implementation plan from docs/<feature-name>/PLAN.md — tick checkboxes, commit each phase. Trigger on "implement/execute/continue/resume the plan", "start phase 1", "go" right after a plan was created, or whenever there is a PLAN.md to build, even if the user never says "plan". |
| argument-hint | [lite|full|ultra] |
Implement Plan
Execute a PLAN.md: phases in order, tick checkboxes as tasks complete, commit each phase. The plan file stays an accurate progress record — anyone interrupted mid-plan must be able to resume from it alone.
Delivery Mode (lite | full | ultra, default lite)
Mode is the trailing argument when it is exactly lite, full, or ultra; everything else is the task/feature description. No mode given → lite.
lite (default) — build every phase the plan has, but on one branch with no phase branches: one implementation commit (plus the plan-status docs commits), one PR at the end.full — one branch + one stacked PR per phase (§3).ultra — phases marked **Parallel**: yes build in separate worktrees simultaneously; merge each into the stack when its completion criteria pass.
Artifact Location
Artifact paths below are relative to the artifact root: docs/ by default, or wherever the user (or
dev-loop, which passes the one it resolved) points it. A gitignored or out-of-repo root means the
artifacts are scratch — write and read them as normal, but never commit them.
Execution Principles
Simplicity ladder — stop at the first rung that satisfies the task: (1) doesn't need to exist → skip, note why; (2) stdlib/platform covers it; (3) already-installed dependency; (4) one function or one line; (5) only then minimum custom code.
Defensive error handling — never simplify away. Handle or explicitly propagate every error. Validate at trust boundaries (user input, external APIs, file I/O, env vars). Fail fast; close resources in all paths.
Surgical changes. Touch only what the task requires; match existing style; mention unrelated issues, don't fix them. Every changed line traces to the current task.
Don't guess at externals. Blocked on how a third-party API/library actually behaves → check docs/<feature-name>/research/, else spawn a research sub-agent (subagent type dev-researcher when available, else general-purpose with the template in dev-research §6) and implement from its findings; commit the topic file with the phase.
Test-first phases. A phase marked **Test-first**: yes in PLAN.md (or requested as test-first/TDD even without the marker) builds its tasks through dev-tdd's red → green loop instead of writing the implementation first and tests after — same phase-commit rules from §3 apply, the loop just runs inside each task rather than test-then-code being a separate step.
Code comment conventions. Tag comments so they're greppable later:
// FIXME(<git username>): <what's broken> — a known-bad workaround needed to keep moving (blocked task resolved with a stopgap, see §4); username from git config user.name; never leave one unticked in the plan.// TODO(<git username>): <what and why deferred> — tech debt or a future improvement out of scope for this plan; username from git config user.name; don't silently skip it, name it.- Don't put
TEST-NNN, RISK-NNN, REQ-NNN, SEC-NNN, or CON-NNN references in code comments — those IDs identify sections of PLAN.md itself (tests, risks, requirements, security notes, constraints), not implementation tasks; they belong in the plan, not the code.
1. Locate the Plan
Named feature → docs/<feature-name>/PLAN.md; else ls docs/*/PLAN.md (prefer status: 'In progress'; several candidates → ask). None → offer dev-create-plan.
2. Pre-flight
Read the entire plan first.
status: Planned → fresh start · In progress → resume (§5) · Completed/Deprecated → stop and confirm · On Hold → ask.- Sync (only if a remote exists):
git fetch origin, rebase onto origin/main. Never rebase by hand when phase branches are already pushed (git ls-remote --heads origin '<feature-name>/*' returns anything) — that rewrites the stacked PRs; use gh stack sync, or warn and continue unrebased.
- Working copy clean? Uncommitted unrelated changes contaminate phase commits — warn.
- Mark started in its own commit:
status: 'In progress', last_updated, badge → docs: start <feature-name> implementation.
3. Phase Execution
lite (default): stay on one branch <feature-name>, tick checkboxes and run completion criteria per phase, but commit and push once at the end (§8). full: per phase —
1. gh stack init <feature-name>/<phase-slug> # first phase; later phases: gh stack add <...>
2. Execute each task; tick its checkbox immediately (same phase commit)
3. Verify completion criteria — run the command, don't assume
4. git add -u && git commit -m "<type>: <phase summary>" # new files: explicit paths
5. gh stack submit --auto # pushes the stack, opens/updates each PR on the right base
6. Next phase: back to 1 — gh stack add stacks it on this one
The stack is managed by the gh-stack skill (see git-safe § Stacked PRs for the non-interactive command set and the fallback when the extension isn't installed) — don't hand-chain gh pr create --base, and fix a lower layer by navigating down to it, not by patching at the top.
Rules:
- Never tick a box for unverified work. Completion criteria are gates — fix before committing.
- Use the plan's commit message; if it no longer fits, write an accurate one and note the deviation (§6).
- Commit hygiene and message style: see the
git-safe skill (no Co-authored-by:, git add -u not -A, imperative why-focused subject).
- Check
git status before staging — no build output or .env.
- Tasks are sequential unless genuinely independent domains with no shared types/fixtures.
- Keep history linear — rebase, not merge.
4. Blocked Tasks
Resolved differently: tick and note inline — > Blocked: <reason>. Resolved by: <what was done>. Unresolvable: leave unchecked with > Blocked: <reason>., stop and ask. If it invalidates later tasks, update the plan (§6) first.
5. Resuming
First unchecked - [ ] TASK- is the resume point. Cross-check git log --oneline — if checkboxes and commits disagree, trust history, fix checkboxes, tell the user. Check git status for partial work.
6. Plan Deviations
Reality wins. Update PLAN.md in its own commit (docs: update plan for <feature-name>) — never buried in implementation commits. New tasks continue TASK-NNN numbering; bump last_updated and version.
7. Testing Section
Run/write each TEST-NNN, tick its box. Tests in a phase's criteria tick with that phase; otherwise final phase: git add -u && git commit -m "test: <feature-name>".
8. Completion
All boxes ticked (or blocked with user sign-off):
status: 'Completed', last_updated, badge.full: commit docs: complete <feature-name> plan on the last phase branch (PRs already open). lite: same commit on <feature-name>, then git push -u origin <feature-name> && gh pr create --base main --title "<imperative ≤60 chars>" --body "<summary + tasks + criteria>".
Report: plan path, phase count, PR URL(s) (full: one per phase with bases — merge in plan order, first phase first, GitHub auto-retargets), deviations, what was run to verify.
No remote → skip pushes, say the branch is ready locally. Interrupted → leave In progress, tick finished tasks, commit partial work, say where to resume.
