From jerry
Generates OpenAPI 3.1 specs from use case interaction sequences with traceability to source steps and schema validation. For API contract design from realized use cases.
npx claudepluginhub geekatron/jerry --plugin jerryThis skill is limited to using the following tools:
> **Version:** 1.0.0 | **Framework:** Jerry Framework | **Constitutional compliance:** P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception)
agents/cd-generator.governance.yamlagents/cd-generator.mdagents/cd-validator.governance.yamlagents/cd-validator.mdcomposition/cd-generator.agent.yamlcomposition/cd-generator.prompt.mdcomposition/cd-validator.agent.yamlcomposition/cd-validator.prompt.mdcontracts/CD_SKILL_CONTRACT.yamlrules/uc-to-contract-rules.mdsamples/sample-contract.openapi.yamltemplates/asyncapi-template.yamltemplates/cloudevents-template.yamltemplates/json-schema-template.jsontemplates/openapi-template.yamltests/BEHAVIOR_TESTS.mdCreates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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
| Section | Purpose |
|---|---|
| Document Audience | Who reads which sections |
| Purpose | What this skill does and key capabilities |
| When to Use | Activation conditions and anti-patterns |
| Available Agents | Agent routing table with decision signals |
| P-003 Agent Topology | ASCII hierarchy diagram -- multi-agent topology |
| Invoking an Agent | Three invocation modes |
| UC-to-Contract Algorithm Reference | Domain methodology summary |
| Input Requirements | Use case artifact prerequisites |
| Output Artifacts | OpenAPI contract, mapping document, validation report, PROTOTYPE review checklist |
| Integration Points | Cross-skill connections |
| Routing Entry (Priority 15) | Trigger map entry for mandatory-skill-usage.md |
| Constitutional Compliance | Principle-to-agent mapping |
| Quick Reference | Common workflows and agent selection |
| References | File paths and external citations |
| Level | Audience | Sections |
|---|---|---|
| L0 | Stakeholders, product managers | Purpose, When to Use, Quick Reference |
| L1 | Developers, API designers using the skill | Available Agents, Invoking an Agent, UC-to-Contract Algorithm Reference, Input Requirements, Output Artifacts |
| L2 | Framework maintainers, reviewers | P-003 Agent Topology, Integration Points, Constitutional Compliance, References |
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:
$.interactions block maps to exactly one API operation or internal operation documentation entry (no invented operations)request_description fields, grounded in RFC 9110 (HTTP Semantics, Section 9), with High/Medium/Low confidence annotationspreconditions (request body) and postconditions (response body) of each interactionoutcome = failure to 4xx/5xx HTTP status codes using semantic pattern analysiscomponents/schemas descriptions per IC-05x-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 stepx-prototype: true in the info section until human review validates semantic correctness (non-negotiable safety gate per RULE-TR-02)Activate this skill when:
realization_level = INTERACTION_DEFINEDNEVER invoke this skill when:
/contract-design agents do not implement Cockburn's writing methodology; they consume use case output, not produce it; use /use-case instead./contract-design produces OpenAPI contracts, not Gherkin Feature files; use /test-spec instead./contract-design requires the structured interactions block as input; writing OpenAPI from free-form requirements is a manual authoring task, not a transformation./adversary for quality scoring and adversarial critique.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.| 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.
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-schema-template.json
| Writes: OpenAPI contract (.openapi.yaml)
| Mapping document (-mapping.md)
|
+-- cd-validator (T2 worker) -- via Task tool
Reads: OpenAPI contract (.openapi.yaml) -- produced by cd-generator
UC artifact (.md) -- same source artifact
Mapping document (-mapping.md)
Writes: Validation report (-validation.md)
Workers do NOT invoke each other.
cd-generator output (OpenAPI + mapping) is consumed by cd-validator via filesystem.
Cross-agent data flow is mediated by shared artifact files on disk (P-003 compliant).
Generate an OpenAPI contract from the use case at
projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
Validate the OpenAPI contract at
projects/PROJ-021/contracts/UC-AUTH-001-validate-credentials.openapi.yaml
against the source use case.
Use cd-generator to transform UC-AUTH-001 from
projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
into an OpenAPI 3.1 contract at
projects/PROJ-021/contracts/UC-AUTH-001-validate-credentials.openapi.yaml
Use cd-validator to validate
projects/PROJ-021/contracts/UC-AUTH-001-validate-credentials.openapi.yaml
against projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
# cd-generator invocation via composition file
from: skills/contract-design/composition/cd-generator.agent.yaml
session_context:
artifact_path: "projects/${JERRY_PROJECT}/use-cases/UC-{DOMAIN}-{NNN}-{slug}.md"
output_path: "projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}.openapi.yaml"
success_criteria:
- "At least 1 operation per consumer interaction"
- "x-prototype: true in info section"
- "Mapping document with full traceability annotations"
The UC-to-contract transformation algorithm encodes a novel 9-step mapping procedure. The full algorithm is defined in skills/contract-design/rules/uc-to-contract-rules.md. Key mappings summarized here for reference:
| UC Artifact Field | OpenAPI Element | Rule |
|---|---|---|
$.title | info.title | RULE-RI-01 |
$.primary_actor | info.x-primary-actor (API consumer role) | RULE-AR-01 |
Interaction where actor_role = consumer | External path + operation | RULE-OM-01 |
Interaction where actor_role = provider | x-internal-operations entry | RULE-OM-02 |
request_description | Operation summary + HTTP method inference | RULE-HM-01 through RULE-HM-05 |
preconditions | Request body schema properties | RULE-SD-01 |
postconditions | Response body schema properties | RULE-SD-02 |
Extension with outcome = failure | 4xx/5xx error response | RULE-ER-01 |
supporting_actors | components/schemas descriptions (IC-05) | RULE-AR-03 |
source_step + source_flow | x-source-interaction, x-source-step, x-source-flow | RULE-TR-01 |
| (always) | info.x-prototype: true | RULE-TR-02 |
| Request Description Pattern | Inferred Method | Confidence |
|---|---|---|
| read, query, get, fetch, retrieve, look up, search, list, find | GET | High |
| create, add, submit, register, initiate, start, send, post | POST | High |
| update, modify, change, edit, set, replace | PUT or PATCH | Medium |
| delete, remove, cancel, revoke, deactivate, terminate | DELETE | High |
| Ambiguous (no pattern match) | POST (default) + WARN | Low |
Low and Medium confidence operations carry x-method-inference: {confidence} annotation and are flagged by cd-validator for human review.
All generated contracts carry x-prototype: true in the info section. This label is mandatory because the UC-to-contract transformation algorithm is novel (no prior art -- G-01) and all generated contracts require human review before production use. cd-validator Step 7 treats absence of this label as a mandatory FAIL with no override permitted.
| Requirement | Constraint | Consequence of Violation |
|---|---|---|
| Artifact exists at specified path | File must be readable | REJECT with path error |
$.work_type = USE_CASE | Discriminator field must match | REJECT |
$.realization_level = INTERACTION_DEFINED | Must not be OUTLINED or STORY_DEFINED | REJECT with actionable message directing to /use-case |
$.interactions non-empty array | At least 1 entry required | REJECT with message: "Use /use-case (uc-slicer Activity 5) to identify system boundaries first" |
| Each interaction has all 7 required fields | id, source_step, source_flow, actor_role, system_role, request_description, response_description | REJECT for missing field |
source_step resolves to a flow step | Cross-reference validation | REJECT for broken reference |
$.supporting_actors readable | Needed for IC-05 | WARN (proceed without IC-05 cross-referencing) |
| Requirement | Constraint | Consequence of Violation |
|---|---|---|
| Contract file exists at specified path | File must be readable | REJECT |
| Contract is valid YAML | Must parse without errors | REJECT |
openapi field is "3.1.x" | Must be OpenAPI 3.1 | Step 1 FAIL |
| Source UC artifact exists | Required for traceability | REJECT |
$.interactions in UC artifact | Required for traceability check | REJECT |
Primary output -- OpenAPI contract (.openapi.yaml):
Location: projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}.openapi.yaml
Contents: OpenAPI 3.1 YAML with paths, operations, schemas, error responses,
traceability annotations, x-internal-operations, and x-prototype: true
Secondary output -- Mapping document (-mapping.md):
Location: projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}-mapping.md
Contents: Traceability table mapping each OpenAPI operation to its source
interaction ID, step number, flow name, and HTTP method confidence.
Includes PROTOTYPE status notice.
Validation report (-validation.md):
Location: projects/${JERRY_PROJECT}/contracts/UC-{DOMAIN}-{NNN}-{slug}-validation.md
Contents: 9-step per-check PASS/FAIL verdicts, traceability coverage as N/M = P%,
traceability matrix, and list of gaps with recommended remediation.
The PROTOTYPE label (x-prototype: true) remains on all contracts until:
cd-validator produces a PASS verdict on all 9 checksx-prototype: true labelNeither cd-generator nor cd-validator removes the PROTOTYPE label. That action is a human decision (P-020 user authority).
When cd-validator produces a PASS verdict, a human reviewer MUST complete this checklist before removing the x-prototype: true label. This checklist constitutes the formal sign-off ceremony. Record completion in the validation report alongside the cd-validator PASS verdict.
Reviewer checklist (all items required for label removal):
| # | Check | Reviewer Action |
|---|---|---|
| 1 | cd-validator PASS confirmed | Verify -validation.md shows overall PASS with all 9 steps individually PASS |
| 2 | HTTP method semantics correct | For every operation: manually verify the inferred HTTP method matches the use case intent -- especially any operations with x-method-inference: medium or x-method-inference: low |
| 3 | Resource naming is correct | Path names (/resources/{id}) match the domain entities and naming conventions of the target system |
| 4 | Request/response schemas are complete | Required fields are present; field names match the implementation's data model; no spurious required fields |
| 5 | Error responses are correct | Each 4xx/5xx response maps to an actual failure condition; status codes follow RFC 9110 semantics for the operation |
| 6 | No invented operations | Every operation traces to a specific $.interactions entry in the source UC artifact via x-source-interaction annotation |
| 7 | Supporting actors are correctly referenced | components/schemas descriptions and x-internal-operations entries accurately represent external system dependencies |
| 8 | Contract is suitable for downstream consumption | The contract can serve as a binding specification for implementation; no ambiguous operations remain |
Sign-off format (append to -validation.md):
## PROTOTYPE Review Sign-Off
**Reviewer:** {name}
**Date:** {YYYY-MM-DD}
**Checklist:** All 8 items verified
**Decision:** APPROVED for label removal
**Action taken:** x-prototype: true removed from info section
**Notes:** {any caveats or conditional approvals}
Audit trail: The sign-off record in -validation.md is the audit trail. Do not remove the PROTOTYPE label without appending this section. The sign-off is permanent -- do not delete it after label removal.
| Integration | Direction | Mechanism | Pre-Condition |
|---|---|---|---|
/use-case to /contract-design | cd-generator reads UC artifact produced by uc-slicer Activity 5 | Shared artifact file validated against docs/schemas/use-case-realization-v1.schema.json | $.realization_level = INTERACTION_DEFINED, $.interactions non-empty |
/contract-design output to implementers | OpenAPI specs serve as API implementation contracts | Human- and machine-readable .openapi.yaml files | Contract validated by cd-validator |
/contract-design parallel to /test-spec | Both are independent consumers of /use-case output | File-mediated -- both read the same UC artifact; neither depends on the other | UC artifact at INTERACTION_DEFINED (for this skill) or ESSENTIAL_OUTLINE+ (for /test-spec) |
/contract-design to code generators | OpenAPI spec feeds OpenAPI Generator or similar tools | Standard OpenAPI 3.1 format | Contract passes cd-validator checks; PROTOTYPE label removed by human reviewer |
For insertion into
mandatory-skill-usage.mdTrigger Map (per agent-routing-standards.md Phase 1 5-column format). Priority 15 places/contract-designbelow/test-spec(14) and/use-case(13), reflecting the pipeline dependency order.
| Column | Value |
|---|---|
| Detected Keywords | contract design, contract-design, API contract, OpenAPI, API spec, API specification, generate contract, contract from use case, API schema, endpoint design, operation mapping, request response schema, API generation, REST contract, swagger, use case to API, interaction to contract |
| Negative Keywords | requirements specification, V&V, technical review, use case model, actor goal, write use case, BDD, Gherkin, scenario, test spec, feature file, adversarial, tournament, transcript, penetration, exploit, code review, pricing model, cloud pricing, documentation, tutorial |
| Priority | 15 |
| Compound Triggers | "API contract" OR "contract design" OR "OpenAPI" OR "generate contract" OR "contract from use case" OR "API specification" OR "use case to API" (phrase match) |
| Skill | /contract-design |
Disambiguation notes:
/diataxis for API docs, /red-team for API security testing). Compound triggers require qualification./test-spec via negative keyword suppression.| Principle | Agent | Application |
|---|---|---|
| P-003 (No recursive subagents) | Both agents | Neither cd-generator nor cd-validator has the Task tool. No agent-to-agent invocation. Cross-agent communication via filesystem only. |
| P-020 (User authority) | Both agents | User decides contract scope, operation granularity, resource naming. PROTOTYPE label removal is a user/reviewer decision. Neither agent removes or overrides x-prototype. |
| P-022 (No deception) | cd-generator | G-01 (no prior art) acknowledged. PROTOTYPE label mandatory. Confidence annotations (high/medium/low) on HTTP method inference. REJECT messages are specific and actionable. |
| P-022 (No deception) | cd-validator | FAIL verdicts cite specific evidence. Traceability gaps list specific interaction IDs (not generic descriptions). Coverage expressed as N/M = P%, not just percentage. |
| P-001 (Truth/Accuracy) | Both agents | Every mapping traces to a specific UC schema field or RFC 9110 clause. No invented API operations. |
| P-002 (File Persistence) | Both agents | All outputs persisted to files; no inline-only responses. |
Generate OpenAPI from use case (single step):
Use cd-generator on the UC artifact at INTERACTION_DEFINED level.
Output: .openapi.yaml + -mapping.md
Generate and validate:
1. Use cd-generator to produce .openapi.yaml and -mapping.md
2. Use cd-validator to produce -validation.md
3. Review validation report; remediate any FAIL verdicts
4. Human review validates semantic correctness; remove x-prototype: true
Check if UC is ready for contract generation:
Verify: $.realization_level = INTERACTION_DEFINED
Verify: $.interactions is non-empty
Verify: Each interaction has id, source_step, source_flow, actor_role,
system_role, request_description, response_description
If missing interactions: run /use-case uc-slicer Activity 5 first
| User Intent | Agent | Rationale |
|---|---|---|
| "Generate an API contract from my use case" | cd-generator | Transformation from UC to OpenAPI |
| "Create OpenAPI spec from interactions block" | cd-generator | Same transformation task |
| "Validate the contract I generated" | cd-validator | 9-step validation protocol |
| "Check traceability coverage of the contract" | cd-validator | Step 2 path completeness check |
| "Generate and validate in one workflow" | cd-generator then cd-validator | Generation must precede validation |
| File | Purpose |
|---|---|
skills/contract-design/agents/cd-generator.md | cd-generator agent definition (F-02) |
skills/contract-design/agents/cd-generator.governance.yaml | cd-generator governance metadata (F-03) |
skills/contract-design/agents/cd-validator.md | cd-validator agent definition (F-04) |
skills/contract-design/agents/cd-validator.governance.yaml | cd-validator governance metadata (F-05) |
skills/contract-design/composition/cd-generator.agent.yaml | Task tool invocation config for cd-generator (F-06) |
skills/contract-design/composition/cd-generator.prompt.md | System prompt for Task tool invocation (F-07) |
skills/contract-design/composition/cd-validator.agent.yaml | Task tool invocation config for cd-validator (F-08) |
skills/contract-design/composition/cd-validator.prompt.md | System prompt for Task tool invocation (F-09) |
skills/contract-design/templates/openapi-template.yaml | OpenAPI 3.1 output template (F-10) |
skills/contract-design/templates/asyncapi-template.yaml | AsyncAPI 3.0 scaffolding -- deferred (F-11) |
skills/contract-design/templates/cloudevents-template.yaml | CloudEvents 1.0 scaffolding -- deferred (F-12) |
skills/contract-design/templates/json-schema-template.json | JSON Schema Draft 2020-12 template (F-13) |
skills/contract-design/rules/uc-to-contract-rules.md | Novel UC-to-contract transformation algorithm (F-14, 24 rules) |
skills/contract-design/contracts/CD_SKILL_CONTRACT.yaml | Skill interface contract (F-15) |
skills/contract-design/tests/BEHAVIOR_TESTS.md | BDD behavior tests, 10 scenarios (F-16) |
skills/contract-design/samples/sample-contract.openapi.yaml | UC-LIB-001 "Borrow a Book" sample output (F-17) |
docs/schemas/use-case-realization-v1.schema.json | Input validation schema |
docs/schemas/agent-governance-v1.schema.json | H-34 governance YAML validation schema |
projects/PROJ-021-use-case/orchestration/use-case-skills-20260308-001/implementation/step-11-contract-design-architecture.md | Architecture SSOT (v1.1.0, 0.956 PASS) |
| OpenAPI Specification 3.1.0 | https://spec.openapis.org/oas/v3.1.0 |
| RFC 9110 (2022) HTTP Semantics | https://www.rfc-editor.org/rfc/rfc9110#section-9 -- Basis for HTTP method inference |
| Jacobson, I. et al. (2011) | Use-Case 2.0: The Guide to Succeeding with Use Cases |