`document`, `implement`, `implement-review`, `review`, `finalize` or
`handoff`. Get it
right: the page decides from it whether to offer a brief, what stopping
early costs, and which command resumes the session if you cannot say.
`dashboard` is the special one: the page draws the skill menu itself, and
your job is the `menu` payload and the launch hand-off — see the workflow
notes.
It prints one line: `{"ok":true,"sid":"...","session":"...","url":"http://127.0.0.1:PORT/s/TOKEN/","terminalLine":"→ Look at the web console: http://127.0.0.1:PORT/s/TOKEN/"}`.
It also tries to open the browser by itself. When it removed session
folders or scratch files older than 30 days, the line also carries
`swept: { sessions, scratch }` — housekeeping, nothing to relay to the
person.
To open with questions already on the page instead, write the payload to a
temporary JSON file first — a file, not a heredoc, because heredocs do not
work in PowerShell, which is the default shell on Windows — and pass it as
`--file <payload.json>`. Opening first is the better order: the page is in
front of them while you work out what to ask, instead of after.
Write temporary payload files into the session's own folder (the `session`
path `open` prints), never into the project or into
`~/.plan2code/console/` directly. The session folder is removed with the
session after 30 idle days, and stray `.json` / `.mjs` files left in the
console folder are swept on the same clock.
**Building?** For `implement`, `implement-review` and `quick-task`, also read
`building.md` beside this file once the session is open. A build is mostly you
working rather than asking, and that file covers the progress the page
shows, the sign-off and the review offer it carries, and the review button
after a finished quick task.
2. If you opened without `--file`, post the first batch of questions as soon
as you have them (see Posting an update). If getting there takes a while
(reading the project, finding the spec), post an `agent.activity` line
first so the page says what you are doing. Either way, tell the person, in plain
words, on one line: the link, and how many questions are waiting. Repeat the link in your
message text, not only in a command output, because terminal scrollback
gets lost. While a console session is open, end every terminal message
with the latest `terminalLine` from `open`, `post` or `wait`, verbatim
(`→ Look at the web console: <url>`).
3. Go into the wait loop below.
Keep `session` (the session id). Every later command needs `--session <sid>`.
---
## The wait loop
This is the part that matters most. **Never try to block for the whole time a
person takes.** Call `wait` in bounded slices and read the exit code.
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
Do not poll faster than this. Do not spin on `status`. Exit 10 is not a finished
turn: never emit a final response or stop after an arbitrary number of slices;
relay one line and immediately call `wait` again. Do not give up: people step
"reply": "File format: a\nWhat to call it: audit-export\nNote on What to call it: Please keep the header row.\n Image: /home/sam/.plan2code/console/sessions/20260923-101500-ab12cd/uploads/3f2b9c1e-8a4d-4f6e-9b7a-2c5d1e0f4a6b.jpg (header.png)\n File: /home/sam/.plan2code/console/sessions/20260923-101500-ab12cd/uploads/7c1d0a4e-5b2f-4e8a-9d3c-1f6e2b8a0c5d.pdf (api-spec.pdf)"
}
```
**`reply` is the important field.** It is what the person would have typed in the
terminal, one line per question, built from the `token` map you supplied. Treat it
as their typed answer and follow the normal workflow from there.
Every part of an answer survives into it, joined by `; ` when there is more than
one: a verdict and the note that came with it, a checklist state and what they
wrote down, a reordered list and its new order. `actions` carries the same thing
with structure, for when you need the detail.
A `comment` action may carry `images` and `files`, each `[{ path, name }]`:
screenshots in the first, text, code and PDF documents in the second. `reply`
then has one ` Image: <path> (<name>)` or ` File: <path> (<name>)` line per
attachment under the note, in the order they were attached. **Open every path
with your file-read tool before you answer the note** — it is what they are
pointing at. If a file cannot be read (your tool does not read PDF, say), tell
them so in your reply rather than guessing what is in it. The files live in the
session's `uploads/`, outside the project; never copy them into it yourself — see Keeping attachments.
A send is the person talking to you. Act on it in that turn: do not wait for
terminal input to confirm it, do not ask whether to proceed, do not merely
summarise it back.
Then, in ONE `post`, do all of:
- mark each answered item `"status": "answered"` and record its `answer`
A settled question stops being a form and becomes a record: the page states the
answer back in its own words ("A · Continue without it"), marks the option they
picked, and locks everything else. That is the whole point of settling one, so
record the answer every time.
The server writes what they sent onto the item as `submitted` when Send is
pressed, and the page falls back to it, so a question you forget is not a blank
card. Treat that as the safety net it is, not as a reason to leave `answer` out:
`submitted` is the raw click, while `answer` is what you decided it meant, and
only the second survives you reopening or rewording the question.
---
## Keeping attachments
Note attachments live in the session's `uploads/`, which is swept after 30 idle days. Before you write any file under `specs/<idea>/` that links to or cites one (plans, the overview, phase files, Pathfinder question files and the map), keep it first:
```
node "<CONSOLE>" keep --session <sid> --upload <path> --name <name> --spec specs/<idea> --from <the file you are writing>
```
`path` and `name` are the attachment's, from the `comment` action. It prints `{ ok, path, link, image, reused }`. Paste `link` as it is: `` for an image, `[name](link)` for a document. The same upload always gets the same name (`attachments/<slug>-<8-char id>.<ext>`), so keeping it again just reuses the copy. Name the kept file in your next update. Leave uncited attachments where they are. Quick-question attachments are never kept. Exit 3 means the path was refused. Say so, and link nothing.
---
## Briefs (Pathfinder only)
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:
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
from the top bar's Subagents button. Their pick is saved per project and per
skill, off by default, and reaches you as a standing instruction, only when it
changes.
### What arrives
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
change alone never ends a `wait` slice: it waits for the next send, or for
your next `chat` check.
```
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
- 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.
### Planning
- Open with `--workflow plan`, first thing. Every question and sign-off gate
goes through the page, phase breakdowns as an editable `list`.
- 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": ""`.
- 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.
### Revision (`revise-plan`)
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`), token equal to the ids, `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`.
### Finalize
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 tasks exist, 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`) 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). |
**Give every new question a new `id`.** An id names one question for the whole session. The server drops a stale `submitted` record if you reword a question under an old id, but never rely on it: a fresh id is the only unambiguous way to ask something new.
| `headline` | required | What just happened, in plain words. Becomes the card's title. |
| `command` | optional | The exact thing they run next, when there is one — the same string as your Trail Footer's Form A. Rendered with a Copy button that is always on show. Leave it out when nothing is left to run: the page shows an "All done" line with `/plan2code` instead. **No placeholders**: a rendered command is copied and run verbatim, and a patch carrying `<` or `>` in it is rejected. |
| `dashboard` | optional | `true` puts a **Back to the dashboard** button on the finished screen. Set it on every ending except a pause, and keep waiting for the press (below). |
| `body` | optional | Markdown. Where the files landed, what to read first. |
| `where` | optional | Overrides "Run this in the terminal where you started Plan2Code, in a new conversation:". |
| `doc` | optional | Id of the document to offer as a Markdown download on the way out. Defaults to the first one. |
| `console` | optional | Whether the copied text asks the next session to use the web console. Leave it out: it follows from the command. |
| `review` | optional | A finished `quick-task` only: `true` or `{ "label": "..." }` puts a **Review it now** button on the finished screen. `implement` offers the review on its sign-off card instead — before approval, where it can still change the outcome. See `building.md`. |
**Write the bare command.** Every Plan2Code skill has a console — the
dashboard and all twelve skills behind it — so for any of them the page
appends ` --web` to what it shows and copies, so someone who worked here
lands back here instead of being asked the interface question as though
they were new. Every one of those skills takes that flag in its argument as
the answer. Do not write `Use the web console for this session.` into the
command; if it is there, the page swaps it for `--web`. A command that is not
a Plan2Code skill gets nothing appended. Set `"console": false` if they have
asked to go back to the terminal.
The page then says the session is finished rather than paused, offers the
command, tells them they can close the tab, and stops treating the server going
away as a fault. Send is disabled, and anything they staged and never sent is
named rather than quietly lost.
Settle whatever the session ends on. An item still `open` when the finish
lands freezes exactly as it stands: a send it carries shows as the final word
on it, and one that was never answered shows as a question that ran out of
time. If their last send was a verdict you are closing on — the review's
`approve`, the plan's `yes`, the fixes pick — the finish post is the same post
that marks it `"status": "answered"` with the `answer` they sent, exactly as
"Handling a send" already has you do everywhere else.
Post it even when you are also printing the footer in the terminal. Someone who
has spent the whole session in the browser has no reason to look anywhere else.
The chat stays readable after a finish, and the page disables its Send. A
message sent just before the finish can still arrive: while you wait for the
dashboard press, answer any chat `wait` delivers, as in Quick questions.
### After the finish: the dashboard button
A **pause** is an ending that keeps a place to come back to: a stop request,
an abort that keeps its place to resume, or a checkpoint that saves and ends
(Plan's Large checkpoint). A pause's headline starts with "Paused", it never
carries `dashboard`, and you `stop` at once.
Every other finish carries `"dashboard": true`. Then keep calling `wait` in the
usual slices for up to about ten minutes:
| What arrives | What you do |
| --- | --- |
| An action `{ "i": "__dashboard", "type": "dashboard" }` | `open --resume <sid> --no-open --workflow dashboard` (the resume re-runs the project scan), then ONE post with `"finish": null`, the `menu` payload and `"agent": { "status": "waiting" }`. Then read the dashboard skill (`~/.agents/skills/plan2code/SKILL.md`) and carry on as the dashboard from its "The menu" section, in this same conversation. The same action can also arrive before any finish, from the top bar's triangle: see Stop requests → "Back to the dashboard, mid-workflow". |
| An action `__review` or `__done` | As `building.md` says (quick task only). |
| `wait` exit `20` | The server is gone, not necessarily the tab. `open --resume <sid> --no-open --workflow <yours>`, then keep waiting: their Ask messages and the dashboard button still need you. Give up only when the resume itself fails. |
| Nothing after about ten minutes | `stop` the server. The page swaps the button for the `/plan2code` command. |
### 2. Stop the server
```
node "<CONSOLE>" stop --session <sid>
```
If you forget, it shuts itself down after 30 minutes of silence. Stop it anyway.
The page keeps the hand-off on screen after the server has gone: everything it
needs is already in `state.json`, and the Copy button is the one action that
still works on a page whose server has died.
`node "<CONSOLE>" status` lists sessions for this project, including any whose
answers were submitted but never picked up.
---
## When things go wrong
| Situation | What to do |
| --- | --- |
| `open` fails | Say so in one line, carry on in the terminal. Never block on this. |
| `wait` returns `20` | `open --resume <sid>`, give them the new link. Nothing they typed is lost. |
| They close the tab | Nothing happens. Drafts are saved. Reopening the link restores everything. |
| Your session ends mid-flight | Their answers still land on disk. A fresh session runs `status` (or `open --resume`, which reports `pendingResult: true`), and `wait` returns them. An uncollected result is never discarded. |
| They ask to go back to the terminal | `stop` the session and continue. The files under `specs/` are unchanged. |
| The session ends and they are still in the browser | Post `finish` **before** `stop`, and wait for the dashboard button first unless it is a pause. See Finishing, above. Without it their last screen says the next question is coming, and then says contact was lost. |
| You started subagents or background jobs | Wait for every one to report back before `finish`, posting `working` with a count meanwhile. A finish while they run tells the person it is safe to close the terminal, and that kills them. |
| Any session end, not only the last one | Also post `finish`: an off-ramp that routes elsewhere, a checkpoint that saves and stops, a stop request. Anything that ends the session without it leaves the page promising a question that is not coming. |
| Picking up a paused session | `open --resume <sid>` (or `open --session <sid>`) clears a paused `finish` itself, and the questions left open at the pause with it: the finish body already said what was still open, so re-ask whatever the new session needs in your own words rather than leaving the old asks on the page as duplicates. Settled items stay. For any other ending you are deliberately taking back, post `"finish": null` in your first patch. |
| The same result arrives twice | Your harness killed `wait` after it handed the result over but before it recorded that. Handle it once. Most of a repeated patch is harmless, because items merge by id, but `thread` **appends**: leave out any thread entry you already sent, or the person sees your reply twice. |
| The same chat arrives twice | Replies merge by `id`, so re-post the same reply if it is not on the page yet; do not answer the question a second time. |
| `node` is missing, or older than 18 | One line, then the terminal. Do not try to install anything. |
---
## Worked example
Opening a pathfinder session with the first two questions: