Improve Codebase Architecture

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.

• Module — anything with an interface and an implementation (function, class, package, slice).
• Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
• Implementation — the code inside.
• Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
• Seam — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
• Adapter — a concrete thing satisfying an interface at a seam.
• Leverage — what callers get from depth.
• Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles (see LANGUAGE.md for the full list):

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

This skill is informed by the project's domain model — CONTEXT.md and any docs/adr/. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See CONTEXT-FORMAT.md and ADR-FORMAT.md.

Process

1. Explore

Read existing documentation first:

• CONTEXT.md (or CONTEXT-MAP.md + each CONTEXT.md in a multi-context repo)
• Relevant ADRs in docs/adr/ (and any context-scoped docs/adr/ directories)

If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront.

Optional pre-pass — export inventory injection (mapper-supported projects only):

Before dispatching the Explore subagent, call extractSemanticSlices(filePath, { type: 'exports' }) from scripts/lib/language-mappers/index.mjs on known entry-point files (e.g., index.ts, src/index.ts, main export barrel). If the mapper returns a non-empty result, format the export list as structured context and inject it into the Explore subagent prompt. This gives the subagent an immediate map of the codebase's public surface without requiring it to grep manually.