@staff0rd/assist 0.446.0 → 0.448.0

package/README.md

@@ -130,8 +130,8 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist backlog [--dir <path>]` - Open the backlog tab in the web dashboard (same as `backlog web`). `--dir` overrides the directory used to resolve the current repository's git origin
 - `assist backlog list [--status <type>] [-a, --all] [--all-repos] [-v]` - List backlog items with status icons (alias: `ls`). Defaults to the current repository's todo/in-progress items; `--all` includes done/wontdo, `--all-repos` lists items across all repositories. Also available as the top-level shortcut `assist list` / `assist ls` with the same flags
 - `assist backlog add` - Add a new backlog item interactively (prompts for type: story/bug)
-- `assist backlog add --name <n> --type <t> --desc <d> --ac <criterion...>` - Add a backlog item from CLI options (used by `/draft`)
-- `assist backlog propose --json <file|->` - Review a complete agent-authored backlog item before it is created, from a JSON payload read from a file or stdin (`name`, `type`, `description`, `acceptanceCriteria`). In a web session it slides the rendered item into the preview pane and blocks: approval writes the item (including a bug's default `Fix` phase and any configured sub-tasks) and prints its id, while rejection exits non-zero with the reviewer's reason and each inline comment so the caller can revise and re-propose. Outside a web session it prints the rendered item and creates it. Used by `/bug`; the payload is strict, so an unknown key is an error. See [docs/backlog-item-preview.md](docs/backlog-item-preview.md)
+- `assist backlog add --name <n> --type <t> --desc <d> --ac <criterion...>` - Add a backlog item from CLI options
+- `assist backlog propose --json <file|->` - Review a complete agent-authored backlog item before it is created, from a JSON payload read from a file or stdin (`name`, `type`, `description`, `acceptanceCriteria`, and `phases` of `{ name, tasks, manualChecks }`). In a web session it slides the rendered item — plan included — into the preview pane and blocks: approval writes the item and every phase in order (plus any configured sub-tasks, and a bug's default `Fix` phase when no phases were given) and prints its id, while rejection exits non-zero with the reviewer's reason and each inline comment so the caller can revise and re-propose. Outside a web session it prints the rendered item and creates it. Used by `/draft` and `/bug`; the payload is strict, so an unknown key is an error. See [docs/backlog-item-preview.md](docs/backlog-item-preview.md)
 - `assist backlog add-phase <id> <name> --task <t...> [--manual-check <c...>] [--position <pos>]` - Add a phase (appends by default; `--position` inserts at a 1-indexed position)
 - `assist backlog add-subtask <id> --title <t> [--desc <d>]` - Add a sub-task (status `todo`) to a backlog item. Sub-tasks listed under the `subtasks` key (each `title` and optional `description`) in `assist.yml` and `~/.assist.yml` are auto-applied to every newly created item (stories and bugs); the global and project lists are combined
 - `assist backlog edit-subtask <id> <idx> [--title <t>] [--desc <d>] [--status <s>]` - Edit a sub-task by its 1-based index from `backlog show`; updates any combination of title, description, and status (omitted fields are left unchanged). `--desc` supports Markdown and `\n` line breaks (pass `--desc ""` to clear it); `--status` must be one of `todo`, `in-progress`, `done`

package/claude/commands/draft.md

@@ -24,7 +24,16 @@ Ask one question at a time. Wait for the user's response before asking the next.
 
 ## Step 3: Propose the item
 
-Once you have enough context, propose a complete backlog item. Show it to the user in a readable format:
+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`:
 
 **Name:** (concise title)
 **Type:** story or bug
@@ -83,27 +92,39 @@ Most phases should NOT have manual checks. Only add `manualChecks` to a phase wh
 
 ## Step 4: Iterate
 
-Ask the user if they want to change anything. Iterate until they confirm.
+In a web session, skip this step — the preview pane handles it.
 
-## Step 5: Save
+Otherwise, ask the user if they want to change anything. Iterate until they confirm.
 
-Once confirmed, create the item and its phases via CLI commands.
+## Step 5: Save
 
-First, add the item and capture the id it prints:
+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:
 
 ```
-assist backlog add --name "Item name" --type story --desc "$(printf '## Background\n\nShort paragraph.\n\n## Goal\n\n- Bullet one\n- Bullet two')" --ac "criterion 1" --ac "criterion 2" 2>&1
+cat <<'JSON' | assist backlog propose --json - 2>&1
+{
+  "name": "Item name",
+  "type": "story",
+  "description": "## Background\n\nShort paragraph.\n\n## Goal\n\n- Bullet one\n- Bullet two",
+  "acceptanceCriteria": ["criterion 1", "criterion 2"],
+  "phases": [
+    { "name": "Phase one name", "tasks": ["Task 1", "Task 2"] },
+    { "name": "Phase two name", "tasks": ["Task 1"], "manualChecks": ["optional check"] }
+  ]
+}
+JSON
 ```
 
-Pass the description as real markdown with line breaks preserved (use `printf` or a quoted heredoc so `\n` becomes actual newlines, not the literal `\n` characters).
+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).
 
-Note the created item id from the output — you'll pass it to the done signal below.
+In a web session this blocks until the user decides in the preview pane:
 
-Then add each phase:
+- **Approved** — the item and all of its phases are created, and the item id is printed.
+- **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.
 
-```
-assist backlog add-phase a<id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
-```
+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