mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Sync upstream into v2.7.0: the git board skill replaces git-commit (ticket-free), and console docs and tests are split up
AI Assisted
This commit is contained in:
1 parent
6114914dd6
commit
f328406bb5
103 files changed
+17636
-9991
No files matched your search
@@ -0,0 +1,23 @@
|
||||
# Changelog on the Web Console
|
||||
|
||||
Workflow notes for `changelog`, part of the web console contract (`console.md`).
|
||||
|
||||
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 |
|
||||
| --- | --- |
|
||||
| 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?". |
|
||||
|
||||
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.
|
||||
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`.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Documentation on the Web Console
|
||||
|
||||
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`.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Finalize on the Web Console
|
||||
|
||||
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 |
|
||||
| --- | --- |
|
||||
| 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 `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
|
||||
|
||||
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".
|
||||
|
||||
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`). The
|
||||
completion summary is printed to a terminal the browser user is not watching,
|
||||
so put it in `finish.body`.
|
||||
@@ -0,0 +1,119 @@
|
||||
# Git on the Web Console
|
||||
|
||||
Workflow notes for `git`, part of the web console contract (`console.md`).
|
||||
|
||||
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 above
|
||||
the board in the usual card slot.
|
||||
|
||||
**A click** arrives as one session action, one 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. ..." }
|
||||
```
|
||||
|
||||
| `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 |
|
||||
| `cleanup` | `branches[]` |
|
||||
| `commit` | `files[]` (paths and untracked folders), `ignore[]` (folders to add to `.gitignore`) |
|
||||
| `pr-host` | `host`, `kind` (already saved by the page's `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`):
|
||||
|
||||
```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` 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.
|
||||
|
||||
**Cards per `plan`.** `git.mjs plan <op>` decides whether to ask:
|
||||
|
||||
| `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, labelled **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. |
|
||||
|
||||
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.
|
||||
|
||||
| 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. |
|
||||
|
||||
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"`.
|
||||
|
||||
**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").
|
||||
|
||||
**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.
|
||||
|
||||
**Finishing** (`console-finish.md`). Done (`op: "done"`) 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`.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Handoff on the Web Console
|
||||
|
||||
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 often sits outside the project (the OS temp folder),
|
||||
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`).
|
||||
@@ -0,0 +1,155 @@
|
||||
# Implement on the Web Console
|
||||
|
||||
Workflow notes for `implement` and `implement-review`, part of the web console
|
||||
contract (`console.md`). Read `building.md` first.
|
||||
|
||||
## The 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 }
|
||||
}
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
## After every task
|
||||
|
||||
In the same breath as writing the task's checkbox to disk:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"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).
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```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, or say what to change.",
|
||||
"verdicts": [
|
||||
{ "id": "review", "label": "Review the code first" },
|
||||
{ "id": "approve", "label": "Approve this phase" },
|
||||
{ "id": "changes", "label": "I want changes" }
|
||||
],
|
||||
"token": { "approve": "approved", "changes": "needs changes" },
|
||||
"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`.
|
||||
|
||||
`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.
|
||||
|
||||
---
|
||||
|
||||
## 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`:
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`"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.
|
||||
|
||||
`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`).
|
||||
|
||||
---
|
||||
|
||||
## 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 **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.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Init and Init Update on the Web Console
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,76 @@
|
||||
# Pathfinder on the Web Console
|
||||
|
||||
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 fresh-idea card carries `"templates": "idea"` (`console.md` → The kinds).
|
||||
- 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.
|
||||
|
||||
## 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:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "submit",
|
||||
"actions": [{ "i": "__brief", "type": "brief", "range": "since 2026-09-15" }],
|
||||
"reply": "Write a brief covering everything 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:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"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.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Planning on the Web Console
|
||||
|
||||
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"` (`console.md` → The kinds).
|
||||
- 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.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Quick Task on the Web Console
|
||||
|
||||
Workflow notes for `quick-task`, part of the web console contract
|
||||
(`console.md`). 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"` (`console.md` → The kinds).
|
||||
- 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`):
|
||||
|
||||
```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- [ ] ..." }
|
||||
]}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"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`:
|
||||
|
||||
```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" }
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
- **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`) 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.
|
||||
|
||||
## Stop requests during a build
|
||||
|
||||
See `building.md` → Stop requests during a build.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Review on the Web Console
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
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).
|
||||
@@ -0,0 +1,18 @@
|
||||
# Revision on the Web Console
|
||||
|
||||
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 |
|
||||
| --- | --- |
|
||||
| 1, Change Analysis | A `recap` item, "Is this the change?", with the affected-areas table in `summary`. |
|
||||
| 2, Impact Assessment | The Revision Impact Summary as a doc (`id: "impact"`), and a `review` item "Approve the spec changes" pointing at it: verdicts `approve` ("Approve these spec changes"), `refine` ("Refine the plan") and `abort` ("Abort", `"danger": true`), `nothingYet`: "No spec file changes until you approve." |
|
||||
| 3 to 5 | Nothing to ask. Post `activity` while you edit, then the Revision Complete summary as a doc. |
|
||||
| 6, Cleanup | A `confirm` per rename or removal, the paths in `consequences`. |
|
||||
|
||||
Revision's own rule holds on the page too: **no option, verdict or label ever
|
||||
offers to execute or implement.** Pass `--spec specs/<feature>` to `open`, or
|
||||
post `specDir` once you know it. The finish command is
|
||||
`/plan2code-3-implement specs/<feature>/overview.md`; an abort's is
|
||||
`/plan2code-1b-revise-plan specs/<feature>/overview.md`.
|
||||
Reference in new issue
Block a user