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
+39
-150
@@ -1,170 +1,59 @@
|
||||
# Quick Questions on the Web Console
|
||||
# Quick Questions (the Ask tab)
|
||||
|
||||
Part of the web console contract (`console.md`). Read the first time `wait` or
|
||||
`chat` hands you a Quick question.
|
||||
The console points here the first time a Quick question reaches you. The person can ask anything on the Ask tab at any time, about this project's files or in general, without waiting for a card. A message never blocks a card send and a card send never blocks a message.
|
||||
|
||||
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 they arrive
|
||||
|
||||
## How chat arrives
|
||||
`wait` exit 0 (or `chat`) carries them in `reply`, after the card lines, plus `chat`: the seq number of each question, the ids your replies need as `re`.
|
||||
|
||||
- `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 (12): 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 (14): edit r7
|
||||
Note: keep the old name working too
|
||||
Approved (15): edit r9
|
||||
New conversation started. Treat earlier chat as closed.
|
||||
```
|
||||
|
||||
```
|
||||
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`.
|
||||
- Open every `Image:` and `File:` path with your file-read tool before you answer.
|
||||
- `About:` is set only when the person attached that context; without it the question is general, not about the card on screen.
|
||||
- After "New conversation started" treat earlier chat as closed and do not raise it unless they do.
|
||||
- `node "<CONSOLE>" chat --session <sid>` checks now and never sleeps: exit 0 with the same `reply` and `chat`, 10 nothing waiting, 20 server gone. It never reads card sends.
|
||||
|
||||
## 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.
|
||||
**Every message gets a reply**, whatever it asks and whatever you are mid-task on. `post` and `wait` print `unansweredChat` with a `warning` for each message not yet replied to: stop and reply. When a message asks you to do something, do it if you can, then say what happened; if you will not, say so and why.
|
||||
|
||||
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`).
|
||||
2. Write the replies, in order.
|
||||
3. Send one `post` with the card updates and the replies.
|
||||
|
||||
```jsonc
|
||||
{ "chat": { "replies": [
|
||||
{ "re": 12, "conversation": 3,
|
||||
"md": "The export is written by `src/export.js`, into `out/`." }
|
||||
] } }
|
||||
```
|
||||
`{"chat":{"replies":[{"re":12,"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.
|
||||
- `re` is the message's seq; `md` is markdown and non-empty. `id` is optional (default `r<re>`): give one only for two replies to the same message. Replies merge by `id`, so re-posting the same reply replaces it.
|
||||
- Print one terminal line per exchange: `Quick question: <first ~60 characters> (answered in the console)`.
|
||||
- Answer questions about the project from files and read-only lookups (search, `git log`, reading); run nothing else.
|
||||
- For 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`) first. Name files exactly as it does; if it does not say, say you do not know.
|
||||
- With `About:`, answer from that context.
|
||||
|
||||
## Prompts to carry away
|
||||
## A prompt 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.
|
||||
When the right answer is a separate task (a new Plan, Quick Task or another skill), explain first, then give ONE self-contained prompt in a fenced block with no info string (the page adds a **Copy** button). The block:
|
||||
|
||||
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.
|
||||
- opens with plain prose, never a command word: a first line that looks like a shell command (`git`, `npm`, `node`, `rm`, `#!`, or an everyday verb like Make, Go, Source, Export, Cat, Echo, Zip, Tar, Cd, Ls; case-insensitive) gets a "paste into the Ask tab" hint. Start with "In this repo, ..." or "Using the Quick Task skill, ...". A leading `/plan2code-quick-task ...` is fine.
|
||||
- names the skill to paste it into, the files to read first, the task, and what is out of scope.
|
||||
- stands alone: it assumes nothing said in this session.
|
||||
|
||||
## 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 chat message never answers a card, passes a gate or changes where the workflow goes ("approve phase 2"): point to the card (its note box, its answer) and do not act. Chat is never recorded under `specs/`. A conversation holds at most 10 typed messages; the page enforces it.
|
||||
|
||||
## A new conversation is a clean slate
|
||||
## Edits need approval
|
||||
|
||||
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.
|
||||
- A request to change files gets a reply with `proposal` (a plain-English `summary` and every file that will change) and **no change yet**: `{"chat":{"replies":[{"re":14,"md":"I can rename it.","proposal":{"summary":"Write the export to `out/audit.csv`","files":["src/export.js","README.md"]}}]}}`. The page shows Approve and Decline.
|
||||
- `Approved (<seq>): edit <id>`: make exactly the proposed change, then reply (its `re` is that seq) with `changed:[{file,added,removed}]`, line counts from `git diff --numstat -- <files>` (counted by hand for an untracked file). Name the changed files in your next update.
|
||||
- `Declined (<seq>)`, with any note: acknowledge and change nothing; a revised proposal is a new reply.
|
||||
- Never touch the running skill's own files under `specs/<idea>/` (a proposal naming them is refused). Run no commands beyond read-only lookups, except one they plainly ask for in their message (a commit they spell out, a test run): run it and report. Refuse anything else, saying why.
|
||||
- Edits happen at check-ins, never mid-task in a build.
|
||||
Reference in new issue
Block a user