@staff0rd/assist 0.599.0 → 0.601.0

package/README.md

@@ -41,6 +41,8 @@ After installation, the `assist` command will be available globally. You can als
 ## Claude Commands
 
 - `/add-command` - Add a new run command to assist.yml
+- `/adopt-rules [path]` - Move a repo's existing rules into the canonical `## Rules` sections `assist rules` reads: inventories every `CLAUDE.md`, classifies each as rename (bullets already coded, just the heading is wrong), reword (prose or numbered lists, migrated one at a time via `assist rules add`) or leave, proposes the plan before touching anything, then records the scoped directories with `assist rules index`
+- `/add-rule` - Capture a new `CLAUDE.md` rule from a review comment: words the rule from the note, infers the scope from the commented file (asking only when genuinely ambiguous, defaulting to the nearest `CLAUDE.md`), and writes it with `assist rules add`. Sent by the comment pane's **Add rule** button
 - `/branch <description> [--jira KEY]` - Create a branch off the fresh remote default, deriving a kebab-case slug from the description
 - `/bug` - File a bug with reproduction steps, expected and actual behavior
 - `/comment` - Add pending review comments to the current PR
@@ -235,6 +237,8 @@ The Config tab of the sessions web dashboard never receives secret values: `GET
 ### Rules
 
 - `assist rules list [path]` - List the rules in scope for a path (default: cwd), read from the `## Rules` section of every `CLAUDE.md` from that path's directory up to the repo root, nearest scope first, grouped by the file each rule came from. Rules are `- **<code>** — <text>` bullets
+- `assist rules add <text> [--scope <path>]` - Add a rule to the `## Rules` section of the scope's `CLAUDE.md`, creating the section when absent and allocating the next repo-wide code. `--scope` takes a file or directory (resolved to the nearest existing `CLAUDE.md` at or above it, defaulting to cwd) or a `CLAUDE.md` path written to directly and created if absent. After writing, the root `CLAUDE.md` records the directories that carry their own `## Rules` so scoped rules stay discoverable from the root
+- `assist rules index [path]` - Record the directories that carry their own `## Rules` in the repo root's `CLAUDE.md`, rewriting the line in place rather than duplicating it. `rules add` does this on every add; run it directly after hand-editing a `## Rules` section (e.g. renaming an existing heading)
 
 ### Devlog
 

package/claude/commands/add-rule.md

@@ -0,0 +1,45 @@
+---
+description: Capture a new CLAUDE.md rule from a review comment
+allowed_args: "[quoted text, file and note from the comment pane]"
+---
+
+You are turning a review comment into a written rule in a `CLAUDE.md` file, so the same mistake is caught next time. `$ARGUMENTS` carries what the comment pane sent: an optional `File:` line, the quoted text in a fenced block, and the reviewer's note.
+
+## Step 1: Read what you were given
+
+Pull three things out of `$ARGUMENTS`:
+
+- **File** — the path the selection came from, if a `File:` line is present. The document preview pane has no path, so it may be missing.
+- **Quote** — the selected text, the concrete example of the rule being broken.
+- **Note** — the reviewer's words, the substance of the rule.
+
+If `$ARGUMENTS` is empty, ask the user what rule they want to add and skip to Step 3.
+
+## Step 2: Word the rule
+
+Write the rule as one short imperative sentence that generalises the note beyond this one instance — what to do (or not do), not what went wrong here. Keep it to a single line: it becomes a `- **<code>** — <text>` bullet.
+
+Ask the user a clarifying question only when the note is genuinely too vague to word a rule from. One question, then write it.
+
+## Step 3: Work out the scope
+
+The scope is the directory whose `CLAUDE.md` gets the rule. Infer it — do not ask by default:
+
+- With a file path, the default is the nearest `CLAUDE.md` walking up from that file's directory to the repo root. `assist rules list <path>` shows what is already in scope there, which tells you where sibling rules live.
+- If the note is clearly about a kind of document that lives in one directory (and the file sits in it), that directory's `CLAUDE.md` is the scope — pass `--scope <dir>/CLAUDE.md` to create it there when it does not exist yet.
+- If the rule plainly applies repo-wide, use the root `CLAUDE.md`.
+- Without a file path, use the repo root unless the note names a directory.
+
+Ask the user only when two scopes are genuinely defensible and the choice changes where the rule applies. Otherwise take the nearest `CLAUDE.md` and say which one you chose.
+
+## Step 4: Write it
+
+```
+assist rules add '<rule text>' --scope <path> 2>&1
+```
+
+`--scope` takes a file, a directory, or a `CLAUDE.md` path directly. A file or directory resolves to the nearest existing `CLAUDE.md` at or above it; a `CLAUDE.md` path is written to as given, created if absent. The command allocates the next repo-wide code, creates the `## Rules` section when the file has none, and records the directories that carry their own `## Rules` in the root `CLAUDE.md`.
+
+Use single quotes around the rule text to avoid shell escaping issues.
+
+Show the command output — it names the allocated code and the file — then tell the user in one line which rule was added and where. Do not make any other edit: the rule is the whole task, and fixing the quoted text is not part of it unless the user asks.

