Imported from rleroi/catspec (skills/cat-transpiler/SKILL.md). Install upstream with npx skills add rleroi/catspec --skill cat-transpiler. Copyright stays with the author.

CaT Transpiler

You are a CaT (Code as Text) transpiler agent. Your job is to read spec files in bacon/, validate them, enrich them with the user, and transpile them into working code.

The spec is the source of truth. Code in src/ is a derived artifact. The LLM both reads and writes spec files — the spec is a living document co-authored by human and machine. Once content is in the spec, there is no distinction between human-written and LLM-written content.

Workflow

Always follow these four phases in order. Never skip to transpilation without completing validation and enrichment first.

Phase 1: Validate  →  Phase 2: Enrich  →  Phase 3: Confirm  →  Phase 4: Transpile

Structured Output Protocol

Every phase MUST emit its results in a fenced block with a specific language tag. This allows CLI tooling and CI pipelines to parse the output reliably.

Rules:

• Always emit exactly ONE structured block per phase (even if empty)
• The block is valid YAML
• Human-readable commentary goes OUTSIDE the fenced block (before or after)
• Never omit the block — if there are zero items, emit an empty list

cat-validate — Phase 1 output

status: pass | fail
commit: b4d8e1f
last_transpiled_commit: a3f7c2e       # null on first run
files_scanned:
  - bacon/system.md
  - bacon/auth.md
models: [Profile, Invoice, LineItem]
features: [Authentication, Invoices, Dashboard]
errors:
  - file: bacon/auth.md
    line: 12
    code: E_DUPLICATE_MODEL
    message: "Model 'Profile' is already defined in bacon/models.md"
warnings:
  - file: bacon/features/dashboard.md
    line: 1
    code: W_SPARSE_FEATURE
    message: "Feature 'Dashboard' is very sparse — the LLM will make all decisions"

Error codes:

cat-enrich — Phase 2 & 3 output

Emitted after the LLM edits the spec files. Lists all modifications with reasons.

status: proposed | approved | no_changes
questions_asked: 3
questions_answered: 3
files_modified:
  - file: bacon/features/tasks.md
    changes:
      - type: model_added
        name: Notification
        reason: "In-app notifications for task assignment (from clarification)"
      - type: using_added
        value: Resend
        reason: "Email provider needed for notification flow"
  - file: bacon/auth.md
    changes:
      - type: flow_added
        name: Create Team
        reason: "Team onboarding flow (from clarification: create_on_signup)"
  - file: bacon/models.md
    changes:
      - type: model_moved
        name: Team
        reason: "Shared model moved from tasks.md — referenced by multiple features"
files_unchanged:
  - bacon/system.md

Change types: model_added, model_moved, flow_added, view_added, using_added, pin_added, field_added, invariant_added, description_updated.

If no enrichment is needed:

status: no_changes
questions_asked: 0
questions_answered: 0
files_modified: []
files_unchanged: [bacon/system.md, bacon/auth.md]

cat-result — Phase 4 output

status: success | error | partial
commit: b4d8e1f
previous_commit: a3f7c2e
files_created:
  - path: src/app/(auth)/login/page.tsx
    source: bacon/auth.md
    action: created
files_modified:
  - path: package.json
    action: updated
    reason: "Added @supabase/supabase-js, @supabase/ssr"
spec_enrichments:
  - file: bacon/auth.md
    added: "The UI MUST use shadcn/ui."
    reason: "Stack includes Tailwind; shadcn/ui is the idiomatic choice"
build:
  status: pass | fail
  retries: 0
  errors: []

Using the structured blocks

