12 KiB
Loop Mode on the Web Console
Notes for Implement and Implement + Review run by the desktop app's
Implementation Loop (--loop), part of the console.md contract. Read building.md and notes/implement.md first: this note says
only where loop mode differs. The app judges the result, so you report and never
approve.
Flags
--loop: this run is one phase of an unattended loop. The skill's first step already ran a plainopen; run it again now, before any post, asnode "<CONSOLE>" open --workflow <implement|implement-review> --spec specs/<feature> --loop. Inside the app it resumes the app's session and locks the page; without it,loopOutcomeandhandledByare refused. If it exits 3, the run is not inside the app: say "Loop mode runs only inside the Plan2Code desktop app." in the terminal and continue as an ordinary run with the person's sign-off. Skip nothing below unless thatopensucceeded. Every lateropen --resumein this run (the server went away:chatorwaitexit 20) carries--looptoo, asopen --resume <sid> --workflow <yours> --loop: a resume without it unlocks the session, and theloopOutcomepost is then refused.--phase <N>: the phase the app is building. Build exactly that one (see Choosing the phase); the app refuses a report that names another.--fix <levels>: a comma list fromcritical,warning,suggestion, the levels to fix in the one fix round. Absent means findings are reported, not fixed.--fix smart: Smart pick. A triage step picks the findings to fix in place of a level list (see Triage).--guess: when a task needs a decision the spec does not make, take the best guess, mark the task[?]with a one-line note as an indented line right under it in the phase file (- Assumed: what you chose and why), and carry on. The app copies that note into the person's report. Without--guess, ask the question as an ordinary open card (see Questions and cards).
What changes in loop mode
- Build the phase
--phasenames, without asking (Choosing the phase). - No sign-off card, no "Approve this phase", no Show me it working, no Continue
offer. A loop run notes lessons and never lists them: no
lessonscard. - Take the
changes.mjs startsnapshot asnotes/implement.mdsays, but run nodiffand post no Changes tab: a loop phase has no sign-off. - Never run
specs.mjs mark --to done, and never set[x]on the phase inoverview.md. Tasks inside the phase file are still checked off as they finish:[x],[!]when blocked,[?]when assumed. - Never run
gitin any form (no add, commit, stash, checkout), and nevercommit-msg.mjs. - No Stop-with-handoff, no
__dashboard, no finish screen: the app ends the session. - Where the prompt would stop and ask, report instead of posting a card:
- A spec conflict: list it in
conflicts, reportfailed, reasonconflict. - A blocked prerequisite or task: mark the task
[!], list it intasks.blocked, reportfailed, reasonblocked. - Failing tests: try one fix, then report
tests.passed: false,failed, reasontests. Never post the Fix now, Document or Investigate options. Exception: tests the phase file's Notes say will fail until a later phase. Name every failing test intests.failingand list the expected ones intests.expectedFailures; when every failing test is on that list, reportpassed. Never list a failure the Notes do not name. - A waiting
**Plan change:**line in the phase's Notes: do not ask Revise first or Resume; reportfailed, reasonother, and say so insummary.
- A spec conflict: list it in
- Run only the tests the phase file names (a phase task, a task's
Test:line, or tasks under## Phase Testing), never the full suite unless it names it.
Headline stages
Post headline.stage as each begins, using only these words: Build, Review,
Fixes, Re-check, Reporting (the app's strip shows any other word as
Build). Keep cleared and total as in any build.
Choosing the phase
The phase is N from --phase N, whatever next in specs.mjs status would
pick. Never post the "Resume?" question or the parallel-phase pick. Run
node "<S>/specs.mjs" status specs/<feature> and find phase N in phases:
- Its
checklistispendingorin-progress: build it. Set it in progress withspecs.mjs mark <spec> --phase N --to in-progress, exactly as an ordinary run does: that mark is allowed, and only--to doneis the app's. - It is
blocked([!]): build nothing; post aloopOutcomewithresult: "failed",reason: "blocked", itsblockedTasksids (like2.4) intasks.blockedandsummary: "Phase N is marked blocked in overview.md". - It is
completeorassumed, or not in the checklist: build nothing; postresult: "failed",reason: "other"andsummary: "Phase N is not an open phase in this spec".
No --phase (an older app): take next.phase.number (the first of
next.options when next.action is choose), and when next.action is none
or checkoff post result: "failed", reason: "other" and
summary: "No open phase left in this spec".
Questions and cards the loop handles
- A real question (a decision the spec does not make, without
--guess) is an ordinary open card, waited on withpost --waitas usual. The app sees it open and holds or stops the loop. Do not mark ithandledBy. - The review stage's findings pick and the fix confirmation are answered by this
run itself from
--fix(with--fix smart, from the triage). Post them for the record as settled items with"handledBy": "loop"and the answer filled in, so the page shows "The loop handles this", for example{ "id": "fixes", "kind": "multi", "title": "Which to fix", "options": [ ... ], "status": "answered", "answer": { "ks": ["1", "2"] }, "handledBy": "loop" }. - Ask (chat) questions do not arrive while the loop drives; if one does, answer it briefly.
Review, one fix round and the re-check
Implement + Review only. Run the review as building-review.md describes. Fix
only the findings at the --fix levels, in one round. Then start one fresh
reviewer helper (a new subagent with no memory of the fix round, or a fresh read
when helpers are off) that re-checks only the fixes: each finding at a chosen
level is fixed, and nothing new was introduced. Count what is left, by level,
after the re-check. Suggestions left or newly found on the re-check are listed
but never fail the phase. Do not run a second fix round.
Triage (--fix smart)
Implement + Review only, after the review lists its findings and before the fix
round. Start one fresh triage helper (a new subagent with no memory of the build
or the review, or a fresh read when helpers are off). Its brief holds the
findings, the phase's tasks in phase-X.md and the project's AGENTS.md. For
each finding it answers fix or skip with one line of reason, at most 200
characters. Skip is for a finding that is not real once the code is read, is
outside this phase's tasks, contradicts AGENTS.md or the spec, or asks for a
change out of proportion to the gain. Every skip carries a reason.
The app stops the phase on any skipped Critical, so the triage must not skip a
Critical it merely dislikes: skip one only when it is plainly not a defect, and
say why. Post the triage's answers for the record as the settled fixes item (its ks are the findings marked fix, posted before the fix round)
(handledBy: "loop"), with one thread entry per skip carrying its reason.
Then run the one fix round on the findings marked fix, and the fresh re-check
of only those fixes, as above. left counts the picked findings still open after
the re-check. Smart pick always reports triage.ran: true and review.recheck: true, even when no finding was raised or none was picked (an empty re-check). The triage runs under the Review stage.
Reporting the outcome
At the end of the run, post once a top-level loopOutcome:
{ "loopOutcome": {
"phase": 2, "result": "passed", "reason": null,
"summary": "Built the setup screen; 6 of 6 tasks",
"tests": { "ran": true, "passed": true, "summary": "14 pass" },
"decisions": ["Kept the old /votes route so existing callers still work"],
"review": { "ran": true, "recheck": true,
"fixed": [ { "level": "warning", "title": "Close the file handle", "file": "src/z.js" } ],
"triage": { "ran": true, "skipped": [ { "level": "warning", "title": "Rename the helper", "file": "src/y.js", "reason": "Outside this phase's tasks" } ] },
"left": { "critical": 0, "warning": 0, "suggestion": 2 },
"unfixed": [ { "level": "suggestion", "title": "Name the timer", "file": "src/x.js" } ] },
"tasks": { "blocked": [], "assumed": ["2.4"] },
"conflicts": [],
"subject": "Add the loop setup screen" } }
resultis"passed"only when every task is[x](or[?]with--guess), the named tests pass, and, with review, no Critical or Warning is left at a chosen level (every level in Smart pick) after the re-check, and, in Smart pick, the triage skipped no Critical (otherwisefailed, reasonfindings). Otherwise"failed", with the first matchingreason:tests,findings,blocked,conflictorother. A passed outcome has"reason": null. Afailedreport addsnextStep: one line (300 characters) with the one thing to do, naming a file or command.review.triageis present only with--fix smart:ran: trueandskippedlisting every skipped finding with its reason (an empty list when nothing was skipped). A picked Critical or Warning still left after the re-check fails the phase with reasonfindings.unfixedlists only picked findings still open after the re-check; skipped findings go only intriage.skipped(the app adds them to the summary), and the 50-entry limits of the two lists are separate.review.fixedlists every finding the fix round fixed (an empty list when none, or with no review), at most 50.decisionslists, at most 50, one line of at most 200 characters each, every other judgment call this run made on the person's behalf that the spec did not settle and theAssumed:notes do not already cover: a library or approach chosen between real options, scope left out or added, a behavior changed outside the task. The person reads these to check the work, so say what you chose and why, and leave nothing out because it seems small. Do not list the routine steps of building. An empty list means you made none.review.ranandreview.recheckarefalsewhen the run did no review or no re-check (plain Implement, or no--fixlevel; never with--fix smart).tasks.blockedandtasks.assumedlist task ids like"2.4".conflictsholds one line per spec conflict.subjectis one imperative line under 100 characters saying what changed (it becomes the commit subject).summaryis one line under 200 characters.
The app stamps loopExpect into the session as the phase starts: the criteria
it will judge the report by (review, fix as "smart" or the level list,
guess). It is the app's field, never yours to post. The console holds every
loopOutcome to it, so a report missing a required piece (review.ran: false
on a review run, no review.triage.ran under Smart pick, a skipped Critical in
the triage, no re-check with fixes chosen, assumed tasks without --guess) is
refused at post time with the field named, while the run can still do that
step and repost.
Then post {"agent":{"status":"waiting"}} and keep waiting with the usual
bounded wait slices until the app ends the session. Never end the turn on text.
If the post is refused (exit 3), fix the field it names and post again.