🦉 Main spex

The AI-first development framework that turns specifications into deterministic code — keeping AI running at full speed while ensuring slop-free verifiable results.

The name spex comes from a casual shorthand for specifications.

Why spex

Ask an AI to write you a snake game and it will. But will the snake have big blue eyes and eat donuts, as you wanted? Unlikely — the AI fills every detail you left out with its own guesses, so you get the game it imagined, not the one you wanted.

AI writes code fast, but fast is not the same as right: it can add changes nobody asked for, forget requirements, do the same thing differently each time, or hallucinate. Every unreviewed decision and unverified result adds slop that compounds. Reviewing everything by hand throws away the speed; accepting everything ships the slop.

spex helps to produce slop-free, verifiable results fast, with minimal human intervention. The AI writes everything, following the specs, skills, and rules; the human decides and approves; and reviews, tests, and deterministic checks prove the result.

Core Concepts

Main spex, or spex for short, is built on four simple pieces:

• Specs define what a feature does — a capability with acceptance criteria. Specs are single source of truth for project - all behaviour, contracts, code, tests and other artifacts come from it and must adhere to it.
• Rules govern how everything is built — cross-cutting conventions like style, security, or testing. Each package must adhere to a list of rules applicable to it.
• Skills are the instructions an AI agent follows to do the job consistently and correctly.
• Traceability is the thread that stitches together spec, contract, implementations, and tests — letting humans and agents find everything related to a spec at once, and ensuring full coverage so no acceptance criterion is forgotten.

spex provides the core flow plus skills and rules you can extend, adapt, or replace for your project needs. Whatever you don't customize updates with each new version, bringing you the latest improvements contributed by the community.

The spex CLI runs and automates all of it. Specs, contracts, and checks are plain files and deterministic commands, so spex works with any AI model, AI coding agent, CLI, and IDE.

Quickstart

Prerequisites

• Rust: Install Rust (required for building the spex CLI)
• Git: Install Git
• Linux or macOS: on Windows, use WSL; see supported platforms
• spex CLI: Install the spex CLI tool from crates.io:

  cargo install main-spex
  

Setup

We will create the following structure:

shopping-notes/                       # project root
├── shopping-notes-api/                # existing api package
├── shopping-notes-frontend/           # existing frontend package
├── ...                                # repeat for other packages
└── shopping-notes-spex/               # new spex repository (created by spex cli)

Package directories follow <project-name>-<package-short-name> (naming-convention), so rename existing packages to match before running /spex-setup.

1. Put all project packages (each a git repository) in one shared folder (project root folder)
2. Run terminal command spex init in the project root and pick the multi-repo layout to create the shopping-notes-spex repo
3. Open workspace to work across all packages at once and integrate with AI coding agent (the workspace file lists only the spex repository until /spex-setup adds the others):
   • Cursor/VSCode: open workspace from file shopping-notes-spex/shopping-notes.code-workspace
   • Cursor agentic: open workspace file in editor mode first, then pick it in agentic mode.
   • Claude CLI: run claude --add-dir ../shopping-notes-api ../shopping-notes-frontend .. from shopping-notes-spex repo
   • Zed: add project, pick all packages (folders)
4. Run your first agent skill (skill) /spex-setup in the AI chat window to add the packages and complete setup. Skills will be detected by the AI coding agent (agent) if the setup is done right.

Prefer one git repository? Run spex init in its root and pick single-repo (the project is the repository) or monorepo (one repository, several packages). Either way it creates a spex/ folder and puts AGENTS.md, CLAUDE.md, .agents and .claude in the repository root, keeping any you already have.

Adoption

After setup is completed you get basic skills and rules which you can customize for your project or leave them as is to be synced from upstream.

For existing project you can generate all specs based on existing code or gradually add them based on features you are working on. For example if you want to limit the shopping item name length, ask AI to generate spec based on how adding a shopping item currently works, then do your changes.

Typical workflow

Feature

Say you want to add shopping item creation functionality to the backend. Here's what you will do:

