opencode-workflow/skills/design-architecture/SKILL.md

name	description
design-architecture	Design system architecture based on PRD requirements. The Architect pipeline's core step, producing the single strict output file. References deliverable skills for format details and knowledge contracts for design principles.

This skill produces the complete architecture document for a feature, including all required deliverables.

Announce at start: "I'm using the design-architecture skill to design the system architecture."

Primary Input

• docs/prd/{feature}.md (required)

Primary Output (STRICT PATH)

• docs/architecture/{feature}.md

This is the only file artifact produced by the Architect pipeline. No intermediate files are written to disk. All deliverables — diagrams, schemas, specs, ADRs — must be embedded within this single document.

Hard Gate

Do NOT start this skill if the PRD has unresolved ambiguities that block architectural decisions. Resolve them with the PM first.

Process

You MUST complete these steps in order:

1. Read the PRD at docs/prd/{feature}.md end-to-end to understand all requirements
2. Apply internal analysis from the analyze-prd step (if performed) to understand which knowledge domains are relevant
3. Design each architecture section based on PRD requirements and relevant knowledge domains
4. Apply knowledge contracts as needed:
   • system-decomposition when designing service boundaries
   • api-contract-design when defining API contracts
   • data-modeling when designing database schema
   • distributed-system-basics when dealing with distributed concerns
   • architecture-patterns when selecting architectural patterns
   • storage-knowledge when making storage technology decisions
   • async-queue-design when designing asynchronous workflows
   • error-model-design when defining error handling
   • security-boundary-design when defining auth, authorization, tenant isolation
   • consistency-transaction-design when defining consistency model, idempotency, saga
   • integration-boundary-design when defining external API integration patterns
   • observability-design when defining logs, metrics, traces, alerts, SLOs
   • migration-rollout-design when defining rollout strategy, feature flags, rollback
5. Apply deliverable skills for format requirements when producing sections:
   • generate_mermaid_diagram when producing the Mermaid Diagrams section
   • design_database_schema when producing the Database Schema section
   • generate_openapi_spec when producing the API Contract section
   • write_adr when producing the ADR section
   • evaluate_tech_stack when producing the Technology Stack subsection
6. Ensure traceability — every architectural decision must trace back to at least one PRD requirement
7. Verify completeness — all 18 required sections are present and substantive
8. Write the architecture document to docs/architecture/{feature}.md

Architect Behavior Principles

Apply these principles in priority order when making design decisions:

1. High Availability — Design for fault tolerance and resilience over perfect consistency
2. Scalability — Design for horizontal scaling over vertical scaling
3. Stateless First — Prefer stateless services; externalize state to databases or caches
4. API First — Define contracts before implementation; APIs are the primary interface
5. Event Driven First — Prefer event-driven communication for cross-service coordination
6. Async First — Prefer asynchronous processing for non-realtime operations

Anti-Placeholder Rule

Examples in deliverable skills and this template are illustrative only. Do not reuse placeholder components, fields, endpoints, or schemas unless explicitly required by the PRD. Every element in the architecture document must be grounded in actual requirements, not copied from examples.

Architecture Document Template

The following 18 sections are required. If a section is not applicable, write N/A with a brief reason. Each section states what it must contain and which deliverable skill to reference for format details.

# Architecture: {Feature Name}

## Overview

High-level description of the system architecture. Map every major PRD requirement to an architectural component. Summarize the system's purpose, key design decisions, and architectural style.

### Requirement Traceability

| PRD Requirement | Architectural Component |
|----------------|------------------------|
| ... | ... |

## System Architecture

Describe the complete system architecture including all services, databases, message queues, caches, and external integrations. Show how components are organized and how they communicate.

### Technology Stack

Reference `evaluate_tech_stack` deliverable skill for evaluation format.

| Layer | Technology | Justification |
|-------|-----------|---------------|
| ... | ... | ... |

If the feature has no backend component, write `N/A` with a brief reason.

### Component Architecture

Describe each major component, its responsibility, and how it fits into the overall system.

## Service Boundaries

Define service boundaries with clear responsibilities.

For each service or module:
- Name and single responsibility
- Owned data
- Communication patterns with other services (sync, async, event-driven)
- Potential coupling points and mitigation

### Communication Matrix

| From | To | Pattern | Protocol | Purpose |
|------|----|---------|----------|---------|
| ... | ... | ... | ... | ... |

## Data Flow

Describe how data moves through the system end-to-end. Include request lifecycle, background job processing, event propagation, and data transformation steps.

## Database Schema

Reference `design_database_schema` deliverable skill for table definition format, index format, partition key format, and relationship format.

Define all tables with field names, types, constraints, indexes, partition keys, and relationships. Include denormalization strategy and migration strategy where applicable.

If the feature requires no database changes, write `N/A` with a brief reason.

## API Contract

Reference `generate_openapi_spec` deliverable skill for endpoint definition format, error code format, idempotency format, and pagination format.

