From improve-code-architecture
Use during the IMPLEMENT step of a plan — pre-flight lens before writing a unit, post-diff audit before each commit. Guards five qualities Architectural alignment, Readability, Modularity, Reusability, Maintainability. Composes with test-driven-development, subagent-driven-development, executing-plans, verification-before-completion. Escalates to improve-code-architecture when structural problems exceed the current diff.
How this skill is triggered — by the user, by Claude, or both
Slash command
/improve-code-architecture:architecture-lensThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A lightweight lens you wear while implementing — **not** a workflow. Two fire points: a **pre-flight** lens before you write a unit, and a **post-diff audit** before you commit. Between the two, TDD drives the work. The lens is deliberately light so you actually use it on every task, instead of skipping it because "this one's small."
A lightweight lens you wear while implementing — not a workflow. Two fire points: a pre-flight lens before you write a unit, and a post-diff audit before you commit. Between the two, TDD drives the work. The lens is deliberately light so you actually use it on every task, instead of skipping it because "this one's small."
superpowers:brainstorming + superpowers:writing-plans.superpowers:test-driven-development — TDD drives the red-green-refactor; the lens bookends it.superpowers:subagent-driven-development or superpowers:executing-plans. One pre-flight per task, one post-diff audit per commit.improve-code-architecture instead.superpowers:brainstorming first — the lens is not a substitute for deciding what to build.improve-code-architectureDefault to this skill while implementing. improve-code-architecture is the escalation path, not the starting point.
improve-code-architecture is a restructuring workflow for codebases that already need surgery — ASK → DIAGNOSE → PLAN → CONFIRM → IMPLEMENT, with an 11-pattern reference. It is deliberately heavy.
architecture-lens is a per-task lens for preventing new rot while implementing. It is deliberately light.
If the lens surfaces a problem too deep to fix in the current diff, escalate to improve-code-architecture (see the Escalation section below). The two skills are designed to be used together: the lens catches drift; the workflow fixes accumulated drift.
| Quality | What it means |
|---|---|
| Architecturally Aligned | Fits the existing seams — layering, bounded contexts, composition root. Does not introduce a new shape incompatible with neighbors. |
| Readable | A stranger grasps intent in 60 seconds. Names reveal purpose. No cleverness for its own sake. |
| Modular | One responsibility per unit. Clean interface. Consumers do not read internals. |
| Reusable | Explicit contract. No hidden globals. No import-time side effects. Usable in a test or a second caller without rewriting. |
| Maintainable | Safe to change one concern without ripple. Edge cases documented where non-obvious. |
Testable is not on this list — superpowers:test-driven-development owns it. If you cannot unit-test a unit, the shape is wrong and that is a T1 finding.
Fires once, at the start of an implementation task, after the plan has been written and before any test or code is written. Walk the prompts once; skip ones that are trivially answered; stop and re-plan if any one blocks.
If any prompt reveals a problem the current plan did not anticipate, stop and raise it to the controller / user before writing code.
Fires before every commit, not just the final one. Walk the diff against these prompts. If any prompt surfaces an issue, fix it in place and re-walk; or escalate (see below).
any / untyped boundary I added to make the compiler stop complaining? Replace with a real contract or an explicit unknown + parse.improve-code-architectureEscalate when:
Handoff format. Stop implementation. Report to the controller / user with:
Then invoke improve-code-architecture.
improve-code-architecture; trim instead.| Excuse | Reality |
|---|---|
| "This is only one file, the lens is overkill" | One file is where the next file's duplication starts. Run the lens. |
| "T1 duplicates planning" | T1 is not re-planning; it translates the plan into local decisions at the moment of typing. |
| "T3 duplicates code review" | Code review is someone else catching what you missed. T3 is catching it yourself first. |
| "Five qualities are too many to remember" | They are a lens, not a checklist. Use them to see, not to score. |
| "I already escalated once this sprint, that's enough" | Escalation is per-symptom, not per-period. Escalate again if the criteria hit again. |
| "The plan says implement, not architect" | The plan says what. This skill guards how. Both fire. |
| "The code is only in a test, the lens doesn't apply" | Test code is code. Tests accumulate the same rot. Apply the lens. |
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub zachcr-ws/improve-code-architecture --plugin improve-code-architecture