1. Create spec /spex-spec backend add shopping item endpoint. Will create shopping-notes-spex/specs/api-add-shopping-item.yaml
2. Derive the contract for a spec /spex-contract api-add-shopping-item. Will add the createItem endpoint to shopping-notes-spex/contracts/api.openapi.yaml.
3. Implement it /spex-implement api-add-shopping-item. Will implement a spec as written following applicable rules and skill instructions.
4. Review review focused on implementation with /spex-review api-add-shopping-item to ensure conformance with spec and applicable rules.
5. Add tests /spex-test api-add-shopping-item. Will add tests coverage for the implemented spec and at the same time work as last verification layer.

Tip: you can combine skills /spex-spec /spex-contract or run /spex-assembly-line to implement, review and fix in loop and test.

Rule

Say you want to add a rule to ensure we don't commit sensitive information. Here's what you will do:

Create a rule: /spex-rule secret handling. Will create shopping-notes-spex/rules/secret-handling.yaml with checks to verify it.

Framework Principles

• AI over Manual Coding: used right, AI writes code faster than a developer while keeping quality high, so the agent writes every artifact — specs, contracts, plans, code, and tests.
• Specs over Guesswork: clear, well-defined specs eliminate guesswork, giving explicit acceptance criteria for the AI to follow and the developer to verify.
• Rules over Tribal Knowledge: cross-cutting conventions are captured as rules, proven by automated checks, instead of living as tribal knowledge.
• Skills over Ad Hoc Prompting: each workflow step is a written, repeatable skill instead of an improvised prompt, loaded progressively to keep the context small.
• Human Approval over Vibe Coding: the AI writes everything and the human decides, approving each artifact before the next is generated.
• Deterministic Checks over Judgment: every check that can be a script must be a script, proving the change does what the spec demands and nothing else broke.
• Traceability over Assumption: every behavioral change traces to a spec, bidirectionally — spec -> contract -> code -> test, and back — so related parts are found fast and no acceptance criterion is forgotten.

See full principles, along with the values that support them, in prd.md.

Description

The flow from business goal to verified code:

For example, the shopping item feature of the shopping-notes example moves through the flow like this:

1. PRD — let users note down shopping items so they don't forget to buy them when visiting a store, by managing a shopping list in the web app: add, view, mark as bought, delete, and clear items

2. Spec — api-add-shopping-item: Create a shopping item.

   Acceptance criteria:

   • MUST create an item with the given name and bought: false when POST /items is called with a non-empty name
   • MUST assign each created item a unique id
   • MUST persist the created item to the JSON file store so it survives an API restart
   • MUST NOT create an item when name is missing or empty

3. Contract — OpenAPI definition of createItem returning 201, tagged @spec contract api-add-shopping-item. The frontend counterpart fe-add-shopping-item uses a Figma reference as its contract instead

4. Implementation — the POST /items handler in app.ts, tagged @spec impl api-add-shopping-item#create-item-with-name

5. Test — app.test.ts verifies that an item is created with the given name and bought: false, tagged @spec test api-add-shopping-item#create-item-with-name

flowchart TD
    PRD["PRD (optional) — why and what"] --> Func

    subgraph Traced ["traced by spec ID"]
        Func["Spec — what it provides"] --> Contract["Contract (if applicable) — interface"]
        Contract --> Plan["Plan (optional) — how to build it"]
        Plan --> Impl["Implementation — code"]
        Impl --> Test["Test — proof"]
    end

Rules live outside the feature flow — they govern how every artifact is built:

For example, the rule secret-handling works like this:

1. Rule — secret-handling: "Secret protection"
2. Governs — every contract, file, and test in the package, regardless of feature
3. Proven by — checks such as no-secret-in-console-log and no-backup-files running in CI or manually with spex check

Even if a deterministic check is not possible, rules are read and followed by AI and can be used for a review by a human or another agent, which gives pretty good results.

flowchart TD
    Eng["Rule — how it's built"] -.governs.-> Flow["Contracts, code, tests"]
    Eng -.proven by.-> Checks["Automated checks, human and agent review"]

Learn more

Framework, CLI, and skill specs.

Example project with spex implemented.

Try tutorial

Ready to try it yourself? Follow the Tutorial to take the shopping-notes example from a plain multi-repo project to a fully spec-driven project, end to end.