vigiles 2.0.0 → 2.2.0

package/docs/spec-format.md

@@ -1,194 +0,0 @@
-# Spec Format Reference
-
-vigiles specs are TypeScript files (`*.spec.ts`) that compile to markdown instruction files. The spec is the source of truth; the markdown is a build artifact.
-
-## CLAUDE.md Specs
-
-Use `claude()` to define a CLAUDE.md spec. Export it as the default export.
-
-```ts
-import { claude, enforce, guidance, file, cmd, ref, instructions } from "vigiles";
-
-export default claude({
-  target: "CLAUDE.md",          // or "AGENTS.md", or ["CLAUDE.md", "AGENTS.md"]
-  sections: { ... },
-  keyFiles: { ... },
-  commands: { ... },
-  rules: { ... },
-  maxSectionLines: 30,          // optional: cap per-section line count
-});
-```
-
-### `target`
-
-`string | string[]` -- Output filename(s). Defaults to `"CLAUDE.md"`. Also used as the `# Heading` in compiled output. Pass an array to compile one spec to multiple targets:
-
-```ts
-target: ["CLAUDE.md", "AGENTS.md"],  // emits both from one spec
-```
-
-### `sections`
-
-`Record<string, string | InstructionFragment[]>` -- Named prose sections. Each key becomes a `## Heading` in the compiled output (first letter uppercased). Values are either plain strings or tagged templates via `instructions` with embedded `file()`, `cmd()`, and `ref()` references.
-
-```ts
-sections: {
-  architecture: `Two rule types: enforce() and guidance().`,
-  setup: instructions`See ${file("docs/setup.md")} and run ${cmd("npm install")}.`,
-}
-```
-
-### `keyFiles`
-
-`Record<string, string>` -- File paths mapped to descriptions. Each path is verified via `existsSync` at compile time. Compiles to a bullet list under `## Key Files`.
-
-```ts
-keyFiles: {
-  "src/spec.ts": "Type system and builder functions",
-  "src/compile.ts": "Compiler: spec to markdown with SHA-256 hash",
-}
-```
-
-### `commands`
-
-`Record<string, string>` -- Commands mapped to descriptions. `npm run <script>` and `npm <lifecycle>` commands are verified against `package.json` scripts at compile time. Compiles to a bullet list under `## Commands`.
-
-```ts
-commands: {
-  "npm run build": "Compile TypeScript to dist/",
-  "npm test": "Build and run all tests",
-}
-```
-
-### `rules`
-
-`Record<string, Rule>` -- Rule ID mapped to an `enforce()` or `guidance()` rule. The ID is kebab-cased by convention and is converted to a Title Case `### Heading` in compiled output. See [Rule Types](#rule-types) below.
-
-## SKILL.md Specs
-
-Use `skill()` to define a SKILL.md spec. Compiles to markdown with YAML frontmatter.
-
-```ts
-import { skill, file, cmd, ref, instructions } from "vigiles";
-
-export default skill({
-  name: "pr-to-lint-rule",
-  description: "Convert PR feedback into an automated lint rule",
-  argumentHint: "<description of recurring PR feedback>",
-  disableModelInvocation: true,
-  body: instructions`
-    Check ${file("eslint.config.ts")} for existing rules.
-    Run ${cmd("npm test")} to verify.
-    See ${ref("skills/other/SKILL.md")} for format.
-  `,
-});
-```
-
-| Field                    | Type                              | Required | Description                                         |
-| ------------------------ | --------------------------------- | -------- | --------------------------------------------------- |
-| `name`                   | `string`                          | yes      | Skill name (used in YAML frontmatter)               |
-| `description`            | `string`                          | yes      | Short description (frontmatter)                     |
-| `argumentHint`           | `string`                          | no       | Hint for the argument (frontmatter)                 |
-| `disableModelInvocation` | `boolean`                         | no       | Disable model invocation flag (frontmatter)         |
-| `body`                   | `string \| InstructionFragment[]` | yes      | Instruction body -- plain string or tagged template |
-
-## Reference Helpers
-
-Reference helpers create branded types that the compiler validates at compile time.
-
-### `file(path)`
-
-Returns a `FileRef` containing a `VerifiedPath`. The path is verified to exist via `existsSync` at compile time. Compiles to a backtick path in markdown: `` `path/to/file.ts` ``.
-
-### `cmd(command)`
-
-Returns a `CmdRef` containing a `VerifiedCmd`. For npm commands, the script is verified against `package.json` at compile time. Compiles to a backtick command: `` `npm run build` ``.
-
-### `ref(path)`
-
-Returns a `SkillRef` containing a `VerifiedRef`. The path is verified to exist at compile time. Compiles to a markdown link: `[dirname](path)`.
-
-### `instructions`
-
-Tagged template literal that interleaves strings and refs. Use it for `sections` values in `claude()` or the `body` of `skill()`.
-
-```ts
-instructions`Check ${file("tsconfig.json")} then run ${cmd("npm test")}.`;
-// Returns InstructionFragment[] -- the compiler renders and validates each ref.
-```
-
-## Rule Types
-
-### `enforce(linterRule, why)`
-
-Declares a rule delegated to an external linter. The `linterRule` accepts template literal types:
-
-- `${BuiltinLinter}/${string}` where BuiltinLinter is `eslint`, `stylelint`, `ruff`, `clippy`, `pylint`, or `rubocop`
-- `@${scope}/${rule}` for scoped ESLint plugins (e.g., `@typescript-eslint/no-explicit-any`)
-
-At compile time, vigiles verifies the rule exists in the linter's catalog and is enabled in the project's config. Compiles to `**Enforced by:** ` followed by the linter rule in backticks.
-
-```ts
-rules: {
-  "no-console-log": enforce("eslint/no-console", "Use structured logger."),
-  "no-print": enforce("ruff/T201", "Use logging module."),
-}
-```
-
-### `guidance(text)`
-
-Declares a prose-only rule with no mechanical enforcement. Guidance rules still participate in the monotonicity proof system: once a rule exists, it can be strengthened ( `guidance` → `enforce` ) but never weakened or removed without an explicit allowlist.
-
-```ts
-rules: {
-  "prefer-composition": guidance("Prefer composition over inheritance."),
-}
-```
-
-Compiles to: `**Guidance only** -- <text>`.
-
-## Branded Types
-
-`VerifiedPath`, `VerifiedCmd`, and `VerifiedRef` are branded string types (`string & { readonly [__brand]: "..." }`). They distinguish compiler-verified references from raw strings.
-
-- `file()` produces `FileRef` containing `VerifiedPath`
-- `cmd()` produces `CmdRef` containing `VerifiedCmd`
-- `ref()` produces `SkillRef` containing `VerifiedRef`
-
-The compiler only accepts these branded types in path-sensitive positions. This prevents passing unverified strings where a verified reference is expected -- the TypeScript compiler catches the error at authoring time.
-
-## Configuration
-
-Create `vigiles.config.ts` with `defineConfig()`:
-
-```ts
-import { defineConfig } from "vigiles";
-
-export default defineConfig({
-  specs: "**/*.spec.ts", // glob pattern for spec discovery (default: "**/*.spec.ts")
-  discover: true, // auto-discover linter rules for coverage reporting
-  maxRules: 50, // maximum rules per spec file
-  maxTokens: 2000, // maximum estimated tokens for compiled output (~4 chars/token)
-});
-```
-
-| Option      | Type      | Description                                             |
-| ----------- | --------- | ------------------------------------------------------- |
-| `specs`     | `string`  | Glob pattern to discover spec files                     |
-| `discover`  | `boolean` | Auto-discover linter rules for coverage reporting       |
-| `maxRules`  | `number`  | Compilation fails if a spec exceeds this rule count     |
-| `maxTokens` | `number`  | Compilation fails if estimated tokens exceed this limit |
-
-## Hash Verification
-
-Every compiled file starts with a SHA-256 integrity hash comment:
-
-```
-<!-- vigiles:sha256:a1b2c3d4e5f67890 compiled from CLAUDE.md.spec.ts -->
-```
-
-The hash covers the full compiled content (excluding the hash line itself), truncated to 16 hex characters.
-
-### `vigiles audit`
-
-Verifies that each compiled file's hash matches its content, reports linter rule coverage gaps, and suggests guidance rules that could be upgraded to `enforce()`. If someone manually edits the markdown, the hash will no longer match, and `vigiles audit` reports the file as modified. This ensures the spec remains the source of truth.

package/eslint.config.mjs

@@ -1,79 +0,0 @@
-import eslint from "@eslint/js";
-import tseslint from "@typescript-eslint/eslint-plugin";
-import tsparser from "@typescript-eslint/parser";
-import sonarjs from "eslint-plugin-sonarjs";
-import globals from "globals";
-
-export default [
-  {
-    ignores: ["dist/", "node_modules/"],
-  },
-  eslint.configs.recommended,
-  {
-    files: ["src/**/*.ts"],
-    languageOptions: {
-      parser: tsparser,
-      globals: {
-        ...globals.node,
-      },
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-    plugins: {
-      "@typescript-eslint": tseslint,
-      sonarjs,
-    },
-    rules: {
-      ...tseslint.configs["strict-type-checked"]?.rules,
-      // TypeScript handles these better than ESLint
-      "no-undef": "off",
-      "no-unused-vars": "off",
-      // Allow unused vars prefixed with _
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-      ],
-      // We use createRequire legitimately for linter detection
-      "@typescript-eslint/no-require-imports": "off",
-      // Relax some strict rules that are too noisy for this codebase
-      "@typescript-eslint/restrict-template-expressions": "off",
-      "@typescript-eslint/no-unnecessary-condition": "off",
-      // Ban non-null assertions — use proper narrowing instead
-      "@typescript-eslint/no-non-null-assertion": "error",
-
-      // --- Complexity rules ---
-      complexity: ["warn", { max: 15 }],
-      "max-depth": ["warn", { max: 4 }],
-      "max-lines-per-function": [
-        "warn",
-        { max: 80, skipBlankLines: true, skipComments: true },
-      ],
-      "max-params": ["warn", { max: 4 }],
-
-      // --- SonarJS ---
-      "sonarjs/cognitive-complexity": ["warn", 15],
-      "sonarjs/no-duplicate-string": ["warn", { threshold: 4 }],
-      "sonarjs/no-identical-functions": "warn",
-      "sonarjs/no-duplicated-branches": "warn",
-      "sonarjs/no-identical-conditions": "error",
-      "sonarjs/no-identical-expressions": "error",
-      "sonarjs/no-nested-conditional": "warn",
-      "sonarjs/nested-control-flow": ["warn", { maximumNestingLevel: 3 }],
-    },
-  },
-  // Test files: relax promise, assertion, and complexity rules
-  {
-    files: ["src/**/*.test.ts"],
-    rules: {
-      // node:test describe/it return promises that don't need to be awaited
-      "@typescript-eslint/no-floating-promises": "off",
-      "@typescript-eslint/no-unnecessary-type-assertion": "off",
-      // Tests are naturally longer and more repetitive
-      "max-lines-per-function": "off",
-      "sonarjs/no-duplicate-string": "off",
-      "sonarjs/no-identical-functions": "off",
-    },
-  },
-];

package/examples/CLAUDE.md

@@ -1,54 +0,0 @@
-<!-- vigiles:sha256:f683550dbdfab721 compiled from examples/CLAUDE.md.spec.ts -->
-
-# CLAUDE.md
-
-## Positioning
-
-vigiles compiles `.spec.ts` files to instruction files (CLAUDE.md, AGENTS.md, or any markdown target). The spec is the source of truth. The markdown is a build artifact.
-
-The linter cross-referencing engine is the core moat: `enforce("@typescript-eslint/no-floating-promises")` verifies the rule exists AND is enabled in your linter config. Same for ESLint, Ruff, Clippy, Pylint, RuboCop, and Stylelint.
-
-`generate-types` is the second moat: scans all 6 linter APIs, package.json, and project files to emit a `.d.ts` with type unions. The TS compiler then PROVES references are valid at authoring time — typos become type errors, not runtime surprises.
-
-## Architecture
-
-Three rule types in specs: `enforce()` (delegated to external tool), `check()` (vigiles-owned filesystem assertion), `guidance()` (prose only).
-
-Core modules: `src/spec.ts` (types + builders), `src/compile.ts` (compiler), `src/linters.ts` (6-linter cross-referencing engine), `src/generate-types.ts` (type generator).
-
-## Key Files
-
-- `src/spec.ts` — Type system and builder functions
-- `src/compile.ts` — Compiler: spec → markdown with SHA-256 hash
-- `src/linters.ts` — Linter cross-referencing engine (6 linters)
-- `src/generate-types.ts` — Type generator: project state → .d.ts
-- `src/cli.ts` — CLI: compile, check, init, generate-types, discover, adopt
-
-## Commands
-
-- `npm run build` — Compile TypeScript to dist/
-- `npm test` — Build and run all tests
-- `npm run fmt` — Format with prettier
-- `npm run fmt:check` — Check formatting
-
-## Rules
-
-### Zero Config By Default
-
-**Guidance only** — vigiles compile should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens, catalogOnly).
-
-### Never Skip Tests
-
-**Guidance only** — All tests must pass. If a test requires a CLI tool (pylint, rubocop, ruff, clippy), install the tool, don't skip the test.
-
-### Dont Reimplement Linters
-
-**Guidance only** — Architectural linting belongs in ast-grep/Dependency Cruiser/Steiger. Per-file code rules belong in ESLint/Ruff/Clippy. vigiles owns: compilation, linter cross-referencing, type generation, filesystem assertions, and stale reference detection.
-
-### Format Before Commit
-
-**Guidance only** — Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.
-
-### No Session Links
-
-**Guidance only** — This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.

