vigiles 2.5.0 → 3.0.0

package/skills/linter-docs/ruff.md

@@ -0,0 +1,187 @@
+# Ruff — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+
+## Check Existing Rules First
+
+Ruff reimplements 800+ rules from flake8, pylint, isort, pyupgrade, and others. Before writing a custom rule, check if Ruff already covers it:
+
+| Prefix    | Source                    | Key rules                                                                                                                                     |
+| --------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `E` / `W` | pycodestyle               | `E501` (line-too-long), `W291` (trailing-whitespace), `E711` (none-comparison)                                                                |
+| `F`       | pyflakes                  | `F401` (unused-import), `F841` (unused-variable), `F811` (redefined-unused-name)                                                              |
+| `I`       | isort                     | `I001` (unsorted-imports), `I002` (missing-required-import)                                                                                   |
+| `N`       | pep8-naming               | `N801` (invalid-class-name), `N802` (invalid-function-name), `N806` (non-lowercase-variable)                                                  |
+| `UP`      | pyupgrade                 | `UP006` (non-pep585-annotation), `UP007` (non-pep604-annotation), `UP035` (deprecated-import)                                                 |
+| `S`       | flake8-bandit             | `S101` (assert), `S105` (hardcoded-password-string), `S301` (suspicious-pickle-usage)                                                         |
+| `B`       | flake8-bugbear            | `B006` (mutable-argument-default), `B007` (unused-loop-control-variable), `B905` (zip-without-explicit-strict)                                |
+| `A`       | flake8-builtins           | `A001` (builtin-variable-shadowing), `A002` (builtin-argument-shadowing)                                                                      |
+| `C4`      | flake8-comprehensions     | `C400` (unnecessary-generator-list), `C401` (unnecessary-generator-set), `C408` (unnecessary-collection-call)                                 |
+| `T20`     | flake8-print              | `T201` (print), `T203` (pprint)                                                                                                               |
+| `SIM`     | flake8-simplify           | `SIM102` (collapsible-if), `SIM108` (if-else-block-instead-of-if-exp), `SIM110` (reimplemented-builtin)                                       |
+| `PL`      | pylint                    | `PLC0414` (useless-import-alias), `PLE1205` (logging-too-many-args), `PLR0913` (too-many-arguments), `PLW0602` (global-variable-not-assigned) |
+| `PTH`     | flake8-use-pathlib        | `PTH100` (os-path-abspath), `PTH118` (os-path-join), `PTH123` (builtin-open)                                                                  |
+| `RUF`     | ruff-specific             | `RUF001` (ambiguous-unicode-character), `RUF005` (collection-literal-concatenation), `RUF013` (implicit-optional)                             |
+| `D`       | pydocstyle                | `D100` (undocumented-public-module), `D103` (undocumented-public-function), `D400` (first-line-should-end-with-period)                        |
+| `ANN`     | flake8-annotations        | `ANN001` (missing-type-function-argument), `ANN201` (missing-return-type-public-function)                                                     |
+| `ARG`     | flake8-unused-arguments   | `ARG001` (unused-function-argument), `ARG002` (unused-method-argument)                                                                        |
+| `ERA`     | eradicate                 | `ERA001` (commented-out-code)                                                                                                                 |
+| `TCH`     | flake8-type-checking      | `TCH001` (typing-only-first-party-import), `TCH002` (typing-only-third-party-import)                                                          |
+| `FBT`     | flake8-boolean-trap       | `FBT001` (boolean-typed-positional-argument), `FBT002` (boolean-default-value-positional-argument)                                            |
+| `ICN`     | flake8-import-conventions | `ICN001` (unconventional-import-alias) — e.g., `import numpy as np`                                                                           |
+| `PIE`     | flake8-pie                | `PIE790` (unnecessary-placeholder), `PIE804` (no-unnecessary-dict-kwargs)                                                                     |
+| `RSE`     | flake8-raise              | `RSE102` (unnecessary-paren-on-raise-exception)                                                                                               |
+| `RET`     | flake8-return             | `RET501` (unnecessary-return-none), `RET504` (unnecessary-assign)                                                                             |
+| `TID`     | flake8-tidy-imports       | `TID252` (relative-imports) — ban relative imports                                                                                            |
+| `PERF`    | perflint                  | `PERF101` (unnecessary-list-cast), `PERF401` (manual-list-comprehension)                                                                      |
+| `FURB`    | refurb                    | `FURB105` (print-empty-string), `FURB118` (reimplemented-operator)                                                                            |
+
+**Tip:** Run `ruff rule <CODE>` to see the full description of any rule. Run `ruff linter` to see all available rule groups.
+
+## Rule Selection
+
+Configure in `pyproject.toml`:
+
+```toml
+[tool.ruff.lint]
+select = [
+  "E", "W",    # pycodestyle
+  "F",         # pyflakes
+  "I",         # isort
+  "B",         # flake8-bugbear
+  "S",         # flake8-bandit
+  "UP",        # pyupgrade
+  "SIM",       # flake8-simplify
+  "T20",       # flake8-print
+  "RUF",       # ruff-specific
+]
+ignore = [
+  "E501",      # line-too-long (handled by formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]  # allow assert in tests
+"__init__.py" = ["F401"]  # allow unused imports in __init__
+```
+
+Or in `ruff.toml` (same syntax without `[tool.ruff]` prefix):
+
+```toml
+[lint]
+select = ["E", "F", "I", "B"]
+```
+
+### Selecting individual rules vs groups
+
+- `"F"` enables all pyflakes rules
+- `"F401"` enables only `F401`
+- `"ALL"` enables everything (noisy — use `ignore` to subtract)
+- Use `extend-select` to add rules without overriding the default set
+
+## Custom Rules
+
+**Ruff does not support user-defined rules.** If no existing rule covers your pattern:
+
+1. **Configure existing rules** — many rules accept options (e.g., `flake8-import-conventions` lets you set allowed aliases)
+2. **Use `ruff.lint.flake8-import-conventions.aliases`** — for import alias enforcement
+3. **Use `ruff.lint.flake8-tidy-imports.banned-api`** — for banning specific imports/modules
+4. **Use ast-grep** — for arbitrary AST pattern matching, reference via `enforce()` with an ast-grep rule
+5. **Write a Pylint checker** — if you need the full power of a custom rule with AST analysis, use Pylint (Ruff can coexist with Pylint in CI)
+
+```toml
+# Ban specific APIs without a custom rule
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"os.system".msg = "Use subprocess.run instead."
+"typing.Dict".msg = "Use dict instead (PEP 585)."
+```
+
+## Auto-Fix
+
+Ruff provides auto-fix for many rules:
+
+```bash
+ruff check --fix              # apply safe fixes only
+ruff check --fix --unsafe-fixes  # include unsafe fixes
+ruff check --fix-only         # only fix, don't report remaining violations
+```
+
+**Safe vs unsafe fixes:**
+
+- **Safe** — guaranteed to not change semantics (e.g., removing unused imports)
+- **Unsafe** — may change semantics (e.g., `UP007` rewriting `Optional[X]` to `X | None` can break runtime type checking)
+
+Check fixability per rule with `ruff rule <CODE>` — it shows whether the rule has a fix and if it's safe.
+
+### vigiles enforce() reference
+
+```typescript
+enforce("ruff/F401", "Remove unused imports.");
+enforce("ruff/T201", "Use logging module instead of print.");
+enforce("ruff/S101", "Don't use assert in production code.");
+```
+
+vigiles checks `ruff rule <CODE>` and verifies the rule exists, then parses `ruff check --show-settings` to confirm it's enabled.
+
+## Edge Cases and Gotchas
+
+### Ruff vs Pylint (PL prefix)
+
+Ruff reimplements many Pylint rules with the `PL` prefix. The mapping is not 1:1 — some Pylint rules have no Ruff equivalent, and Ruff's implementations may differ in edge cases.
+
+| Ruff code | Pylint equivalent                      | Notes         |
+| --------- | -------------------------------------- | ------------- |
+| `PLR0913` | `R0913` (too-many-arguments)           | Same behavior |
+| `PLC0414` | `C0414` (useless-import-alias)         | Same behavior |
+| `PLW0602` | `W0602` (global-variable-not-assigned) | Same behavior |
+| `PLE1205` | `E1205` (logging-too-many-args)        | Same behavior |
+
+If the project uses both Ruff and Pylint, disable Pylint rules that Ruff already covers to avoid duplicate reports.
+
+### Preview rules
+
+Some rules are behind `--preview` flag. These are not stable and may change between versions. Don't use `enforce()` on preview rules unless you pin the Ruff version.
+
+```toml
+[tool.ruff]
+preview = true  # enables preview rules
+```
+
+### Formatter vs linter conflicts
+
+Ruff has both a linter (`ruff check`) and a formatter (`ruff format`). Some linter rules conflict with the formatter:
+
+- `E501` (line-too-long) — the formatter handles line length; disable in the linter
+- `W291`/`W292`/`W293` — whitespace rules handled by formatter
+- `COM812` (missing-trailing-comma) — conflicts with formatter in some cases
+
+The Ruff docs recommend: `ignore = ["E501", "W291", "W292", "W293"]` when using `ruff format`.
+
+### Monorepo config inheritance
+
+Ruff resolves config by walking up from the file being linted. In a monorepo:
+
+- Each package can have its own `pyproject.toml` with `[tool.ruff]`
+- A root config applies to all packages unless overridden
+- Use `extend` to inherit from a shared config: `extend = "../../pyproject.toml"`
+
+vigiles discovers Ruff config at `basePath` only. In a monorepo, run vigiles from each package root.
+
+## Mapping PR Feedback to Rule Strategy
+
+| PR comment pattern            | Best approach                                                      |
+| ----------------------------- | ------------------------------------------------------------------ |
+| "Remove unused imports"       | `ruff/F401` — already exists                                       |
+| "Don't use print()"           | `ruff/T201` — already exists                                       |
+| "Sort your imports"           | `ruff/I001` — already exists                                       |
+| "Use pathlib not os.path"     | `ruff/PTH*` — enable the PTH group                                 |
+| "Don't use assert in prod"    | `ruff/S101` — already exists, ignore in tests via per-file-ignores |
+| "Remove commented-out code"   | `ruff/ERA001` — already exists                                     |
+| "Add type annotations"        | `ruff/ANN*` — enable the ANN group                                 |
+| "Use comprehensions"          | `ruff/C4*` — enable the C4 group                                   |
+| "Don't shadow builtins"       | `ruff/A001` / `A002` — already exists                              |
+| "Simplify this if"            | `ruff/SIM102` / `SIM108` — already exists                          |
+| "Don't use mutable defaults"  | `ruff/B006` — already exists                                       |
+| "Ban specific import"         | `flake8-tidy-imports.banned-api` config — no custom rule needed    |
+| "Naming convention violated"  | `ruff/N*` — enable the N group                                     |
+| "Don't use os.system"         | `flake8-tidy-imports.banned-api` config                            |
+| "Complex pattern not in Ruff" | Write a Pylint checker or use ast-grep                             |

