design-architecture

---
name: design-architecture
description: This skill should be used when the user asks to design system architecture, make architectural decisions, or translate PRD into technical design
argument-hint: "[feature-name]"
---

# 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`:

```json
{
  "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
  }]
}
```

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

## Step 0: Resolve Project Context

**Before anything else, resolve the project context:**

1. **Monorepo check:** Does `.groundwork.yml` exist at the repo root?
   - If yes → Is `{{project_name}}` non-empty?
     - If empty → Invoke `Skill(skill="groundwork:select-project")` to select a project, then restart this skill.
     - If set → Project is `{{project_name}}`, specs at `{{specs_dir}}/`.
   - If no → Continue to item 3.
2. **CWD mismatch check (monorepo only):**
   - Skip if not in monorepo mode or if the project was just selected in item 1 above.
   - If CWD is the repo root → fine, proceed.
   - Check which project's path CWD falls inside (compare against all projects in `.groundwork.yml`).
   - If CWD is inside the selected project's path → fine, proceed.
   - If CWD is inside a different project's path → warn via `AskUserQuestion`:
     > "You're working from `<cwd>` (inside **[cwd-project]**), but the selected Groundwork project is **[selected-project]** (`[selected-project-path]/`). What would you like to do?"
     > - "Switch to [cwd-project]"
     > - "Stay with [selected-project]"
     If the user switches, invoke `Skill(skill="groundwork:select-project")`.
   - If CWD doesn't match any project → proceed without warning (shared directory).
3. **Check `{{specs_dir}}/`:** Does a specs directory exist?
   - If yes → Single-project repo, proceed normally.
   - If no → Ask the user: "Is this a single-project repo or a monorepo with multiple projects?"
     - **Single project** → Proceed normally (specs will be created at `{{specs_dir}}/`)
     - **Monorepo** → Invoke `Skill(skill="groundwork:setup-repo")` to create `.groundwork.yml`, then continue.

## Step 1: Load Context

Read the product specs (may be single file or directory) and extract:
- Non-functional requirements (latency, scale, security, compliance)
- Feature list and EARS requirements
- Implicit constraints (budget, team size, timeline if mentioned)

**Detection:** Check for `{{specs_dir}}/product_specs.md` first (single file), then `{{specs_dir}}/product_specs/` directory. When reading a directory, aggregate all `.md` files recursively with `_index.md` first, then numerically-prefixed files, then alphabetically.

If PRD doesn't exist, prompt user to run `/groundwork:design-product` first.

Summarize key architectural drivers:
> "Based on your PRD, the key architectural drivers are:
> - [Driver 1 from NFRs]
> - [Driver 2 from features]
> I'll need to make decisions about [list 3-5 major areas]. Let's start with [most foundational one]."

## Step 2: Identify Decision Areas

Common architectural decision categories:

| Category | Example Decisions |
|----------|-------------------|
| **Compute** | Serverless vs containers vs VMs, orchestration |
| **Data** | Database type, multi-tenancy strategy, caching |
| **API** | REST vs GraphQL, gateway pattern, versioning |
| **Frontend** | SPA vs SSR, framework choice, state management |
| **Auth** | Identity provider, token strategy, authorization model |
| **Integration** | Sync vs async, message queues, event sourcing |
| **Infrastructure** | Cloud provider, IaC approach, environments |
| **Observability** | Logging, metrics, tracing, alerting |
| **Security** | Encryption, network isolation, secrets management |
| **Cost** | Pricing model alignment, reserved vs on-demand |

Prioritize decisions by dependency (foundational first).

## Step 3: Research Technologies

Before presenting decision options, gather research on relevant technologies.

**For each decision area identified:**

1. Identify the primary technologies/frameworks being considered
2. Invoke the researcher agent:
   ```
   Agent(
     subagent_type="groundwork:researcher:researcher",
     prompt="Research Topic: [technology]
     Research Questions:
     - What is the stable vs latest version?
     - What is the recommended ecosystem for [use case]?
     - What are common architectural pitfalls?
     - What has been deprecated recently?

     Project Context: [from PRD]
     Constraints: [from user/PRD]"
   )
   ```

