Skip to content
Back to search

specx

⚙️ Executable architecture guardrails and agent skills for building structured Python services!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maksimzayats--specx/badge.svg)](/listings/maksimzayats--specx)

HTML

<a href="/listings/maksimzayats--specx"><img src="/api/listings/maksimzayats--specx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the CLI in an isolated environment with [uv](https://docs.astral.sh/uv/getting-started/installation/):

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](https://specx.dev/docs/guides/install-agent-skills/) for other agents and installation options.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 112 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="https://specx.dev">
  3. <img alt="specx" src="https://raw.githubusercontent.com/maksimzayats/specx/main/docs/public/favicon.svg" width="72">
  4. </a>
  5. </p>
  6. <h1 align="center">specx</h1>
  7. <p align="center">
  8. Agent skills and executable architecture guardrails for Python services.
  9. </p>
  10. <p align="center">
  11. <a href="https://pypi.org/project/specx/"><img alt="PyPI" src="https://img.shields.io/pypi/v/specx.svg"></a>
  12. <a href="https://pypi.org/project/specx/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/specx.svg"></a>
  13. <a href="https://github.com/maksimzayats/specx/actions/workflows/deploy-storybook.yml"><img alt="Documentation build" src="https://img.shields.io/github/actions/workflow/status/maksimzayats/specx/deploy-storybook.yml?branch=main&label=docs"></a>
  14. <a href="https://github.com/maksimzayats/specx/blob/main/LICENSE.md"><img alt="MIT license" src="https://img.shields.io/github/license/maksimzayats/specx.svg"></a>
  15. </p>
  16. <p align="center">
  17. <a href="https://specx.dev"><strong>Documentation</strong></a> ·
  18. <a href="https://specx.dev/docs/overview/quickstart/"><strong>Quickstart</strong></a> ·
  19. <a href="https://specx.dev/docs/reference/architecture-rules/"><strong>Rules</strong></a> ·
  20. <a href="https://github.com/maksimzayats/specx/issues"><strong>Issues</strong></a>
  21. </p>
  22. `specx` gives coding agents a shared architecture for Python backends and checks
  23. that the implementation still follows it. It combines composable agent skills,
  24. typed foundation classes, a project initializer, and rule-based architecture
  25. checks with stable, documented rule IDs.
  26. ## Highlights
  27. - **Agent-ready workflows.** Installable skills cover project structure, core
  28. behavior, FastAPI delivery, DI, persistence, settings, migrations, and tests.
  29. - **Architecture as code.** `specx check` catches layer leaks, incorrect
  30. inheritance, hidden transaction ownership, misplaced types, and test drift.
  31. - **Explicit building blocks.** Typed foundation classes give use cases,
  32. services, capabilities, controllers, repositories, gateways, and DTOs clear
  33. roles.
  34. - **A strict starting point.** `specx init` creates a small, framework-neutral
  35. service with uv, Ruff, mypy, pytest, DI composition, and mirrored tests.
  36. ## Installation
  37. Install the CLI in an isolated environment with
  38. [uv](https://docs.astral.sh/uv/getting-started/installation/):
  39. ```sh
  40. uv tool install specx
  41. ```
  42. Upgrade it later with `uv tool upgrade specx`.
  43. The agent skills are installed separately and require Node.js. This example
  44. installs the full catalog for Codex:
  45. ```sh
  46. npx skills add maksimzayats/specx --skill '*' --agent codex -y
  47. ```
  48. See [Install agent skills](https://specx.dev/docs/guides/install-agent-skills/)
  49. for other agents and installation options.
  50. ## Quickstart
  51. Create a framework-neutral Python service and run its checks:
  52. ```console
  53. $ specx init order-service
  54. $ cd order-service
  55. $ make check
  56. ```
  57. For an existing `src/`-layout project, add specx as a project dependency:
  58. ```sh
  59. uv add specx
  60. uv run specx check
  61. ```
  62. Inspect the available guardrails from the command line:
  63. ```sh
  64. uv run specx rule list
  65. uv run specx rule explain use-cases.return-dtos
  66. ```
  67. Configuration lives in `pyproject.toml`. See the
  68. [configuration reference](https://specx.dev/docs/reference/configuration/) and
  69. [adoption guide](https://specx.dev/docs/guides/adopt-specx-in-an-existing-service/)
  70. for selectors, exclusions, JSON output, and incremental rollout.
  71. ## Documentation
  72. - [Quickstart](https://specx.dev/docs/overview/quickstart/)
  73. - [How specx works](https://specx.dev/docs/overview/how-specx-works/)
  74. - [Architecture rules](https://specx.dev/docs/reference/architecture-rules/)
  75. - [Foundation API](https://specx.dev/docs/reference/foundation-api/)
  76. - [Skills catalog](https://specx.dev/docs/reference/skills-catalog/)
  77. - [CLI reference](https://specx.dev/docs/reference/cli/)
  78. ## Contributing
  79. Contributions are welcome. See the
  80. [contributing guide](https://github.com/maksimzayats/specx/blob/main/CONTRIBUTING.md)
  81. for local setup and validation. Run `make check` before opening a pull request.
  82. ## License
  83. specx is released under the
  84. [MIT License](https://github.com/maksimzayats/specx/blob/main/LICENSE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.