|
1 | 1 | --- |
2 | 2 | name: loop-implement |
3 | | -description: Close a single implementation task with a methodology-grounded verification loop — define done, analyze, plan, write tests first (Red), implement (Green), run, self-review, get an independent test-quality audit, then judge against done; on failure reflect and retry (bounded). Use for one non-trivial task (feature, fix, behavior-changing refactor). Skip for typos, config values, simple renames. |
| 3 | +description: The single implementation loop. Plans via wiki-plan (step 2, required) into an ordered, wiki-navigated task list, then executes those tasks IN ORDER — each loading only its named wiki pages, applying their directives with no improvisation, writing tests first (Red), implementing (Green), running, self-reviewing, getting an independent test-quality audit, and judging against done (reporting the wiki references applied); on failure reflect and retry (bounded). Consumes an existing plan if handed one. Use for a non-trivial task or feature. Skip for typos, config values, simple renames. |
4 | 4 | --- |
5 | 5 |
|
6 | | -# loop-implement — verification loop for a single task |
| 6 | +# loop-implement — the single implementation loop, driven by a wiki-plan |
7 | 7 |
|
8 | | -Take one task and drive it to "done" through a closed loop whose steps are |
9 | | -grounded in established methodology (sources at the bottom). This is the worker |
10 | | -half of loop-orchestrator: an orchestrator session hands you one task; you |
11 | | -complete it here. It also works standalone for a single task. |
| 8 | +Drive work to "done" through a closed, methodology-grounded loop (sources at the |
| 9 | +bottom). **This is dev-loop's one and only implementation skill** — it both plans |
| 10 | +(via `wiki-plan`, step 2) and executes, so there is no separate executor. The |
| 11 | +plan `wiki-plan` produces is not a loose sketch: it fixes an ordered task list |
| 12 | +and, for each task, *navigates to the exact wiki pages that ground it* (the |
| 13 | +decision→page map). This loop **consumes that plan directly** — executing the |
| 14 | +tasks in the plan's order, loading exactly the wiki pages each task names, and |
| 15 | +citing them — so every change traces back to a verified wiki page. |
| 16 | + |
| 17 | +It works the same whether it runs standalone (you produce the plan here in step 2) |
| 18 | +or as an orchestrated worker (the orchestrator hands you a task brief and you plan |
| 19 | ++ implement it here). Either path, one loop. |
12 | 20 |
|
13 | 21 | ## When to use |
14 | 22 | - Use: logic changes, new features, bug fixes, behavior-changing refactors. |
15 | 23 | - Skip: typos, config values, simple rename/import cleanup, one-line edits. |
16 | 24 |
|
| 25 | +## Two entry modes (both run the SAME loop) |
| 26 | +- **A plan already exists** (a `plans/<feature>/` from a prior `wiki-plan` run, or |
| 27 | + handed to you by the orchestrator): skip producing one — execute its tasks in |
| 28 | + the `## Task order` sequence, one at a time, each through steps 0 and 3–7 below, |
| 29 | + loading that task's named wiki pages. |
| 30 | +- **No plan yet** (a fresh standalone task): step 2 runs `wiki-plan` first to |
| 31 | + produce the ordered, wiki-navigated plan, then you execute it the same way. |
| 32 | + |
17 | 33 | ## The plan step is fixed (not pluggable) |
18 | 34 | Step 2 (Plan) is **hardwired to the bundled `wiki-plan` skill** and is |
19 | 35 | **mandatory** for every non-trivial task — it is not a pluggable role and cannot |
@@ -47,42 +63,92 @@ is no `implement` role — step 4 below is the single owner of the implement cyc |
47 | 63 |
|
48 | 64 | ## The loop |
49 | 65 |
|
| 66 | +Step 2 produces the plan once (or you were handed one). Steps 0 and 3–7 then run |
| 67 | +**per task, in the plan's `## Task order`** — finish and judge one task before |
| 68 | +starting the next, so a downstream task always builds on a verified upstream one. |
| 69 | + |
50 | 70 | ``` |
51 | | -0. Define done — write the acceptance criteria + done checklist FIRST, |
52 | | - so the loop has an explicit pass/fail target. [DoD/XP] |
53 | | -1. Analyze — understand the change; list the test scenarios it needs. |
54 | | - Consult `knowledge` + `tacit` if configured; use `explore` |
55 | | - to locate code/symbols. For a UI-facing task, read the |
56 | | - visual spec — the brief's `<design_spec>` if present, else |
57 | | - consult `design` (e.g. a Figma link) — and implement to it. [TDD step 1 / PDCA Plan] |
58 | | -2. Plan (wiki-plan) — REQUIRED. Invoke the bundled `wiki-plan` skill to make |
59 | | - every design decision, each grounded in a `wiki/` page |
60 | | - (record the decision->page map), and to write the plan |
61 | | - as concrete values/code — never "as appropriate". This |
62 | | - step is not skippable for a non-trivial task and never |
63 | | - defers a decision to the implementing pass. [PDCA Plan / wiki-plan] |
64 | | -3. Write tests (Red) — write the failing test(s) BEFORE the code. The test is |
65 | | - the spec and the verification oracle. If test-first is |
66 | | - impractical (e.g. exploratory UI), fix the acceptance |
67 | | - criteria / verification command before implementing. [TDD test-first] |
68 | | -4. Implement (Green) — minimal code to make the tests pass. [TDD Green / PDCA Do] |
69 | | -5. Run tests (Check) — run new + existing tests; preserve failure output. Use the |
70 | | - `verify` role's command if configured (run only). [PDCA Check / self-testing code] |
71 | | -6. Self-review + refactor — clean up; check bugs, edge cases, resource leaks, |
72 | | - input validation, unused code. Re-check against the |
73 | | - `tacit` role's danger zones if configured. [TDD Refactor / self-review / Self-Refine] |
| 71 | +2. Plan (wiki-plan) — REQUIRED, once. If no plan exists, invoke `wiki-plan` to |
| 72 | + make every design decision (each grounded in a `wiki/` |
| 73 | + page — the decision->page map) and emit the ordered task |
| 74 | + list, each task naming the exact wiki pages it needs. If a |
| 75 | + plan exists, adopt it. Never defer a decision to execution. [PDCA Plan / wiki-plan] |
| 76 | +
|
| 77 | + ── for each task, in Task order: ── |
| 78 | +0. Define done — from the task's Objective + Verify + the plan's Deliverables: |
| 79 | + write this task's pass/fail checklist FIRST. [DoD/XP] |
| 80 | +1. Analyze + load refs— read THIS task's "Wiki pages (read these first, only |
| 81 | + these)" — the pages `wiki-plan` navigated to — and load |
| 82 | + exactly those from `${CLAUDE_PLUGIN_ROOT}/wiki/`, plus the |
| 83 | + task's Inputs (confirm each exists; a missing Input is a |
| 84 | + plan defect -> 7b, not a stand-in). List the test |
| 85 | + scenarios. Consult `knowledge`/`tacit`/`explore` if |
| 86 | + configured; for a UI task read the `<design_spec>`/`design`. [TDD step 1 / PDCA Plan] |
| 87 | +3. Write tests (Red) — failing test(s) BEFORE code, from the task's Verify/Objective. |
| 88 | + If test-first is impractical (exploratory UI), fix the |
| 89 | + acceptance criteria / verify command first. [TDD test-first] |
| 90 | +4. Implement (Green) — minimal code to pass, executing the task under the |
| 91 | + Execution contract below: apply the named pages' directive |
| 92 | + rows as written, task D-number decisions win, stay inside |
| 93 | + Deliverables, and do NOT improvise — a gap is a plan defect. [TDD Green / PDCA Do] |
| 94 | +5. Run tests (Check) — run new + existing tests + the task's Verify command; |
| 95 | + preserve failure output. Use the `verify` role if set. [PDCA Check / self-testing code] |
| 96 | +6. Self-review + refactor — bugs, edge cases, resource leaks, input validation, |
| 97 | + unused code; re-check against the named pages' edge-case |
| 98 | + rows and the `tacit` danger zones if configured. [TDD Refactor / self-review] |
74 | 99 | 6.5 Independent audit — REQUIRED: call the test-quality-auditor subagent with the |
75 | | - task brief, the diff, and the test paths. Do NOT grade |
76 | | - your own tests. (self-grading guard) |
77 | | -7. Judge against done — pass only if the done checklist is met AND the auditor |
78 | | - returns VERDICT: PASS. [DoD / evaluator] |
79 | | - - PASS -> done. |
| 100 | + task brief, the diff, and the test paths. (self-grading guard) |
| 101 | +7. Judge against done — PASS only if the checklist is met AND the auditor returns |
| 102 | + VERDICT: PASS. Emit the task report (format below, with the |
| 103 | + WIKI: references you applied). [DoD / evaluator] |
| 104 | + - PASS -> next task in Task order (back to step 0), until all tasks done. |
80 | 105 | - FAIL -> 7b. |
81 | | -7b. Reflect + retry — state in words why it failed (what the auditor/tests |
82 | | - showed), then retry from step 3 with that reflection. |
83 | | - Bounded: at most 3 attempts. On the 3rd failure, STOP |
84 | | - and escalate with the last failure reason. [Reflexion / bounded retry] |
| 106 | +7b. Reflect + retry — say why it failed. If it is a PLAN defect (a decision/name/ |
| 107 | + input the task+pages+inputs never gave), repair the plan/ |
| 108 | + task via step 2, don't guess; else retry from step 3. |
| 109 | + Bounded: ≤3 attempts per task; 3rd failure STOPs + escalates. [Reflexion / bounded retry] |
| 110 | +``` |
| 111 | + |
| 112 | +## Execution contract (step 4 — absorbed from the wiki executor) |
| 113 | + |
| 114 | +The plan already decided the design; your discipline is what makes the output |
| 115 | +correct. While implementing a task: |
| 116 | + |
| 117 | +1. **Read exactly what the task names, nothing else.** The task file (all |
| 118 | + sections), then every page under its "Wiki pages" — those are your |
| 119 | + best-practice instructions for this task — then every "Inputs" file. Where a |
| 120 | + task step and a wiki page both speak, the task's explicit **D-number decisions |
| 121 | + win**; the wiki fills in the *how*. |
| 122 | +2. **Stay inside the box.** Touch only files named in Deliverables (creating |
| 123 | + parent dirs is fine). "Out of scope" is the next task's work — stop at the |
| 124 | + boundary even when finishing it looks easy. Use the exact names/paths/types/ |
| 125 | + signatures the task spells out; they are seams other tasks depend on. |
| 126 | +3. **No improvisation.** If a step needs something the task, its wiki pages, and |
| 127 | + its inputs do not give — a name, a type, a library choice, a behavior for an |
| 128 | + unlisted case — do NOT pick one. That is a planning defect: go to 7b and repair |
| 129 | + the plan/task via `wiki-plan`. A wrong guess costs more than a re-plan. |
| 130 | +4. **Apply wiki directives as written.** A listed page's decision table → do your |
| 131 | + case's row. A listed edge case → the edge-case row overrides the general rule. |
| 132 | + No matching row → that's rule 3 (plan defect), not a guess. |
| 133 | +5. **Cite what you applied.** The task report's `WIKI:` line names each page id |
| 134 | + and the row/directive you followed — this is the explicit reference back to the |
| 135 | + plan's decision→page map, so every change is traceable. |
| 136 | + |
| 137 | +## Task report (step 7 output, per task) |
| 138 | + |
85 | 139 | ``` |
| 140 | +STATUS: PASS | BLOCKED |
| 141 | +TASK: <NN-slug> |
| 142 | +CHANGED: <each file created/modified, one per line> |
| 143 | +TESTS: <n cases; the Red->Green transition; auditor VERDICT> |
| 144 | +VERIFY: <the task's Verify command → actual result> |
| 145 | +WIKI: <page id applied → the row/directive followed, one line each> |
| 146 | +NOTES: <deviations (should be none); for BLOCKED: the exact missing decision/ |
| 147 | + input, as a one-line question wiki-plan can answer> |
| 148 | +``` |
| 149 | + |
| 150 | +A BLOCKED task is a plan defect: repair the task file / decisions via `wiki-plan` |
| 151 | +(step 2) and re-run it. Never mark PASS with a failing or skipped Verify. |
86 | 152 |
|
87 | 153 | ## Depth that keeps the loop to one pass |
88 | 154 |
|
|
0 commit comments