improve-codebase-architecture

name	improve-codebase-architecture
description	Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Improve Codebase Architecture

This command is informed by the project's domain model and built on a shared design vocabulary:

• Run the codebase-design skill for the architecture 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"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
• The domain language in .zoo-flow/CONTEXT.md gives names to good seams; ADRs in .zoo-flow/docs/adr/ record decisions this command should not re-litigate.

Explore

1. Read relevant .zoo-flow/CONTEXT.md.
2. Read relevant ADRs.
3. Explore code organically.
4. Find friction:
   • Concept requires many-module bouncing.
   • Module shallow: interface ≈ implementation.
   • Pure fns exist only for tests; no locality.
   • Tight modules leak across seams.
   • Tests absent/hard through current interface.
5. Apply deletion test.
6. Keep candidates where deepening improves leverage/locality/testability.

Report

1. Write fresh .scratch/architecture-review-{timestamp}.html.
2. Use Tailwind CDN + Mermaid CDN.
3. Include candidate cards with before/after visuals.
4. Per candidate include: files/modules; problem; solution; locality/leverage/testing benefits; diagram; strength Strong/Worth exploring/Speculative; ADR conflict only if real.
5. Include Top recommendation.
6. Open file: Linux xdg-open {path}, macOS open {path}, Windows start {path}.
7. Tell user absolute path.
8. DO NOT propose interfaces yet.
9. Ask: Which of these would you like to explore?

Context economy

Before broad reads, locate relevant files/symbols with Glob, Grep, or targeted file reads.

Prefer targeted Read with line ranges or block reads once the relevant area is known.

Read full files only when structure, ordering, or surrounding context is required for correctness.

Do not re-read unchanged files; use prior findings unless the file changed.

Use searches to identify dependency/call patterns before reading full modules. Read full files only for top candidates.

After candidate chosen

• If module name introduces unresolved domain term, run the domain-modeling skill to update CONTEXT.md lazily.
• If term sharpened, run the domain-modeling skill to update CONTEXT.md immediately.
• Durable rejected reason useful later → offer an ADR.
• Interface options requested → run DESIGN-IT-TWICE.md from the codebase-design skill.

Complete

COMPLETION PROTOCOL: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.

• report file path (.scratch/architecture-review-{timestamp}.html)
• candidates found (count and titles)
• user selection (which candidate was chosen, if any)
• status (complete / blocked with reason)
• recommended next command (/zoo-refactor to implement the chosen candidate, or /zoo-feature if it requires PRD + issue slicing)