@staff0rd/assist 0.490.3 → 0.491.0

package/README.md

@@ -120,6 +120,7 @@ Every command supports `--help` for full detail on its flags and behaviour.
   - `--refine` - Skip posting; walk through `synthesis.md` interactively and edit it in place
   - `--apply` - Skip posting; walk through each finding asking apply/skip. Applied findings are fixed in the working tree
   - `--backlog` - Skip posting; file all findings as a single bug backlog item with one phase per finding
+  - `--address-comments` - After the review posts comments and submits, start an Address Comments session (`assist review-pr-comments <n>`) for the PR. Only fires inside an assist session, and only when at least one comment was posted and the review was submitted
   - `--verbose` - Per-line log output instead of the stacked-spinner UI (automatic in CI)
 - `assist github commits <org> [--since <date>] [--top <n>] [--json]` - Report commit activity across a GitHub organisation: repos ranked by commits, top committers, and a per-repo author breakdown
 - `assist news add [url]` - Add an RSS feed URL (rendered in the sessions web News tab)
@@ -134,7 +135,7 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist backlog list [--status <type>] [-a, --all] [--all-repos] [-v]` - List backlog items with status icons (alias: `ls`; also `assist list` / `assist ls`)
 - `assist backlog add` - Add a new backlog item interactively (human CLI use only; agents must use `propose`)
 - `assist backlog add --name <n> --type <t> --desc <d> --ac <criterion...>` - Add a backlog item from CLI options
-- `assist backlog propose --json <file|->` - Create an agent-authored item from a JSON payload, previewed for approval in a web session. Used by `/draft` and `/bug`. See [docs/backlog-item-preview.md](docs/backlog-item-preview.md)
+- `assist backlog propose --json <file|-> [--confirmed]` - Create an agent-authored item from a JSON payload, previewed for approval in a web session. Outside a web session an agent invocation prints the draft and writes nothing until it is re-run with `--confirmed`; `--confirmed` is rejected in a web session, where the pane is the gate. Used by `/draft` and `/bug`. See [docs/backlog-item-preview.md](docs/backlog-item-preview.md)
 - `assist backlog show <id> [--all-commits]` - Display full detail for a backlog item (alias: `view`). Activity lists the newest 10 commits; `--all-commits` prints every commit
 - `assist backlog plan <id>` - Display the phased plan for a backlog item
 - `assist backlog update-field <id> [--name <n>] [--desc <d>] [--type <t>] [--ac <criterion...>]` - Update fields on a backlog item

package/claude/commands/bug.md

@@ -21,18 +21,9 @@ Before asking the user about existing functionality — how a feature currently
 
 Skip questions the user has already answered. Stop asking as soon as you have enough to write a clear bug report — don't over-interrogate.
 
-## Step 3: Propose the item
+## Step 3: Compose the bug report
 
-Where the review happens depends on whether this is a web session — check it once:
-
-```
-echo "${ASSIST_SESSION:-0}"
-```
-
-- **`1` (web session):** do NOT print the bug report in the terminal. Skip straight to Step 5 — `assist backlog propose` slides the item into the web UI preview pane, where the user approves it, rejects it, or leaves inline comments on specific lines. That pane is the review gate.
-- **anything else:** show the user the bug report in chat as below, iterate (Step 4), then save.
-
-Either way you compose the same content, so draft it before you call `propose`:
+Compose the bug report's content, but do not show it to the user yet and do not work out where the review should happen — `propose` decides that in Step 4 and tells you what to do next.
 
 **Name:** (concise title)
 **Type:** bug
@@ -62,13 +53,7 @@ The description renders as markdown in both the terminal (`assist backlog show`)
 **Actual:** what happens instead.
 ```
 
-## Step 4: Iterate
-
-In a web session, skip this step — the preview pane handles it.
-
-Otherwise, ask the user if they want to change anything and iterate until they confirm.
-
-## Step 5: Save
+## Step 4: Propose the item
 
 Propose the item and capture the id it prints. Use `propose`, not `assist backlog add` — `propose` is the reviewed path for an agent-authored item:
 
@@ -85,15 +70,14 @@ JSON
 
 The payload is strict JSON — an unknown key is an error. `\n` inside the `description` string is a JSON escape and becomes a real newline, which is what the markdown rendering needs.
 
-In a web session this blocks until the user decides in the preview pane, and the review can take far longer than the default command timeout. Run `propose` **as a background task** so it is never killed mid-review, and do no other work until it returns — the pending preview dies with the process, so a killed `propose` abandons the item.
+Always run `propose` **as a background task**, and do no other work until it returns. In a web session it blocks on the preview pane until the user decides, which can take far longer than the default command timeout, and the pending preview dies with the process — a killed `propose` abandons the item.
 
