Dark-Alex-17andSisyphus
720591d24a
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 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`](../code-reviewer/README.md),
|
|
[`adversary`](../adversary/README.md), [`security-reviewer`](../security-reviewer/README.md))
|
|
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`](../../skills/codebase-design/SKILL.md) 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
|
|
|
|
```sh
|
|
# 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`](../../skills/codebase-design/SKILL.md) — the vocabulary and principles it runs on.
|
|
- [`oracle`](../oracle/README.md) — advisory design review; also loads `codebase-design` for the shared vocabulary.
|
|
- [`explore`](../explore/README.md) — the codebase walkers it fans out.
|
|
|
|
## Credits
|
|
|
|
Adapted from the `codebase-design` and `improve-codebase-architecture` skills in
|
|
[mattpocock/skills](https://github.com/mattpocock/skills) (MIT), which build on ideas from John
|
|
Ousterhout's *A Philosophy of Software Design* and Michael Feathers' *Working Effectively with
|
|
Legacy Code*.
|