Update the web console server, screens, help, prefs and loop setup, with matching page and logic suites

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-02 12:00:12 -08:00
1 parent 2468027a5a
commit 8e34bf1005
119 files changed
+9957 -3728

No files matched your search

+10 -23
View File
@@ -1,27 +1,14 @@
# Changelog on the Web Console
# Changelog
Workflow notes for `changelog`, part of the web console contract (`console.md`).
`changelog`: post `activity` while you read the history and diff. One card per step, each only when needed:
Open with `--workflow changelog` (launched from the dashboard: resume the
session instead). Post `activity` while you read the history and the diff. One
card per step, each asked only when the step needs it:
| Step | On the page |
| Step | Card |
| --- | --- |
| Version | A `choice`, "Which version?": the computed version (recommended) with its reason in `body` (main is at X, the branch has Y), "Keep Y" when the branch's own entry could stay, and "Another version" (`allowOther`). A `choice` does not check what is typed, so check it yourself: anything that is not `X.Y.Z` gets the card again with a `thread` reply saying so. Left out when the entry is already right. |
| Entries | A `list` titled "Entries to add": one row per suggested entry, `title` the entry line itself (the part they can edit) and `body` its section (`Added`, `Fixed`…). Removable and reorderable; `reply` names renames, additions and removals. A row they add has no section: ask, or file it where it reads best and say so. |
| The result | The final entry as a doc (`id: "entry"`, marked `"saved": "CHANGELOG.md"` once written) plus a `review` card with verdicts `write` ("Write it"), `change` and `stop`. |
| package.json | A `confirm` with the `old → new` in `consequences`. |
| Commit this now? | A `confirm`, "Commit this now?". |
| Version | `choice` "Which version?": the computed version (recommended, reason in `body`), "Keep Y" when the branch's entry could stay, "Another version" (`allowOther`). Typed text is unchecked: anything but `X.Y.Z` gets the card again with a `thread` reply. Skipped when the entry is right. |
| Entries | `list` "Entries to add": `title` the entry line, `body` its section. `reply` names renames, additions, removals. A row they add has no section: ask, or file it and say so. |
| Result | Doc `entry` (`"saved":"CHANGELOG.md"` once written) plus a `review` with verdicts `write`, `change`, `stop`. |
| package.json | `confirm`, `old → new` in `consequences`. |
| Commit now? | `confirm` "Commit this now?" |
A yes to "Commit this now?" ends no session (no `finish`, no `stop`): settle
the card, resume as `git` (`open --resume <sid> --no-open --workflow git`),
then read `~/.agents/skills/plan2code-git/SKILL.md` with your file-read tool
and start with its commit flow, in this same session, as a dashboard launch
does (`console-launches.md`); the resume clears Changelog's page for it.
Entered from **Update CHANGELOG first** on a finished Quick Task or Finalize
(`console-finish.md`): the hop is the same as a dashboard launch, and nothing
else changes. The yes above is the exit to Git as always, so the person lands in
the commit flow with the CHANGELOG already updated.
Finish, on a no: `"dashboard": true` and the version and entries in `body`,
with no `command`. A stop's finish is the bare `/plan2code-changelog`.
A yes ends no session (no `finish`): settle the card, resume as `git` (`open --resume <sid> --no-open --workflow git`), read `~/.agents/skills/plan2code-git/SKILL.md` and start its commit flow.
A no finishes with `"dashboard":true`, version and entries in `body`, no `command`. A stop's `command` is `/plan2code-changelog`.
+13 -58
View File
@@ -1,83 +1,38 @@
# Diagnose on the Web Console
Workflow notes for `diagnose`, part of the web console contract (`console.md`).
# Diagnose
## The bug
A typed argument that already describes the bug skips the cards it answers.
Otherwise ask in one batch (at most three open), posted with `--wait`:
An argument that already describes the bug skips the cards it answers. Otherwise one `--wait` batch, no `templates`:
```jsonc
{
"title": "Diagnose a bug",
"headline": { "stage": "The bug", "cleared": 0, "total": 3 },
"items": [
{ "id": "bug", "kind": "text", "title": "What is wrong",
"body": "The bug, in a sentence or two.",
"placeholder": "The CSV export drops the last row when the report has more than 100 rows." },
{ "id": "expected", "kind": "text", "title": "Expected and actual",
"body": "What should happen, and what happens instead.",
"placeholder": "Expected 150 rows in the file; it has 149, and the last order is missing." },
{ "id": "see-it", "kind": "text", "title": "How to see it",
"body": "The steps, command, page or input that shows it, and since when if you know.",
"placeholder": "Run npm run export -- --month 2026-09 and count the rows. It worked last month." }
]
}
{"title":"Diagnose a bug","headline":{"stage":"The bug","cleared":0,"total":3},"items":[{"id":"bug","kind":"text","title":"What is wrong","body":"The bug, in a sentence or two."},{"id":"expected","kind":"text","title":"Expected and actual","body":"What should happen, and what happens instead."},{"id":"see-it","kind":"text","title":"How to see it","body":"The steps, command, page or input that shows it, and since when if known."}]}
```
No `"templates"` on these cards: the starter templates are for a fresh idea,
and a bug report is not one. A follow-up the answers leave open is a new card
with a new id.
A follow-up the answers leave open is a new card with a new id.
## The cause
Post the cause as a doc, `id` `"cause"`, as soon as there is something to show,
and grow it as evidence lands, with `"agent": { "status": "working",
"activity": "..." }` while you reproduce and narrow:
Doc `cause`, posted as soon as there is something to show and grown as evidence lands, with `agent` `working` while you reproduce:
```jsonc
"docs": [{ "id": "cause", "title": "The cause", "note": "Reproduced; narrowing", "blocks": [
{ "id": "repro", "state": "settled", "md": "## Reproduction\n\n`node scripts/export-check.mjs` fails: 149 rows, expected 150." },
{ "id": "found", "state": "settled", "md": "## The cause\n\n`src/export.ts` `writeRows()`: the loop stops at `rows.length - 1`. **Proven** by the reproduction." },
{ "id": "fix", "state": "settled", "md": "## Suggested fix\n\nLoop to `rows.length`. **Size:** Small (Quick Task)." }
]}]
{"docs":[{"id":"cause","title":"The cause","note":"Reproduced; narrowing","blocks":[{"id":"repro","state":"settled","md":"## Reproduction\n\n..."},{"id":"found","state":"settled","md":"## The cause\n\n..."},{"id":"fix","state":"settled","md":"## Suggested fix\n\n... **Size:** Small (Quick Task)."}]}]}
```
- **Unproven** guesses are `assumed` blocks, one per guess, ranked, each with
its evidence and what would confirm it. A guess the evidence proves becomes
`settled`; one it rules out is removed (`"_delete": true`).
- Keeping a failing test inside the project is a `confirm` card pointing at
the doc (`"doc": "cause"`), `yesLabel` "Keep it", `noLabel` "Throw it away".
- Unproven guesses are `assumed` blocks, ranked, each with its evidence and what would confirm it. Proven: `settled`. Ruled out: `"_delete":true`.
- Keeping a failing test in the project: `confirm` with `"doc":"cause"`, `yesLabel` "Keep it", `noLabel` "Throw it away".
## The bug name
With the cause written, ask the folder name, posted with `--wait`:
After the cause, `--wait`:
```jsonc
{ "id": "name", "kind": "text", "title": "Name for the write-up", "doc": "cause",
"body": "The diagnosis is saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.",
"placeholder": "csv-export-drops-rows",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"patternHint": "Lowercase letters, numbers and dashes, like csv-export-drops-rows." }
{"id":"name","kind":"text","title":"Name for the write-up","doc":"cause","body":"Saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.","placeholder":"csv-export-drops-rows","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","patternHint":"Lowercase letters, numbers and dashes."}
```
Once written, re-send the doc with
`"saved": "specs/<name>/DIAGNOSIS-<date>.md"` and its blocks replaced by one
`file` block for that path (delete the old ids).
Once written, re-send `cause` with `"saved":"specs/<name>/DIAGNOSIS-<date>.md"` and one `file` block for that path (delete the old block ids).
## The finish
`command` is `/plan2code-quick-task specs/<name>` (small fix) or
`/plan2code-1-plan specs/<name>` (big fix) with the real folder filled in
(`/plan2code-quick-task specs/csv-export-drops-rows`), never a placeholder: a
copied command must reach the diagnosis. `body` names the cause, how sure, and that the
next step reads the diagnosis first. `doc` is `"cause"`. `"dashboard": true`,
then keep waiting for the press (`console-finish.md`): back on the dashboard
the folder shows as "Bug diagnosed", with that card lit.
`command` is `/plan2code-quick-task specs/<name>` (small fix) or `/plan2code-1-plan specs/<name>` (big fix), real folder filled in. `body`: the cause, how sure, and that the next step reads the diagnosis first. `"doc":"cause"`, `"dashboard":true`. Nothing kept (did not reproduce, no guess held): no `command`, say so in `body`.
Nothing kept (the bug did not reproduce and no guess held up): leave
`command` out and say so in `body`.
A stop before the file is written ends on a finish whose `body` says nothing
was kept (and names any throwaway script or kept test you wrote), with
`"command": "/plan2code-diagnose"` (`console-stop.md`).
A stop before the file is written: `body` says nothing was kept (and names any throwaway script or kept test), `"command":"/plan2code-diagnose"`.
+2 -11
View File
@@ -1,12 +1,3 @@
# Documentation on the Web Console
# Documentation
Workflow notes for `document`, part of the web console contract (`console.md`).
The questions are few — which draft, a clarification, the sign-off — but the
docs are the point: post each phase file as a doc as it is written, so a
browser-only person watches the spec take shape. Each one mirrors a file on
disk, so carry its `saved` path, and post it as a `file` block
(`{ "id": "body", "file": "specs/<feature>/phase-2.md" }`) rather than pasting
the text you just wrote. Pass `--spec specs/<feature>` once the folder is known;
it is what the resume command needs. Finish commands follow the pipeline: the
sign-off's is `/plan2code-3-implement specs/<feature>/overview.md`.
Post each phase file as a doc as it is written, as a `file` block (`{"id":"body","file":"specs/<feature>/phase-2.md"}`) carrying its `saved` path. Pass `--spec specs/<feature>` once the folder is known. The sign-off's finish `command` is `/plan2code-3-implement specs/<feature>/overview.md`.
+10 -30
View File
@@ -1,34 +1,14 @@
# Finalize on the Web Console
# Finalize
Workflow notes for `finalize`, part of the web console contract (`console.md`).
Finalize is a run of reports and gates, and each maps onto a kind you already
know:
| Step | On the page |
| Step | Card |
| --- | --- |
| 1, Task Completion Audit | The audit table as a doc (`id: "audit"`). If incomplete or blocked tasks exist (`totals.incomplete + totals.blocked > 0`), a `choice` with the three options — return to implementation, mark partially complete, abandon — with the counts against the thresholds in `body`. |
| 2, Implementation Verification | The verification results as a doc. Nothing to ask unless an issue needs their decision. |
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`, as a `file` block on `overview.md`) so the page reader sees it land. |
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
| 6, Spec Cleanup | A `review` item before moving anything (`doc`: Step 3's summary), verdicts `yes` ("Archive it"), `show` ("Show me it working", token `show me`) and `no`, the archive paths in `body`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). On `show`, run it as `notes/implement.md` → Show me it working says (the summary line goes into `overview.md`'s Completion Summary), then reopen the card without `show`. |
| 1, Audit | Table as doc `audit`. If `totals.incomplete + totals.blocked > 0`, a `choice` (return, mark partial, abandon) with counts against thresholds in `body`. |
| 2, Verification | Results as a doc; ask only on an issue. Unless Full Suite is `Never` or `At Phase N`: `confirm` "Run the full suite" (`yesLabel` "Run it", `noLabel` "Skip it", reason in `body`); a failure is the building notes' `choice`. |
| 3, Summary | Written to `overview.md`; mirror it as a doc (`saved`, `file` block). |
| 4, Docs review | Proposed-updates table as a doc, plus a `multi` of documents (ticked = approved); a `review` if all-or-nothing. |
| 5, Feedback | `required:false`: rating as `choice` 1 to 10 or `text`, three reasons as `text`, maintainer consent as `confirm`. |
| 6, Cleanup | `review` (`doc` Step 3's summary), verdicts `yes` ("Archive it"), `show` (token `show me`), `no`; archive paths in `body`, and a line that remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). On `show`, see `notes/implement.md`, then reopen without `show`. |
Post `activity` as each step starts, before its doc or question lands — reading
the spec, running `specs.mjs status` or `archive --dry-run`, checking the
implementation — the same way Review does. A step with no card of its own
(2, 3) is otherwise a stretch of silence the page can only show as "Starting
Finalize".
Post `activity` as each step starts. Pass `--spec specs/<feature>` or post `specDir`.
Pass `--spec specs/<feature>` to `open`, or post `specDir` once you know it.
Stopping mid-finalize loses nothing — the specs are untouched until Step 3's
summary write — so a stop's finish just says where it paused and uses
`"command": "/plan2code-4-finalize specs/<feature>/overview.md"`. On success
the finish's `command` is the suggested commit when Step 4 doc updates landed
(with `"where": "When you are happy with it, commit it from your terminal:"`), otherwise leave `command` out.
When the finish prints that suggested commit, it also carries `"commit": true`,
so the finished screen offers **Commit it now** (`console-finish.md`), and
`"changelog": true` beside it, for **Update CHANGELOG first** (it hops into
Changelog and on to Git). Both only when the finish prints a commit. The
completion summary is printed to a terminal the browser user is not watching,
so put it in `finish.body`.
Finish: the completion summary goes in `body`. `command` is the suggested commit when Step 4 updates landed (`"where":"When you are happy with it, commit it from your terminal:"`, `"commit":true`, `"changelog":true`), else none. A stop loses nothing before Step 3's write: `command` `/plan2code-4-finalize specs/<feature>/overview.md`.
+32 -98
View File
@@ -1,124 +1,58 @@
# Git on the Web Console
# Git
Workflow notes for `git`, part of the web console contract (`console.md`).
Launched from the dashboard or a hand-off: resume the session. The main column is the git board, from `state.git`. **Never post `git`** (exit 3). Your cards sit in the board's card slot.
Open with `--workflow git` (launched from the dashboard, or by a **Commit it
now** or Changelog hand-off: resume the session instead). Like the dashboard,
the main column is drawn by the page itself: the git board, from `state.git`,
which `open` and every `reread` snapshot through `git-repo.mjs`. **You never
post `git`** (exit 3: `state.git` is the console's own). Your cards sit in
the board's card slot, under its tab strip.
**A click** arrives as one session action, one per send, and the board locks
until your next post lands:
A click arrives as one session action per send, and the board locks until your next post lands:
```jsonc
{ "type": "submit",
"actions": [{ "i": "__git", "type": "git", "op": "create",
"name": "feature/export-csv", "from": "origin/main",
"then": "commit", "files": ["src/a.js"], "ignore": ["dist/"] }],
"reply": "Create feature/export-csv from origin/main. ..." }
{"reply":"Create feature/export-csv from origin/main.","session":[{"i":"__git","op":"create","name":"feature/export-csv","from":"origin/main","then":"commit","files":["src/a.js"],"ignore":["dist/"]}]}
```
| `op` | Fields |
| --- | --- |
| `refresh`, `pull`, `push`, `abort`, `continue`, `done` | none (a `refresh` with no remote is "look again": `plan refresh` gives no commands, so just post `reread`) |
| `publish` | `remote?` (left out when there are several: `plan publish` asks which) |
| `switch`, `delete` | `branch` (a remote-only row is `<remote>/<name>`) |
| `create` | `name`, `from`; `then: "commit"` with `files` (and `ignore`, when any) when it came from the commit panel's branch offer |
| `refresh`, `pull`, `push`, `abort`, `continue`, `done` | none (`refresh` with no remote: `plan refresh` gives no commands, just post `reread`) |
| `publish` | `remote?` (absent with several: `plan publish` asks) |
| `switch`, `delete` | `branch` (remote-only row is `<remote>/<name>`) |
| `create` | `name`, `from`; `then:"commit"` with `files` (and `ignore`) from the commit panel's branch offer |
| `cleanup` | `branches[]` |
| `commit` | `files[]` (paths and untracked folders), `ignore[]` (folders to add to `.gitignore`). `files[]` may be empty when `ignore[]` is not: the board's held-back offer (**Add … to .gitignore**). Then add the paths to `.gitignore` and commit only `.gitignore`. |
| `pr-host` | `host`, `kind` (already saved by the page's `POST /pr-host`) |
| `commit` | `files[]`, `ignore[]` (folders for `.gitignore`). `files[]` may be empty when `ignore[]` is not (held-back offer): add the paths to `.gitignore` and commit only `.gitignore`. |
| `pr-host` | `host`, `kind` (already saved by `POST /pr-host`) |
`reply` is the plain instruction the terminal would get, so it reads like any
answer. `__git` names no question, like `__stop`.
**After an action**, in ONE post (with `--wait`):
**After an action**, ONE post with `--wait`:
```jsonc
{ "reread": true,
"items": [{ "id": "git-result", "kind": "notice", "status": "open",
"title": "Pushed 2 commits to origin/feature/x",
"body": "a1b2c3d, e4f5a6b. [Open pull request](https://github.com/...)" }],
"board": { "describe": "export-csv-button" } }
{"reread":true,"items":[{"id":"git-result","kind":"notice","title":"Pushed 2 commits to origin/feature/x","body":"a1b2c3d, e4f5a6b. [Open pull request](https://github.com/...)"}],"board":{"describe":"export-csv-button"}}
```
- `reread` is `true`, or `{ "refreshFailed": true }` after a Refresh that
failed (the board then says so beside the last refreshed time and keeps the
last data). It goes only with the `git` workflow; anywhere else, or in any
other shape, it is exit `3`. The console takes the snapshot inside the same
locked write as your cards, so the result line and the fresh board land
together.
- `git-result` is a `notice` replaced every action (same id). The board shows
it under its header, not in the card slot: what happened, with short hashes
and, after a push or publish, the `pr-url` link. On a failure it quotes
git's stderr verbatim with `classify-error`'s `next`.
- `board.describe` is yours: a short kebab-case description of the changes
still on the tree, which the Create prompt pre-fills. Post it with the
reread whenever changes remain; leave it out otherwise.
- The board is the person's to click whenever you wait, so `wait` hands the
turn back by itself; no `agent` status is needed.
- `reread` is `true`, or `{"refreshFailed":true}` after a failed Refresh. Only with the `git` workflow, else exit 3.
- `git-result` is one `notice` replaced every action: what happened, short hashes, the `pr-url` link after a push or publish. A failure quotes git's stderr verbatim with `classify-error`'s `next`.
- `board.describe`: short kebab-case description of the changes still on the tree (prefills Create); leave out when none remain.
**Cards per `plan`.** `git.mjs plan <op>` decides whether to ask:
**Cards per `plan`** (`git.mjs plan <op>`):
| `plan` says | On the page |
| --- | --- |
| `confirm` | A `confirm` card with its `title`, `body`, `danger` and `consequences` verbatim (the consequences end with the exact command). Where the plan names files, add them as `files: [{ "path", "state" }]`. |
| `card.kind: "switch"` | A `choice`, "Bring your changes?": exactly the `options` given, labeled **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); the files in `body`, and `reason` when git would refuse (then there is no `bring`). `allowOther: false`. |
| `card.kind: "dirty"` | The same `choice` for a pull that needs a clean tree: **Commit first** / **Cancel**, `reason` in `body`. |
| `card.kind: "remote"` | A `choice`, "Publish to which remote?": one option per remote, `preset` recommended. Then `plan publish --remote <it>` and its `confirm`. |
| `ask: false` | No card: run it on the click. |
| exit 4 or 5 | No card and nothing run: the `message` and `next` as the `git-result` notice. |
| `confirm` | `confirm` with `title`, `body`, `danger`, `consequences` verbatim; named files as `files:[{"path","state"}]`. |
| `card.kind:"switch"` | `choice` "Bring your changes?", exactly the given `options`: **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); files in `body`, `reason` when git refuses (no `bring` then). `allowOther:false`. |
| `card.kind:"dirty"` | Same `choice`, **Commit first** / **Cancel**, `reason` in `body`. |
| `card.kind:"remote"` | `choice` "Publish to which remote?", one option per remote, `preset` recommended; then `plan publish --remote <it>` and its `confirm`. |
| `ask:false` | No card: run on the click. |
| exit 4 or 5 | Nothing run: `message` and `next` as the `git-result` notice. |
An `auth` failure gets a `notice` card saying the tool never handles logins,
with `next`. The commit flow's own cards (message, groups, `git init`,
`.gitignore`) are the rows below.
An `auth` failure: a `notice` saying the tool never handles logins, with `next`.
| Commit step | On the page |
| --- | --- |
| One commit | A `text` card whose `placeholder` is the drafted subject and whose `pattern` caps it at 100 characters, then a `confirm` "Commit this?" with the files in `consequences` and, as `files: [{ "path": "src/a.js", "state": "modified" }]` (states: modified, new, deleted, renamed), a collapsed **Show the N files** table on the card. With the subject given as the argument there is no card. |
| A split | The groups as a doc (`id: "commits"`: each group's subject and files, and any file that mixes concerns) plus a `review` card with verdicts `approve`, `change` and `single` ("One commit instead"). Asked even when the subject came as the argument. |
| Push | Not asked after a commit on the board: the board lights Push. `commit and push` (or a Push click) asks `plan push` / `plan publish`'s `confirm`. |
| `git init` | A `confirm` naming the folder and its first branch (`init-check`'s `branch`, `danger: false`), its `consequences` `init-check`'s `commands`. Run those, not a bare `git init`. |
| `.gitignore` | The proposed file, or the lines a `commit`'s `ignore[]` adds, as a doc plus a `review` card. |
| One commit | `text` card, `placeholder` the drafted subject, `pattern` capping it at 100 characters, then `confirm` "Commit this?" with files in `consequences` and `files:[{"path","state"}]` (modified, new, deleted, renamed). No card when the subject was the argument. |
| A split | Doc `commits` (each group's subject and files, files mixing concerns) plus `review` with verdicts `approve`, `change`, `single` ("One commit instead"). Asked even with a subject argument. |
| Push | Not asked after a board commit (the board lights Push). `commit and push` or a Push click asks `plan push` / `plan publish`'s `confirm`. |
| `git init` | `confirm` naming folder and first branch (`init-check`'s `branch`, `danger:false`), `consequences` its `commands`. Run those, not a bare `git init`. |
| `.gitignore` | The proposed file, or a `commit`'s `ignore[]` lines, as a doc plus `review`. |
Risky files (`sensitive`, `large`) are named in the card's `body`. On the
board there is no branch-offer card: the commit panel's **You're on main**
line asks it, and the answer arrives as `create` with `then: "commit"`.
Risky files (`sensitive`, `large`) go in the card's `body`. There is no branch-offer card: the commit panel's **You're on main** asks, answered as `create` with `then:"commit"`.
**Conflict help.** A pull, rebase or merge stopped on conflicts asks first, a
`choice` "Resolve them for me?": **Yes**, **I'll fix it**, **Abort pull**.
On yes, every stop is a doc (`id: "conflict"`, replaced per stop, its version moving by itself: step N of M,
the commit being replayed, each file with a one-line reason, then a per-file
diff) plus a `review` card, fresh id per stop, `"nothingYet": false` (the resolution is already on disk), with the verdicts `continue`
("Continue"), `change` ("Change it") and `abort` ("Abort pull", `danger`).
Only **Continue** runs `plan continue`'s commands; **Abort pull** runs
`plan abort` and the board is back on the exact original HEAD. A file you
cannot resolve with confidence is named and left with its markers; **I'll fix
it** leaves the markers too. The board's banner always offers Continue: a
`continue` click is the person saying the files are fixed, so run `plan
continue`; when it refuses (exit 5, markers left), post a `reread` with its
`message` as the `git-result` notice, which also refreshes the banner's file
list. Nothing is pushed during conflict help. At the end, a `notice`
summary (commits replayed, each resolved file with its reason, "N commits
ready to push").
**Conflict help.** A pull, rebase or merge stopped on conflicts: `choice` "Resolve them for me?": **Yes**, **I'll fix it**, **Abort pull**. On yes, each stop is doc `conflict` (replaced per stop: step N of M, the commit replayed, each file with a one-line reason, per-file diff) plus a `review` with a fresh id per stop, `"nothingYet":false`, verdicts `continue`, `change`, `abort` ("Abort pull", `danger`). Only **Continue** runs `plan continue`'s commands; **Abort pull** runs `plan abort`. A file you cannot resolve confidently keeps its markers, as does **I'll fix it**. A `continue` click from the board's banner means the files are fixed: run `plan continue`; on exit 5 (markers left) post a `reread` with its `message` as the `git-result`. End with a `notice` summary (commits replayed, each resolved file with its reason, "N commits ready to push").
**Meter events** (`console-meter.md`). Git scores on launch.
Post `run: { "event": "git-commits", "id": "<first short hash>", "commits": N }`
after each commit step (N commits made), and `run: { "event": "git-conflict",
"id": "conflict-<n>" }` once per conflict help, resolved or aborted.
**Meter.** Post `run:{"event":"git-commits","id":"<first short hash>","commits":N}` after each commit step, and `run:{"event":"git-conflict","id":"conflict-<n>"}` once per conflict help.
**Finishing** (`console-finish.md`). **Done with git** (`op: "done"`). A `done`
that arrives while one of your cards is still open is the person canceling it:
record that card as canceled (`{ "items": [{ "id": "<id>", "status":
"answered", "answer": { "text": "Canceled by Done with git" } }] }`, not
`settle`, which refuses a card nothing was sent to) in the same post as the
finish, or, with nothing done, before resuming as the dashboard. Never run what
the card was asking for. With something done this session: a `finish` with a
headline, the commits with hashes, pushes and branches created or deleted in
`body`, no `command`, and `"dashboard": true`; keep waiting for the press. Done
with nothing done: no finish screen — resume as `dashboard` at once (`open
--resume <sid> --no-open --workflow dashboard`), read the dashboard skill
(`~/.agents/skills/plan2code/SKILL.md`), post its `menu` with `--wait` and
carry on from its "Coming back from another skill". A stop's finish is a pause,
headline "Paused …", the bare `/plan2code-git`, then `stop`.
**Finishing.** **Done with git** is `op:"done"`. A `done` while one of your cards is open cancels it: record it `{"items":[{"id":"<id>","status":"answered","answer":{"text":"Canceled by Done with git"}}]}` (not `settle`) in the finish post, or, with nothing done, before resuming as the dashboard. Never run what that card asked. Something done: `finish` with a headline and the commits (hashes), pushes and branches created or deleted in `body`, no `command`, `"dashboard":true`. Nothing done: no finish screen; resume as `dashboard` (`open --resume <sid> --no-open --workflow dashboard`), read `~/.agents/skills/plan2code/SKILL.md`, post its `menu` with `--wait`, carry on from "Coming back from another skill". A stop's finish is a pause, "Paused ...", bare `/plan2code-git`.
+2 -10
View File
@@ -1,11 +1,3 @@
# Handoff on the Web Console
# Handoff
Workflow notes for `handoff`, part of the web console contract (`console.md`).
One gate: the next-task confirmation, then the document itself as a doc —
that is what the person is there to download. Give it no `saved` and paste it
as `md`: the handoff file lives in `~/.plan2code/handoffs/`, outside the project,
where a `file` block is refused, and the download is the point. The finish carries no
`command`: the doc download is the point, and the dashboard button and the
"All done" line cover what comes next. Unless it is a pause, the finish carries
`"dashboard": true` and you keep waiting for the press (`console-finish.md`).
One gate (next-task confirmation), then the document as a doc with `md`, no `saved` (the file lives outside the project, where a `file` block is refused). The finish has no `command`; unless it is a pause it carries `"dashboard":true`.
+22 -152
View File
@@ -1,193 +1,63 @@
# Implement on the Web Console
# Implement
Workflow notes for `implement` and `implement-review`, part of the web console
contract (`console.md`). Read `building.md` first.
`implement` and `implement-review`. Read `building.md` first.
## The first post of a phase
## First post of a phase
```jsonc
{
"headline": { "stage": "Phase 3: API layer", "cleared": 0, "total": 9 },
"docs": [
{ "id": "phase", "title": "Phase 3 tasks", "blocks": [
{ "id": "tasks", "file": "specs/<feature>/phase-3.md", "select": "tasks" }
]},
{ "id": "phasefile", "title": "phase-3.md", "blocks": [
{ "id": "body", "file": "specs/<feature>/phase-3.md" }
]}
],
"agent": { "status": "working", "activity": "Checking the prerequisites", "quietMinutes": 15 }
}
{"headline":{"stage":"Phase 3: API layer","cleared":0,"total":9},"docs":[{"id":"phase","title":"Phase 3 tasks","blocks":[{"id":"tasks","file":"specs/<feature>/phase-3.md","select":"tasks"}]},{"id":"phasefile","title":"phase-3.md","blocks":[{"id":"body","file":"specs/<feature>/phase-3.md"}]}],"agent":{"status":"working","activity":"Checking the prerequisites","quietMinutes":15}}
```
`phase` is the task list, `phasefile` the whole `phase-X.md` as its own tab —
the person can read the prerequisites and task specs while you build. Both are
read from disk by the console: never paste the file. It renders as markdown, so
the file's checkboxes show as ticks exactly as they stand on disk.
A later phase in the same session posts the same two docs with the new phase's
title and file: their content changed, so their versions move up by themselves
(a doc's version never goes back, and you no longer have to track it). Leave
`version` out.
`phase` is the task list, `phasefile` the whole file. A later phase posts the same two docs with the new title and file.
## After every task
In the same breath as writing the task's checkbox to disk:
With the checkbox write:
```jsonc
{
"headline": { "cleared": 4 },
"docs": [ { "id": "phase", "refresh": true }, { "id": "phasefile", "refresh": true } ],
"agent": { "activity": "Task 5 of 9: the rate limiter" }
}
{"headline":{"cleared":4},"docs":[{"id":"phase","refresh":true},{"id":"phasefile","refresh":true}],"agent":{"activity":"Task 5 of 9: the rate limiter"}}
```
`refresh` re-reads the file the checkbox write just changed, so both tabs tick
in place; the Phase Completion Summary lands in `phasefile` the same way at the
end. Then the `chat` check (`building.md` → Quick questions between tasks).
---
The Phase Completion Summary lands in `phasefile` the same way. Then the `chat` check.
## Sign-off
Put the Completion Report on the page as a doc, then ask for approval as a
`review` item pointing at it. The review offer rides on this card, as a verdict
ahead of the approval buttons — not on the finish after it, where it could
only ever be offered once nothing could come of it:
Loop mode (`notes/loop.md`) posts `loopOutcome` instead. Otherwise the Completion Report is a doc and the approval a `review` pointing at it; the review offer is a verdict here, not on the finish:
```jsonc
{
"docs": [{ "id": "report", "title": "Completion report", "blocks": [
{ "id": "summary", "state": "settled", "md": "## Summary\n\n..." },
{ "id": "files", "state": "settled", "md": "## Files\n\n..." },
{ "id": "verify", "state": "settled", "md": "## How to check it\n\n..." }
]}],
"items": [{
"id": "signoff", "kind": "review", "title": "Approve this phase", "doc": "report",
"body": "Phase 3 is built. Read the report, try the checks, then approve it, review the code first, see it running, or say what to change.",
"verdicts": [
{ "id": "review", "label": "Review the code first" },
{ "id": "approve", "label": "Approve this phase" },
{ "id": "show", "label": "Show me it working" },
{ "id": "changes", "label": "I want changes" }
],
"token": { "approve": "approved", "changes": "needs changes", "show": "show me" },
"nothingYet": "Nothing is marked complete until you approve.",
"gate": { "id": "signoff", "authoritative": true }
}]
}
{"docs":[{"id":"report","title":"Completion report","blocks":[{"id":"summary","state":"settled","md":"## Summary\n\n..."},{"id":"files","state":"settled","md":"## Files\n\n..."},{"id":"verify","state":"settled","md":"## How to check it\n\n..."}]}],"items":[{"id":"signoff","kind":"review","title":"Approve this phase","doc":"report","body":"Phase 3 is built. Read the report, try the checks, then approve it, review the code first, see it running, or say what to change.","verdicts":[{"id":"review","label":"Review the code first"},{"id":"approve","label":"Approve this phase"},{"id":"show","label":"Show me it working"},{"id":"changes","label":"I want changes"}],"token":{"approve":"approved","changes":"needs changes","show":"show me"},"nothingYet":"Nothing is marked complete until you approve.","gate":{"id":"signoff","authoritative":true}}]}
```
Posted with `--wait`. `reply` carries `Approve this phase: approved`, which is
the terminal's `approved`. If the note that came with an approval asks for a
change, treat it as "describe any issues": do the change first and ask again.
`changes` means exactly what it says: address it, update the report, and reopen
the item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
person asking for the code review before they approve anything — read
`building-review.md`. `show` is the terminal's `show me`: see below.
Posted with `--wait`. An approval whose note asks for a change: do the change first and ask again. `changes`: address it, update the report, reopen the item with a `thread` reply. `review`: read `building-review.md`. `show`: below.
A later phase in the same session asks with a new id (`signoff-phase-2`, title "Approve Phase 2"); the old card is a record.
### Show me it working
On `show`, run the workflow's **Show me it working** paragraph (start the app,
look at the change, stop it, one summary line in `phase-X.md`). Save each
screenshot under the session's `shots/` folder, never under `specs/`, and post
them as image blocks in a `shown` doc (`console.md` → Documents), with what was
run in a `md` block above them; no browser tool means that block alone says
what the command printed. Then reopen the same card (`"status": "reopened"`)
without the `show` verdict, a `thread` reply naming what was seen. The same
holds on Finalize's card and the one `building-review.md` reopens; Quick
Task's card is settled instead (`notes/quick-task.md`).
`gate` marks the one approval that counts. The server refuses a second open
authoritative gate, which is what keeps a composed workflow from asking for
sign-off twice. A later phase in the same session asks with a new id
(`signoff-phase-2`, its title naming the phase, "Approve Phase 2", so the rail tells
the two apart), since the last phase's approved card is a record: the same
id posted again would only edit that record.
---
On `show`, run the workflow's **Show me it working** paragraph. Save screenshots under the session's `shots/`, never `specs/`, and post them as image blocks in a `shown` doc with what was run in a `md` block above (no browser tool: that block alone says what the command printed). Then reopen the same card without the `show` verdict, with a `thread` reply naming what was seen. Same on Finalize's card and the one `building-review.md` reopens; Quick Task's card is settled instead.
## After approval: the finish
Do everything the workflow does on approval (the checkboxes, the summary, the
upcoming phases, the commit command) and print it in the terminal as usual.
Then post the finish, wait for the dashboard button as `console-finish.md`
says, and `stop`:
Do what the workflow does on approval and print it in the terminal as usual, then:
```jsonc
{
"settle": true,
"run": { "event": "implement-phase", "id": "phase-3", "tasks": 9 },
"finish": {
"headline": "Phase 3 is done",
"body": "9 of 9 tasks, all on disk.\n\n| Phase | Tasks | Goal |\n| --- | --- | --- |\n| Phase 4: ... | 6 | ... |\n\nCommit it with:\n\n```\ngit add -A && git commit -m \"...\" -m \"AI Assisted\"\n```",
"command": "/plan2code-3-implement specs/lunch-vote/overview.md",
"doc": "report",
"commit": true,
"dashboard": true
}
}
{"settle":true,"run":{"event":"implement-phase","id":"phase-3","tasks":9},"finish":{"headline":"Phase 3 is done","body":"9 of 9 tasks, all on disk.\n\n| Phase | Tasks | Goal |\n| --- | --- | --- |\n| Phase 4: ... | 6 | ... |\n\nCommit it with:\n\n```\ngit add -A && git commit -m \"...\" -m \"AI Assisted\"\n```","command":"/plan2code-3-implement specs/lunch-vote/overview.md","doc":"report","commit":true,"dashboard":true}}
```
`"commit": true` is there because the body prints a git command: the finished
screen gets a **Commit it now** button, and its `__commit` press is handled as
`console-finish.md` says (resume as `git` and open its commit flow, same
session). Leave it out when the body prints no commit.
`commit:true` only when the body prints a commit. `command` is the next step: `/plan2code-3-implement specs/<feature>/overview.md`, or `/plan2code-4-finalize specs/<feature>/overview.md` after the last phase. No `review` on the finish.
`finish.command` is the next pipeline step, the same one the terminal names:
the next `/plan2code-3-implement specs/<feature>/overview.md`, or
`/plan2code-4-finalize specs/<feature>/overview.md` after the last phase. An `implement` finish never carries `review`: the offer was on the
sign-off card, and approving past it was the answer. `implement-review` ends
the same way; that phase was reviewed already.
`run` gives the approved phase its final score on the session meter
(`console-meter.md`), in the same post that records the approval; it takes over
what the build already counted from `cleared`, never adds to it:
`implement-phase` for Implement, `implement-review-phase` for Implement +
Review, id `phase-N`, and `tasks`: how many of the phase's tasks were
completed (`[x]`, not blocked `[!]`). The phase scores by its size, so a
twelve-task phase weighs four times a three-task one; leave `tasks` out and
every phase weighs the same. A review run on the page after a build reports its
own (`building-review.md`).
---
`run` takes over what `cleared` counted, never adds: `implement-phase` (Implement) or `implement-review-phase` (Implement + Review), id `phase-N`, `tasks` the completed ones (`[x]`, not `[!]`); without `tasks` every phase weighs the same.
## Manual check-off (`next.action` is `checkoff`)
No phase to build: the open tasks under approved phases are asked about one
at a time, one `confirm` item each, posted with `--wait`:
Open tasks under approved phases, one `confirm` each, `--wait`:
```jsonc
{
"headline": { "stage": "Manual check-off", "cleared": 0, "total": 2 },
"items": [{
"id": "checkoff-3.4", "kind": "confirm", "title": "Task 3.4",
"body": "**Configure the SSO app in Okta**\n\nBLOCKED: needs admin access. User action: create the app and paste its client id into `.env`.\n\nIs this done?",
"yesLabel": "Done, check it off", "noLabel": "Not yet"
}]
}
{"headline":{"stage":"Manual check-off","cleared":0,"total":2},"items":[{"id":"checkoff-3.4","kind":"confirm","title":"Task 3.4","body":"**Configure the SSO app in Okta**\n\nBLOCKED: needs admin access.\n\nIs this done?","yesLabel":"Done, check it off","noLabel":"Not yet"}]}
```
`yes` → `specs.mjs tick`, then `"headline": { "cleared": N }` with the next
item. When the last one is answered, post the finish: `command` is
`/plan2code-4-finalize specs/<feature>/overview.md` when `tick` said
`remaining` is empty, otherwise the same `/plan2code-3-implement` command,
and `body` lists what is still open. No `run` (nothing was built), no
`commit` unless a body prints one.
---
Yes: `specs.mjs tick`, `{"headline":{"cleared":N}}` with the next item. After the last: finish with `command` `/plan2code-4-finalize specs/<feature>/overview.md` when `tick` said `remaining` is empty, else `/plan2code-3-implement ...`; `body` lists what is open. No `run`, no `commit` unless the body prints one.
## Implement + Review (`implement-review`)
The same build, then Stage 2 publishes the findings exactly as
`building-review.md` → The findings (the `review` doc and the `fixes` item).
Stage 3 fixes, with no "Check the fixes" item: Stage 4 is the only gate. The
post that starts Stage 2's review carries `"run": { "event": "review", "id":
"review" }`: in this workflow it scores the review stage's 1 point on the meter
as it begins, and the phase's final `run` leaves that point out. Stage 4 is the
sign-off above (`show` included) **without the review verdict** — the phase was already reviewed
— with the review results and unresolved findings in the report doc, header
"Reviewed and ready for sign-off" in the item's `body`. The finish never
carries `review`, and its post carries `"run": { "event":
"implement-review-phase", "id": "phase-N", "tasks": N }` with the count of
completed tasks.
Stage 2 publishes findings as in `building-review.md` (The findings). Stage 3 has no "Check the fixes" item. The post starting Stage 2 carries `"run":{"event":"review","id":"review"}` (scores 1 point; the final `run` leaves it out). Stage 4 is the sign-off above, `show` included, without the `review` verdict, with review results and unresolved findings in the report and "Reviewed and ready for sign-off" in `body`. Its finish `run` is `implement-review-phase`.
+2 -13
View File
@@ -1,14 +1,3 @@
# Init and Init Update on the Web Console
# Init and Init Update
Workflow notes for `init` and `init-update`, part of the web console contract
(`console.md`).
Setup conversations: every confirmation and Q&A item goes through the page.
For `init` and `init-update` the finished AGENTS.md also lands as a doc so a
browser-only person can read what was written — marked `"saved": "AGENTS.md"`,
since the file itself is already on disk (or as a `file` block:
`{ "id": "body", "file": "AGENTS.md" }`, instead of pasting it). A completed run
finishes with **no** `command`: the page shows the "All done" line. Nothing is
on disk to resume mid-run, so a stop's finish command is the bare
`/plan2code-init` or `/plan2code-init-update` — the skill starts over
either way.
Post the finished AGENTS.md as a doc (`"saved":"AGENTS.md"` or a `file` block). A completed run finishes with no `command`; a stop's is the bare `/plan2code-init` or `/plan2code-init-update`.
+168
View File
@@ -0,0 +1,168 @@
# Loop Mode on the Web Console
Workflow notes for Implement and Implement + Review started by the desktop app's
Implementation Loop with `--loop`, part of the web console contract
(`console.md`). 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 plain `open`; run it again now, before any post, as
`node "<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,
`loopOutcome` and `handledBy` are 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 that `open` succeeded.
- `--fix <levels>`: a comma list from `critical`, `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 chooses which findings to fix, in
place of a level list (see Triage). The one fix round and the fresh re-check
are unchanged.
- `--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
- Pick the phase without asking (Choosing the phase).
- No sign-off card, no "Approve this phase", no Show me it working, no Continue
offer.
- Never run `specs.mjs mark --to done`, and never set `[x]` on the phase in
`overview.md`. Tasks inside the phase file are still checked off as they
finish: `[x]`, `[!]` when blocked, `[?]` when assumed.
- Never run `git` in any form (no add, commit, stash, checkout), and never
`commit-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`, report `failed`, reason `conflict`.
- A blocked prerequisite or task: mark the task `[!]`, list it in
`tasks.blocked`, report `failed`, reason `blocked`.
- Failing tests: try one fix, then report `tests.passed: false`, `failed`,
reason `tests`. Never post the Fix now, Document or Investigate options.
- A waiting `**Plan change:**` line in the phase's Notes: do not ask Revise
first or Resume; report `failed`, reason `other`, and say so in `summary`.
- Run only the tests the phase file names, as the Implement prompt's tests rule
says: a phase task or a task's `Test:` line (a `## Phase Testing` block counts
when it lists them as tasks). Never the full suite unless the phase file names it.
## Headline stages
Post `headline.stage` as each begins, using only these words: `Build`, `Review`,
`Fixes`, `Re-check`, `Reporting`. The app's strip reads them, and any other word
shows as Build, so do not invent new ones in loop mode. Keep `cleared` and
`total` as in any build.
## Choosing the phase
Run `node "<S>/specs.mjs" status specs/<feature>`. A phase whose checklist marker
is `[/]` goes first; otherwise take `next.phase.number` (the first of
`next.options` when `next.action` is `choose`). Never post the "Resume?" question
or the parallel-phase pick. Set the phase in progress with
`specs.mjs mark <spec> --phase N --to in-progress`, exactly as an ordinary run
does: that mark is allowed, and only `--to done` is the app's. When `next.action`
is `none` or `checkoff` (no open phase), post a `loopOutcome` with
`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 with `post --wait` as usual. The app sees it open
and holds or stops the loop. Do not mark it `handledBy`.
- 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 as usual.
## 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; the stage words do not
change.
## Reporting the outcome
At the end of the run, post once a top-level `loopOutcome`:
```json
{ "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" } }
```
- `result` is `"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 (otherwise `failed`, reason `findings`). Otherwise `"failed"`, with the first matching
`reason`: `tests`, `findings`, `blocked`, `conflict` or `other`. A passed
outcome has `"reason": null`.
- `review.triage` is present only with `--fix smart`: `ran: true` and `skipped` listing
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
reason `findings`. `unfixed` lists only picked findings still open after the
re-check; skipped findings go only in `triage.skipped` (the app adds them to the
summary), and the 50-entry limits of the two lists are separate.
- `review.fixed` lists every finding the fix round fixed (an empty list when none,
or with no review), at most 50.
- `decisions` lists, 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 the `Assumed:` 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.ran` and `review.recheck` are `false` when the run did no review or no
re-check (plain Implement, or no `--fix` level; never with `--fix smart`). `tasks.blocked` and
`tasks.assumed` list task ids like `"2.4"`. `conflicts` holds one line per
spec conflict.
- `subject` is one imperative line under 100 characters saying what changed (it
becomes the commit subject). `summary` is one line under 200 characters.
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.
+14 -65
View File
@@ -1,77 +1,26 @@
# Pathfinder on the Web Console
# Pathfinder
Workflow notes for `pathfinder`, part of the web console contract (`console.md`).
- Every probe, recap and menu goes through the page.
- Post `"stopWarning"` while no map exists (Steps 0 to 4) and `"stopWarning": ""`
once it does, and `"specDir": "specs/<idea>"` when the folder is created
(`console-stop.md` → Saying what stopping would cost).
- The menu after a decision is a `menu` card: its `options` are `trail --form C`'s, and the `Start fresh` one keeps its `"fresh": true` (the page words it "Start New Session" under the desktop app and asks the app for one on Send). Set the card's `command` to the resume command printed under `OR START FRESH`: the page copies it first. A declined confirm leaves you the pick: carry on as for any `Start fresh`.
- The fresh-idea card carries `"templates": "idea"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
- A doc that is a file exactly as written (the map once it is on disk, a
brief) goes up as a `file` block (`{ "id": "body", "file":
"specs/<idea>/pathfinder/map.md" }`) rather than pasted. Keep `md` blocks
where a block's `assumed` / `draft` state carries meaning.
- Chart Step 8's research subagents must all report back before the
finish (`console-finish.md` → Nothing of yours may still be running); the
finish body then names what each one found.
- Report every research subagent as a helper, whatever the Subagents switch
says (`console-subagents.md` → Reporting helpers).
- At every session end, post `finish` (headline, `body`, and Form A's command as
`command`) BEFORE `stop`. Someone who spent the session in the browser never
sees the Trail Footer, and without this their last screen promises a question
that is never coming.
- Post `run` `pathfinder-chart` (id `map`) when a new map is first written,
and `pathfinder-research` (id = the question's file slug; on `github`, `q<issue-number>`) as each research
subagent reports back, or when you resolve a `research` question yourself
(`console-meter.md`). Other questions score through their answers, so there is
nothing to post for them.
- The scope probe is **Leave for later**: "Which of these features are we
leaving out this time?" as a `multi` with a recommended preset. Every option
names a feature, and its `detail` ends "(Leaving this out = …)". Never phrase
an option as a rule to keep.
- Post `"stopWarning"` while no map exists (Steps 0 to 4), `""` once it does, and `"specDir":"specs/<idea>"` when the folder is created.
- The menu after a decision is a `menu` card: `options` are `trail --form C`'s, the `Start fresh` one keeps `"fresh":true`. Set the card's `command` to the resume command printed under `OR START FRESH`. A declined confirm leaves you the pick: carry on as for `Start fresh`.
- The fresh-idea card carries `"templates":"idea"`, `"fill":"note"`.
- A doc that is a file as written (the map, a brief) is a `file` block (`{"id":"body","file":"specs/<idea>/pathfinder/map.md"}`). Keep `md` where `assumed` / `draft` state matters.
- Step 8 research subagents all report before the finish; the finish `body` names what each found. Report every one as a helper, whatever the Subagents switch says.
- Every session end `finish`es with Form A's command as `command`.
- Post `run` `pathfinder-chart` (id `map`) when a map is first written, and `pathfinder-research` (id the question's file slug; on `github`, `q<issue-number>`) as each research subagent reports or when you resolve a `research` question yourself. Other questions score through answers.
- The scope probe is **Leave for later**: "Which of these features are we leaving out this time?" as a `multi` with a recommended preset. Each option names a feature, its `detail` ends "(Leaving this out = ...)". Never phrase an option as a rule to keep.
## Briefs
The page shows a **Write a brief** button when `workflow` is `pathfinder`,
because that is the workflow with a brief playbook. The person picks a range and
presses it; nothing else about the session changes.
It arrives through the wait loop like any other send:
The page shows **Write a brief** for this workflow. It arrives as a send:
```jsonc
{
"type": "submit",
"actions": [{ "i": "__brief", "type": "brief", "range": "since 2026-09-15" }],
"reply": "Write a brief covering everything since 2026-09-15."
}
{"reply":"Write a brief covering everything since 2026-09-15.","session":[{"i":"__brief","range":"since 2026-09-15"}]}
```
`range` is one of `today`, `this week`, `since <YYYY-MM-DD>` or `full`, which is
the range grammar the brief playbook already parses. `reply` says the same thing
in words, so a workflow that only reads `reply` needs no new code path. The
`__brief` id is not an item and matches nothing; it marks the action as being
about the session rather than about a question.
Run your normal brief procedure, write the file where it belongs, and then put
the same report on the page as a doc, as a `file` block on the file you wrote:
`range` is `today`, `this week`, `since <YYYY-MM-DD>` or `full`. `__brief` matches no item. Run your brief procedure, write the file, then post it as one `file` block in doc `brief` (reused, so a second replaces the first; Save as HTML appears only on that id):
```jsonc
{
"docs": [{
"id": "brief",
"title": "Brief",
"note": "Covers this week",
"blocks": [{ "id": "body", "file": "specs/<idea>/pathfinder/briefs/<the brief>.md" }]
}]
}
{"docs":[{"id":"brief","title":"Brief","note":"Covers this week","blocks":[{"id":"body","file":"specs/<idea>/pathfinder/briefs/<the brief>.md"}]}]}
```
One block holding the whole report is right here: a brief is read start to
finish, not block by block, and it gets Save as HTML, Print and Download buttons
that work on the document as a whole. Save as HTML appears only on the doc with
the id `brief`. Reuse the id `brief` so a second brief replaces the first
rather than growing a row of tabs; its version moves up by itself.
Say in chat where the file went, as you always would. The page is a second copy
for reading and printing, never the record.
Say in chat where the file went.
+5 -21
View File
@@ -1,22 +1,6 @@
# Planning on the Web Console
# Planning
Workflow notes for `plan`, part of the web console contract (`console.md`).
- Open with `--workflow plan`, first thing. Every question and sign-off gate
goes through the page, phase breakdowns as an editable `list`.
- The fresh-idea card carries `"templates": "idea"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
- Planning has no mid-session save before the Large checkpoint or Phase 7, so for
a stop before then say plainly in `finish.body` that nothing was kept, and use
`"command": "/plan2code-1-plan"`. After the checkpoint, post
`"stopWarning": ""` (`console-stop.md`).
- At every session end, post `finish` BEFORE `stop`; on completion that is
`"command": "/plan2code-2-document"`, and at the Large checkpoint it is
`/plan2code-1-plan`. The closing message is printed to a terminal the
browser user is not watching.
- The Large checkpoint finish is a pause: a headline starting "Paused", no
`dashboard`, and `stop` at once.
- Plan offers the Subagents switch. A `Subagents:` block may arrive on `open`
output or a `wait` / `chat` pickup: follow `console-subagents.md` and the
skill's Helpers section, and report each helper as `helpers`. Post a helper
as `done` or `failed` before the sign-off it feeds, and every one before a
`finish`. Questions, sign-offs and the PLAN-DRAFT stay with you.
- Phase breakdowns are an editable `list`. The fresh-idea card carries `"templates":"idea"`, `"fill":"note"`.
- Nothing is saved before the Large checkpoint or Phase 7: a stop before then has `finish.body` say nothing was kept, `"command":"/plan2code-1-plan"`. After the checkpoint post `"stopWarning":""`.
- Completion finish `command`: `/plan2code-2-document`. The Large checkpoint finish is a pause: headline starts "Paused", `command` `/plan2code-1-plan`, no `dashboard`.
- Helpers are reported as `helpers`, each `done` or `failed` before the sign-off it feeds. Questions, sign-offs and the PLAN-DRAFT stay with you.
+19 -91
View File
@@ -1,106 +1,34 @@
# Quick Task on the Web Console
# Quick Task
Workflow notes for `quick-task`, part of the web console contract
(`console.md`). Read `building.md` first.
Read `building.md` first.
## Quick task (`quick-task`)
- Open with the first clarifying question. Clarifying questions go out as
`text` or `choice`, at most three at a time. The first, asking what to build,
carries `"templates": "idea"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
- Post `"stopWarning": "A quick task saves nothing until it is built, so stopping now loses what we have worked out."`
at the start, and `"stopWarning": ""` once the build is under way.
- **Scope check:** a `choice`, "Too big for a quick task?", options
`1` Continue (lightweight format) and `2` Escalate to a full plan, with the
measured counts against the thresholds in `body`.
- **Feature name** (escalating): `text` with
`"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"` and a kebab-case placeholder.
- **The plan:** a `plan` doc titled "Plan", one block per section, with the
Steps written as a checklist so the build can tick them in place, and a
`review` item "Build this plan?" (`"doc": "plan"`) with verdicts `yes`
("Build it"), `modify` ("Change the plan"), `escalate` ("Plan it properly
instead") and `abort` ("Stop here", `"danger": true`):
- Clarifying questions are `text` or `choice`. The first (what to build) carries `"templates":"idea"`, `"fill":"note"`.
- Post `"stopWarning":"A quick task saves nothing until it is built, so stopping now loses what we have worked out."` at the start and `""` once the build is under way.
- **Scope check:** `choice` "Too big for a quick task?": `1` Continue (lightweight format), `2` Escalate to a full plan; measured counts against thresholds in `body`.
- **Feature name** (escalating): `text`, `"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"`, kebab-case placeholder.
- **The plan:** doc `plan`, one block per section, Steps as a checklist, plus `review` "Build this plan?" (`"doc":"plan"`) with verdicts `yes` ("Build it"), `modify` ("Change the plan"), `escalate` ("Plan it properly instead"), `abort` ("Stop here", `danger`):
```jsonc
{ "id": "plan", "title": "Plan", "blocks": [
{ "id": "summary", "state": "settled", "md": "## Summary\n\n..." },
{ "id": "files", "state": "settled", "md": "## Files to change\n\n- `src/a.ts` - ..." },
{ "id": "steps", "state": "settled", "md": "## Steps\n\n- [ ] **1.** Step one\n- [ ] **2.** Step two\n- [ ] **3.** Step three\n- [ ] **4.** Step four" },
{ "id": "verify", "state": "settled", "md": "## Verify\n\n- [ ] ..." }
]}
{"id":"plan","title":"Plan","blocks":[{"id":"summary","state":"settled","md":"## Summary\n\n..."},{"id":"files","state":"settled","md":"## Files to change\n\n- `src/a.ts` - ..."},{"id":"steps","state":"settled","md":"## Steps\n\n- [ ] **1.** Step one\n- [ ] **2.** Step two"},{"id":"verify","state":"settled","md":"## Verify\n\n- [ ] ..."}]}
```
A `modify` reposts the changed blocks, Steps still a checklist; the version
moves up by itself.
- **Building** after `yes`: the Plan tab is the build's live task list, the
way an Implement phase has its tasks tab. There is no separate progress tab.
Settle the verdict (`"settle": true`) in the post that starts the build; the
plan's steps are the tasks and `total` is their number:
A `modify` reposts the changed blocks.
- **Building** after `yes`: the Plan tab is the live task list; steps are the tasks. Settle the verdict in the post that starts it:
```jsonc
{
"stopWarning": "",
"settle": true,
"headline": { "stage": "Building", "cleared": 0, "total": 4 },
"agent": { "status": "working", "activity": "Task 1 of 4: step one", "quietMinutes": 10 }
}
{"stopWarning":"","settle":true,"headline":{"stage":"Building","cleared":0,"total":4},"agent":{"status":"working","activity":"Task 1 of 4: step one","quietMinutes":10}}
```
Then post after every step, as `building.md` → While you build says, in the
same breath as finishing it: repost the plan's `steps` block alone (blocks
merge by id, so Summary, Files and Verify stay as they are) with that step
ticked; raise `headline.cleared`; set `agent.activity` to the next step
("Task 2 of 4: step two"). The plan lives only on the page, so this block is
`md`, not `file`:
After each step (`building.md` → While you build), repost the `steps` block alone, as `md` since the plan lives only on the page:
```jsonc
{
"headline": { "cleared": 1 },
"docs": [{ "id": "plan", "blocks": [
{ "id": "steps", "state": "settled", "md": "## Steps\n\n- [x] **1.** Step one\n- [ ] **2.** Step two\n- [ ] **3.** Step three\n- [ ] **4.** Step four" }
]}],
"agent": { "activity": "Task 2 of 4: step two" }
}
{"headline":{"cleared":1},"docs":[{"id":"plan","blocks":[{"id":"steps","state":"settled","md":"## Steps\n\n- [x] **1.** Step one\n- [ ] **2.** Step two"}]}],"agent":{"activity":"Task 2 of 4: step two"}}
```
A step that cannot be done is `- [!]` with the reason after it, and is not
counted in `cleared`. A step added mid-build goes into the list and raises
`headline.total` in the same post. Tick each step the moment it is done,
never in a batch at the end: the person is watching the Plan tab fill in.
Check for a Quick question between steps, and do not call `wait` until the
build is done. Tick the Verify block's boxes too as the checks pass, in the
post that reports them.
- **See it running, before the finish:** a finished screen freezes every open
card, so ask first. Once the build is done, post a `review` item "See it
running" (`"doc": "plan"`, verdicts `show` ("Show me it working") and `fine`
("No need, finish up"), token `show me` / `no`) with `--wait`. On `show`, run
it as `notes/implement.md` → Show me it working says, its one line going into
the work summary (the finish's `body`); then, or on `fine`, settle the card in
the same post as the finish.
- **Archive a fixed bug, before the finish:** launched on a diagnosed folder
and now Fixed with nothing past the diagnosis, post a `confirm` card
"Archive this bug?" in the same post as "See it running": the dry run's
`files` in `body`, `yesLabel` "Archive it", `noLabel` "Keep it in specs/",
and `consequences` naming `specs--completed/<bug>/`. On yes, run
`node "<S>/specs.mjs" archive <spec>` (the skill file says where `<S>` is),
and say where it went in the finish's `body`. On no, the
dashboard lists the folder as "Bug fixed", never pre-selected.
- **The finish after the build:** `command` is the commit command, filled in,
in the project's commit format (AGENTS.md), with
`"where": "When you are happy with it, commit it from your terminal:"`, and
`review` on offer — the **Review it now** button, since a quick task has no
sign-off card to put it on — `"commit": true` (the **Commit it now** button;
`console-finish.md`), `"changelog": true` (**Update CHANGELOG first**, beside
it; it hops into Changelog and on to Git) and `"dashboard": true`, so the finished screen
also offers **Back to the dashboard**. Review and dashboard are required: a finish without
`dashboard` leaves the person on a dead end. Keep waiting for whichever
button is pressed, and everything after that is `building-review.md`.
- **Escalated / aborted:** settle the verdict the same way in the finish post —
finish with `"command": "/plan2code-1-plan"` and the
PLAN-DRAFT's path in `body`, no review; or `"command": "/plan2code-quick-task"`.
Both set `"dashboard": true`: an abort of a quick task saves nothing to
resume, so it is not a pause.
A step that cannot be done is `- [!]` with the reason, not counted in `cleared`. A step added mid-build raises `headline.total` in the same post. Tick Verify boxes in the post that reports the checks. Do not `wait` until the build is done.
- **See it running, before the finish:** once built, post `review` "See it running" (`"doc":"plan"`, verdicts `show` ("Show me it working"), `fine` ("No need, finish up"), tokens `show me` / `no`) with `--wait`. On `show`, see `notes/implement.md` → Show me it working; its one line goes in the finish `body`. Settle the card in the finish post.
- **Archive a fixed bug:** launched on a diagnosed folder and now Fixed with nothing past the diagnosis, post `confirm` "Archive this bug?" in the same post as "See it running": dry run's `files` in `body`, `yesLabel` "Archive it", `noLabel` "Keep it in specs/", `consequences` naming `specs--completed/<bug>/`. Yes: `node "<S>/specs.mjs" archive <spec>`, and say where it went in the finish `body`.
- **Finish after the build:** `command` is the filled-in commit command in the project's format (AGENTS.md), `"where":"When you are happy with it, commit it from your terminal:"`, with `review` (**Review it now**), `"commit":true`, `"changelog":true` and `"dashboard":true`. Review and dashboard are required. Whichever button is pressed, what follows is `building-review.md`.
- **Escalated / aborted:** settle the verdict in the finish post: `"command":"/plan2code-1-plan"` with the PLAN-DRAFT's path in `body`, no review; or `"command":"/plan2code-quick-task"`. Both `"dashboard":true`.
## Stop requests during a build
See `building.md` → Stop requests during a build.
Stop requests during a build: `building.md`.
+5 -30
View File
@@ -1,34 +1,9 @@
# Review on the Web Console
# Review
Workflow notes for `review`, part of the web console contract (`console.md`).
A review run from a build's review button stays in the build's session, under
its workflow: `building-review.md` governs it instead.
Standalone with nothing named: first a `choice` "What should I review?" from a quick scan (branch changes, uncommitted changes, specs, files you name; each with its size). A build's review skips it. Launched from the dashboard: `open --resume <sid> --no-open --workflow review`. Post `activity` while you read.
Scope questions up front — run standalone with nothing named, the first is
a `choice`, "What should I review?", built from a quick scan (branch changes,
uncommitted changes, specs, files you name; each option with its size),
never an assumed target; a build's review skips it (`building-review.md`). Then the
findings report as a doc (`id: "report"`), then the pick-what-gets-fixed menu
as a `multi` or `choice` keyed by finding id, carrying `"doc": "report"` so the
card links straight to the findings. Settle that item (`"settle": true`) in the
same post that takes the picks up: left open it stays on the page as a question
still owed, next to whatever you ask next. Post `activity` while you read — a
real review is long stretches of you working, and the page should say so rather
than hint at questions.
Findings are doc `report`; the fix menu is a `multi` or `choice` keyed by finding id with `"doc":"report"`, settled (`"settle":true`) in the post that takes the picks up.
When the session was launched from the dashboard, resume the session you were
handed (`open --resume <sid> --no-open --workflow review`), never a fresh
`open`.
Closing gate: `review` "Check the fixes", `"doc":"report"`, `"nothingYet":false`, verdicts `approve`, `changes`.
Review Mode's closing gate ("Reply approved to commit, or request changes")
is a `review` item titled "Check the fixes", `doc: "report"`, `"nothingYet":
false` (the fixes are already on disk), verdicts `approve` and `changes`.
On completion the finish's `command` is the suggested commit when fixes
landed — filled in, in the AGENTS.md format, with
`"where": "When you are happy with it, commit it from your terminal:"` —
otherwise leave `command` out; with one, `"commit": true` puts **Commit it
now** beside it. The completion finish carries `"dashboard": true`
so the finished screen offers **Back to the dashboard**; keep waiting for the
press. A stop mid-review loses nothing on disk, so its finish is the bare
`/plan2code-review` (a pause, so no dashboard button).
Completion finish: `command` is the suggested commit when fixes landed (AGENTS.md format, `"where":"When you are happy with it, commit it from your terminal:"`, `"commit":true`), else none; `"dashboard":true`. A stop's `command` is the bare `/plan2code-review`, no dashboard.
+8 -22
View File
@@ -1,26 +1,12 @@
# Revision on the Web Console
# Revision
Workflow notes for `revise-plan`, part of the web console contract (`console.md`).
Revision is a short run of gates, and each maps onto a kind you already know:
| Step | On the page |
| Step | Card |
| --- | --- |
| 1, Change Analysis | A `recap` item, "Is this the change?", with the affected-areas table in `summary`. Found a waiting `**Plan change:**` brief? Quote it at the top of that `summary` and post no open "what should change" card first. With none waiting, the first card is a `text` item titled "What should change", `"fill": "note"`, asking what to change; its answer feeds the "Is this the change?" recap. |
| 2, Impact Assessment | The Revision Impact Summary as a doc (`id: "impact"`), and a `review` item "Approve the spec changes" pointing at it: verdicts `approve` ("Approve these spec changes"), `refine` ("Refine the plan") and `abort` ("Abort", `"danger": true`), `nothingYet`: "No spec file changes until you approve." |
| 3 to 5 | Nothing to ask. Post `activity` while you edit, then the Revision Complete summary as a doc. |
| 6, Cleanup | A `confirm` per rename or removal, the paths in `consequences`. |
| 1, Change Analysis | `recap` "Is this the change?", affected-areas table in `summary`. A waiting `**Plan change:**` brief is quoted atop `summary` and no "what should change" card goes first; with none, the first card is `text` "What should change", `"fill":"note"`. |
| 2, Impact | Doc `impact`, plus `review` "Approve the spec changes": verdicts `approve`, `refine`, `abort` (`danger`), `nothingYet` "No spec file changes until you approve." |
| 3 to 5 | Nothing to ask: `activity` while you edit, then the Revision Complete summary as a doc. |
| 6, Cleanup | `confirm` per rename or removal, paths in `consequences`. |
Revision's own rule holds on the page too: **no option, verdict or label ever
offers to execute or implement.** Pass `--spec specs/<feature>` to `open`, or
post `specDir` once you know it. The finish command is
`/plan2code-3-implement specs/<feature>/overview.md`; an abort's is
`/plan2code-1b-revise-plan specs/<feature>/overview.md`.
No option, verdict, label, or helper `title`, `ask` or `result` ever offers to execute or implement. Pass `--spec specs/<feature>` to `open` or post `specDir`. Finish `command`: `/plan2code-3-implement specs/<feature>/overview.md`; abort: `/plan2code-1b-revise-plan specs/<feature>/overview.md`.
Revision offers the Subagents switch. A `Subagents:` block may arrive on
`open` output or a `wait` / `chat` pickup: follow `console-subagents.md` and
the skill's Helpers section, and report each helper as `helpers`. Lookup
helpers report back before the Step 2 review item goes up; phase-file helpers
report back before the Step 4 check. Every gate stays with you, and a helper's
`title`, `ask` and `result` follow the same rule as every label: nothing
offers to execute or implement.
Helpers: lookup helpers report before the Step 2 review goes up; phase-file helpers before the Step 4 check.
+12 -48
View File
@@ -1,73 +1,37 @@
# X-ray on the Web Console
Workflow notes for `xray`, part of the web console contract (`console.md`).
# X-ray
## The mode question
A typed argument that names the mode and area skips it. Otherwise ask both in
one batch, posted with `--wait`:
An argument naming mode and area skips it. Otherwise one `--wait` batch:
```jsonc
{
"title": "Codebase X-ray",
"headline": { "stage": "Choosing", "cleared": 0, "total": 2 },
"items": [
{ "id": "mode", "kind": "choice", "title": "What you want to know", "allowOther": false,
"body": "Explain one area, or rank what makes this code hard to change.",
"options": [
{ "k": "1", "text": "Explain an area", "detail": "How it works and why it is that way, citing files and the commits behind it." },
{ "k": "2", "text": "Find the rough spots", "detail": "Ranked spots that make change hard. You pick the ones worth fixing; they become a brief for Pathfinder or Plan." }
] },
{ "id": "area", "kind": "text", "title": "Which area", "required": false,
"body": "A folder, file or feature. Needed to explain; leave it empty to survey the whole repository.",
"placeholder": "src/exporter, the code that builds the CSV reports" }
]
}
{"title":"Codebase X-ray","headline":{"stage":"Choosing","cleared":0,"total":2},"items":[{"id":"mode","kind":"choice","title":"What you want to know","allowOther":false,"body":"Explain one area, or rank what makes this code hard to change.","options":[{"text":"Explain an area","detail":"How it works and why, citing files and commits."},{"text":"Find the rough spots","detail":"Ranked spots that make change hard. You pick the ones worth fixing; they become a brief for Pathfinder or Plan."}]},{"id":"area","kind":"text","title":"Which area","required":false,"body":"A folder, file or feature. Needed to explain; empty surveys the whole repository."}]}
```
Explain picked with the area left empty: ask for it again as a required `text`
card. No recommendation on the mode: only the person knows what they came for.
Explain with the area empty: ask again as a required `text`.
## Explain mode
The answer is a doc, `id` `"answer"`, one block per section (`In one paragraph`,
`How it works`, `Why it is this way`, `Worth knowing`), with the `Sources:` line
at the top of the first. Then the save offer as a `confirm` card pointing at it:
Doc `answer`, one block per section (`In one paragraph`, `How it works`, `Why it is this way`, `Worth knowing`), `Sources:` line atop the first. Then:
```jsonc
{ "id": "keep", "kind": "confirm", "title": "Keep this answer", "doc": "answer",
"body": "Save it as `specs/exporter/XRAY-exporter-20261016.md`, as input for Pathfinder or Plan?",
"yesLabel": "Save it", "noLabel": "No, just reading" }
{"id":"keep","kind":"confirm","title":"Keep this answer","doc":"answer","body":"Save it as `specs/exporter/XRAY-exporter-20261016.md`, as input for Pathfinder or Plan?","yesLabel":"Save it","noLabel":"No, just reading"}
```
Ask the folder name in the same batch as a `text` card with `pattern`
`^[a-z0-9]+(-[a-z0-9]+)*$` when it is not obvious. Once written, re-send the doc
with `"saved": "specs/<name>/XRAY-<area-slug>-<date>.md"`.
When the folder name is not obvious, ask it in the same batch as a `text` with `pattern` `^[a-z0-9]+(-[a-z0-9]+)*$`. Once written, re-send the doc with `"saved":"specs/<name>/XRAY-<area-slug>-<date>.md"`.
## Rough-spots mode
The ranked list is a doc, `id` `"spots"`, one block per spot (its files, why it
hurts, the "to change X today" example). The pick is one `multi` card pointing
at it, posted with `--wait`:
Doc `spots`, one block per spot (files, why it hurts, the "to change X today" example). Pick, `--wait`:
```jsonc
{ "id": "pick", "kind": "multi", "title": "Worth fixing", "doc": "spots", "required": false,
"body": "Tick the spots worth fixing. Add a note for any of them in the box (\"1: the exporter part only\"). Only ticked spots go into the brief.",
"options": [
{ "k": "1", "text": "Exporter and its formatter always change together", "detail": "src/export.ts, src/format.ts: together in 14 of 16 commits." }
] }
{"id":"pick","kind":"multi","title":"Worth fixing","doc":"spots","required":false,"body":"Tick the spots worth fixing. Only ticked spots go into the brief.","options":[{"text":"Exporter and its formatter always change together"}]}
```
Nothing ticked: nothing is written. Otherwise write the brief, then add it as a
second doc with `"saved": "specs/<name>/ARCHITECTURE-BRIEF-<date>.md"` and a
`file` block.
Nothing ticked: nothing written. Otherwise write the brief and add it as a second doc with `"saved":"specs/<name>/ARCHITECTURE-BRIEF-<date>.md"` and a `file` block.
## The finish
`command` is `/plan2code-0-pathfinder` (big or unclear) or `/plan2code-1-plan`
(settled), never with a placeholder; leave it out when nothing was kept. `doc`
is the brief or the saved answer when there is one. `"dashboard": true`, then
keep waiting for the press (`console-finish.md`).
`command` is `/plan2code-0-pathfinder` (big or unclear) or `/plan2code-1-plan` (settled); none when nothing was kept. `doc` is the brief or saved answer. `"dashboard":true`.
A stop before anything was written ends on a finish whose `body` says nothing
was kept, with `"command": "/plan2code-xray"` (`console-stop.md`).
A stop before anything was written: `body` says nothing was kept, `"command":"/plan2code-xray"`.