specx-project-tooling

Name: specx-project-tooling
Author: maksimzayats

199stars36forks

How to install specx-project-tooling?

maksimzayats/specx/specx-project-tooling

$npx -y skills add maksimzayats/specx --skill specx-project-tooling

Installs into the current project.

Summary

Add strict Python project tooling for a specx service. Use when creating or updating pyproject.toml, uv dependency groups and lock checks, Ruff formatting and linting, mypy strict mode, pytest and HTTPX2 test configuration, Makefile commands, root AGENTS.md command guidance

Files · 1

View on GitHub

SKILL.md

1	# specx Project Tooling
2
3	Use this skill to make the repository executable and checkable. Read
4	`references/tooling.md` before editing tooling files.
5
6	## Workflow
7
8	1. Use `specx init <path>` for the fresh framework-neutral baseline. It renders
9	the canonical `pyproject.toml`, Makefile, `.python-version`, health core/IOC
10	scaffold, mirrored unit tests, and root guidance, then runs
11	`uv add specx diwire` and
12	`uv add --dev mypy pytest ruff` unless `--no-sync` is passed. Let uv select
13	and record compatible releases rather than rendering dependency floors.
14	2. Preserve the repo's Python version if it already exists. For a new repo,
15	default to Python 3.14. The initializer accepts any `major.minor` value;
16	do not hardcode a release allowlist that blocks future Python versions.
17	3. Use `uv` metadata in `pyproject.toml`.
18	4. For a new project, verify current compatible releases against the official
19	package indexes and documentation before copying reference floors. Preserve
20	intentional versions in an existing repo unless the user asks to upgrade.
21	5. Add runtime dependencies only for real runtime features. For a starter API,
22	include `specx`, FastAPI, `diwire`, `pydantic-settings`, and Uvicorn.
23	6. Add dev dependencies for pytest, Ruff, mypy, HTTP testing, and ASGI lifespan
24	testing when there is a FastAPI app.
25	7. Keep mypy strict. Do not enable the DIWire mypy plugin for constructor-field
26	injection; it is only needed if an existing project intentionally uses
27	`resolver_context.inject` function wrappers.
28	8. Enable `select = ["ALL"]` for Ruff in new projects. Ignore only formatter
29	conflicts and deliberate file-category conventions, and put a concise
30	comment describing what each ignored rule checks beside its code.
31	9. Generate `[tool.specx]` with `select = ["ALL"]` so every applicable built-in
32	guardrail is explicit. Missing technology surfaces are skipped for `ALL`;
33	explicit technology selectors still warn when their surface is absent.
34	10. Add simple Makefile targets: `check`, `format`, `lint`, `test`, and `dev`
35	when there is a FastAPI delivery app. `lint` runs Ruff, mypy, and
36	`uv run --locked specx check`; do not create separate `guardrails` or
37	`lock-check` targets.
38	11. If SQLAlchemy adapters exist, add Alembic dependency/config and
39	`migrate`/`makemigrations` targets with `$specx-sqlalchemy-migrations`.
40	12. When adding or changing Makefile targets, update root `AGENTS.md` Commands
41	so coding agents run the right project commands.
42	13. Use locked execution for non-mutating validation commands.
43	14. Run the smallest useful checks after changing tooling.
44
45	## Guardrails
46
47	- Do not add heavyweight services such as Docker, Alembic, Redis, or
48	PostgreSQL unless the repo has code that uses them.
49	- Once a SQLAlchemy adapter exists, Alembic is required. Do not use
50	`metadata.create_all` as a replacement for migrations.
51	- Do not split linting rules across many files unless the project already does.
52	- Keep commands copyable and non-interactive.
53	- Keep `AGENTS.md` command guidance aligned with the actual Makefile. Do not
54	list migration commands before SQLAlchemy/Alembic exists.
55
56	## Code Style
57
58	Use blank lines as logical separators in all code. Keep related statements
59	together, but separate independent setup, action, assertion, response, branch,
60	and transformation groups so long blocks stay readable.
61
62	## References
63
64	- `references/tooling.md` - recommended `pyproject.toml`, Makefile, and command
65	patterns.