Define all API endpoints with method, path, request/response schemas, error codes, idempotency, and pagination. Include an endpoint catalog and endpoint details.

## Async / Queue Design

Define asynchronous operations and their behavior. If the feature has no asynchronous requirements, write `N/A` with a brief reason.

For each async operation:
- Operation name and trigger
- Queue or event topic
- Producer and consumer
- Retry policy (max retries, backoff, DLQ)
- Ordering guarantees
- Timeout and cancellation behavior

## Consistency Model

Define the consistency guarantees of the system. Reference `consistency-transaction-design` knowledge contract for design principles.

- Strong vs eventual consistency per data domain
- Idempotency design per idempotent operation
- Deduplication and retry strategy
- Outbox pattern usage (when applicable)
- Saga / compensation patterns (when applicable)

If the feature has no consistency or idempotency requirements, write `N/A` with a brief reason.

## Error Model

Define error handling strategy across the system.

- Error categories (client errors, server errors, business rule violations, timeout, cascading failure)
- Error propagation strategy (fail-fast, graceful degradation, circuit breaker)
- Error response format
- PRD edge case mapping

## Security Boundaries

Define security architecture. Reference `security-boundary-design` knowledge contract for design principles.

- Authentication mechanism
- Authorization model
- Service identity and service-to-service auth
- Token propagation strategy
- Tenant isolation
- Secret management
- Audit logging

If the feature has no security implications, write `N/A` with a brief reason.

## Integration Boundaries

Define all integrations with external systems. Reference `integration-boundary-design` knowledge contract for design principles.

For each external system:
- Integration pattern (API, webhook, polling, event)
- Rate limits and quotas
- Failure modes and fallback
- Retry strategy
- Data contract
- Authentication

If the feature has no external integrations, write `N/A` with a brief reason.

## Observability

Define observability strategy. Reference `observability-design` knowledge contract for design principles.

- Logs: levels, format, aggregation
- Metrics: business metrics, system metrics, naming conventions
- Traces: distributed tracing, correlation ID, span boundaries
- Alerts: conditions, thresholds, routing
- SLOs: availability, latency, error budget

## Scaling Strategy

Define how the system scales based on NFRs.

- Horizontal scaling approach
- Database scaling (read replicas, sharding, partitioning)
- Cache scaling
- Queue scaling
- Auto-scaling policies
- Bottleneck analysis

## Non-Functional Requirements

Document all NFRs from the PRD and how the architecture addresses each one.

| NFR | Requirement | Architectural Decision | Verification Method |
|-----|-------------|----------------------|---------------------|
| ... | ... | ... | ... |

## Mermaid Diagrams

Reference `generate_mermaid_diagram` deliverable skill for diagram format and guidelines.

Produce at minimum:
- 1 System Architecture Diagram
- 1 Sequence Diagram
- 1 Data Flow Diagram

Additional diagrams as needed (event flow, state machine, etc.).

## ADR

Reference `write_adr` deliverable skill for ADR format.

Document significant architectural decisions. Each ADR must include Context, Decision, Consequences, and Alternatives. Minimum 1 ADR.

## Risks

| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|------------|
| ... | High/Medium/Low | High/Medium/Low | ... |

## Open Questions

List any unresolved questions that need PM or Engineering input.

1. ...
2. ...

Completeness Check

Before finalizing the architecture document, verify:

1. All 18 required sections are present (or explicitly marked N/A with reason)
2. Every PRD functional requirement is traced to at least one architectural component
3. Every PRD NFR is traced to at least one architectural decision
4. Every architecture section that is not N/A has substantive content grounded in PRD requirements
5. All API endpoints map to PRD functional requirements
6. All DB tables map to data requirements from functional requirements or NFRs
7. All async flows map to PRD requirements
8. All error handling strategies map to PRD edge cases
9. ADRs exist for all significant decisions (minimum 1)
10. At least 3 Mermaid diagrams are present (system, sequence, data flow)
11. No placeholder content reused from examples — all content must be grounded in actual requirements

Guardrails

This is a pure Architecture skill.

Do:

• Design system structure and boundaries
• Define API contracts and data models
• Define error handling, retry, and consistency strategies
• Define security boundaries and integration patterns
• Reference deliverable skills for format requirements of specific sections
• Reference knowledge contracts for design principles
• Ensure traceability to PRD requirements
• Ensure all content is grounded in actual PRD requirements, not placeholder examples

Do not:

• Change PRD requirements or scope
• Create task breakdowns, milestones, or deliverables
• Write test cases or test plans
• Write implementation code or pseudocode
• Choose specific libraries or frameworks at the implementation level
• Prescribe code patterns, class structures, or function-level logic
• Produce any file artifact other than docs/architecture/{feature}.md
• Reuse placeholder components, fields, endpoints, or schemas from examples unless explicitly required by the PRD

The Architect defines HOW the system is structured. The Engineering defines HOW the code is written.

Transition

After completing the architecture document, invoke challenge-architecture to audit and review the architecture.