contract-checklist

Files (1)

• SKILL.md

SKILL.md (first lines)

# Contract Checklist

Shared reference for `architect-agent` and `implementer-lead-agent`.

Resolve all applicable questions **before finalizing any API or database contract**. Unanswered questions are silent drift points between phases — document your resolution even when the answer is "not applicable," so downstream agents can verify rather than guess.

---

## 1. Entity Lifecycle

- Does this entity exist independently, or only as a child of a parent?
- Can it be created without a parent reference?
- What happens on parent deletion: cascade delete, orphan (set null), or block?
- Who creates the entity — only through a parent endpoint, or via a dedicated child endpoint?

## 2. Payload Shape for Master-Detail

- Does the UI edit the parent and its children in one form submission, or independently?
  - One form → nested payload (children array inside the parent body) is natural.
  - Independent management → separate child endpoints are correct.
- If a parent update endpoint accepts child mutations in the same payload, what are the semantics: replace-all, or explicit add/update/delete per child?
- Decision depends on the interaction model — resolve before defining the endpoint.

## 3. Ownership and IDOR Risk

- Which field establishes ownership (e.g. `user_id`, `org_id`, `tenant_id`)?
- On write operations: is ownership enforced server-side from the authenticated identity, or trusted from the payload?
- On nested updates: can the payload change a child's owning parent?
  - A PUT on parent A containing a child currently owned by parent B is an IDOR vector — explicit defense required.
- On bulk or indirect updates: are all child records re-verified to belong to the same owner as the parent before mutation?

## 4. Idempotency and Retry Behavior

- Is this endpoint safe to retry (idempotent)?
- If yes, how is idempotency enforced: idempotency-key header, dedup by business key, or upsert semantics?
- What is the response on a duplicate submission: 200 with the original result, 409 Conflict, or 204 No Content?

## 5. Delete Behavior

- Soft delete (flag + timestamp) or hard delete?
- On soft delete: are soft-deleted records excluded from list and get queries by default?
- On hard delete: which FK constraints cascade? Which block deletion?
- Are cascades explicit in migrations, or enforced in application code?

## 6. Aggregate Update Diff

When a payload updates a collection (e.g. children array inside a parent PUT):

- **Existing children**: carry their `id` field.
- **New children**: no `id` (server assigns on creation).
- **Deleted children**: omitted from the array (replace-all semantics) OR included with `_destroy: true` (explicit delete semantics).

Which semantics does this contract use? **Document it explicitly.** If IDs are absent on existing children, the server cannot distinguish an update from a delete + recreate — this must be resolved before implementation begins.

## 7. Pagination, Filter, and Sort

- Maximum page size? Default page size?
- Which fields are filterable? Any requiring a database index to be viable?
- Which fields are sortable? Default sort order and direction?
- Cursor-based or offset-based pagination?

## 8. Versioning

- Is this endpoint versioned (e.g. `/v1/`, `/v2/`)?
- If extending an existing versioned API: does the addition belong to the current version or require a new version?
- What is the deprecation policy for the version being extended?

## 9. Error Response Shape

- What is the exact JSON shape for all error responses?
- Are validation errors per-field (`[{ field, message }]`) or a single aggregate message?
- What is the error-code vocabulary: string codes (e.g. `validation_error`) or numeric?
- Does the response body structure differ between 4xx client errors and 5xx server errors?

From diego81b/kairos-agents-framework, AGPL-3.0.

More from diego81b/kairos-agents-framework