Specx Project Tooling

specx Project Tooling

Use this skill to make the repository executable and checkable. Read references/tooling.md before editing tooling files.

Workflow

1. Use specx init for the fresh framework-neutral baseline. It renders

the canonical pyproject.toml, Makefile, .python-version, health core/IOC scaffold, mirrored unit tests, and root guidance, then runs uv add specx diwire and uv add --dev mypy pytest ruff unless --no-sync is passed. Let uv select and record compatible releases rather than rendering dependency floors.

1. Preserve the repo's Python version if it already exists. For a new repo,

default to Python 3.14. The initializer accepts any major.minor value; do not hardcode a release allowlist that blocks future Python versions.

1. Use uv metadata in pyproject.toml.
2. For a new project, verify current compatible releases against the official

package indexes and documentation before copying reference floors. Preserve intentional versions in an existing repo unless the user asks to upgrade.

1. Add runtime dependencies only for real runtime features. For a starter API,

include specx, FastAPI, diwire, pydantic-settings, and Uvicorn.

1. Add dev dependencies for pytest, Ruff, mypy, HTTP testing, and ASGI lifespan

testing when there is a FastAPI app.

1. Keep mypy strict. Do not enable the DIWire mypy plugin for constructor-field

injection; it is only needed if an existing project intentionally uses resolver_context.inject function wrappers.

1. Enable select = ["ALL"] for Ruff in new projects. Ignore only formatter

conflicts and deliberate file-category conventions, and put a concise comment describing what each ignored rule checks beside its code.

1. Generate [tool.specx] with select = ["ALL"] so every applicable built-in

guardrail is explicit. Missing technology surfaces are skipped for ALL; explicit technology selectors still warn when their surface is absent.

1. Add simple Makefile targets: check, format, lint, test, and dev

when there is a FastAPI delivery app. lint runs Ruff, mypy, and uv run --locked specx check; do not create separate guardrails or lock-check targets.

1. If SQLAlchemy adapters exist, add Alembic dependency/config and

migrate/makemigrations targets with $specx-sqlalchemy-migrations.

1. When adding or changing Makefile targets, update root AGENTS.md Commands

so coding agents run the right project commands.

1. Use locked execution for non-mutating validation commands.
2. Run the smallest useful checks after changing tooling.

Guardrails

• Do not add heavyweight services such as Docker, Alembic, Redis, or

PostgreSQL unless the repo has code that uses them.

• Once a SQLAlchemy adapter exists, Alembic is required. Do not use

metadata.create_all as a replacement for migrations.

• Do not split linting rules across many files unless the project already does.
• Keep commands copyable and non-interactive.
• Keep AGENTS.md command guidance aligned with the actual Makefile. Do not

list migration commands before SQLAlchemy/Alembic exists.

Code Style

Use blank lines as logical separators in all code. Keep related statements together, but separate independent setup, action, assertion, response, branch, and transformation groups so long blocks stay readable.

References

• references/tooling.md - recommended pyproject.toml, Makefile, and command

patterns.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maksimzayats
• Source: maksimzayats/specx
• License: MIT
• Homepage: https://specx.dev

Install and usage instructions live in the source repository linked above.