package/examples/CLAUDE.md.spec.ts

@@ -1,65 +0,0 @@
-/**
- * Example: CLAUDE.md specification for the vigiles project itself.
- *
- * This is the source of truth. CLAUDE.md is a compiled build artifact.
- * Run `vigiles compile` to generate CLAUDE.md from this spec.
- */
-import { claude, guidance } from "../src/spec.js";
-
-export default claude({
-  sections: {
-    positioning: `vigiles compiles \`.spec.ts\` files to instruction files (CLAUDE.md, AGENTS.md, or any markdown target). The spec is the source of truth. The markdown is a build artifact.
-
-The linter cross-referencing engine is the core moat: \`enforce("@typescript-eslint/no-floating-promises")\` verifies the rule exists AND is enabled in your linter config. Same for ESLint, Ruff, Clippy, Pylint, RuboCop, and Stylelint.
-
-\`generate-types\` is the second moat: scans all 6 linter APIs, package.json, and project files to emit a \`.d.ts\` with type unions. The TS compiler then PROVES references are valid at authoring time — typos become type errors, not runtime surprises.`,
-
-    architecture: `Three rule types in specs: \`enforce()\` (delegated to external tool), \`check()\` (vigiles-owned filesystem assertion), \`guidance()\` (prose only).
-
-Core modules: \`src/spec.ts\` (types + builders), \`src/compile.ts\` (compiler), \`src/linters.ts\` (6-linter cross-referencing engine), \`src/generate-types.ts\` (type generator).`,
-  },
-
-  keyFiles: {
-    "src/spec.ts": "Type system and builder functions",
-    "src/compile.ts": "Compiler: spec → markdown with SHA-256 hash",
-    "src/linters.ts": "Linter cross-referencing engine (6 linters)",
-    "src/generate-types.ts": "Type generator: project state → .d.ts",
-    "src/cli.ts": "CLI: compile, check, init, generate-types, discover, adopt",
-  },
-
-  commands: {
-    "npm run build": "Compile TypeScript to dist/",
-    "npm test": "Build and run all tests",
-    "npm run fmt": "Format with prettier",
-    "npm run fmt:check": "Check formatting",
-  },
-
-  rules: {
-    "zero-config-by-default": guidance(
-      "vigiles compile should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens, catalogOnly).",
-    ),
-
-    "never-skip-tests": guidance(
-      "All tests must pass. If a test requires a CLI tool (pylint, rubocop, ruff, clippy), install the tool, don't skip the test.",
-    ),
-
-    "dont-reimplement-linters": guidance(
-      "Architectural linting belongs in ast-grep/Dependency Cruiser/Steiger. Per-file code rules belong in ESLint/Ruff/Clippy. vigiles owns: compilation, linter cross-referencing, type generation, filesystem assertions, and stale reference detection.",
-    ),
-
-    "format-before-commit": guidance(
-      "Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.",
-    ),
-
-    "no-session-links": guidance(
-      "This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.",
-    ),
-
-    // Example: check() rule (commented out because this is a demo spec,
-    // not the project's actual spec — see root CLAUDE.md.spec.ts)
-    // "test-file-pairing": check(
-    //   every("src/**/!(*test|*spec).ts").has("{name}.test.ts"),
-    //   "Every source module should have a corresponding test file.",
-    // ),
-  },
-});

