Read-set manifest: devrites-engine context --skills-root .pi/skills <slug> --skill devrites-api-interface (no workspace: --out <path>) bundles every file named below into one deduplicated read.
devrites-api-interface: contract before implementation
When a slice crosses a boundary (FE/BE, service/service, module/module) or exposes a
public interface, define the contract first so both sides can proceed and the interface
stays stable.
Define the contract first
- Shape: request/response or function signature; field names, types, optionality,
units. Follow the project's existing naming and conventions.
- Status & errors: success codes, error codes, error body shape, validation
messages. Errors are part of the contract, not an afterthought.
- Semantics: idempotency, pagination, ordering, nullability, side effects.
- Versioning/compat: is this new or a change to an existing contract? A breaking
change to an existing consumer is a user decision (and a drift event if unplanned).
Stability principles
- Design for the caller. The interface should make the common case easy and the wrong
call hard.
- Prefer addition over modification. A new field is additive and optional; changing a
field's type or removing one is a breaking change. You can add later. You can't un-ship a
shape consumers already read (observable behavior is the contract:
deprecation.md Hyrum's law).
- One-Version Rule. Design as if only one version of this interface will ever exist:
extend the single contract rather than fork a v2 you then maintain in parallel. Forking
multiplies the surface and breeds diamond-dependency conflicts; bump a version only when an
addition genuinely can't stay backward-compatible.
- Match existing endpoints/modules in style: don't introduce a competing convention.
- Validate at the boundary, and only there (untrusted → trusted); don't trust
caller-supplied trust signals (IDs, roles). Validation does not belong between two internal
typed functions, on your own database's data, or in a utility already called by validated code.
A check inside the trusted core hides the bug in the boundary that should have caught it. A
third-party API response is external input: always untrusted. (Three-tier boundary:
security.md; see security-review.md.)
Type craft: make the wrong call unrepresentable
- Brand your ids. A bare
string/number id is assignable to any other id, so the compiler
won't stop you passing a userId where a taskId is due. Give each a nominal brand
(type TaskId = string & { readonly __brand: 'TaskId' }) and the mix-up becomes a type error,
not a production incident.
- Model variants as discriminated unions, each state carrying only its own fields, so an
impossible combination can't be constructed in the first place.
Doubt the contract
Before standing the interface, run devrites-doubt.
Done when
The contract is complete only when every field carries a type + optionality + unit,
every success and error status code is enumerated with its error-body shape, the
devrites-doubt verdict is accept (on reject: revise the contract and re-doubt under
the canonical retry contract
with caller repair and human-risk gates), and the
contract + rationale are recorded in decisions.md. A contract that pins only the
happy-path shape is not done.
Enables the split
A clear contract lets /rite-plan split proceed: the backend slice can land against the
contract with a stub consumer; the frontend slice can build against a mock or the real
contract. Neither side blocks on the other.
1---2name: devrites-api-interface-43description: Shape stable API, type, module, or frontend/backend contracts before implementation. Use when a slice crosses a boundary; not for internal helpers.4user-invocable: false5metadata:6 source: https://skillmd.com/skills/viktorsbaikers/devrites-api-interface-47---89<!-- loads: {"always":["devrites-lib/reference/standards/core.md"],"triggers":{"afk":["devrites-lib/reference/standards/afk-hitl.md"],"deprecation":["devrites-lib/reference/standards/deprecation.md"],"security":["devrites-lib/reference/standards/security.md","rite-review/reference/security-review.md"]},"workspace":["spec.md","plan.md","tasks.md","state.md","decisions.md"],"rootOnly":["devrites-lib/reference/standards/afk-hitl.md"]} -->10> Read-set manifest: `devrites-engine context --skills-root .pi/skills <slug> --skill devrites-api-interface` (no workspace: `--out <path>`) bundles every file named below into one deduplicated read.1112# devrites-api-interface: contract before implementation1314When a slice crosses a boundary (FE/BE, service/service, module/module) or exposes a15public interface, define the contract first so both sides can proceed and the interface16stays stable.1718## Define the contract first19- **Shape:** request/response or function signature; field names, types, optionality,20 units. Follow the project's existing naming and conventions.21- **Status & errors:** success codes, error codes, error body shape, validation22 messages. Errors are part of the contract, not an afterthought.23- **Semantics:** idempotency, pagination, ordering, nullability, side effects.24- **Versioning/compat:** is this new or a change to an existing contract? A breaking25 change to an existing consumer is a user decision (and a drift event if unplanned).2627## Stability principles28- Design for the caller. The interface should make the common case easy and the wrong29 call hard.30- **Prefer addition over modification.** A new field is additive and optional; changing a31 field's type or removing one is a breaking change. You can add later. You can't un-ship a32 shape consumers already read (observable behavior is the contract: [`deprecation.md`](../devrites-lib/reference/standards/deprecation.md) Hyrum's law).33- **One-Version Rule.** Design as if only one version of this interface will ever exist:34 extend the single contract rather than fork a v2 you then maintain in parallel. Forking35 multiplies the surface and breeds diamond-dependency conflicts; bump a version only when an36 addition genuinely can't stay backward-compatible.37- Match existing endpoints/modules in style: don't introduce a competing convention.38- **Validate at the boundary, and only there** (untrusted → trusted); don't trust39 caller-supplied trust signals (IDs, roles). Validation does *not* belong between two internal40 typed functions, on your own database's data, or in a utility already called by validated code.41 A check inside the trusted core hides the bug in the boundary that should have caught it. A42 third-party API response is external input: always untrusted. (Three-tier boundary:43 [`security.md`](../devrites-lib/reference/standards/security.md); see [`security-review.md`](../rite-review/reference/security-review.md).)4445## Type craft: make the wrong call unrepresentable46- **Brand your ids.** A bare `string`/`number` id is assignable to any other id, so the compiler47 won't stop you passing a `userId` where a `taskId` is due. Give each a nominal brand48 (`type TaskId = string & { readonly __brand: 'TaskId' }`) and the mix-up becomes a type error,49 not a production incident.50- **Model variants as discriminated unions**, each state carrying only its own fields, so an51 impossible combination can't be constructed in the first place.5253## Doubt the contract54Before standing the interface, run `devrites-doubt`.5556## Done when57The contract is complete only when **every** field carries a type + optionality + unit,58**every** success and error status code is enumerated with its error-body shape, the59`devrites-doubt` verdict is accept (on reject: revise the contract and re-doubt under60[the canonical retry contract](../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve)61with caller repair and human-risk gates), and the62contract + rationale are recorded in `decisions.md`. A contract that pins only the63happy-path shape is not done.6465## Enables the split66A clear contract lets `/rite-plan split` proceed: the backend slice can land against the67contract with a stub consumer; the frontend slice can build against a mock or the real68contract. Neither side blocks on the other.