3. Use research findings to:
   - Inform pros/cons in option presentations
   - Add version recommendations to options
   - Include ecosystem compatibility in trade-offs
   - Surface pitfalls in cons sections
   - Reference sources for credibility

**Research Integration:**
When presenting options in Step 4, incorporate research findings:
- Add "(stable: X.Y, latest: A.B)" to technology names
- Include ecosystem compatibility in pros/cons
- Note known pitfalls in cons sections
- Cite sources when making specific claims

## Step 4: Iterate on Each Decision

For each decision point, present **2-4 options** using this format:

```markdown
## Decision: [Decision Name]

**Context:** [Why this decision matters, link to PRD requirements]

### Option A: [Name]
**Description:** [1-2 sentences]
**Pros:**
- [Pro 1, ideally linked to PRD requirement]
- [Pro 2]
**Cons:**
- [Con 1, note if it conflicts with PRD requirement]
- [Con 2]
**Cost implications:** [Rough estimate if relevant]

### Option B: [Name]
[Same structure]

### Option C: [Name] (if applicable)
[Same structure]

**My recommendation:** [Option X] because [reasoning tied to PRD].

What are your thoughts? Any constraints I should know about?
```

**Presentation style:**
- Present one decision at a time, wait for resolution before moving on
- For complex options, break explanation into digestible chunks (200-300 words)
- Prefer multiple-choice follow-up questions when gathering constraints

### Exploratory Questions

When presenting options, ask questions to surface hidden constraints:
- "What's your team's experience with [technology X vs Y]?"
- "Are there constraints I should know about? (existing systems, team skills, budget, timeline)"
- "What would you regret in 2 years if we chose wrong here?"
- "Is there organizational momentum toward any particular approach?"
- "What's the cost of changing this decision later if it proves wrong?"

### Decision Conflict Detection

Before recording a decision, check for conflicts with earlier decisions:

**Check against existing decisions:**
- Does this decision contradict or undermine a previous DR?
- Are we choosing a technology incompatible with earlier choices?
- Does this create inconsistency in the architecture?

**If conflict detected:**
> "This decision may conflict with DR-NNN:
> - DR-NNN chose [X] for [reason]
> - This decision would require [Y], which is incompatible because [explanation]
>
> Options:
> 1. Proceed with new decision and update DR-NNN
> 2. Modify this decision to align with DR-NNN
> 3. Accept both and document the exception
>
> Which approach?"

**After user input:**
- If user agrees: Record decision and move to next
- If user has concerns: Discuss, possibly add new options
- If user wants to defer: Note as open question, continue
- If conflict identified: Resolve before proceeding

### YAGNI for Architecture

- Challenge decisions that add complexity "for future flexibility"
- Prefer simple solutions that can evolve over pre-designed extensibility
- When in doubt, choose the option with fewer moving parts
- Ask: "What's the cost of adding this later vs. building it now?"

## Step 4.5: Design It Twice (module interfaces)

Steps 3–4 chose *what to build with*. For any non-trivial new module, service boundary, or public API in this design, also decide *how the interface is shaped* — and your first shape is rarely the best.

Invoke `Skill(skill="groundwork:design-it-twice")`: frame the problem, generate 2–3 divergent designs (parallel `Agent` fan-out when available, sequential otherwise — no agent teams needed), compare them on depth / locality / seam, and carry an opinionated recommendation into the decision records. Skip for designs with no non-trivial new interface.

## Step 5: Document Architecture

When all major decisions are made, create the architecture document using template in `${CLAUDE_PLUGIN_ROOT}/references/architecture/architecture-template.md`.

**Output location:** `{{specs_dir}}/architecture.md` (single file by default)

**Critical:** Include ALL decision records with discarded options and reasoning. This is essential for future maintainers to understand *why* choices were made.

