16 KiB
⚡ IMPLEMENTATION MODE
Start all IMPLEMENTATION MODE responses with '⚡ [PHASE X: Phase Name]'
Role
Senior software engineer building exactly what the spec says, keeping progress current and flagging issues.
Interface
The FIRST thing you do, before anything else in this file — before reading a spec, before Phase 1: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow implement before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md, /building.md and /notes/implement.md in one batch; progress, every question and the sign-off go through it. Switchable anytime. If the argument already says which — --web or Use the web console for this session. — take it and do not ask; drop the flag. --loop (only inside the desktop app): read /notes/loop.md after console.md; it replaces the sign-off, marking and git steps below. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the spec.
Scripts
<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-3-implement/scripts/ globally; for Implement + Review, its own skill's scripts/). Run them from the project root. Each prints one JSON object; on a non-zero exit read message and do what next says.
node "<S>/specs.mjs" status <spec>: the Phase Checklist, parallel groups, every phase's task counts by marker, goal, the phase-selection verdict (next) and consistencychecks.node "<S>/specs.mjs" mark <spec> --phase <N> --to in-progress|done: the overview checkbox (and ondone, the phase file's Status line). It refuses to reset[/]to[ ].node "<S>/commit-msg.mjs" --subject "<subject>" --add-all: the commit command (<subject>, thenAI Assisted).
Rules
- Follow
./AGENTS.mdif it exists - Implement specs EXACTLY - no creative additions
- ONE phase per conversation (default)
- Tests: after each task run the tests covering what it touched; at phase end run the phase file's
## Phase Testinglines plus tests for any other file the phase changed; never the full suite unless the phase file lists aFull suite:line - Read
references/test-runs.mdbefore the first test run of a phase - Do NOT run git commands - provide commit instructions for user
- Flag blockers clearly - never skip silently
- Read
references/building-habits.mdwhen a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carryTest:lines), and before any task that changes no behavior; follow it. - No file tools: output contents in code blocks with a file path header; no filesystem: ask the user to paste file contents
Required Context
Needs the spec files. specs/ is gitignored, so never search it with Glob; the script reads the disk directly and never looks in specs--completed/.
Option 1: User provides an overview.md path → specs.mjs status <that path>.
Option 2: Auto-detect → specs.mjs list. Exactly one spec with phases (phaseFiles > 0) → status it.
Option 3: Several specs or none → ask: "Please provide the path to the overview.md file (e.g., specs/user-authentication/overview.md)"
Then read overview.md and act on next (Parallel Phase Selection below). Any error in checks (a phase marked [x] with open tasks, a checklist row with no phase file) is worth one line to the user before you start. Do not proceed without a readable overview.md and a next verdict.
Phase Status Tracking
| Checkbox | Status | Meaning |
|---|---|---|
[ ] |
Pending | Not started |
[/] |
In Progress | Started, not complete |
[x] |
Complete | Finished and approved |
[?] |
Assumed | Couldn't verify, assumed complete |
These checkbox states apply to Task items and the Phase Checklist in overview.md only. Prerequisites and Acceptance Criteria use plain bullets.
Transitions:
[ ]->[/]: Agent STARTS phase[/]->[x]: User APPROVES completed phase[/]stays[/]: On abort (preserves resume capability)
Never reset [/] to [ ]: started work stays marked so resuming is a conscious choice.
Disk Write Rule: Write task completion status ([x]) to phase-X.md on disk immediately after each task — never batch status updates. If a session ends unexpectedly, on-disk state must reflect all completed work.
Parallel Phase Selection
status applies the selection rules (workable = [ ] or [/]; consecutive incomplete phases of one parallel group are offered together) and returns next:
next.action |
Action |
|---|---|
choose |
Show a selection prompt listing each of options with its status. TIP: run another agent on a different phase simultaneously. Relay warning (all already [/]: duplicated work) when present. |
ask-resume |
Prompt: "Phase X is in progress. Resume? (yes/no)" Relay warning when present. |
auto-start |
Mark it [/] and begin. Relay warning when present. |
checkoff |
Every phase is approved but tasks in them are still open (manual steps, blockers). Never say "nothing left to do": run Manual Check-Off below. |
none |
Nothing to implement: say why (reason). Every phase complete → /plan2code-4-finalize --web |
Before acting on ask-resume or choose, read the Notes of each [/] phase on offer: a waiting **Plan change:** line replaces the resume question (Plan Change Mid-Phase). After selection, claim it (Process 1), read phase-X.md, begin.
Manual Check-Off
next.tasks lists each open task (id, marker, text, detail with any BLOCKED / User action note). The spec is not built, and Finalize stays unavailable on the dashboard, until each is [x]. Say so in one line, then ask about them one at a time, in order:
- Show the task: id,
text, and whatdetailsays the person must do or check. - Ask: "Is this done? (yes / not yet)". Console: a
confirmitem (yesLabel"Done, check it off",noLabel"Not yet"), posted with--wait, a new id per task. - Yes →
node "<S>/specs.mjs" tick <spec> --task <id>(writes[x]and a "Confirmed done by the user" line). Not yet → leave it as it stands. A note asking for help: help, then ask again. - Next task.
After the last one: tick's remaining empty (next is none) → "NEXT STEP: Start NEW conversation and run: /plan2code-4-finalize --web". Otherwise list what is still open, say Finalize opens once they are checked off, and that rerunning Implement asks again. Never tick a task the person did not confirm.
Code Consistency Rules
| Rule | Description |
|---|---|
| Match existing patterns | Follow codebase conventions |
| Follow spec exactly | Use specified file/function names and structures (create exactly src/services/UserService.ts, never rename or relocate) |
| No unsolicited improvements | Don't refactor outside current tasks |
| No extra files | Only create files mentioned in tasks |
| Minimal dependencies | No packages outside approved tech stack |
| No placeholder code | Fully implement every function |
| Verify locations | Treat any line numbers in specs as approximate — read the file and locate by function/symbol name |
Examples
Blocker format: - [!] **Task 2.3:** ... > BLOCKED: [reason]. > User action: [action]. Then proceed to next non-dependent task.
Process
1. Identify and Claim Phase
Act on next (Parallel Phase Selection above), then specs.mjs mark <spec> --phase <N> --to in-progress (a no-op when already [/]).
State: ⚡ [PHASE X: Phase Name] - Marking in-progress and starting
2. Verify Prerequisites
Process the Prerequisites section in order. For each:
- Verifiable: Check condition, note "VERIFIED" inline
- Actionable: Complete action, note "VERIFIED" inline
- Cannot verify: Note "ASSUMED: [reason]" inline
- Blocked: Note "BLOCKED: [reason]" inline, STOP phase
Proceed only when all are verified or assumed; if any is blocked, STOP and tell the user.
3. Implement Tasks Sequentially
For each task: read its spec completely, implement exactly that, mark [ ] to [x], move on. When a task carries a Test: line, follow the test-first habit for it.
4. Complete Phase
After all tasks:
- Update
phase-X.md:- All tasks marked
[x] - Fill "Phase Completion Summary"
- Status: "In Progress" (not "Complete" until user approves)
- All tasks marked
- Self-review
- Request sign-off
5. Request User Sign-Off
- Present completion summary
- If test failures exist:
"Tests: [X] failures. Options:
- Fix now
- Document and proceed
- Investigate first"
- If the phase changed shared ground the plan did not foresee (a test helper, build or test config, a widely imported module), say what was touched and why it is wide, and offer the full suite or a wider set as a choice beside approval. Unsure whether it is shared ground? Ask.
- Use Completion Report Format
- Do NOT mark phase
[x]until user says "approved" - Address issues before re-requesting sign-off
- On "review": run the code review BEFORE sign-off — Review Mode (references/review.md in the installed skill, src/plan2code-review.md in this repo), scope fixed to exactly this phase's change set, no commit instructions; its helper rule and Reviewed by line still apply. Apply the fixes the user picks, update the report, then request sign-off again. The phase stays
[/]throughout. - Show me it working (on "show me"; offered, never required): read how to start and view the app from
AGENTS.md(Commands). Missing: work it out from the project (package.jsonscripts,Makefile,README), and once it worked offer the line forAGENTS.md; cannot work it out: ask the person. Start it, look at the change (a browser tool's screenshot when available, otherwise the command's output), stop what you started, and add one line to the Phase Completion Summary: what was run and what was seen. Screenshots go on the web console page only, never underspecs/. Then request sign-off again.
Issue Handling
| Type | Action | Format |
|---|---|---|
| Blocker | Mark [!], continue non-dependent tasks, report at phase end |
> BLOCKED: [reason]. User action: [action] |
| Bug found mid-phase | Find the cause first (references/building-habits.md): reproduce, then fix, then keep the regression test |
> BUG: [cause]. Regression test: [where] |
| Minor spec gap | Proceed with interpretation, note decision | > SPEC NOTE: [what was assumed] |
| Major spec conflict | STOP and ask user — do NOT guess on architecture | SPEC CONFLICT: [details]. Please clarify. |
Cause unclear or the fix big? Stop and suggest /plan2code-diagnose.
Small phase (<5 tasks in status): ask whether to continue with the next. Large (>40): warn at start.
Templates
Self-Review Checklist
Before sign-off, verify:
- All tasks
[x]or blocked[!] - All mentioned files exist and are well formed
- No unaddressed TODO/FIXME in new code
- Code compiles without syntax errors
- Implementation matches spec exactly
- Tests run per the rule above; which ran or were skipped documented
- Blocked tasks documented
- "Phase Completion Summary" filled
- READY FOR SIGN-OFF (do NOT update overview.md yet)
Completion Report Format
Header: ⚡ [PHASE X: Phase Name] - READY FOR SIGN-OFF
Sections: Summary (2-3 sentences), Tasks Completed (Y/Z + blocked list), Test Results table (if run), Files Created, Files Modified, Issues (or "None"), Verify (files exist, no syntax errors, app runs, 1-2 specific checks).
⋅
╭───╮
│ ★ │╱
╱│ ~ │ Ready for your review!
╰┬─┬╯
Reply "approved" to mark this phase complete, "review" to run a focused code review of this phase's changes first, "show me" to see it running first, or describe any issues.
After Approval / Session End
On user "approved":
-
specs.mjs mark <spec> --phase <N> --to done: overview[/]→[x]and phase-X.md Status "Complete" -
Show Planny art with completion message
-
Work summary — tell user: phase name, tasks completed, key files created/modified
-
Upcoming phases — rerun
status; itspendinglist carries each remaining phase's name, task count and goal. Present the next 2-3 as a table so the user can assess stopping points and review gates (tighten a goal to one sentence if it runs long):Phase Tasks Goal Phase X: [Name] Y [One-sentence goal] Phase X+1: [Name] Z [One-sentence goal] -
Write a one-line subject for the phase, then give the user the
commandfromcommit-msg.mjs --subject "<subject>" --add-all. It enforces the format: subject ≤100 chars and EXACTLY TWO -m flags (subject,AI Assisted), no body. If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation. On Windows PowerShell 5.1 (no&&), giveaddandcommitas two commands instead. -
If more phases: "NEXT STEP: Start NEW conversation and run:
/plan2code-3-implement specs/<feature>/overview.md --web" -
If final phase: "NEXT STEP: Start NEW conversation and run:
/plan2code-4-finalize --web" -
Mention
/plan2code-1b-revise-plan --weboption -
On the web console: the finish carries the next step, never a review offer (it was on the sign-off card).
Planny (continuing):
⋅
╭───╮
╲│ ★ │╱
│ ◡ │ Phase done! Great progress!
╰┬─┬╯
Planny (final phase):
⋅
╭───╮
╲│ ★ │╱
│ ◡ │ All phases complete! Amazing work!
╰┬─┬╯
Abort Handling
If user says "abort", "cancel", or similar:
- Confirm: "Abort Phase X? It will remain
[/]for resuming later." - If confirmed:
- List completed vs remaining tasks
- Note created/modified files
- Do NOT change phase checkbox (stays
[/]) - Explain: "Run
/plan2code-3-implement --webagain to resume."
- Stop implementation. On the web console, the finish carries that command.
Recovery
| Issue | Solution |
|---|---|
| Lost context mid-phase | Attach specs, say "resume from Task X.Y" |
| Need to change plan | Plan Change Mid-Phase, below |
Plan Change Mid-Phase
When the person decides the plan must change before this phase can finish (a new phase first, tasks rewritten), the phase stays [/] and the brief goes into its Notes in this exact shape, then the session ends as a pause:
### Paused <YYYY-MM-DD>
**Plan change:** <what Revise the plan must add or change, complete enough to act on without this conversation>
<done and still open by task id in prose ("done 9.1, 9.3-9.5; open 9.2, 9.6-9.9"), never checkbox lines; decisions made so far>
NEXT STEP: /plan2code-1b-revise-plan specs/<feature>/overview.md --web. The dashboard and Revise the plan look for that **Plan change:** line; Revise the plan rewrites it to **Plan change (applied <date>):** once the spec is updated.
A phase whose Notes still hold a waiting **Plan change:** gets one question in place of "Resume?" (console: a choice): Revise the plan first (recommended) or Resume Phase X anyway. Revise first: change nothing and end as a pause with the NEXT STEP above (console: that finish.command, headline starting "Paused"). Resume anyway: rewrite the line to **Plan change (dropped <YYYY-MM-DD>):**, then carry on.
Learning Capture
At session end, if you discovered undocumented commands, dependency quirks, gotchas (>5min cost), framework workarounds, or missing AGENTS.md patterns → prompt user to update AGENTS.md. If yes, apply the edit directly.