@staff0rd/assist 0.372.0 → 0.373.0

package/README.md

@@ -121,6 +121,8 @@ After installation, the `assist` command will be available globally. You can als
 
 The first backlog command in a repository that still has a local `.assist/backlog.jsonl` automatically migrates it into Postgres — but only as a one-time bootstrap into an empty origin. If Postgres has **no** items for the repo's origin yet, it runs `git pull` (best-effort) to fetch the latest committed copy, imports every item under the origin with fresh global IDs (rewriting links to other items), and verifies the result. If Postgres **already** has items for that origin (a prior run, another clone, or a pre-seeded database), the import is skipped to avoid creating duplicates. Either way the local `.assist/backlog.jsonl` and `.assist/backlog.db` are renamed to `*.bak`, so the migration never re-runs and a local copy is retained.
 
+Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 555 is `a555`) to disambiguate them from GitHub PR/issue numbers (`#42`) and Jira keys. Commands and web API routes that take an `<id>` accept either the prefixed form (`a555`) or a bare number (`555`).
+
 - `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 init` - Create an empty backlog
 - `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
@@ -163,7 +165,7 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist backlog web [-p, --port <number>] [--no-open]` - Open the backlog tab in the web dashboard (default port 3100); `--no-open` skips opening a browser on startup
 - `assist roam auth` - Authenticate with Roam via OAuth (opens browser, saves tokens to ~/.assist.yml)
 - `assist roam show-claude-code-icon` - Forward Claude Code hook activity to Roam local API
-- `assist run <name> [params...]` - Run a configured command from assist.yml (positional params are matched to `params` config; supports `pre` array of commands to run first). If `<name>` is purely numeric and matches no configured command, it is treated as an alias for `assist backlog run <name>` and forwards `--write`/`--no-write`/`-w`.
+- `assist run <name> [params...]` - Run a configured command from assist.yml (positional params are matched to `params` config; supports `pre` array of commands to run first). If `<name>` is a backlog item id (`a555` or a bare `555`) and matches no configured command, it is treated as an alias for `assist backlog run <name>` and forwards `--write`/`--no-write`/`-w`.
 - `assist run add` - Add a new run configuration to assist.yml and create a Claude command file
 - `assist run link <path> --prefix <prefix>` - Link run configurations from another project's assist.yml
 - `assist run remove <name>` - Remove a run configuration from assist.yml and delete its Claude command file

package/claude/commands/bug.md

@@ -69,12 +69,12 @@ Pass the description as real markdown with line breaks preserved (use `printf` o
 
 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.
+Then show the user the item was created and suggest they can run `assist backlog run a<id>` to start implementation.
 
-Finally, signal that the bug-filing task is complete, passing the created item id:
+Finally, signal that the bug-filing task is complete, passing the created item id (a-prefixed, e.g. `a555`):
 
 ```
-assist signal done <id> 2>&1
+assist signal done a<id> 2>&1
 ```
 
 This lets a wrapping `assist bug --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.

package/claude/commands/draft.md

@@ -102,15 +102,15 @@ Note the created item id from the output — you'll pass it to the done signal b
 Then add each phase:
 
 ```
-assist backlog add-phase <id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
+assist backlog add-phase a<id> "Phase name" --task "Task 1" --task "Task 2" --manual-check "optional check" 2>&1
 ```
 
-Then show the user the item was created and suggest they can run `assist backlog run <id>` to start implementation.
+Then show the user the item was created and suggest they can run `assist backlog run a<id>` to start implementation.
 
-Finally, signal that the drafting task is complete, passing the created item id:
+Finally, signal that the drafting task is complete, passing the created item id (a-prefixed, e.g. `a555`):
 
 ```
-assist signal done <id> 2>&1
+assist signal done a<id> 2>&1
 ```
 
 This lets a wrapping `assist draft --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.

package/claude/commands/jira.md

@@ -22,7 +22,7 @@ These actions operate on a single Jira issue. Resolve it once:
 - Otherwise read it from the backlog item this session is working on — the one you are implementing, reviewing, or otherwise focused on (e.g. via `/next-backlog-item`, a `backlog run`, or earlier in this conversation). Get its id, then run:
 
   ```
-  assist backlog show <id> 2>&1
+  assist backlog show a<id> 2>&1
   ```
 
   Use the `Jira: <KEY>` line from the output.

package/claude/commands/subtask.md

@@ -9,14 +9,14 @@ You are adding a sub-task to the backlog item this session is working on by call
 
 Use the backlog item this session is working on — the one you are implementing, reviewing, or otherwise focused on (e.g. via `/next-backlog-item`, a `backlog run`, or earlier in this conversation). Use its id directly.
 
-If this session is not working on a backlog item, there is nothing to attach the sub-task to — tell the user there is no current item and ask them to run this from a session working on one (or to add the sub-task with `assist backlog add-subtask <id>` directly).
+If this session is not working on a backlog item, there is nothing to attach the sub-task to — tell the user there is no current item and ask them to run this from a session working on one (or to add the sub-task with `assist backlog add-subtask a<id>` directly).
 
 ## Step 2: Add the sub-task
 
 `$ARGUMENTS` is the sub-task title. Call the CLI command with the resolved id:
 
 ```
-assist backlog add-subtask <id> --title '<sub-task text>' 2>&1
+assist backlog add-subtask a<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`.