daniel.w
/
opencode-workflow
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
opencode-workflow/skills/design-architecture/SKILL.md

8.3 KiB
Raw Blame History

name description
design-architecture Design system architecture based on PRD requirements. This is the Architect pipeline's core step, producing the single strict output file. Comparable to write-a-prd in the PM pipeline.

This skill produces the complete architecture document for a feature.

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

Primary Input

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

Primary Output (STRICT PATH)

  • docs/architecture/{date}-{feature}.md

This is the only file artifact produced by the Architect pipeline. No intermediate files (research, analysis) are written to disk.

Save architecture to: docs/architecture/{date}-{feature}.md

  • (User preferences for architecture location override this default)

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/{date}-{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 domains as needed - reference relevant knowledge contracts during design:
    • 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
    • idempotency-design when designing idempotent operations
  5. Ensure traceability - every architectural decision must trace back to at least one PRD requirement
  6. Write completeness check - verify all required sections are present and substantive
  7. Write the architecture document to docs/architecture/{date}-{feature}.md

Architecture Document Template

# Architecture: {Feature Name}

## System Overview

High-level description of the system architecture. Map every major PRD requirement to an architectural component. Show component relationships and data flow direction. Identify external system integrations. Document deployment topology when relevant.

Use text or ASCII diagrams for component relationships.

### Requirement Traceability

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

## Frontend Architecture

Define frontend architecture including component structure, state management, and rendering strategy. If the feature has no frontend component, write `N/A` with a brief reason.

### Component Hierarchy
### State Management
### Routing Structure
### Client-Side Caching

## Backend Architecture

Define backend architecture including service layers, module boundaries, and dependency flow. This section MUST be present for all features with backend implications.

### Service/Module Boundaries
### Layer Separation
### Dependency Flow
### Shared Utilities

## API Definitions

Define all API endpoints with full specifications.

For each endpoint:
- Method and path
- Request schema (headers, path params, query params, body)
- Response schema (success and error responses)
- Status codes
- Authentication requirements
- Idempotency requirements (when applicable)
- Rate limiting expectations (when applicable)
- PRD functional requirement it satisfies

### Endpoint Catalog

| Method | Path | Description | PRD Requirement |
|--------|------|-------------|-----------------|
| ... | ... | ... | ... |

### Endpoint Details

(Define each endpoint in detail)

## DB Schema

Define all database tables, columns, indexes, constraints, and relationships. If the feature requires no database changes, write `N/A` with a brief reason.

### Table Definitions

For each table:
- Table name and purpose
- Column definitions (name, type, constraints, defaults)
- Indexes and their justification
- Foreign key relationships
- Data volume estimates (when relevant)

### Entity Relationships

Describe relationships between tables.

### Migration Strategy

Notes on migration approach if schema changes affect existing data.

## 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 |
|------|----|---------|----------|---------|
| ... | ... | ... | ... | ... |

## Async Model

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

### Async Operations

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

## Error Model

Define error handling strategy across the system.

### Error Categories
- Client errors (4xx)
- Server errors (5xx)
- Business rule violations
- Timeout errors
- Cascading failure modes

### Error Propagation Strategy
- Fail-fast vs graceful degradation vs circuit breaker
- Fallback behavior

### Error Response Format

Consistent error response schema across the system.

### Observability Hooks
- Logging strategy
- Metrics to track
- Alerting thresholds

### PRD Edge Case Mapping

| Error Category | PRD Edge Case | Handling Strategy |
|---------------|---------------|-------------------|
| ... | ... | ... |

## Idempotency Design

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

For each idempotent operation:
- Operation name
- Idempotency key source and format
- Key TTL and storage location
- Duplicate request behavior
- Collision handling

## Architectural Decision Records

For each significant architectural decision:

### ADR-{N}: {Decision Title}

- **Decision**: What was decided
- **Context**: Why this decision was needed, including which PRD requirements drove it
- **Alternatives**: What other options were considered
- **Rationale**: Why this option was chosen
- **Consequences**: What trade-offs or implications result

Completeness Check

Before finalizing the architecture document, verify:

  1. Every PRD functional requirement is traced to at least one architectural component
  2. Every PRD NFR is traced to at least one architectural decision
  3. All 9 required sections are present (or explicitly marked N/A with reason)
  4. Every architecture section that is not N/A has substantive content
  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
  10. No architectural element exists without traceability to a PRD requirement

Add explicit detail for these when relevant:

  • Security boundaries and authentication
  • Scalability considerations
  • Performance-critical paths
  • Data consistency 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 idempotency strategies
  • Make architectural decisions with clear rationale and alternatives
  • Ensure traceability to PRD requirements

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/{date}-{feature}.md

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 validate and stress-test the architecture.