specx-project-structure

Name: specx-project-structure
Author: maksimzayats

199stars36forks

How to install specx-project-structure?

maksimzayats/specx/specx-project-structure

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

Installs into the current project.

Summary

Create or reshape a Python FastAPI service repo into the specx clean core/delivery architecture using packaged scoped foundation bases. Use when starting an API backend, adding the first src package, or establishing AGENTS.md, core/, optional local foundation/, delivery/,

Files · 1

View on GitHub

SKILL.md

1	# specx Project Structure
2
3	Use this skill to create the repo shell and first runnable vertical slice. For
4	details, read `references/blueprint.md`.
5
6	## Workflow
7
8	1. For a fresh framework-neutral repo, start with `specx init <path>`. It creates
9	packaging, strict tooling, root `AGENTS.md`, a small `core/health` use case
10	and pure service, `ioc/container.py`, and mirrored unit tests. It
11	intentionally omits delivery and infrastructure; add those packages only
12	with real technology-specific behavior.
13	2. Preserve an existing import package declared by the repo. For a new repo,
14	derive a lowercase underscore name, normalize every non-identifier
15	character, and verify `name.isidentifier()` and
16	`not keyword.iskeyword(name)`; distribution names and import packages need
17	not be identical. If normalization still yields a keyword or leading digit,
18	choose an explicit valid package name rather than emitting it unchanged.
19	3. Create `src/<package>/` and `tests/` packages with empty `__init__.py` files only.
20	4. Add `specx` as a runtime dependency and import base classes from
21	`specx.core.foundation`, `specx.delivery.foundation`, or
22	`specx.infrastructure.foundation`.
23	5. Use `core/<scope>/` as the main boundary. Put application packages at the
24	scope root: `capabilities/`, `dtos/`, `entities/`, `exceptions/`,
25	`gateways/`, `repositories/`, `services/`, and `use_cases/`. Put
26	scope-owned technical adapters under `infrastructure/` only when real IO
27	exists.
28	6. Add top-level `delivery/` for runnable framework apps, lifecycles,
29	controllers, request/response schemas, and delivery-only services.
30	7. Add top-level `infrastructure/` for shared technical resources such as
31	SQLAlchemy session factories, logging, telemetry, and external client
32	factories. App-owned pooled clients live here even when only one scope
33	currently consumes them; bounded short-lived clients may stay with the
34	scope adapter.
35	8. Add `infrastructure/logging/` with a stdlib `LoggingConfigurator` and
36	`LoggingSettings` for every new API repo.
37	9. Add `ioc/` for `diwire.Container` creation and explicit bindings.
38	10. Add `shared/` only for stable cross-scope application primitives such as
39	unit-of-work contracts, clocks, ids, or errors.
40	11. Add `migrations/` with Alembic when SQLAlchemy models exist.
41	12. Build the first user-requested business vertical slice. The initializer's
42	process-health slice is a framework-neutral composition example, not a
43	readiness check. With a delivery framework, map or replace it deliberately:
44	keep simple liveness at delivery, and use `core/health` for `/readyz` when
45	readiness checks a required dependency or policy is shared across deliveries.
46	13. Create root `AGENTS.md` for every new repo. Include runnable project
47	commands from `$specx-project-tooling` and specx boundaries from
48	`$specx-component-architecture`.
49	14. Do not create an empty local `foundation/` package. Create
50	`src/<package>/foundation/` only for a real project-local base category or a
51	stateful framework base that must not be shared globally, such as a
52	SQLAlchemy declarative base.
53	15. Add tests only where there is real code to test. Do not create empty folders
54	just to satisfy the diagram.
55
56	## Non-Negotiable Boundaries
57
58	- Keep all source and test `__init__.py` files empty. Do not add empty local
59	foundation, source, test, or helper packages.
60	- Every non-foundation source class inherits an explicit packaged or local
61	scoped base and uses the suffix implied by that ancestry. Every source class,
62	including local bases, has a scoped docstring with a real `Example:`.
63	- Keep core inner packages free of delivery, IOC, SQLAlchemy, Redis, HTTP
64	clients, and framework imports. Put concrete IO adapters under
65	`core/<scope>/infrastructure/<technology>/`.
66	- Capabilities are narrow `BaseCapability` collaborators; gateways are
67	business-language `BaseGateway` ports; core services choose
68	`BasePureService`, `BaseReadService`, or `BaseEffectService`.
69	- Same-file `BaseCommand` or `BaseQuery` inputs enter use cases, and result DTOs
70	leave them. Persistence use cases inject a `UnitOfWorkManager`; services do
71	not open or finish transactions.
72	- Prefer frozen, keyword-only, slotted dataclasses for core data and
73	`BaseStrEnum` for reusable closed value sets. Keep Pydantic at delivery and
74	settings edges.
75	- Keep infrastructure technical and schema evolution in Alembic. Never call
76	`metadata.create_all` or `drop_all` in application or test code.
77	- Configure stdlib logging once before composing the FastAPI app. Use FastAPI
78	lifespan for resour

