mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
Update the web console server, screens, help, prefs and loop setup, with matching page and logic suites
AI Assisted
This commit is contained in:
1 parent
2468027a5a
commit
8e34bf1005
119 files changed
+9957
-3728
No files matched your search
+64
-391
@@ -1,431 +1,104 @@
|
||||
# The Web Console
|
||||
# The Web Console (the card)
|
||||
|
||||
A local page in the person's browser where they answer your questions, read what
|
||||
you have drafted, and approve things, instead of typing into the terminal.
|
||||
A local page where the person answers your questions, reads your drafts and approves things. Read this card once per session. Read a topic file only when your workflow notes or the console's `read` output name it.
|
||||
|
||||
> **Not open yet?** `node "<CONSOLE>" open --workflow <yours>` first (launched
|
||||
> from the dashboard: its `resume` instead), then read on.
|
||||
`<CONSOLE>` is `<SKILL_ROOT>/references/web-console/console.mjs` (globally `~/.agents/skills/<skill-name>/references/web-console/`; `~/.plan2code/console/console-dir` may hold the folder). Always quote the path. `node "<CONSOLE>" help <topic>` prints any topic file.
|
||||
|
||||
**Read this file once per conversation.** Every Plan2Code skill ships the same
|
||||
copy (`version.json` beside it says which). If you already read it in this
|
||||
conversation — from the dashboard, or from another skill's copy — do not read it
|
||||
again after a hop; carry on. The topic files below are read only when their
|
||||
moment comes, also once each.
|
||||
## Start
|
||||
|
||||
**`<SKILL_ROOT>`** means the directory holding this skill's `SKILL.md`, and
|
||||
`<CONSOLE>` means `<SKILL_ROOT>/references/web-console/console.mjs` (globally:
|
||||
`~/.agents/skills/<skill-name>/references/web-console/`; an earlier session may
|
||||
have left the directory in `~/.plan2code/console/console-dir`). `node
|
||||
"<CONSOLE>" help <topic>` prints any topic file below. Always quote the path:
|
||||
install paths contain spaces. Requires Node 18+; nothing to install.
|
||||
`node "<CONSOLE>" open --workflow <w>` (add `--spec specs/<idea>` when known). `<w>` is one of `dashboard`, `init`, `init-update`, `pathfinder`, `quick-task`, `plan`, `revise-plan`, `document`, `implement`, `implement-review`, `review`, `finalize`, `handoff`, `git`, `changelog`, `xray`, `diagnose`. Launched from the dashboard? The session is open: run the `resume` command the launch carried instead.
|
||||
|
||||
**The console changes where you ask, not what you ask.** Every rule of this
|
||||
workflow still applies: the same questions, the same order, the same gates, the
|
||||
same cap of three questions at a time, the same recap before anything is recorded.
|
||||
You are not allowed to answer your own questions just because a form makes it easy.
|
||||
Keep `sid`: every later command takes `--session <sid>`. `open` failing: carry on in the terminal. When `open` adds `remote` and a `note`, give the link, ask whether it opened, and move to the terminal if not. Tell the person the link (with `"inApp":true`, never print it: only how many questions are waiting) and end every terminal message with the latest `terminalLine`, verbatim.
|
||||
|
||||
> **The one rule that keeps the page alive: while the session is open, every
|
||||
> turn ends on a `wait` (or `post --wait`) call, never on text.** Exit `10` means
|
||||
> "nobody has answered yet", not "done": relay one line and wait again in the
|
||||
> same turn, as many times as it takes. A turn that ends without a `wait`
|
||||
> running strands the person's next click.
|
||||
|
||||
## What to read, and when
|
||||
|
||||
All beside this file. Read one when its moment first comes, not before; when
|
||||
several are due at once (a build's start), read them in one batch.
|
||||
|
||||
| File (`help` topic) | Read it when |
|
||||
| --- | --- |
|
||||
| `building.md` (`building`) | You run `implement`, `implement-review` or `quick-task`: right after `open`, then `notes/implement.md` or `notes/quick-task.md`. |
|
||||
| `building-review.md` (`building-review`) | A build's review is asked for on the page (a `review` verdict, `__review`, Implement + Review's Stage 2). |
|
||||
| `notes/<workflow>.md` (`<workflow>`) | Right after `open`: `init` (also init-update), `pathfinder`, `plan`, `revise-plan`, `document`, `implement` (also implement-review), `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`, `xray`, `diagnose`. The dashboard's is `console-launches.md`. |
|
||||
| `console-launches.md` (`launches`) | You are the dashboard. |
|
||||
| `console-finish.md` (`finish`) | Before your first `finish` post, and when a send carries `__commit`, or `__dashboard` from a finished screen. |
|
||||
| `console-stop.md` (`stop`) | A send carries `__stop`, or `__dashboard` with no finish up; or your notes say to post a `stopWarning`. |
|
||||
| `console-chat.md` (`chat`) | The first time `wait` or `chat` hands you a Quick question (`chat: [...]`). |
|
||||
| `console-workspace.md` (`workspace`) | `open` lists more than one folder, a `Workspace:` line arrives, or someone writes `@name`. |
|
||||
| `console-subagents.md` (`subagents`) | A `Subagents:` block arrives, or your workflow notes say to report helpers. |
|
||||
| `console-meter.md` (`meter`) | Only if a `run` is refused: your notes give the exact `run` to post. |
|
||||
| `console-attachments.md` (`attachments`) | A file you write under `specs/` cites a note's attachment. |
|
||||
| `console-trouble.md` (`trouble`) | Something goes wrong: `open` fails, a repeat delivery, a dead server. |
|
||||
|
||||
---
|
||||
|
||||
## Starting it
|
||||
|
||||
It needs Node 18+ on PATH (anything older exits naming the version), the
|
||||
person's own machine (the page is on `127.0.0.1`; in a cloud VM or remote
|
||||
sandbox do not offer it), and a foreground command of a minute at a time. When
|
||||
`open` thinks the machine is remote (SSH, a dev container, a Codespace) it adds
|
||||
`"remote"` and a `note`: give them the link, ask whether it opened, and move to
|
||||
the terminal if not. If anything fails, say so in one line and carry on in the
|
||||
terminal — that path loses nothing, and they can switch either way at any time.
|
||||
|
||||
1. `node "<CONSOLE>" open --workflow <w>`, where `<w>` is one of `dashboard`,
|
||||
`init`, `init-update`, `pathfinder`, `quick-task`, `plan`, `revise-plan`,
|
||||
`document`, `implement`, `implement-review`, `review`, `finalize`,
|
||||
`handoff`, `git`, `changelog`, `xray`, `diagnose`. Get it right: the page decides from it what
|
||||
to offer and what stopping costs. `--title` defaults to the folder name;
|
||||
`--spec specs/<idea>` when you already know the spec. It prints
|
||||
`{"ok":true,"sid":"...","session":"...","url":"...","terminalLine":"→ Look at the web console: ..."}`
|
||||
and opens the browser itself. `swept` is housekeeping, `workspace` and
|
||||
`subagents` are explained in their topic files.
|
||||
2. Pass each patch on stdin with `--file -` (The turn, below). Where you cannot
|
||||
(PowerShell), write it to a file in the `session` folder `open` printed —
|
||||
never into the project or `~/.plan2code/console/` itself — and pass that
|
||||
path. `open --file <payload>` opens with a first payload the same way.
|
||||
3. Post the first questions as soon as you have them. If getting there takes a
|
||||
while, post `{"agent":{"status":"working","activity":"Reading the plan"}}`
|
||||
first so the page says what you are doing.
|
||||
4. Tell the person, in one line, the link and how many questions are waiting.
|
||||
While the session is open, end every terminal message with the latest
|
||||
`terminalLine`, verbatim. When `open` printed `"inApp":true` the page is
|
||||
already in the desktop app's window: never print the link (here, after a
|
||||
resume or anywhere else), only the count; `terminalLine` leaves it out too.
|
||||
|
||||
Keep `sid`: every later command takes `--session <sid>`.
|
||||
|
||||
---
|
||||
Right after `open`, read `building.md` (implement, implement-review, quick-task only) and `notes/<workflow>.md`.
|
||||
|
||||
## The turn
|
||||
|
||||
```
|
||||
node "<CONSOLE>" post --session <sid> --file - --wait 240 <<'EOF'
|
||||
{ "settle": true, "items": [ ... ] }
|
||||
{"settle":true,"items":[...]}
|
||||
EOF
|
||||
```
|
||||
|
||||
`--file -` reads the patch from stdin: in bash or zsh a quoted heredoc
|
||||
(`<<'EOF'`) saves writing a file first. PowerShell has no heredoc and its pipe
|
||||
can mangle non-ASCII text, so there write the patch to a file in the session
|
||||
folder and pass `--file <path>`. `post --wait <N>` posts, then waits up to `N`
|
||||
seconds in the same command: use it for every post that hands the turn to the
|
||||
person, so a turn costs one command. It prints the post's line (its `open` is
|
||||
the required questions still open; optional cards and notices are not
|
||||
counted), then the wait's; the exit code is the wait's, and exit `3` means the post was refused
|
||||
and nothing waited. `--wait` with no number takes `--seconds`, else 240, so
|
||||
always give one; slices under 5 seconds count as 5. Plain
|
||||
`wait --session <sid> --seconds <N>` waits without posting.
|
||||
Keep the heredoc quoted (`<<'EOF'`). PowerShell has no heredoc: write the patch to a file in the `session` folder `open` printed (never in the project) and pass `--file <path>`. Size the `--wait` slice to your shell limit: 5 minutes or more `240` (tool timeout 300000 ms), about 2 minutes `90`, 60 seconds or unsure `45`.
|
||||
|
||||
**Size the slice to your shell timeout**, comfortably below its limit, so the
|
||||
command returns by itself rather than being killed:
|
||||
With nothing to post, `node "<CONSOLE>" wait --session <sid> --seconds 240` waits alone (same slice sizes).
|
||||
|
||||
| Your limit on one command | Use |
|
||||
| --- | --- |
|
||||
| 5 minutes or more | `240`, with the tool timeout set to 300000 ms |
|
||||
| about 2 minutes | `90` |
|
||||
| 60 seconds, or you cannot tell | `45` |
|
||||
**Every turn ends on a `wait` (or `post --wait`), never on text.**
|
||||
|
||||
Killing a wait mid-slice loses nothing; a result is marked collected only after
|
||||
it is printed, so the worst case is a repeat, never a lost answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| Exit | Meaning | Do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, asked a Quick question, or both. stdout is the result. | Handle it (below), then post once, with `--wait`. |
|
||||
| `10` | Nobody has answered yet. | Relay one line, the `message` followed by the `terminalLine`, and wait again in the same turn. |
|
||||
| `20` | The server is gone. | `open --resume <sid> --workflow <yours>` (no `--no-open`: the restart has a new link, and the browser opens it), give them the new link, keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want, in the terminal. |
|
||||
| `3` | (`post --wait` only) the post was refused; stderr says why. | Fix the patch and post again. |
|
||||
| `2` | Bad usage: a flag missing its value, or a patch that is not one readable JSON object. Nothing was posted. | Fix the command or the patch and run it again. |
|
||||
| 0 | A send arrived | Handle it (below), then one `post --wait` |
|
||||
| 10 | Nobody answered yet | Relay one line of your own, ending with the latest `terminalLine`, and wait again, same turn, without limit |
|
||||
| 20 | `{"gone":true,"fix":...}` | Run its `fix` (replace `<yours>` with your workflow), give the new link, keep waiting |
|
||||
| 30 | They canceled | Stop; ask what they want in the terminal |
|
||||
| 3 | Patch refused | stderr names the item, the field and the fix; correct it and post again |
|
||||
| 2 | Patch unreadable | stderr gives line, column and the spot; fix it and post again |
|
||||
|
||||
Do not poll faster, do not spin on `status`, and never stop after some number
|
||||
of slices: people step away and come back. After a finish, keep waiting the
|
||||
same way (`console-finish.md`). **Collect promptly:** a sent question is locked
|
||||
on the page, and a second send is blocked, until your next post lands.
|
||||
## A send
|
||||
|
||||
### Handling a send
|
||||
`reply` is what they would have typed: one line per question, parts joined with `; `. Act on it as their typed answer, in that turn, with no summary back. Open every `Image:` and `File:` path in it with your file-read tool before you answer.
|
||||
|
||||
```jsonc
|
||||
{ "type": "submit",
|
||||
"actions": [
|
||||
{ "i": "q2", "type": "answer", "kind": "choice", "k": "A" },
|
||||
{ "i": "q3", "type": "comment", "text": "Please keep the header row.",
|
||||
"images": [{ "path": "/home/sam/.plan2code/console/sessions/<sid>/uploads/3f2b9c1e.jpg", "name": "header.png" }] }
|
||||
],
|
||||
"reply": "File format: a\nNote on What to call it: Please keep the header row.\n Image: /home/sam/.plan2code/console/sessions/<sid>/uploads/3f2b9c1e.jpg (header.png)" }
|
||||
```
|
||||
Other fields, when present: `session` (actions about the session, dispatch on `i`: `__launch` and `__pickup` run `resume`, then read `skillFile` and follow it in this conversation; `__stop`, `__dashboard`, `__commit`, `__changelog`, `__delete`, `__brief`, `__review`, `__done`, `__git` are covered by the topic file `read` names, or by your notes), `chat` (the seq numbers of Quick questions that need a reply), `read` (open each path now, before acting), `resume`, `skillFile`, `handoffFile`, `fallback` (hop fields: run `resume` as given).
|
||||
|
||||
**`reply` is the important field**: what they would have typed in the terminal,
|
||||
one line per question, every part of an answer joined by `; `. Treat it as their
|
||||
typed answer and follow the workflow from there; `actions` has the same with
|
||||
structure. Collecting it already set the page to "working" for you: do not post
|
||||
a status first. Act on it in that turn — no asking whether to proceed, no
|
||||
summary back.
|
||||
## A patch
|
||||
|
||||
A `comment` may carry `images` and `files` (`[{ path, name }]`), listed under the
|
||||
note in `reply` as `Image:` / `File:` lines. **Open every path with your
|
||||
file-read tool before you answer** — or say you could not read it. They live in
|
||||
the session's `uploads/`; never copy one into the project yourself
|
||||
(`console-attachments.md`).
|
||||
One-line JSON, only what changed; the patch merges (`items`, `topics`, `docs` and blocks by `id`; `thread` appends; `null` deletes a key). The console fills `status:"open"`, `required:true`, `allowOther:true`, empty `options` and `thread`, and option keys `A`, `B`, `C` by position, so leave them out.
|
||||
|
||||
An action whose `i` starts with `__` is about the session, not a question:
|
||||
`{"title":"Audit export","headline":{"stage":"Working","cleared":4,"total":9,"confidence":"One area still needs work."},"items":[...],"agent":{"status":"working","activity":"Reading the plan"}}`
|
||||
|
||||
| Action | Read |
|
||||
| --- | --- |
|
||||
| `__stop` (plain, or with `handoff: true`), `__dashboard` (no finish up) | `console-stop.md` |
|
||||
| `__commit`, `__dashboard` (from a finished screen) | `console-finish.md` |
|
||||
| `__launch` | `console-launches.md` |
|
||||
| `__delete` | `console-launches.md` (the dashboard only) |
|
||||
| `__brief` | `notes/pathfinder.md` |
|
||||
| `__review`, `__done` | `building-review.md` |
|
||||
| `__git` | `notes/git.md` |
|
||||
`headline.cleared`/`total` drive the progress bar: always fill them. `agent.activity` is one plain sentence; add `quietMinutes` (1 to 60) when a stretch may go silent. Say `status:"working"` only while you work on with nothing for the person to answer. A new open question hands the turn over by itself; with only a doc or notice up, post `"agent":{"status":"waiting"}` yourself before you wait.
|
||||
|
||||
A hop (`__launch`, `__dashboard`, `__commit`) arrives with `resume`, the exact
|
||||
command that resumes the session under the new workflow — run it as given —
|
||||
and, in an installed skill, `skillFile`, the `SKILL.md` to follow next.
|
||||
Every item: `id` (new for each question, whole session), `kind`, `title` (2 to 4 plain words), `body` (markdown: the question and why it matters), optional `topic`, `doc`, `required:false` (adds Skip), `token` (`{"A":"approved"}`: the typed word an answer stands for).
|
||||
|
||||
Then, in ONE post (with `--wait`):
|
||||
- `choice`: `{"id":"q1","kind":"choice","title":"Export format","body":"Which format?","options":[{"text":"CSV","detail":"Opens in Excel","recommended":true},{"text":"JSON","detail":"For scripts"}]}`. Back: `{k}` or `{text}`; `allowOther:false` drops the free-text row.
|
||||
- `text`: `{"id":"q2","kind":"text","title":"Who uses it","body":"Who, and for what?","placeholder":"For example: reviewers, in Excel every Monday."}`. Back: `{text}`. `pattern` plus `patternHint` checks shape (kebab-case). The placeholder is an offer, so write a whole answer. On the fresh-idea card in Pathfinder, Plan and Quick Task add `"templates":"idea"` (also when the idea came as the argument, with a one-line summary in `placeholder`; a resumed map, PLAN-DRAFT or checkpoint gets no idea card; never mention templates in the terminal); a Notebook tab fills a box marked `"fill":"note"`.
|
||||
- `confirm`: `{"id":"q3","kind":"confirm","title":"Keep going","body":"Continue?","yesLabel":"Yes","noLabel":"Not yet"}`. Back: `{yes,text?}`.
|
||||
- `recap`: `{"id":"q4","kind":"recap","title":"What we heard","body":"Is this right?","summary":"- ..."}`. Back: `{ok,text?}`.
|
||||
- `menu`: `{"id":"q5","kind":"menu","title":"Next step","body":"What now?","options":[{"text":"Plan it"}],"command":"/plan2code-1-plan"}`. Back: `{k}`.
|
||||
|
||||
- settle what they answered: `"settle": true` (below)
|
||||
- reply to every note in that item's `thread`
|
||||
- reply to any Quick question (`console-chat.md`)
|
||||
- publish the next batch of questions
|
||||
|
||||
You never post the status for a turn: a post that asks a new question, and any
|
||||
`wait` started with a question open (or a finish, the dashboard menu, the git
|
||||
board), hands the turn over by itself (`agent.status` becomes `waiting`). Say
|
||||
`"agent": { "status": "working" }` only while you work on with nothing for them
|
||||
to answer, and `"agent": { "status": "waiting" }` yourself when you go back to
|
||||
waiting with nothing open for them (only a doc or a notice on the page, a
|
||||
brief just delivered): `wait` leaves a working agent working then, since
|
||||
that is also how an agent waiting out its subagents looks.
|
||||
|
||||
### Replying to a note
|
||||
|
||||
```jsonc
|
||||
{ "items": [{ "id": "p4", "thread": [
|
||||
{ "who": "agent", "text": "A proxy is the server some company networks route traffic through. **Markdown** is fine." }
|
||||
] }] }
|
||||
```
|
||||
|
||||
`{ "who": "agent", "text": "<markdown>" }` — `text`, not `md`. The server already
|
||||
wrote their note into the thread: send only your new entries (`thread`
|
||||
appends). Answer what they asked in the thread, even when you also change a doc
|
||||
or re-ask; "I've updated the doc" alone leaves their question unanswered.
|
||||
|
||||
### Recording the answer
|
||||
|
||||
`"settle": true` marks every card from their latest send `answered`, with the
|
||||
answer they sent. `"settle": ["q2"]` names the cards instead — use it when only
|
||||
some are final (a pick that still owes its recap stays open). A card the same
|
||||
post reopens is never settled. To record a
|
||||
reading of your own, also send the item with its `answer` (it wins):
|
||||
`{ "k": "A" }`, `{ "ks": ["A","C"] }`, `{ "text": "audit-export" }`,
|
||||
`{ "yes": true }`, `{ "verdict": "changes", "text": "..." }`,
|
||||
`{ "done": [0,1], "state": "done" }`, `{ "rows": [...] }`. A settled card turns
|
||||
into a record ("A · Continue without it"), so settle every card you are done
|
||||
with — one left open stays on the page as a question still owed.
|
||||
|
||||
---
|
||||
|
||||
## Posting an update
|
||||
|
||||
```
|
||||
node "<CONSOLE>" post --session <sid> --file <patch.json | -> [--wait <N>]
|
||||
```
|
||||
|
||||
The patch merges: scalars replace, `null` deletes a key, `items` / `topics` /
|
||||
`docs` and a doc's `blocks` merge by `id` (an unknown id is added), `thread`
|
||||
appends. **Send only what changed.** Never write a timestamp: the server stamps
|
||||
them. A refused patch is exit `3` with the reason on stderr; nothing is
|
||||
written.
|
||||
|
||||
While you work through a long stretch, say so:
|
||||
`{"agent":{"status":"working","activity":"Reading the plan"}}` — one plain
|
||||
sentence, shown in place of "thinking". The page calls a working agent stuck
|
||||
after two silent minutes: expecting longer, add `"quietMinutes": <1-60>` to
|
||||
`agent`. It only counts while you are working, so set it once.
|
||||
|
||||
`run` (session meter, `console-meter.md`), `folderIssue`
|
||||
(`console-workspace.md`) and `helpers` (`console-subagents.md`) are top-level
|
||||
keys too; `run` and `folderIssue` go to the session's ledger, never the page.
|
||||
|
||||
---
|
||||
|
||||
## The payload
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"title": "Audit export",
|
||||
"headline": { "stage": "Working", "cleared": 4, "total": 9,
|
||||
"confidence": "Looking solid, but one area still needs work.",
|
||||
"note": "optional sentence shown above the list" },
|
||||
"topics": [ { "id": "t2", "title": "How it behaves", "status": "current" } ],
|
||||
"items": [ /* the kinds below */ ],
|
||||
"docs": [ /* Documents, below */ ],
|
||||
"finish": { /* only at the end: console-finish.md */ },
|
||||
"agent": { "status": "waiting" }
|
||||
}
|
||||
```
|
||||
|
||||
Fill in `headline.cleared` / `total`: the progress bar is the first thing anyone
|
||||
looks at. `confidence` is a plain-English sentence, never raw scores. Post
|
||||
`"specDir": "specs/<idea>"` once the folder exists (or pass `--spec` to
|
||||
`open`): the page builds a resume command from it if you ever cannot answer a
|
||||
stop. `stopWarning` is in `console-stop.md`.
|
||||
|
||||
### Every item
|
||||
|
||||
**Every new question gets a new `id`**, for the whole session.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "q7",
|
||||
"topic": "t2",
|
||||
"kind": "choice",
|
||||
"title": "Export format", // 2-4 plain words a newcomer understands
|
||||
"body": "The question, in markdown, with why it matters.",
|
||||
"required": true, // false adds a "Skip this one" link
|
||||
"doc": "report", // optional: a "Read ... in full" button for that doc
|
||||
"status": "open", // open | answered | reopened | skipped
|
||||
"token": { "A": "approved" } // optional: the typed word an answer stands for
|
||||
}
|
||||
```
|
||||
|
||||
`token` is only needed where the terminal word differs from the option's `k`
|
||||
or verdict `id`: without it, `reply` uses the key itself.
|
||||
|
||||
### The kinds
|
||||
|
||||
| `kind` | Use it for | Extra fields | You get back |
|
||||
| Kind | Use | Extra fields | Back |
|
||||
| --- | --- | --- | --- |
|
||||
| `choice` | one of several | `options[]`, `allowOther` | `{ k }` **or** `{ text }` |
|
||||
| `multi` | any number of several | `options[]`, `presets[]` | `{ ks[], text? }` |
|
||||
| `text` | free text | `placeholder`, `help`, `pattern`, `patternHint`, `templates` | `{ text }` |
|
||||
| `confirm` | yes or no | `yesLabel`, `noLabel`, `danger`, `consequences` | `{ yes, text? }` |
|
||||
| `recap` | play decisions back for agreement | `summary` (markdown) | `{ ok, text? }` |
|
||||
| `review` | read something, then approve | `doc` (always), `summary`, `verdicts[]` (each `{ id, label, danger? }`: `label`, not `text`), `nothingYet` (the line under the buttons; defaults to "Nothing has been changed yet…", so `false` when the change is already on disk) | `{ verdict, text? }` |
|
||||
| `checklist` | steps only they can do | `steps[]`, `valuesLabel` | `{ done?[], state?, text? }` (each left out when nothing was ticked or picked) |
|
||||
| `menu` | what to do next | `options[]`, `command` | `{ k }` |
|
||||
| `list` | reorder or edit a breakdown | `rows[{id,title,body}]` | `{ rows[] }`, or `{ text }` when they changed nothing; `reply` names renames, additions and removals |
|
||||
| `notice` | something to read, no answer | — | nothing |
|
||||
| `multi` | any number of several | `options`, `presets:[{label,ks}]` | `{ks,text?}` |
|
||||
| `review` | read, then approve | `doc` (required), `summary`, `verdicts:[{id,label,danger?}]`, `nothingYet` (false once the change is on disk) | `{verdict,text?}` |
|
||||
| `checklist` | steps only they can do | `steps`, `valuesLabel` | `{done?,state?,text?}` |
|
||||
| `list` | reorder or edit a breakdown | `rows:[{id,title,body}]` | `{rows}` or `{text}` |
|
||||
| `notice` | read, no answer | none | none |
|
||||
|
||||
An option is `{ "k": "A", "text": "short label", "detail": "the trade-off", "recommended": true }`.
|
||||
`detail` is the difference between a person choosing and a person guessing.
|
||||
Items show in the order sent: send them in the order you want them answered.
|
||||
|
||||
- **`choice`**: one of the two, never both. The page offers "Something else, in
|
||||
your own words" in the same radio group; read `k` if it is there, otherwise
|
||||
`text`. `"allowOther": false` drops it when the options are the whole set.
|
||||
- **`multi`**: `text` joins the ticks rather than replacing them. `presets`
|
||||
(`[{ "label": "Critical and warnings", "ks": ["1","2"] }]`) only tick boxes.
|
||||
- **`pattern`** is a JavaScript regex checked as they type, with `patternHint`
|
||||
shown when it fails. Use it for anything with a shape, above all kebab-case.
|
||||
- **A placeholder is an offer.** The **Autofill suggestion** button drops it
|
||||
into the box as a real answer (a lead-in like "For example:" is stripped), so
|
||||
write a whole example in their voice, one that satisfies any `pattern`.
|
||||
- **Starter templates:** on the `text` card that asks for a **fresh idea** in
|
||||
Pathfinder, Plan and Quick Task, add `"templates": "idea"` (any other kind or
|
||||
value is exit 3). Launched with notes or an idea as the argument? Still set
|
||||
it, with a one-line summary in `placeholder`. A resumed map, PLAN-DRAFT or
|
||||
checkpoint gets no idea card. Only the box's text comes back; never mention
|
||||
templates in the terminal.
|
||||
- **Fill from a Notebook tab:** on a `text` item, `"fill": "note"` (its only
|
||||
value; any other kind or value is exit 3) has the page fill the first open one
|
||||
once, with the tab's text and ticked pictures, when the person started from a
|
||||
Notebook tab. You read it only when they send that box (Send, or Stop or
|
||||
Back to the dashboard, which carry ready answers).
|
||||
- **Recommend only when you genuinely know better and can say why.** "Which
|
||||
format survives Excel?" is yours; "Who is this for?" is not — there a
|
||||
recommendation is an anchor people rubber-stamp. At most one per question.
|
||||
**Documents:** the first patch that carries `docs` is answered with a `read` pointer to `console-docs.md`.
|
||||
|
||||
Items appear in the order you send them, and the person walks the open ones with
|
||||
Previous / Next: send them in the order you want them answered.
|
||||
## Settling and notes
|
||||
|
||||
### Documents
|
||||
`"settle":true` marks every card in their latest send answered with what they sent; `"settle":["q2"]` names cards. A card the same post reopens is never settled. To record your own reading, send the item with `answer` (`{k}`, `{ks}`, `{text}`, `{yes}`, `{verdict,text}`, `{rows}`).
|
||||
|
||||
```jsonc
|
||||
"docs": [{
|
||||
"id": "map", "title": "What we've agreed",
|
||||
"note": "what changed in this version",
|
||||
"saved": "specs/lunch-vote/pathfinder/map.md",
|
||||
"blocks": [
|
||||
{ "id": "b1", "state": "settled", "md": "## Where we're headed\n\n..." },
|
||||
{ "id": "b2", "state": "assumed", "md": "### File format\n\nAssuming CSV..." },
|
||||
{ "id": "b3", "state": "draft", "md": "### Still to work out\n\n- ..." },
|
||||
{ "id": "b4", "file": "specs/lunch-vote/overview.md" }
|
||||
]
|
||||
}]
|
||||
```
|
||||
Every note in an item's `thread` gets a reply: `{"id":"p4","thread":[{"who":"agent","text":"..."}]}`. Send only new entries.
|
||||
|
||||
Each doc is a tab. Patch blocks as decisions land: `{ "id": "b2", "state":
|
||||
"settled" }` settles b2 and keeps its text, blocks you leave out stay, a new id
|
||||
goes at the end, `{ "id": "b3", "_delete": true }` removes one (a doc entry
|
||||
with `"_delete": true` removes the whole tab).
|
||||
## What the console refuses (exit 3)
|
||||
|
||||
- **`state`**: `settled` (decided), `assumed` (picked to keep going, still open:
|
||||
shown dashed, "Assumed for now"), `draft` (dimmed). Marking assumptions
|
||||
honestly is what stops a half-finished doc reading as decisions.
|
||||
- **`file`** instead of `md`: the console reads the block's text from that file
|
||||
(relative to the project, never outside it). Re-send the block, or the doc
|
||||
with `"refresh": true`, after the file changes. `"select": "tasks"` keeps only
|
||||
its `- [ ] **Task N.M:**` lines. Never paste a file you could name.
|
||||
- **`image`** instead of `md`: `{ "id", "image": "shots/run.png", "alt": "..." }`
|
||||
shows a PNG, JPEG or WebP (5 MB at most) saved directly in the session's
|
||||
`shots/` folder (the `session` path `open` printed), named with letters,
|
||||
digits, `.`, `_` or `-`; anything else is exit `3`.
|
||||
- **`version`** moves by itself: a known doc whose content changed is the next
|
||||
version. Send one only to jump; it never goes back. Write a one-line `note`
|
||||
when you change a doc, and `"stale": true` while answers it does not reflect
|
||||
have landed.
|
||||
- **`saved`** is the path of the file the doc mirrors, when one exists: the page
|
||||
shows the path instead of a download. Leave it off docs that exist only here.
|
||||
- more than three open required questions at once (optional cards and notices do not count)
|
||||
- internal vocabulary in a title (grill, frontier, fog, HITL, AFK, durable, `Locked:`, `Blocked by:`, `State:`)
|
||||
- more than one recommended option on a question
|
||||
- loop completion markers (`TASK_COMPLETE`, `PHASE_COMPLETE` and the rest)
|
||||
- a bare Requirements, Feasibility, Integration or Risk followed by a number (hyphenate or reword)
|
||||
- a doc `version` that goes back (leave `version` out)
|
||||
- a finish `command` with `<` or `>` in it
|
||||
- a note left without a reply
|
||||
- a `finish` while `stopWarning` is set or a helper is still `running`
|
||||
- a `stop` with no `finish` (`stop --session <sid> --force` for a dead page)
|
||||
|
||||
---
|
||||
It cannot see these two: every turn ends on a `wait`, and no new open question after a `finish`.
|
||||
|
||||
## House rules the server enforces
|
||||
Ending: every session end posts `finish` (`{"settle":true,"finish":{"headline":"Phase 3 is done","body":"...","command":"/plan2code-3-implement specs/x/overview.md","dashboard":true}}`, with `--wait`, then keep waiting for the button), then `stop`. A pause (headline starting "Paused") has no `dashboard` and stops at once. Your notes give your workflow's finish; read `console-finish.md` for every field.
|
||||
|
||||
A patch that breaks one is refused, exit `3`, with the reason:
|
||||
## Read when
|
||||
|
||||
1. **At most three questions open at once.**
|
||||
2. **No internal vocabulary in a title**: *grill*, *frontier*, *fog*, *HITL*,
|
||||
*durable*, `Locked:`, `Blocked by:`.
|
||||
3. **At most one recommended option per question.**
|
||||
4. **No loop completion markers** (`TASK_COMPLETE`, `PHASE_COMPLETE` and the rest).
|
||||
5. **No bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a
|
||||
number** (the metrics collector scrapes that): hyphenate or reword. Rules 4
|
||||
and 5 skip `file` blocks: those words are already on disk.
|
||||
6. **Chat replies hold together** (`console-chat.md`).
|
||||
7. **`run`, `folderIssue` and `helpers` are well formed** (their topic files).
|
||||
8. **A doc's `version` never goes back.**
|
||||
9. **A finish `command` has no placeholders** (`<` or `>`).
|
||||
10. **Every note gets a reply.** A card whose thread ends with the person's own
|
||||
words stays that way until a patch adds an agent reply to it; settling or
|
||||
reopening it does not count. Exempt once the item is deleted, or the whole
|
||||
session is ending.
|
||||
|
||||
---
|
||||
|
||||
## Ending
|
||||
|
||||
Every session end — done, a pause, a stop request, an off-ramp — posts a
|
||||
`finish` **before** `stop`, and every ending but a pause keeps waiting for the
|
||||
person's last button. Read `console-finish.md` before your first finish post:
|
||||
it has the fields, the dashboard button and the order. Before any finish, every
|
||||
subagent or background job you started must have reported back.
|
||||
|
||||
---
|
||||
|
||||
## Worked example
|
||||
|
||||
The first questions of a pathfinder session, piped in with `post --file - --wait 240`:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Audit export",
|
||||
"headline": { "stage": "Charting", "cleared": 0, "total": 6 },
|
||||
"items": [
|
||||
{ "id": "q1", "kind": "choice", "title": "What you end up with",
|
||||
"body": "When this is done, what exists that does not exist now?",
|
||||
"options": [
|
||||
{ "k": "A", "text": "A plan, ready to build from", "detail": "We write the decisions down. Nothing is built yet.", "recommended": true },
|
||||
{ "k": "B", "text": "A change already made", "detail": "Small enough to just do. We would skip planning entirely." }
|
||||
] },
|
||||
{ "id": "q2", "kind": "text", "title": "Who uses it",
|
||||
"body": "Who uses the result, and what do they do with it the day it lands?",
|
||||
"placeholder": "For example: compliance reviewers, who open it in Excel every Monday." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
It lands and waits in one command; the new questions make it the person's turn.
|
||||
| File | When |
|
||||
| --- | --- |
|
||||
| `notes/<workflow>.md` | right after `open` |
|
||||
| `building.md` | right after `open`: implement, implement-review, quick-task |
|
||||
| `console-launches.md` | you are the dashboard |
|
||||
| `console-meter.md` | a `run` was refused |
|
||||
| `console-attachments.md` | a file you write under `specs/` cites a note's attachment |
|
||||
| `console-trouble.md` | something breaks (a failed `open`, a repeat delivery, a dead server) |
|
||||
Reference in new issue
Block a user