Your spec is the source.
The transpiler writes the code.

Why CaT exists

Spec-driven tools today either throw the spec away after generation or keep it next to hand-written code. CaT is the third option: the spec is the only thing humans edit, and the code is regenerated from it.

The spectrum of control

One document, five levels of authority. Higher levels override lower ones.

Three tiers, nothing new where something existed

A CaT feature file with the CaT-only parts removed is a valid OpenSpec spec.md. The CLI test suite proves it against the real openspec validate.

Where CaT sits

Martin Fowler’s taxonomy: spec-first tools generate once and discard the spec (Kiro, GitHub Spec Kit); spec-anchored tools keep the spec and update it alongside code (OpenSpec); spec-as-source tools regenerate code from the spec (Tessl, CaT). CaT takes OpenSpec’s grammar, Tessl’s DO NOT EDIT output marker, Kiro’s CONTINUE TO regression form, and adds the system layer: stack, providers, Models, Flows, Views, references.

The CaT language

Plain .md files. Frontmatter for the fields that need a closed vocabulary. Headings for sections that map to generated artifacts. GFM tables for Models. OpenSpec headings for requirements and scenarios. Fenced code for anything verbatim. Any other heading is informative prose, never an error.

my-project/
├── cat.config.yaml       # transpiler settings, provider profiles, references   (human-owned)
├── bacon/                # the spec                                              (human-owned)
│   ├── system.md         # required: name, stack, system-wide requirements
│   ├── models.md         # Models shared by more than one feature
│   ├── auth.md           # feature file
│   ├── features/*.md     # feature files, same format
│   └── refs/             # snapshots of references
├── purr                  # transpile record                                  (transpiler-owned)
└── src/                  # output                                            (transpiler-owned)

---
name: TaskFlow
stack:
  framework:  Next.js (App Router)
  language:   TypeScript
  database:   Supabase
  auth:       Supabase Auth
  styling:    Tailwind + shadcn/ui
  deploy:     Vercel
---

## Requirements

### Requirement: Account lockout
IF sign-in fails three times within 10 minutes, THEN the system MUST lock
the account for 15 minutes.

#### Scenario: Third failure locks
- **GIVEN** an account with 2 failed attempts in the last 10 minutes
- **WHEN** a third attempt fails
- **THEN** the account is locked for 15 minutes
- **AND** further attempts are rejected without checking the password

## Model: Task

| Field | Type | Notes |
|---|---|---|
| id | uuid | primary key |
| title | text | |
| assignee | Profile | |
| status | todo, in_progress, done | |
| priority | low, medium, high, urgent | default medium |
| due_date | date | nullable |
| created_at | timestamp | auto |

Invariants:
- The assignee MUST belong to the same team as created_by.

## Flow: Assign Task

1. User picks a team member from a dropdown
2. System updates the assignee
3. System notifies the new assignee

## View: Dashboard

Show tasks grouped by status in a kanban board. User can filter by assignee
and priority. Overdue tasks are highlighted with the `color.overdue` token.

The kanban board's drag-and-drop MUST use @hello-pangea/dnd.

Validate the session server-side before rendering a protected page:

```typescript
const { data: { session } } = await supabase.auth.getSession()
if (!session) redirect('/login')
```

references:
  design-tokens:
    kind: design-tokens      # W3C DTCG json; theme is generated from it
    uri: bacon/refs/tokens.json
  dashboard-design:
    kind: design
    uri: https://www.figma.com/design/AbC123/TaskFlow?node-id=12-34
    via: mcp:figma              # cat-author reads it here
    snapshot: bacon/refs/dashboard/ # cat-transpile reads only this

version: 0.2            # CaT language version
transpiler:
  model: claude-sonnet-4 # LLM id. The one place "model" means the LLM
  strategy: incremental  # or full
  output: src/
  retries: 2             # self-correction attempts on build failure
providers:
  supabase-auth:
    name: Supabase Auth  # matched by `using:`
    package: "@supabase/supabase-js"
    env: [NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY]

How a change flows

Authoring is interactive and local. Transpiling is headless and runs in CI. Two skills, one for each.

Phases

Generate rules

• Existing output is context. Smallest change that satisfies the changed spec. Outputs of unchanged spec files stay byte-identical.
• Every output file starts with GENERATED FROM bacon/<file> BY CaT - DO NOT EDIT.
• One scenario becomes one test, named <feature> / <requirement> / <scenario>.
• Build after generating. On failure, self-correct up to transpiler.retries times, then fail the run.

The purr file

The transpile record at the project root. Incremental runs diff bacon/ against last_transpiled_commit, expand through dependencies and references, and regenerate only those outputs.

last_transpiled_commit: a3f7c2e
last_transpiled_at: 2026-10-14T10:30:00Z

dependencies:            # Model -> spec files that reference it
  Team: [bacon/auth.md, bacon/features/tasks.md]

decisions:
  - spec: bacon/auth.md
    requirement: Session length
    kind: should_deviation   # should_deviation | may_skipped | ambiguity
    reason: "Supabase default is 1h; set JWT expiry to 7d via project config"

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

Example: TaskFlow

Four spec files. Fourteen named requirements, every one with scenarios. Validates with --strict and zero warnings. Full source in rleroi/catspec-example.

bacon/system.md

---
name: TaskFlow
stack:
  framework:  Next.js (App Router)
  language:   TypeScript
  database:   Supabase
  auth:       Supabase Auth
  styling:    Tailwind + shadcn/ui
  deploy:     Vercel
---

## Purpose

A simple task management app for small teams. Create projects, assign
tasks, track progress.

## Requirements

### Requirement: Team scoping
WHEN a user queries any table, the system MUST return only rows that belong
to that user's team.

#### Scenario: Member of another team
- **GIVEN** a user in Team A
- **WHEN** they request a Task that belongs to Team B
- **THEN** the response contains no Task
- **AND** the status code is 404

### Requirement: Unauthenticated requests
IF a request carries no valid session, THEN the system MUST respond with
401 and MUST NOT reveal whether the resource exists.

#### Scenario: Protected route without session
- **WHEN** a visitor with no session opens /dashboard
- **THEN** they are redirected to /login
- **AND** no data is rendered

bacon/auth.md (excerpt)

---
feature: Authentication
using: [Supabase Auth]
---

## Purpose

Users sign up with email or Google OAuth. A Profile is created on first
login. Profile is shared with other features, see `bacon/models.md`.

## Requirements

### Requirement: Verification email
WHEN a user completes email sign-up, the system MUST send a verification
email.

#### Scenario: Email sign-up
- **WHEN** a visitor signs up with email and password
- **THEN** a verification email is sent to that address
- **AND** the account is not usable until verified

#### Scenario: Google sign-up
- **WHEN** a visitor signs up with Google
- **THEN** no verification email is sent

### Requirement: Session length
Sessions SHOULD last 7 days.

#### Scenario: Return within a week
- **GIVEN** a user who signed in 6 days ago
- **WHEN** they open the app
- **THEN** they are still signed in

## Flow: Sign Up

1. User enters email and password, or clicks "Sign in with Google"
2. System creates the auth account
3. System sends a verification email (email sign-up only)
4. On first login, system creates a Profile row

bacon/features/tasks.md (excerpt)

---
feature: Task Management
using: [Supabase]
references: [design-tokens]
---

## Model: Notification

| Field | Type | Notes |
|---|---|---|
| id | uuid | primary key |
| user | Profile | recipient |
| message | text | |
| read | boolean | default false |
| task | Task | nullable |
| created_at | timestamp | auto |

Invariants:
- A user MUST only read notifications where user is themselves.

## Requirements

### Requirement: Assignment notification
WHEN a task's assignee changes, the system MUST create a Notification for
the new assignee that references the task.

#### Scenario: Reassignment
- **GIVEN** a task assigned to alice
- **WHEN** it is reassigned to bob
- **THEN** one new Notification exists for bob referencing the task

#### Scenario: Reassignment to the same person
- **GIVEN** a task assigned to alice
- **WHEN** it is reassigned to alice
- **THEN** no new Notification is created

### Requirement: Overdue highlight
WHILE a task's due_date is in the past and its status is not `done`, the
dashboard MUST render it with a red highlight.

#### Scenario: Overdue but done
- **GIVEN** a task due yesterday with status `done`
- **WHEN** the dashboard renders
- **THEN** that task card has no overdue highlight

## View: Dashboard

Show tasks grouped by status in a kanban board. User can filter by assignee
and priority. Overdue tasks are highlighted with the `color.overdue` token.

The kanban board's drag-and-drop MUST use @hello-pangea/dnd.

Get started

CaT ships as three agent skills and a CLI. Any agent that can load a SKILL.md works: Cursor, Claude Code, and others.

Scaffold, author, transpile

# 1. Scaffold. The cat-init skill creates cat.config.yaml, bacon/system.md,
#    the CI workflow, .gitattributes and CODEOWNERS.
skills/cat-init/SKILL.md

# 2. Author. Interactive. Validate, enrich, confirm, commit bacon/.
skills/cat-author/SKILL.md

# 3. Validate anywhere.
node cli/dist/cli.js validate . --strict   # or uses: rleroi/catspec@master in CI

# 4. Transpile. Headless, in CI or locally. Writes src/ and purr only.
skills/cat-transpile/SKILL.md
catspec transpile .

Roadmap

• Language 0.2 — OpenSpec grammar, glossary, references
• Skills — cat-init, cat-author, cat-transpile
• CLI — catspec validate | verify | diff | transpile, lint-rule tests, OpenSpec conformance test
• Example — TaskFlow passes validate --strict
• catspec verify — fails when a human commit touched src/ or purr
• Agent backends — transpiler.agent: cursor, cursor-cli, claude-code
• The twenty-change experiment — twenty real spec changes on catspec-example, no hand edits to src/. The kill criterion.
• GitHub Action — uses: rleroi/catspec@master, check or transpile and commit as the bot
• Skills — npx skills add rleroi/catspec
• References — kind: code for brownfield, kind: spec for cross-repo