CCBuddy: Skill for Codex

Architecture governance

Use this skill before editing code in the CCbuddy 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

1. Identify intended files and modules from the task, contracts, and existing tests. Run pnpm architecture:check --changed for the current baseline; a clean diff does not identify files you have not edited yet.
2. For cross-module changes, state ownership changes, or an unclear contract, run pnpm architecture:context <module-id> (or node .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.
3. 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.
4. 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. Keep ui → hooks/services → app → domain → adapters and keep IO out of domain.
   • Explicit time: for asynchronous or remote behavior, write the event order, owner/lease, idempotency key, stale-result rule, replay/resume boundary, and desktop versus Web/SSH 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.
5. 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.