@staff0rd/assist 0.300.0 → 0.302.0

package/README.md

@@ -58,6 +58,7 @@ After installation, the `assist` command will be available globally. You can als
 - `/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
+- `/strip-comments` - Enforce self-documenting code: declare the comment policy in CLAUDE.md if absent, then strip redundant comments, commented-out code, and section banners from tracked source files (functional directives and genuine workaround comments are preserved); edits are left unstaged
 - `/sync` - Sync commands and settings to ~/.claude
 - `/test-cover` - Incrementally increase test coverage by identifying and testing uncovered files
 - `/test-review` - Review existing tests for quality, coverage gaps, and adherence to conventions
@@ -159,7 +160,7 @@ The first backlog command in a repository that still has a local `.assist/backlo
 - `assist verify hardcoded-colors` - Check for hardcoded hex colors in src/ (supports `hardcodedColors.ignore` globs in config)
 - `assist verify comment-policy` - Flag comments added on changed lines (staged + unstaged) unless they carry a justification marker; supports `commentPolicy.markers` and `commentPolicy.ignore` globs in config
 - `assist lint [-f, --fix]` - Run lint checks for conventions not enforced by oxlint (use `-f` to auto-fix)
-- `assist lint init` - Initialize Biome with standard linter config
+- `assist lint init` - Initialize oxlint with baseline linter config
 - `assist refactor check [pattern]` - Check for files that exceed the maximum line count
 - `assist refactor ignore <file>` - Add a file to the refactor ignore list
 - `assist refactor rename file <source> <destination>` - Rename/move a TypeScript file and update all imports (dry-run by default, use `--apply` to execute)

package/claude/commands/add-command.md

@@ -18,7 +18,7 @@ Run `assist run add --help` to see the current CLI usage and options. Use the ou
 Run `assist run add <name> <command> [args...]` with the appropriate arguments. For example:
 
 ```
-assist run add lint biome check --write
+assist run add lint oxlint --fix
 ```
 
 If the command needs a working directory, use `--cwd <dir>`.

package/claude/commands/strip-comments.md

@@ -0,0 +1,53 @@
+---
+description: Enforce self-documenting code by declaring the comment policy and stripping redundant comments
+---
+
+You are enforcing a self-documenting code style: code should explain itself, and comments should only earn their place when they convey something the code cannot.
+
+## Step 1: Ensure CLAUDE.md declares the policy
+
+Read `CLAUDE.md` at the repository root.
+
+Decide whether it already states a code-style or commenting policy — look for an existing `## Code style` heading, a `## Commenting code` (or similar) section, or any prose that tells contributors not to write comments that restate the code.
+
+- If such a policy is **already present**, leave `CLAUDE.md` unchanged. Do not duplicate or reword it.
+- If **no** such policy exists, append the following section verbatim (including the heading) to the end of `CLAUDE.md`:
+
+```markdown
+## Code style
+
+Write self-documenting code. Do not add comments that restate what the code already says, label obvious sections, or narrate standard logic and syntax. Only comment when a line involves unintuitive complexity, a genuine hack, or a workaround that the code itself cannot make clear. Never leave commented-out code in the tree.
+```
+
+## Step 2: Enumerate tracked source files
+
+List git-tracked source files with `git ls-files`. Restrict to source files (e.g. `.ts`, `.tsx`, `.js`, `.jsx`, `.cs`, `.py`, `.go`, `.rs`, `.java`, `.kt`, `.rb`, `.c`, `.h`, `.cpp`, `.css`, `.scss`, `.sh`). Skip generated output, lockfiles, vendored dependencies, and markdown/docs.
+
+## Step 3: Remove violating comments
+
+Read each file and remove only comments that violate the policy:
+
+- **Redundant explanatory comments** that restate what the adjacent code plainly does (e.g. `// increment counter` above `counter++`).
+- **Commented-out code** — dead code left in the tree.
+- **Section-banner comments** that merely label a region (e.g. `// ---- helpers ----`, `// === Setup ===`).
+
+**Never remove** the following, even if they look like noise:
+
+- **Functional directives** that the toolchain acts on: `eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `biome-ignore`, `prettier-ignore`, `// @ts-nocheck`, coverage pragmas (`c8 ignore`, `istanbul ignore`), `noqa`, `type: ignore`, `#pragma`, `//go:`-style directives, and similar.
+- **Comments marking a genuine hack or workaround** — anything explaining *why* non-obvious code exists, including `HACK`/`WORKAROUND`/`FIXME`/`TODO` notes, links to issues, or rationale the code cannot convey on its own.
+- **Doc comments** that form part of an API contract (JSDoc/TSDoc, XML doc comments, docstrings) unless they only restate the signature.
+
+When in doubt, keep the comment. The cost of leaving a borderline comment is far lower than deleting one that carries intent.
+
+## Step 4: Apply as unstaged edits and summarise
+
+Apply every removal directly to the working tree using Edit. **Do not stage and do not commit** — leave all changes unstaged for the user to review.
+
+Then print a per-file summary, for example:
+
+```
+src/foo.ts        3 removed
+src/bar/baz.ts    1 removed
+```
+
+For each file with removals, list the removed comments (a short quote of each) so the user can audit the changes. End with the total count and a reminder that the edits are unstaged and ready for review.

package/claude/commands/verify-new.md

@@ -18,7 +18,7 @@ Run `assist run add --help` to see the current CLI usage and options. Use the ou
 `assist verify` runs every `verify:*` entry in parallel and only surfaces output for the ones that fail. A noisy success drowns the signal, so before registering the command, find the flag(s) that make the wrapped tool silent on success:
 
 - Check the tool's `--help` for options like `--silent`, `--quiet`, `-q`, `--reporter=dot`, `--reporter=line`, `--no-progress`, `--log-level=error`, `--no-color`, etc.
-- Prefer reporters that print only failures (e.g. `vitest --reporter=dot`, `eslint --quiet`, `tsc --pretty false`, `biome check --reporter=summary`).
+- Prefer reporters that print only failures (e.g. `vitest --reporter=dot`, `oxlint --quiet`, `tsc --pretty false`).
 - If the tool always prints a banner or summary on success, look for a way to suppress it (redirect, `--no-summary`, etc.). Mention any unavoidable noise to the user.
 
 Apply those flags as part of the args you pass to `assist run add`.
@@ -29,7 +29,7 @@ Run `assist run add verify:<name> <command> [args...]` with the quiet flags appl
 
 ```
 assist run add verify:test vitest run --reporter=dot
-assist run add verify:lint eslint . --quiet
+assist run add verify:lint oxlint . --quiet
 assist run add verify:types tsc --noEmit --pretty false
 ```
 

package/claude/settings.json

@@ -80,6 +80,9 @@
 			"SlashCommand(/handover)",
 			"Skill(recall)",
 			"SlashCommand(/recall)",
+			"Skill(strip-comments)",
+			"SlashCommand(/strip-comments)",
+			"Bash(git ls-files:*)",
 			"WebFetch(domain:staffordwilliams.com)"
 		],
 		"deny": [