# Improve Architecture > Scan a codebase for deepening opportunities, present them on a live canvas, then delegate each approved refactor to a bounded sub-agent while the canvas tracks progress. - Skill: `firzus/improve-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add firzus/improve-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/firzus/improve-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Firzus (https://skillmd.com/u/firzus) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/firzus/improve-architecture --- # Improve Architecture Surface architectural friction, propose **deepening opportunities** — refactors that turn shallow modules into deep ones — and drive the approved ones to verified completion. The aim is testability and AI-navigability. The main thread never refactors: it scans, presents, dispatches, reviews, and keeps the canvas current. ## Vocabulary Invoke the `codebase-design` skill before scanning; it is required. It supplies 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 candidate and every work order; do not drift into "component", "service", "API", or "boundary". If the skill is not installed, stop and tell the user to install it first. ## 1. Explore **Scope before you scan: YAGNI.** Deepening pays off where change is coming, so weight recently changed code: - If the user named a direction (module, subsystem, pain point), take it. - Otherwise walk back a good stretch of `git log --oneline` to find hot spots — files and areas that keep coming up — and let those paths pull your attention first. Scattered changes with no hot spot: widen the net. Read the domain glossary (`CONTEXT.md`) and any ADRs in `docs/adr/` touching the area; ADRs record decisions this skill does not re-litigate. Spawn one sub-agent to walk the scoped area and report friction; explore organically rather than by rigid heuristics: - Where does understanding one concept require bouncing between many small modules? - Where are modules shallow? - Where were pure functions extracted just for testability while the real bugs hide in how they are called (no locality)? - Where do tightly-coupled modules leak across their seams? - Which parts are untested, or untestable through their current interface? Apply the deletion test to every suspect. The scan is complete when each candidate carries: involved files, the friction observed, the deletion-test result, and how tests would improve. ## 2. Present candidates on a canvas Invoke the `canvas` skill and render the review as a **living artifact** — one file, kept for the whole run, updated in place at every stage below. For each candidate, a card with: - **Files**: files and modules involved. - **Problem**: why the current architecture causes friction. - **Solution**: plain-English description of what would change. - **Benefits**: in terms of locality and leverage, and how tests improve. - **Before / after diagram**: side by side, illustrating the deepening. - **Recommendation strength**: `Strong`, `Worth exploring`, or `Speculative`. - **Status badge**: every candidate starts at `Proposed`. Use `CONTEXT.md` vocabulary for the domain: if it defines "Order", write "the Order intake module", not "the FooBarHandler". A candidate that contradicts an ADR appears only when the friction justifies reopening the decision, with a visible warning naming the ADR. End with a **Top recommendation** section: which candidate to tackle first and why. Then ask the user which candidates to run — one, several, or all. Do not start work without a pick. ## 3. Delegate each approved refactor For each approved candidate, write a **work order** and spawn a sub-agent to execute it. The work order is the sub-agent's whole world, so it carries: - **Scope**: the exact files and modules it may touch, and the statement that everything else is out of bounds. Behavior-preserving refactor only: no features, no drive-by cleanups, no dependency changes. - **Target shape**: the deepened interface — what callers will see, what moves behind the seam. - **Completion criterion**: the refactor is done when the full test suite passes and every caller compiles against the new interface. If the area has no tests, the sub-agent writes characterization tests against the current behavior first and keeps them green through the refactor. - **Report format**: files changed, interface before/after, test results, and any discovery that changed the plan. Independent candidates (disjoint files) may run as parallel sub-agents; any two candidates whose scopes overlap run sequentially. On dispatch, flip the candidate's canvas badge to `In progress`. ## 4. Review, verify, update the canvas When a sub-agent reports back, the main thread reviews before anything is marked done: - Read the diff. Confirm the scope held and the interface matches the work order's target shape. - Re-run the test suite from the main thread; the sub-agent's claim is not the evidence. - Passed: flip the badge to `Verified` and add a short outcome line to the card (what the interface became, test delta). Failed or scope drifted: flip to `Blocked` with the reason, and either re-dispatch with a corrected work order or surface the decision to the user. Side effects happen as results crystallize: - A deepened module named after a concept missing from `CONTEXT.md`: add the term (create the file lazily). - The user rejects a candidate for a load-bearing reason: offer an ADR so future reviews do not re-suggest it. Skip ephemeral reasons ("not worth it right now"). The run is complete when every approved candidate reads `Verified` or `Blocked` on the canvas, and the closing message links the canvas with a one-line summary per candidate.