Add AsyncAPI and JSON-RPC contract support

.github/actions/idd-check/action.yml

@@ -90,7 +90,7 @@ runs:
         # Determine which core checks to run
         CHECKS="${{ inputs.checks }}"
         if [ "$CHECKS" = "all" ]; then
-          CHECKS="traceability front-matter capability-scope fixtures models journey-maps"
+          CHECKS="contracts traceability front-matter capability-scope fixtures models journey-maps"
         fi
 
         # Run each core validator individually, capturing JSON per check
@@ -118,6 +118,8 @@ runs:
         echo "openapi_exit=$OPENAPI_EXIT" >> "$GITHUB_OUTPUT"
         echo "openapi_ran=$OPENAPI_RAN" >> "$GITHUB_OUTPUT"
 
+        # AsyncAPI and JSON-RPC contract validation is covered by the core "contracts" validator.
+
         # Run Gherkin lint if config and features exist
         GHERKIN_EXIT=0
         GHERKIN_RAN=false
@@ -163,6 +165,7 @@ runs:
         // ── Pretty names for checks ──
         const LABELS = {
           'traceability': 'Traceability',
+          'contracts': 'Contracts',
           'front-matter': 'Front-Matter',
           'capability-scope': 'Capability Scope',
           'fixtures': 'Fixtures',

.gitignore

@@ -1,6 +1,7 @@
 .env
 .idea
 .DS_Store
+.claude/settings.local.json
 build/
 node_modules/
 tools/node_modules/

README.md

@@ -26,7 +26,7 @@ The result is a framework where AI agents can autonomously implement, verify, an
 ├─────────────────────────────────────────────────────────────┤
 │                     CONTRACT LAYER                           │
 │   Features ◀── Contracts ──▶ Fixtures                        │
-│   (Gherkin)    (OpenAPI)     (test data)                     │
+│   (Gherkin)    (OpenAPI / AsyncAPI / JSON-RPC)               │
 │                                        /behavior-contract    │
 ├──────────────────────────────────────────────────────────────┤
 │                  IMPLEMENTATION LAYER                        │
@@ -66,7 +66,9 @@ IDD breaks this into a traceable chain:
 | Narrative | `specs/stories/onboarding/mobile-signup.md` | Capability: quick mobile account creation |
 | Model | `specs/models/audit/audit.model.yaml` | Concept: Audit entity, states, rules |
 | Contract | `specs/features/onboarding/mobile-signup.feature` | Behavior: Gherkin scenarios |
-| Contract | `specs/contracts/openapi/api.yaml` | API: `POST /accounts`, `POST /audits` |
+| Contract | `specs/contracts/openapi/api.yaml` | HTTP boundary: `POST /accounts`, `POST /audits` |
+| Contract | `specs/contracts/asyncapi/audit-events.yaml` | Event boundary: `publish audits/created` |
+| Contract | `specs/contracts/json-rpc/account-service.yaml` | RPC boundary: `account.getQuickStartPrompt` |
 | Contract | `specs/fixtures/onboarding/mobile-signup.json` | Test data: request/response pairs |
 | Implementation | Backend + Frontend code | Derived from contracts |
 | Validation | `frontend/e2e/journeys/trade-show-signup.spec.ts` | E2E test following the journey |
@@ -94,7 +96,7 @@ node tools/graph-generation/generate-spec-graph.js examples --format mermaid
 
 1. **Intent precedes code.** No implementation without an explicit intent artifact.
 2. **Shared mental models are artifacts, not conversations.** If a concept matters, it has a file.
-3. **Contracts define reality at boundaries.** API contracts are the source of truth, not implementation.
+3. **Contracts define reality at boundaries.** OpenAPI, AsyncAPI, and JSON-RPC contracts are the source of truth, not implementation.
 4. **Assumptions must become executable.** Untested assumptions are technical debt.
 5. **Feedback must be fast, honest, and automated.** Evidence, not confidence theater.
 6. **Human cognition is protected.** Agents handle bookkeeping; humans handle meaning.
@@ -190,7 +192,7 @@ The `idd-workflow` skill should load that overlay before picking backend/fronten
 |-------|---------|------------|
 | **Solution Narrative** | Personas, journeys, stories — the "why" | `/solution-narrative` |
 | **Domain Modeling** | Entities, aggregates, business rules | `/domain-modeling` |
-| **Behavior Contract** | BDD features, OpenAPI contracts, fixtures | `/behavior-contract` |
+| **Behavior Contract** | BDD features, OpenAPI/AsyncAPI/JSON-RPC contracts, fixtures | `/behavior-contract` |
 | **E2E Journey Testing** | Playwright tests from journey maps | `/e2e-journey-testing` |
 | **Certification** | Traceability verification and evidence manifests | `/certification` |
 | **IDD Workflow** | Meta-skill: when to use which skill | `/idd-workflow` |
@@ -227,7 +229,7 @@ docs/idd/                    IDD philosophy and concept library
 skills/                      IDD methodology skills (bundled in package)
 ├── solution-narrative/      Personas, journeys, stories
 ├── domain-modeling/         Entities, aggregates, business rules
-├── behavior-contract/       BDD features, OpenAPI contracts, fixtures
+├── behavior-contract/       BDD features, protocol contracts, fixtures
 ├── e2e-journey-testing/     Playwright journey tests
 ├── certification/           Traceability verification and evidence
 └── idd-workflow/            Meta-skill: when to use which skill
@@ -242,7 +244,8 @@ tools/                       Validators and generators
 ├── validate-front-matter.js Validate required/recommended metadata fields
 ├── validate-traceability.js Validate cross-artifact reference integrity
 ├── validate-capability-scope.js Validate capability scope coverage
-├── validate-fixtures.js     Validate fixtures against OpenAPI request/response schemas
+├── validate-contracts.js    Validate OpenAPI, AsyncAPI, and JSON-RPC contracts
+├── validate-fixtures.js     Validate fixtures against protocol-specific contract schemas
 ├── validate-models.js       Validate model/lifecycle structural rules
 ├── validate-journey-maps.js Validate journey map structural rules
 ├── generate-evidence.js     Scaffold certification evidence manifests
@@ -267,7 +270,7 @@ idd validate traceability front-matter --json
 idd validate fixtures models --strict
 ```
 
-Available validators: `traceability`, `front-matter`, `capability-scope`, `fixtures`, `models`, `journey-maps`, `evidence`.
+Available validators: `contracts`, `traceability`, `front-matter`, `capability-scope`, `fixtures`, `models`, `journey-maps`, `evidence`.
 
 Common CLI options:
 - `--files <paths...>` limit checks to specific files

bin/idd.js

@@ -38,6 +38,7 @@ if (commands[subcommand]) {
 
 function cmdValidate(argv) {
   const VALIDATORS = {
+    contracts: 'validate-contracts.js',
     traceability: 'validate-traceability.js',
     'front-matter': 'validate-front-matter.js',
     'capability-scope': 'validate-capability-scope.js',
@@ -246,6 +247,8 @@ function cmdInit(argv) {
     'specs/stories',
     'specs/features',
     'specs/contracts/openapi',
+    'specs/contracts/asyncapi',
+    'specs/contracts/json-rpc',
     'specs/fixtures',
     'specs/models',
     'specs/capabilities',

docs/idd/concepts.md

@@ -33,12 +33,12 @@ knowledge. If a concept matters, it has a file.
 
 ## C3 — Contracts Define Reality at Boundaries
 
-API contracts (OpenAPI, Gherkin features) are the authoritative source of truth
+Boundary contracts (OpenAPI, AsyncAPI, JSON-RPC, plus Gherkin features) are the authoritative source of truth
 for how systems interact. Implementation must conform to the contract, not the
 other way around.
 
 **Manifesto principle**: 3
-**Artifacts involved**: features, contracts/openapi, fixtures
+**Artifacts involved**: features, contracts/*, fixtures
 
 ---
 
@@ -95,7 +95,7 @@ The capability groups artifacts into a certifiable scope. No link in the chain
 is optional. If an artifact exists, its provenance is declared.
 
 **Enforced via**: YAML front-matter (preferred), comment headers,
-`x-story`/`x-feature`/`x-journey` OpenAPI extensions, `_meta` blocks in
+`x-story`/`x-feature`/`x-journey` contract extensions, `_meta` blocks in
 fixtures, test file headers. See `docs/idd/front-matter-spec.md` for the
 uniform front-matter schema.
 

docs/idd/front-matter-spec.md

@@ -7,7 +7,7 @@ IDD artifacts use five different reference conventions parsed five different way
 | Artifact | Reference mechanism |
 |----------|-------------------|
 | Feature files | `# Story:` / `# Journey:` Gherkin comments |
-| OpenAPI operations | `x-story` / `x-feature` / `x-journey` extensions |
+| Contract operations | `x-story` / `x-feature` / `x-journey` extensions |
 | Fixtures | `_meta.story` / `_meta.feature` JSON blocks |
 | Journey maps | `sources.journey` / `sources.stories` YAML fields |
 | Stories/journeys | `Journey:` / `Persona:` embedded in markdown prose |
@@ -199,7 +199,7 @@ sources:
 
 ## Relationship to capability artifacts
 
-Capabilities are the highest-level grouping artifact. They define the scope of what gets certified. The capability's `scope` block is the authoritative enumeration of which artifacts belong together — it replaces the inline `intent` block that previously lived only in `certification/{capability}/evidence.yaml`.
+Capabilities are the highest-level grouping artifact. They define the scope of what gets certified. The capability's `scope` block is the authoritative enumeration of which artifacts belong together, including OpenAPI, AsyncAPI, and JSON-RPC contracts. It replaces the inline `intent` block that previously lived only in `certification/{capability}/evidence.yaml`.
 
 See `docs/idd/certification-guide.md` for how capabilities relate to certification.
 

docs/idd/project-template.md

@@ -7,7 +7,7 @@
 3. `specs/stories/`
 4. `specs/models/`
 5. `specs/features/` (BDD)
-6. `specs/contracts/openapi/`
+6. `specs/contracts/openapi/`, `specs/contracts/asyncapi/`, and/or `specs/contracts/json-rpc/`
 7. `specs/fixtures/`
 8. `specs/journey-maps/`
 9. `specs/capabilities/` (created as a stub after narrative, finalized after models/contracts/features exist)
@@ -18,7 +18,7 @@
 1. Capture intent in persona + journey + story artifacts.
 2. Create a capability stub with personas, journeys, and stories.
 3. Model domain concepts, rules, and lifecycles.
-4. Convert story acceptance criteria into BDD features + API contracts, then finalize the capability scope with models, features, and contracts.
+4. Convert story acceptance criteria into BDD features + boundary contracts, then finalize the capability scope with models, features, and contracts.
 5. Implement code from contracts and feature expectations.
 6. Produce executable verification: unit, contract, e2e, regression.
 7. Publish evidence under `certification/` before merge (`/certification`).

package.json

@@ -26,6 +26,9 @@
   "bin": {
     "idd": "./bin/idd.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "bin/",
     "tools/lib/",

skills/behavior-contract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: behavior-contract
-description: "Convert solution narratives into BDD feature files and OpenAPI contracts. Use when translating user stories into testable specifications and API definitions. Consumes output from solution-narrative skill, produces artifacts consumed by architecture skills."
+description: "Convert solution narratives into BDD feature files and protocol contracts. Use when translating user stories into testable specifications and API/event/RPC definitions. Consumes output from solution-narrative skill, produces artifacts consumed by architecture skills."
 argument-hint: "[feature-area or story]"
 allowed-tools:
   - Read
@@ -20,7 +20,7 @@ Transform narrative artifacts into executable specifications and API contracts.
 1. Review journey and story from specs/journeys/ and specs/stories/.
 2. Write Gherkin feature files capturing behavior.
 3. Identify API touchpoints from journey system responses.
-4. Define or update OpenAPI contract.
+4. Define or update the appropriate OpenAPI, AsyncAPI, or JSON-RPC contract.
 5. Create fixtures for test data.
 6. Finalize the capability scope by adding the relevant models, features, and contracts.
 7. Ensure traceability: story → feature → contract → implementation.
@@ -35,12 +35,12 @@ specs/
 │   └── {feature-area}/
 │       └── {feature-name}.feature
 ├── contracts/
-│   └── openapi/
-│       ├── api.yaml              ← main spec
-│       └── components/
-│           ├── schemas.yaml
-│           ├── parameters.yaml
-│           └── responses.yaml
+│   ├── openapi/
+│   │   └── api.yaml              ← HTTP boundary
+│   ├── asyncapi/
+│   │   └── events.yaml           ← event boundary
+│   └── json-rpc/
+│       └── service.yaml          ← RPC boundary
 └── fixtures/
     └── {feature-area}/
         └── {fixture-name}.json
@@ -74,7 +74,7 @@ Before defining contract schemas, check specs/models/:
 ## Traceability Requirements
 
 - Feature files must reference the source story, journey, and contract at the top of the file.
-- OpenAPI operations must include `x-story`, `x-feature`, and `x-journey`.
+- Contract operations must include `x-story`, `x-feature`, and `x-journey`.
 - Fixtures must include a `_meta` block with the story and scenario they support.
 
 ## Feature File Template

specs/README.md

@@ -20,7 +20,7 @@ The example chain models a trade-show workflow:
 - `personas/` → who the system serves
 - `journeys/` → end-to-end user experience
 - `stories/` → scoped user capabilities
-- `features/` + `contracts/` + `fixtures/` → executable behavior
+- `features/` + `contracts/` + `fixtures/` → executable behavior across HTTP, event, and RPC boundaries
 - `models/` → domain concepts and rules
 - `journey-maps/` → E2E validation spine
 - `capabilities/` → certification scope boundary
@@ -30,9 +30,9 @@ The example chain models a trade-show workflow:
 Run checks against this directory directly:
 
 ```bash
-node tools/check-front-matter.js examples/
-node tools/check-traceability.js examples/
-node tools/check-capability-scope.js examples/
+node tools/check-front-matter.js specs/
+node tools/check-traceability.js specs/
+node tools/check-capability-scope.js specs/
 ```
 
 Real adopters should place equivalent artifacts under `specs/` in their own repositories.

specs/capabilities/trade-show-signup.capability.yaml

@@ -11,6 +11,7 @@ scope:
     - specs/stories/quick-start-audit.story.md
   features:
     - specs/features/mobile-signup.feature
+    - specs/features/quick-start-audit.feature
   models:
     - specs/models/account.model.yaml
     - specs/models/account.lifecycle.yaml
@@ -19,7 +20,11 @@ scope:
     - specs/models/shared-value-objects.model.yaml
   contracts:
     - specs/contracts/openapi/api.yaml
+    - specs/contracts/asyncapi/audit-events.yaml
+    - specs/contracts/json-rpc/account-service.yaml
   fixtures:
     - specs/fixtures/mobile-signup.fixture.yaml
+    - specs/fixtures/quick-start-audit-rpc.fixture.yaml
+    - specs/fixtures/quick-start-audit-event.fixture.yaml
   journey_maps:
     - specs/journey-maps/trade-show-signup.journey-map.yaml

specs/contracts/asyncapi/audit-events.yaml

@@ -0,0 +1,28 @@
+asyncapi: 2.6.0
+info:
+  title: Trade Show Audit Events
+  version: 1.0.0
+  description: Event contract for quick-start audit orchestration.
+channels:
+  audits/created:
+    publish:
+      operationId: publishAuditCreated
+      summary: Publish a domain event when the first audit is created
+      x-story: specs/stories/quick-start-audit.story.md
+      x-feature: specs/features/quick-start-audit.feature
+      x-journey: specs/journeys/trade-show-signup.journey.md
+      message:
+        name: AuditCreated
+        payload:
+          type: object
+          required: [auditId, accountId, templateId, createdAt]
+          properties:
+            auditId:
+              type: string
+            accountId:
+              type: string
+            templateId:
+              type: string
+            createdAt:
+              type: string
+              format: date-time

specs/contracts/json-rpc/account-service.yaml

@@ -0,0 +1,27 @@
+jsonrpc: '2.0'
+info:
+  title: Trade Show Account RPC
+  version: 1.0.0
+  description: RPC contract for quick-start account guidance.
+methods:
+  account.getQuickStartPrompt:
+    summary: Load quick-start prompt details for a newly created account
+    x-story: specs/stories/quick-start-audit.story.md
+    x-feature: specs/features/quick-start-audit.feature
+    x-journey: specs/journeys/trade-show-signup.journey.md
+    paramsSchema:
+      type: object
+      required: [accountId]
+      properties:
+        accountId:
+          type: string
+    resultSchema:
+      type: object
+      required: [accountId, cta, recommendedTemplateId]
+      properties:
+        accountId:
+          type: string
+        cta:
+          type: string
+        recommendedTemplateId:
+          type: string

specs/contracts/openapi/api.yaml

@@ -41,7 +41,7 @@ paths:
     post:
       operationId: createInitialAudit
       x-story: specs/stories/quick-start-audit.story.md
-      x-feature: specs/features/mobile-signup.feature
+      x-feature: specs/features/quick-start-audit.feature
       x-journey: specs/journeys/trade-show-signup.journey.md
       summary: Create a first audit from quick-start prompt
       parameters:

specs/features/quick-start-audit.feature

@@ -0,0 +1,23 @@
+# id: quick-start-audit
+# type: feature
+# story: specs/stories/quick-start-audit.story.md
+# journey: specs/journeys/trade-show-signup.journey.md
+# contract: openapi POST /accounts/{accountId}/audits
+# contract: asyncapi publish audits/created
+# contract: json-rpc account.getQuickStartPrompt
+
+Feature: Quick-start audit
+  In order to see product value before leaving the booth
+  As a newly signed-up prospect
+  I want the system to guide and confirm my first audit quickly
+
+  Scenario: The confirmation screen loads quick-start guidance
+    Given the prospect has just created an account
+    When the client requests quick-start prompt details
+    Then the response includes the primary call to action
+    And the prompt recommends a default audit template
+
+  Scenario: Creating the first audit emits a contract event
+    Given the prospect starts the first audit from the confirmation screen
+    When the system creates the audit
+    Then an audit created event is published for downstream consumers

specs/fixtures/quick-start-audit-event.fixture.yaml

@@ -0,0 +1,16 @@
+id: quick-start-audit-event
+type: fixture
+story: specs/stories/quick-start-audit.story.md
+feature: specs/features/quick-start-audit.feature
+scenario: Creating the first audit emits a contract event
+contract:
+  protocol: asyncapi
+  ref: specs/contracts/asyncapi/audit-events.yaml
+  channel: audits/created
+  action: publish
+request:
+  payload:
+    auditId: audit_001
+    accountId: acct_001
+    templateId: template_trade_show_default
+    createdAt: '2026-03-21T10:15:00Z'

specs/fixtures/quick-start-audit-rpc.fixture.yaml

@@ -0,0 +1,17 @@
+id: quick-start-audit-rpc
+type: fixture
+story: specs/stories/quick-start-audit.story.md
+feature: specs/features/quick-start-audit.feature
+scenario: The confirmation screen loads quick-start guidance
+contract:
+  protocol: json-rpc
+  ref: specs/contracts/json-rpc/account-service.yaml
+  method: account.getQuickStartPrompt
+request:
+  params:
+    accountId: acct_001
+response:
+  result:
+    accountId: acct_001
+    cta: Start first audit
+    recommendedTemplateId: template_trade_show_default