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](https://docs.astral.sh/uv/getting-started/installation/): ```sh 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: ```sh npx skills add maksimzayats/specx --skill '*' --agent codex -y ``` See [Install agent skills](https://specx.dev/docs/guides/install-agent-skills/) for other agents and installation options. ## Quickstart Create a framework-neutral Python service and run its checks: ```console $ specx init order-service $ cd order-service $ make check ``` For an existing `src/`-layout project, add specx as a project dependency: ```sh uv add specx uv run specx check ``` Inspect the available guardrails from the command line: ```sh uv run specx rule list uv run specx rule explain use-cases.return-dtos ``` Configuration lives in `pyproject.toml`. See the [configuration reference](https://specx.dev/docs/reference/configuration/) and [adoption guide](https://specx.dev/docs/guides/adopt-specx-in-an-existing-service/) for selectors, exclusions, JSON output, and incremental rollout. ## Documentation - [Quickstart](https://specx.dev/docs/overview/quickstart/) - [How specx works](https://specx.dev/docs/overview/how-specx-works/) - [Architecture rules](https://specx.dev/docs/reference/architecture-rules/) - [Foundation API](https://specx.dev/docs/reference/foundation-api/) - [Skills catalog](https://specx.dev/docs/reference/skills-catalog/) - [CLI reference](https://specx.dev/docs/reference/cli/) ## Contributing Contributions are welcome. See the [contributing guide](https://github.com/maksimzayats/specx/blob/main/CONTRIBUTING.md) for local setup and validation. Run `make check` before opening a pull request. ## License specx is released under the [MIT License](https://github.com/maksimzayats/specx/blob/main/LICENSE.md).