@staff0rd/assist 0.363.0 → 0.365.0

package/README.md

@@ -167,7 +167,8 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist config set <key> <value>` - Set a config value (e.g. commit.push true)
 - `assist config get <key>` - Get a config value
 - `assist config list` - List all config values
-  - `prs.slack` - The Slack channel (e.g. `#example`) that `/prs-slack` posts pull requests to via the Slack MCP connector
+  - `prs.slack` - The Slack channel (e.g. `#example`) that `/prs-slack` posts pull requests to via the Slack MCP connector (optional; can be omitted when only `prs.required` is set)
+  - `prs.required` - When `true` (default `false`), `assist backlog run` auto-branches a story that has no recorded branch at run start, so a new story never inherits the previous story's branch
 - `assist verify` - Run all verify:\* commands in parallel (from run configs in assist.yml and scripts in package.json)
 - `assist verify all` - Run all checks, ignoring diff-based filters
 - `assist verify --measure` - After the run, print a summary table of each command's status and duration (slowest first) plus a wall-clock total
@@ -304,6 +305,8 @@ When `branch.prefix` is set (e.g. `sw`), `assist branch <slug>` prepends `<prefi
 
 `assist branch` resolves the base branch live from the remote (`git ls-remote --symref origin HEAD`), so it never depends on a stale or unset local `origin/HEAD`. If the remote advertises no default it falls back to `main`. Set `branch.defaultBranch` (e.g. `develop`) to override the base branch outright.
 
+When `prs.required` is `true`, `assist backlog run` checks at run start whether a branch has been recorded against the story; if none has, it uses the same branch-creation code as `assist branch` to cut a fresh branch off `origin/<default>` (name derived from the story's title, plus its Jira key when associated) and records it against the story. A story that already has a recorded branch is left untouched, so resumes and later phases never re-branch. With the key unset or `false`, run behaviour is unchanged.
+
 ## netcap browser extension
 
 `assist netcap` only runs the receiver; the browser side is a raw Manifest V3 extension (no build step) under `netcap-extension/`. A MAIN-world content script patches `fetch`/`XMLHttpRequest` to capture `{url, method, status, requestBody, responseBody, timestamp}`, relays each entry to the background service worker (`window.postMessage` → `chrome.runtime.sendMessage`), and the background worker POSTs it to the receiver. The XHR patch reads the response across every `responseType` (`json`, `blob`, `arraybuffer`, `document`, not just `text`) — LinkedIn's voyager GraphQL calls use `responseType: "json"`, which exposes no `responseText`, so reading `responseText` alone captured those bodies empty. Forwarding happens in the background context, so the page's CSP (`connect-src`) never blocks it — the limitation that killed the earlier console-paste approach.

package/claude/commands/bug.md

@@ -38,6 +38,21 @@ Show the user the bug report:
 
 Do NOT generate a plan — the implementer will determine how to fix it.
 
+### Writing the description
+
+The description renders as markdown in both the terminal (`assist backlog show`) and the web UI, so author it as structured markdown — never a single run-on prose paragraph. Use bold section labels or `##` headings, a numbered list for the repro steps, and short paragraphs for Expected/Actual:
+
+```markdown
+**Repro:**
+
+1. Step one
+2. Step two
+
+**Expected:** what should happen.
+
+**Actual:** what happens instead.
+```
+
 ## Step 4: Iterate
 
 Ask the user if they want to change anything. Iterate until they confirm.
@@ -47,9 +62,11 @@ Ask the user if they want to change anything. Iterate until they confirm.
 Once confirmed, add the item via CLI and capture the id it prints:
 
 ```
-assist backlog add --name "Bug title" --type bug --desc "**Repro:**\n1. ...\n\n**Expected:** ...\n\n**Actual:** ..." --ac "criterion 1" --ac "criterion 2" 2>&1
+assist backlog add --name "Bug title" --type bug --desc "$(printf '**Repro:**\n\n1. ...\n2. ...\n\n**Expected:** ...\n\n**Actual:** ...')" --ac "criterion 1" --ac "criterion 2" 2>&1
 ```
 
