contract-design

What this skill does

> **Version:** 1.0.0 | **Framework:** Jerry Framework | **Constitutional compliance:** P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception)
> **Status:** ACTIVE | **Author:** eng-backend | **Date:** 2026-03-09

---

## Document Sections

| Section | Purpose |
|---------|---------|
| [Document Audience](#document-audience) | Who reads which sections |
| [Purpose](#purpose) | What this skill does and key capabilities |
| [When to Use](#when-to-use) | Activation conditions and anti-patterns |
| [Available Agents](#available-agents) | Agent routing table with decision signals |
| [P-003 Agent Topology](#p-003-agent-topology) | ASCII hierarchy diagram -- multi-agent topology |
| [Invoking an Agent](#invoking-an-agent) | Three invocation modes |
| [UC-to-Contract Algorithm Reference](#uc-to-contract-algorithm-reference) | Domain methodology summary |
| [Input Requirements](#input-requirements) | Use case artifact prerequisites |
| [Output Artifacts](#output-artifacts) | OpenAPI contract, mapping document, validation report, PROTOTYPE review checklist |
| [Integration Points](#integration-points) | Cross-skill connections |
| [Routing Entry (Priority 15)](#routing-entry-priority-15) | Trigger map entry for mandatory-skill-usage.md |
| [Constitutional Compliance](#constitutional-compliance) | Principle-to-agent mapping |
| [Quick Reference](#quick-reference) | Common workflows and agent selection |
| [References](#references) | File paths and external citations |

---

## Document Audience

| Level | Audience | Sections |
|-------|----------|---------|
| L0 | Stakeholders, product managers | [Purpose](#purpose), [When to Use](#when-to-use), [Quick Reference](#quick-reference) |
| L1 | Developers, API designers using the skill | [Available Agents](#available-agents), [Invoking an Agent](#invoking-an-agent), [UC-to-Contract Algorithm Reference](#uc-to-contract-algorithm-reference), [Input Requirements](#input-requirements), [Output Artifacts](#output-artifacts) |
| L2 | Framework maintainers, reviewers | [P-003 Agent Topology](#p-003-agent-topology), [Integration Points](#integration-points), [Constitutional Compliance](#constitutional-compliance), [References](#references) |

---

## Purpose

The `/contract-design` skill transforms structured use case realization artifacts produced by `/use-case` into OpenAPI 3.1 API contract specifications using a novel UC-to-contract transformation algorithm. It closes the gap between behavioral use case specifications and machine-readable API contracts that downstream code generators and implementers can consume.

**Key Capabilities:**

- Novel UC-to-contract transformation: every interaction step in the `$.interactions` block maps to exactly one API operation or internal operation documentation entry (no invented operations)
- HTTP method inference: derives GET/POST/PUT/PATCH/DELETE from the semantic content of `request_description` fields, grounded in RFC 9110 (HTTP Semantics, Section 9), with High/Medium/Low confidence annotations
- Request/response schema derivation: extracts schema properties directly from `preconditions` (request body) and `postconditions` (response body) of each interaction
- Error response mapping: maps use case extension conditions with `outcome = failure` to 4xx/5xx HTTP status codes using semantic pattern analysis
- Actor role mapping: maps primary actor to API consumer role, provider interactions to internal operations documentation, and supporting actors to `components/schemas` descriptions per IC-05
- Full traceability: every operation carries `x-source-interaction`, `x-source-step`, `x-source-flow` annotations; the separate mapping document provides the complete traceability chain from OpenAPI operation back to use case step
- PROTOTYPE labeling: all generated contracts carry `x-prototype: true` in the `info` section until human review validates semantic correctness (non-negotiable safety gate per RULE-TR-02)
- Contract validation: 9-step protocol verifying structural compliance, traceability completeness (100% of consumer interactions mapped), and PROTOTYPE label presence

---

## When to Use

**Activate this skill when:**

- Generating OpenAPI 3.1 specifications from use case realization artifacts at `realization_level = INTERACTION_DEFINED`
- Transforming use case interaction sequences into API operations, paths, and schemas
- Creating request/response schemas from interaction preconditions and postconditions
- Mapping use case actors to API consumer/provider roles
- Deriving error responses from use case extension conditions
- Validating that a generated contract traces to all source interaction steps
- Checking whether a generated OpenAPI contract meets structural compliance and traceability standards

**NEVER invoke this skill when:**

- Task is writing or editing use case artifacts -- Consequence: `/contract-design` agents do not implement Cockburn's writing methodology; they consume use case output, not produce it; use `/use-case` instead.
- Task is generating BDD test specifications from use case artifacts -- Consequence: `/contract-design` produces OpenAPI contracts, not Gherkin Feature files; use `/test-spec` instead.
- Task is writing OpenAPI specifications from scratch (not from use case artifacts) -- Consequence: `/contract-design` requires the structured `interactions` block as input; writing OpenAPI from free-form requirements is a manual authoring task, not a transformation.
- Task is adversarial quality review of deliverables -- Consequence: use `/adversary` for quality scoring and adversarial critique.
- Use case artifact does not have an `interactions` block -- Consequence: the UC-to-contract transformation requires `$.interactions[*]` produced by `uc-slicer` Activity 5; use `/use-case` to realize the use case first.
- Task is generating AsyncAPI or CloudEvents specifications -- Consequence: these contract types are deferred (DI-07, ASM-005, G-02); templates exist as scaffolding but agent generation logic is not implemented in v1.0.0.

---

## Available Agents

| Agent | Role | Model | Cognitive Mode | Tool Tier | Output Location | Decision Signal |
|-------|------|-------|----------------|-----------|-----------------|-----------------|
| `cd-generator` | Transforms UC interaction sequences into OpenAPI 3.1 contract specifications using the UC-to-contract transformation algorithm | opus | convergent | T2 | `projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}.openapi.yaml` | "generate", "create contract", "OpenAPI from use case", "map interactions to operations", "derive API" |
| `cd-validator` | Validates generated contracts against OpenAPI 3.1 structural standards and verifies traceability from every operation to source interaction | sonnet | systematic | T2 | `projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}-validation.md` | "validate contract", "check OpenAPI", "verify traceability", "contract compliance", "schema validation" |

**Default routing:** When intent is ambiguous between generation and validation, route to `cd-generator` first. Generation must precede validation. When the user says "generate and validate the contract," invoke `cd-generator` first, then `cd-validator` on the output.

---

## P-003 Agent Topology

Both `cd-generator` and `cd-validator` are T2 worker agents. They are invoked independently from MAIN CONTEXT. They do NOT invoke each other. The output of `cd-generator` (OpenAPI YAML and mapping document on disk) is consumed by `cd-validator` via the filesystem -- not via direct agent-to-agent communication.

```
MAIN CONTEXT (orchestrator)
    |
    +-- cd-generator (T2 worker) -- via Task tool
    |   Reads: UC artifact (.md with YAML frontmatter)
    |          docs/schemas/use-case-realization-v1.schema.json
    |          skills/contract-design/rules/uc-to-contract-rules.md
    |          skills/contract-design/templates/openapi-template.yaml
    |          skills/contract-design/templates/json-