package/skills/linter-docs/stylelint.md

@@ -0,0 +1,247 @@
+# Stylelint — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+
+## Check Existing Plugins First
+
+Before writing a custom rule, search these packages — the pattern may already be covered:
+
+| Plugin                                      | Scope                    | Key rules                                                                                                                                   |
+| ------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stylelint-config-standard`                 | Standard CSS conventions | Extends `stylelint-config-recommended`, adds `declaration-block-no-redundant-longhand-properties`, `shorthand-property-no-redundant-values` |
+| `stylelint-config-recommended`              | Error prevention         | `no-descending-specificity`, `no-duplicate-selectors`, `declaration-block-no-duplicate-properties`                                          |
+| `stylelint-order`                           | Property ordering        | `order/properties-order`, `order/properties-alphabetical-order` — configurable sort orders                                                  |
+| `stylelint-scss`                            | SCSS syntax              | `scss/no-duplicate-mixins`, `scss/no-unused-private-members`, `scss/at-rule-no-unknown`, `scss/dollar-variable-pattern`                     |
+| `stylelint-config-css-modules`              | CSS Modules              | Adjusts rules for `:global`, `:local`, `composes` syntax                                                                                    |
+| `stylelint-config-tailwindcss`              | Tailwind CSS             | Allows Tailwind directives (`@tailwind`, `@apply`, `@screen`)                                                                               |
+| `stylelint-no-unsupported-browser-features` | Browser compat           | Flags CSS features not supported by your browserslist targets                                                                               |
+| `stylelint-declaration-strict-value`        | Value enforcement        | Require variables/functions for specific properties (colors, fonts, z-index)                                                                |
+| `stylelint-config-clean-order`              | Property order           | Opinionated property ordering (positioning → box model → typography → visual → misc)                                                        |
+| `stylelint-config-prettier`                 | Prettier compat          | Disables rules that conflict with Prettier (deprecated in Stylelint v15+)                                                                   |
+| `stylelint-a11y`                            | Accessibility            | `a11y/no-outline-none`, `a11y/no-text-size-adjust`, `a11y/media-prefers-reduced-motion`                                                     |
+
+**Tip:** Stylelint v15+ removed all stylistic rules (spacing, formatting). Use Prettier for formatting, Stylelint for correctness.
+
+## Rule Anatomy
+
+Every Stylelint rule is a function that receives options and returns a checker:
+
+```js
+const stylelint = require("stylelint");
+
+const ruleName = "plugin/no-important";
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  rejected: "Unexpected !important — use utility classes instead.",
+});
+const meta = { url: "https://example.com/rules/no-important" };
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = (primary, secondary, context) => {
+  return (root, result) => {
+    const validOptions = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+    if (!validOptions) return;
+
+    root.walkDecls((decl) => {
+      if (decl.important) {
+        stylelint.utils.report({
+          message: messages.rejected,
+          node: decl,
+          result,
+          ruleName,
+        });
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = meta;
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+```
+
+### Key concepts
+
+| Concept                             | Purpose                                    | Notes                                                     |
+| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
+| `primary`                           | First option (usually `true` or a pattern) | What the user passes in config                            |
+| `secondary`                         | Second option (usually an object)          | Additional configuration                                  |
+| `context`                           | Execution context                          | Contains `fix` boolean for auto-fix mode                  |
+| `root`                              | PostCSS AST root node                      | Entry point for walking the CSS tree                      |
+| `result`                            | Results accumulator                        | Pass to `stylelint.utils.report()`                        |
+| `stylelint.utils.report()`          | Report a violation                         | Canonical way to report — handles severity, ignores, etc. |
+| `stylelint.utils.validateOptions()` | Validate rule config                       | Returns false if config is invalid                        |
+
+### PostCSS AST node types
+
+| Node type     | What it represents      | Walker method         | Example                     |
+| ------------- | ----------------------- | --------------------- | --------------------------- |
+| `Root`        | Entire stylesheet       | —                     | Top-level container         |
+| `Rule`        | Selector + declarations | `root.walkRules()`    | `.button { color: red }`    |
+| `Declaration` | Property: value pair    | `root.walkDecls()`    | `color: red`                |
+| `AtRule`      | `@` rule                | `root.walkAtRules()`  | `@media (min-width: 768px)` |
+| `Comment`     | CSS comment             | `root.walkComments()` | `/* comment */`             |
+
+Properties on `Declaration`: `decl.prop` (property name), `decl.value` (value string), `decl.important` (boolean).
+
+## Configuration
+
+### `.stylelintrc.json`
+
+```json
+{
+  "extends": ["stylelint-config-standard"],
+  "plugins": ["stylelint-order"],
+  "rules": {
+    "declaration-no-important": true,
+    "selector-max-specificity": "0,3,0",
+    "order/properties-alphabetical-order": true
+  }
+}
+```
+
+### `stylelint.config.js` (flat config)
+
+```js
+module.exports = {
+  extends: ["stylelint-config-standard"],
+  rules: {
+    "declaration-no-important": true,
+  },
+  overrides: [
+    {
+      files: ["**/*.scss"],
+      extends: ["stylelint-config-standard-scss"],
+    },
+  ],
+};
+```
+
+### Key config concepts
+
+- **`extends`** — inherit from shared configs (order matters — later overrides earlier)
+- **`plugins`** — load additional rule packages
+- **`rules`** — enable/disable/configure individual rules (`true`, `null`, or `[value, options]`)
+- **`overrides`** — per-file rule configuration (like ESLint overrides)
+
+## Testing Rules
+
+```js
+const { lint } = require("stylelint");
+
+async function testRule() {
+  const result = await lint({
+    code: "a { color: pink !important; }",
+    config: {
+      plugins: ["./plugin-no-important.js"],
+      rules: { "plugin/no-important": true },
+    },
+  });
+
+  console.log(result.results[0].warnings);
+  // [{ rule: "plugin/no-important", text: "Unexpected !important...", line: 1, column: 19 }]
+}
+```
+
+For plugin development, use `jest-preset-stylelint` or test via `lint()` directly.
+
+**Testing best practices:**
+
+1. **Test with `lint()` API** — canonical method, works with any test runner
+2. **Test valid and invalid cases** — ensure no false positives
+3. **Test with SCSS/Less** if the plugin should support preprocessor syntax
+4. **Test `overrides`** — if the rule has options, test each configuration
+
+### vigiles enforce() reference
+
+```typescript
+enforce("stylelint/declaration-no-important", "Use utility classes instead.");
+enforce(
+  "stylelint/selector-max-specificity",
+  "Keep specificity low for maintainability.",
+);
+```
+
+vigiles loads Stylelint config via `createLinter` + `getConfigForFile`, checks if the rule value is not `null`.
+
+## Edge Cases and Gotchas
+
+### CSS-in-JS
+
+Stylelint supports CSS-in-JS via custom syntaxes:
+
+```json
+{
+  "overrides": [
+    {
+      "files": ["**/*.{js,jsx,ts,tsx}"],
+      "customSyntax": "@stylelint/postcss-css-in-js"
+    }
+  ]
+}
+```
+
+Note: `@stylelint/postcss-css-in-js` is deprecated as of Stylelint v15. For styled-components / emotion, consider `postcss-styled-syntax` or lint extracted CSS instead.
+
+### SCSS / Less
+
+Use dedicated configs:
+
+- SCSS: `stylelint-config-standard-scss` (includes `stylelint-scss` plugin)
+- Less: `postcss-less` as `customSyntax`
+
+SCSS nesting (`&-modifier`) and mixins may trigger false positives in standard rules. The SCSS config handles this.
+
+### Prettier conflicts (v15+)
+
+Stylelint v15 removed all stylistic rules. If upgrading from v14:
+
+- Remove `stylelint-config-prettier` (no longer needed)
+- Remove manual disables of formatting rules (`indentation`, `string-quotes`, etc.)
+- Stylelint now handles correctness only; Prettier handles formatting
+
+### Property order plugins
+
+`stylelint-order` and `stylelint-config-clean-order` can conflict. Use one ordering strategy:
+
+- Alphabetical: `order/properties-alphabetical-order`
+- Grouped: `order/properties-order` with a custom group list
+- Clean order: extend `stylelint-config-clean-order` (opinionated groups)
+
+### `extends` order matters
+
+```json
+{
+  "extends": ["stylelint-config-standard", "stylelint-config-prettier"]
+}
+```
+
+Later configs override earlier ones. Put base configs first, overrides last.
+
+### Monorepo considerations
+
+- Stylelint resolves config from the file being linted, walking up directories
+- Each package can have its own `.stylelintrc.json`
+- vigiles checks Stylelint config via `createLinter({ cwd: basePath })` — in a monorepo, run from each package root
+
+## Mapping PR Feedback to Rule Strategy
+
+| PR comment pattern           | Best approach                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------- |
+| "Don't use !important"       | `stylelint/declaration-no-important` — already exists                             |
+| "Keep specificity low"       | `stylelint/selector-max-specificity` with threshold                               |
+| "Sort properties"            | `stylelint-order` plugin — `order/properties-alphabetical-order` or custom groups |
+| "Don't use ID selectors"     | `stylelint/selector-max-id` — already exists                                      |
+| "Use variables for colors"   | `stylelint-declaration-strict-value` plugin                                       |
+| "No vendor prefixes"         | `stylelint/property-no-vendor-prefix`, `value-no-vendor-prefix`                   |
+| "Don't nest too deep"        | `stylelint/selector-max-compound-selectors` with threshold                        |
+| "Use modern CSS"             | `stylelint/declaration-property-value-no-unknown` + browserslist                  |
+| "Remove empty blocks"        | `stylelint/block-no-empty` — already exists                                       |
+| "Don't duplicate properties" | `stylelint/declaration-block-no-duplicate-properties` — already exists            |
+| "Use shorthand"              | `stylelint/declaration-block-no-redundant-longhand-properties` — already exists   |
+| "Font naming convention"     | `stylelint/font-family-name-quotes` — already exists                              |
+| "No unknown @rules"          | `stylelint/at-rule-no-unknown` (or `scss/at-rule-no-unknown` for SCSS)            |

package/skills/migrate-to-spec/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: migrate-to-spec
+description: Convert an existing hand-written CLAUDE.md into a typed .spec.ts file for incremental adoption
+disable-model-invocation: true
+argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
+---
+
+Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed `CLAUDE.md.spec.ts` file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
+
+> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles audit` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
+
+## Instructions
+
+### Step 1: Read the Existing File
+
+Read the target instruction file (default: `CLAUDE.md` in the repo root). If the user specified a path, use that.
+
+Also check if vigiles is installed: look for `vigiles` in `package.json` devDependencies. If not, suggest:
+
+```bash
+npm install -D vigiles
+```
+
+### Step 2: Parse the Structure
+
+Identify these sections in the markdown:
+
+- **Commands** — lines like `` `npm run build` — description `` or ``- `command` — description``
+- **Key files** — lines like `` `src/foo.ts` — description `` listing important files
+- **Rules** — `###` headings with `**Enforced by:**` or `**Guidance only**` annotations
+- **Prose sections** — everything else (positioning, architecture, principles, etc.)
+
+For each rule, classify it:
+
+- Has `**Enforced by:** \`linter/rule\``→`enforce("linter/rule", "why")`
+- Has `**Enforced by:** \`code-review\``or similar non-linter →`guidance("...")`
+- Has `**Guidance only**` → `guidance("...")`
+- Has no annotation → mark as TODO for the user to classify
+
+### Step 3: Generate the Spec File
+
+Create `CLAUDE.md.spec.ts` (or the appropriate name based on the source file) with this structure:
+
+```typescript
+import {
+  claude,
+  enforce,
+  guidance,
+  check,
+  every,
+  file,
+  cmd,
+  ref,
+  instructions,
+} from "vigiles/spec";
+
+export default claude({
+  sections: {
+    // Prose sections here
+  },
+
+  keyFiles: {
+    // Key files here
+  },
+
+  commands: {
+    // Commands here
+  },
+
+  rules: {
+    // Rules here
+  },
+});
+```
+
+**Important guidelines:**
+
+- Use `file()` refs in sections where file paths appear in backticks — this enables stale reference detection
+- Use `cmd()` refs for any `npm run` commands mentioned in sections
+- Convert `**Enforced by:** \`code-review\``rules to`guidance()` — code review is not a mechanical enforcement
+- For rules with no annotation, add a `// TODO: classify as enforce() or guidance()` comment
+- Keep rule IDs as kebab-case versions of the heading text
+- Preserve the `**Why:**` text as the second argument to `enforce()` or `guidance()`
+- If sections reference other files or skills, use `ref()` for cross-references
+
+### Step 4: Verify the Spec Compiles
+
+Run:
+
+```bash
+npm run build
+npx vigiles compile CLAUDE.md.spec.ts
+```
+
+Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, key files, and prose content should be preserved.
+
+### Step 5: Present the Result
+
+Show the user:
+
+1. The generated spec file
+2. How many rules were converted (enforce vs guidance vs TODO)
+3. How many file/cmd refs were added for stale reference detection
+4. The command to compile: `npx vigiles compile`
+5. The command to verify: `npx vigiles check`
+
+Ask if they want you to write the file. If yes, also suggest adding to `.gitignore` or updating CI to run `vigiles compile` and `vigiles check`.
+
+### Step 6: Optional — Set Up CI
+
+If the user wants CI integration, suggest adding to their GitHub Actions workflow:
+
+```yaml
+- name: Compile specs
+  run: npx vigiles compile
+- name: Verify integrity
+  run: npx vigiles check
+```
+
+Or using the vigiles GitHub Action:
+
+```yaml
+- uses: zernie/vigiles@main
+  with:
+    command: check
+```

package/skills/pr-to-lint-rule/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: pr-to-lint-rule
+description: Convert a recurring PR review comment into an automated lint rule with tests and spec entry
+disable-model-invocation: true
+argument-hint: <description of recurring PR feedback>
+---
+
+Convert a recurring PR review comment into an automated lint rule.
+
+## Arguments
+
+$ARGUMENTS — A natural language description of the pattern to enforce. Examples:
+
+- "we keep telling people not to import directly from antd, use our design system barrel file instead"
+- "people forget to use our custom logger instead of console.log"
+- "don't use unwrap() in production code, use expect() or proper error handling"
+- "API route handlers must use the withAuth wrapper"
+
+## Instructions
+
+You are generating an automated lint rule from a recurring code review pattern. Follow these steps:
+
+### Step 1: Detect the Project Language and Toolchain
+
+Look at the repository to determine:
+
+- **Primary language** (JS/TS, Python, Rust, Go, Ruby, etc.)
+- **Linter in use** (ESLint, Ruff, Clippy, golangci-lint, RuboCop, etc.)
+- **Testing framework** (Vitest, Jest, pytest, cargo test, etc.)
+- **Existing custom rules** (to match conventions)
+
+**If the language or linter cannot be confidently detected** (e.g. polyglot repo, no linter config, or multiple candidates), **ask the user** which language and linter to target before generating anything.
+
+### Step 2: Generate the Lint Rule
+
+Based on the detected (or user-specified) language, generate the appropriate rule type:
+
+**Read the linter-specific reference doc before generating.** Each doc covers existing plugins to check first, rule/lint anatomy, AST patterns, auto-fix safety, testing, and edge cases.
+
+| Language              | Linter    | Reference doc                 |
+| --------------------- | --------- | ----------------------------- |
+| JavaScript/TypeScript | ESLint    | `../linter-docs/eslint.md`    |
+| Python                | Ruff      | `../linter-docs/ruff.md`      |
+| Python                | Pylint    | `../linter-docs/pylint.md`    |
+| Ruby                  | RuboCop   | `../linter-docs/rubocop.md`   |
+| Rust                  | Clippy    | `../linter-docs/clippy.md`    |
+| CSS                   | Stylelint | `../linter-docs/stylelint.md` |
+
+For all linters, follow this order:
+
+1. **Check existing plugins/rules first** — see the plugin table in the linter doc
+2. **Try built-in config options** — most linters have `no-restricted-*` or equivalent rules that handle one-off patterns without custom code
+3. **Only write a custom rule** when you need AST analysis, auto-fix, or configurable options beyond what exists
+
+If a custom rule is needed, the reference doc provides: rule anatomy, AST node cheat sheet, auto-fix/suggest patterns, testing examples, and registration instructions.
+
+#### For Go (go/analysis)
+
+No linter doc yet. Generate an analyzer using `golang.org/x/tools/go/analysis` with `analysistest` tests.
+
+#### For other languages
+
+Generate the most idiomatic linting approach with test cases and integration instructions.
+
+### Step 3: Add to Instruction File
+
+**If the project uses v2 specs** (has `CLAUDE.md.spec.ts`):
+
+Add an `enforce()` rule to the spec file:
+
+```typescript
+"<rule-id>": enforce("<linter>/<rule-name>", "<why>"),
+```
+
+Then run `npx vigiles compile` to regenerate CLAUDE.md.
+
+**If the project uses v1** (hand-written CLAUDE.md):
+
+Append an annotation block:
+
+```markdown
+### <Rule title — imperative, concise>
+
+**Enforced by:** `<linter>/<rule-name>`
+**Why:** <One sentence explaining the architectural reason>
+```
+
+### Step 4: Present the Output
+
+Show the user:
+
+1. All generated files with full contents
+2. Step-by-step integration instructions
+3. The spec rule or CLAUDE.md block to add
+4. How to verify it works (run the linter, expect it to catch a violation)
+
+Ask the user if they want you to write the files and update the spec/CLAUDE.md.