architecture-governance
Installation
SKILL.md
Architecture governance
Use this skill before editing code in the ZCode repository. It is a design guide as well as a gate: the goal is to make the intended architecture obvious before code is generated, so the checker confirms a decision instead of discovering it for the first time.
Before writing code
- Identify intended files and modules from the task, contracts, and existing tests. Run
pnpm architecture:check --changedfor the current baseline; a clean diff does not identify files you have not edited yet. - For cross-module changes, state ownership changes, or an unclear contract, run
pnpm architecture:context <module-id>(ornode .agents/skills/architecture-governance/scripts/context-package.mjs <module-id>). For a local change with a known contract, read only the relevant contract, spec, and affected tests; expand when a concrete dependency or evidence gap requires it. - Apply the spec and regression-evidence rules in AGENTS.md. New behavior needs a spec before implementation; restoring already specified behavior needs regression evidence, not a duplicate feature document. Pure refactors update docs only when contracts change.
- For changes to mutable state, asynchronous behavior, or module boundaries, make the relevant design decisions before coding:
- One owner: name the single component that owns each piece of mutable state. Other layers read through its contract and send commands; they do not keep a second accepted queue, cache, or derived truth.
- One path: reuse an existing command, service, hook, adapter, or contract when it already expresses the behavior. Do not create a parallel helper for the same responsibility.
- Explicit boundaries: choose the layer for every new file and the public contract for every cross-module edge. Layers from low to high are
contract < domain < app < adapters < ui; a file may import only its own layer or lower ones through their public surface.domainis pure (no IO, noawaiton the world),appdecides side effects through ports,adaptersexecutes them,uidepends only on this module'scontract.ts. Quick test: needsawait? not domain. Knows it is sqlite / MessagePort / a timer? adapters. - Explicit time: for asynchronous or remote behavior, write the event order, owner/lease, idempotency key, stale-result rule, replay/resume boundary, and desktop versus mobile delivery kind before implementation.
- Bounded context: use the relevant contracts, specs, and tests. A generated reading package helps when dependencies are unclear; do not require a whole-module reading pass for every local edit.
- If the change alters a public contract, ownership, or allowed dependency, record that decision in the relevant spec/contract before implementation. Editing files in two modules alone does not require a new document. Use the root task boundary for when to consult the user; ordinary authorized implementation choices proceed autonomously.
Use this compact design sketch while planning stateful changes: