spex

The essential spec layer AI agents need to build software reliably.

Scaffolds a specs/ directory so AI coding agents can read and follow your project's requirements and design.

Install

npm install -g @sublang/spex

Or run once without installing:

npx @sublang/spex scaffold

Usage

spex scaffold

This creates:

• specs/ — directories and starter templates for writing behavioral specs, decision records, and iteration plans
• CLAUDE.md / AGENTS.md — instructions that tell AI agents (Claude, Codex, etc.) to read and follow the specs before writing code

See specs/decisions/000-spec-structure-format.md for the spec format and naming conventions.

Idempotency: Rerunning is safe — existing files and directories are skipped.

Try it: review the sample iteration specs/iterations/000-spdx-headers.md, update the copyright text, then prompt your AI coding agent:

Complete Iteration #0

Updating templates

When a new release ships updated templates, refresh them with:

spex scaffold --update

• Spex-authoritative files (specs/meta.md and the spec-format decision record) are refreshed unconditionally, including when they are absent.
• Starter files (map.md, the sample iteration, boilerplate items) are refreshed when you have not customized them, and written from the bundled template when they are absent. Customized starter files are kept as-is. Remove a starter file after --update if you do not want it.
• Anything you authored outside the bundled framework and starter files is left alone.

Review the changes with git diff -- specs. Update any citations that reference renamed sections or renumbered IDs — the command prints clear next steps and a copy-paste-ready prompt you can hand to your AI agent for that review.

Workflow

Spex does not enforce a heavyweight workflow. We believe spec-driven development is a flexible combination of a few primitives.

1. Make Decisions — Discuss requirements, architecture, and design with AI agents. Let AI generate and review decision records in specs/decisions/.
2. Plan Iterations — Break down work into tasks with AI agents. Let AI generate and review iteration records in specs/iterations/.
3. Agents Execute — Let AI agents complete the tasks autonomously. They generate code and update specs/user/, specs/dev/, and specs/test/.

Then loop back to the next decision or iteration.

Requirements

• Node.js >= 20
• Git (optional, used for repo root detection)

Contributing

We welcome contributions of all kinds. If you'd like to help:

• 🌟 Star our repo if you find spex useful.
• Open an issue for bugs or feature requests.
• Open a PR for fixes or improvements.
• Discuss on Discord for support or new ideas.

License

Apache-2.0