formalize

name	formalize
description	Use after a human jam session to turn agreements into code. Converts shared artifacts into versioned event schemas, mocks, and validation config. Keywords: formalize, contracts, event schemas, boundaries, multi-human, event storming.
argument-hint	<path to shared jam artifact>
disable-model-invocation	false
user-invocable	true
allowed-tools	Read, Grep, Glob, Write, Edit, Bash(git:*), Task
context	inline

Formalize: Event Contract Generation from Jam Artifacts

You are running the formalize skill — Phase 3 of the multi-human Event Storming workflow. Input: $ARGUMENTS

This skill consumes the shared jam artifact produced by a human jam session (seeded by /storm-prep) and generates machine-readable event contracts that /integrate will use to wire services together.

When to Use

• After a human jam session has produced a shared artifact documenting bounded contexts, owned events, and consumed events
• When you need to translate verbal or whiteboard agreements into versioned event schemas
• When each team member needs their own contract-aware mocks and validation config for local development
• Before running /sprint agents — contracts gate all implementation tasks

DO NOT Use When

• You have not completed a human jam session — schemas from assumptions are not contracts
• The shared artifact is incomplete (missing ownership, unclear boundaries, or unresolved disputes)
• You are trying to shortcut the jam session — formalize codifies agreement, it does not create it

Named Law

NO SCHEMA WITHOUT JAM ARTIFACT — If you are formalizing from assumptions rather than a shared artifact, STOP. Return to /storm-prep and complete the jam session. Contracts without jam artifacts are guesses wearing a schema's clothing.

What NOT to Do

• Do not resolve ambiguities by assuming — If the jam artifact says "TBD" or leaves ownership unclear, surface the ambiguity to the user and halt. Do not pick a side.
• Do not treat silence as agreement — An event that appears in diagrams but has no explicit owner is unresolved. Mark it POSSIBLE and flag it.
• Do not skip confidence tagging — Every field, every event, every boundary gets a confidence tag: CONFIRMED (explicitly agreed in session), LIKELY (implied by context or ownership patterns), POSSIBLE (assumed from usage without explicit agreement).
• Do not generate schemas for another team's bounded context — Each human runs formalize for their own context only. Cross-boundary schemas come from consuming, not owning.
• Do not invent field names — Use names as agreed in the jam artifact. If a field name is ambiguous, note the ambiguity and use the artifact's wording verbatim.

Overview

$ARGUMENTS (shared jam artifact path)
    |
    v
Phase 0: Gate — artifact exists and readable?
    |
    v
Phase 1: Parse — extract this human's bounded context, owned events, consumed events
    |
    v
Phase 2: Schema generation — versioned YAML schemas with field definitions and confidence tags
    |
    v
Phase 3: Mock generation — mock producers for consumed events, stub consumers for provided events
    |
    v
Phase 4: Validation config — contract-aware validation for local /sprint agents
    |
    v
