design-invariants

Design Invariants Skill

Audits a design proposal or diff against Exarchos-specific architectural invariants. Project-scoped — these invariants govern Exarchos itself, not consumers of the Exarchos plugin.

The skill is the operational complement to issue #1118 (codify principles) and #1109 (cross-cutting constraints). Reference content is also a candidate to back the v2.11.0 #1275 (MCP Resources) surface and the #1260 machine-readable invariants generator — every invariant carries a stable ID and structured shape.

When to use

During /exarchos:ideate or /exarchos:plan, before committing a design.
During /exarchos:review, alongside /axiom:audit.
When reviewing a PR that touches the event store, MCP surface, runtime YAML, or composite tool registry.

When NOT to use

For generic backend quality — use /axiom:* skills (see complementarity matrix below).
For TDD / spec compliance — use /exarchos:review or the spec-review skill.
For prose / AI-writing tells — use /axiom:humanize.

How to invoke

State the artifact under review (design path, diff range, or PR URL).
Walk INV-1..INV-5 in order, recording HIGH/MEDIUM/LOW findings per invariant.
For INV-5, walk all four sub-disciplines (5a input ergonomics, 5b output contract, 5c Aspire verbs, 5d action discriminator).
Cross-link any axiom finding that overlaps (e.g., a topology issue under INV-1 may also be DIM-1).
Output the same finding format as axiom (severity + dimension + file:line + description + required_fix).

Invariant references

INV-1 → references/INV-1-event-sourcing.md
INV-2 → references/INV-2-facade-equivalence.md
INV-3 → references/INV-3-basileus-forward.md
INV-4 → references/INV-4-platform-agnosticity.md
INV-5a → references/INV-5a-input-ergonomics.md
INV-5b → references/INV-5b-output-contract.md
INV-5c → references/INV-5c-aspire-verbs.md
INV-5d → references/INV-5d-action-discriminator.md
Deterministic checks → references/deterministic-checks.md

Finding format

Match axiom's vocabulary (HIGH / MEDIUM / LOW) so reviewers don't context-switch:

{
  "verdict": "pass | conditional | fail",
  "findings": [
    {
      "invariant": "INV-1",
      "severity": "HIGH",
      "file": "servers/exarchos-mcp/src/projections/foo.ts",
      "line": 42,
      "description": "Reducer mutates state in place inside the apply switch",
      "required_fix": "Return a new state object via spread; deep-freeze input via assertReducerImmutable in tests",
      "axiom_overlap": "DIM-1"
    }
  ]
}

Pairing with axiom — complementarity matrix

The seam: axiom asks "is this code well-engineered?"; this skill asks "does this design respect Exarchos's load-bearing invariants?" A design can be axiom-clean and still violate event-sourcing integrity (a perfectly well-typed handler that mutates state in place instead of emitting events).

Finding	Axiom dimension	Design invariant
Lazy fallback that creates degraded EventStore	DIM-1 Topology	INV-1 (silent loss of event integrity)
Hardcoded `Skill({...})` in skills-src	—	INV-4
`console.log`-only catch in projection apply	DIM-2 Observability	INV-1 (fold throws → must trigger reducer-throw degradation path)
New CLI verb without MCP equivalent	—	INV-2
Adapter-local mutable cache for projection state	DIM-1 Topology	INV-1 + INV-2 (TaskStore-as-side-database anti-pattern)
`runtimes/claude.yaml` field read at runtime	—	INV-3
Tool description without "do NOT use for" guidance	—	INV-5a
Successful `ToolResult` without `next_actions`	—	INV-5b
Long-running op using NDJSON post-v2.11.0	—	INV-5b (should use Tasks SEP-1686)
New top-level tool that should be an action on `exarchos_workflow`	—	INV-5d
Schema field removed but still read	DIM-3 Contracts	INV-1 if it's an event field

Concerns axiom owns and this skill defers to:

Concern	Owner
Generic SOLID, coupling, dependency direction (DIM-6)	`axiom:critique`
Generic error handling, silent fallbacks (DIM-2, DIM-7)	`axiom:harden`
Generic schema-runtime drift, type-assertion safety (DIM-3)	`axiom:scan`, `axiom:critique`
Generic test fidelity, mock overuse (DIM-4)	`axiom:verify`
Generic dead code, vestigial patterns (DIM-5)	`axiom:distill`
AI-prose tells (DIM-8)	`axiom:humanize`

Source

Discovery report: docs/research/2026-05-07-design-invariants-skill.md. Amend this skill when the principles doc per #1118 lands at docs/architecture/principles.md — the skill becomes the operational projection of that doc rather than re-stating principles.