vigiles 2.5.0 → 3.0.0

package/package.json

@@ -1,25 +1,33 @@
 {
   "name": "vigiles",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
   },
-  "main": "./dist/spec.js",
-  "types": "./dist/spec.d.ts",
+  "main": "./dist/core/spec.js",
+  "types": "./dist/core/spec.d.ts",
   "exports": {
-    ".": "./dist/spec.js",
-    "./spec": "./dist/spec.js",
-    "./compile": "./dist/compile.js",
-    "./linters": "./dist/linters.js",
-    "./eval": "./dist/eval.js",
-    "./harness-test": "./dist/harness-test.js",
+    ".": "./dist/core/spec.js",
+    "./unit": "./dist/unit.js",
+    "./integration": "./dist/integration.js",
+    "./e2e": "./dist/e2e.js",
+    "./linting": "./dist/linting.js",
+    "./testing": "./dist/testing.js",
+    "./claude-code": "./dist/claude-code.js",
+    "./codex": "./dist/codex.js",
+    "./adapter": "./dist/adapter.js",
+    "./spec": "./dist/core/spec.js",
+    "./compile": "./dist/core/compile.js",
+    "./linters": "./dist/core/linters.js",
+    "./eval": "./dist/adapters/claude-code/eval.js",
+    "./harness-test": "./dist/adapters/claude-code/harness-test.js",
     "./harness-assert": "./dist/harness-assert.js",
-    "./run-hook": "./dist/run-hook.js",
-    "./plugin-loader": "./dist/plugin-loader.js",
-    "./mcp": "./dist/mcp.js",
-    "./judge": "./dist/judge.js",
-    "./mock-model": "./dist/mock-model.js",
+    "./run-hook": "./dist/adapters/claude-code/run-hook.js",
+    "./plugin-loader": "./dist/adapters/claude-code/plugin-loader.js",
+    "./mcp": "./dist/core/mcp.js",
+    "./judge": "./dist/adapters/claude-code/judge.js",
+    "./mock-model": "./dist/adapters/claude-code/mock-model.js",
     "./vitest": {
       "types": "./dist/vitest.d.mts",
       "default": "./dist/vitest.mjs"
@@ -35,6 +43,9 @@
     "!dist/**/*.test.d.ts",
     "action.yml",
     ".claude-plugin",
+    "hooks",
+    "skills",
+    "!skills/**/*.spec.ts",
     "README.md",
     "LICENSE"
   ],
@@ -46,12 +57,16 @@
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
     "demo": "npm run build && bash examples/demo/run.sh",
-    "test:e2e": "bash test/e2e/run.sh",
+    "test:unit": "npm run build && vitest run --project unit",
+    "test:integration": "npm run build && vitest run --project integration",
+    "test:e2e": "npm run build && vitest run --project e2e",
+    "test:cli-e2e": "bash test/e2e/run.sh",
     "test:harness": "npm run build && node dist/cli.js test",
     "test:eval": "npm run build && node dist/cli.js eval",
     "test:vitest": "npm run build && vitest run --project runners",
     "test:jest": "npm run build && jest",
-    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json"
+    "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json",
+    "demo:plugin": "npm run build && node examples/plugin-test-demo.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -62,6 +77,8 @@
     "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^10.1.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-boundaries": "^6.0.2",
     "eslint-plugin-sonarjs": "^4.0.2",
     "globals": "^17.4.0",
     "jest": "^30.4.2",
@@ -87,11 +104,13 @@
     "@ast-grep/lang-ruby": "^0.0.7",
     "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.43.0",
+    "@iarna/toml": "^2.2.5",
     "@jackchuka/mdschema": "^0.12.8",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.0.1",
+    "ts-essentials": "^10.2.1",
     "typescript": "^5.9.3"
   }
 }

