architecture-governance
Skill8 starsChanged 33 days agoApache-2.0View on GitHub
Check CCbuddy module and layer boundaries for code changes. Generate bounded context for cross-module or ownership changes; skip documentation-only work.
6 other projects use a version of this, 5 of them edited.
Adopted by
Most recently taken up by
- axiom-desu/ZCodiumedited, first seen Nov 15, 2026
- skillpie/ZCodeOnlineedited, first seen Nov 5, 2026
- ZCodium-project/ZCodiumedited, first seen Nov 1, 2026
- betacatsling/Open-ZCodeedited, first seen Oct 13, 2026
- zai-org/ZCodeedited, first seen Oct 8, 2026
- Cartograf666/alex-ter-vibeskillstheir own version, first seen Aug 13, 2026
Used with
Projects with it also use e2e-case-lifecycle, zcode-large-task-fixture and 1 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ZCodium-projectSkille2e-case-lifecycle
Plan, maintain, replay, and promote ZCode desktop E2E cases and their fixtures, coverage matrices, and CI admission evidence.
Also in 3 projects that use this
ZCodium-projectSkillzcode-large-task-fixture
Generate, verify, or remove large synthetic ZCode task fixtures in local ~/.zcode persistence for UI/session performance testing. Use when testing big conversation/task rendering, task list performance, snapshot recovery, tool-call rendering, reasoning, patches, todos, and model usage without spending time chatting manually.
Also in 3 projects that use this
WillhongSkillsession-management
Also in 3 projects that use this
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 5
- zai-org/ZCode★ 8.6k76% same
- ZCodium-project/ZCodium★ 25378% same
- axiom-desu/ZCodium★ 3751% same
- skillpie/ZCodeOnline★ 376% same
- betacatsling/Open-ZCode★ 051% same
Wrote their own version · 1
- Cartograf666/alex-ter-vibeskills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/react-best-practices/AGENTS.mdAGENTS.md
- agent-browserSkill
- ai-elementsSkill
- dep-refsSkill
- dogfoodSkill
- electronSkill
- feature-boundary-plannerSkill
- vercel-react-best-practicesSkill
The file
We split this skill into the rules it gives an agent
4 rules. 2 are common, 1 is distinctive, and 1 is very specific to this project.
2
Common
Most of the 6 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Bounded context: use the relevant contracts, specs, and tests.
- Common: line 23
Use this compact design sketch while planning stateful changes:
- Common: line 40
Keep changes inside the declared module and its allowed layer direction.
- Very specific: line 41
Run pnpm architecture:check --changed after editing.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- 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. Keep
ui → hooks/services → app → domain → adaptersand 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.
- 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:
input → single owner → command admission → state transition → contract/event
└── persistence / replay / projection are derived from the ownerFor remote or streaming changes, make the delivery boundary explicit:
desktop: continuous ── direct live stream ──┐
├─ same owner and sequence
Web/SSH: replayable ─ snapshot + gap repair ┘During and after editing
- Keep changes inside the declared module and its allowed layer direction. Add a module dependency or public contract before introducing a cross-module edge.
- Run
pnpm architecture:check --changedafter editing. Report new violations separately from baseline violations; include owners and event-order assumptions when affected. Follow the root validation matrix, finish after required checks pass, and expand checks only for new edits, failures, or unresolved risks.
The executable policy is architecture-policy.yaml; keep its detailed rule definitions there. Check the actual managed-module coverage before claiming the gate verifies a boundary: a passing result does not prove unconfigured modules or runtime semantics are correct. Use pnpm architecture:baseline:update only when a reviewed change intentionally changes the accepted legacy baseline. CI never refreshes baseline automatically.
For a new managed module, provide module.ts, contract.ts, contract.example.ts, contract.test.ts, and a short CONTRACT.md. Keep runtime and persistence details behind the contract. Prefer typed service calls for one-to-one interactions, commands for state changes, and typed events for broadcast facts.
See policy-schema.md, module-contract.md, and rule-catalog.md when the change needs their detailed guidance. The golden-module fixture is the smallest compliant example. See ai-guidance.md for the anti-patterns this workflow is designed to prevent and the questions an agent must answer before proposing code.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

