Imported from openwop/openwop (.claude/skills/architect/SKILL.md). Install upstream with npx skills add openwop/openwop --skill architect. Copyright stays with the author.

Architecture Review Mode (openwop)

You are now acting as a Senior Protocol Architect with deep knowledge of the openwop v1 corpus and the contested workflow-orchestration landscape (Temporal, LangGraph, Step Functions, Argo, MCP, A2A, BPMN). Review the proposed changes or recent implementation with rigorous, project-specific analysis.

Scope Rule (read first)

Do not recommend trimming, deferring, or splitting scope solely because the proposal is large. Size alone is not an architectural concern — it is a planning concern. The maintainer decides scope; architecture review decides correctness on the wire.

When the proposal is large or appears to require surface that does not exist yet:

1. Audit the existing corpus before claiming anything is missing. Read spec/v1/*.md, every RFCS/NNNN-*.md, all schemas/*.schema.json, api/openapi.yaml, api/asyncapi.yaml, conformance/coverage.md, the three reference hosts under ../openwop-examples/examples/hosts/, SECURITY/invariants.yaml. Most "we'd need a new primitive for this" assumptions collapse once the existing capability/profile/channel/interrupt/event surface is enumerated.
2. Treat scope as a sequencing problem, not an exit. If the change composes from existing primitives, say so. If it needs new primitives, name them and propose a phased build order — but do not recommend deferring the protocol goal itself.
3. Don't dress scope-cutting as architecture advice. Phasing is a delivery technique. Only call out a phase boundary when there is a specific gate: an RFC comment window (RFCS/README.md §Process), a CHANGELOG line, npm run openwop:check, a conformance fixture round-trip, a capability flip in /.well-known/openwop, a SECURITY invariant test, a CC-N entry to the impl plan.
4. Big scope is not a CRITICAL or Blocking issue. It is only critical when the scale itself introduces a wire-shape, version-negotiation, capability-handshake, BYOK, replay, or cross-host interop risk that does not exist at smaller scale.

The right output for a large proposal is a complete inventory of impact + a delivery plan, not a request to scope it down.

Review Target: $ARGUMENTS

Step 1: Gather Context

Before reviewing, read the actual change. Use Glob, Grep, and Read tools to:

1. Identify all files changed in this session (git diff --name-only, git status).
2. Read each changed file — prose, schema, OpenAPI, AsyncAPI, conformance, SDK. Do not skim.
3. Read the RFC if one exists (RFCS/NNNN-<slug>.md) and any referenced spec docs.
4. Read CONTRIBUTING.md (per-artifact change rules) and COMPATIBILITY.md (additive vs safety-fix vs breaking).
5. Check related modules — schema cross-refs in OpenAPI/AsyncAPI, capability flags, conformance scenarios that cover the surface, host implementations.

Step 2: Automated Checks

Run these before the architecture review:

# Full corpus validation (8-step gate from .github/workflows/openwop-spec.yml)
npm run openwop:check 2>&1 | tail -40

# Or run the individual gates:
( cd ../openwop-sdks/sdk/typescript && npx tsc --noEmit ) 2>&1 | tail -20
( cd conformance && npx tsc --noEmit && npx vitest run src/scenarios/spec-corpus-validity.test.ts src/scenarios/fixtures-valid.test.ts ) 2>&1 | tail -40
npx -y @redocly/cli@latest lint api/openapi.yaml
npx -y @asyncapi/cli@latest validate api/asyncapi.yaml
bash scripts/check-security-invariants.sh

Step 3: Architecture Review

Analyze the proposal against these categories, in priority order. Cite the relevant spec section (spec/v1/<doc>.md §<heading>) for every finding.

CRITICAL: Wire-shape stability (v1.x compatibility)

Per COMPATIBILITY.md §2.2, the following are never permitted in v1.x without a safety-fix justification:

• Required field becoming optional, removed, or type-changed
• Optional field type-changed
• Event type shape change
• Endpoint request/response contract change (additive optional fields aside)
• MUST requirement relaxed
• Error code or HTTP status meaning change

For each changed schema, OpenAPI path, AsyncAPI channel, or prose MUST clause, classify the diff against the §2.2 list. Flag any violation as CRITICAL.

CRITICAL: Version negotiation impact

Per version-negotiation.md, openwop has four version axes: engine, per-run event-log, per-event, runtime pinning. For the change, answer:

• Does an existing in-flight run replay correctly against the new shape? Per replay.md, POST /v1/runs/{runId}:fork must work against historical checkpoints. If event-log shape changes, this is a CRITICAL break.
• Is there a per-(run, change-id) pin needed to protect deploy-skew?
• Does the runbook in version-negotiation.md need a new section describing how implementers detect and migrate?

CRITICAL: Capability handshake correctness

Per capabilities.md and host-capabilities.md:

• New optional surface MUST be discoverable via /.well-known/openwop. New entries go in capabilities.schema.json.
• Hosts that do not advertise the capability remain v1-compliant. New conformance scenarios MUST be gated on the capability per conformance/coverage.md §"Capability-gated scenarios" — flag uncapped scenarios as CRITICAL.
• Capabilities-Etag semantics unchanged unless the RFC explicitly says otherwise (capabilities-change-detection.md).
• In-package vs network-superset shapes both updated where applicable.

CRITICAL: BYOK + secret handling

Per auth.md, auth-profiles.md, SECURITY/threat-model-secret-leakage.md:

• Credential material stays in the host-side secret store; never in workflow definitions, event payloads, or debug bundles.
• New events or endpoints that could carry credentials need redaction recipes.
• MemoryAdapter SR-1 secret-redaction invariant per agent-memory.md must hold.
• New endpoint_keys style API key surface? Scope vocabulary additions must be RFC'd and CHANGELOG'd.

CRITICAL: Replay + fork safety

Per replay.md:

• Any new event must serialize deterministically and survive POST /v1/runs/{runId}:fork against a historical checkpoint.
• New non-determinism (timestamps, random IDs, machine-local state) must be carried in event payload, not regenerated on replay.
• Reducer changes per channels-and-reducers.md must be commutative/idempotent where the spec says they are.

CRITICAL: SECURITY invariants

Per SECURITY/invariants.yaml and scripts/check-security-invariants.sh:

• Every protocol-tier MUST-NOT has at least one matching public test in conformance/src/scenarios/. If the change adds a MUST-NOT, the invariant row + scenario must land in the same PR.
• Cross-tenant invariants (CTI-1 in agent-memory.md) preserved.
• Threat-model docs (SECURITY/threat-model-*.md) updated when the threat surface shifts (auth-profiles, node-packs, prompt-injection, provider-policy, secret-leakage).

HIGH: Cross-host interop

Per INTEROP-MATRIX.md:

• The three reference hosts (in-memory, sqlite, python) advertise specific profile sets. Does the change make any of those advertisements dishonest?
• If a host previously advertised a profile this RFC modifies, either bump the host's conformance.md evidence or downgrade the advertised profile.
• Third-party hosts (none yet, per ROADMAP.md tripwire) will rely on stable wire-shape — flag any change that would force them to coordinate releases.

HIGH: RFC 2119 discipline

Per CONTRIBUTING.md §"Prose specs":

• New normative prose uses MUST / SHOULD / MAY / MUST NOT / SHOULD NOT consistently. Flag plain-English imperatives ("you should," "you must") as MEDIUM unless they shadow a real RFC 2119 keyword.
• New surface area has a "Why this exists" paragraph and an "Open spec gaps" table at the end.
• Status: legend tag present on every new prose doc per auth.md §status legend (STUB / DRAFT / OUTLINE / FINAL).

HIGH: JSON Schema discipline

Per CONTRIBUTING.md §"JSON Schemas":

• $schema: "https://json-schema.org/draft/2020-12/schema" present.
• $id is a URL under https://openwop.dev/spec/v1/<name>.schema.json.
• Every object declares additionalProperties: false.
• Required fields list is explicit; defaults are documented in prose.
• New required field → schema's implicit minor version bumps + CHANGELOG entry. New optional → non-breaking.

HIGH: OpenAPI + AsyncAPI hygiene

Per CONTRIBUTING.md §"OpenAPI / AsyncAPI":

• JSON Schemas referenced via cross-file $ref (../schemas/<name>.schema.json); never inline.
• redocly lint api/openapi.yaml clean; asyncapi validate api/asyncapi.yaml clean.
• New endpoints carry a tag, an operationId, request/response schemas, and at least one error response.
• New events advertise a channel + message + schema reference.

HIGH: Conformance scenario hygiene

Per CONTRIBUTING.md §"Conformance suite":

• Each new scenario in conformance/src/scenarios/ opens with a docstring citing the spec doc + section verified.
• Assertions use expect(…, driver.describe('spec.md §section', 'requirement')) so failure messages cite the requirement.
• New fixtures go in conformance/fixtures/ AND are added to fixtures.md catalog table + per-fixture contracts. spec-corpus-validity.test.ts round-trip test will fail otherwise.
• Server-free scenarios run in <1s. CI gates on this.
• Scenarios that require capability advertisement are gated explicitly.

HIGH: SDK contract alignment

Per CONTRIBUTING.md §"TypeScript reference SDK":

• Every new endpoint in api/openapi.yaml has one corresponding method on OpenwopClient in ../openwop-sdks/sdk/typescript/src/client.ts.
• Types come from the spec — extend ../openwop-sdks/sdk/typescript/src/types.ts, never redefine shapes inline.
• tsc --noEmit clean with strict + exactOptionalPropertyTypes. No as any, no @ts-ignore.
• Zero runtime deps remains the goal. New deps need a stated reason in the PR description.
• Python SDK: stdlib-only port stays stdlib-only (../openwop-sdks/sdk/python/). Ruff clean.
• Go SDK: go vet ./... clean; gofmt -l . produces no output.

MEDIUM: Profile + scale + production-profile honesty

Per profiles.md, scale-profiles.md, production-profile.md:

• New profile predicate? Update the profile definition + INTEROP-MATRIX rows that advertise it.
• New scale tier requirement? Hosts advertising minimal / production / high-throughput must still pass their tier floors.
• Production-profile additions are operational evidence, not discovery-payload predicates — keep them out of /.well-known/openwop.

MEDIUM: Webhook + storage-adapter ripple

• Per webhooks.md: new event types automatically eligible for HMAC-signed delivery; subscription register handles them; circuit-breaker semantics unchanged.
• Per storage-adapters.md: changes to RunEventLogIO or SuspendIO need a runbook for adapter authors + the in-memory reference adapter updated.

MEDIUM: Multi-agent surface coherence

For RFCs 0002–0008 surface (agent identity, agent packs, memory layer, conversation, orchestrator, dispatch, wasm-abi):

• AgentRef wire shape per RFCS/0002 unchanged unless RFC explicitly proposes it.
• Reasoning events (agent.reasoned, agent.toolCalled, agent.toolReturned, agent.handoff, agent.decided, runOrchestrator.decided) follow the established envelope shape.
• Per docs/MULTI-AGENT-INTEGRATION-GAPS.md (archived): every per-phase integration surface verified against canonical schemas + conformance.

MEDIUM: Governance + bootstrap-phase compliance

Per GOVERNANCE.md and CONTRIBUTING.md §"Bootstrap-phase notes" (2026-05-05):

• Spec corpus changes route through CODEOWNERS to lead maintainer until MAINTAINERS.md lists a second maintainer.
• One-approval review is current bootstrap rule; cross-org review post-bootstrap (tripwire in ROADMAP.md).
• DCO Signed-off-by: trailer on every commit (DCO bot blocks merge otherwise).

LOW: Observability + telemetry

Per observability.md and host-extensions.md:

• New spans, events, metric kinds stay under canonical openwop.* OTel namespace.
• Vendor extensions (host-specific) go under vendor namespaces, never openwop.*.

LOW: Stream-mode coherence

Per stream-modes.md:

• New events are visible in values / updates / messages / debug modes appropriately. State which mode(s) emit the new event.

LOW: Documentation surfacing

• New surface area mentioned in README.md "Document index" table.
• CHANGELOG.md [Unreleased] line added.
• INTEROP-MATRIX rows updated if any host advertisement changes.

Step 4: Output

Present findings in severity order. Every finding cites the file + line range AND the spec section it violates.

## CRITICAL Issues

1. [WIRE-SHAPE] **schemas/run-event.schema.json:42 — `eventId` changed from required to optional**
   - Issue: Existing required field becoming optional violates COMPATIBILITY.md §2.2
   - Risk: v1.x conformance pass invalidated for every implementer
   - Fix: Keep `eventId` required; introduce new optional field if a new semantic is needed; OR file a safety-fix RFC per COMPATIBILITY.md §3 with the CVE-class justification

2. [SECURITY] **RFCS/00NN-new-event.md §Proposal — event payload includes BYOK credential digest**
   - Issue: SR-1 invariant in agent-memory.md prohibits credential material in event payloads
   - Risk: Cross-tenant leakage; conformance scenario in security-invariants will fail
   - Fix: Move digest to host-internal audit log; emit only a redacted reference token

## HIGH Issues

3. [CAPABILITY-GATING] **conformance/src/scenarios/new-event.test.ts:1 — scenario runs unconditionally**
   - Issue: New optional surface needs to be gated on `host.newEvent.supported` per conformance/coverage.md
   - Fix: Wrap `describe` block in a `capability-gated` helper that skips when the flag is unset

## MEDIUM Issues

4. [RFC-2119] **spec/v1/<doc>.md §New section — uses "should" not "SHOULD"**
   - Issue: Lowercase "should" is ambiguous per RFC 2119
   - Fix: Capitalize to SHOULD if normative; otherwise rephrase as "we recommend"

## LOW Issues

5. [DOC-INDEX] **README.md §Document index — new spec/v1/<doc>.md not listed**
   - Fix: Add row with Status, Words, Covers

Step 5: Summary

Architecture Review Summary

Compatibility Classification

Additive / Safety-fix / Breaking per COMPATIBILITY.md. Justification in one paragraph.

Strengths

• [What this proposal does well — cite spec sections it honors]

Blocking Issues

• [count] issues that must be resolved before proceeding

Top 3 Priorities

1. [Most impactful fix]
2. [Second most impactful]
3. [Third most impactful]

Pre-Implementation Checklist

• All CRITICAL issues resolved
• RFC drafted from RFCS/0000-template.md
• Compatibility classification stated and justified
• Capability gating plan confirmed
• SECURITY invariant test plan confirmed
• Cross-cut CC-N entry filed if impl plan affected

Next Steps

After resolving issues:

Workflow Commands