People who liked this also viewed

6 picks

Type

specx-project-tooling

199stars36forks

View on GitHub

How to install specx-project-tooling?

maksimzayats/specx/specx-project-tooling

$npx -y skills add maksimzayats/specx --skill specx-project-tooling

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# specx Project Tooling
2
3	Use this skill to make the repository executable and checkable. Read
4	`references/tooling.md` before editing tooling files.
5
6	## Workflow
7
8	1. Use `specx init <path>` for the fresh framework-neutral baseline. It renders
9	the canonical `pyproject.toml`, Makefile, `.python-version`, health core/IOC
10	scaffold, mirrored unit tests, and root guidance, then runs
11	`uv add specx diwire` and
12	`uv add --dev mypy pytest ruff` unless `--no-sync` is passed. Let uv select
13	and record compatible releases rather than rendering dependency floors.
14	2. Preserve the repo's Python version if it already exists. For a new repo,
15	default to Python 3.14. The initializer accepts any `major.minor` value;
16	do not hardcode a release allowlist that blocks future Python versions.
17	3. Use `uv` metadata in `pyproject.toml`.
18	4. For a new project, verify current compatible releases against the official
19	package indexes and documentation before copying reference floors. Preserve
20	intentional versions in an existing repo unless the user asks to upgrade.
21	5. Add runtime dependencies only for real runtime features. For a starter API,
22	include `specx`, FastAPI, `diwire`, `pydantic-settings`, and Uvicorn.
23	6. Add dev dependencies for pytest, Ruff, mypy, HTTP testing, and ASGI lifespan
24	testing when there is a FastAPI app.
25	7. Keep mypy strict. Do not enable the DIWire mypy plugin for constructor-field
26	injection; it is only needed if an existing project intentionally uses
27	`resolver_context.inject` function wrappers.
28	8. Enable `select = ["ALL"]` for Ruff in new projects. Ignore only formatter
29	conflicts and deliberate file-category conventions, and put a concise
30	comment describing what each ignored rule checks beside its code.
31	9. Generate `[tool.specx]` with `select = ["ALL"]` so every applicable built-in
32	guardrail is explicit. Missing technology surfaces are skipped for `ALL`;
33	explicit technology selectors still warn when their surface is absent.
34	10. Add simple Makefile targets: `check`, `format`, `lint`, `test`, and `dev`
35	when there is a FastAPI delivery app. `lint` runs Ruff, mypy, and
36	`uv run --locked specx check`; do not create separate `guardrails` or
37	`lock-check` targets.
38	11. If SQLAlchemy adapters exist, add Alembic dependency/config and
39	`migrate`/`makemigrations` targets with `$specx-sqlalchemy-migrations`.
40	12. When adding or changing Makefile targets, update root `AGENTS.md` Commands
41	so coding agents run the right project commands.
42	13. Use locked execution for non-mutating validation commands.
43	14. Run the smallest useful checks after changing tooling.
44
45	## Guardrails
46
47	- Do not add heavyweight services such as Docker, Alembic, Redis, or
48	PostgreSQL unless the repo has code that uses them.
49	- Once a SQLAlchemy adapter exists, Alembic is required. Do not use
50	`metadata.create_all` as a replacement for migrations.
51	- Do not split linting rules across many files unless the project already does.
52	- Keep commands copyable and non-interactive.
53	- Keep `AGENTS.md` command guidance aligned with the actual Makefile. Do not
54	list migration commands before SQLAlchemy/Alembic exists.
55
56	## Code Style
57
58	Use blank lines as logical separators in all code. Keep related statements
59	together, but separate independent setup, action, assertion, response, branch,
60	and transformation groups so long blocks stay readable.
61
62	## References
63
64	- `references/tooling.md` - recommended `pyproject.toml`, Makefile, and command
65	patterns.

People who liked this also viewed

6 picks

Type