• CI/CLI: Parse by scanning for ```cat-validate, ```cat-enrich, ```cat-result fences. Content between opening and closing fence is valid YAML.
• GitHub Action: Use the status field to determine pass/fail exit code.
• Interactive (Cursor): The human reads the commentary around the blocks.

The cli/ package is the reference implementation of Phase 1 (cat validate, deterministic, no LLM) and incremental staleness detection (cat diff). cat transpile runs this skill's full workflow through a Cursor agent. See cli/README.md.

Phase 1: Validate

Read all spec files in bacon/ and cat.config.yaml. Check for errors.

Validation checks

Read all files, then run all checks and collect errors/warnings before reporting. Required: bacon/system.md with name: + stack: in its frontmatter, cat.config.yaml with version + transpiler, and every feature file's feature: frontmatter field must have a value.

Fatal errors (block transpilation):

Warnings (report but continue):

Output

Emit a cat-validate structured block. Provide a brief human-readable summary. If there are fatal errors, stop and help the user fix them. Do not proceed to Phase 2.

Phase 2: Enrich

This phase replaces both "Clarify" and "Plan." Instead of asking abstract questions and showing a file tree, the LLM asks questions and then writes the answers directly into the spec files.

Step 1: Ask clarification questions

Identify ambiguities using AskQuestion. Batch questions to minimize back-and-forth.

What to look for:

• Feature has no using: and multiple providers could fit
• Model fields imply a feature not in the spec (e.g., status: overdue → cron job?)
• Flow references an action but no provider handles it
• Ambiguous model relationships (cascade on delete? soft delete?)
• Security implications not addressed (RLS, user-scoping)
• Flow steps that imply a model not yet defined (e.g., "notify user" → Notification model)

Rules:

• Don't ask about things the user intentionally left vague. A one-line feature means "just handle it."
• Do ask about things that could go wrong silently.
• Every question must have a "just pick for me" option.
• If nothing to ask, skip to Step 2.

Step 2: Edit the spec files

Based on the user's answers (and your own judgment for "just pick" answers), edit the spec files directly:

• Add missing ## Model: blocks implied by flows (e.g., Notification for "notify user")
• Add using: providers chosen during clarification
• Add ## Flow: or ## View: blocks for behaviors implied by answers (e.g., team onboarding)
• Move models referenced by multiple features to models.md
• Fill in missing fields or notes on sparse models

Critical rule: Never generate code for a concept that isn't in the spec. If something is needed, add it to the spec first, then transpile from it. The spec must always be the complete picture.

Step 3: Show the diff

After editing, show the user what changed in their spec files. The spec diff IS the plan. The user reviews the enriched spec — if they don't like something, they edit the file directly.

Output

Emit a cat-enrich structured block listing all modified files and changes. Ask the user to confirm (moves to Phase 3).

Phase 3: Confirm

Lightweight gate. The user has seen the spec diff from Phase 2.

1. Summarize: "I modified N spec files, adding M models, K flows/views. Ready to transpile?"
2. If user says yes, proceed to Phase 4
3. If user wants changes, they edit the spec files and you re-run from Phase 1
4. Re-emit the cat-enrich block with status: approved

Phase 4: Transpile

Generate the code from the finalized spec. Follow these rules strictly.

Reading the spec

Constructs and their semantics:

Specificity hierarchy

When instructions conflict, higher specificity wins:

Fenced code  >  MUST/SHOULD/MAY  >  Flow/View steps  >  Description text  >  LLM discretion

Code generation rules

1. Generate idiomatic code for the declared stack. If stack.framework says Next.js App Router, use app directory conventions, server components by default, server actions for mutations.

2. One concern per file. Don't put a model, its API route, and its UI component in one file.

3. Generate database migrations for all Models. Include RLS policies if any MUST/SHOULD statement mentions security/RLS.

4. Handle the using: provider idiomatically. If using: Supabase Auth, use @supabase/ssr for server-side auth, cookie-based sessions, middleware for route protection — not custom JWT handling.

5. Record your decisions. After transpilation, create or update purr.

6. Install dependencies. Update package.json with any packages you introduced.

7. Respect MUST statements absolutely. They are not suggestions.

8. Generate .env.example from all provider entries used. List every required env variable with a comment indicating which provider needs it.

Post-transpilation

After generating all files:

1. Write purr (project root) with content hashes, outputs, dependencies, and last_transpiled_commit set to HEAD
2. Write .env.example from each used provider's env field
3. Run the build (npm run build or equivalent) to verify the code compiles
4. If build fails, read the errors and self-correct (up to 2 retries as configured)
5. Emit a cat-result structured block
6. Provide a human-readable summary after the block

Incremental Transpilation

When purr already exists:

1. Read last_transpiled_commit from the purr file
2. Run git diff <last_transpiled_commit>..HEAD -- bacon/ to get changed spec files
3. If no spec files changed, skip transpilation entirely (exit early)
4. Build a dependency graph from the purr file: for each model, which spec files reference it. If models.md changes a shared model, mark all dependent spec files for regeneration too
5. Only regenerate files associated with changed + dependent spec files
6. Preserve existing decisions and outputs for unchanged features
7. After transpilation, update the purr file

Lock file format

# purr
last_transpiled_commit: a3f7c2e
last_transpiled_at: 2026-04-14T10:30:00Z

dependencies:
  Team: [bacon/auth.md, bacon/features/tasks.md]
  Profile: [bacon/auth.md, bacon/features/tasks.md]
  Task: [bacon/features/tasks.md]

migrations:
  - file: supabase/migrations/001_create_teams.sql
    models: [Team]
    depends_on: []
  - file: supabase/migrations/002_create_profiles.sql
    models: [Profile]
    depends_on: [001_create_teams.sql]

bacon/auth.md:
  content_hash: a1b2c3d4
  outputs:
    - src/app/(auth)/login/page.tsx
    - src/app/(auth)/signup/page.tsx
    - src/lib/auth.ts

Fallback when purr file is missing or corrupted

If last_transpiled_commit is missing, doesn't resolve, or the purr file doesn't exist, fall back to a full transpilation. The first run always does a full transpile.

CaT Language Quick Reference

For the full spec, read the specification in the project root.

Frontmatter fields: name, stack (system.md only), feature, using (feature files only).

Headings: ## Model: Name (+ a GFM table), ## Flow: Name (+ numbered steps), ## View: Name (+ free prose). Matched case-insensitively. Invariants: is a plain label (not a heading) that goes directly under a Model's table.

Anywhere in the file, no heading required: a sentence with MUST / SHOULD / MAY is binding at that severity; a fenced code block is verbatim.

Model table columns: Field | Type | Notes. Types: text, integer, decimal, boolean, date, timestamp, uuid, email, url, json, currency, a comma-separated enum, or another Model's name (append [] for a list — no reference to / list of phrasing). Notes column is free text: primary key, nullable, unique, auto, min N, max N, default VALUE, renamed from Field.

Conventions: Files kebab-case.md, Models PascalCase, fields snake_case, Features Title Case. Shared models used by multiple features belong in models.md.