2026-10-11 16:39:25 -07:00
|
|
|
# Quick Questions on the Web Console
|
|
|
|
|
|
|
|
|
|
Part of the web console contract (`console.md`). Read the first time `wait` or
|
|
|
|
|
`chat` hands you a Quick question.
|
|
|
|
|
|
|
|
|
|
The page has an **Ask** tab, always the last one, on every workflow. There the
|
|
|
|
|
person can ask anything, about this project's files or in general, at any
|
|
|
|
|
time, without waiting for a card. Their messages reach you at your next
|
|
|
|
|
check-in, through the `wait` you already run (and, in a build, the instant
|
|
|
|
|
`chat` check). Chat rides its own channel: a message never blocks a card send,
|
|
|
|
|
and a card send never blocks a message. The page handles its own refusals, so
|
|
|
|
|
you never see them: `too-long` past 4,000 characters, `limit` after 10
|
|
|
|
|
messages, `offline` when no agent has checked in for a few minutes (a finish alone does
|
|
|
|
|
not end the chat: you may still be waiting on its buttons),
|
|
|
|
|
`stale` after a new conversation started.
|
|
|
|
|
|
|
|
|
|
## How chat arrives
|
|
|
|
|
|
|
|
|
|
- `wait` exit `0` may carry `chat: [...]` beside `actions`, or, when no card
|
|
|
|
|
was sent, be `type: "chat"` with `actions: []`. No exit code changes.
|
|
|
|
|
- `reply` gains one block per entry after the card lines:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Quick question: Where does the export go?
|
|
|
|
|
About: Export format
|
|
|
|
|
Image: /home/sam/.plan2code/console/sessions/<sid>/uploads/3f2b9c1e.jpg (shot.png)
|
|
|
|
|
File: /home/sam/.plan2code/console/sessions/<sid>/uploads/9e4b2d7a.json (config.json)
|
|
|
|
|
Declined: edit r7
|
|
|
|
|
Note: keep the old name working too (only a decline carries one)
|
|
|
|
|
New conversation started. Treat earlier chat as closed.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Typed text past its first line is indented, so only a real entry ever
|
|
|
|
|
starts a line.
|
|
|
|
|
- Each `chat` entry carries `seq`, `conversation` and `kind`: `message`
|
|
|
|
|
(`text`, optional `about`, `images` and `files`), `decision` (`re`,
|
|
|
|
|
`decision` `approve` or `decline`, optional `text`) or `reset`.
|
|
|
|
|
- `about` is set only when the person attached it with **+ Add context**. The
|
|
|
|
|
page never adds one on its own, so a message without it is a general
|
|
|
|
|
question, not one about the card on screen.
|
|
|
|
|
- Open every `Image:` and `File:` path with your file-read tool before you
|
|
|
|
|
answer, as for notes.
|
|
|
|
|
- `node "<CONSOLE>" chat --session <sid>` checks right now and never sleeps:
|
|
|
|
|
exit `0` with `{ chat, reply, terminalLine }`, `10` with `{ chat: [] }` when
|
|
|
|
|
nothing is waiting, `20` when the server is gone. It never reads or collects
|
|
|
|
|
card sends; those stay with `wait`.
|
|
|
|
|
|
|
|
|
|
## Answering
|
|
|
|
|
|
|
|
|
|
**Every message gets a reply, always.** The Ask tab is the person talking to
|
|
|
|
|
you, and the page shows "working on the answer" until a reply lands. Never
|
|
|
|
|
leave one unanswered, whatever it asks and whatever mid-task you are in. When
|
|
|
|
|
a message asks you to do something, do it if you can, then say what happened; if
|
|
|
|
|
you will not, the reply says so and why. `post` and `wait` print
|
|
|
|
|
`unansweredChat` with a `warning` for every message handed over and not yet
|
|
|
|
|
replied to: treat that as a stop-and-reply.
|
|
|
|
|
|
|
|
|
|
1. Handle any card answers first, under the workflow's own rules.
|
|
|
|
|
2. Write the chat replies, in inbox order.
|
|
|
|
|
3. Send **one** `post` with the card updates and `chat: { replies: [...] }`
|
|
|
|
|
(`chat.replies`).
|
|
|
|
|
|
|
|
|
|
```jsonc
|
|
|
|
|
{ "chat": { "replies": [
|
|
|
|
|
{ "re": 12, "conversation": 3,
|
|
|
|
|
"md": "The export is written by `src/export.js`, into `out/`." }
|
|
|
|
|
] } }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `re` is the message's `seq`, `conversation` is copied from the entry, `md` is
|
|
|
|
|
markdown. `id` is optional: left out, it is `r<re>`. Give one only when you
|
|
|
|
|
send two replies to the same message.
|
|
|
|
|
- Replies merge by `id`, so re-posting the same reply after a repeated
|
|
|
|
|
delivery replaces it (unlike `thread`, which appends).
|
|
|
|
|
- Print one terminal line per exchange: `Quick question: <first ~60 characters
|
|
|
|
|
of the question> — answered in the console`.
|
|
|
|
|
- Answer questions about the project by reading files and read-only lookups
|
|
|
|
|
(search, `git log`, reading files); run no other commands.
|
|
|
|
|
- Questions about what a Plan2Code skill does, asks or writes: read that
|
|
|
|
|
skill's `SKILL.md` (`~/.agents/skills/<skill>/SKILL.md`, or the table "What
|
|
|
|
|
each skill reads and writes" in `~/.agents/skills/plan2code/SKILL.md`)
|
|
|
|
|
before answering. Never answer from menu text, card blurbs or memory. Name
|
|
|
|
|
files exactly as the skill does; if the skill does not say, say you do not
|
|
|
|
|
know.
|
|
|
|
|
- When `about` is set, answer from that context: the card, doc section or
|
|
|
|
|
spec the person was looking at.
|
|
|
|
|
|
2026-10-19 17:55:37 -07:00
|
|
|
## Prompts to carry away
|
|
|
|
|
|
|
|
|
|
Some questions are really a new task: the person asks for "a prompt", or the
|
|
|
|
|
right answer is work for a separate Plan, Quick Task or another skill rather
|
|
|
|
|
than something to do inside this session. Do not start that work here and do
|
|
|
|
|
not make them retype your answer. Reply with the explanation first, then ONE
|
|
|
|
|
self-contained prompt in a fenced block with no info string. The page draws
|
|
|
|
|
every fenced block with a **Copy** button, so the person copies it into a new
|
|
|
|
|
conversation.
|
|
|
|
|
|
|
|
|
|
A good prompt block:
|
|
|
|
|
|
|
|
|
|
- opens with plain prose, never a command word. A block whose first line looks
|
|
|
|
|
like a terminal command (`git`, `npm`, `node`, `rm` and the like, or `#!`)
|
|
|
|
|
gets the muted "paste it into the Ask tab" hint, which is wrong for a prompt.
|
|
|
|
|
The check is case-insensitive and also catches everyday verbs that are shell
|
|
|
|
|
commands (Make, Go, Source, Export, Service, Cat, Echo, Zip, Tar, Cd, Ls), so
|
|
|
|
|
"Make the report export..." trips it. Start with "In this repo, ..." or "Using
|
|
|
|
|
the Quick Task skill, ...". A leading skill command (`/plan2code-quick-task ...`)
|
|
|
|
|
is fine: it gets none;
|
|
|
|
|
- names the skill to paste it into, the files to read first, and what to do;
|
|
|
|
|
- states what is out of scope, so the new conversation does not wander;
|
|
|
|
|
- stands alone: it assumes nothing said in this session, because the new
|
|
|
|
|
conversation has none of it.
|
|
|
|
|
|
|
|
|
|
One block per reply, and only when the work is likely to move to a new
|
|
|
|
|
conversation. A plain answer stays a plain answer.
|
|
|
|
|
|
2026-10-11 16:39:25 -07:00
|
|
|
## Never steer the workflow
|
|
|
|
|
|
|
|
|
|
A chat answer never changes a card's answer, a gate, or where the workflow
|
|
|
|
|
goes. If a message asks for that ("approve phase 2", "skip the tests
|
|
|
|
|
question"), reply by pointing to the card — its note box for a comment, its
|
|
|
|
|
answer for a change — and do not act on it. Chat never counts as an answer to
|
|
|
|
|
a card and is never recorded under `specs/`.
|
|
|
|
|
|
|
|
|
|
## A new conversation is a clean slate
|
|
|
|
|
|
|
|
|
|
After a `reset` entry (New conversation, or a skill switch through the
|
|
|
|
|
dashboard) treat earlier chat as closed, and do not bring it up unless the
|
|
|
|
|
person does. A conversation holds at most 10 typed messages; the page
|
|
|
|
|
enforces it, so never tell someone to keep asking past it.
|
|
|
|
|
|
|
|
|
|
## Edits need approval first
|
|
|
|
|
|
|
|
|
|
- A request to change files gets a reply carrying `proposal: { summary,
|
|
|
|
|
files }` — a plain-English summary and every file that will change — and
|
|
|
|
|
**no change yet**. The page shows it with Approve and Decline.
|
|
|
|
|
- Only after `Approved: edit <id>`: make exactly the proposed change, then post
|
|
|
|
|
a reply (its `re` is the decision's `seq`) carrying `changed: [{ file,
|
|
|
|
|
added, removed }]`, with line counts from `git diff --numstat -- <files>` (or
|
|
|
|
|
counted by hand for an untracked file). Name the changed files in your next
|
|
|
|
|
progress update or `activity` line.
|
|
|
|
|
- `Declined:` (with any note): acknowledge it and change nothing. A revised
|
|
|
|
|
proposal is a new reply.
|
|
|
|
|
- Hard limits: never touch the running skill's own files under
|
|
|
|
|
`specs/<idea>/` (`post` rejects a proposal that names them); run no commands
|
|
|
|
|
beyond read-only lookups, except one the person plainly asks you to run in
|
|
|
|
|
their message (a commit they spell out, a test run): run it, then report the
|
|
|
|
|
result in the reply; refuse anything else and say why, in the reply.
|
|
|
|
|
- Edits happen only at check-ins, never mid-task in a build.
|
|
|
|
|
|
|
|
|
|
```jsonc
|
|
|
|
|
{ "chat": { "replies": [
|
|
|
|
|
{ "id": "r14", "re": 14, "conversation": 3, "md": "I can rename it.",
|
|
|
|
|
"proposal": { "summary": "Write the export to `out/audit.csv` instead of `out/export.csv`",
|
|
|
|
|
"files": ["src/export.js", "README.md"] } }
|
|
|
|
|
] } }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## What the server checks
|
|
|
|
|
|
|
|
|
|
Each reply needs a unique `id` (or none, to take `r<re>`), an `re` naming a real
|
|
|
|
|
message or decision `seq`, an integer `conversation` and non-empty `md`. A
|
|
|
|
|
`proposal` needs a `summary` and project-relative `files`, none under the
|
|
|
|
|
running skill's `specs/<idea>/`. `changed` is a list of `{ file, added,
|
|
|
|
|
removed }`. The house rules on completion markers and metric-like words cover
|
|
|
|
|
reply text too.
|
|
|
|
|
|
|
|
|
|
## The same chat 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.
|