improve-code-architecture

improve-code-architecture

A Claude Code / Cursor / Codex / Gemini plugin shipping two complementary skills for design discipline: a restructuring workflow for codebases that need surgery, and a lightweight lens you wear during routine implementation.

Core principle: Every extraction must answer what concern does this boundary hide? If you cannot name it, do not extract.

When to Use

Symptoms that mean this skill applies:

• One file / function does HTTP + DB + external API + business rules
• Changing one feature forces edits in many files (shotgun surgery)
• Tests require the real DB, real HTTP, or mocked SDKs
• The same shape repeats in slightly different forms (3+ times)
• You cannot describe a module's responsibility in one sentence
• Module-level singletons wired from process.env at import time
• any types at internal boundaries

When NOT to Use

• One-off scripts or throwaway tooling
• Cosmetic cleanup (renaming, formatting) — that's not architecture
• There are no tests AND no budget to add them — refactoring without tests is rewriting
• You cannot name a concrete pain point beyond "this feels messy"

Install

Claude Code

/plugin marketplace add https://github.com/zachcr-ws/improve-code-architecture
/plugin install improve-code-architecture

Cursor

Point Cursor at the cloned repo in Plugin settings. Manifest lives at .cursor-plugin/plugin.json.

git clone https://github.com/zachcr-ws/improve-code-architecture.git

Codex

See .codex/INSTALL.md — clone + symlink.

Gemini CLI

Install as a Gemini extension from this repo. Manifest: gemini-extension.json. Context is loaded from GEMINI.md.

OpenCode (manual)

No runtime plugin is provided. Copy skills/improve-code-architecture/ into your OpenCode skills directory:

git clone https://github.com/zachcr-ws/improve-code-architecture.git
cp -R improve-code-architecture/skills/improve-code-architecture ~/.config/opencode/skills/

(Adjust the destination path to match your OpenCode skills location.)

How It Works

The skill enforces a five-step workflow. Each step is mandatory; each scales with the size of the change.

1. ASK — 3–5 concrete questions about pain, scope, tests, constraints, and non-goals. No pattern talk until these are answered.
2. DIAGNOSE — rate each of the five qualities (Testable, Readable, Modular, Maintainable, Reusable) as OK / Weak / Broken with evidence. Name the 1–2 broken ones. Those drive the plan.
3. PLAN — current structure → target structure → patterns applied (each justified by "Pattern X hides concern Y so Z can change independently") → migration sequence → trade-offs → verification.
4. CONFIRM — present the plan, wait for explicit approval. No coding mid-discussion.
5. IMPLEMENT — tests first, one concern per commit, strangler not big-bang, behavior preservation over purity.

Skills in this repo

This plugin ships two complementary skills:

architecture-lens — start here

A lightweight pre-flight + post-diff lens you wear during routine implementation. Guards five qualities — Architectural alignment, Readability, Modularity, Reusability, Maintainability — and escalates to improve-code-architecture when a problem is too deep for the current diff. Use during the IMPLEMENT step of a plan, alongside TDD.

improve-code-architecture — escalation path

A restructuring workflow for codebases that already need surgery. Five-step workflow (ASK → DIAGNOSE → PLAN → CONFIRM → IMPLEMENT) with an 11-pattern reference. Use when you are deliberately refactoring.

Pattern Catalog

Eleven patterns, each with Problem → Solution → Code shape → Use when → Do NOT use when → Trade-offs. See skills/improve-code-architecture/patterns-reference.md.

• Dependency Injection — hides a concrete collaborator (DB, clock, HTTP)
• Strategy — hides a runtime choice of algorithm
• Repository + Unit of Work — hides persistence / query details
• Ports & Adapters (Hexagonal) — isolates domain from all I/O
• Facade — hides a complex subsystem behind one verb
• Decorator — hides cross-cutting behavior (logging, retry, auth)
• Factory — hides construction complexity and wiring
• Command — reifies an operation (undo, queue, audit)
• Observer / Domain Events — reacts to a thing that happened
• Adapter — integrates an incompatible interface
• Template Method — a fixed workflow with swappable steps

Contributing