@staff0rd/assist 0.404.1 → 0.405.0

package/README.md

@@ -58,6 +58,7 @@ After installation, the `assist` command will be available globally. You can als
 - `/restructure` - Analyze and restructure tightly-coupled files
 - `/review-pr-comments` - Process PR review comments one by one
 - `/jira [action] [KEY] [args]` - Dispatch Jira actions. `view` (default for a bare key) fetches and displays the issue; `associate <KEY> [id]` associates a ticket with a backlog item via `assist backlog associate-jira`; `update [KEY]` posts a concise session-summary comment via MCP (attaches a passed key to the session item first, else reads the key from it; retargets sub-task comments to the parent; previews before posting); `started [KEY]` assigns it to the current Atlassian user and transitions it to In Progress; `done [KEY]` transitions it to Done with no assignment change; `help` (or bare `/jira`) lists the actions. A `[KEY]` is optional for every action — when omitted it resolves from the session's current backlog item; started/done act on the exact issue with no parent retargeting
+- `/github [action] [ref] [args]` - Dispatch GitHub issue actions via the `gh` CLI (`ref` is `owner/repo#number` shorthand or an issue URL). `view` (default for a bare ref) fetches and displays the issue; `associate <ref> [id]` associates an issue with a backlog item via `assist backlog associate-github`; `update [ref]` posts a concise session-summary comment (attaches a passed ref to the session item first, else reads it from the item; previews before posting); `started [ref]` assigns it to you (GitHub has no In Progress state); `done [ref]` closes it with no assignment change; `help` (or bare `/github`) lists the actions. A `[ref]` is optional for every action — when omitted it resolves from the session's current backlog item's `GitHub:` line
 - `/journal` - Append a journal entry summarising recent work, decisions, and notable observations
 - `/next [id]` - Signal completion and chain into the next backlog item; pass an `id` to run a specific item directly (falls back to the picker if the id is missing, done, won't-do, or blocked)
 - `/standup` - Summarise recent journal entries as a standup update
@@ -161,7 +162,8 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist backlog run <id>` - Run a backlog item's plan phase-by-phase with Claude; `--resume-session <id>` resumes an interrupted Claude session for the current phase (used by the sessions daemon when it restarts a running item)
 - `assist backlog export [file]` - Export every table in the backlog database (discovered by live schema introspection, so new tables are covered automatically) to a file, or stdout if omitted
 - `assist backlog import [file]` - Restore every table present in a dump (file or stdin) back into the backlog database in foreign-key-safe order, faithfully replacing all data and resyncing identity sequences; prompts for confirmation (use `-y, --yes` to skip; required when reading from stdin)
-- `assist backlog associate-jira <id> [key]` - Associate a Jira ticket with a backlog item; validates the key shape, fetches the issue to confirm it exists, and stores the key (re-running with a different key replaces it). Use `--clear` to remove the association
+- `assist backlog associate-jira <id> [key]` - Associate a Jira ticket with a backlog item; validates the key shape, fetches the issue to confirm it exists, and stores the key (re-running with a different key replaces it). Clears any GitHub issue on the item (one external tracker per item). Use `--clear` to remove the association
+- `assist backlog associate-github <id> [issue]` - Associate a GitHub issue with a backlog item; accepts a full issue URL or `owner/repo#number` shorthand, normalises to `owner/repo#number`, and fetches the issue title via the `gh` CLI to confirm it. Clears any Jira key on the item (one external tracker per item). Use `--clear` to remove the association
 - `assist backlog add-activity <id> <kind> <ref>` - Attach a git activity ref to a backlog item, where `kind` is `branch`, `commit`, or `pr`; `branch`/`commit` auto-fill their GitHub URL. Use `--title`, `--url`, `--state` to supply or override metadata. Re-adding the same kind and ref upserts rather than duplicating
 - `assist backlog move-repo <old-origin> [new-origin]` - Retag all items from one origin to another after a repo rename; the new origin defaults to the current repo's remote, both accept URL or `git@` forms, and a bare repo name works for the old origin when unambiguous. Prompts for confirmation (use `-y, --yes` to skip)
 - `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

package/claude/commands/github.md

@@ -0,0 +1,130 @@
+---
+description: View or act on a GitHub issue (view, associate, update, started, done, help)
+allowed_args: "[action] [owner/repo#number | issue-url] [args]"
+---
+
+You are the `/github` dispatcher. Parse `$ARGUMENTS` into an **action verb** plus optional issue/args, then run that action. Actions: `view`, `associate`, `update`, `started`, `done`, `help`.
+
+All GitHub operations go through the `gh` CLI. A GitHub issue is referenced as the compact shorthand `owner/repo#number` (e.g. `staff0rd/assist#5`) or a full `https://github.com/owner/repo/issues/N` URL.
+
+## Step 1: Parse the action
+
+Tokenise `$ARGUMENTS` on whitespace.
+
+- No tokens → run **help**.
+- First token is a known action verb (`view`, `associate`, `update`, `started`, `done`, `help`) → that is the action; the remaining tokens are its args.
+- First token matches a GitHub issue reference (`owner/repo#number` or a `github.com/.../issues/N` URL) → action is **view**, issue is that token.
+- Anything else → run **help** (the input was not understood).
+
+## Step 2: Resolve the issue (for view / started / done / update)
+
+These actions operate on a single GitHub issue. Resolve it once:
+
+- If the action's args include a token matching `owner/repo#number` or a `github.com/.../issues/N` URL, use that reference verbatim.
+- 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 a<id> 2>&1
+  ```
+
+  Use the `GitHub: <owner/repo#number>` line from the output.
+
+If no issue can be resolved — none was passed and there is no session item, or the item has no associated GitHub issue — tell the user there is nothing to act on and ask them to pass an explicit issue. Do not guess an issue.
+
+From an `owner/repo#number` reference, the `gh` repo flag is `-R <owner>/<repo>` and the issue selector is the `<number>`. A full issue URL can be passed to `gh` directly as the selector.
+
+## Action: view
+
+Fetch and display the issue:
+
+```
+gh issue view <number> -R <owner>/<repo> 2>&1
+```
+
+Display the result to the user.
+
+## Action: associate
+
+Associate a GitHub issue with a backlog item by calling the `assist backlog associate-github` CLI command, which normalises the reference, confirms the issue exists via `gh`, and stores it on the item. Args are `<owner/repo#number | issue-url> [backlog item id]`.
+
+Identify which token is the issue reference and which, if any, is the item id (a bare number, optionally `a`-prefixed).
+
+Resolve the target item: use the explicit item id if provided, otherwise the backlog item this session is working on. If there is no explicit id and this session is not working on a backlog item, there is nothing to associate the issue with — tell the user and ask them to pass an explicit item id.
+
+Call the CLI command with the resolved id and the issue reference:
+
+```
+assist backlog associate-github <id> <owner/repo#number | issue-url> 2>&1
+```
+
+To remove an existing association instead, run:
+
+```
+assist backlog associate-github <id> --clear 2>&1
+```
+
+Display the command output so the user can see the result. If the command reports an error (item not found, malformed reference), relay it to the user — nothing is stored on failure. Associating a GitHub issue clears any Jira key on the item (one external tracker per item).
+
+## Action: update
+
+Post a concise comment summarising this session's findings to a GitHub issue. If an issue reference is passed it is first attached to the session's current backlog item; otherwise the reference is read from that item.
+
+**Resolve the issue** as in Step 2, with one addition: if a reference was explicitly passed in the args, first attach it to the session's current backlog item, then use it:
+
+```
+assist backlog associate-github <id> <owner/repo#number | issue-url> 2>&1
+```
+
+If the command reports an error, relay it to the user and stop — nothing is stored on failure.
+
+**Compose a concise comment** from the conversation context:
+
+- One summary line stating what was done or found.
+- A few short bullets with the concrete specifics (files, decisions, outcomes).
+
+Keep it concise: no headers, no wall of text, no restating the whole session. If there is little of substance to report, keep it to the single summary line.
+
+Do not mention `assist`, the assist backlog, or any backlog item number in the comment — the GitHub issue is outward-facing and must not leak internal tooling references. Refer to commits, PRs, or the work itself instead.
+
+**Preview and confirm before posting.** Show the drafted comment and the target issue to the user. Do not post until the user explicitly confirms. If they ask for edits, revise and show the updated draft again. Once confirmed, post it:
+
+```
+gh issue comment <number> -R <owner>/<repo> --body "<comment>" 2>&1
+```
+
+Display the result so the user can see it landed.
+
+## Action: started
+
+Assign the resolved issue to yourself:
+
+```
+gh issue edit <number> -R <owner>/<repo> --add-assignee @me 2>&1
+```
+
+GitHub issues have no generic "In Progress" state (only open/closed), so `started` only self-assigns. If the repo tracks status via a project board, tell the user that must be moved manually.
+
+Report the final assignee.
+
+## Action: done
+
+Close the resolved issue with **no** assignment change:
+
+```
+gh issue close <number> -R <owner>/<repo> 2>&1
+```
+
+Report the final state.
+
+## Action: help
+
+List the available actions and their arguments:
+
+- `/github <owner/repo#number>` or `/github view <ref>` — view an issue (ref optional; falls back to the session item's GitHub issue).
+- `/github associate <ref> [id]` — associate a GitHub issue with a backlog item (id optional; falls back to the session item).
+- `/github update [ref]` — post a concise session-summary comment to the issue (previews before posting).
+- `/github started [ref]` — assign the issue to yourself.
+- `/github done [ref]` — close the issue (no assignment change).
+- `/github help` — show this list.
+
+Note that every action's `[ref]` is optional: when omitted it resolves from the session's current backlog item.

package/claude/settings.json

@@ -65,6 +65,8 @@
 			"Skill(voice-logs)",
 			"Skill(jira)",
 			"SlashCommand(/jira)",
+			"Skill(github)",
+			"SlashCommand(/github)",
 			"Skill(seq)",
 			"SlashCommand(/seq)",
 			"SlashCommand(/sql)",