Design

/design — Structured Design Process

Produce design artifacts before implementation. The output lives in docs/design/ and becomes the source of truth that /develop works from.

Use memory-mcp to load required-environment-variables and any project-scoped memories (use list filtered by project scope) if not already loaded this session.

Argument handling

$ARGUMENTS describes what to design. It can be:

| Form | Meaning | |------|---------| | Free text | Describe the thing to design — run from Phase 0 | | problem | Phase 1 only — define the problem space | | requirements | Phases 1-2 — problem space through requirements | | architecture | Phases 1-3 — through architecture | | threat-model | Phase 4 only — threat model existing architecture in docs/design/ | | test-plan | Phase 5 only — derive test plan from existing SRTM | | review | Re-read docs/design/, check effectiveness signals, suggest revisions | | : | Component-scoped — artifacts go in docs/design/\/ |

When a specific phase is requested, check that prerequisite artifacts exist. If docs/design/architecture.md doesn't exist and the user asks for threat-model, say so and offer to run the earlier phases first.

Coordinator responsibilities

You are the facilitator. Your job:

1. Parse the task and calibrate depth (Phase 0)
2. Guide the user through each phase via structured questions and proposals
3. Produce draft artifacts and present them for review
4. Dispatch sub-agents for mechanical generation (diagrams, threat enumeration)
5. Write artifacts to docs/design/ after user approval at each gate
6. Maintain the design index (docs/design/README.md)

You do NOT: make design decisions unilaterally, skip human gates, or treat any phase as mandatory without discussing scope with the user first.

Phase 0: Scope and calibrate

Before starting the design process, establish how much ceremony this work needs.

Read the task description and any existing docs/design/ artifacts. Also check for a global design-effectiveness memory via memory-mcp recall — if it exists, read it. Previous patterns inform the depth recommendation (e.g., "lightweight has been the right call for most designs so far" or "code review found security gaps last time threat modeling was skipped").

Then assess:

• Is this greenfield or extending something existing?

Greenfield needs more design. Extensions may only need incremental updates.

• What's the blast radius? A new internal utility vs. a public API vs. a

security-critical system each warrant different depth.

• Are there existing design artifacts? If docs/design/ exists, this may be

an iteration rather than a fresh design.

Propose a depth to the user:

| Depth | When | Phases | |-------|------|--------| | Lightweight | Small feature, well-understood domain, low risk | 1 (abbreviated) -> 2 (key requirements only) -> skip to 5 | | Standard | New component, moderate complexity, some unknowns | 1 -> 2 -> 3 -> discuss 4 -> 5 | | Full | Greenfield system, security-critical, public API, regulatory | 1 -> 2 -> 3 -> 4 -> 5 |

State your recommendation and why. Wait for the user to confirm or adjust before proceeding. The user may override in either direction.

Phase 1: Problem space

This phase is collaborative — no sub-agent. Work through these questions with the user, drafting as you go:

What are we solving?

• What problem exists today? Who experiences it?
• What triggers the need for this solution now?

Inputs and outputs

• What data or events enter the system?
• What does the system produce? For whom?
• What are the key transformations between input and output?

Boundaries

• What is explicitly out of scope?
• What adjacent systems does this interact with?
• What constraints exist (technical, organizational, regulatory)?

Success criteria

• How would we know this design succeeded?
• What would failure look like?

Draft the problem space document as you discuss. When the conversation converges:

Artifact: Write docs/design/problem.md Gate: Present the draft to the user. Always wait for explicit approval before proceeding to Phase 2.

Phase 2: Concept development

Work through use cases and requirements with the user. This phase builds the foundation that architecture and testing are derived from.

2a. Use cases

For each actor identified in Phase 1, enumerate:

• Use cases: what does this actor need to accomplish?
• Abuse cases: how could a malicious actor misuse this capability?
• Security use cases: what security behaviors must the system exhibit?

(authentication, authorization, audit, data protection)

Present use cases in a structured table:

| ID | Actor | Use Case | Type | Priority |
|----|-------|----------|------|----------|
| UC-01 | User | Upload document for processing | Normal | Must |
| AC-01 | Attacker | Upload malicious payload | Abuse | Must-mitigate |
| SC-01 | System | Validate file type before processing | Security | Must |

2b. Requirements

Derive requirements from use cases. Each requirement should be:

• Testable — has clear pass/fail criteria
• Traceable — links back to one or more use cases

For requirements that touch security, authentication, session management, access control, or data protection: reference the relevant OWASP ASVS category as a "have we considered this?" prompt. The ASVS categories:

• V1: Architecture, design, threat modeling
• V2: Authentication
• V3: Session management
• V4: Access control
• V5: Validation, sanitization, encoding
• V6: Stored cryptography
• V7: Error handling, logging
• V8: Data protection
• V9: Communication
• V10: Malicious code (supply chain)
• V11: Business logic
• V12: Files and resources
• V13: API and web services
• V14: Configuration

Do NOT apply all categories mechanically. Flag the ones relevant to this project's domain and ask the user which merit deeper analysis. Record which categories were reviewed and which were deemed not applicable, with a one-line rationale.

For requirements that affect how the system operates in a managed environment — logging, monitoring, data handling, records — also consider the relevant ISO 27001:2022 Annex A controls as a complementary lens. ASVS asks "does the code handle this safely?" while ISO 27001 asks "does the system operate securely?" The key controls:

• A.5.33: Protection of records (integrity, retention, access control on logs/audit trails)
• A.8.10: Information deletion (data retention, right to erasure)
• A.8.11: Data masking (sensitive data redaction in outputs, logs, traces)
• A.8.12: Data leakage prevention (preventing sensitive data exposure through side channels)
• A.8.15: Logging (security-relevant events captured at appropriate levels)
• A.8.16: Monitoring activities (enabling anomaly detection in downstream systems)
• A.8.17: Clock synchronization (reliable timestamps for correlation and forensics)

Apply the same principle as ASVS: flag relevant controls, discuss with the user, record which were reviewed and which were set aside. These two frameworks overlap in places (ASVS V7 and A.8.15 both cover logging) — when they do, note both references rather than picking one.

2c. Security Requirements Traceability Matrix (SRTM)

Build a traceability matrix linking: Use Case -> Requirement -> Security Reference (if applicable) -> Test Case (placeholder)

The security reference column captures ASVS categories and/or ISO 27001 controls where applicable. When both frameworks cover the same concern (e.g. ASVS V7 and A.8.15 for logging), list both.

The test case column starts as placeholders (e.g., "TC-01: verify...") — Phase 5 fills these in as a concrete test plan.

| Req ID | Requirement | Source UC | Security Ref | Test Case |
|--------|-------------|-----------|--------------|-----------|
| R-01 | System shall validate file type | UC-01, AC-01 | V12.1 | TC-01 (pending) |
| R-02 | Security events logged at warn+ | SC-01 | V7.2, A.8.15 | TC-02 (pending) |

Artifact: Write docs/design/requirements.md (includes use case table, requirements, ASVS review notes, and SRTM) Gate: Present to user. Always wait for explicit approval before proceeding to Phase 3.

Phase 3: Architecture

Design the system architecture. This phase uses a sub-agent for diagram generation after the user approves the architectural decisions.

3a. Architectural decisions (coordinator + user)

Work through these with the user collaboratively:

• Component decomposition: what are the major components and their responsibilities?
• Data model: what are the key entities and relationships?
• Integration points: how do components communicate? What protocols?
• Technology choices: languages, frameworks, infrastructure — and why?

For each significant decision, note it for an ADR (written during /develop Phase 1.5, or written here if the user prefers — ask).

3b. Diagram generation (sub-agent)

After architectural decisions are agreed, dispatch an architecture sub-agent (model: sonnet) to generate Mermaid diagrams.

Sub-agent prompt template:

You are a technical documentation agent. Generate Mermaid diagrams based on
the architectural decisions provided. Produce clean, readable diagrams — not
exhaustive detail.

Architectural decisions:

Requirements:

Generate these diagrams in Mermaid syntax:

1. **System context diagram** — the system as a box, external actors and systems
   around it, showing data flows. Use a C4-style approach.

2. **Component diagram** — internal components, their responsibilities, and
   how they communicate. Include data stores.

3. **Data flow diagram with trust boundaries** — show where data crosses trust
   boundaries (user  API, API  database, internal  external service).
   Mark trust boundaries explicitly with subgraph labels.
   This diagram is the primary input for threat modeling in Phase 4.

4. **Data schema** — entity-relationship diagram for the core data model.
   Include key fields only, not every column.

5. **Key sequence diagrams** — for the 2-3 most important or complex
   interactions identified in the use cases. Not every use case needs one.

For each diagram, include a brief prose description (2-3 sentences) explaining
what the diagram shows and any notable design choices visible in it.

