specx

Agent skills and executable architecture guardrails for Python services.

Documentation · Quickstart · Rules · Issues

specx gives coding agents a shared architecture for Python backends and checks that the implementation still follows it. It combines composable agent skills, typed foundation classes, a project initializer, and rule-based architecture checks with stable, documented rule IDs.

Highlights

• Agent-ready workflows. Installable skills cover project structure, core behavior, FastAPI delivery, DI, persistence, settings, migrations, and tests.
• Architecture as code. specx check catches layer leaks, incorrect inheritance, hidden transaction ownership, misplaced types, and test drift.
• Explicit building blocks. Typed foundation classes give use cases, services, capabilities, controllers, repositories, gateways, and DTOs clear roles.
• A strict starting point. specx init creates a small, framework-neutral service with uv, Ruff, mypy, pytest, DI composition, and mirrored tests.

Installation

Install the CLI in an isolated environment with uv:

uv tool install specx

Upgrade it later with uv tool upgrade specx.

The agent skills are installed separately and require Node.js. This example installs the full catalog for Codex:

npx skills add maksimzayats/specx --skill '*' --agent codex -y

See Install agent skills for other agents and installation options.

Quickstart

Create a framework-neutral Python service and run its checks:

$ specx init order-service
$ cd order-service
$ make check

For an existing src/-layout project, add specx as a project dependency:

uv add specx
uv run specx check

Inspect the available guardrails from the command line:

uv run specx rule list
uv run specx rule explain use-cases.return-dtos

Configuration lives in pyproject.toml. See the configuration reference and adoption guide for selectors, exclusions, JSON output, and incremental rollout.

Documentation

• Quickstart
• How specx works
• Architecture rules
• Foundation API
• Skills catalog
• CLI reference

Contributing

Contributions are welcome. See the contributing guide for local setup and validation. Run make check before opening a pull request.

License

specx is released under the MIT License.