package/skills/audit-feedback-loop/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: audit-feedback-loop
+description: Scan the current repo and score its feedback loop maturity for AI-assisted development
+disable-model-invocation: true
+---
+
+Scan the current repository and score its feedback loop maturity for AI-assisted development.
+
+## Instructions
+
+Analyze this repository and score its **feedback loop maturity** using the levels below. Check for each signal, then output a summary report.
+
+### Maturity Levels
+
+**Level 0 — Vibes**
+No CI config, no linter rules, no CLAUDE.md. The AI agent is flying blind.
+
+**Level 1 — Guardrails**
+Has CI + standard linters, but no custom rules. The agent gets basic feedback but can't learn project-specific conventions.
+
+**Level 2 — Architecture as Code**
+Has custom lint rules, CLAUDE.md rules have enforcement annotations. The agent gets rich, project-specific feedback.
+
+**Level 3 — The Organism**
+Has CI + custom rules + screenshot/visual tests + observability + scheduled agent tasks. The entire development loop is instrumented.
+
+### Signals to Check
+
+Scan the repository for the following and note which exist:
+
+1. **CI Configuration**: Look for `.github/workflows/`, `.circleci/`, `Jenkinsfile`, `.gitlab-ci.yml`, `bitbucket-pipelines.yml`, `.travis.yml`, etc.
+2. **Linter Config** (language-aware):
+   - **JS/TS**: `eslint.config.*`, `.eslintrc*`, `biome.json`, `.prettierrc*`, `deno.json`
+   - **Python**: `pyproject.toml` (look for `[tool.ruff]`, `[tool.pylint]`, `[tool.flake8]`), `setup.cfg`, `.flake8`, `ruff.toml`
+   - **Rust**: `clippy.toml`, `.clippy.toml`, `rustfmt.toml`
+   - **Go**: `.golangci.yml`, `.golangci.yaml`
+   - **Ruby**: `.rubocop.yml`
+   - **Java/Kotlin**: `checkstyle.xml`, `pmd.xml`, `detekt.yml`
+3. **Custom Lint Rules**: Look for custom plugins, rule directories, or inline rule definitions in linter configs
+   - JS/TS: `eslint-plugin-*`, `eslint-rules/` directories
+   - Python: custom Ruff/Pylint plugins, AST-based checks
+   - Rust: custom Clippy lints
+   - Go: custom analyzers
+4. **CLAUDE.md**: Check if `CLAUDE.md` exists at the repo root
+5. **CLAUDE.md Enforcement**: Check if using vigiles v2 specs (`CLAUDE.md.spec.ts` exists) or v1 annotations (`**Enforced by:**` in CLAUDE.md). v2 specs = higher maturity.
+6. **Type-Safe Specs**: Check for `CLAUDE.md.spec.ts` or `*.spec.ts` files — indicates typed spec compilation via vigiles v2
+7. **Generated Types**: Check for `.vigiles/generated.d.ts` — indicates linter rules are type-checked at authoring time
+8. **Screenshot/Visual Tests**: Look for Playwright (`playwright.config.*`), Cypress (`cypress.config.*`), Chromatic, Percy, BackstopJS configs
+9. **Observability**: Search for imports/usage of `@sentry/`, `dd-trace`, `@datadog/`, `newrelic`, `@opentelemetry/`, `sentry_sdk`, `structlog`, `tracing` (Rust), `opentelemetry` in source files
+10. **Scheduled Agent Tasks**: Look for cron patterns in CI configs, `.github/workflows/` with `schedule:` triggers, or references to scheduled Claude Code tasks
+
+### Output Format
+
+```
+## Feedback Loop Audit
+
+**Repository:** <repo name>
+**Primary language(s):** <detected languages>
+**Score: Level X — <Name>**
+
+### Signals Found
+- [x] CI Configuration: <details>
+- [ ] Custom Lint Rules: not found
+- [x] CLAUDE.md: found, 5 enforced / 2 guidance / 1 missing
+...
+
+### Recommendations
+1. <Most impactful next step to level up>
+2. <Second recommendation>
+3. <Third recommendation>
+
+### How to Level Up
+<Specific, actionable advice for reaching the next maturity level>
+```
+
+Be specific about file paths and what you found. Give actionable recommendations tailored to the project's language and toolchain.

