Improve Codebase Architecture

What it does

The workflow scopes the survey before scanning, giving weight to recent change hotspots or an explicitly named pain point. It reads the domain glossary and existing decisions, then looks for concrete navigation, coupling and testability friction. Candidates are presented in a self-contained HTML report with before-and-after diagrams, expected benefits and recommendation strength. It stops short of prescribing interfaces until the user picks a candidate. Companion skills supply design vocabulary, interviewing and domain documentation.

When to use it

• A frequently changed checkout area requires edits in many small files.
• Developers cannot test a business outcome without knowing several private helpers.
• A team needs a ranked architectural discussion before authorizing a refactor.

Step-by-step workflow

1. Choose the survey scope from the user’s pain point or recent commit hotspots.
2. Read the relevant glossary and ADRs, then explore concrete coupling and testing friction.
3. Prepare a temporary HTML report with files, problems, proposed deepening and before-and-after visuals.
4. Ask the user which candidate deserves exploration instead of changing architecture automatically.
5. Explore that candidate’s constraints and interfaces, recording agreed terminology and durable trade-offs.

Example request

Use improve-codebase-architecture on the frequently changed order-intake area. Read recent commits, GLOSSARY.md and relevant ADRs. Identify up to three concrete opportunities where behavior is scattered or tests cross the wrong seam. Produce a visual report with evidence, before-and-after diagrams, recommendation strength and the top candidate. Explain any conflict with a recorded decision. Do not refactor until we choose a candidate.

Worked example

A survey may find validation rules split between a web handler, importer and three wrappers. A useful report shows which callers repeat decisions and where a deeper intake module could concentrate them. A second candidate may be speculative because its files rarely change. The recommendation should explain that difference rather than ranking by file count. If an ADR intentionally separates those paths, the report must explain the observed friction that warrants reopening it.

What you get

A visual architecture opportunity report and a focused follow-up discussion for one selected candidate.

How to evaluate the result

• Tie each candidate to actual files and observed maintenance or testing friction.
• Distinguish strong evidence from speculative opportunities.
• Verify the report precedes interface implementation and identifies meaningful ADR conflicts.

What you need

Source code, Git history, project glossary and decision records. Full execution uses subagents, a browser and companion design/interview skills; the default report uses CDN assets.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

This surveys opportunities rather than repairing an entire legacy system. Attractive diagrams are not evidence of improvement. The source report loads Tailwind and Mermaid from CDNs, which matters for offline or confidential environments. Existing ADRs and user selection constrain subsequent work.

Related workflows

• Use codebase-design to compare interfaces for the selected candidate.
• Use domain-modeling when a proposed module exposes an unresolved business concept.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license