edit-spec

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: if there's a hand-written CLAUDE.md, suggest the adopt-spec skill; otherwise suggest npx vigiles init to scaffold one.

Step 2: Read and Understand the Spec

Read the spec file. It's a TypeScript file that exports a claude() call with these fields:

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."),
  },
});