+Pass the description as real markdown with line breaks preserved (use `printf` or a quoted heredoc so the `\n` sequences become actual newlines, not literal `\n` characters).
+
 Note the created item id from the output — you'll pass it to the done signal below.
 
 Then show the user the item was created and suggest they can run `assist backlog run <id>` to start implementation.

package/claude/commands/draft.md

@@ -28,11 +28,22 @@ Once you have enough context, propose a complete backlog item. Show it to the us
 
 **Name:** (concise title)
 **Type:** story or bug
-**Description:** 1-3 sentences
+**Description:** (structured markdown — see below)
 **Acceptance Criteria:**
 
 - (specific, testable criteria)
 
+### Writing the description
+
+Descriptions render as markdown in both the terminal (`assist backlog show`) and the web UI, so author them as structured markdown — never a single run-on prose paragraph:
+
+- Use short paragraphs (1-3 sentences each), separated by blank lines.
+- Use `##` headings to break longer descriptions into sections (e.g. Background, Goal, Notes).
+- Use bullet lists for enumerations and `-`/`1.` lists where they read more clearly than prose.
+- Use **bold**, `inline code`, and other inline markdown for emphasis and identifiers.
+
+Keep it scannable. A short item can be a couple of tight paragraphs; a larger one should use headings and lists.
+
 **Plan:**
 
 - Phase 1: (name) — tasks...
@@ -81,9 +92,11 @@ Once confirmed, create the item and its phases via CLI commands.
 First, add the item and capture the id it prints:
 
 ```
-assist backlog add --name "Item name" --type story --desc "Description text" --ac "criterion 1" --ac "criterion 2" 2>&1
+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
 ```
 
+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).
+
 Note the created item id from the output — you'll pass it to the done signal below.
 
 Then add each phase:

package/claude/commands/refine.md

@@ -37,13 +37,15 @@ Based on the user's input, apply changes using the appropriate commands. Always
 
 ```
 assist backlog update-field <id> --name "New name"
-assist backlog update-field <id> --desc "New description"
+assist backlog update-field <id> --desc "$(printf '## Section\n\nShort paragraph.\n\n- Bullet one\n- Bullet two')"
 assist backlog update-field <id> --type story
 assist backlog update-field <id> --ac "criterion 1" --ac "criterion 2"
 ```
 
 Note: `--ac` replaces all acceptance criteria, so include the full list (both existing and new).
 
+Descriptions render as markdown in both the terminal (`assist backlog show`) and the web UI, so author them as structured markdown — short paragraphs, `##` headings for longer descriptions, and bullet lists rather than one run-on prose paragraph. Pass the value as real markdown with line breaks preserved (use `printf` or a quoted heredoc so `\n` becomes actual newlines, not literal `\n` characters).
+
 **To modify a plan phase** (phase is 0-indexed):
 
 ```

package/claude/commands/subtask.md

@@ -21,4 +21,10 @@ assist backlog add-subtask <id> --title '<sub-task text>' 2>&1
 
 Use single quotes around the title to avoid shell escaping issues. The sub-task is created with status `todo`.
 
+If the sub-task needs more than a title — extra context, steps, or acceptance detail — pass a `--desc` as well. Sub-task descriptions render as markdown in both the terminal (`assist backlog show`) and the web UI, so author them as structured markdown (short paragraphs, bullet lists, optional `##` headings), never a single run-on prose paragraph. Preserve line breaks by building the value with `printf` (or a quoted heredoc) so `\n` becomes real newlines:
+
+```
+assist backlog add-subtask <id> --title '<sub-task text>' --desc "$(printf '## Context\n\nShort paragraph.\n\n- Point one\n- Point two')" 2>&1
+```
+
 Display the command output so the user can see the result. If the command reports an error (item not found, or a missing title), relay it to the user.