package/examples/SKILL.md

@@ -1,50 +0,0 @@
-<!-- vigiles:sha256:da271d5e41e8e90e compiled from examples/SKILL.md.spec.ts -->
-
----
-
-name: pr-to-lint-rule
-description: Convert a recurring PR review comment into an automated lint rule with tests and CLAUDE.md annotation
-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**, **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.
-
-For JavaScript/TypeScript, generate an ESLint rule using the AST visitor pattern with `meta` and `create(context)`.
-
-### Step 3: Update `CLAUDE.md`
-
-Add the annotation block. See [enforce-rules-format](skills/enforce-rules-format/SKILL.md) for the correct format.
-
-### Step 4: Verify
-
-Run `npm test` to ensure the new rule and tests pass.

package/examples/SKILL.md.spec.ts

@@ -1,57 +0,0 @@
-/**
- * Example: SKILL.md specification for the pr-to-lint-rule skill.
- *
- * This is the source of truth. SKILL.md is a compiled build artifact.
- * Run `vigiles compile` to generate SKILL.md from this spec.
- */
-import { skill, file, cmd, ref, instructions } from "../src/spec.js";
-
-export default skill({
-  name: "pr-to-lint-rule",
-  description:
-    "Convert a recurring PR review comment into an automated lint rule with tests and CLAUDE.md annotation",
-  disableModelInvocation: true,
-  argumentHint: "<description of recurring PR feedback>",
-
-  body: instructions`
-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**, **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.
-
-For JavaScript/TypeScript, generate an ESLint rule using the AST visitor pattern with \`meta\` and \`create(context)\`.
-
-### Step 3: Update ${file("CLAUDE.md")}
-
-Add the annotation block. See ${ref("skills/enforce-rules-format/SKILL.md")} for the correct format.
-
-### Step 4: Verify
-
-Run ${cmd("npm test")} to ensure the new rule and tests pass.
-`,
-});

