@staff0rd/assist 0.600.0 → 0.601.1

package/README.md

@@ -49,6 +49,7 @@ After installation, the `assist` command will be available globally. You can als
 - `/devlog` - Generate devlog entry for the next unversioned day
 - `/draft` - Draft a new backlog item with LLM-assisted questioning
 - `/fix-conflict [--rebase]` - Resolve the current PR branch's conflicts against the remote default, verify, then push; merges by default, `--rebase` replays the branch and pushes with `--force-with-lease`
+- `/fix-rules [dir]` - Put existing rules into the `## Rules` format `assist rules` reads. `[dir]` bounds the work (default: cwd) — only `CLAUDE.md` files at or below it are inventoried and changed, and a target below the repo root reports which files that excluded. Reads each one, then suggests the full list of changes — one row per candidate, showing how it reads today and the exact bullet it would become — and waits. Once agreed, applies them one file at a time (a wrongly-named heading is renamed, preserving its codes; prose and numbered rules are reworded and added via `assist rules add`, with the original prose removed), then records the scoped directories with `assist rules index`. Rules stay in the `CLAUDE.md` they were already in; the root index line is the only thing written outside the target
 - `/forward-comments` - Split a coarse PR comment into per-line review comments, attributed to the original reviewer
 - `/handover` - Write a session handover note for the next conversation
 - `/pr` - Raise a PR with a concise description, then watch CI in the background
@@ -237,6 +238,7 @@ The Config tab of the sessions web dashboard never receives secret values: `GET
 
 - `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` - Record the directories that carry their own `## Rules` in the repo root's `CLAUDE.md`, rewriting the line in place rather than duplicating it. Always repo-wide, resolved from the cwd — it takes no path, since the index lives at the root by definition and cannot be narrowed. `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/fix-rules.md

@@ -0,0 +1,97 @@
+---
+description: Put a repo's existing rules into the `## Rules` format assist reads
+allowed_args: "[directory to fix, defaults to cwd]"
+---
+
+You are fixing existing written rules so `assist rules` can read them, and so they become citable from the comment panes. `$ARGUMENTS` is the directory to fix — the cwd when it is empty.
+
+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, suggests the changes that would fix them, and applies what the user agrees to.
+
+Nothing leaves the file it is in. A rule stays in its own `CLAUDE.md`; it just ends up under that file's `## Rules` heading, in the bullet form the parser reads.
+
+## Step 1: Inventory
+
+The target directory bounds everything you inventory and everything you change. Find every `CLAUDE.md` at or below it:
+
+```
+git -C <target> ls-files '**/CLAUDE.md' 'CLAUDE.md' 2>&1
+```
+
+A `CLAUDE.md` **above** the target is out of scope, even though its rules still apply to files inside the target. So when the target is not the repo root, open by naming the files you are therefore not touching — the user asked for a directory, and they should not have to guess what that excluded.
+
+Also check for untracked ones (`git -C <target> 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. Read every `CLAUDE.md` you found, including ones that already have a `## Rules` section, since a file can have rules in the section and more of them scattered elsewhere.
+
+## 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 fix; 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 it replaced, so the rule is not stated twice in the same file. 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 reformatting rules, not rewriting them.
+- Do not hard-wrap: one line per bullet.
+
+## Step 4: Suggest the changes
+
+Before touching anything, show the user the whole list of suggested changes — every candidate you found, in every `CLAUDE.md`, as its own numbered row. Group the rows by file. Each row gives:
+
+- how it reads today: the heading it sits under, or the opening words of the prose
+- the exact bullet it would become, `- **<code>** — <text>`, with the code it would be given
+- the file whose `## Rules` section it lands in, when that is not the file it is already in
+
+A rename is a single row for the whole section, naming the heading it replaces and the codes it preserves. Close with the files you would leave alone and a few words on why.
+
+Then stop and wait. These are suggestions: the user may strike rows, reword them, move one to a different scope, or add something you missed. Do not start applying because the list looks obvious.
+
+## Step 5: Apply what was agreed
+
+Work through the agreed rows **one file at a time**, showing what changed after each, so a wrong call is caught before it repeats across the repo. Apply only what was agreed — do not add a row, reword one, or quietly drop one along the way.
+
+## Step 6: Record and verify
+
+Once the files are fixed, record the scoped directories in the root `CLAUDE.md`:
+
+```
+assist rules index 2>&1
+```
+
+A rename does not update that index by itself, so run this even if you only renamed headings.
+
+This is the one thing that reaches outside the target directory: the index line lives in the repo root's `CLAUDE.md` by definition, and is rebuilt from every `## Rules` section in the repo. Mention that you touched the root file when the target was not the root.
+
+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.