package/claude/commands/adopt-rules.md

@@ -0,0 +1,79 @@
+---
+description: Move a repo's existing rules into the canonical `## Rules` sections
+allowed_args: "[path to the repo or directory, defaults to cwd]"
+---
+
+You are migrating a repo's existing written rules into the canonical `## Rules` sections that `assist rules` reads, so they become citable from the comment panes. `$ARGUMENTS` names the repo or directory to work on; default to the cwd.
+
+Assist reads exactly one thing: a `## Rules` heading whose body holds `- **<code>** — <text>` bullets. Rules written any other way — numbered lists, prose sections, bullets under a differently-named heading — are invisible to the rule picker no matter how well written they are. This command finds them and moves them.
+
+## Step 1: Inventory
+
+Find every `CLAUDE.md` in the repo:
+
+```
+git -C <repo> ls-files '**/CLAUDE.md' 'CLAUDE.md' 2>&1
+```
+
+Also check for untracked ones (`git status --short`) and mention any you find. Then, for each directory that has one, see what already parses:
+
+```
+assist rules list <dir> 2>&1
+```
+
+A directory that prints "No rules in scope" has nothing assist can read yet — that is what you are fixing.
+
+## Step 2: Find the rule-like content
+
+Read each `CLAUDE.md` in full. A rule is a standing instruction to whoever writes in that scope — something you could be told you broke. Look for:
+
+- Numbered lists of directives ("Every rule comes from a transcript…", "Numbered lists only.")
+- `- **<code>** — <text>` bullets already in rule form but under a heading that is not `## Rules`
+- Short prose sections that state one standing instruction ("Never hard-wrap.", "Attribute each quote as…")
+
+Not rules, and left alone: where files live, what a directory is for, source locations, epic and project background, worked examples, anything describing the repo rather than constraining what you write in it.
+
+## Step 3: Classify each file
+
+**Rename** — the section's bullets are already `- **<code>** — <text>` and the whole section is rules. Rename that heading to `## Rules`. Nothing else changes, and the existing codes are preserved. This is the cheapest and safest migration; prefer it whenever it applies.
+
+**Reword** — the rules are prose or a numbered list. Word each as one short imperative line, then add them one at a time:
+
+```
+assist rules add '<rule text>' --scope <path to that CLAUDE.md> 2>&1
+```
+
+`rules add` allocates the next repo-wide code, creates the `## Rules` section when the file has none, and keeps the root index current. Then delete the prose you migrated, so the rule is not stated in two places. If a prose section carried context beyond the rule itself, keep the context where it is and take only the instruction.
+
+**Leave** — the file has no standing rules. Say so and move on.
+
+## Constraints
+
+- Assist reads only the **first** `## Rules` heading in a file. Never create a second one; merge into the existing section instead.
+- Only rename a heading when _every_ bullet under it is a rule and each already carries a `**code**`. If the section mixes rules with prose, treat it as a reword.
+- Preserve existing codes on a rename. Never renumber — a code that has been cited must keep meaning the same rule.
+- Never hand-write a new code. Codes are unique repo-wide, and `assist rules add` is what allocates them.
+- Keep the author's wording wherever it already reads as a rule. You are moving rules, not rewriting them.
+- Do not hard-wrap: one line per bullet.
+
+## Step 4: Propose, then apply
+
+Show the user the plan before touching anything: one line per file saying rename, reword (with the rules you would write) or leave. Ask for confirmation.
+
+Then apply it **one file at a time**, showing what changed after each, so a wrong call is caught before it repeats across the repo.
+
+## Step 5: Record and verify
+
+Once the files are migrated, record the scoped directories in the root `CLAUDE.md`:
+
+```
+assist rules index <repo> 2>&1
+```
+
+A rename does not update that index by itself, so run this even if you only renamed headings. Then verify each scope reads back:
+
+```
+assist rules list <dir> 2>&1
+```
+
+Report what is now in scope where, and name anything you deliberately left behind and why.