@staff0rd/assist 0.454.1 → 0.456.0

package/README.md

@@ -99,6 +99,7 @@ After installation, the `assist` command will be available globally. You can als
 - `assist commit <message>` - Commit staged changes with validation
 - `assist commit <message> [files...]` - Stage files and create a git commit with validation
 - `assist branch <slug> [--jira <key>] [--from <ref>]` - Create and switch to a new branch off the fresh remote default branch. Assembles the name as `[<prefix>/][<JIRA>-]<slug>` (prefix from the optional `branch.prefix` config, Jira key used verbatim), fetches and branches from `origin/<default>` (resolved live from the remote, falling back to `main`, overridable via `branch.defaultBranch`), and rejects slugs whose numeric tokens look like backlog IDs. Pass `--from <ref>` to base the branch off `<ref>` verbatim (a local branch, tag, or `origin/*` remote-tracking ref) instead of the remote default; the ref is still fetched first and validated with `git rev-parse --verify`, failing fast if it does not resolve. A long free-text slug is first shortened to a concise, LLM-assisted kebab-case name (falling back to a word-boundary trim if the model is unavailable) so branch names stay brief
+- `assist watch wait [--interval <duration>] [--timeout <duration>] [--pull]` - Block until the current branch's upstream gains commits, then exit. Waiting costs no agent turns, so a watcher wakes only when a commit actually lands rather than on a clock tick. Fetches every `--interval` (default `30s`) and compares `@` against `@{u}`; a branch that is already behind returns immediately without fetching, and a transient fetch failure is ignored rather than ending the wait. Durations are a whole number followed by `s`, `m`, or `h`. `--pull` fast-forwards the branch with `git pull --ff-only` once movement is detected and prints the resulting sha; there is no force, rebase, or reset path, so a pull that is not a clean fast-forward is reported rather than resolved and the working tree is left untouched. The exit code is the interface: `0` the upstream moved (prints the `from..to` sha range and commit count) and, with `--pull`, was fast-forwarded cleanly, `2` timed out after `--timeout` (default `60m`) with no movement — just wait again, `3` the upstream moved but the `--pull` was not a clean fast-forward (prints git's own reason) — stop and report, `1` cannot wait at all (no upstream, detached HEAD, or not a repo), `130` interrupted
 - `assist prs` - List pull requests for the current repository
 - `assist prs raise --title <title> --what <what> --why <why> [--how <how>] [--resolves <key>] [--force]` - Raise a pull request, assembling the body from `## What`, `## Why` (with `--resolves` Jira URLs appended inline), and an optional `## How`. When run inside an assist web session, the drafted title and body are shown in a 50/50 preview pane beside the terminal for approve/reject before the PR is created or updated (the command blocks until you decide; rejecting exits non-zero); in a plain terminal it places the PR directly, erroring if one already exists unless `--force` overwrites its title and body. In the web preview pane you can attach inline comments to spans of the body, and drop or paste screenshots anywhere on the pane — each image is hosted via the [`gh-image`](https://github.com/drogers0/gh-image) gh extension (`gh extension install drogers0/gh-image`), shown in a Screenshots section, and on approval appended to the PR body under a `## Screenshots` heading (discarded on rejection). Run `assist prs raise --help` for full authoring guidance (which itself adapts to the terminal-vs-web context)
 - `assist prs edit [--title <title>] [--what <what>] [--why <why>] [--how <how>] [--resolves <key>]` - Update only the supplied sections of the current branch's pull request, preserving every other section of its body

package/claude/CLAUDE.md

@@ -28,6 +28,10 @@ When drafting a message to send on the user's behalf (Slack, PR, email, comment)
 
 Do not include comments for standard logic or syntax. Only comment if the specific line involves unintuitive complexity or a hack.
 
+## Backlog item IDs
+
+A bare `a` followed by hex (e.g. `a791`, `a3f0`) is an assist backlog item ID, not a git SHA. Read it with `assist backlog view <id>`.
+
 ## Backlog items, PRs, and commits
 
 Do not mention assist backlog items in PR descriptions or PR comments. The reference goes the other way: mention the relevant commits or PRs in the assist backlog item.