-When it returns:
+`propose` decides where the bug report is reviewed and prints what to do next. Follow that instruction; never inspect the environment to work it out yourself:
 
-- **Approved** — the item is created and its id is printed.
+- **Created** — the item exists and its id is printed. Continue below.
+- **Draft only** — it printed the rendered bug report, wrote nothing, and asked you to re-run with `--confirmed`. Show the rendered report in chat, ask the user if they want to change anything, and iterate until they confirm. Then re-run the same command with `--confirmed` appended to create the item.
 - **Rejected** — the command exits non-zero and prints the reason plus every inline comment with the excerpt it was left on. Do not retry verbatim: address each comment, then call `propose` again with the revised payload. Repeat until it is approved.
 
-Outside a web session the rendered item is printed and created straight away.
-
 Note the created item id from the output — you'll pass it to the done signal below.
 
 ### Associate an external tracker

package/claude/commands/draft.md

@@ -22,18 +22,9 @@ Ask 2-4 targeted questions conversationally to flesh out the idea. Focus on:
 
 Ask one question at a time. Wait for the user's response before asking the next.
 
-## Step 3: Propose the item
+## Step 3: Compose the item
 
-Where the review happens depends on whether this is a web session — check it once:
-
-```
-echo "${ASSIST_SESSION:-0}"
-```
-
-- **`1` (web session):** do NOT print the item in the terminal. Skip straight to Step 5 — `assist backlog propose` slides the whole item, plan included, into the web UI preview pane, where the user approves it, rejects it, or leaves inline comments on specific lines. That pane is the review gate.
-- **anything else:** show the user the item in chat as below, iterate (Step 4), then save.
-
-Either way you compose the same content, so draft it before you call `propose`:
+Compose the item's content, but do not show it to the user yet and do not work out where the review should happen — `propose` decides that in Step 4 and tells you what to do next.
 
 **Name:** (concise title)
 **Type:** story or bug
@@ -90,13 +81,7 @@ Keep phases small (2-4 tasks each). A typical item should have 2-3 phases.
 
 Most phases should NOT have manual checks. Only add `manualChecks` to a phase when the checks are genuinely difficult to automate (e.g. visual appearance, UX flow, hardware interaction). Do not add a final phase just for end-to-end verification — a review phase is auto-appended at runtime.
 
-## Step 4: Iterate
-
-In a web session, skip this step — the preview pane handles it.
-
-Otherwise, ask the user if they want to change anything. Iterate until they confirm.
-
-## Step 5: Save
+## Step 4: Propose the item
 
 Propose the item and capture the id it prints. Use `propose`, not `assist backlog add` plus `add-phase` — `propose` is the reviewed path for an agent-authored item, and it writes the item and every phase on a single approval:
 
@@ -117,15 +102,14 @@ JSON
 
 The payload is strict JSON — an unknown key is an error. `\n` inside the `description` string is a JSON escape and becomes a real newline, which is what the markdown rendering needs. Each phase needs at least one task; omit `manualChecks` for the phases that don't need any (most of them).
 
-In a web session this blocks until the user decides in the preview pane, and the review can take far longer than the default command timeout. Run `propose` **as a background task** so it is never killed mid-review, and do no other work until it returns — the pending preview dies with the process, so a killed `propose` abandons the item.
+Always run `propose` **as a background task**, and do no other work until it returns. In a web session it blocks on the preview pane until the user decides, which can take far longer than the default command timeout, and the pending preview dies with the process — a killed `propose` abandons the item.
 
-When it returns:
+`propose` decides where the item is reviewed and prints what to do next. Follow that instruction; never inspect the environment to work it out yourself:
 
-- **Approved** — the item and all of its phases are created, and the item id is printed.
+- **Created** — the item and all of its phases exist and the id is printed. Continue below.
+- **Draft only** — it printed the rendered item, wrote nothing, and asked you to re-run with `--confirmed`. Show the rendered item in chat, ask the user if they want to change anything, and iterate until they confirm. Then re-run the same command with `--confirmed` appended to create the item and its phases.
 - **Rejected** — the command exits non-zero and prints the reason plus every inline comment with the excerpt it was left on. Do not retry verbatim: address each comment — including ones about the plan — then call `propose` again with the revised payload. Repeat until it is approved.
 
-Outside a web session the rendered item is printed and created straight away.
-
 Note the created item id from the output — you'll pass it to the done signal below.
 
 ### Associate an external tracker