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
  }]
}

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:

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:

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

{
  "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:

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