@staff0rd/assist 0.654.1 → 0.656.0

package/README.md

@@ -104,13 +104,13 @@ Every command supports `--help` for full detail on its flags and behaviour.
 
 ### Git and GitHub
 
-- `assist sync [--prune] [--force]` - Copy commands, settings, `CLAUDE.md` and design assets to `~/.claude` (plus `~/.codex` and `~/.pi` when those CLIs are on PATH). With `--prune`, also lists commands in the target dirs that sync did not write — anything whose name is not in the repo's `claude/commands/*.md` set — and adding `--force` removes them. `~/.codex/skills` and `~/.pi/agent/prompts` are only inspected when those CLIs are detected; an orphaned codex skill directory is removed only when `SKILL.md` is its sole content, and any other is left in place with a reason. Subdirectories and non-`.md` files are listed separately and never removed. `--force` without `--prune` is an error
+- `assist sync [--prune] [--force]` - Copy commands, settings and design assets to `~/.claude` (plus `~/.codex` and `~/.pi` when those CLIs are on PATH). No global instructions file is written any more — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and `~/.pi/agent/AGENTS.md` are all gone, and each harness instead receives the repo's composed advice at session start: Claude Code from the `assist advise --hook` SessionStart hook, Codex from `assist codex-hook` on its `SessionStart` event, and pi from the `assist-advice.ts` extension. Any of those three files an earlier sync left on disk is named on every run — sync never deletes them, since a hand-written one is indistinguishable from a leftover, but until they go they keep injecting the retired global instructions. With `--prune`, also lists commands in the target dirs that sync did not write — anything whose name is not in the repo's `claude/commands/*.md` set — and adding `--force` removes them. `~/.codex/skills` and `~/.pi/agent/prompts` are only inspected when those CLIs are detected; an orphaned codex skill directory is removed only when `SKILL.md` is its sole content, and any other is left in place with a reason. Subdirectories and non-`.md` files are listed separately and never removed. `--force` without `--prune` is an error
 - `assist activity [--since <date>]` - Chart GitHub commit activity per day (defaults to last 30 days)
 - `assist commit status` - Show git status and diff
 - `assist commit <message> [files...] [--ref <ref>]` - Stage files and create a git commit with validation. The message must be a single line under 50 characters; `--ref` is the only way to give the commit a body. Each `--ref` value is free text containing a URL (e.g. `--ref "rationale for removing it https://…"`) and becomes one `Ref:` trailer line, verbatim — commas are not separators, so repeat the flag to pass several. A value carrying no `http`/`https` URL is rejected before anything is staged
 - `assist branch <slug> [--jira <key>] [--from <ref>]` - Create and switch to a new branch off the fresh remote default (or `--from <ref>`); name is `[<prefix>/][<JIRA>-]<slug>`, long slugs shortened by LLM
 - `assist watch wait [--interval <d>] [--timeout <d>|none] [--pull] [--build [entry]]` - Block until the current branch's upstream gains commits, then exit. Fetches once at startup, so commits already on the remote are picked up without waiting out an interval. `--timeout` defaults to `none`, so a quiet branch waits indefinitely rather than exiting 2. With `--pull`, fast-forwards (recovering a dirty tree or a merely-behind branch) and prints the build report (see `assist watch report`) baselined on the pre-pull SHA. With `--build`, runs the `auto-build` run entry — or `[entry]` if named — after a successful pull, then, when the report's **Sync** section names something, shells out to `assist sync --yes` so the freshly built binary installs the changed commands, skills and settings into `~/.claude`. Exit codes: `0` moved (and cleanly pulled, built and synced), `2` timed out on an explicit finite `--timeout`, `3` the branch has genuinely diverged, `4` the build or the post-build sync failed, `1` cannot wait, `130` interrupted
