design-architecture · diff
git:20260622.e142476 to git:20260622.3609064
11 added, 1 removed. Audit A to A.
---
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` or higher AND you are Opus (1M context).
If effort is 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)
- Each decision in the architecture doc follows this format:
+ **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