mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20: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
@@ -1,27 +1,14 @@
|
||||
# Changelog on the Web Console
|
||||
# Changelog
|
||||
|
||||
Workflow notes for `changelog`, part of the web console contract (`console.md`).
|
||||
`changelog`: post `activity` while you read the history and diff. One card per step, each only when needed:
|
||||
|
||||
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 |
|
||||
| Step | Card |
|
||||
| --- | --- |
|
||||
| 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?". |
|
||||
| Version | `choice` "Which version?": the computed version (recommended, reason in `body`), "Keep Y" when the branch's entry could stay, "Another version" (`allowOther`). Typed text is unchecked: anything but `X.Y.Z` gets the card again with a `thread` reply. Skipped when the entry is right. |
|
||||
| Entries | `list` "Entries to add": `title` the entry line, `body` its section. `reply` names renames, additions, removals. A row they add has no section: ask, or file it and say so. |
|
||||
| Result | Doc `entry` (`"saved":"CHANGELOG.md"` once written) plus a `review` with verdicts `write`, `change`, `stop`. |
|
||||
| package.json | `confirm`, `old → new` in `consequences`. |
|
||||
| Commit now? | `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.
|
||||
Entered from **Update CHANGELOG first** on a finished Quick Task or Finalize
|
||||
(`console-finish.md`): the hop is the same as a dashboard launch, and nothing
|
||||
else changes. The yes above is the exit to Git as always, so the person lands in
|
||||
the commit flow with the CHANGELOG already updated.
|
||||
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`.
|
||||
A yes ends no session (no `finish`): settle the card, resume as `git` (`open --resume <sid> --no-open --workflow git`), read `~/.agents/skills/plan2code-git/SKILL.md` and start its commit flow.
|
||||
A no finishes with `"dashboard":true`, version and entries in `body`, no `command`. A stop's `command` is `/plan2code-changelog`.
|
||||
@@ -1,83 +1,38 @@
|
||||
# Diagnose on the Web Console
|
||||
|
||||
Workflow notes for `diagnose`, part of the web console contract (`console.md`).
|
||||
# Diagnose
|
||||
|
||||
## The bug
|
||||
|
||||
A typed argument that already describes the bug skips the cards it answers.
|
||||
Otherwise ask in one batch (at most three open), posted with `--wait`:
|
||||
An argument that already describes the bug skips the cards it answers. Otherwise one `--wait` batch, no `templates`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"title": "Diagnose a bug",
|
||||
"headline": { "stage": "The bug", "cleared": 0, "total": 3 },
|
||||
"items": [
|
||||
{ "id": "bug", "kind": "text", "title": "What is wrong",
|
||||
"body": "The bug, in a sentence or two.",
|
||||
"placeholder": "The CSV export drops the last row when the report has more than 100 rows." },
|
||||
{ "id": "expected", "kind": "text", "title": "Expected and actual",
|
||||
"body": "What should happen, and what happens instead.",
|
||||
"placeholder": "Expected 150 rows in the file; it has 149, and the last order is missing." },
|
||||
{ "id": "see-it", "kind": "text", "title": "How to see it",
|
||||
"body": "The steps, command, page or input that shows it, and since when if you know.",
|
||||
"placeholder": "Run npm run export -- --month 2026-09 and count the rows. It worked last month." }
|
||||
]
|
||||
}
|
||||
{"title":"Diagnose a bug","headline":{"stage":"The bug","cleared":0,"total":3},"items":[{"id":"bug","kind":"text","title":"What is wrong","body":"The bug, in a sentence or two."},{"id":"expected","kind":"text","title":"Expected and actual","body":"What should happen, and what happens instead."},{"id":"see-it","kind":"text","title":"How to see it","body":"The steps, command, page or input that shows it, and since when if known."}]}
|
||||
```
|
||||
|
||||
No `"templates"` on these cards: the starter templates are for a fresh idea,
|
||||
and a bug report is not one. A follow-up the answers leave open is a new card
|
||||
with a new id.
|
||||
A follow-up the answers leave open is a new card with a new id.
|
||||
|
||||
## The cause
|
||||
|
||||
Post the cause as a doc, `id` `"cause"`, as soon as there is something to show,
|
||||
and grow it as evidence lands, with `"agent": { "status": "working",
|
||||
"activity": "..." }` while you reproduce and narrow:
|
||||
Doc `cause`, posted as soon as there is something to show and grown as evidence lands, with `agent` `working` while you reproduce:
|
||||
|
||||
```jsonc
|
||||
"docs": [{ "id": "cause", "title": "The cause", "note": "Reproduced; narrowing", "blocks": [
|
||||
{ "id": "repro", "state": "settled", "md": "## Reproduction\n\n`node scripts/export-check.mjs` fails: 149 rows, expected 150." },
|
||||
{ "id": "found", "state": "settled", "md": "## The cause\n\n`src/export.ts` `writeRows()`: the loop stops at `rows.length - 1`. **Proven** by the reproduction." },
|
||||
{ "id": "fix", "state": "settled", "md": "## Suggested fix\n\nLoop to `rows.length`. **Size:** Small (Quick Task)." }
|
||||
]}]
|
||||
{"docs":[{"id":"cause","title":"The cause","note":"Reproduced; narrowing","blocks":[{"id":"repro","state":"settled","md":"## Reproduction\n\n..."},{"id":"found","state":"settled","md":"## The cause\n\n..."},{"id":"fix","state":"settled","md":"## Suggested fix\n\n... **Size:** Small (Quick Task)."}]}]}
|
||||
```
|
||||
|
||||
- **Unproven** guesses are `assumed` blocks, one per guess, ranked, each with
|
||||
its evidence and what would confirm it. A guess the evidence proves becomes
|
||||
`settled`; one it rules out is removed (`"_delete": true`).
|
||||
- Keeping a failing test inside the project is a `confirm` card pointing at
|
||||
the doc (`"doc": "cause"`), `yesLabel` "Keep it", `noLabel` "Throw it away".
|
||||
- Unproven guesses are `assumed` blocks, ranked, each with its evidence and what would confirm it. Proven: `settled`. Ruled out: `"_delete":true`.
|
||||
- Keeping a failing test in the project: `confirm` with `"doc":"cause"`, `yesLabel` "Keep it", `noLabel` "Throw it away".
|
||||
|
||||
## The bug name
|
||||
|
||||
With the cause written, ask the folder name, posted with `--wait`:
|
||||
After the cause, `--wait`:
|
||||
|
||||
```jsonc
|
||||
{ "id": "name", "kind": "text", "title": "Name for the write-up", "doc": "cause",
|
||||
"body": "The diagnosis is saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.",
|
||||
"placeholder": "csv-export-drops-rows",
|
||||
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
|
||||
"patternHint": "Lowercase letters, numbers and dashes, like csv-export-drops-rows." }
|
||||
{"id":"name","kind":"text","title":"Name for the write-up","doc":"cause","body":"Saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.","placeholder":"csv-export-drops-rows","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","patternHint":"Lowercase letters, numbers and dashes."}
|
||||
```
|
||||
|
||||
Once written, re-send the doc with
|
||||
`"saved": "specs/<name>/DIAGNOSIS-<date>.md"` and its blocks replaced by one
|
||||
`file` block for that path (delete the old ids).
|
||||
Once written, re-send `cause` with `"saved":"specs/<name>/DIAGNOSIS-<date>.md"` and one `file` block for that path (delete the old block ids).
|
||||
|
||||
## The finish
|
||||
|
||||
`command` is `/plan2code-quick-task specs/<name>` (small fix) or
|
||||
`/plan2code-1-plan specs/<name>` (big fix) with the real folder filled in
|
||||
(`/plan2code-quick-task specs/csv-export-drops-rows`), never a placeholder: a
|
||||
copied command must reach the diagnosis. `body` names the cause, how sure, and that the
|
||||
next step reads the diagnosis first. `doc` is `"cause"`. `"dashboard": true`,
|
||||
then keep waiting for the press (`console-finish.md`): back on the dashboard
|
||||
the folder shows as "Bug diagnosed", with that card lit.
|
||||
`command` is `/plan2code-quick-task specs/<name>` (small fix) or `/plan2code-1-plan specs/<name>` (big fix), real folder filled in. `body`: the cause, how sure, and that the next step reads the diagnosis first. `"doc":"cause"`, `"dashboard":true`. Nothing kept (did not reproduce, no guess held): no `command`, say so in `body`.
|
||||
|
||||
Nothing kept (the bug did not reproduce and no guess held up): leave
|
||||
`command` out and say so in `body`.
|
||||
|
||||
A stop before the file is written ends on a finish whose `body` says nothing
|
||||
was kept (and names any throwaway script or kept test you wrote), with
|
||||
`"command": "/plan2code-diagnose"` (`console-stop.md`).
|
||||
A stop before the file is written: `body` says nothing was kept (and names any throwaway script or kept test), `"command":"/plan2code-diagnose"`.
|
||||
@@ -1,12 +1,3 @@
|
||||
# Documentation on the Web Console
|
||||
# Documentation
|
||||
|
||||
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`.
|
||||
Post each phase file as a doc as it is written, as a `file` block (`{"id":"body","file":"specs/<feature>/phase-2.md"}`) carrying its `saved` path. Pass `--spec specs/<feature>` once the folder is known. The sign-off's finish `command` is `/plan2code-3-implement specs/<feature>/overview.md`.
|
||||
@@ -1,34 +1,14 @@
|
||||
# Finalize on the Web Console
|
||||
# Finalize
|
||||
|
||||
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 |
|
||||
| Step | Card |
|
||||
| --- | --- |
|
||||
| 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 `review` item before moving anything (`doc`: Step 3's summary), verdicts `yes` ("Archive it"), `show` ("Show me it working", token `show me`) and `no`, the archive paths in `body`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). On `show`, run it as `notes/implement.md` → Show me it working says (the summary line goes into `overview.md`'s Completion Summary), then reopen the card without `show`. |
|
||||
| 1, Audit | Table as doc `audit`. If `totals.incomplete + totals.blocked > 0`, a `choice` (return, mark partial, abandon) with counts against thresholds in `body`. |
|
||||
| 2, Verification | Results as a doc; ask only on an issue. Unless Full Suite is `Never` or `At Phase N`: `confirm` "Run the full suite" (`yesLabel` "Run it", `noLabel` "Skip it", reason in `body`); a failure is the building notes' `choice`. |
|
||||
| 3, Summary | Written to `overview.md`; mirror it as a doc (`saved`, `file` block). |
|
||||
| 4, Docs review | Proposed-updates table as a doc, plus a `multi` of documents (ticked = approved); a `review` if all-or-nothing. |
|
||||
| 5, Feedback | `required:false`: rating as `choice` 1 to 10 or `text`, three reasons as `text`, maintainer consent as `confirm`. |
|
||||
| 6, Cleanup | `review` (`doc` Step 3's summary), verdicts `yes` ("Archive it"), `show` (token `show me`), `no`; archive paths in `body`, and a line that remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). On `show`, see `notes/implement.md`, then reopen without `show`. |
|
||||
|
||||
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".
|
||||
Post `activity` as each step starts. Pass `--spec specs/<feature>` or post `specDir`.
|
||||
|
||||
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`), and
|
||||
`"changelog": true` beside it, for **Update CHANGELOG first** (it hops into
|
||||
Changelog and on to Git). Both only when the finish prints a commit. The
|
||||
completion summary is printed to a terminal the browser user is not watching,
|
||||
so put it in `finish.body`.
|
||||
Finish: the completion summary goes in `body`. `command` is the suggested commit when Step 4 updates landed (`"where":"When you are happy with it, commit it from your terminal:"`, `"commit":true`, `"changelog":true`), else none. A stop loses nothing before Step 3's write: `command` `/plan2code-4-finalize specs/<feature>/overview.md`.
|
||||
@@ -1,124 +1,58 @@
|
||||
# Git on the Web Console
|
||||
# Git
|
||||
|
||||
Workflow notes for `git`, part of the web console contract (`console.md`).
|
||||
Launched from the dashboard or a hand-off: resume the session. The main column is the git board, from `state.git`. **Never post `git`** (exit 3). Your cards sit in the board's card slot.
|
||||
|
||||
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 in
|
||||
the board's card slot, under its tab strip.
|
||||
|
||||
**A click** arrives as one session action, one per send, and the board locks
|
||||
until your next post lands:
|
||||
A click arrives as one session action 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. ..." }
|
||||
{"reply":"Create feature/export-csv from origin/main.","session":[{"i":"__git","op":"create","name":"feature/export-csv","from":"origin/main","then":"commit","files":["src/a.js"],"ignore":["dist/"]}]}
|
||||
```
|
||||
|
||||
| `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 |
|
||||
| `refresh`, `pull`, `push`, `abort`, `continue`, `done` | none (`refresh` with no remote: `plan refresh` gives no commands, just post `reread`) |
|
||||
| `publish` | `remote?` (absent with several: `plan publish` asks) |
|
||||
| `switch`, `delete` | `branch` (remote-only row is `<remote>/<name>`) |
|
||||
| `create` | `name`, `from`; `then:"commit"` with `files` (and `ignore`) from the commit panel's branch offer |
|
||||
| `cleanup` | `branches[]` |
|
||||
| `commit` | `files[]` (paths and untracked folders), `ignore[]` (folders to add to `.gitignore`). `files[]` may be empty when `ignore[]` is not: the board's held-back offer (**Add … to .gitignore**). Then add the paths to `.gitignore` and commit only `.gitignore`. |
|
||||
| `pr-host` | `host`, `kind` (already saved by the page's `POST /pr-host`) |
|
||||
| `commit` | `files[]`, `ignore[]` (folders for `.gitignore`). `files[]` may be empty when `ignore[]` is not (held-back offer): add the paths to `.gitignore` and commit only `.gitignore`. |
|
||||
| `pr-host` | `host`, `kind` (already saved by `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`):
|
||||
**After an action**, 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":true,"items":[{"id":"git-result","kind":"notice","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.
|
||||
- `reread` is `true`, or `{"refreshFailed":true}` after a failed Refresh. Only with the `git` workflow, else exit 3.
|
||||
- `git-result` is one `notice` replaced every action: what happened, short hashes, the `pr-url` link after a push or publish. A failure quotes git's stderr verbatim with `classify-error`'s `next`.
|
||||
- `board.describe`: short kebab-case description of the changes still on the tree (prefills Create); leave out when none remain.
|
||||
|
||||
**Cards per `plan`.** `git.mjs plan <op>` decides whether to ask:
|
||||
**Cards per `plan`** (`git.mjs plan <op>`):
|
||||
|
||||
| `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, labeled **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. |
|
||||
| `confirm` | `confirm` with `title`, `body`, `danger`, `consequences` verbatim; named files as `files:[{"path","state"}]`. |
|
||||
| `card.kind:"switch"` | `choice` "Bring your changes?", exactly the given `options`: **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); files in `body`, `reason` when git refuses (no `bring` then). `allowOther:false`. |
|
||||
| `card.kind:"dirty"` | Same `choice`, **Commit first** / **Cancel**, `reason` in `body`. |
|
||||
| `card.kind:"remote"` | `choice` "Publish to which remote?", one option per remote, `preset` recommended; then `plan publish --remote <it>` and its `confirm`. |
|
||||
| `ask:false` | No card: run on the click. |
|
||||
| exit 4 or 5 | Nothing run: `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.
|
||||
An `auth` failure: a `notice` saying the tool never handles logins, with `next`.
|
||||
|
||||
| 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. |
|
||||
| One commit | `text` card, `placeholder` the drafted subject, `pattern` capping it at 100 characters, then `confirm` "Commit this?" with files in `consequences` and `files:[{"path","state"}]` (modified, new, deleted, renamed). No card when the subject was the argument. |
|
||||
| A split | Doc `commits` (each group's subject and files, files mixing concerns) plus `review` with verdicts `approve`, `change`, `single` ("One commit instead"). Asked even with a subject argument. |
|
||||
| Push | Not asked after a board commit (the board lights Push). `commit and push` or a Push click asks `plan push` / `plan publish`'s `confirm`. |
|
||||
| `git init` | `confirm` naming folder and first branch (`init-check`'s `branch`, `danger:false`), `consequences` its `commands`. Run those, not a bare `git init`. |
|
||||
| `.gitignore` | The proposed file, or a `commit`'s `ignore[]` lines, as a doc plus `review`. |
|
||||
|
||||
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"`.
|
||||
Risky files (`sensitive`, `large`) go in the card's `body`. There is no branch-offer card: the commit panel's **You're on main** asks, answered 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").
|
||||
**Conflict help.** A pull, rebase or merge stopped on conflicts: `choice` "Resolve them for me?": **Yes**, **I'll fix it**, **Abort pull**. On yes, each stop is doc `conflict` (replaced per stop: step N of M, the commit replayed, each file with a one-line reason, per-file diff) plus a `review` with a fresh id per stop, `"nothingYet":false`, verdicts `continue`, `change`, `abort` ("Abort pull", `danger`). Only **Continue** runs `plan continue`'s commands; **Abort pull** runs `plan abort`. A file you cannot resolve confidently keeps its markers, as does **I'll fix it**. A `continue` click from the board's banner means the files are fixed: run `plan continue`; on exit 5 (markers left) post a `reread` with its `message` as the `git-result`. End with 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.
|
||||
**Meter.** Post `run:{"event":"git-commits","id":"<first short hash>","commits":N}` after each commit step, and `run:{"event":"git-conflict","id":"conflict-<n>"}` once per conflict help.
|
||||
|
||||
**Finishing** (`console-finish.md`). **Done with git** (`op: "done"`). A `done`
|
||||
that arrives while one of your cards is still open is the person canceling it:
|
||||
record that card as canceled (`{ "items": [{ "id": "<id>", "status":
|
||||
"answered", "answer": { "text": "Canceled by Done with git" } }] }`, not
|
||||
`settle`, which refuses a card nothing was sent to) in the same post as the
|
||||
finish, or, with nothing done, before resuming as the dashboard. Never run what
|
||||
the card was asking for. 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`.
|
||||
**Finishing.** **Done with git** is `op:"done"`. A `done` while one of your cards is open cancels it: record it `{"items":[{"id":"<id>","status":"answered","answer":{"text":"Canceled by Done with git"}}]}` (not `settle`) in the finish post, or, with nothing done, before resuming as the dashboard. Never run what that card asked. Something done: `finish` with a headline and the commits (hashes), pushes and branches created or deleted in `body`, no `command`, `"dashboard":true`. Nothing done: no finish screen; resume as `dashboard` (`open --resume <sid> --no-open --workflow dashboard`), read `~/.agents/skills/plan2code/SKILL.md`, post its `menu` with `--wait`, carry on from "Coming back from another skill". A stop's finish is a pause, "Paused ...", bare `/plan2code-git`.
|
||||
@@ -1,11 +1,3 @@
|
||||
# Handoff on the Web Console
|
||||
# Handoff
|
||||
|
||||
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 lives in `~/.plan2code/handoffs/`, outside the project,
|
||||
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`).
|
||||
One gate (next-task confirmation), then the document as a doc with `md`, no `saved` (the file lives outside the project, where a `file` block is refused). The finish has no `command`; unless it is a pause it carries `"dashboard":true`.
|
||||
@@ -1,193 +1,63 @@
|
||||
# Implement on the Web Console
|
||||
# Implement
|
||||
|
||||
Workflow notes for `implement` and `implement-review`, part of the web console
|
||||
contract (`console.md`). Read `building.md` first.
|
||||
`implement` and `implement-review`. Read `building.md` first.
|
||||
|
||||
## The first post of a phase
|
||||
## 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 }
|
||||
}
|
||||
{"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.
|
||||
`phase` is the task list, `phasefile` the whole file. A later phase posts the same two docs with the new title and file.
|
||||
|
||||
## After every task
|
||||
|
||||
In the same breath as writing the task's checkbox to disk:
|
||||
With the checkbox write:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"headline": { "cleared": 4 },
|
||||
"docs": [ { "id": "phase", "refresh": true }, { "id": "phasefile", "refresh": true } ],
|
||||
"agent": { "activity": "Task 5 of 9: the rate limiter" }
|
||||
}
|
||||
{"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).
|
||||
|
||||
---
|
||||
The Phase Completion Summary lands in `phasefile` the same way. Then the `chat` check.
|
||||
|
||||
## 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:
|
||||
Loop mode (`notes/loop.md`) posts `loopOutcome` instead. Otherwise the Completion Report is a doc and the approval a `review` pointing at it; the review offer is a verdict here, not on the finish:
|
||||
|
||||
```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, see it running, or say what to change.",
|
||||
"verdicts": [
|
||||
{ "id": "review", "label": "Review the code first" },
|
||||
{ "id": "approve", "label": "Approve this phase" },
|
||||
{ "id": "show", "label": "Show me it working" },
|
||||
{ "id": "changes", "label": "I want changes" }
|
||||
],
|
||||
"token": { "approve": "approved", "changes": "needs changes", "show": "show me" },
|
||||
"nothingYet": "Nothing is marked complete until you approve.",
|
||||
"gate": { "id": "signoff", "authoritative": true }
|
||||
}]
|
||||
}
|
||||
{"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, see it running, or say what to change.","verdicts":[{"id":"review","label":"Review the code first"},{"id":"approve","label":"Approve this phase"},{"id":"show","label":"Show me it working"},{"id":"changes","label":"I want changes"}],"token":{"approve":"approved","changes":"needs changes","show":"show me"},"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`. `show` is the terminal's `show me`: see below.
|
||||
Posted with `--wait`. An approval whose note asks for a change: do the change first and ask again. `changes`: address it, update the report, reopen the item with a `thread` reply. `review`: read `building-review.md`. `show`: below.
|
||||
|
||||
A later phase in the same session asks with a new id (`signoff-phase-2`, title "Approve Phase 2"); the old card is a record.
|
||||
|
||||
### Show me it working
|
||||
|
||||
On `show`, run the workflow's **Show me it working** paragraph (start the app,
|
||||
look at the change, stop it, one summary line in `phase-X.md`). Save each
|
||||
screenshot under the session's `shots/` folder, never under `specs/`, and post
|
||||
them as image blocks in a `shown` doc (`console.md` → Documents), with what was
|
||||
run in a `md` block above them; no browser tool means that block alone says
|
||||
what the command printed. Then reopen the same card (`"status": "reopened"`)
|
||||
without the `show` verdict, a `thread` reply naming what was seen. The same
|
||||
holds on Finalize's card and the one `building-review.md` reopens; Quick
|
||||
Task's card is settled instead (`notes/quick-task.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.
|
||||
|
||||
---
|
||||
On `show`, run the workflow's **Show me it working** paragraph. Save screenshots under the session's `shots/`, never `specs/`, and post them as image blocks in a `shown` doc with what was run in a `md` block above (no browser tool: that block alone says what the command printed). Then reopen the same card without the `show` verdict, with a `thread` reply naming what was seen. Same on Finalize's card and the one `building-review.md` reopens; Quick Task's card is settled instead.
|
||||
|
||||
## 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`:
|
||||
Do what the workflow does on approval and print it in the terminal as usual, then:
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
{"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.
|
||||
`commit:true` only when the body prints a commit. `command` is the next step: `/plan2code-3-implement specs/<feature>/overview.md`, or `/plan2code-4-finalize specs/<feature>/overview.md` after the last phase. No `review` on the finish.
|
||||
|
||||
`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`).
|
||||
|
||||
---
|
||||
`run` takes over what `cleared` counted, never adds: `implement-phase` (Implement) or `implement-review-phase` (Implement + Review), id `phase-N`, `tasks` the completed ones (`[x]`, not `[!]`); without `tasks` every phase weighs the same.
|
||||
|
||||
## Manual check-off (`next.action` is `checkoff`)
|
||||
|
||||
No phase to build: the open tasks under approved phases are asked about one
|
||||
at a time, one `confirm` item each, posted with `--wait`:
|
||||
Open tasks under approved phases, one `confirm` each, `--wait`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"headline": { "stage": "Manual check-off", "cleared": 0, "total": 2 },
|
||||
"items": [{
|
||||
"id": "checkoff-3.4", "kind": "confirm", "title": "Task 3.4",
|
||||
"body": "**Configure the SSO app in Okta**\n\nBLOCKED: needs admin access. User action: create the app and paste its client id into `.env`.\n\nIs this done?",
|
||||
"yesLabel": "Done, check it off", "noLabel": "Not yet"
|
||||
}]
|
||||
}
|
||||
{"headline":{"stage":"Manual check-off","cleared":0,"total":2},"items":[{"id":"checkoff-3.4","kind":"confirm","title":"Task 3.4","body":"**Configure the SSO app in Okta**\n\nBLOCKED: needs admin access.\n\nIs this done?","yesLabel":"Done, check it off","noLabel":"Not yet"}]}
|
||||
```
|
||||
|
||||
`yes` → `specs.mjs tick`, then `"headline": { "cleared": N }` with the next
|
||||
item. When the last one is answered, post the finish: `command` is
|
||||
`/plan2code-4-finalize specs/<feature>/overview.md` when `tick` said
|
||||
`remaining` is empty, otherwise the same `/plan2code-3-implement` command,
|
||||
and `body` lists what is still open. No `run` (nothing was built), no
|
||||
`commit` unless a body prints one.
|
||||
|
||||
---
|
||||
Yes: `specs.mjs tick`, `{"headline":{"cleared":N}}` with the next item. After the last: finish with `command` `/plan2code-4-finalize specs/<feature>/overview.md` when `tick` said `remaining` is empty, else `/plan2code-3-implement ...`; `body` lists what is open. No `run`, no `commit` unless the body prints one.
|
||||
|
||||
## 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 (`show` included) **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.
|
||||
Stage 2 publishes findings as in `building-review.md` (The findings). Stage 3 has no "Check the fixes" item. The post starting Stage 2 carries `"run":{"event":"review","id":"review"}` (scores 1 point; the final `run` leaves it out). Stage 4 is the sign-off above, `show` included, without the `review` verdict, with review results and unresolved findings in the report and "Reviewed and ready for sign-off" in `body`. Its finish `run` is `implement-review-phase`.
|
||||
@@ -1,14 +1,3 @@
|
||||
# Init and Init Update on the Web Console
|
||||
# Init and Init Update
|
||||
|
||||
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.
|
||||
Post the finished AGENTS.md as a doc (`"saved":"AGENTS.md"` or a `file` block). A completed run finishes with no `command`; a stop's is the bare `/plan2code-init` or `/plan2code-init-update`.
|
||||
@@ -0,0 +1,168 @@
|
||||
# Loop Mode on the Web Console
|
||||
|
||||
Workflow notes for Implement and Implement + Review started by the desktop app's
|
||||
Implementation Loop with `--loop`, part of the web console contract
|
||||
(`console.md`). Read `building.md` and `notes/implement.md` first: this note says
|
||||
only where loop mode differs. The app judges the result, so you report and never
|
||||
approve.
|
||||
|
||||
## Flags
|
||||
|
||||
- `--loop`: this run is one phase of an unattended loop. The skill's first step
|
||||
already ran a plain `open`; run it again now, before any post, as
|
||||
`node "<CONSOLE>" open --workflow <implement|implement-review> --spec specs/<feature> --loop`.
|
||||
Inside the app it resumes the app's session and locks the page; without it,
|
||||
`loopOutcome` and `handledBy` are refused. If it exits 3, the run is not inside
|
||||
the app: say "Loop mode runs only inside the Plan2Code desktop app." in the
|
||||
terminal and continue as an ordinary run with the person's sign-off. Skip
|
||||
nothing below unless that `open` succeeded.
|
||||
- `--fix <levels>`: a comma list from `critical`, `warning`, `suggestion`, the
|
||||
levels to fix in the one fix round. Absent means findings are reported, not
|
||||
fixed.
|
||||
- `--fix smart`: Smart pick. A triage step chooses which findings to fix, in
|
||||
place of a level list (see Triage). The one fix round and the fresh re-check
|
||||
are unchanged.
|
||||
- `--guess`: when a task needs a decision the spec does not make, take the best
|
||||
guess, mark the task `[?]` with a one-line note as an indented line right under
|
||||
it in the phase file (` - Assumed: what you chose and why`), and carry on. The
|
||||
app copies that note into the person's report. Without `--guess`, ask the question as an ordinary open card
|
||||
(see Questions and cards).
|
||||
|
||||
## What changes in loop mode
|
||||
|
||||
- Pick the phase without asking (Choosing the phase).
|
||||
- No sign-off card, no "Approve this phase", no Show me it working, no Continue
|
||||
offer.
|
||||
- Never run `specs.mjs mark --to done`, and never set `[x]` on the phase in
|
||||
`overview.md`. Tasks inside the phase file are still checked off as they
|
||||
finish: `[x]`, `[!]` when blocked, `[?]` when assumed.
|
||||
- Never run `git` in any form (no add, commit, stash, checkout), and never
|
||||
`commit-msg.mjs`.
|
||||
- No Stop-with-handoff, no `__dashboard`, no finish screen: the app ends the
|
||||
session.
|
||||
- Where the prompt would stop and ask, report instead of posting a card:
|
||||
- A spec conflict: list it in `conflicts`, report `failed`, reason `conflict`.
|
||||
- A blocked prerequisite or task: mark the task `[!]`, list it in
|
||||
`tasks.blocked`, report `failed`, reason `blocked`.
|
||||
- Failing tests: try one fix, then report `tests.passed: false`, `failed`,
|
||||
reason `tests`. Never post the Fix now, Document or Investigate options.
|
||||
- A waiting `**Plan change:**` line in the phase's Notes: do not ask Revise
|
||||
first or Resume; report `failed`, reason `other`, and say so in `summary`.
|
||||
- Run only the tests the phase file names, as the Implement prompt's tests rule
|
||||
says: a phase task or a task's `Test:` line (a `## Phase Testing` block counts
|
||||
when it lists them as tasks). Never the full suite unless the phase file names it.
|
||||
|
||||
## Headline stages
|
||||
|
||||
Post `headline.stage` as each begins, using only these words: `Build`, `Review`,
|
||||
`Fixes`, `Re-check`, `Reporting`. The app's strip reads them, and any other word
|
||||
shows as Build, so do not invent new ones in loop mode. Keep `cleared` and
|
||||
`total` as in any build.
|
||||
|
||||
## Choosing the phase
|
||||
|
||||
Run `node "<S>/specs.mjs" status specs/<feature>`. A phase whose checklist marker
|
||||
is `[/]` goes first; otherwise take `next.phase.number` (the first of
|
||||
`next.options` when `next.action` is `choose`). Never post the "Resume?" question
|
||||
or the parallel-phase pick. Set the phase in progress with
|
||||
`specs.mjs mark <spec> --phase N --to in-progress`, exactly as an ordinary run
|
||||
does: that mark is allowed, and only `--to done` is the app's. When `next.action`
|
||||
is `none` or `checkoff` (no open phase), post a `loopOutcome` with
|
||||
`result: "failed"`, `reason: "other"` and
|
||||
`summary: "No open phase left in this spec"`.
|
||||
|
||||
## Questions and cards the loop handles
|
||||
|
||||
- A real question (a decision the spec does not make, without `--guess`) is an
|
||||
ordinary open card, waited on with `post --wait` as usual. The app sees it open
|
||||
and holds or stops the loop. Do not mark it `handledBy`.
|
||||
- The review stage's findings pick and the fix confirmation are answered by this
|
||||
run itself from `--fix` (with `--fix smart`, from the triage). Post them for the record as settled items with
|
||||
`"handledBy": "loop"` and the answer filled in, so the page shows "The loop
|
||||
handles this", for example
|
||||
`{ "id": "fixes", "kind": "multi", "title": "Which to fix", "options": [ ... ], "status": "answered", "answer": { "ks": ["1", "2"] }, "handledBy": "loop" }`.
|
||||
- Ask (chat) questions do not arrive while the loop drives. If one does, answer
|
||||
it briefly as usual.
|
||||
|
||||
## Review, one fix round and the re-check
|
||||
|
||||
Implement + Review only. Run the review as `building-review.md` describes. Fix
|
||||
only the findings at the `--fix` levels, in one round. Then start one fresh
|
||||
reviewer helper (a new subagent with no memory of the fix round, or a fresh read
|
||||
when helpers are off) that re-checks only the fixes: each finding at a chosen
|
||||
level is fixed, and nothing new was introduced. Count what is left, by level,
|
||||
after the re-check. Suggestions left or newly found on the re-check are listed
|
||||
but never fail the phase. Do not run a second fix round.
|
||||
|
||||
## Triage (`--fix smart`)
|
||||
|
||||
Implement + Review only, after the review lists its findings and before the fix
|
||||
round. Start one fresh triage helper (a new subagent with no memory of the build
|
||||
or the review, or a fresh read when helpers are off). Its brief holds the
|
||||
findings, the phase's tasks in `phase-X.md` and the project's `AGENTS.md`. For
|
||||
each finding it answers `fix` or `skip` with one line of reason, at most 200
|
||||
characters. Skip is for a finding that is not real once the code is read, is
|
||||
outside this phase's tasks, contradicts `AGENTS.md` or the spec, or asks for a
|
||||
change out of proportion to the gain. Every skip carries a reason.
|
||||
|
||||
The app stops the phase on any skipped Critical, so the triage must not skip a
|
||||
Critical it merely dislikes: skip one only when it is plainly not a defect, and
|
||||
say why. Post the triage's answers for the record as the settled `fixes` item (its `ks` are the findings marked `fix`, posted before the fix round)
|
||||
(`handledBy: "loop"`), with one `thread` entry per skip carrying its reason.
|
||||
|
||||
Then run the one fix round on the findings marked `fix`, and the fresh re-check
|
||||
of only those fixes, as above. `left` counts the picked findings still open after
|
||||
the re-check. Smart pick always reports `triage.ran: true` and `review.recheck: true`, even when no finding was raised or none was picked (an empty re-check). The triage runs under the `Review` stage; the stage words do not
|
||||
change.
|
||||
|
||||
## Reporting the outcome
|
||||
|
||||
At the end of the run, post once a top-level `loopOutcome`:
|
||||
|
||||
```json
|
||||
{ "loopOutcome": {
|
||||
"phase": 2, "result": "passed", "reason": null,
|
||||
"summary": "Built the setup screen; 6 of 6 tasks",
|
||||
"tests": { "ran": true, "passed": true, "summary": "14 pass" },
|
||||
"decisions": ["Kept the old /votes route so existing callers still work"],
|
||||
"review": { "ran": true, "recheck": true,
|
||||
"fixed": [ { "level": "warning", "title": "Close the file handle", "file": "src/z.js" } ],
|
||||
"triage": { "ran": true, "skipped": [ { "level": "warning", "title": "Rename the helper", "file": "src/y.js", "reason": "Outside this phase's tasks" } ] },
|
||||
"left": { "critical": 0, "warning": 0, "suggestion": 2 },
|
||||
"unfixed": [ { "level": "suggestion", "title": "Name the timer", "file": "src/x.js" } ] },
|
||||
"tasks": { "blocked": [], "assumed": ["2.4"] },
|
||||
"conflicts": [],
|
||||
"subject": "Add the loop setup screen" } }
|
||||
```
|
||||
|
||||
- `result` is `"passed"` only when every task is `[x]` (or `[?]` with `--guess`),
|
||||
the named tests pass, and, with review, no Critical or Warning is left at a
|
||||
chosen level (every level in Smart pick) after the re-check, and, in Smart pick,
|
||||
the triage skipped no Critical (otherwise `failed`, reason `findings`). Otherwise `"failed"`, with the first matching
|
||||
`reason`: `tests`, `findings`, `blocked`, `conflict` or `other`. A passed
|
||||
outcome has `"reason": null`.
|
||||
- `review.triage` is present only with `--fix smart`: `ran: true` and `skipped` listing
|
||||
every skipped finding with its reason (an empty list when nothing was skipped).
|
||||
A picked Critical or Warning still left after the re-check fails the phase with
|
||||
reason `findings`. `unfixed` lists only picked findings still open after the
|
||||
re-check; skipped findings go only in `triage.skipped` (the app adds them to the
|
||||
summary), and the 50-entry limits of the two lists are separate.
|
||||
- `review.fixed` lists every finding the fix round fixed (an empty list when none,
|
||||
or with no review), at most 50.
|
||||
- `decisions` lists, at most 50, one line of at most 200 characters each, every
|
||||
other judgment call this run made on the person's behalf that the spec did not
|
||||
settle and the `Assumed:` notes do not already cover: a library or approach
|
||||
chosen between real options, scope left out or added, a behavior changed outside
|
||||
the task. The person reads these to check the work, so say what you chose and
|
||||
why, and leave nothing out because it seems small. Do not list the routine steps
|
||||
of building. An empty list means you made none.
|
||||
- `review.ran` and `review.recheck` are `false` when the run did no review or no
|
||||
re-check (plain Implement, or no `--fix` level; never with `--fix smart`). `tasks.blocked` and
|
||||
`tasks.assumed` list task ids like `"2.4"`. `conflicts` holds one line per
|
||||
spec conflict.
|
||||
- `subject` is one imperative line under 100 characters saying what changed (it
|
||||
becomes the commit subject). `summary` is one line under 200 characters.
|
||||
|
||||
Then post `{"agent":{"status":"waiting"}}` and keep waiting with the usual
|
||||
bounded `wait` slices until the app ends the session. Never end the turn on text.
|
||||
If the post is refused (exit 3), fix the field it names and post again.
|
||||
@@ -1,77 +1,26 @@
|
||||
# Pathfinder on the Web Console
|
||||
# Pathfinder
|
||||
|
||||
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 menu after a decision is a `menu` card: its `options` are `trail --form C`'s, and the `Start fresh` one keeps its `"fresh": true` (the page words it "Start New Session" under the desktop app and asks the app for one on Send). Set the card's `command` to the resume command printed under `OR START FRESH`: the page copies it first. A declined confirm leaves you the pick: carry on as for any `Start fresh`.
|
||||
- The fresh-idea card carries `"templates": "idea"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
|
||||
- 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.
|
||||
- Post `"stopWarning"` while no map exists (Steps 0 to 4), `""` once it does, and `"specDir":"specs/<idea>"` when the folder is created.
|
||||
- The menu after a decision is a `menu` card: `options` are `trail --form C`'s, the `Start fresh` one keeps `"fresh":true`. Set the card's `command` to the resume command printed under `OR START FRESH`. A declined confirm leaves you the pick: carry on as for `Start fresh`.
|
||||
- The fresh-idea card carries `"templates":"idea"`, `"fill":"note"`.
|
||||
- A doc that is a file as written (the map, a brief) is a `file` block (`{"id":"body","file":"specs/<idea>/pathfinder/map.md"}`). Keep `md` where `assumed` / `draft` state matters.
|
||||
- Step 8 research subagents all report before the finish; the finish `body` names what each found. Report every one as a helper, whatever the Subagents switch says.
|
||||
- Every session end `finish`es with Form A's command as `command`.
|
||||
- Post `run` `pathfinder-chart` (id `map`) when a map is first written, and `pathfinder-research` (id the question's file slug; on `github`, `q<issue-number>`) as each research subagent reports or when you resolve a `research` question yourself. Other questions score through answers.
|
||||
- The scope probe is **Leave for later**: "Which of these features are we leaving out this time?" as a `multi` with a recommended preset. Each option names a feature, 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:
|
||||
The page shows **Write a brief** for this workflow. It arrives as a send:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "submit",
|
||||
"actions": [{ "i": "__brief", "type": "brief", "range": "since 2026-09-15" }],
|
||||
"reply": "Write a brief covering everything since 2026-09-15."
|
||||
}
|
||||
{"reply":"Write a brief covering everything since 2026-09-15.","session":[{"i":"__brief","range":"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:
|
||||
`range` is `today`, `this week`, `since <YYYY-MM-DD>` or `full`. `__brief` matches no item. Run your brief procedure, write the file, then post it as one `file` block in doc `brief` (reused, so a second replaces the first; Save as HTML appears only on that id):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"docs": [{
|
||||
"id": "brief",
|
||||
"title": "Brief",
|
||||
"note": "Covers this week",
|
||||
"blocks": [{ "id": "body", "file": "specs/<idea>/pathfinder/briefs/<the brief>.md" }]
|
||||
}]
|
||||
}
|
||||
{"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.
|
||||
Say in chat where the file went.
|
||||
@@ -1,22 +1,6 @@
|
||||
# Planning on the Web Console
|
||||
# Planning
|
||||
|
||||
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"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
|
||||
- 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.
|
||||
- Plan offers the Subagents switch. A `Subagents:` block may arrive on `open`
|
||||
output or a `wait` / `chat` pickup: follow `console-subagents.md` and the
|
||||
skill's Helpers section, and report each helper as `helpers`. Post a helper
|
||||
as `done` or `failed` before the sign-off it feeds, and every one before a
|
||||
`finish`. Questions, sign-offs and the PLAN-DRAFT stay with you.
|
||||
- Phase breakdowns are an editable `list`. The fresh-idea card carries `"templates":"idea"`, `"fill":"note"`.
|
||||
- Nothing is saved before the Large checkpoint or Phase 7: a stop before then has `finish.body` say nothing was kept, `"command":"/plan2code-1-plan"`. After the checkpoint post `"stopWarning":""`.
|
||||
- Completion finish `command`: `/plan2code-2-document`. The Large checkpoint finish is a pause: headline starts "Paused", `command` `/plan2code-1-plan`, no `dashboard`.
|
||||
- Helpers are reported as `helpers`, each `done` or `failed` before the sign-off it feeds. Questions, sign-offs and the PLAN-DRAFT stay with you.
|
||||
@@ -1,106 +1,34 @@
|
||||
# Quick Task on the Web Console
|
||||
# Quick Task
|
||||
|
||||
Workflow notes for `quick-task`, part of the web console contract
|
||||
(`console.md`). Read `building.md` first.
|
||||
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"` and `"fill": "note"` (`console.md` → The kinds): the page fills that box from a Notebook tab when the person started with one.
|
||||
- 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`):
|
||||
- Clarifying questions are `text` or `choice`. The first (what to build) carries `"templates":"idea"`, `"fill":"note"`.
|
||||
- Post `"stopWarning":"A quick task saves nothing until it is built, so stopping now loses what we have worked out."` at the start and `""` once the build is under way.
|
||||
- **Scope check:** `choice` "Too big for a quick task?": `1` Continue (lightweight format), `2` Escalate to a full plan; measured counts against thresholds in `body`.
|
||||
- **Feature name** (escalating): `text`, `"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"`, kebab-case placeholder.
|
||||
- **The plan:** doc `plan`, one block per section, Steps as a checklist, plus `review` "Build this plan?" (`"doc":"plan"`) with verdicts `yes` ("Build it"), `modify` ("Change the plan"), `escalate` ("Plan it properly instead"), `abort` ("Stop here", `danger`):
|
||||
|
||||
```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- [ ] ..." }
|
||||
]}
|
||||
{"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"},{"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:
|
||||
A `modify` reposts the changed blocks.
|
||||
- **Building** after `yes`: the Plan tab is the live task list; steps are the tasks. Settle the verdict in the post that starts it:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"stopWarning": "",
|
||||
"settle": true,
|
||||
"headline": { "stage": "Building", "cleared": 0, "total": 4 },
|
||||
"agent": { "status": "working", "activity": "Task 1 of 4: step one", "quietMinutes": 10 }
|
||||
}
|
||||
{"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`:
|
||||
After each step (`building.md` → While you build), repost the `steps` block alone, as `md` since the plan lives only on the page:
|
||||
|
||||
```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" }
|
||||
}
|
||||
{"headline":{"cleared":1},"docs":[{"id":"plan","blocks":[{"id":"steps","state":"settled","md":"## Steps\n\n- [x] **1.** Step one\n- [ ] **2.** Step two"}]}],"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.
|
||||
- **See it running, before the finish:** a finished screen freezes every open
|
||||
card, so ask first. Once the build is done, post a `review` item "See it
|
||||
running" (`"doc": "plan"`, verdicts `show` ("Show me it working") and `fine`
|
||||
("No need, finish up"), token `show me` / `no`) with `--wait`. On `show`, run
|
||||
it as `notes/implement.md` → Show me it working says, its one line going into
|
||||
the work summary (the finish's `body`); then, or on `fine`, settle the card in
|
||||
the same post as the finish.
|
||||
- **Archive a fixed bug, before the finish:** launched on a diagnosed folder
|
||||
and now Fixed with nothing past the diagnosis, post a `confirm` card
|
||||
"Archive this bug?" in the same post as "See it running": the dry run's
|
||||
`files` in `body`, `yesLabel` "Archive it", `noLabel` "Keep it in specs/",
|
||||
and `consequences` naming `specs--completed/<bug>/`. On yes, run
|
||||
`node "<S>/specs.mjs" archive <spec>` (the skill file says where `<S>` is),
|
||||
and say where it went in the finish's `body`. On no, the
|
||||
dashboard lists the folder as "Bug fixed", never pre-selected.
|
||||
- **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`), `"changelog": true` (**Update CHANGELOG first**, beside
|
||||
it; it hops into Changelog and on to Git) 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.
|
||||
A step that cannot be done is `- [!]` with the reason, not counted in `cleared`. A step added mid-build raises `headline.total` in the same post. Tick Verify boxes in the post that reports the checks. Do not `wait` until the build is done.
|
||||
- **See it running, before the finish:** once built, post `review` "See it running" (`"doc":"plan"`, verdicts `show` ("Show me it working"), `fine` ("No need, finish up"), tokens `show me` / `no`) with `--wait`. On `show`, see `notes/implement.md` → Show me it working; its one line goes in the finish `body`. Settle the card in the finish post.
|
||||
- **Archive a fixed bug:** launched on a diagnosed folder and now Fixed with nothing past the diagnosis, post `confirm` "Archive this bug?" in the same post as "See it running": dry run's `files` in `body`, `yesLabel` "Archive it", `noLabel` "Keep it in specs/", `consequences` naming `specs--completed/<bug>/`. Yes: `node "<S>/specs.mjs" archive <spec>`, and say where it went in the finish `body`.
|
||||
- **Finish after the build:** `command` is the filled-in commit command in the project's format (AGENTS.md), `"where":"When you are happy with it, commit it from your terminal:"`, with `review` (**Review it now**), `"commit":true`, `"changelog":true` and `"dashboard":true`. Review and dashboard are required. Whichever button is pressed, what follows is `building-review.md`.
|
||||
- **Escalated / aborted:** settle the verdict in the finish post: `"command":"/plan2code-1-plan"` with the PLAN-DRAFT's path in `body`, no review; or `"command":"/plan2code-quick-task"`. Both `"dashboard":true`.
|
||||
|
||||
## Stop requests during a build
|
||||
|
||||
See `building.md` → Stop requests during a build.
|
||||
Stop requests during a build: `building.md`.
|
||||
@@ -1,34 +1,9 @@
|
||||
# Review on the Web Console
|
||||
# Review
|
||||
|
||||
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.
|
||||
Standalone with nothing named: first a `choice` "What should I review?" from a quick scan (branch changes, uncommitted changes, specs, files you name; each with its size). A build's review skips it. Launched from the dashboard: `open --resume <sid> --no-open --workflow review`. Post `activity` while you read.
|
||||
|
||||
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.
|
||||
Findings are doc `report`; the fix menu is a `multi` or `choice` keyed by finding id with `"doc":"report"`, settled (`"settle":true`) in the post that takes the picks up.
|
||||
|
||||
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`.
|
||||
Closing gate: `review` "Check the fixes", `"doc":"report"`, `"nothingYet":false`, verdicts `approve`, `changes`.
|
||||
|
||||
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).
|
||||
Completion finish: `command` is the suggested commit when fixes landed (AGENTS.md format, `"where":"When you are happy with it, commit it from your terminal:"`, `"commit":true`), else none; `"dashboard":true`. A stop's `command` is the bare `/plan2code-review`, no dashboard.
|
||||
@@ -1,26 +1,12 @@
|
||||
# Revision on the Web Console
|
||||
# Revision
|
||||
|
||||
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 |
|
||||
| Step | Card |
|
||||
| --- | --- |
|
||||
| 1, Change Analysis | A `recap` item, "Is this the change?", with the affected-areas table in `summary`. Found a waiting `**Plan change:**` brief? Quote it at the top of that `summary` and post no open "what should change" card first. With none waiting, the first card is a `text` item titled "What should change", `"fill": "note"`, asking what to change; its answer feeds the "Is this the change?" recap. |
|
||||
| 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`. |
|
||||
| 1, Change Analysis | `recap` "Is this the change?", affected-areas table in `summary`. A waiting `**Plan change:**` brief is quoted atop `summary` and no "what should change" card goes first; with none, the first card is `text` "What should change", `"fill":"note"`. |
|
||||
| 2, Impact | Doc `impact`, plus `review` "Approve the spec changes": verdicts `approve`, `refine`, `abort` (`danger`), `nothingYet` "No spec file changes until you approve." |
|
||||
| 3 to 5 | Nothing to ask: `activity` while you edit, then the Revision Complete summary as a doc. |
|
||||
| 6, Cleanup | `confirm` per rename or removal, 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`.
|
||||
No option, verdict, label, or helper `title`, `ask` or `result` ever offers to execute or implement. Pass `--spec specs/<feature>` to `open` or post `specDir`. Finish `command`: `/plan2code-3-implement specs/<feature>/overview.md`; abort: `/plan2code-1b-revise-plan specs/<feature>/overview.md`.
|
||||
|
||||
Revision offers the Subagents switch. A `Subagents:` block may arrive on
|
||||
`open` output or a `wait` / `chat` pickup: follow `console-subagents.md` and
|
||||
the skill's Helpers section, and report each helper as `helpers`. Lookup
|
||||
helpers report back before the Step 2 review item goes up; phase-file helpers
|
||||
report back before the Step 4 check. Every gate stays with you, and a helper's
|
||||
`title`, `ask` and `result` follow the same rule as every label: nothing
|
||||
offers to execute or implement.
|
||||
Helpers: lookup helpers report before the Step 2 review goes up; phase-file helpers before the Step 4 check.
|
||||
@@ -1,73 +1,37 @@
|
||||
# X-ray on the Web Console
|
||||
|
||||
Workflow notes for `xray`, part of the web console contract (`console.md`).
|
||||
# X-ray
|
||||
|
||||
## The mode question
|
||||
|
||||
A typed argument that names the mode and area skips it. Otherwise ask both in
|
||||
one batch, posted with `--wait`:
|
||||
An argument naming mode and area skips it. Otherwise one `--wait` batch:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"title": "Codebase X-ray",
|
||||
"headline": { "stage": "Choosing", "cleared": 0, "total": 2 },
|
||||
"items": [
|
||||
{ "id": "mode", "kind": "choice", "title": "What you want to know", "allowOther": false,
|
||||
"body": "Explain one area, or rank what makes this code hard to change.",
|
||||
"options": [
|
||||
{ "k": "1", "text": "Explain an area", "detail": "How it works and why it is that way, citing files and the commits behind it." },
|
||||
{ "k": "2", "text": "Find the rough spots", "detail": "Ranked spots that make change hard. You pick the ones worth fixing; they become a brief for Pathfinder or Plan." }
|
||||
] },
|
||||
{ "id": "area", "kind": "text", "title": "Which area", "required": false,
|
||||
"body": "A folder, file or feature. Needed to explain; leave it empty to survey the whole repository.",
|
||||
"placeholder": "src/exporter, the code that builds the CSV reports" }
|
||||
]
|
||||
}
|
||||
{"title":"Codebase X-ray","headline":{"stage":"Choosing","cleared":0,"total":2},"items":[{"id":"mode","kind":"choice","title":"What you want to know","allowOther":false,"body":"Explain one area, or rank what makes this code hard to change.","options":[{"text":"Explain an area","detail":"How it works and why, citing files and commits."},{"text":"Find the rough spots","detail":"Ranked spots that make change hard. You pick the ones worth fixing; they become a brief for Pathfinder or Plan."}]},{"id":"area","kind":"text","title":"Which area","required":false,"body":"A folder, file or feature. Needed to explain; empty surveys the whole repository."}]}
|
||||
```
|
||||
|
||||
Explain picked with the area left empty: ask for it again as a required `text`
|
||||
card. No recommendation on the mode: only the person knows what they came for.
|
||||
Explain with the area empty: ask again as a required `text`.
|
||||
|
||||
## Explain mode
|
||||
|
||||
The answer is a doc, `id` `"answer"`, one block per section (`In one paragraph`,
|
||||
`How it works`, `Why it is this way`, `Worth knowing`), with the `Sources:` line
|
||||
at the top of the first. Then the save offer as a `confirm` card pointing at it:
|
||||
Doc `answer`, one block per section (`In one paragraph`, `How it works`, `Why it is this way`, `Worth knowing`), `Sources:` line atop the first. Then:
|
||||
|
||||
```jsonc
|
||||
{ "id": "keep", "kind": "confirm", "title": "Keep this answer", "doc": "answer",
|
||||
"body": "Save it as `specs/exporter/XRAY-exporter-20261016.md`, as input for Pathfinder or Plan?",
|
||||
"yesLabel": "Save it", "noLabel": "No, just reading" }
|
||||
{"id":"keep","kind":"confirm","title":"Keep this answer","doc":"answer","body":"Save it as `specs/exporter/XRAY-exporter-20261016.md`, as input for Pathfinder or Plan?","yesLabel":"Save it","noLabel":"No, just reading"}
|
||||
```
|
||||
|
||||
Ask the folder name in the same batch as a `text` card with `pattern`
|
||||
`^[a-z0-9]+(-[a-z0-9]+)*$` when it is not obvious. Once written, re-send the doc
|
||||
with `"saved": "specs/<name>/XRAY-<area-slug>-<date>.md"`.
|
||||
When the folder name is not obvious, ask it in the same batch as a `text` with `pattern` `^[a-z0-9]+(-[a-z0-9]+)*$`. Once written, re-send the doc with `"saved":"specs/<name>/XRAY-<area-slug>-<date>.md"`.
|
||||
|
||||
## Rough-spots mode
|
||||
|
||||
The ranked list is a doc, `id` `"spots"`, one block per spot (its files, why it
|
||||
hurts, the "to change X today" example). The pick is one `multi` card pointing
|
||||
at it, posted with `--wait`:
|
||||
Doc `spots`, one block per spot (files, why it hurts, the "to change X today" example). Pick, `--wait`:
|
||||
|
||||
```jsonc
|
||||
{ "id": "pick", "kind": "multi", "title": "Worth fixing", "doc": "spots", "required": false,
|
||||
"body": "Tick the spots worth fixing. Add a note for any of them in the box (\"1: the exporter part only\"). Only ticked spots go into the brief.",
|
||||
"options": [
|
||||
{ "k": "1", "text": "Exporter and its formatter always change together", "detail": "src/export.ts, src/format.ts: together in 14 of 16 commits." }
|
||||
] }
|
||||
{"id":"pick","kind":"multi","title":"Worth fixing","doc":"spots","required":false,"body":"Tick the spots worth fixing. Only ticked spots go into the brief.","options":[{"text":"Exporter and its formatter always change together"}]}
|
||||
```
|
||||
|
||||
Nothing ticked: nothing is written. Otherwise write the brief, then add it as a
|
||||
second doc with `"saved": "specs/<name>/ARCHITECTURE-BRIEF-<date>.md"` and a
|
||||
`file` block.
|
||||
Nothing ticked: nothing written. Otherwise write the brief and add it as a second doc with `"saved":"specs/<name>/ARCHITECTURE-BRIEF-<date>.md"` and a `file` block.
|
||||
|
||||
## The finish
|
||||
|
||||
`command` is `/plan2code-0-pathfinder` (big or unclear) or `/plan2code-1-plan`
|
||||
(settled), never with a placeholder; leave it out when nothing was kept. `doc`
|
||||
is the brief or the saved answer when there is one. `"dashboard": true`, then
|
||||
keep waiting for the press (`console-finish.md`).
|
||||
`command` is `/plan2code-0-pathfinder` (big or unclear) or `/plan2code-1-plan` (settled); none when nothing was kept. `doc` is the brief or saved answer. `"dashboard":true`.
|
||||
|
||||
A stop before anything was written ends on a finish whose `body` says nothing
|
||||
was kept, with `"command": "/plan2code-xray"` (`console-stop.md`).
|
||||
A stop before anything was written: `body` says nothing was kept, `"command":"/plan2code-xray"`.
|
||||
Reference in new issue
Block a user