adopt-spec

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:

npm install -D vigiles

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:

import {
  claude,
  enforce,

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 toguidance()` — 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: