Sync upstream into v2.7.0: the git board skill replaces git-commit (ticket-free), and console docs and tests are split up

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-11 16:39:25 -07:00
1 parent 6114914dd6
commit f328406bb5
103 files changed
+17636 -9991

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
# Changelog on the Web Console
Workflow notes for `changelog`, part of the web console contract (`console.md`).
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 |
| --- | --- |
| 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?". |
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.
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`.
+12
View File
@@ -0,0 +1,12 @@
# Documentation on the Web Console
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`.
+32
View File
@@ -0,0 +1,32 @@
# Finalize on the Web Console
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 |
| --- | --- |
| 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 `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
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".
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`). The
completion summary is printed to a terminal the browser user is not watching,
so put it in `finish.body`.
+119
View File
@@ -0,0 +1,119 @@
# Git on the Web Console
Workflow notes for `git`, part of the web console contract (`console.md`).
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 above
the board in the usual card slot.
**A click** arrives as one session action, one 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. ..." }
```
| `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 |
| `cleanup` | `branches[]` |
| `commit` | `files[]` (paths and untracked folders), `ignore[]` (folders to add to `.gitignore`) |
| `pr-host` | `host`, `kind` (already saved by the page's `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`):
```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` 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.
**Cards per `plan`.** `git.mjs plan <op>` decides whether to ask:
| `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, labelled **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. |
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.
| 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. |
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"`.
**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").
**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.
**Finishing** (`console-finish.md`). Done (`op: "done"`) 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`.
+11
View File
@@ -0,0 +1,11 @@
# Handoff on the Web Console
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 often sits outside the project (the OS temp folder),
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`).
+155
View File
@@ -0,0 +1,155 @@
# Implement on the Web Console
Workflow notes for `implement` and `implement-review`, part of the web console
contract (`console.md`). Read `building.md` first.
## The 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 }
}
```
`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.
## After every task
In the same breath as writing the task's checkbox to disk:
```jsonc
{
"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).
---
## 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:
```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, or say what to change.",
"verdicts": [
{ "id": "review", "label": "Review the code first" },
{ "id": "approve", "label": "Approve this phase" },
{ "id": "changes", "label": "I want changes" }
],
"token": { "approve": "approved", "changes": "needs changes" },
"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`.
`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.
---
## 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`:
```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
}
}
```
`"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.
`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`).
---
## 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 **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.
+14
View File
@@ -0,0 +1,14 @@
# Init and Init Update on the Web Console
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.
+76
View File
@@ -0,0 +1,76 @@
# Pathfinder on the Web Console
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 fresh-idea card carries `"templates": "idea"` (`console.md` → The kinds).
- 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.
## 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:
```jsonc
{
"type": "submit",
"actions": [{ "i": "__brief", "type": "brief", "range": "since 2026-09-15" }],
"reply": "Write a brief covering everything 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:
```jsonc
{
"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.
+17
View File
@@ -0,0 +1,17 @@
# Planning on the Web Console
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"` (`console.md` → The kinds).
- 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.
+90
View File
@@ -0,0 +1,90 @@
# Quick Task on the Web Console
Workflow notes for `quick-task`, part of the web console contract
(`console.md`). 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"` (`console.md` → The kinds).
- 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`):
```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- [ ] ..." }
]}
```
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:
```jsonc
{
"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`:
```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" }
}
```
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.
- **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`) 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.
## Stop requests during a build
See `building.md` → Stop requests during a build.
+34
View File
@@ -0,0 +1,34 @@
# Review on the Web Console
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.
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.
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`.
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).
+18
View File
@@ -0,0 +1,18 @@
# Revision on the Web Console
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 |
| --- | --- |
| 1, Change Analysis | A `recap` item, "Is this the change?", with the affected-areas table in `summary`. |
| 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`. |
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`.