package/fixtures/example-project/CLAUDE.md

@@ -1,11 +0,0 @@
-<!-- vigiles-disable require-spec -->
-
-# CLAUDE.md
-
-## Code Style
-
-Use TypeScript strict mode. Never use `any`.
-
-## Testing
-
-Run `npm test` before submitting. Every file in src/ should have tests.

package/fixtures/example-project/package.json

@@ -1,9 +0,0 @@
-{
-  "name": "example-project",
-  "version": "1.0.0",
-  "scripts": {
-    "build": "echo build",
-    "test": "echo test",
-    "lint": "echo lint"
-  }
-}

package/fixtures/example-project/src/index.ts

@@ -1,3 +0,0 @@
-export function greet(name: string): string {
-  return `Hello, ${name}!`;
-}

package/fixtures/example-project/src/utils.test.ts

@@ -1,2 +0,0 @@
-import { capitalize } from "./utils";
-console.assert(capitalize("hello") === "Hello");

package/fixtures/example-project/src/utils.ts

@@ -1,3 +0,0 @@
-export function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}

package/research/adoption-strategy.md

@@ -1,111 +0,0 @@
-# vigiles Adoption Strategy
-
-Goal: **`npx vigiles setup && npx skills add zernie/vigiles` works on first run with zero config. The agent starts editing specs automatically — no workflow change required. Start permissive, tighten over time.**
-
-### Adoption Principles
-
-1. **Works on first run.** Setup must succeed in any project without configuration. Auto-detect everything. Create reasonable defaults. Don't block on missing tools.
-2. **Zero workflow change.** After plugin install, the agent edits specs instead of markdown. The user doesn't need to learn a new workflow — they say "update CLAUDE.md" and the plugin handles the redirect.
-3. **Start permissive, tighten later.** First run creates `guidance()` rules (no enforcement). User upgrades to `enforce()` as they add linter rules. `require-spec: false` available for incremental migration.
-4. **Every surface tells you the next step.** `vigiles check` says "run setup." The hook says "edit the spec." The wizard says "install the plugin." No dead ends.
-
----
-
-## Scope: What vigiles Does vs. Doesn't
-
-vigiles compiles typed TypeScript specs to **markdown instruction files** (CLAUDE.md, AGENTS.md). It verifies linter rules, file paths, and commands at compile time. The compiled markdown is the artifact.
-
-**vigiles handles:** CLAUDE.md (Claude Code), AGENTS.md (Codex, GitHub Copilot, any agent that reads AGENTS.md). These are both plain markdown — same compiler, same validation, different `target`.
-
-**vigiles does NOT handle:** `.cursorrules`, `.copilot-instructions.md`, Windsurf format, or any non-markdown target. These have different structures. Use [rule-porter](https://github.com/nichochar/rule-porter) or [rulesync](https://github.com/dyoshikawa/rulesync) to convert compiled markdown to those formats. vigiles is the source; sync tools are the distribution layer.
-
-**No symlinks needed.** AGENTS.md is a first-class target via `target: "AGENTS.md"` or `target: ["CLAUDE.md", "AGENTS.md"]`. The compiler outputs both from one spec.
-
----
-
-## The Setup Wizard
-
-`npx vigiles setup` is the single entry point. It does everything:
-
-1. **Creates spec** — scaffolds `CLAUDE.md.spec.ts` (or `--target=AGENTS.md` variant)
-2. **Generates types** — scans linters, package.json, project files → `.vigiles/generated.d.ts`
-3. **Compiles** — spec → markdown with SHA-256 hash
-4. **Adds CI step** — finds existing GHA workflow and appends `vigiles check` + `generate-types --check`
-5. **Prompts plugin install** — prints `npx skills add zernie/vigiles` with explanation
-
-After setup, the user edits the spec, runs `vigiles compile`, and commits. The plugin handles everything else automatically.
-
----
-
-## Adoption Levels
-
-### Level 0: Discovery
-
-User runs `npx vigiles check` on an existing repo. `require-spec` fires: "No spec file found. Run `npx vigiles setup`." First nudge.
-
-### Level 1: Setup
-
-```bash
-npx vigiles setup
-```
-
-One command. Creates spec, types, compiled markdown, CI step. The user has a working pipeline in under a minute.
-
-### Level 2: Plugin
-
-```bash
-npx skills add zernie/vigiles
-```
-
-Two hooks activate:
-
-- **PreToolUse**: Blocks direct edits to compiled `.md` files. Agent gets redirected to `.spec.ts`.
-- **PostToolUse**: Auto-runs `generate-types` on config changes, `compile` on spec changes.
-
-### Level 3: Multi-Target
-
-```typescript
-export default claude({
-  target: ["CLAUDE.md", "AGENTS.md"],
-  rules: { ... },
-});
-```
-
-One spec, multiple outputs. For non-markdown formats, pipe through rule-porter.
-
-### Level 4: Type Narrowing
-
-Commit `.vigiles/generated.d.ts`. Now `enforce("eslint/no-consolee")` is a type error in the editor. Types narrow `enforce()`, `file()`, `cmd()` via declaration merging.
-
----
-
-## Pain Points (Updated)
-
-| Pain Point                        | Status    | Resolution                                      |
-| --------------------------------- | --------- | ----------------------------------------------- |
-| Multi-step installation           | Fixed     | `vigiles setup` does everything                 |
-| No CI integration from wizard     | Fixed     | Wizard auto-adds GHA step                       |
-| Plugin not mentioned as important | Fixed     | README and wizard both prompt it                |
-| Agent edits compiled .md directly | Fixed     | PreToolUse hook blocks with redirect            |
-| Cursor/Windsurf support           | Won't fix | Out of scope — use sync tools                   |
-| Codex / AGENTS.md                 | Fixed     | First-class target                              |
-| No interactive mode for agents    | Open      | `vigiles setup` works non-interactively already |
-
-## README Structure
-
-The README should have:
-
-1. **Hook** — one compelling sentence
-2. **Problem** — realistic example of rot
-3. **Fix** — the spec that catches it
-4. **Quick Start** — `npx vigiles setup` (one command)
-5. **Three Rule Types** — enforce/check/guidance
-6. **Verified References** — file/cmd/ref
-7. **Type-Safe Rule References** — generate-types + narrowing
-8. **CLI** — reference for all commands
-9. **GitHub Action** — CI snippet
-10. **Plugin** — what it does, install command
-11. **Output Targets** — CLAUDE.md, AGENTS.md, multi-target
-12. **Related Tools** — sync tools for non-markdown formats
-
-No separate installation steps. The wizard IS the installation.