vigiles 4.0.0 → 4.0.2

package/skills/edit-spec/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: edit-spec
-description: Edit a vigiles spec file to update instruction files (CLAUDE.md, AGENTS.md)
-disable-model-invocation: true
+description: Edit a vigiles .spec.ts to change a compiled instruction file (CLAUDE.md / AGENTS.md) — add, modify, or remove a rule, section, command, or key file. Use whenever you need to change a CLAUDE.md/AGENTS.md that carries a vigiles hash (edit the spec, never the artifact), including adding a new enforce()/check()/guidance() rule.
 argument-hint: <what to change — e.g., "add a rule about error handling" or "update the testing section">
 ---
 
@@ -27,7 +26,8 @@ Look for spec files in the repo root:
 - `AGENTS.md.spec.ts` — source for AGENTS.md
 - Any `*.spec.ts` matching instruction files
 
-If no spec exists, suggest: `npx vigiles setup`
+If no spec exists: if there's a hand-written `CLAUDE.md`, suggest the
+`migrate-to-spec` skill; otherwise suggest `npx vigiles init` to scaffold one.
 
 ### Step 2: Read and Understand the Spec
 
@@ -83,11 +83,22 @@ export default claude({
 
 Based on what the user asked for:
 
-**Adding a rule:**
-
-- Determine the type: `enforce()` if a linter rule exists, `check()` for filesystem conventions, `guidance()` for prose-only
-- For `enforce()`: find the actual linter rule name (e.g., `eslint/no-console`, `@typescript-eslint/no-explicit-any`, `ruff/T201`)
-- Add to the `rules` object with a descriptive key
+**Adding a rule** (this absorbs the old `generate-rule` skill):
+
+- **Classify the rule** from the request:
+  - `enforce()` — a linter rule can back it. Check the project's linter configs
+    (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) for a matching rule; also
+    consider an architectural tool (ast-grep, Dependency Cruiser, Steiger). If
+    uncertain whether a rule exists, **ask the user** rather than guessing.
+  - `check()` — a filesystem structural convention ("every X needs a Y"). Only
+    for file-pairing; never for code content.
+  - `guidance()` — can't be mechanically enforced (subjective conventions,
+    process rules, migration context).
+- For `enforce()`: use the real linter rule name (e.g. `eslint/no-console`,
+  `@typescript-eslint/no-explicit-any`, `ruff/T201`).
+- Add to the `rules` object with a kebab-case key derived from the intent,
+  preserving alphabetical order if the existing rules are alphabetical. Import
+  any new builders needed (e.g. `check` and `every` for the first `check()`).
 
 **Updating a section:**
 
@@ -118,10 +129,10 @@ This regenerates the compiled instruction file(s). Review the output for any err
 ### Step 5: Verify
 
 ```bash
-npx vigiles check
+npx vigiles lint
 ```
 
-If the PostToolUse hook is installed (via `npx skills add zernie/vigiles`), compilation happens automatically after you save the spec.
+If the vigiles plugin is installed (`/plugin marketplace add zernie/vigiles` then `/plugin install vigiles@vigiles`, or `npx vigiles init`), the PostToolUse hook recompiles automatically after you save the spec.
 
 ## Important
 

package/skills/linter-docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: linter-docs
+description: Deep linter reference for authoring or debugging a vigiles enforce() rule — plugin tables, AST selectors, type-aware rules, auto-fix, and edge cases for ESLint, Ruff, Pylint, RuboCop, and Stylelint. Use when you need the exact rule name or config for a specific linter, not for running a linter.
+disable-model-invocation: true
+---
+
+Reference material for the linters vigiles cross-references. Open the file for
+the linter you're working with when you need exact rule names, AST selectors,
+or config details to author an `enforce()` rule (or diagnose why one is reported
+missing or disabled).
+
+| Linter    | Reference                                                                              |
+| --------- | -------------------------------------------------------------------------------------- |
+| ESLint    | [`eslint.md`](eslint.md) — plugin table, AST selectors, type-aware rules, auto-fix     |
+| Ruff      | [`ruff.md`](ruff.md) — 800+ reimplemented rules, selection, auto-fix, pyproject config |
+| Pylint    | [`pylint.md`](pylint.md) — plugin table, astroid AST, type inference, custom checkers  |
+| RuboCop   | [`rubocop.md`](rubocop.md) — gem table, node pattern DSL, auto-correct, custom cops    |
+| Stylelint | [`stylelint.md`](stylelint.md) — plugin table, PostCSS AST, custom rules, SCSS         |
+| Clippy    | [`clippy.md`](clippy.md) — Rust lint groups and configuration                          |
+
+These are read by the `strengthen` and `edit-spec` skills when matching a
+guidance rule to a real linter rule. This skill is user-invoked (a reference,
+not an action), so it never fires on its own — open the relevant file directly.

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

@@ -7,7 +7,7 @@ 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.
+> **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 lint` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
 
 ## Instructions
 

package/skills/strengthen/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: strengthen
-description: Upgrade guidance() rules to enforce() by finding existing linter rules that match
-disable-model-invocation: true
+description: Upgrade a vigiles spec's guidance() rules to enforce() — scan the guidance rules in a CLAUDE.md/AGENTS.md spec and find existing linter rules (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) that back them. Use when asked to strengthen, harden, or make vigiles rules enforceable; NOT for general linting or fixing lint errors.
 ---
 
 Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.

package/skills/generate-rule/SKILL.md

@@ -1,64 +0,0 @@
-<!-- vigiles:sha256:a9df2c1748576753 compiled from skills/generate-rule/SKILL.md.spec.ts -->
-
----
-
-name: generate-rule
-description: Add a new enforce(), check(), or guidance() rule to an existing spec file
-disable-model-invocation: true
-argument-hint: <rule>
-
----
-
-## Arguments
-
-- `$1` **rule** — natural-language description of what the rule should enforce, e.g. "no console.log in production code"
-
-## Steps
-
-### Step 1
-
-**Find the spec file.** Look for `CLAUDE.md.spec.ts` in the repo root. If it doesn't exist:
-
-- If there's a hand-written `CLAUDE.md`, suggest running the `migrate-to-spec` skill first.
-- If there's no `CLAUDE.md` either, suggest `npx vigiles init` to scaffold one.
-
-### Step 2
-
-**Classify the rule** from the description ($1):
-
-- **enforce()** — if a linter rule can back it. Check the project's linter configs (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) for a matching rule; also consider an architectural tool (ast-grep, Dependency Cruiser, Steiger). If uncertain whether a rule exists, **ask the user** rather than guessing.
-- **check()** — if it's a filesystem structural convention ("every X needs a Y"). Only for file-pairing; never for code content.
-- **guidance()** — if it can't be mechanically enforced (subjective conventions, process rules, migration context).
-
-### Step 3
-
-**Generate the rule.** Create an entry with a kebab-case ID derived from the description. Examples:
-
-    "no-console": enforce("eslint/no-console", "Use structured logger for observability."),
-
-    "controller-tests": check(
-      every("src/**/*.controller.ts").has("{name}.controller.test.ts"),
-      "Every controller must have a co-located test file.",
-    ),
-
-    "research-before-implementing": guidance(
-      "Google unfamiliar APIs before implementing.",
-    ),
-
-### Step 4
-
-**Add it to the spec.** Read the existing spec file and add the new rule to the `rules` object, preserving alphabetical ordering if the existing rules are alphabetical. Import any new builders needed (e.g. `check` and `every` for the first `check()` rule).
-
-### Step 5
-
-**Compile and verify.** Build and recompile; if compilation fails (e.g. the linter rule doesn't exist), report the error and suggest alternatives. Show the user the updated spec and the compiled `CLAUDE.md` diff.
-
-**Gate** — run the project's build command (retry up to 2×); do not proceed until it passes.
-
-<!-- vigiles:gate role:build retry:2 -->
-
-## Result
-
-This skill is complete when the project's build command passes.
-
-<!-- vigiles:result role:build -->