| name | ds-architecture-plan |
| description | Analyze an existing codebase's architecture and produce a sequenced refactoring plan — assess module boundaries, dependency structure, and layering, then lay out ordered, risk-tagged steps. Language-agnostic. Reports a plan; changes nothing. |
| disable-model-invocation | true |
When invoked, audit the code against one question: is the architecture itself sound — and if not, what's the highest-leverage way to fix it, and in what order? Not file/function simplification (that's /ds-code-quality-review, which works within the architecture), not a map (that's /ds-zoom-out, which renders no judgment). This operates at the module / dependency / boundary altitude and is willing to propose big, sequenced structural change. Every finding is anchored to a concrete symptom in this codebase — generic best-practice with no local evidence is banned. Proposed refactors preserve observable behavior. Do not edit any files. Map first with /ds-zoom-out; turn the roadmap into tasks with /ds-roadmap; add characterization tests at a seam with /ds-test-mode or /ds-tdd-mode before a risky move. (To design a new architecture rather than review an existing one, use /ds-blueprint.)
Arguments
- Positional args are scope (directories, packages, the whole repo). No scope → the whole project (or the changed area, if you say so).
--max-level=<1|2|3> → clamp: suppress steps above that tier. --max-level=1 = safe, in-place wins only.--no-tiger → skip the Tiger Style / simplicity section.
Levels (risk / blast-radius)
- L1 — In-place, low-risk: move/rename, extract a module within existing boundaries, break a cycle with an interface, relocate misplaced logic. Individually shippable, behavior-preserving.
- L2 — Restructure within the current style: introduce a missing layer/boundary, consolidate duplicated subsystems, invert a dependency direction, split a god-package.
- L3 — Architecture-style change: monolith→modular, ports-and-adapters, service split, persistence-boundary change. Justify why L1/L2 won't suffice; give a migration path.
What to assess
Build the picture from evidence — the dependency/import graph, and (when available) which files change together in git history. Don't pattern-match a style onto the code.
1. Module boundaries & cohesion. God packages/files, grab-bag utils/common/helpers modules, low cohesion, unclear ownership of a concept.
2. Dependency structure. Import cycles, dependency-direction violations (a lower layer importing an upper one), hub modules everything depends on, unstable things depended upon by stable ones.
3. Layering & separation of concerns. Business logic in the wrong layer (in HTTP handlers, in the DB layer, in views); transport/persistence/domain bleeding into each other; missing seams.
4. Coupling & change amplification. Modules that always change together (shotgun surgery), a change that ripples across unrelated areas, hidden temporal coupling.
5. Duplicated subsystems. Parallel implementations of one concept, divergent copies, multiple sources of truth.
6. System-level abstraction leaks. Implementation details leaking through a public API; a boundary that doesn't actually encapsulate.
7. Architectural-style fit (L3). Does the style (or its absence) match the system's actual needs and scale? Only with strong evidence — this is where cargo-culting hides.
8. Module depth. Shallow modules whose interface is nearly as complex as what they hide (thin pass-throughs, wrappers that don't encapsulate); logic extracted only for testability where the real bugs live in how it's called, not in the unit. Diagnostic — the deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through; if it reappears across N callers, it was earning its keep.
Output
A sequenced refactoring roadmap.
First, a 3–5 line assessment: the current architecture (what style, what's healthy, what's not) and the 2–3 highest-leverage problems.
Then ordered steps, ranked by leverage (impact ÷ risk-effort) within ordering constraints. Respect --max-level. Each step:
- The move, in one line, with its level tag (L1/L2/L3).
- The symptom it fixes — anchored to evidence:
file:line, an import-cycle path, or the set of files that co-change. No symptom → not a step.
- Why now / what it unblocks — the ordering rationale.
- Blast radius & risk.
- Confidence:
Strong / Worth exploring / Speculative — how sure the problem is real and worth fixing, separate from the level's blast-radius risk.
- Safety: whether characterization tests are needed at the seam before the move (point to
/ds-test-mode or /ds-tdd-mode); confirm observable behavior is preserved.
Rules:
- No recommendation without a concrete symptom in this codebase. Generic best-practice with no local evidence is banned.
- Before proposing a change, check
.project/DECISIONS.md (if present) so you don't re-litigate a decision already settled there; if a proposal would override one, say so explicitly.
- Simplicity first — prefer the change that removes structure over the one that adds it; resist speculative generality.
- Weight impact by churn — a fix in a frequently-changed hot spot (
git log) pays off more than the same fix in stable code.
- Behavior-preserving: refactors keep observable behavior; recommend characterization tests before risky moves.
Safety > Performance > Developer Experience.- Each step independently shippable where possible.
- Change nothing. The output is the plan.
Tiger Style (skipped with --no-tiger)
- Simplicity first; the simplest structure that meets the requirements. No speculative generality.
- Explicit boundaries; separate control plane from data plane.
- Design for the actual scale, not an imagined one.
Safety > Performance > Developer Experience.
