specx CLI
A CLI checking Python service architecture against documented rules, with skills teaching the agent to code within them.
- 199 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- Generates a project and runs checks in the working directory.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/specxDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Generates a project and runs checks in the working directory.
This is third-party code. Review the repository files before installing.
What it does
specx gives coding agents a shared architecture for Python backends and checks that the implementation follows it. The `specx init` command creates a small framework-neutral service with uv, Ruff, mypy, pytest, dependency composition and mirrored tests. Typed foundation classes define roles for use cases, services, controllers, repositories, gateways and DTOs. The `specx check` command catches layer leaks, incorrect inheritance, hidden transaction ownership, misplaced types and test drift, and every rule has a stable documented ID. Skills are installed separately and cover project structure, core behavior, FastAPI, dependency injection, persistence, settings, migrations and tests.
Who it is for. Python developers who write a backend with an agent and want to automatically hold layers and class roles.
Good fit when
- A new Python service starts with an agent and needs a strict starting structure.
- The agent adds a use case and the check must catch a layer leak.
- FastAPI delivery, migrations or a persistence layer must be added to a single pattern.
- CI should fail on architecture rule violations with clear codes.
Not a fit when
- The project is not in Python.
- The team has adopted another architecture and is not ready to adapt to the proposed roles.
- You need a quick one-off utility with no layers.
Example request
Create an order-service through specx init, add an order checkout use case and run specx check.Limitations
The tool strongly imposes its own architecture: existing code must be brought into line, and `specx check` rules are not switched off by small settings. The CLI is installed with uv and the skills with Node.js through `npx skills add`. Skills install separately from the CLI and do not update with it. Service generation suits new projects, and porting old ones takes manual work. The license is MIT. The last commit is dated August 2026.
How to disable. Remove the CLI with `uv tool uninstall specx` and the skills from the agent skills directory. Created projects remain ordinary Python code.
FAQ
How do I install specx?
Run `uv tool install specx` in an isolated environment. Upgrade with `uv tool upgrade specx`.
How do I install the skills?
The command `npx skills add maksimzayats/specx --skill '*' --agent codex -y` installs the full catalog for Codex. Other agents are covered in the skill installation guide.
What does specx init create?
A small framework-neutral service with uv, Ruff, mypy, pytest, dependency composition and mirrored tests.
What does specx check catch?
Layer leaks, incorrect inheritance, hidden transaction ownership, misplaced types and test drift. Every rule has a stable ID.
Does it suit FastAPI?
Yes, the skills include FastAPI delivery, but the starter service is not tied to a framework.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill that teaches your agent to run datamodel-codegen and get Pydantic models from OpenAPI, JSON Schema and GraphQL
The official FastAPI skill, bundled with the package, teaching agents to write code for the installed version
An MCP server and plugin for agents that generate web APIs from OpenAPI, AsyncAPI, GraphQL, gRPC and SQL specs on a Rust core.
builder-skills: agent skills for Convex apps
builder-skills
17 skills that teach an agent to build Convex apps by the docs and run a project through a PRD, task.md and a changelog
A skill that interviews you about a project and writes a working Django app with up-to-date packages, settings and CI.
Laravel API Architecture Skill
Laravel API Production-Ready Architecture Skill
A skill that keeps an agent within a layered Laravel API architecture: JSON:API v1.1, strict types, PHPStan level 8 and tests
README in short
The README presents features, CLI and skills installation and a quickstart that creates a service. Detailed rules, guides and links are collected on the documentation site.