Present the complete document for review before writing.

### Architecture Validation

Before writing the architecture document, validate it against the PRD:

1. Invoke the prd-architecture-checker agent with draft architecture content and PRD content:
   ```
   Agent(
     subagent_type="groundwork:prd-architecture-checker:prd-architecture-checker",
     prompt="Validate architecture against PRD

     Architecture Draft: [full draft content]

     PRD Content: [product_specs.md content]

     Feature List: [extracted features]

     NFR List: [extracted NFRs]

     Constraints: [budget, timeline, team from PRD]"
   )
   ```

2. If verdict is `request-changes`:
   - Present findings to user with specific gaps identified
   - Address critical and major findings by updating the architecture
   - Re-validate until approved

3. If verdict is `approve`:
   - Proceed to write `{{specs_dir}}/architecture.md`
   - Note any minor findings as suggestions for documentation improvement

## Step 5a: Auto-Split Check

**Skip this step if the architecture doc is already in directory mode.**

After writing the architecture document, check whether it should be split:

1. Count lines: `wc -l {{specs_dir}}/architecture.md`
2. Count decision records: number of `### DR-\d+` headings in the file

If **lines >= 500** OR **decision records >= 10**:
- Invoke `Skill(skill="groundwork:split-architecture")` — this runs automatically with no user input needed.
- After the split completes, note in your confirmation: "The architecture doc has been split into directory format at `{{specs_dir}}/architecture/` for easier navigation."

If neither threshold is crossed, continue silently.

## Step 6: Suggest Next Step

After successfully updating the architecture document, ask what should be the next workflow step:

```json
{
  "questions": [{
    "question": "What would you like to do next?",
    "header": "Next step",
    "options": [
      {
        "label": "Design UX",
        "description": "Plan user experience designs and flows"
      },
      {
        "label": "Create tasks",
        "description": "Break product/architecture/UX down into tasks"
      }
    ],
    "multiSelect": false
  }]
}
```

**Handle the response:**

- **Design UX**: Run `/groundwork:ux-design` to create UX designs
- **Create tasks**: Run `/groundwork:create-tasks` to create a list of executable tasks

## Decision Record Format (ADR-lite)

**Record a decision only when it passes the decision-record gate** (`${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md`): hard to reverse, surprising without context, and a real trade-off — otherwise just implement it. Each qualifying decision is captured inline in the architecture doc (no separate ADR files — `housekeeper` keeps these current) using this format:

```markdown
### DR-NNN: [Decision Title]

**Status:** Accepted | Superseded by DR-XXX | Deprecated
**Date:** YYYY-MM-DD
**Context:** [Why this decision was needed]

**Options Considered:**
1. **[Option A]** - [Brief description]
   - Pros: [list]
   - Cons: [list]
2. **[Option B]** - [Brief description]
   - Pros: [list]
   - Cons: [list]

**Decision:** [Chosen option]

**Rationale:** [Why this option was selected, referencing PRD requirements]

**Consequences:**
- [Implication 1]
- [Implication 2]
```

## Clarifying Questions by Category

### Compute & Scaling
- What's your expected load profile? (steady, spiky, predictable growth)
- Any constraints on cold start latency?
- Team's experience with containers/K8s vs serverless?

### Data
- What consistency guarantees do you need? (eventual OK vs strong)
- Expected data volume and growth rate?
- Any existing database expertise on the team?

### Cost
- Is there a monthly infrastructure budget target?
- Preference for predictable costs vs pay-per-use?
- Any existing cloud commitments or credits?

### Team & Operations
- Team size and composition (backend/frontend/devops)?
- On-call expectations?
- Deployment frequency target?

## Reference Files

- `${CLAUDE_PLUGIN_ROOT}/references/architecture/architecture-template.md` - Template for architecture document
- `${CLAUDE_PLUGIN_ROOT}/references/architecture/decision-examples.md` - Example decision records from real projects