---
name: loom-api-and-interface-design
description: "Use when a shared interface needs consumer, compatibility, error, permission, or migration design before implementation, including REST, GraphQL, CLI, event, module, component, file-format, worker, or cross-system contracts."
disable-model-invocation: true
---

# loom-api-and-interface-design

API and interface design is a spec-first playbook for shared contracts.

It defines the contract before implementation, checks compatibility and error
semantics, and routes execution through tickets, evidence, and audit.

If consumers, data shape, compatibility promise, permission boundary, or domain
model are unclear, stay in design shaping before implementation.

## Loom Routing

Common routes use these Loom skills for durable records or follow-up workflow:
`loom-specs`, `loom-research`, `loom-tickets`, `loom-ralph`, `loom-evidence`,
`loom-audit`, `loom-constitution`, and `loom-knowledge`.

Ensure the `using-loom` skill is loaded before applying this workflow.

When routing to any named Loom skill, follow that skill's procedure and guidance
completely. This playbook adds workflow pressure; it does not shorten the target
skill's requirements.

## Use This Playbook When

Use this playbook when designing or changing:

- REST, GraphQL, RPC, event, webhook, or CLI interfaces
- module boundaries or exported functions
- component props or design-system contracts
- data shapes, file formats, records, or worker handoffs
- frontend/backend contracts
- public behavior that consumers may depend on

## Route

Use this route:

```text
consumer -> contract -> compatibility -> implement -> evidence -> audit
```

## Consumer

Identify the consumers:

- users, callers, clients, components, services, workers, agents, or future records
- existing consumers and their current assumptions
- domain model and state relationships the interface should expose or hide
- compatibility expectations
- unsupported consumers and non-goals

Inspect current code, docs, specs, tests, and usage before changing an interface.

## Contract

Write or update a `loom-specs` record when the interface is durable.

Cover:

- inputs and validation boundary
- outputs and generated fields
- side effects
- idempotency
- ordering and pagination
- error semantics
- permission and authentication behavior
- compatibility and deprecation expectations
- observability or event emission
- examples and non-examples
- `REQ-*` and `SCN-*` IDs for downstream tickets and audit

## Compatibility

Prefer additive changes when existing consumers depend on the interface.

Check:

- field removal or type changes
- renamed enum values
- changed nullability
- changed ordering, pagination, or default limits
- error code and status changes
- timing or retry semantics
- undocumented behavior known to be used

Route policy or compatibility precedent to `loom-constitution` when it should guide
future interface changes.

## Implement

Use `loom-tickets` and `loom-ralph` for scoped implementation.

Implementation guidance:

- validate untrusted input at system boundaries
- keep internal contracts typed and simple
- separate input and output types when generated fields or sanitized output matter
- use consistent error shape across related endpoints
- document public behavior in the spec or source docs that consumers actually use
- add tests at the contract boundary

## Evidence And Audit

Evidence should show the interface contract works:

- contract tests
- request/response examples
- schema validation output
- generated docs
- migration or compatibility checks
- consumer integration checks

Use audit for public or high-risk interface changes, especially compatibility,
auth, permission, security, migration, or data-shape changes.

## Done Means

The interface pass is done when:

- the contract is captured in specs or a scoped ticket
- consumers and compatibility risks are named
- implementation tests or observations support the scenarios
- docs or examples match actual behavior
- breaking changes have migration or deprecation follow-up
- audit or review is complete for high-risk surfaces
