Read-set manifest: devrites-engine context --skills-root .devin/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-73description: Shape stable API, type, module, or frontend/backend contracts before implementation. Use when a slice crosses a boundary; not for internal helpers.4triggers:5 - model6metadata:7 source: https://skillmd.com/skills/viktorsbaikers/devrites-api-interface-78---910<!-- 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"]} -->11> Read-set manifest: `devrites-engine context --skills-root .devin/skills <slug> --skill devrites-api-interface` (no workspace: `--out <path>`) bundles every file named below into one deduplicated read.1213# devrites-api-interface: contract before implementation1415When a slice crosses a boundary (FE/BE, service/service, module/module) or exposes a16public interface, define the contract first so both sides can proceed and the interface17stays stable.1819## Define the contract first20- **Shape:** request/response or function signature; field names, types, optionality,21 units. Follow the project's existing naming and conventions.22- **Status & errors:** success codes, error codes, error body shape, validation23 messages. Errors are part of the contract, not an afterthought.24- **Semantics:** idempotency, pagination, ordering, nullability, side effects.25- **Versioning/compat:** is this new or a change to an existing contract? A breaking26 change to an existing consumer is a user decision (and a drift event if unplanned).2728## Stability principles29- Design for the caller. The interface should make the common case easy and the wrong30 call hard.31- **Prefer addition over modification.** A new field is additive and optional; changing a32 field's type or removing one is a breaking change. You can add later. You can't un-ship a33 shape consumers already read (observable behavior is the contract: [`deprecation.md`](../devrites-lib/reference/standards/deprecation.md) Hyrum's law).34- **One-Version Rule.** Design as if only one version of this interface will ever exist:35 extend the single contract rather than fork a v2 you then maintain in parallel. Forking36 multiplies the surface and breeds diamond-dependency conflicts; bump a version only when an37 addition genuinely can't stay backward-compatible.38- Match existing endpoints/modules in style: don't introduce a competing convention.39- **Validate at the boundary, and only there** (untrusted → trusted); don't trust40 caller-supplied trust signals (IDs, roles). Validation does *not* belong between two internal41 typed functions, on your own database's data, or in a utility already called by validated code.42 A check inside the trusted core hides the bug in the boundary that should have caught it. A43 third-party API response is external input: always untrusted. (Three-tier boundary:44 [`security.md`](../devrites-lib/reference/standards/security.md); see [`security-review.md`](../rite-review/reference/security-review.md).)4546## Type craft: make the wrong call unrepresentable47- **Brand your ids.** A bare `string`/`number` id is assignable to any other id, so the compiler48 won't stop you passing a `userId` where a `taskId` is due. Give each a nominal brand49 (`type TaskId = string & { readonly __brand: 'TaskId' }`) and the mix-up becomes a type error,50 not a production incident.51- **Model variants as discriminated unions**, each state carrying only its own fields, so an52 impossible combination can't be constructed in the first place.5354## Doubt the contract55Before standing the interface, run `devrites-doubt`.5657## Done when58The contract is complete only when **every** field carries a type + optionality + unit,59**every** success and error status code is enumerated with its error-body shape, the60`devrites-doubt` verdict is accept (on reject: revise the contract and re-doubt under61[the canonical retry contract](../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve)62with caller repair and human-risk gates), and the63contract + rationale are recorded in `decisions.md`. A contract that pins only the64happy-path shape is not done.6566## Enables the split67A clear contract lets `/rite-plan split` proceed: the backend slice can land against the68contract with a stub consumer; the frontend slice can build against a mock or the real69contract. Neither side blocks on the other.