Adopt a typed .spec.ts for an existing hand-written CLAUDE.md — start from the file you already have, non-destructively

Start a typed CLAUDE.md.spec.ts from an existing hand written CLAUDE.md (or AGENTS.md). This is the non destructive adoption path — you keep your existing instruction file as the starting point and get type safety going forward. Adoption rules Adoption is the safe, faithful on ramp — never an upgrade in disguise. These are non negotiable: Faithful. Preserve every rule, command, key file, and prose section as is. Invent nothing — the spec must compile back to ~the user's existing file. Non destructive. Never edit the original CLAUDE.md / AGENTS.md . Only write the new .spec.ts . Never auto compile over the file — switching it to spec managed is a separate, explicit step the user runs with a diff to review. Don't escalate enforcement. Keep guidance() as guidance() . Upgrading to enforce() has a cost (config/plugins, possible false positives) and is a separate opt in step — the strengthen skill. Adoption is not turning on strict / workflow gating. Reversible. vigiles eject <file hands the file back as plain hand owned markdown anytime — it's never a one way door. Tell the user this. Ask before writing. Present the generated spec and a conversion summary first; write only on the user's yes. A lighter touch exists. For no spec at all, inline <! vigiles:enforce ... comments are verified by vigiles lint with the same engine. 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: 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: 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: 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 lint 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 lint . Step 6: Optional — Set Up CI If the user wants CI integration, suggest adding to their GitHub Actions workflow: Or using the vigiles GitHub Action:

adopt-spec