design-architecture
This skill should be used when the user asks to design system architecture, make architectural decisions, or translate PRD into technical design
etr · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add etr/groundwork --skill design-architectureAbout this skill
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
- Load Context - Read PRD and understand requirements
- Identify Decisions - List architectural decisions to make
- Iterate Decisions - For each decision: present options → discuss → decide
- 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:
- Monorepo check: Does
.groundwork.ymlexist 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 empty → Invoke
- If no → Continue to item 3.
- If yes → Is
- 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).
- 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.
- Single project → Proceed normally (specs will be created at
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 rele
Read the complete source ↗