package/skills/edit-spec/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: edit-spec
+description: Edit a vigiles spec file to update instruction files (CLAUDE.md, AGENTS.md)
+disable-model-invocation: true
+argument-hint: <what to change — e.g., "add a rule about error handling" or "update the testing section">
+---
+
+Edit a `.spec.ts` file to update the project's instruction files. The spec is the source of truth — CLAUDE.md and AGENTS.md are compiled build artifacts that must not be edited directly.
+
+## Arguments
+
+$ARGUMENTS — What the user wants to change. Examples:
+
+- "add a rule about always using the custom logger"
+- "update the architecture section"
+- "add src/services/auth.ts to key files"
+- "add npm run lint to commands"
+- "change the testing guidance"
+
+## Instructions
+
+### Step 1: Find the Spec
+
+Look for spec files in the repo root:
+
+- `CLAUDE.md.spec.ts` — source for CLAUDE.md
+- `AGENTS.md.spec.ts` — source for AGENTS.md
+- Any `*.spec.ts` matching instruction files
+
+If no spec exists, suggest: `npx vigiles setup`
+
+### Step 2: Read and Understand the Spec
+
+Read the spec file. It's a TypeScript file that exports a `claude()` call with these fields:
+
+```typescript
+import { claude, enforce, guidance, check, every } from "vigiles/spec";
+
+export default claude({
+  // Optional: output target (defaults to "CLAUDE.md")
+  target: "CLAUDE.md",
+  // or multi-target:
+  // target: ["CLAUDE.md", "AGENTS.md"],
+
+  // Prose sections — become ## headings in compiled output
+  sections: {
+    positioning: "What this project does...",
+    architecture: "How the codebase is structured...",
+  },
+
+  // File paths verified to exist at compile time
+  keyFiles: {
+    "src/index.ts": "Main entry point",
+  },
+
+  // Commands verified against package.json
+  commands: {
+    "npm run build": "Compile the project",
+    "npm test": "Run all tests",
+  },
+
+  // Rules — three types
+  rules: {
+    // enforce() — backed by a linter rule, verified to exist AND be enabled
+    "no-any": enforce(
+      "@typescript-eslint/no-explicit-any",
+      "Use unknown and narrow with type guards.",
+    ),
+
+    // check() — filesystem assertion run by vigiles
+    "test-pairing": check(
+      every("src/**/*.service.ts").has("{name}.test.ts"),
+      "Every service must have tests.",
+    ),
+
+    // guidance() — prose only, no enforcement
+    "research-first": guidance("Google unfamiliar APIs before implementing."),
+  },
+});
+```
+
+### Step 3: Make the Changes
+
+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
+
+**Updating a section:**
+
+- Edit the string in `sections`. Sections are plain strings or tagged template literals with `file()`, `cmd()`, `ref()` for verified references
+- Do NOT add `#` or `##` headers inside sections — they break the document structure
+
+**Adding a key file or command:**
+
+- Add to `keyFiles` or `commands`. The compiler verifies these exist at compile time
+- For commands: must match a script in `package.json`
+- For key files: must exist on disk
+
+### Step 4: Compile
+
+After editing the spec, run:
+
+```bash
+npx vigiles compile
+```
+
+This regenerates the compiled instruction file(s). Review the output for any errors:
+
+- `stale-file` — a key file path doesn't exist
+- `stale-command` — a command isn't in package.json
+- `invalid-rule` — a linter rule doesn't exist or is disabled
+- `section-has-header` — a section contains `#` headers (break into separate named sections)
+
+### Step 5: Verify
+
+```bash
+npx vigiles check
+```
+
+If the PostToolUse hook is installed (via `npx skills add zernie/vigiles`), compilation happens automatically after you save the spec.
+
+## Important
+
+- **Never edit CLAUDE.md or AGENTS.md directly** — they have a vigiles hash comment and are build artifacts
+- **The spec is TypeScript** — you get type checking, autocomplete, and verified references
+- **`enforce()` rules are verified** — the compiler checks the rule exists AND is enabled in your linter config
+- **Sections must not contain `#` or `##` headers** — use separate named sections instead

