{
  "markdown": "# improve-code-architecture\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Version](https://img.shields.io/badge/version-0.2.1-blue.svg)](./CHANGELOG.md)\n[![Skill](https://img.shields.io/badge/type-skill-purple.svg)](./skills/improve-code-architecture/SKILL.md)\n\nA 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.\n\n> **Core principle:** Every extraction must answer _what concern does this boundary hide?_ If you cannot name it, do not extract.\n\n## When to Use\n\nSymptoms that mean this skill applies:\n\n- One file / function does HTTP + DB + external API + business rules\n- Changing one feature forces edits in many files (shotgun surgery)\n- Tests require the real DB, real HTTP, or mocked SDKs\n- The same shape repeats in slightly different forms (3+ times)\n- You cannot describe a module's responsibility in one sentence\n- Module-level singletons wired from `process.env` at import time\n- `any` types at internal boundaries\n\n## When NOT to Use\n\n- One-off scripts or throwaway tooling\n- Cosmetic cleanup (renaming, formatting) — that's not architecture\n- There are no tests AND no budget to add them — refactoring without tests is rewriting\n- You cannot name a concrete pain point beyond \"this feels messy\"\n\n## Install\n\n### Claude Code\n\n```bash\n/plugin marketplace add https://github.com/zachcr-ws/improve-code-architecture\n/plugin install improve-code-architecture\n```\n\n### Cursor\n\nPoint Cursor at the cloned repo in Plugin settings. Manifest lives at `.cursor-plugin/plugin.json`.\n\n```bash\ngit clone https://github.com/zachcr-ws/improve-code-architecture.git\n```\n\n### Codex\n\nSee [`.codex/INSTALL.md`](./.codex/INSTALL.md) — clone + symlink.\n\n### Gemini CLI\n\nInstall as a Gemini extension from this repo. Manifest: `gemini-extension.json`. Context is loaded from `GEMINI.md`.\n\n### OpenCode (manual)\n\nNo runtime plugin is provided. Copy `skills/improve-code-architecture/` into your OpenCode skills directory:\n\n```bash\ngit clone https://github.com/zachcr-ws/improve-code-architecture.git\ncp -R improve-code-architecture/skills/improve-code-architecture ~/.config/opencode/skills/\n```\n\n(Adjust the destination path to match your OpenCode skills location.)\n\n## How It Works\n\nThe skill enforces a five-step workflow. Each step is mandatory; each scales with the size of the change.\n\n1. **ASK** — 3–5 concrete questions about pain, scope, tests, constraints, and non-goals. No pattern talk until these are answered.\n2. **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.\n3. **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.\n4. **CONFIRM** — present the plan, wait for explicit approval. No coding mid-discussion.\n5. **IMPLEMENT** — tests first, one concern per commit, strangler not big-bang, behavior preservation over purity.\n\n## Skills in this repo\n\nThis plugin ships two complementary skills:\n\n### [`architecture-lens`](./skills/architecture-lens/SKILL.md) — start here\n\nA 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.\n\n### [`improve-code-architecture`](./skills/improve-code-architecture/SKILL.md) — escalation path\n\nA 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.\n\n## Pattern Catalog\n\nEleven patterns, each with Problem → Solution → Code shape → Use when → Do NOT use when → Trade-offs. See [`skills/improve-code-architecture/patterns-reference.md`](./skills/improve-code-architecture/patterns-reference.md).\n\n- **Dependency Injection** — hides a concrete collaborator (DB, clock, HTTP)\n- **Strategy** — hides a runtime choice of algorithm\n- **Repository + Unit of Work** — hides persistence / query details\n- **Ports & Adapters (Hexagonal)** — isolates domain from all I/O\n- **Facade** — hides a complex subsystem behind one verb\n- **Decorator** — hides cross-cutting behavior (logging, retry, auth)\n- **Factory** — hides construction complexity and wiring\n- **Command** — reifies an operation (undo, queue, audit)\n- **Observer / Domain Events** — reacts to a thing that happened\n- **Adapter** — integrates an incompatible interface\n- **Template Method** — a fixed workflow with swappable steps\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). New patterns must pass the _\"hides concern Y\"_ template test and include Problem / Solution / Code shape / Use when / Do NOT use when / Trade-offs.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 5190,
  "sha": "245fd2f75d1617487510069ec51a683ec23b4a8b06484418f328b604f70b00c2",
  "repo_slug": "zachcr-ws/improve-code-architecture",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_zachcr_ws_improve_code_architecture_91e44429/readme"
}