Implement a Service¶
Workflow · implement-service
Invoke it in the AI chat with /implement-service. Install the skills ·
View source
The failure mode this prevents is a large, plausible, unreviewable diff. Code arrives in layers, each validated against the principles before it is shown, each small enough that a human can actually read it.
Required Skills¶
Read and apply:
clean-architecture— layer placement and dependency direction for every file. (always)test-strategy— every component ships with tests at the right level. (always)collaborative-judgment— deviations and trade-offs are surfaced, not absorbed. (always)domain-modelling— aggregates, entities, value objects, where behaviour lives. (conditional: domain types)data-access— repositories, queries, transactions, migrations, caches. (conditional: persistence)cqrs-and-consistency— read models and projections. (conditional: a separate read path)infrastructure-adapters— ports, clients, consumers, publishers, SDK wrappers. (conditional: the adapter layer)resilience-patterns— timeouts, retries, breakers, outbox. (conditional: any call leaving the process, any message handler)idempotency-and-immutability— retry safety and shared state. (conditional: retryable operations, message handlers, value types)secure-service— authorisation, validation, secrets, output hygiene. (conditional: any trust boundary — handlers, clients, queries, anything touching credentials or personal data)api-contracts— the shape of anything crossing a boundary. (conditional: endpoints, schemas, published events)api-protocols— protocol-specific craft. (conditional: GraphQL, gRPC, WebSocket or SSE)config-and-dependencies— settings, flags, new libraries. (conditional: config or dependency changes)contract-testing— cross-service agreement. (conditional: an integration with another service)
Workflow¶
Step 1 — Establish the ground¶
- Read
.msskills/stack.md. Absent → say once thatstack-profilewould make the generated code match the project's idiom, then infer conventions from the repository and proceed. - Read
.msskills/decisions.md— recorded decisions are binding. - Find the blueprint in
.msskills/designs/for this feature.
Design gate. Check the blueprint's frontmatter:
status: approved→ proceed with an approved design.status: complete→ already implemented. If this is new scope, recommenddesign-servicefor a fresh pass. If the user confirms, continue.status: draft, or no blueprint → STOP: "There is no approved design for this. Run/design-servicefirst, or shall I proceed from what we have discussed?" On confirmation, record it as a decision and continue without an approved design — every principle still applies; there is simply no agreed contract to build against.
Level gate. With a blueprint, check which levels it contains. Missing L3 or L4 means the failure behaviour or the contracts were never agreed — STOP, say which are missing, and ask whether to proceed and fill them as you go or to design them first.
- Read the existing code before writing any. Find the patterns already in use — error handling, naming, test structure, package layout — and match them. Code that is correct but foreign is a review burden.
Step 2 — Plan and agree the order¶
Derive the component list from the blueprint's L2, or classify it yourself against
clean-architecture if there is no blueprint.
Plan inside-out: start at the innermost layer with no outward dependencies and work outward, so each component's dependencies already exist when it is built. Typically: domain types → domain logic → ports → application use cases → adapters → wiring and configuration.
Present the plan — the ordered component list, each one's layer, and what already exists that you will reuse. Then ask for a review mode:
How should we review this? 1. Layer by layer (recommended) — implement a full layer, pause for review, then the next. 2. All at once — implement end to end, review the complete result. 3. Component by component — pause after each one.
Default to layer by layer. STOP — do not write code against an unagreed plan. If the user corrects the plan, revise and re-present it.
Step 3 — Implement, component by component¶
For each component, in the planned order, write code and its tests together.
Before writing:
- Prefer what exists. Does the standard library, an existing dependency, or existing code in
this repository already do this? Use it. Adding a dependency runs
config-and-dependenciesfirst. - Prefer the simpler shape. No abstraction without a named force (
clean-architecture).
While writing, apply the principles that govern this component:
| Component kind | Apply |
|---|---|
| Domain type or aggregate | domain-modelling, clean-architecture, idempotency-and-immutability |
| Repository, query, or migration | data-access, clean-architecture |
| Read model or projection | cqrs-and-consistency, data-access |
| Use case / handler | clean-architecture, secure-service, idempotency-and-immutability |
| Inbound adapter (HTTP, consumer) | infrastructure-adapters, api-contracts, api-protocols, secure-service |
| Outbound adapter (client, publisher) | infrastructure-adapters, resilience-patterns, secure-service |
| Configuration or flag | config-and-dependencies |
| Tests | test-strategy, plus contract-testing at a service boundary |
Post-generation verification — before showing anything:
- Run the Self-Validation Checklist of every applicable principle against every function and type in the component. The checklists say STOP and verify; do that literally.
- Run every applicable Active Anti-Pattern Scan. Check each box honestly.
- Fix every violation found. Do not present code you know fails a check.
- Collect flagged Ambiguity Signals and present them through
collaborative-judgmentbefore showing the code. Never resolve a real trade-off silently to keep momentum. - Run the tests you wrote, if the environment allows. Report the result. If you could not run them, say so — never imply tests passed when they were only written.
- Present with a one-line compliance note when clean; be verbose only when reporting a violation you fixed or a decision you need.
Pace by the chosen review mode. In every mode, one exception overrides it: a component needing a significant deviation — a new dependency, a changed contract, unexpected complexity, a blueprint decision that turns out to be unworkable — STOPS immediately for discussion, whatever the mode.
Step 4 — Verify across components¶
Once the components exist:
- Wire it and run it. Start the service. A set of components that has never been assembled is not an implementation.
- Run the whole suite, not just the new tests. Report failures with their output.
- Trace one flow end to end against the blueprint's L3: does the real code follow the agreed interactions, with the agreed timeouts and failure behaviour?
- Verify the contracts against L4 — request and response shapes, error catalogue, event schemas. Flag every deviation; do not quietly ship a different contract from the approved one.
- Check the failure paths actually work: the timeout fires, the breaker opens, the duplicate
message is ignored, the compensation runs. These are the paths that only execute on the worst
day (
test-strategy).
Step 5 — Close out¶
- Update the blueprint:
status: complete, and record any decision made during implementation in its Decisions Log. - Append cross-cutting decisions to
.msskills/decisions.md. - Summarise: what was built, what was reused, which tests cover what, what is deliberately not done.
- Name the follow-ups explicitly rather than leaving them implicit.
- Recommend
review-servicefor an independent audit before the change is merged.
Rules¶
- Never present code that fails a checklist. Fix it first.
- Tests are part of the component, not a later step.
- Never claim a test passed without running it.
- A deviation from the approved design stops the work. Surface it; the design is what was agreed, and changing it is the user's call.
- Match the repository's conventions over this library's examples.
- Do not touch unrelated code. Improvements you notice go in the close-out list, not in the diff.