@staff0rd/assist 0.364.0 → 0.366.0

package/README.md

@@ -128,6 +128,8 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist backlog add --name <n> --type <t> --desc <d> --ac <criterion...>` - Add a backlog item from CLI options (used by `/draft`)
 - `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`
+- `assist backlog remove-subtask <id> <idx>` - Remove a sub-task by its 1-based index from `backlog show`; the remaining sub-tasks are re-indexed so they stay contiguous
 - `assist backlog subtask-status <id> <idx> <status>` - Set a sub-task's status (`todo`, `in-progress`, `done`) by its 1-based index from `backlog show`
 - `assist backlog update-field <id> [--name <n>] [--desc <d>] [--type <t>] [--ac <criterion...>]` - Update fields on a backlog item
 - `assist backlog update-field <id> [--add-ac <text>] [--edit-ac <n> <text>] [--remove-ac <n>]` - Granular acceptance-criteria edits using 1-based indices matching `backlog show`: `--add-ac` appends (repeatable), `--edit-ac` replaces criterion n in place, `--remove-ac` deletes criterion n and renumbers the rest (cannot be combined with the whole-list `--ac`)

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.