coyote/assets/agents/architecture-reviewer/README.md

Architecture Reviewer

An on-demand architecture improvement scout. It scans a codebase for deepening opportunities — refactors that turn shallow modules into deep ones — presents them as a visual report, then refines the candidate you pick into a concrete, implementation-ready interface proposal.

Two things it is deliberately not:

1. Not a completion gate. The review stack (code-reviewer, adversary, security-reviewer) judges changes before a task finishes. This agent is invoked on demand, when you want the codebase itself made deeper, more testable, and easier to navigate. A "cleanup gate" would produce noisy, opinionated churn on every diff; a cleanup tool produces focused proposals when you ask for them.
2. Not an implementer. It proposes; you (or a coder you delegate to) implement. Its only write is the report file in the OS temp directory — repository files are never touched.

How it works

Driven by the codebase-design skill — the shared deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real").

1. Scope by git history (YAGNI). Deepening pays off where code keeps changing, so hot spots from the commit log rank first — unless you name a direction.
2. Explore for friction. Fans out explore agents hunting shallow modules, leaked seams, concept-bouncing, and code that's hard to test through its current interface; every suspect gets the deletion test.
3. Report candidates. 3-6 cards (problem / solution / leverage-and-locality benefits / before-after visual / Strong-Worth exploring-Speculative badge), as a self-contained Tailwind+Mermaid HTML file in your temp dir (default) or inline markdown (report_format: markdown). Ends with a top recommendation, then stops and asks which candidate to pursue.
4. Refine via design-it-twice. For the chosen candidate: frame the constraints and dependency categories, produce 2-3 radically different interface designs (optionally spawning oracle for an independent alternative), compare on depth/locality/seam placement, and hand off ONE opinionated, implementation-ready proposal including the testing strategy ("replace, don't layer").

Usage

# Scan the current repo, HTML report
coyote -a architecture-reviewer "Find deepening opportunities"

# Aim it at a pain point, inline report
coyote -a architecture-reviewer --agent-variable report_format markdown \
  "The billing/entitlements code is painful to test - what should be deepened?"

Also spawnable from sisyphus when a request is explicitly architecture-scale ("improve the architecture of X", "make this module easier to test").

Related

• codebase-design — the vocabulary and principles it runs on.
• oracle — advisory design review; also loads codebase-design for the shared vocabulary.
• explore — the codebase walkers it fans out.

Credits

Adapted from the codebase-design and improve-codebase-architecture skills in mattpocock/skills (MIT), which build on ideas from John Ousterhout's A Philosophy of Software Design and Michael Feathers' Working Effectively with Legacy Code.