Design Architecture

!bash ~/.claude/hooks/sweetclaude/record-event.sh skill_invoked "sweetclaude:design-architecture" 2>/dev/null || true

!cat .sweetclaude/state/session-state.yaml 2>/dev/null || echo "STATE_NOT_FOUND"

Design Architecture

Artifact Path Resolution

Before writing any artifact file:

1. Read .sweetclaude/artifact-privacy.yaml. If it does not exist, stop and say:

   "No artifact privacy manifest found. Run /sweetclaude:setup to configure artifact privacy, then return here." Do not guess a path. Do not fall back to a default.

2. Read categories.technical.base_path. This is the base directory for all technical artifacts.

3. Construct full paths as {base_path}/{filename}, e.g. {base_path}/architecture.md, {base_path}/tech-spec-v1.md.

4. Write artifacts to those paths.

Define the architecture for your system. This skill conducts a structured interview, produces Architectural Decision Records (ADRs) for each significant decision, and generates an architecture document ready for development.

Entry

Check for .sweetclaude/ directory. If not found, tell the user to run /sweetclaude:init first. Stop.

Check for .sweetclaude/log.md. If not found, create it.

Read available state:

• .sweetclaude/state/brief.yaml
• .sweetclaude/state/prd.yaml
• .sweetclaude/state/personas.yaml
• .sweetclaude/state/stories.yaml

Note any missing state files — the interview is the primary input, but prior artifacts inform decisions.

ultraplan option: For large or complex architectural decisions, Anthropic's ultraplan (3 explorer agents + 1 critic) produces more thorough results than a single-context pass. Offer via AskUserQuestion before starting the interview:

• Run native design interview (default) — structured interview → SweetClaude produces the architecture document
• Use ultraplan — invoke sweetclaude:ultraplan to prepare context, launch ultraplan, and ingest the result

If the user picks ultraplan: invoke sweetclaude:ultraplan. Do not start the interview below.

Step 1 — Architecture Interview

Ask one question at a time. Always offer a recommendation before asking the user to decide.

Platform decisions:

1. "What programming language(s) will this be built in? I can recommend based on your team, use case, and ecosystem if helpful."
2. "What type of application is this primarily — web app, CLI tool, CLI utility, desktop app, mobile app, or something else?"
3. "How will this be deployed — SaaS (cloud-hosted, you manage), on-premises (customer hosts), locally run (runs on user's machine), or a hybrid?"

Architecture style: 4. "What's your instinct on architecture style — monolith (simpler, one deployable), services (microservices or macro-services, more complex), or are you unsure?" Offer a recommendation based on team size and scale indicators from prior state. A solo founder with an early-stage product should start with a monolith unless there's a strong reason not to.

Data: 5. "What kind of database do you need — relational (structured data, SQL), document (flexible schema, JSON), time-series, graph, or a mix?" Recommend based on the use case.

Compliance and security interview (mandatory, do not skip): 6. "Does your product handle any of the following regulated data types? Answer yes or no for each:

• PII (personally identifiable information — names, emails, addresses, IDs)
• PHI (protected health information — anything health/medical related)
• PCI data (payment card numbers, CVVs, cardholder data)
• Financial data subject to regulatory oversight (SOX, SEC, etc.)
• Any other regulated data or compliance frameworks your industry requires (GDPR, CCPA, HIPAA, SOC 2, etc.)"

If any regulated data: "These are legal requirements, not design preferences. I'll flag specific compliance constraints throughout the architecture and tech spec." Surface and label these as HARD REQUIREMENTS.

Additional questions as needed based on what the prior answers imply (auth requirements, third-party integrations, offline capability, etc.)

Step 2 — Analyze

Review all interview answers alongside available prior artifacts. Surface any conflicts: does the architecture interview imply something inconsistent with what the PRD or stories require?

Step 3 — Decision List

Produce a list of architectural decisions to be made. Walk through each with the user. For each decision:

• State the decision to be made
• Give a recommendation with reasoning
• Note any compliance requirements that constrain the options
• Record the decision once made

Step 4 — ADRs

Create an ADR for each significant decision. Use the following format (standard ADR format):

# ADR-{NNN}: {Title}

**Date:** {YYYY-MM-DD}
**Status:** Accepted | Proposed | Deprecated | Superseded

## Context

{What situation or requirement prompted this decision?}

## Decision

{What was decided?}

## Rationale

{Why this option over alternatives?}

## Consequences

{What becomes easier or harder as a result of this decision?}

## Alternatives Considered

{What other options were evaluated and why were they rejected?}

Save each ADR to {base_path}/adr/ADR-{NNN}-{kebab-title}.md.

Step 5 — Boundary Design

If service-oriented architecture: Define service boundaries:

• Which services exist?
• What does each service own (data, business logic)?
• How do services communicate (REST, gRPC, message queue, events)?
• Where are the seams — what can change in one service without affecting others?

If monolith: Define module/domain boundaries:

• What are the bounded contexts within the monolith?
• What are the internal module boundaries?
• What are the domain seams — where would you split if you needed to?
• What must not bleed across module boundaries?

Step 6 — Architecture Document

Write the architecture document. Standard sections:

• Overview and guiding principles
• Technology decisions (language, framework, database, deployment)
• Architecture style and rationale
• Component diagram (ASCII or description)
• Data flow
• Compliance and security requirements (labeled as HARD REQUIREMENTS if applicable)
• Boundary design (services or modules)
• ADR index (links to each ADR)
• Open questions

Document Production System

ADRs: {base_path}/adr/ADR-{NNN}-{title}-{yyyymmdd}.md Architecture doc: {base_path}/{project-name}-architecture-draft-v1.0-{yyyymmdd}.md

Both follow the standard front matter schema.

Exit

Write .sweetclaude/state/architecture.yaml:

style: monolith | services | hybrid
tech_stack:
  language: {}
  framework: {}
  database: {}
  deployment: {}
compliance_requirements: []
adr_ids: []
boundary_design_type: services | modules
current_architecture_file: {}

Append to .sweetclaude/log.md:

## {ISO datetime} — design-architecture (n/a)

**Status:** completed | degraded
**Produced:** {architecture doc filename}, {ADR count} ADRs
**Compliance flags:** {list or none}
**Key decisions:** {bullets}
**Open questions:** {bullets}