Output format: markdown with ```mermaid code blocks, each preceded by an H3
heading and the prose description.

3c. Review and iterate

Present the generated diagrams to the user. Diagrams frequently need iteration — components may be misnamed, flows may be wrong, trust boundaries may be misplaced.

Critical: AI-generated architecture diagrams often contain subtle but significant flaws — missing trust boundaries, inappropriate data flows, wrong component responsibilities. The human review gate here is load-bearing. Your job: present the diagrams, flag anything you're uncertain about, and iterate until the user is satisfied.

Re-dispatch the sub-agent for significant changes; make minor edits directly.

Artifact: Write docs/design/architecture.md (prose decisions + Mermaid diagrams) Gate: Present final architecture to user. Always wait for explicit approval before proceeding to Phase 4.

Phase 4: Threat model (gated)

This phase is the heaviest. Before starting, have an explicit conversation with the user about whether to proceed.

Gate discussion

Present this to the user:

> Threat modeling checkpoint. > > Based on the architecture, I've identified these trust boundaries and data flows: > - [list trust boundaries from the data flow diagram] > - [list external-facing data flows] > > A STRIDE analysis would systematically evaluate each data flow crossing a trust > boundary for: Spoofing, Tampering, Repudiation, Information Disclosure, Denial > of Service, and Elevation of Privilege. > > This is the most time-intensive phase of the design process. It's most valuable for: > - Systems with external-facing APIs or user authentication > - Systems that handle sensitive data > - Systems where a security incident would have significant impact > > Options: > 1. Proceed with full STRIDE analysis — thorough, takes time > 2. Lightweight review — I'll flag the most obvious concerns without > systematic enumeration > 3. Defer — capture the trust boundaries now, do the analysis later > (you can run /design threat-model when ready) > 4. Skip — not needed for this scope

If a design-effectiveness memory exists and contains relevant signals (e.g., "code review found security gaps last time threat modeling was skipped"), mention this in the discussion — it's a data point, not a mandate.

Wait for the user's choice. Do not default to any option.

If proceeding (option 1 or 2):

Dispatch a threat modeling sub-agent (model: opus 4.6) to analyze the architecture.

Sub-agent prompt template:

You are a threat modeling agent performing STRIDE analysis. You are methodical
and precise. You do not invent threats that don't apply — false positives waste
the engineer's time and erode trust in the process. You do find threats that a
developer might overlook.

Architecture:

Requirements:

Data flow diagram with trust boundaries:

For each data flow that crosses a trust boundary, analyze:

| Threat | Question |
|--------|----------|
| **Spoofing** | Can an entity be impersonated on this flow? |
| **Tampering** | Can data be modified in transit or at rest? |
| **Repudiation** | Can actions on this flow occur without accountability? |
| **Information Disclosure** | Can data leak via this flow (logs, errors, side channels)? |
| **Denial of Service** | Can this flow be used to exhaust resources? |
| **Elevation of Privilege** | Can this flow be used to gain unauthorized access? |

For each identified threat:
1. Describe the threat concretely (not "tampering is possible" but "an attacker
   could modify the JWT payload because...")
2. Assess likelihood (low/medium/high) and impact (low/medium/high)
3. Propose a mitigation — either a new requirement or an architectural change
4. If the mitigation is a new requirement, format it as: "NEW-REQ: "
   with a suggested ASVS category

Also check for:
- Injection vectors at each input boundary
- Authentication/authorization gaps in the flow
- Sensitive data exposure in logs, errors, or API responses
- Resource exhaustion vectors (unbounded queues, connections, memory)
- Supply chain concerns (dependencies with excessive privilege)

Output format:

## Trust Boundary: 
### Data Flow:  destination>
| STRIDE | Threat | Likelihood | Impact | Mitigation |
|--------|--------|------------|--------|------------|
| S | ... | ... | ... | ... |

## New Requirements from Threat Model
- NEW-REQ-01:  (ASVS: )
- ...

## Architectural Changes Recommended
- 

Iteration back to requirements and architecture

After the threat model sub-agent returns, present findings to the user. Then:

1. New requirements (NEW-REQ items): add to docs/design/requirements.md and

update the SRTM. These get traced like any other requirement.

1. Architectural changes: update docs/design/architecture.md. Re-generate

affected diagrams if needed.

1. If changes are significant, discuss whether another threat model pass is needed

on the updated architecture. One iteration is usually sufficient; diminishing returns set in quickly.

This iteration — where threat modeling surfaces issues that change requirements and architecture — is where real engineering happens. It's the process working, not failing.

Artifact: Write docs/design/threat-model.md Gate: Present threat model and any resulting requirement/architecture changes to user. Always wait for explicit approval before proceeding to Phase 5.

Phase 5: Verification plan

Derive a test strategy from the SRTM. This phase bridges design into implementation — the outp

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: butterflyskies
• Source: butterflyskies/claude-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.