selecting-implementation-architecture

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/)