People who liked this also viewed

6 picks

Type

specx-project-structure

199stars36forks

View on GitHub

How to install specx-project-structure?

maksimzayats/specx/specx-project-structure

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# specx Project Structure
2
3	Use this skill to create the repo shell and first runnable vertical slice. For
4	details, read `references/blueprint.md`.
5
6	## Workflow
7
8	1. For a fresh framework-neutral repo, start with `specx init <path>`. It creates
9	packaging, strict tooling, root `AGENTS.md`, a small `core/health` use case
10	and pure service, `ioc/container.py`, and mirrored unit tests. It
11	intentionally omits delivery and infrastructure; add those packages only
12	with real technology-specific behavior.
13	2. Preserve an existing import package declared by the repo. For a new repo,
14	derive a lowercase underscore name, normalize every non-identifier
15	character, and verify `name.isidentifier()` and
16	`not keyword.iskeyword(name)`; distribution names and import packages need
17	not be identical. If normalization still yields a keyword or leading digit,
18	choose an explicit valid package name rather than emitting it unchanged.
19	3. Create `src/<package>/` and `tests/` packages with empty `__init__.py` files only.
20	4. Add `specx` as a runtime dependency and import base classes from
21	`specx.core.foundation`, `specx.delivery.foundation`, or
22	`specx.infrastructure.foundation`.
23	5. Use `core/<scope>/` as the main boundary. Put application packages at the
24	scope root: `capabilities/`, `dtos/`, `entities/`, `exceptions/`,
25	`gateways/`, `repositories/`, `services/`, and `use_cases/`. Put
26	scope-owned technical adapters under `infrastructure/` only when real IO
27	exists.
28	6. Add top-level `delivery/` for runnable framework apps, lifecycles,
29	controllers, request/response schemas, and delivery-only services.
30	7. Add top-level `infrastructure/` for shared technical resources such as
31	SQLAlchemy session factories, logging, telemetry, and external client
32	factories. App-owned pooled clients live here even when only one scope
33	currently consumes them; bounded short-lived clients may stay with the
34	scope adapter.
35	8. Add `infrastructure/logging/` with a stdlib `LoggingConfigurator` and
36	`LoggingSettings` for every new API repo.
37	9. Add `ioc/` for `diwire.Container` creation and explicit bindings.
38	10. Add `shared/` only for stable cross-scope application primitives such as
39	unit-of-work contracts, clocks, ids, or errors.
40	11. Add `migrations/` with Alembic when SQLAlchemy models exist.
41	12. Build the first user-requested business vertical slice. The initializer's
42	process-health slice is a framework-neutral composition example, not a
43	readiness check. With a delivery framework, map or replace it deliberately:
44	keep simple liveness at delivery, and use `core/health` for `/readyz` when
45	readiness checks a required dependency or policy is shared across deliveries.
46	13. Create root `AGENTS.md` for every new repo. Include runnable project
47	commands from `$specx-project-tooling` and specx boundaries from
48	`$specx-component-architecture`.
49	14. Do not create an empty local `foundation/` package. Create
50	`src/<package>/foundation/` only for a real project-local base category or a
51	stateful framework base that must not be shared globally, such as a
52	SQLAlchemy declarative base.
53	15. Add tests only where there is real code to test. Do not create empty folders
54	just to satisfy the diagram.
55
56	## Non-Negotiable Boundaries
57
58	- Keep all source and test `__init__.py` files empty. Do not add empty local
59	foundation, source, test, or helper packages.
60	- Every non-foundation source class inherits an explicit packaged or local
61	scoped base and uses the suffix implied by that ancestry. Every source class,
62	including local bases, has a scoped docstring with a real `Example:`.
63	- Keep core inner packages free of delivery, IOC, SQLAlchemy, Redis, HTTP
64	clients, and framework imports. Put concrete IO adapters under
65	`core/<scope>/infrastructure/<technology>/`.
66	- Capabilities are narrow `BaseCapability` collaborators; gateways are
67	business-language `BaseGateway` ports; core services choose
68	`BasePureService`, `BaseReadService`, or `BaseEffectService`.
69	- Same-file `BaseCommand` or `BaseQuery` inputs enter use cases, and result DTOs
70	leave them. Persistence use cases inject a `UnitOfWorkManager`; services do
71	not open or finish transactions.
72	- Prefer frozen, keyword-only, slotted dataclasses for core data and
73	`BaseStrEnum` for reusable closed value sets. Keep Pydantic at delivery and
74	settings edges.
75	- Keep infrastructure technical and schema evolution in Alembic. Never call
76	`metadata.create_all` or `drop_all` in application or test code.
77	- Configure stdlib logging once before composing the FastAPI app. Use FastAPI
78	lifespan for resour

People who liked this also viewed

6 picks

Type