Improve Codebase Architecture
Surface architectural friction and propose deepening refactors. Vocabulary (module, interface, seam, adapter, depth, leverage, locality) is defined in LANGUAGE.md. Use the deletion test: deleting a pass-through makes complexity vanish, while deleting a deep module pushes it into N callers. Treat a single production adapter as evidence that a seam may be hypothetical, not proof that it is unnecessary; keep it when it isolates real volatility, ownership, testability, or an architectural boundary.
Process
- Context: read the architecture rules in AGENTS.md and the target area's code. Use the project's own terminology from AGENTS.md, not generic glossaries.
- Explore — lightest mode that covers the request (direct inspection for a quick assessment; a read-only exploration subagent for a formal review). Note friction: bouncing between many small modules to follow one concept; interfaces nearly as complex as implementations; pure functions extracted for testability while the real bugs hide at call sites; layer divergence from the prescribed conventions; areas untestable through their current interface. Apply the deletion test to every shallow suspect.
- Candidates: quick assessment → concise findings in conversation. Formal review →
docs/architecture-reviews/YYYY-MM-DD-<topic>.md, one section per candidate: Files, Problem (friction evidence), Solution (plain English), Benefits (locality / leverage / testability), recommendation strength (Strong / Worth exploring / Speculative), ending with a Top recommendation. Diagrams only when clearer than prose.
- Grilling: after the user picks a candidate, walk the design tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive. Use your harness's question tool for structured choices (pi
question, Cursor AskUserQuestion); without one, ask in markdown. Do not design the full replacement interface until a candidate is selected. If the user rejects a candidate with a load-bearing reason, record it in a comment or rule so future reviews do not re-suggest it.
- Handoff: agreed design → skill
plan-execute (model-invocable execution workflow) for an implementation plan. New tests target the deepened module's interface; delete old shallow-module tests the new interface subsumes.
Dependency categories (deepening safety)
| Dependency |
Strategy |
| In-process |
Merge freely; test through the new interface |
| Local-substitutable (in-memory stand-in exists) |
Deepen; the seam stays internal |
| Remote but owned |
Port at the seam; production adapter + in-memory test adapter |
| True external (third-party) |
Injected port; mock adapter in tests |
Replace, don't layer: new tests assert observable outcomes at the interface; old shallow-module tests become waste once interface tests exist. A test that must change when the implementation changes is testing past the interface.
1---2name: improve-codebase-architecture3description: Find deepening opportunities — refactors that turn shallow modules into deep ones for testability and AI-navigability. Use when the user wants architecture assessment, refactoring candidates, or module consolidation.4---56# Improve Codebase Architecture78Surface architectural friction and propose **deepening** refactors. Vocabulary (module, interface, seam, adapter, depth, leverage, locality) is defined in [LANGUAGE.md](LANGUAGE.md). Use the **deletion test**: deleting a pass-through makes complexity vanish, while deleting a deep module pushes it into N callers. Treat a single production adapter as evidence that a seam may be hypothetical, not proof that it is unnecessary; keep it when it isolates real volatility, ownership, testability, or an architectural boundary.910## Process11121. **Context**: read the architecture rules in AGENTS.md and the target area's code. Use the project's own terminology from AGENTS.md, not generic glossaries.132. **Explore** — lightest mode that covers the request (direct inspection for a quick assessment; a read-only exploration subagent for a formal review). Note friction: bouncing between many small modules to follow one concept; interfaces nearly as complex as implementations; pure functions extracted for testability while the real bugs hide at call sites; layer divergence from the prescribed conventions; areas untestable through their current interface. Apply the deletion test to every shallow suspect.143. **Candidates**: quick assessment → concise findings in conversation. Formal review → `docs/architecture-reviews/YYYY-MM-DD-<topic>.md`, one section per candidate: Files, Problem (friction evidence), Solution (plain English), Benefits (locality / leverage / testability), recommendation strength (`Strong` / `Worth exploring` / `Speculative`), ending with a **Top recommendation**. Diagrams only when clearer than prose.154. **Grilling**: after the user picks a candidate, walk the design tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive. Use your harness's question tool for structured choices (pi `question`, Cursor `AskUserQuestion`); without one, ask in markdown. Do not design the full replacement interface until a candidate is selected. If the user rejects a candidate with a load-bearing reason, record it in a comment or rule so future reviews do not re-suggest it.165. **Handoff**: agreed design → skill `plan-execute` (model-invocable execution workflow) for an implementation plan. New tests target the deepened module's interface; delete old shallow-module tests the new interface subsumes.1718## Dependency categories (deepening safety)1920| Dependency | Strategy |21|------------|----------|22| In-process | Merge freely; test through the new interface |23| Local-substitutable (in-memory stand-in exists) | Deepen; the seam stays internal |24| Remote but owned | Port at the seam; production adapter + in-memory test adapter |25| True external (third-party) | Injected port; mock adapter in tests |2627Replace, don't layer: new tests assert observable outcomes at the interface; old shallow-module tests become waste once interface tests exist. A test that must change when the implementation changes is testing past the interface.
zhu327