| name | selecting-implementation-architecture |
| description | Use before writing an implementation plan — recommend lightweight vs heavyweight (hex-infra, DDD depth) from signals, confirm with the user, and record the decision for execution |
Selecting implementation architecture
Overview
Before task breakdown in superpowers:writing-plans, choose how much structure the implementation needs. Recommend based on heuristics, then ask the user to confirm or override. Record the final choice in the plan **Architecture:** line so superpowers:executing-plans can follow it.
Announce at start: "I'm using selecting-implementation-architecture to choose an implementation approach."
Options
| ID | Approach | Primary skill |
|---|
| A | Lightweight — minimal ceremony, still modular and domain-centered | superpowers:lightweight-software-principles |
| B | Heavyweight — full hex boundaries, ports/adapters, DDD-informed domain | superpowers:hex-infra (see references/ddd-expert-knowledge-base.md in that skill for deep DDD) |
TDD is always on: Regardless of A or B, execution uses superpowers:test-driven-development.
Step 1: Gather signals
From the spec or conversation, score mentally (no spreadsheet required):
- Domain complexity — New vocabulary, many rules, aggregates, or cross-cutting policies?
- Integration surface — How many external systems (DB, HTTP APIs, queues, payments)?
- Change pressure — Will this area churn or need substitution/mocking?
- Team / codebase — Is hex layering already present and consistent?
Heuristic:
- Favor B (heavyweight) when: multiple integrations, high domain complexity, or need clear test seams and long-lived boundaries.
- Favor A (lightweight) when: small change, few rules, one integration, or codebase has no hex precedent and migration would be out of scope.
Step 2: State recommendation
Present exactly:
Recommendation: <A Lightweight | B Heavyweight>
Reasons (2-4 bullets):
- ...
Skills if confirmed:
- Architecture: <lightweight-software-principles | hex-infra>
- Testing: test-driven-development (always)
Step 3: Ask user to confirm or override
Do you accept this recommendation?
1. Yes — use <A | B>
2. Override — I want <A | B> instead
Reply with 1 or 2 (and if 2, specify A or B).
Wait for explicit answer. If the user picks override, adopt their choice without debate unless it violates a stated repo policy.
Step 4: Emit plan header fragment
After confirmation, output a single line the author must paste under the plan header **Architecture:** (or merge into existing architecture text):
**Architecture:** Approach=<Lightweight|Heavyweight>; skills=`superpowers:<lightweight-software-principles|hex-infra>` + `superpowers:test-driven-development`. Rationale: <one short sentence>.
Red flags
- Skipping user confirmation when they are available
- Choosing heavyweight for trivial edits without reason
- Choosing lightweight when multiple integrations and unclear domain boundaries exist
- Dropping TDD because the approach is "lightweight"
Integration
Called by:
- writing-plans — Required before task decomposition when the plan will drive implementation.
Pairs with:
- lightweight-software-principles — Option A
- hex-infra — Option B (includes DDD knowledge base under
references/)
