design-architecture

Architecture Design Skill

Interactive workflow for translating product requirements into architecture through iterative decision-making.

File Locations

• Input: {{specs_dir}}/product_specs.md (PRD with EARS requirements)
• Output: {{specs_dir}}/architecture.md (architecture document with decisions)

Workflow Overview

1. Load Context - Read PRD and understand requirements
2. Identify Decisions - List architectural decisions to make
3. Iterate Decisions - For each decision: present options → discuss → decide
4. Document - Write architecture with full decision records

Design Principles

Anchor decisions on the named principles in ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — favor deep modules (simple interface, substantial functionality), minimize the surface Hyrum's Law will freeze into a contract, and design it twice before committing to a module boundary. When a decision passes the decision-record gate (in the principles file), record it using the Decision Record Format (ADR-lite) below. Sharpen the shared vocabulary with [[domain-modeling]].

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Opus (1M context). If effort is low or medium (i.e. below high), you MUST show the recommendation prompt — regardless of model. If you are not Opus (1M context), you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Cross-decision conflict detection and trade-off synthesis across NFRs benefit from deeper reasoning.\n\nTo switch: cancel, run `/model opus[1m]` and `/effort high`, then re-invoke this skill.",
    "header": "Recommended: Opus (1M context) at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}