Specx Add Core Service

specx Add Core Service

Use this skill for reusable core behavior that is smaller than an application action. Read references/service.md before writing the service.

Workflow

1. Confirm this is reusable business/application behavior, not a small

replaceable ability. Use BaseCapability instead for one narrow injectable thing.

1. Name the behavior, not a vague role, and always use the Service suffix:

InvoicePricingService, AccessPolicyService, OrderAllocationService, SubscriptionRenewalService.

1. Put it under core//services/.py.
2. Choose exactly one foundation base:

BasePureService, BaseReadService, or BaseEffectService.

1. Do not add or use a generic BaseService.
2. Inject concrete project collaborators when there is one implementation.
3. Inject ports/ABCs only for external IO, framework-bound dependencies, or

multiple real implementations. Do not create an interface only to make a concrete collaborator mockable.

1. Add a docstring that explains the service scope and includes a concrete

Example:.

1. Keep methods keyword-only after self.
2. Do not open UoW scopes in services. Use cases own transaction lifecycle and

pass active UoWs into read/effect services when needed.

1. Add flat unit tests that receive the native pytest container fixture,

register local doubles or inline mocks before resolution, and resolve the service with container.resolve(ServiceClass).

Operational probe services may live under core/health when readiness checks any required external dependency or policy is reused across deliveries. Keep simple process liveness in delivery. Use a pure service for reusable liveness policy and a read service for readiness coordination. Readiness services depend on gateway ports, not SQLAlchemy, Redis, SDKs, or delivery frameworks directly. Technical readiness adapters must bound external checks with short timeouts so a probe cannot hang indefinitely.

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/service.md - class shape, dependency choices, UoW parameter

rules, and unit-test examples.

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.