# Architecture Governor

> Govern codebase architecture through evidence-backed workflow mapping, independent specialist audits or reviews, conflict resolution, and decision-complete planning. Use explicitly for repository architecture audits, architectural decisions, or architecture-focused branch reviews; stop before implementation.

- Skill: `kheawkachee/architecture-governor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kheawkachee/architecture-governor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kheawkachee/architecture-governor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: KheawKachee (https://skillmd.com/u/kheawkachee)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kheawkachee/architecture-governor

---


# Architecture Governor

Own the architectural judgment. Specialists provide independent evidence; they do not vote, choose the architecture, or implement it. Remain read-only and end with a decision-complete plan. If the session supports `/plan`, recommend invoking this skill there, but never claim a skill can switch session modes itself.

## Ground first

Before proposing architecture, inspect the relevant repository evidence end to end:

- user and CLI entrypoints;
- runtime calls and dependency direction;
- data, artifact, validation, and failure flows;
- tests, specifications, ADRs, and architecture documents;
- relevant history when identifying hotspots or changed intent.

Label claims as observed behavior, documented intent, or inference. For current behavior, code, tests, and runnable evidence outrank stale prose. For intended behavior, explicit requirements and accepted decisions outrank accidental implementation.

## Route the request

Inspect the available skill catalog and load only the smallest relevant set. Use exact skill names. Never recursively invoke `architecture-governor`.

Availability means presence in the current skill catalog, not merely a file on disk. If a specialist is not catalogued, do not pretend it ran; use only the fallback defined below and label the missing coverage.

| Skill | Task class | Lens | Required inputs | Output | Exclusions |
|---|---|---|---|---|---|
| `improve-codebase-architecture` with `codebase-design` | Whole-repo or scoped audit | Module depth, seams, locality, leverage, testability | Repository scope and governing docs | Architecture candidates with evidence | No implementation; do not continue into unavailable `grilling` or `domain-modeling` skills |
| `ponytail-audit` | Whole-repo audit | Deletion, native/stdlib replacements, speculative complexity | Repository scope | Ranked simplification findings | No correctness, security, or performance judgment |
| `codebase-design` | New decision or diff review | Interfaces, seams, adapters, dependency direction | Current flow and constraints | Design options or conformance findings | No speculative seam for one adapter |
| `code-review` | Diff or branch review | Documented standards and originating specification | Resolvable fixed point and spec, or explicit confirmation that no spec exists | Separate Standards and Spec reports | No whole-repo audit; do not merge its two axes |
| `ponytail-review` | Diff or branch review | Over-engineering in the change | Same fixed point/diff | Deletion and simplification findings | No correctness, security, or performance judgment |
| `tdd` | Accepted design | Observable behavior and public test seams | Selected interfaces and invariants | Acceptance scenarios and agreed test seams | Do not write tests or begin red-green implementation |
| `writing-plans` | Accepted design | Implementation handoff | Settled architecture, interfaces, constraints, and test seams | Decision-complete plan | Do not require unavailable `superpowers` skills or its default plan path; do not persist unless asked |

Future specialists belong in this registry only when they add a distinct lens, state their required inputs and exclusions, and have a defined reconciliation rule.

### Whole-repository architecture audit

The native workflow-evidence branch is mandatory. Run every applicable available branch, up to three independent subagents in parallel:

1. **Architecture:** use `improve-codebase-architecture`, informed by `codebase-design`.
2. **Simplicity:** use `ponytail-audit`.
3. **Workflow evidence:** natively trace entrypoints, calls, data/artifacts, validation, failures, tests, and documentation drift.

Give every subagent the same scope, repository state, and governing documents, but none of the other specialists' conclusions. Require read-only work, file/function evidence, uncertainty labels, and a compact report. If a named skill or downstream dependency is unavailable, report the limitation and perform only the feasible read-only analysis; never invent the missing skill's result.

If `improve-codebase-architecture` is unavailable, use `codebase-design` alone as a clearly labelled limited architecture lens. Report the missing coverage and do not describe the result as a full architecture audit.

### Diff or branch review

Require the user to supply the fixed point; never infer it from the current branch, its upstream, `main`, or another conventional ref. Resolve it, verify the three-dot diff is non-empty, and locate the originating spec. Then run at most three independent subagents in parallel:

1. **Architecture conformance:** use `codebase-design` against approved interfaces, seams, dependency direction, locality, and invariants.
2. **Standards/specification:** use `code-review`; preserve its Standards and Spec axes.
3. **Complexity:** use `ponytail-review` against the same diff.

If the fixed point is missing or invalid, stop and request it. If the resolved diff is empty, report that there are no reviewable changes and stop. If no spec can be found, ask for it or obtain explicit confirmation that none exists before running the Spec axis.

### New architectural decision

Use `codebase-design` for alternatives and seam placement. Use `improve-codebase-architecture` only when current structural friction is material. Do not apply Ponytail audit/review skills to an unimplemented proposal: their contracts require a repository or diff artifact.

After selecting the architecture, consult `tdd` to define test seams, then `writing-plans` to form the handoff. Within governance both are advisory references: this skill's read-only stop overrides downstream instructions to write tests, save a plan, commit, create a worktree, offer execution, or invoke implementation skills. Return test seams and the plan inline, then stop.

## Reconcile without voting

Present each specialist report under its own heading before synthesis. Agreement is not proof; re-check decisive claims against repository evidence. For every contested recommendation record:

| Field | Content |
|---|---|
| Evidence | Files, functions, calls, tests, or governing documents |
| Lens | Architecture, simplicity, standards, specification, or workflow accuracy |
| Benefit | Locality, leverage, correctness, clarity, reduced code, or reduced dependency |
| Risk | Lost validation, weakened contract, migration cost, speculative abstraction, or documentation drift |
| Decision | Accept, reject, defer, or investigate |
| Reason | The governor's architectural justification |

Resolve conflicts in this order:

1. Explicit user and product requirements.
2. Safety, correctness, and data or validation invariants.
3. Accepted specifications and ADRs.
4. Observed runtime behavior and tests.
5. Architectural locality and leverage.
6. Simplicity and deletion opportunities.
7. Style preferences.

Reject a deletion that removes a required validation boundary, independent verification, retry safeguard, or observable contract. Reject an abstraction that serves only hypothetical variation or fails the deletion test. Keep standards failures separate from specification failures. Reopen an ADR only with concrete new friction or changed requirements.

Treat claimed duplication across validation layers as contested until their responsibilities, enforced invariants, call sites, failure behavior, and tests have been compared. Processing the same payload or reporting overlapping errors is not by itself duplication.

## Visual architecture maps

Use Mermaid diagrams when relationships are material to the architectural judgment. For whole-repository audits and new architectural decisions, include the smallest applicable set that makes these concerns directly verifiable:

- end-to-end runtime workflow;
- module dependency direction;
- data and artifact flow;
- validation and failure flow;
- selected future-state architecture when it materially differs from the current state.

Keep current-state and proposed-state diagrams separate. Every node and edge must be supported by inspected repository evidence or clearly labelled as proposed; never make an inferred dependency look observed. Prefer several small diagrams over one unreadable diagram, and omit a diagram only when that relationship is genuinely inapplicable or already clear from a smaller visual.

## Deliverable and stop condition

Return only the sections applicable to the routed task:

- goal, scope, audience, and governing constraints;
- evidence-backed current-state workflow map;
- evidence-backed Mermaid architecture diagrams as required above;
- separate specialist reports;
- architectural options and tradeoffs;
- reconciliation table for contested findings;
- selected decision and rejected alternatives;
- interface, seam, dependency, data, validation, artifact, and failure-flow implications;
- public test seams and behavioral acceptance scenarios;
- a decision-complete implementation plan;
- the explicit statement: **Implementation has not begun.**

Do not fabricate a specialist report or reconciliation table when no specialist or contested finding exists. If the decision is reject or no change, provide the evidence and conditions for reconsideration instead of inventing an implementation plan.

Ask the user only when a material product or architecture choice cannot be resolved from repository evidence. Do not edit code, tests, architecture documents, plans, ADRs, or configuration while governing. Persist a plan or decision record only when explicitly requested in a later implementation turn.

`ponytail` is downstream of this hierarchy: it may minimize an approved implementation, but it cannot override the governor's decisions, invariants, validation boundaries, or test seams.

## Guardrails

- Do not load every installed skill.
- Do not let a specialist orchestrate the full specialist set.
- Do not share one specialist's conclusions with another before review.
- Do not use more than three concurrent review branches without a demonstrated need.
- Do not allow audit or review specialists to edit files.
- Do not silently normalize conflicting evidence.
- Do not expand a scoped documentation audit into a whole-repository audit automatically.
- If `docs/architecture/` or another requested path is absent, report it as not directly auditable, inventory architecture evidence elsewhere in the repository, identify uncovered traceability gaps, and propose only documents needed to close those gaps.