package/skills/enforce-rules-format/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: enforce-rules-format
+description: Validate that all rules have proper enforcement classification (enforce/check/guidance)
+disable-model-invocation: true
+---
+
+Validate that every rule in the project's instruction files has a proper enforcement classification, and fix any that are missing.
+
+## Instructions
+
+### Step 1: Detect Format
+
+Check which format the project uses:
+
+**v2 (spec-based):** Look for `CLAUDE.md.spec.ts` or any `*.spec.ts` files. If found, this is a v2 project — rules must use `enforce()`, `check()`, or `guidance()`.
+
+**v1 (hand-written):** Look for `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. If found without a spec file, this is a v1 project — rules need `**Enforced by:**` or `**Guidance only**` annotations.
+
+### Step 2: Validate
+
+**For v2 specs:**
+
+The TypeScript type system already prevents unannotated rules — you can't create a rule without calling `enforce()`, `check()`, or `guidance()`. So focus on:
+
+1. Do `enforce()` rules reference real linter rules? Run `npx vigiles compile` to check.
+2. Are there guidance rules that COULD be `enforce()`? Check linter configs for matching rules.
+3. Are there `check()` assertions that could be delegated to a linter? Suggest `enforce()` instead.
+
+```bash
+npx vigiles compile
+npx vigiles discover
+```
+
+**For v1 hand-written files:**
+
+Scan for `###` headings. Each must have one of:
+
+- `**Enforced by:** \`linter/rule-name\``
+- `**Guidance only** — reason`
+- `<!-- vigiles-disable -->`
+
+Report missing annotations with a summary table.
+
+### Step 3: Fix Issues
+
+For each issue found:
+
+1. Check the project's linter configuration for matching rules
+2. Suggest `enforce("linter/rule")` (v2) or `**Enforced by:** \`linter/rule\`` (v1)
+3. If no linter rule exists, suggest `guidance()` (v2) or `**Guidance only**` (v1)
+4. **Ask the user** before making changes
+
+### Step 4: Suggest Migration
+
+If the project uses v1 format, suggest migrating to v2 specs for type safety:
+
+> Your rules could benefit from type-safe specs. Run the `migrate-to-spec` skill to convert your CLAUDE.md to a typed .spec.ts file.
+
+### Step 5: Verify
+
+Run the appropriate command:
+
+```bash
+# v2
+npx vigiles compile && npx vigiles check
+
+# validate
+npx vigiles check
+```
+
+Report the validation result.

package/skills/generate-logo/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: generate-logo
+description: Generate or iterate on the vigiles logo using ImageRouter API
+---
+
+# Generate Logo
+
+Generate logo variations for vigiles using the ImageRouter API (imagerouter.io).
+
+## Setup
+
+Get an API key from https://imagerouter.io/api-keys. Pass it as an argument or set `IMAGEROUTER_API_KEY` env var. Do NOT commit the key.
+
+## API
+
+```
+Endpoint: https://api.imagerouter.io/v1/openai/images/generations
+Auth: Bearer token in Authorization header
+Method: POST, Content-Type: application/json
+```
+
+### Request body
+
+```json
+{
+  "prompt": "...",
+  "model": "google/nano-banana-2",
+  "quality": "high",
+  "size": "1024x1024",
+  "response_format": "url",
+  "output_format": "png"
+}
+```
+
+### Available models (image generation)
+
+List models: `GET https://api.imagerouter.io/v1/models`
+
+Known good models:
+
+- `google/nano-banana-2` — best quality, $0.07/image
+- `google/nano-banana-2:free` — free tier
+- `openai/gpt-image-1` — OpenAI's image model
+- `black-forest-labs/FLUX-1.1-pro` — FLUX pro
+
+### Response
+
+```json
+{
+  "created": 1775430873,
+  "data": [{ "url": "https://storage.imagerouter.io/..." }],
+  "cost": 0.069,
+  "latency": 27627
+}
+```
+
+Download the image from the URL in `data[0].url`.
+
+## Current logo
+
+The current logo (`logo.png`) is v6: overlapping translucent flame petals on dark background, amber-orange palette. Generated with `google/nano-banana-2`.
+
+### Prompt that produced it
+
+```
+A premium, refined logo icon for a developer tool called vigiles that compiles
+typed TypeScript specs to AI instruction files. Inspired by OpenAI geometric aesthetic and Apple
+minimalism. A single abstract geometric shape: an upward-pointing flame composed
+of 3 overlapping translucent rounded shapes, creating depth through overlap —
+similar to how the OpenAI logo uses overlapping curves. Warm amber to deep orange
+color palette. Black background. No text. No letters. Pure abstract mark. Clean
+enough to be an app icon. Luxurious, premium, modern tech company feel.
+```
+
+## Design principles
+
+- **Flame/torch motif** — vigiles were Rome's night watchmen who carried torches
+- **Amber/orange palette** — matches GitHub Action branding color
+- **No text in the icon** — must work at 16px favicon size
+- **Dark background variant** for README, light/transparent variant for npm
+
+## Example curl
+
+```bash
+curl 'https://api.imagerouter.io/v1/openai/images/generations' \
+  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "prompt": "YOUR PROMPT HERE",
+    "model": "google/nano-banana-2",
+    "quality": "high",
+    "size": "1024x1024",
+    "response_format": "url",
+    "output_format": "png"
+  }'
+```
+
+## Workflow
+
+1. Generate variations with different prompts
+2. Save as `logo-v*.png` (gitignored)
+3. Pick the best, copy to `logo.png`
+4. Commit `logo.png` only

package/skills/generate-rule/SKILL.md

@@ -0,0 +1,64 @@
+<!-- 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 -->