Output: contracts/agreed/*.schema.yaml + mocks/ + validation config + pipe-format summary

---

Phase 0: Gate (Precondition Check)

STOP if any gate fails. Do not proceed to Phase 1 until all gates pass.

Gate 1 — Artifact path provided

If $ARGUMENTS is empty, ask: "What is the path to the shared jam artifact? (e.g., docs/jam/session-YYYY-MM-DD.md)"

Gate 2 — Artifact exists and is readable

Read the file at $ARGUMENTS. If the file does not exist or cannot be read:

"Jam artifact not found at <path>. Ensure the shared artifact from your human jam session is committed and accessible before running /formalize. If you have not completed a jam session, run /storm-prep first."

Gate 3 — Artifact has required structure

Scan the artifact for:

• A bounded context section identifying ownership assignments
• An event list with explicit owners (not just "discussed" or "TBD")
• At least one event with a clear owner and at least one field definition

If the artifact is missing any of these:

"The jam artifact at <path> is missing required sections: [list what is missing]. Complete the human jam session and update the artifact before formalizing. Formalize codifies agreement — it cannot create it."

Gate 4 — Identify this human's context

Ask (or detect from $ARGUMENTS if a context name was provided): "Which bounded context are you formalizing contracts for?"

State the detected context before proceeding: "Formalizing contracts for bounded context: <context-name>"

---

Phase 1: Parse Shared Artifact

Read the full shared artifact. Extract three lists for this human's bounded context only:

1a. Owned Events

Events this context produces and owns — the events for which this team generates authoritative schemas.

For each owned event, extract:

• Event name
• Version (if stated; default to v1 if not)
• All fields mentioned in the artifact, with types if stated
• Any business rules or constraints mentioned
• Confidence level for each element (CONFIRMED / LIKELY / POSSIBLE)

1b. Consumed Events

Events this context receives from other bounded contexts. This context does not own these schemas — it generates mocks for local testing only.

For each consumed event, extract:

• Event name
• Owning context (which team produces it)
• Fields this context is known to read
• Any SLA or ordering constraints mentioned

1c. Boundary Agreements

Explicit interface contracts agreed at the boundary:

• Which events cross which context boundaries
• Any versioning agreements (e.g., "Orders must not break before v2 migration completes")
• Any ordering or causality constraints

Parse Report

Print a structured summary before proceeding to Phase 2:

## Parse Summary: <context-name>

**Owned events**: N
  - <event-name> (CONFIRMED | LIKELY | POSSIBLE)
  - ...

**Consumed events**: N
  - <event-name> from <owning-context>
  - ...

**Boundary agreements**: N
  - <agreement summary>
  - ...

**Unresolved items** (require user input before schema generation):
  - <item> — [what is unclear]
  - ...

If unresolved items exist, ask the user to resolve them before continuing. Do not proceed to Phase 2 with unresolved ownership or missing field definitions for CONFIRMED events.

---

Phase 2: Schema Generation

Generate versioned event schemas as YAML for owned events only. Store each schema at contracts/agreed/<event-name>.<version>.schema.yaml.

Create contracts/agreed/ if it does not exist.

Schema Format

Each schema file follows this structure:

# contracts/agreed/<event-name>.<version>.schema.yaml
schema:
  name: <EventName>
  version: "<version>"
  owner: "<bounded-context-name>"
  source: "<path-to-jam-artifact>"
  formalized: "<YYYY-MM-DD>"

description: >
  <One paragraph describing what this event means in the domain,
  when it is emitted, and what guarantees the producer makes.>

fields:
  - name: <field-name>
    type: <string | integer | boolean | object | array | uuid | timestamp | enum>
    required: true | false
    description: "<What this field means. Cite the jam artifact if named explicitly.>"
    confidence: CONFIRMED | LIKELY | POSSIBLE
    constraints:
      - <e.g., "non-empty string", "ISO 8601 timestamp", "must be a valid UUID">
    example: <example value>

  - name: <field-name>
    ...

envelope:
  topic: "<message-bus-topic or queue name, if agreed>"
  ordering-key: "<field used for ordering, if agreed>"
  idempotency-key: "<field used for deduplication, if agreed>"

unresolved:
  - "<description of any POSSIBLE-confidence element needing human sign-off>"

Confidence Tagging Rules

• CONFIRMED: The jam artifact explicitly states this field, type, or constraint using the team's own words. Direct quote available.
• LIKELY: The field is implied by the event's purpose or by ownership patterns, but not explicitly named in the artifact.
• POSSIBLE: This element is assumed from usage patterns or analogous events. Needs human sign-off before implementation.

Tag every field with its confidence level. Do not omit tags on the grounds that "it is obvious."

Schema Generation Loop

For each owned event:

1. Create the schema file at contracts/agreed/<event-name>.<version>.schema.yaml
2. Populate from the parse output in Phase 1a
3. Tag each field with confidence
4. Add any POSSIBLE-confidence items to the unresolved section
5. State: "Written: contracts/agreed/<event-name>.<version>.schema.yaml (N fields, M unresolved)"

After all schemas are written, list the schema files created.

---

Phase 3: Mock Generation

Generate mock producers and stub consumers to enable local development without cross-team coordination.

3a. Mock Producers (for consumed events)

For each consumed event identified in Phase 1b, generate a mock producer that emits plausible test payloads. This lets local agents simulate upstream events without requiring the owning team's service.

Create mocks/producers/<event-name>-mock.yaml:

# mocks/producers/<event-name>-mock.yaml
mock:
  event: <EventName>
  owner: <owning-context>
  warning: "This mock is for LOCAL TESTING ONLY. Do not use in integration or production."
  source-schema: "<path-to-owning-team-schema if available, else 'unknown — schema not yet received'>"

payloads:
  - label: "happy path"
    fields:
      <field>: <plausible-test-value>
      ...

  - label: "edge case: <description>"
    fields:
      <field>: <edge-case-value>
      ...

Notes:

• Use plausible but clearly synthetic values (e.g., user-id: "test-user-001", not real UUIDs)
• Include at least one happy-path payload and one edge-case payload
• Mark the mock as LOCAL TESTING ONLY

3b. Stub Consumers (for owned events)

For each owned event, generate a stub consumer that documents the expected consumption pattern. This serves as a contract test target.

Create mocks/consumers/<event-name>-stub.yaml:

# mocks/consumers/<event-name>-stub.yaml
stub:
  event: <EventName>
  version: "<version>"
  owner: "<this-context>"
  schema: "contracts/agreed/<event-name>.<version>.schema.yaml"

consumption-contract:
  reads-fields:
    - <field-name>: "<why this field matters to consumers>"
    ...
  ordering-guarantee: "<guaranteed | best-effort | none>"
  idempotency: "<idempotent | at-least-once | exactly-once | unknown>"

contract-tests:
  - name: "rejects events missing required fields"
    input: { <omit a required field> }
    expected: reject

  - name: "accepts valid happy-path event"
    input: { <all required fields with valid values> }
    expected: accept

---

Phase 4: Validation Config

Generate a validation config that local /sprint agents can use to enforce contract compliance during development.

Create contracts/validation.yaml:

# contracts/validation.yaml
# Generated by /formalize from <path-to-jam-artifact>
# DO NOT edit manually — re-run /formalize to regenerate

context: "<bounded-context-name>"
formalized: "<YYYY-MM-DD>"

schemas:
  - event: <EventName>
    version: "<version>"
    schema: "contracts/agreed/<event-name>.<version>.schema.yaml"
    role: producer  # this context produces this event
    enforce: strict  # reject events that fail schema validation

  - event: <ConsumedEventName>
    version: "unknown"  # version not yet confirmed from owning team
    mock: "mocks/producers/<event-name>-mock.yaml"
    role: consumer  # this context consumes this event
    enforce: warn   # warn on schema mismatches but do not fail

sprint-agent-instructions: |
  Before dispatching sprint agents that produce or consume events:
  1. Check contracts/validation.yaml to identify owned vs consumed events
  2. Owned events: schema at contracts/agreed/ is authoritative — validate against it
  3. Consumed events: use mocks/producers/ for local testing — do not call real endpoints
  4. Flag any POSSIBLE-confidence fields in schemas as needing human sign-off before shipping
  5. Do not treat consumed event mocks as confirmed schemas — verify with the owning team

unresolved-flags:
  - <description of each POSSIBLE-confidence item requiring human sign-off>

After writing contracts/validation.yaml, read it back and verify it was written correctly. State: "Verified: contracts/validation.yaml written with N owned events and M consumed events."

---

Output Summary

After all phases complete, emit a pipe-format summary block. This output is consumed by /integrate as its Phase 0 input.

## Formalize Output: <bounded-context-name>

**Source**: /formalize
**Input**: <path to shared jam artifact>
**Pipeline**: /storm-prep (human jam session) -> /formalize

### Items (N)

1. **<EventName> schema** — versioned schema at contracts/agreed/<event-name>.<version>.schema.yaml
   - source: contracts/agreed/<event-name>.<version>.schema.yaml
   - confidence: CONFIRMED | LIKELY

2. **<ConsumedEventName> mock** — mock producer for local testing
   - source: mocks/producers/<event-name>-mock.yaml
   - confidence: LIKELY

3. **Validation config** — sprint-agent contract enforcement rules
   - source: contracts/validation.yaml
   - confidence: CONFIRMED

[... one item per schema, mock, and unresolved flag]

N+1. **Unresolved: <element>** — requires human sign-off before implementation
   - source: <jam artifact section>
   - confidence: POSSIBLE

### Summary

<One paragraph: which bounded context was formalized, how many owned schemas were generated, how many consumed mocks, how many unresolved items require sign-off, and what the integration gate is.>

The pipe-format block is the handoff artifact for /integrate. It lists all schemas, mocks, and unresolved items that the integration phase must reconcile across teams.

---

Guidelines

1. Artifact is truth — Every schema element traces to the jam artifact. When in doubt, cite the artifact line. If you cannot cite it, the element is POSSIBLE.
2. One context per run — Each human runs formalize for their own bounded context only. Do not generate schemas for events owned by other teams.
3. Confidence is non-negotiable — Every field gets a confidence tag. Fields without tags will silently mislead sprint agents.
4. Mocks are not schemas — A mock producer for a consumed event is a testing convenience, not an authoritative schema. Label it accordingly.
5. Unresolved items are features, not bugs — Surfacing POSSIBLE items for human sign-off is the skill working correctly. Do not suppress them to produce a "cleaner" output.
6. Verify every write — After writing each schema file, read it back to confirm it was written. Do not report success without verification.
7. Contracts gate implementation — Sprint agents should not implement producers or consumers until the relevant schema is at CONFIRMED confidence. The validation config encodes this gate.

See Also

• /storm-prep — Phase 2 of the multi-human workflow: produces the shared jam artifact that this skill consumes. Detection pattern for Phase 0: look for a ## Bounded Contexts section and explicit ownership tables in the shared artifact.
• /integrate — Phase 4 of the multi-human workflow: consumes this skill's pipe-format output to wire schemas across team boundaries. Consumption interface: reads the ## Formalize Output: <context> pipe-format block and cross-references schemas from all participants.
• /spec — If agreement on a bounded context or event cannot be reached, use /spec to produce a formal design document before re-running the jam session.
• /test-strategy — Consumes the stub consumers and contract tests in mocks/consumers/ to generate a full test plan for contract compliance.