-- `assist watch report [--from <sha>]` - Print the built version from `package.json`, the last 10 commits as a markdown SHA/When/Subject table newest-first, a **Restarts** section naming the restarts the new commits make necessary, and a **Sync** section naming what changed under the paths `assist sync` installs (`claude/commands/`, `claude/skills/`, `claude/settings.json`, `claude/CLAUDE.md`, `claude/design-system-prompt.md`, `codex/`, `pi/`), or `- not needed`. With `--from`, commits reachable from `HEAD` but not `<sha>` are marked `← new` and both the restart and sync advice come from the files they changed. Exit codes: `0` printed, `1` git could not resolve the range
+- `assist watch report [--from <sha>]` - Print the built version from `package.json`, the last 10 commits as a markdown SHA/When/Subject table newest-first, a **Restarts** section naming the restarts the new commits make necessary, and a **Sync** section naming what changed under the paths `assist sync` installs (`claude/commands/`, `claude/skills/`, `claude/settings.json`, `claude/design-system-prompt.md`, `codex/`, `pi/`), or `- not needed`. With `--from`, commits reachable from `HEAD` but not `<sha>` are marked `← new` and both the restart and sync advice come from the files they changed. Exit codes: `0` printed, `1` git could not resolve the range
 - `assist read-time <target> [--budget <duration>]` - Estimate how long a document takes to read, printing e.g. `142 words · ~1m 39s read`. `<target>` is a pull request number, a GitHub pull request URL (which may point at another repo), `-` to read from stdin, or a path to a file; the current branch's PR is deliberately not a default. Prose counts at `readTime.wordsPerMinute` (default 200) and fenced code at half that, with a bare URL or an image/HTML tag counting as one word. The effective rate decays as the document grows, so a 500-word one reads at ~70 wpm and a 2000-word one at ~55. When the estimate exceeds the budget — one minute unless `--budget` (`45s`, `1m30s`, `2m`) says otherwise — `· over the ~1m budget` is appended
 - `assist prs` - List pull requests for the current repository
 - `assist prs raise --title <t> --what <w> --why <y> [--how <h>] [--resolves <ref>] [--force] [--draft|--no-draft]` - Raise a PR, assembling the body from What/Why/How. Whether the PR is created as a draft comes from `prs.draft` unless `--draft` or `--no-draft` is passed, which always wins. In a web session the draft is previewed for approve/reject (with inline comments and pasted screenshots or video, hosted via the [`gh-image`](https://github.com/drogers0/gh-image) gh extension) before the PR is created. The preview pane carries two independent chain checkboxes, both default on: **Review PR** chains a `review --no-prompt --submit <n> --address-comments` session once the PR is raised (review → post findings → Address Comments), and **Post to Slack** announces the PR in Slack at the tail of that chain — or directly via `/prs-slack <n> --no-confirm` when Review PR is off. With both on, approving runs raise → Review PR + Post to Slack → Address Comments → Slack announce end to end. A third checkbox, **Auto-merge (squash)**, defaults off and is offered for both a new PR and an update to an existing one: approving with it ticked runs `gh pr merge --auto --squash` on the current branch's PR once it is placed, before the chain runs, and a repo that refuses auto-merge only prints a warning. It and **Draft** untick each other, since GitHub refuses auto-merge on a draft PR
@@ -270,7 +270,7 @@ The Config tab of the sessions web dashboard never receives secret values: `GET
 - `assist code-comment confirm <pin>` - Insert the pinned comment at its file/line and clear the pin state
 - `assist db-migration unlock` - Page a human to approve creating the next new migration module, issuing a pin via desktop notification
 - `assist db-migration confirm <pin>` - Confirm a pin from `db-migration unlock`, letting that migration's file write through once
-- `assist advise [--hook]` - Print the advice fragments from `claude/advice/*.md` that apply to the cwd's repo, each selected by its `when` condition against the merged config and repo facts, composed in filename order. `--hook` reads the SessionStart payload from stdin for the session's cwd and emits the markdown as `hookSpecificOutput.additionalContext`
+- `assist advise [--hook] [--explain]` - Print the advice fragments from `claude/advice/*.md` that apply to the cwd's repo, each selected by its `when` condition against the merged config and repo facts, composed in filename order. A fragment body may interpolate `{{variable}}` placeholders — `verify.md` names the repo's own `verify*` run commands that way. `advice.include` and `advice.exclude` override a fragment's condition by name, `advice.verify` replaces the verify fragment's text and forces it in, and `advice.extra` is appended as a "Repo notes" section. `--hook` reads the SessionStart payload from stdin for the session's cwd and emits the markdown as `hookSpecificOutput.additionalContext`; `--explain` lists every shipped fragment with whether it was included and the reason. Claude Code gets this through the `assist advise --hook` SessionStart hook, Codex through `assist codex-hook` on its own `SessionStart` event, and pi through the `assist-advice.ts` extension, which composes on `session_start` and appends the markdown to the system prompt on `before_agent_start`
 - `assist notify` - Show desktop notification from JSON stdin (macOS, Windows, WSL)
 - `assist status-line` - Format Claude Code status line from JSON stdin
 

package/claude/advice/filename-convention.md

@@ -0,0 +1,6 @@
+---
+title: Naming files after their export
+when: filenameConvention
+---
+
+A file's name must match the function it exports (e.g. `updateWorkerCapacity.ts` for `updateWorkerCapacity`), per the `oxlint-rules/filenameConvention.ts` lint rule — including the destination passed to `assist refactor extract`.

package/claude/advice/refactor.md

@@ -0,0 +1,12 @@
+---
+title: Renaming and extracting TypeScript
+when: typescript
+---
+
+When renaming TypeScript files or symbols, use the refactor commands instead of doing it manually:
+
+- `assist refactor rename file <source> <destination>` — rename/move a file and update all imports
+- `assist refactor rename symbol <file> <oldName> <newName>` — rename a variable, function, class, or type across the project
+- `assist refactor extract <file> <functionName> <destination>` — extract a function and its private dependencies to a new file
+
+All default to dry-run; add `--apply` to execute.

package/claude/advice/settings-json.md

@@ -0,0 +1,6 @@
+---
+title: Editing claude/settings.json
+when: claudeSettings
+---
+
+Do not modify `claude/settings.json` without asking the user first. Only read-only commands should be added to the allow list — write operations (add, remove, set, delete) must require confirmation.

package/claude/advice/verify.md

@@ -0,0 +1,6 @@
+---
+title: Verifying a change
+when: verify
+---
+
+After any code change, run `assist verify` — it runs this repo's {{verifyCommands}} in parallel and prints only what failed. Run it bare, never piped through `head`, `tail`, `grep`, `rg` or `wc`.

package/codex/config.toml

@@ -1,8 +1,14 @@
 # Managed by `assist sync`: merged into ~/.codex/config.toml when the codex CLI
 # is detected. Registers the assist codex-hook, which auto-approves read-only
-# commands and reports running/waiting status for daemon-tracked sessions.
+# commands, injects the repo's composed advice at SessionStart, and reports
+# running/waiting status for daemon-tracked sessions.
 # Codex still requires this hook to be trusted once per machine on first run.
 
+[[hooks.SessionStart]]
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "assist codex-hook"
+
 [[hooks.UserPromptSubmit]]
 [[hooks.UserPromptSubmit.hooks]]
 type = "command"