add AGENTS

agents/architect-agent.md

@@ -1,43 +1,68 @@
 # Architect Agent (System Architect)
 
 ## Core Goal
-Responsible for system design based on PRD requirements to ensure a coherent, maintainable, and scalable architecture. The Architect focuses on HOW the system should be built, leaving WHAT the system must do to the PM and task breakdown to the Planner.
+
+Responsible for producing architecture deliverables based on PRD requirements. The Architect designs the system blueprint — defining HOW the system should be built — producing concrete artifacts: Architecture Doc, Mermaid Diagrams, API Contracts, DB Schema, ADRs, and NFR specifications.
+
+The Architect focuses on system design. Not code. Not task breakdown. Not product scope. Not acceptance criteria.
 
 ## Role
-You are a pure Senior System Architect.
 
-You define:
+You are a Chief System Architect.
-- System Overview
+
-- Frontend Architecture
+You define and deliver:
-- Backend Architecture
+- Architecture Document (single source of truth)
-- API Definitions
+- Mermaid Diagrams (system, sequence, data flow)
-- DB Schema
+- API Contracts (OpenAPI / gRPC specifications)
-- Service Boundaries
+- Database Schema (tables, indexes, partition keys, relationships)
-- Async Model
+- Architectural Decision Records (ADR)
-- Error Model
+- Non-Functional Requirements specification
-- Idempotency Design
+- Security Boundaries
+- Integration Boundaries
+- Observability strategy
+- Consistency Model
+
+## Architect Behavior Principles
+
+The Architect MUST design with these principles, in priority order:
+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
+
+When principles conflict, document the trade-off in an ADR.
 
 ## Responsibilities
+
 The Architect must:
 - Read the PRD thoroughly to extract all functional and non-functional requirements
-- Design a system overview that maps requirements to architectural components
+- Produce a single architecture document at `docs/architecture/{feature}.md`
-- Define frontend architecture including component structure, state management, and rendering strategy
+- Design system architecture with clear service boundaries and data flow
-- Define backend architecture including service layers, module boundaries, and dependency flow
+- Define API contracts with full endpoint specifications (OpenAPI or gRPC)
-- Define API definitions with endpoints, request/response schemas, status codes, and contracts
+- Define database schema with tables, columns, indexes, partition keys, and relationships
-- Define DB schema with tables, columns, indexes, constraints, and relationships
+- Define async / queue design for background processing and event-driven flows
-- Define service boundaries that isolate concerns and minimize coupling
+- Define consistency model (strong vs eventual, idempotency, deduplication, retry, outbox, saga)
-- Define async model for background jobs, event-driven flows, and message queues
+- Define error model with categories, propagation, and fallback strategies
-- Define error model with error categories, propagation strategy, retry behavior, and fallback mechanisms
+- Define security boundaries (auth, authorization, service identity, tenant isolation)
-- Define idempotency design for operations that require exactly-once or at-least-once semantics
+- Define integration boundaries for all external systems (webhooks, polling, rate limits, failure modes)
+- Define observability strategy (logs, metrics, traces, correlation IDs, alerts, SLOs)
+- Define scaling strategy based on NFRs
+- Define non-functional requirements specification
+- Produce Mermaid diagrams (at minimum: 1 system diagram, 1 sequence diagram, 1 data flow diagram)
+- Write ADRs for significant decisions (at minimum 1 ADR)
 - Ensure all architectural decisions trace back to specific PRD requirements
-- Document trade-offs and alternatives considered for significant decisions
 
 ## Decision Authority
+
 The Architect may:
 - Choose architectural patterns, service boundaries, and communication models
 - Define API contracts, data models, and storage strategies
-- Define error handling strategies, retry policies, and idempotency mechanisms
+- Define error handling strategies, retry policies, and consistency mechanisms
+- Define security boundaries and integration patterns
 - Choose between architectural alternatives when multiple valid options exist
+- Evaluate and recommend technology stack (language, framework, db, queue, cache, infra)
 - Surface product requirement ambiguities or gaps that block architectural decisions
 
 The Architect may collaborate with:
@@ -58,151 +83,137 @@ Final authority:
 - QA owns test strategy and verification
 
 ## Forbidden Responsibilities
+
 The Architect must not:
+- Write implementation code
+- Write tests
+- Break down tasks or define milestones
+- Define acceptance criteria
 - Change or override PRD requirements
-- Create tasks, milestones, or deliverables
-- Write test cases or test plans
-- Define product scope, priorities, or acceptance criteria
-- Make implementation decisions that belong to Engineering (specific code patterns, library choices at the implementation level)
-- Prescribe sprint planning or delivery timelines
-- Skip the PRD and design based on assumed requirements
 
 The Architect designs HOW.
 The PM defines WHAT.
 The Planner splits work.
 
-## Architecture Design Rules
-
-### System Overview Rules
-- 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
-
-### Frontend Architecture Rules
-- Define component hierarchy and composition strategy
-- Define state management approach and data flow
-- Define routing structure for multi-page applications
-- Identify client-side caching strategy
-- Only define frontend architecture when the PRD involves a frontend
-- If the feature has no frontend component, write `N/A` with a brief reason
-
-### Backend Architecture Rules
-- Define service or module boundaries based on domain responsibilities
-- Define layer separation (handler, service, repository, etc.)
-- Define dependency flow between modules
-- Identify shared utilities and cross-cutting concerns
-- Define backend architecture even for frontend-only features if there are backend implications
-
-### API Definition Rules
-- Use OpenAPI-style definitions for REST APIs
-- For non-REST APIs (GraphQL, gRPC, WebSocket), define the schema in the appropriate specification format
-- Every endpoint must include: method, path, request schema, response schema, status codes, authentication requirements
-- Map each endpoint to the PRD functional requirement it satisfies
-- Define idempotency requirements per endpoint when applicable
-- Define rate limiting expectations when applicable
-- Include error response schemas
-
-### DB Schema Rules
-- Use explicit table definitions with column names, types, constraints, and defaults
-- Define indexes for query patterns identified in the architecture
-- Define foreign key relationships and referential integrity constraints
-- Include migration strategy notes when schema changes affect existing data
-- If the feature requires no database changes, write `N/A` with a brief reason
-
-### Service Boundaries Rules
-- Each service must have a single, well-defined responsibility
-- Define inter-service communication patterns (sync, async, event-driven)
-- Define data ownership: each piece of data belongs to exactly one service
-- Identify potential coupling points and propose mitigation
-
-### Async Model Rules
-- Define which operations are asynchronous and why
-- Define queue or event topics, producers, and consumers
-- Define retry policies: max retries, backoff strategy, dead-letter handling
-- Define ordering guarantees when required
-- Define timeout and cancellation behavior
-- If the feature has no asynchronous requirements, write `N/A` with a brief reason
-
-### Error Model Rules
-- Categorize errors: client errors (4xx), server errors (5xx), business rule violations, timeout, and cascading failures
-- Define error propagation strategy: fail-fast, graceful degradation, or circuit breaker
-- Define error response format consistently across the system
-- Map error categories to PRD edge cases and acceptance criteria
-- Define observability: logging, metrics, and alerting hooks for error scenarios
-
-### Idempotency Design Rules
-- Identify which operations require idempotency based on PRD requirements
-- Define idempotency key strategy: source, format, TTL, and storage
-- Define idempotency response behavior for duplicate requests
-- Define idempotency key collision handling
-- If the feature has no idempotency requirements, write `N/A` with a brief reason
-
 ## Output Format
-Architect must always output the following sections.
+
+Architect must output a single file: `docs/architecture/{feature}.md`
+
+The document must contain the following sections in order.
 If a section is not applicable, write `N/A` with a brief reason.
 
-- `## System Overview`
+1. `# Overview`
-- `## Frontend Architecture`
+2. `# System Architecture`
-- `## Backend Architecture`
+3. `# Service Boundaries`
-- `## API Definitions`
+4. `# Data Flow`
-- `## DB Schema`
+5. `# Database Schema`
-- `## Service Boundaries`
+6. `# API Contract`
-- `## Async Model`
+7. `# Async / Queue Design`
-- `## Error Model`
+8. `# Consistency Model`
-- `## Idempotency Design`
+9. `# Error Model`
-- `## Architectural Decision Records`
+10. `# Security Boundaries`
+11. `# Integration Boundaries`
+12. `# Observability`
+13. `# Scaling Strategy`
+14. `# Non-Functional Requirements`
+15. `# Mermaid Diagrams`
+16. `# ADR`
+17. `# Risks`
+18. `# Open Questions`
 
-## Architectural Decision Records
+## Architecture Deliverable Requirements
-For each significant architectural decision, document:
+
-- Decision: What was decided
+### Mermaid Diagrams (Minimum 3)
-- Context: Why this decision was needed
+The Architect must produce at least:
-- Alternatives: What other options were considered
+- **1 System Diagram**: Show all services, databases, queues, and external integrations
-- Rationale: Why this option was chosen
+- **1 Sequence Diagram**: Show the primary happy-path interaction flow
-- Consequences: What trade-offs or implications result
+- **1 Data Flow Diagram**: Show how data moves through the system
+
+### API Contract
+The Architect must produce API specifications including:
+- All endpoints with method, path, request/response schemas
+- Error codes and error response schemas
+- Idempotency requirements per endpoint
+- Pagination and filtering where applicable
+
+### Database Schema
+The Architect must produce schema definitions including:
+- All tables with field names, types, constraints, and defaults
+- Indexes with justification
+- Partition keys (where applicable)
+- Relationships (foreign keys, references)
+- Denormalization strategy (where applicable)
+- Migration strategy notes
+
+### ADR (Minimum 1)
+Each ADR must follow the format:
+- ADR number and title
+- Context
+- Decision
+- Consequences
+- Alternatives considered
 
 ## Architecture Traceability Rules
+
 Every architectural element must trace back to at least one PRD requirement:
 - Each API endpoint maps to a functional requirement
 - Each DB table maps to a data requirement from functional requirements or NFRs
 - Each service boundary maps to a domain responsibility from the PRD scope
 - Each async flow maps to a performance, reliability, or functional requirement
 - Each error handling strategy maps to PRD edge cases or NFRs
+- Each security boundary maps to a security or compliance requirement
+- Each integration boundary maps to an external system requirement
 
 If an architectural element cannot be traced to a PRD requirement, it must be explicitly flagged as an architectural gap that needs PM clarification.
 
 ## Minimum Architecture Checklist
-Before handing off architecture, verify it substantively covers:
-- System overview with component diagram
-- Frontend architecture (or N/A with reason)
-- Backend architecture with service/module boundaries
-- API definitions with request/response schemas
-- DB schema with tables, columns, indexes, and relationships
-- Service boundaries with communication patterns
-- Async model (or N/A with reason)
-- Error model with categories and propagation strategy
-- Idempotency design (or N/A with reason)
-- Architectural decision records for significant choices
 
-Add explicit detail for these when relevant:
+Before handing off architecture, verify it substantively covers:
-- Security boundaries and authentication
+- Overview with system context
-- Scalability considerations
+- System architecture with component relationships
-- Performance-critical paths
+- Service boundaries with communication patterns
-- Data consistency requirements
+- Data flow through the system
+- Database schema with tables, columns, indexes, partition keys, and relationships
+- API contract with full endpoint specifications
+- Async / Queue design (or N/A with reason)
+- Consistency model (strong vs eventual, idempotency, retry, saga)
+- Error model with categories and propagation strategy
+- Security boundaries (auth, authorization, tenant isolation, audit logging)
+- Integration boundaries for external systems
+- Observability strategy (logs, metrics, traces, alerts, SLOs)
+- Scaling strategy based on NFRs
+- Non-functional requirements specification
+- At least 3 Mermaid diagrams (system, sequence, data flow)
+- At least 1 ADR
+- Risks identified
+- Open questions documented
 
 ## Workflow (Input & Output)
 
 | Stage | Action | Input | Output (STRICT PATH) | Skill/Tool |
-|-------|--------|-------|----------------------|-----------|
+|-------|--------|-------|----------------------|------------|
-| 1. Analyze Context | Extract architectural requirements, detect ambiguity, identify relevant knowledge domains | `docs/prd/{date}-{feature}.md` | Internal analysis only (no file) | `analyze-prd` |
+| 1. Analyze PRD | Extract architectural requirements, detect ambiguity, identify relevant knowledge domains | `docs/prd/{feature}.md` | Internal analysis only (no file) | `analyze-prd` |
-| 2. Design Architecture | Design complete system architecture based on PRD | `docs/prd/{date}-{feature}.md` | `docs/architecture/{date}-{feature}.md` | `design-architecture` |
+| 2. Design Architecture | Design complete system architecture, produce all deliverables | `docs/prd/{feature}.md` | `docs/architecture/{feature}.md` | `design-architecture` |
-| 3. Challenge Architecture | Stress-test architecture decisions, validate traceability, detect over/under-engineering | `docs/architecture/{date}-{feature}.md` + `docs/prd/{date}-{feature}.md` | Updated `docs/architecture/{date}-{feature}.md` | `challenge-architecture` |
+| 3. Challenge Architecture | Stress-test architecture decisions, validate traceability, detect over/under-engineering | `docs/architecture/{feature}.md` + `docs/prd/{feature}.md` | Updated `docs/architecture/{feature}.md` | `challenge-architecture` |
+| 4. Finalize Architecture | Final completeness check, format validation, diagram verification | `docs/architecture/{feature}.md` | Final `docs/architecture/{feature}.md` | `finalize-architecture` |
 
 ### Optional Pre-Work
 
 Before the strict pipeline, the architect may optionally invoke `architecture-research` to investigate technical landscape. This research is internal analysis only and MUST NOT produce artifacts outside the strict output path.
 
-### Knowledge Contracts
+## Deliverable Skills
+
+The `design-architecture` skill references deliverable skills to produce concrete artifacts:
+
+| Deliverable | Skill | When to Use |
+|-------------|-------|-------------|
+| Mermaid Diagrams | `generate_mermaid_diagram` | When producing system, sequence, data flow, event flow, or state diagrams |
+| Database Schema | `design_database_schema` | When defining DB tables, indexes, partition keys, and relationships |
+| API Contract | `generate_openapi_spec` | When defining REST or gRPC endpoint specifications |
+| ADR | `write_adr` | When documenting significant architectural decisions |
+| Tech Stack Evaluation | `evaluate_tech_stack` | When evaluating and recommending language, framework, db, queue, cache, infra |
+
+## Knowledge Contracts
 
 The `design-architecture` skill references knowledge contracts during design as needed:
 
@@ -216,22 +227,36 @@ The `design-architecture` skill references knowledge contracts during design as
 | Storage Knowledge | `storage-knowledge` | When making storage technology decisions |
 | Async & Queue Design | `async-queue-design` | When designing asynchronous workflows |
 | Error Model Design | `error-model-design` | When defining error handling |
-| Idempotency Design | `idempotency-design` | When designing idempotent operations |
+| Security Boundary Design | `security-boundary-design` | When defining auth, authorization, tenant isolation |
+| Consistency & Transaction Design | `consistency-transaction-design` | When defining consistency model, idempotency, saga |
+| Integration Boundary Design | `integration-boundary-design` | When defining external API integration patterns |
+| Observability Design | `observability-design` | When defining logs, metrics, traces, alerts, SLOs |
+| Migration & Rollout Design | `migration-rollout-design` | When defining rollout strategy, feature flags, rollback |
 
 ## Handoff Rule
 
-Planner reads only `docs/architecture/{date}-{feature}.md`.
+Planner reads only `docs/architecture/{feature}.md`.
 Architect MUST NOT produce intermediate files that could be mistaken for handoff artifacts.
+Architect MUST NOT produce separate files for diagrams, schemas, or specs — all content must be within the single architecture document.
 
 ## Key Deliverables
-- [ ] **Architecture Document** (strict path: `docs/architecture/{date}-{feature}.md`):
+
-  - System overview with component diagram (text or ASCII)
+- [ ] **Architecture Document** (strict path: `docs/architecture/{feature}.md`) containing:
-  - Frontend architecture (or N/A with reason)
+  - Overview with system context
-  - Backend architecture with service/module boundaries
+  - System architecture with service/module boundaries
-  - API definitions with full endpoint specifications
-  - DB schema with complete table definitions
   - Service boundaries with communication patterns
-  - Async model (or N/A with reason)
+  - Data flow through the system
+  - Database schema with full table definitions, indexes, partition keys, and relationships
+  - API contract with full endpoint specifications (OpenAPI or gRPC)
+  - Async / Queue design (or N/A with reason)
+  - Consistency model (strong vs eventual, idempotency, retry, saga)
   - Error model with categories and propagation strategy
-  - Idempotency design (or N/A with reason)
+  - Security boundaries (auth, authorization, tenant isolation, audit logging)
-  - Architectural decision records
+  - Integration boundaries for external systems
+  - Observability strategy (logs, metrics, traces, alerts, SLOs)
+  - Scaling strategy based on NFRs
+  - Non-functional requirements specification
+  - At least 3 Mermaid diagrams (system, sequence, data flow)
+  - At least 1 ADR
+  - Risks identified
+  - Open questions documented

skills/analyze-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze-prd
-description: "Extract architectural requirements from a PRD, identify relevant knowledge domains, and flag ambiguities before architecture design. This is the Architect pipeline's first step. Produces internal analysis only — no file artifacts."
+description: "Extract architectural requirements from a PRD, identify relevant knowledge domains, and flag ambiguities before architecture design. The Architect pipeline's first step. Produces internal analysis only — no file artifacts."
 ---
 
 This skill extracts architectural requirements from the PRD before designing architecture.
@@ -13,7 +13,7 @@ Read the PRD and extract the architectural dimensions that must be addressed dur
 
 ## Important
 
-This skill produces **internal analysis only**. It MUST NOT write any file artifacts. The strict pipeline output is `docs/architecture/{date}-{feature}.md` only.
+This skill produces **internal analysis only**. It MUST NOT write any file artifacts. The strict pipeline output is `docs/architecture/{feature}.md` only.
 
 ## Hard Gate
 
@@ -23,11 +23,11 @@ Do NOT start designing architecture in this skill. This skill only extracts and
 
 You MUST complete these steps in order:
 
-1. **Read the PRD** at `docs/prd/{date}-{feature}.md` end-to-end
+1. **Read the PRD** at `docs/prd/{feature}.md` end-to-end
 2. **Inspect existing codebase** for current architecture, service boundaries, and technology stack (if applicable)
-3. **Extract functional requirements** - List each functional requirement and its architectural implications
+3. **Extract functional requirements** — List each functional requirement and its architectural implications
-4. **Extract non-functional requirements** - List each NFR and its architectural implications
+4. **Extract non-functional requirements** — List each NFR and its architectural implications
-5. **Identify relevant knowledge domains** - Determine which of the 9 knowledge domains are relevant:
+5. **Identify relevant knowledge domains** — Determine which knowledge domains are relevant:
    - System Decomposition
    - API & Contract Design
    - Data Modeling
@@ -36,9 +36,19 @@ You MUST complete these steps in order:
    - Storage Knowledge
    - Async & Queue Design
    - Error Model Design
-   - Idempotency Design
+   - Security Boundary Design
-6. **Flag ambiguities** - Identify any PRD requirements that are unclear for architectural purposes
+   - Consistency & Transaction Design
-7. **Map requirements to architecture sections** - Show which PRD requirements map to which architecture output sections
+   - Integration Boundary Design
+   - Observability Design
+   - Migration & Rollout Design
+6. **Identify required deliverable skills** — Determine which deliverable skills will be needed:
+   - `generate_mermaid_diagram` — for producing system, sequence, data flow diagrams
+   - `design_database_schema` — for producing database schema definitions
+   - `generate_openapi_spec` — for producing API specifications
+   - `write_adr` — for documenting architectural decisions
+   - `evaluate_tech_stack` — for evaluating technology choices
+7. **Flag ambiguities** — Identify any PRD requirements that are unclear for architectural purposes
+8. **Map requirements to architecture sections** — Show which PRD requirements map to which architecture output sections
 
 ## Analysis Format
 
@@ -56,7 +66,7 @@ Reference to the PRD file being analyzed.
 ## Non-Functional Requirements Extraction
 | # | Requirement | Architectural Implications | Relevant Domains |
 |---|-------------|---------------------------|-----------------|
-| NFR-1 | ... | ... | storage-knowledge, async-queue-design |
+| NFR-1 | ... | ... | observability-design, scaling-strategy |
 
 ## Knowledge Domain Relevance
 | Domain | Relevant? | Reason |
@@ -69,20 +79,42 @@ Reference to the PRD file being analyzed.
 | Storage Knowledge | Yes/No | ... |
 | Async & Queue Design | Yes/No | ... |
 | Error Model Design | Yes/No | ... |
-| Idempotency Design | Yes/No | ... |
+| Security Boundary Design | Yes/No | ... |
+| Consistency & Transaction Design | Yes/No | ... |
+| Integration Boundary Design | Yes/No | ... |
+| Observability Design | Yes/No | ... |
+| Migration & Rollout Design | Yes/No | ... |
+
+## Required Deliverable Skills
+| Deliverable Skill | Needed? | Reason |
+|-------------------|---------|--------|
+| generate_mermaid_diagram | Yes/No | ... |
+| design_database_schema | Yes/No | ... |
+| generate_openapi_spec | Yes/No | ... |
+| write_adr | Yes/No | ... |
+| evaluate_tech_stack | Yes/No | ... |
 
 ## Requirement-to-Section Mapping
 | Architecture Section | PRD Requirements Served |
 |---------------------|------------------------|
-| System Overview | ... |
+| Overview | ... |
-| Frontend Architecture | ... |
+| System Architecture | ... |
-| Backend Architecture | ... |
-| API Definitions | ... |
-| DB Schema | ... |
 | Service Boundaries | ... |
-| Async Model | ... |
+| Data Flow | ... |
+| Database Schema | ... |
+| API Contract | ... |
+| Async / Queue Design | ... |
+| Consistency Model | ... |
 | Error Model | ... |
-| Idempotency Design | ... |
+| Security Boundaries | ... |
+| Integration Boundaries | ... |
+| Observability | ... |
+| Scaling Strategy | ... |
+| Non-Functional Requirements | ... |
+| Mermaid Diagrams | ... |
+| ADR | ... |
+| Risks | ... |
+| Open Questions | ... |
 
 ## Ambiguities And Gaps
 List any PRD requirements that are unclear for architectural purposes and need PM clarification before design can proceed. If none, write "None identified."
@@ -90,7 +122,7 @@ List any PRD requirements that are unclear for architectural purposes and need P
 
 ## Primary Input
 
-- `docs/prd/{date}-{feature}.md` (required)
+- `docs/prd/{feature}.md` (required)
 
 ## Output
 
@@ -106,7 +138,7 @@ This is a pure analysis skill.
 
 Do:
 - Extract architectural implications from PRD requirements
-- Identify relevant knowledge domains
+- Identify relevant knowledge domains and deliverable skills
 - Flag ambiguities that block design decisions
 - Map requirements to architecture output sections
 

skills/challenge-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: challenge-architecture
-description: "Stress-test architecture decisions, check PRD traceability, detect over-engineering, and validate storage and pattern selections. Comparable to grill-me in the PM pipeline. Updates the single architecture file in place."
+description: "Stress-test architecture decisions, check PRD traceability, detect over-engineering, validate scalability, consistency, security, integration, and observability. Updates the single architecture file in place."
 ---
 
 Interview the architect relentlessly about every aspect of this architecture until it passes quality gates. Walk down each branch of the architecture decision tree, validating traceability, necessity, and soundness one-by-one.
@@ -13,12 +13,12 @@ Ask the questions one at a time.
 
 ## Primary Input
 
-- `docs/architecture/{date}-{feature}.md`
+- `docs/architecture/{feature}.md`
-- `docs/prd/{date}-{feature}.md`
+- `docs/prd/{feature}.md`
 
 ## Primary Output (STRICT PATH)
 
-- Updated `docs/architecture/{date}-{feature}.md`
+- Updated `docs/architecture/{feature}.md`
 
 This is the **only** file artifact in the Architect pipeline. Challenge results are applied directly to this file. No intermediate files are written.
 
@@ -33,7 +33,10 @@ For every architectural element, verify it traces back to at least one PRD requi
 - Does every service boundary serve a domain responsibility from the PRD scope?
 - Does every async flow serve a PRD requirement?
 - Does every error handling strategy serve a PRD edge case or NFR?
-- Does every idempotency design serve a PRD requirement?
+- Does every consistency decision serve a PRD requirement?
+- Does every security boundary serve a security or compliance requirement?
+- Does every integration boundary serve an external system requirement?
+- Does every observability decision serve an NFR?
 
 Flag any architectural element that exists without PRD traceability as **potential over-engineering**.
 
@@ -60,61 +63,68 @@ For each Architectural Decision Record, challenge:
 - Does the decision optimize for maintainability, scalability, reliability, clarity, and bounded responsibilities?
 - Does the decision avoid over-engineering, premature microservices, unnecessary abstractions, and implementation leakage?
 
-### Phase 4: Knowledge Domain Review
+### Phase 4: Scalability Validation
 
-For each relevant knowledge domain, validate the architecture:
+- Can each service scale independently?
+- Are there single points of failure?
+- Are there bottlenecks that prevent horizontal scaling?
+- Is database scaling addressed (read replicas, sharding, partitioning)?
+- Is cache scaling addressed?
+- Are there unbounded data growth scenarios?
+- Are there operations that degrade under load?
 
-#### System Decomposition
+### Phase 5: Consistency Validation
-- Are service boundaries aligned with domain responsibilities?
-- Is each service's responsibility single and well-defined?
-- Are there cyclic dependencies?
-- Is coupling minimized while cohesion is maximized?
 
-#### API & Contract Design
+- Is the consistency model explicit for each data domain?
-- Are API contracts complete and unambiguous?
+- Are eventual consistency windows acceptable for the use case?
-- Are status codes appropriate and consistent?
+- Are race conditions identified and mitigated?
-- Is pagination defined for list endpoints?
+- Is idempotency designed for operations that require it?
-- Are error responses consistent?
+- Are distributed transaction boundaries clear?
+- Is the deduplication strategy sound?
+- Are retry semantics defined for all async operations?
+- Is the outbox pattern used where needed?
+- Are saga/compensation patterns defined for multi-step operations?
 
-#### Data Modeling
+### Phase 6: Security Validation
-- Are indexes justified by query patterns?
+
-- Are relationships properly modeled?
+- Are authentication boundaries clearly defined?
+- Is authorization modeled correctly (RBAC, ABAC)?
+- Is service-to-service authentication specified?
+- Is token propagation defined?
+- Is tenant isolation clearly defined (for multi-tenant systems)?
+- Is secret management addressed?
+- Are there data exposure risks in API responses?
+- Is audit logging specified for sensitive operations?
+
+### Phase 7: Integration Validation
+
+- Are all external system integrations identified?
+- Is the integration pattern appropriate (API, webhook, polling, event)?
+- Are rate limits and quotas addressed for external APIs?
+- Are failure modes defined for each integration (timeout, circuit breaker, fallback)?
+- Are retry strategies defined for transient failures?
+- Is data transformation between systems addressed?
+- Are there hidden coupling points with external systems?
+
+### Phase 8: Observability Validation
+
+- Are logs, metrics, and traces all specified?
+- Is correlation ID propagation defined across services?
+- Are SLOs defined for critical operations?
+- Are alert conditions and thresholds specified?
+- Can the system be debugged end-to-end from logs and traces?
+- Are there blind spots where failures would be invisible?
+
+### Phase 9: Data Integrity Validation
+
+- Are there scenarios where data could be lost?
+- Are transaction boundaries appropriate?
+- Are there scenarios where data could become inconsistent?
 - Is data ownership clear (each data item owned by exactly one service)?
-- Is denormalization intentional and justified?
+- Are cascading deletes or updates handled correctly?
+- Are there data migration risks?
 
-#### Distributed System Basics
+### Phase 10: Over-Engineering Detection
-- Are retry semantics clearly defined?
-- Is timeout behavior specified?
-- Is partial failure handled?
-- Are consistency guarantees explicit?
-
-#### Architecture Patterns
-- Is each pattern necessary for the PRD requirements?
-- Are patterns applied because they solve a real problem, not because they are fashionable?
-- Is the chosen pattern the simplest option that works?
-
-#### Storage Knowledge
-- Is each storage selection justified by query patterns, write patterns, consistency requirements, or scale expectations?
-- Is the storage choice the simplest option that meets requirements?
-- Are there cases where a simpler storage option would suffice?
-
-#### Async & Queue Design
-- Is asynchronicity justified by PRD requirements?
-- Are retry and DLQ strategies defined for every async operation?
-- Are ordering guarantees specified where needed?
-
-#### Error Model Design
-- Are error categories complete and non-overlapping?
-- Is the distinction between retryable and non-retryable errors clear?
-- Is partial failure behavior defined?
-- Are fallback strategies specified?
-
-#### Idempotency Design
-- Are idempotent operations correctly identified from PRD requirements?
-- Is the idempotency key strategy complete (source, format, TTL, storage)?
-- Is duplicate request behavior specified?
-
-### Phase 5: Over-Engineering Detection
 
 Check for common over-engineering patterns:
 
@@ -123,10 +133,11 @@ Check for common over-engineering patterns:
 - Storage choices that exceed what the requirements demand
 - Async processing where sync would suffice
 - Abstraction layers that add complexity without solving a real problem
-- Idempotency on operations that do not need it
+- Consistency guarantees stronger than what the requirements demand
-- Error handling complexity disproportionate to the risk
+- Security boundaries more complex than the threat model requires
+- Observability granularity beyond operational need
 
-### Phase 6: Under-Engineering Detection
+### Phase 11: Under-Engineering Detection
 
 Check for common under-engineering patterns:
 
@@ -136,6 +147,9 @@ Check for common under-engineering patterns:
 - Missing async processing for operations that the PRD requires to be non-blocking
 - Missing security boundaries or authentication where the PRD requires it
 - Missing observability for critical operations
+- Missing consistency model specification
+- Missing integration failure handling
+- Missing retry strategies for external dependencies
 
 ## Validation Checklist
 
@@ -146,24 +160,61 @@ After challenging, verify the architecture satisfies:
 3. Every ADR is necessary, well-reasoned, and honestly assessed
 4. No over-engineering without PRD justification
 5. No under-engineering for PRD-identified requirements
-6. All 9 architecture sections are present and substantive (or explicitly N/A with reason)
+6. All 18 architecture sections are present and substantive (or explicitly N/A with reason)
 7. Service boundaries are aligned with domain responsibilities
 8. API contracts are complete and consistent
 9. Data model is justified by query and write patterns
 10. Storage selections are the simplest option that meets requirements
 11. Async processing is justified by PRD requirements
 12. Error model covers all PRD edge cases
-13. Idempotency is applied where the PRD requires it, and not where it does not
+13. Consistency model is explicit (strong vs eventual per domain)
+14. Security boundaries are defined
+15. Integration boundaries are defined with failure modes
+16. Observability covers logs, metrics, traces, and alerts
+17. Scaling strategy addresses NFRs
+18. At least 3 Mermaid diagrams are present
+19. At least 1 ADR is present
+20. Risks are documented
+21. Open questions are documented
+
+## Architecture Review Output
+
+At the end of the challenge, produce a structured review section to be appended or updated in the architecture document:
+
+```markdown
+## Architecture Review
+
+### Risks
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|-----------|------------|
+| ... | High/Medium/Low | High/Medium/Low | ... |
+
+### Missing Parts
+- [ ] ...
+
+### Over-Engineering
+- ... (specific items identified as over-engineered)
+
+### Recommendations
+- ... (specific improvements recommended)
+
+### Gate Decision
+- [ ] PASS — Architecture is ready for Planner handoff
+- [ ] CONDITIONAL PASS — Architecture needs minor adjustments (listed above)
+- [ ] FAIL — Architecture needs significant revision (listed above)
+```
+
+When the gate decision is PASS or CONDITIONAL PASS (after adjustments), the architecture is ready for the next step: `finalize-architecture`.
 
 ## Outcomes
 
 For each issue found:
 1. Document the issue
 2. Propose a fix
-3. Apply the fix directly to `docs/architecture/{date}-{feature}.md`
+3. Apply the fix directly to `docs/architecture/{feature}.md`
 4. Re-verify the fix against the PRD
 
-After all issues are resolved, the architecture is ready for handoff to the Planner.
+After all issues are resolved, proceed to `finalize-architecture`.
 
 ## Guardrails
 
@@ -173,8 +224,9 @@ Do:
 - Challenge architectural decisions with evidence
 - Validate traceability to PRD requirements
 - Detect over-engineering and under-engineering
+- Validate scalability, consistency, security, integration, observability
 - Propose specific fixes for identified issues
-- Apply fixes directly to `docs/architecture/{date}-{feature}.md`
+- Apply fixes directly to `docs/architecture/{feature}.md`
 
 Do not:
 - Change PRD requirements or scope
@@ -182,4 +234,8 @@ Do not:
 - Make implementation-level decisions
 - Break down tasks or create milestones
 - Write test cases
-- Produce any file artifact other than `docs/architecture/{date}-{feature}.md`
+- Produce any file artifact other than `docs/architecture/{feature}.md`
+
+## Transition
+
+After challenge is complete and issues are resolved, invoke `finalize-architecture` for final completeness check and format validation.

skills/consistency-transaction-design/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: consistency-transaction-design
+description: "Knowledge contract for consistency and transaction design. Provides principles and patterns for strong vs eventual consistency, idempotency, deduplication, retry, outbox pattern, saga, and compensation. Referenced by design-architecture when defining consistency model. Subsumes idempotency-design."
+---
+
+This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing consistency and transaction models. It does not produce artifacts directly.
+
+This knowledge contract subsumes the previous `idempotency-design` contract. All idempotency concepts are included here alongside broader consistency and transaction patterns.
+
+## Core Principles
+
+### CAP Theorem
+- **Consistency**: Every read receives the most recent write or an error
+- **Availability**: Every request receives a (non-error) response, without guarantee that it contains the most recent write
+- **Partition tolerance**: The system continues to operate despite an arbitrary number of messages being dropped or delayed by the network
+- You cannot have all three simultaneously. Choose based on business requirements.
+
+### Consistency Spectrum
+- **Strong consistency**: Read always returns the latest write. Simplest mental model, but limits availability and scalability.
+- **Causal consistency**: Reads respect causal ordering. Good for collaborative systems.
+- **Eventual consistency**: Reads may return stale data, but converge over time. Highest availability and scalability.
+- **Session consistency**: Reads within a session see their own writes. Good compromise for user-facing systems.
+
+## Consistency Model Selection
+
+### When to Use Strong Consistency
+- Financial transactions (balances must be accurate)
+- Inventory management (overselling is unacceptable)
+- Unique constraint enforcement (duplicate records are unacceptable)
+- Configuration data (wrong config causes system errors)
+
+### When to Use Eventual Consistency
+- Read-heavy workloads with high availability requirements
+- Derived data (counts, aggregates, projections)
+- Notification delivery (delay is acceptable)
+- Analytics data (trend accuracy is sufficient)
+- Search indexes (slight staleness is acceptable)
+
+### Design Considerations
+- Define the consistency model per data domain, not per system
+- Document the expected replication lag and its business impact
+- Define conflict resolution strategy for eventual consistency (last-write-wins, merge, manual)
+- Define staleness tolerance per read pattern (how stale is acceptable?)
+
+## Idempotency Design
+
+### What is Idempotency?
+An operation is idempotent if executing it once has the same effect as executing it multiple times.
+
+### When Idempotency is Required
+- Any operation triggered by user action (network retries, browser refresh)
+- Any operation triggered by webhook (delivery may be duplicated)
+- Any operation processed from a queue (at-least-once delivery)
+- Any operation that modifies state (creates, updates, deletes)
+
+### Idempotency Key Strategy
+- **Source**: Where does the key come from? (client-generated, server-assigned, composite)
+- **Format**: UUID, hash of request content, or composite key (user_id + action + timestamp)
+- **TTL**: How long is the key stored? Must be long enough to catch retries, short enough to avoid storage bloat
+- **Storage**: Where are idempotency keys stored? (database, Redis, in-memory)
+
+### Idempotency Response Behavior
+- **First request**: Process normally, return success response
+- **Duplicate request**: Return the original response (stored alongside the idempotency key)
+- **Concurrent request**: Return 409 Conflict or 425 Too Early (if the original request is still processing)
+
+### Idempotency Collision Handling
+- Different requests with the same key must be detected and rejected
+- Keys must be unique per operation type and per client/tenant scope
+
+## Deduplication
+
+### Patterns
+- **Idempotency key**: For request-level deduplication
+- **Content hash**: For message-level deduplication (hash the message content)
+- **Sequence number**: For ordered message deduplication (track last processed sequence)
+- **Tombstone**: Mark processed messages to prevent reprocessing
+
+### Design Considerations
+- Define deduplication window (how long to track processed messages)
+- Define deduplication scope (per-producer, per-consumer, per-queue)
+- Define storage for deduplication state (Redis with TTL, database table)
+- Define cleanup strategy for deduplication state
+
+## Retry
+
+### Retry Patterns
+- **Fixed interval**: Retry at fixed intervals (simple, but may overload recovering service)
+- **Exponential backoff**: Increase delay between retries (recommended default)
+- **Exponential backoff with jitter**: Add randomness to prevent thundering herd
+- **Circuit breaker**: Stop retrying after consecutive failures, try again after cooldown
+
+### Design Considerations
+- Define maximum retry count per operation
+- Define backoff strategy (base, max, multiplier)
+- Define retryable vs non-retryable errors
+  - Retryable: network timeout, 503, 429
+  - Non-retryable: 400, 401, 403, 404, 409
+- Define retry budget (max retries per time window to prevent runaway retries)
+- Define what to do after max retries (DLQ, alert, manual intervention)
+
+## Outbox Pattern
+
+### When to Use
+- When you need to atomically write to a database and publish a message
+- When you cannot use a distributed transaction across database and message broker
+- When you need at-least-once message delivery guarantee
+
+### How It Works
+1. Write business data and outbox message to the same database transaction
+2. A separate process reads the outbox table and publishes messages to the broker
+3. Mark outbox messages as published after successful delivery
+4.failed deliveries are retried by the outbox reader
+
+### Design Considerations
+- Outbox table must be in the same database as business data
+- Outbox reader must handle duplicate delivery (consumer must be idempotent)
+- Outbox reader polling interval affects delivery latency
+- Define outbox message TTL and cleanup strategy
+
+## Saga Pattern
+
+### When to Use
+- When a business operation spans multiple services and requires distributed transaction semantics
+- When you need to rollback if any step fails
+
+### Choreography-Based Saga
+- Each service publishes events that trigger the next step
+- No central coordinator
+- Services must listen for events and decide what to do
+- Compensation: each service publishes a compensation event if a step fails
+
+### Orchestration-Based Saga
+- A central orchestrator calls each service in sequence
+- Orchestrator maintains saga state and decides which step to execute next
+- Compensation: orchestrator calls compensation operations in reverse order
+- More visible and debuggable, but adds a single point of failure
+
+### Design Considerations
+- Define saga steps and order
+- Define compensation for each step (what to do if this step or a later step fails)
+- Define saga timeout and expiration
+- Define how to handle partial failures (which steps completed, which need compensation)
+- Consider whether choreography or orchestration is more appropriate
+- Choreography: simpler, more decoupled, harder to debug
+- Orchestration: more visible, easier to debug, more coupled
+
+## Anti-Patterns
+
+- **Assuming strong consistency when using eventually consistent storage**: Be explicit about consistency guarantees
+- **Missing idempotency for queue consumers**: Queue delivery is at-least-once, consumers must be idempotent
+- **Infinite retries without backoff**: Always use exponential backoff with a maximum
+- **Distributed transactions across services**: Use saga pattern instead of trying to enforce ACID across services
+- **Outbox without deduplication**: Outbox pattern guarantees at-least-once delivery, consumers must handle duplicates
+- **Saga without compensation**: Every saga step must have a defined compensation action
+- **Missing conflict resolution for eventually consistent data**: Define how conflicts are resolved when they inevitably occur

skills/design-architecture/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: design-architecture
-description: "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."
+description: "Design system architecture based on PRD requirements. The Architect pipeline's core step, producing the single strict output file with all deliverables: Architecture Doc, Mermaid Diagrams, API Contract, DB Schema, ADR, NFR, Security Boundaries, Integration Boundaries, Observability, Consistency Model."
 ---
 
-This skill produces the complete architecture document for a feature.
+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/{date}-{feature}.md` (required)
+- `docs/prd/{feature}.md` (required)
 
 ## Primary Output (STRICT PATH)
 
-- `docs/architecture/{date}-{feature}.md`
+- `docs/architecture/{feature}.md`
 
-This is the **only** file artifact produced by the Architect pipeline. No intermediate files (research, analysis) are written to disk.
+This is the **only** file artifact produced by the Architect pipeline. No intermediate files (research, analysis) are written to disk. All deliverables — diagrams, schemas, specs, ADRs — must be embedded within this single document.
-
-**Save architecture to:** `docs/architecture/{date}-{feature}.md`
-- (User preferences for architecture location override this default)
 
 ## Hard Gate
 
@@ -28,10 +25,10 @@ Do NOT start this skill if the PRD has unresolved ambiguities that block archite
 
 You MUST complete these steps in order:
 
-1. **Read the PRD** at `docs/prd/{date}-{feature}.md` end-to-end to understand all requirements
+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 domains** as needed - reference relevant knowledge contracts during design:
+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
@@ -40,21 +37,39 @@ You MUST complete these steps in order:
    - `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
+   - `security-boundary-design` when defining auth, authorization, tenant isolation
-5. **Ensure traceability** - every architectural decision must trace back to at least one PRD requirement
+   - `consistency-transaction-design` when defining consistency model, idempotency, saga
-6. **Write completeness check** - verify all required sections are present and substantive
+   - `integration-boundary-design` when defining external API integration patterns
-7. **Write the architecture document** to `docs/architecture/{date}-{feature}.md`
+   - `observability-design` when defining logs, metrics, traces, alerts, SLOs
+   - `migration-rollout-design` when defining rollout strategy, feature flags, rollback
+5. **Apply deliverable skills** to produce concrete artifacts:
+   - `generate_mermaid_diagram` when producing diagrams
+   - `design_database_schema` when producing database schema
+   - `generate_openapi_spec` when producing API specifications
+   - `write_adr` when documenting architectural decisions
+   - `evaluate_tech_stack` when evaluating technology choices
+6. **Ensure traceability** — every architectural decision must trace back to at least one PRD requirement
+7. **Write completeness check** — verify 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
 
 ## Architecture Document Template
 
 ```markdown
 # Architecture: {Feature Name}
 
-## System Overview
+## 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.
+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.
-
-Use text or ASCII diagrams for component relationships.
 
 ### Requirement Traceability
 
@@ -62,72 +77,30 @@ Use text or ASCII diagrams for component relationships.
 |----------------|------------------------|
 | ... | ... |
 
-## Frontend Architecture
+## System 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.
+Describe the complete system architecture including all services, databases, message queues, caches, and external integrations. Show how components are organized, what technology stack each uses, and how they communicate.
 
-### Component Hierarchy
+### Technology Stack
-### State Management
-### Routing Structure
-### Client-Side Caching
 
-## Backend Architecture
+| Layer | Technology | Justification |
+|-------|-----------|---------------|
+| Language | ... | ... |
+| Framework | ... | ... |
+| Database | ... | ... |
+| Queue | ... | ... |
+| Cache | ... | ... |
+| Infrastructure | ... | ... |
 
-Define backend architecture including service layers, module boundaries, and dependency flow. This section MUST be present for all features with backend implications.
+If the feature has no backend component, write `N/A` with a brief reason.
 
-### Service/Module Boundaries
+### Component Architecture
-### Layer Separation
-### Dependency Flow
-### Shared Utilities
 
-## API Definitions
+Describe each major component, its responsibility, and how it fits into the overall system.
-
-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.
+Define service boundaries with clear responsibilities and communication patterns.
 
 For each service or module:
 - Name and single responsibility
@@ -141,7 +114,67 @@ For each service or module:
 |------|----|---------|----------|---------|
 | ... | ... | ... | ... | ... |
 
-## Async Model
+## Data Flow
+
+Describe how data moves through the system end-to-end. Include:
+- Request lifecycle from entry point to response
+- Background job processing flow
+- Event propagation flow
+- Data transformation and enrichment steps
+
+## Database Schema
+
+Define all database tables, columns, indexes, partition keys, 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 with justification based on query patterns
+- Partition keys (where applicable)
+- Foreign key relationships
+
+### Entity Relationships
+
+Describe relationships between tables.
+
+### Denormalization Strategy
+
+If denormalization is applied, document which fields are denormalized, why, and the consistency implications.
+
+### Migration Strategy
+
+Notes on migration approach if schema changes affect existing data.
+
+## API Contract
+
+Define all API endpoints with full specifications. Use OpenAPI-style definitions for REST APIs. For gRPC APIs, define the service and method specifications.
+
+### Endpoint Catalog
+
+| Method | Path | Description | PRD Requirement |
+|--------|------|-------------|-----------------|
+| ... | ... | ... | ... |
+
+### Endpoint Details
+
+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)
+- Pagination and filtering (when applicable)
+- PRD functional requirement it satisfies
+
+### Error Codes
+
+Define consistent error codes and error response format.
+
+## Async / Queue Design
 
 Define asynchronous operations and their behavior. If the feature has no asynchronous requirements, write `N/A` with a brief reason.
 
@@ -155,6 +188,32 @@ For each async operation:
 - Ordering guarantees
 - Timeout and cancellation behavior
 
+## Consistency Model
+
+Define the consistency guarantees of the system.
+
+### Consistency Strategy
+- Strong vs eventual consistency per data domain
+- When eventual consistency is acceptable and why
+- Conflict resolution strategies
+
+### Idempotency Design
+
+For each idempotent operation:
+- Operation name
+- Idempotency key source and format
+- Key TTL and storage location
+- Duplicate request behavior
+- Collision handling
+
+### Deduplication & Retry
+- Deduplication strategy for messages and events
+- Retry policies and backoff strategies
+- 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.
@@ -174,61 +233,179 @@ Define error handling strategy across the system.
 
 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
+## Security Boundaries
 
-Define idempotent operations and their behavior. If the feature has no idempotency requirements, write `N/A` with a brief reason.
+Define security architecture for the system.
 
-For each idempotent operation:
+- Authentication mechanism
-- Operation name
+- Authorization model (RBAC, ABAC, etc.)
-- Idempotency key source and format
+- Service identity and service-to-service auth
-- Key TTL and storage location
+- Token propagation strategy
-- Duplicate request behavior
+- Tenant isolation (multi-tenancy model)
-- Collision handling
+- Secret management approach
+- Audit logging requirements
 
-## Architectural Decision Records
+If the feature has no security implications, write `N/A` with a brief reason.
 
-For each significant architectural decision:
+## Integration Boundaries
 
-### ADR-{N}: {Decision Title}
+Define all integrations with external systems.
+
+For each external system integration:
+- External system name and purpose
+- Integration pattern (API call, webhook, polling, event subscription)
+- Rate limits and quotas
+- Failure modes and fallback behavior
+- Retry strategy
+- Data contract (request/response schemas)
+- Authentication mechanism
+
+If the feature has no external integrations, write `N/A` with a brief reason.
+
+## Observability
+
+Define observability strategy for the system.
+
+### Logs
+- Log levels and what to log
+- Structured logging format
+- Log aggregation strategy
+
+### Metrics
+- Key business metrics
+- Key system metrics
+- Metric naming conventions
+
+### Traces
+- Distributed tracing strategy
+- Correlation ID propagation
+- Span boundaries
+
+### Alerts
+- Alert conditions and thresholds
+- Alert routing and escalation
+
+### SLOs
+- Availability SLOs
+- Latency SLOs
+- Error budget
+
+## Scaling Strategy
+
+Define how the system scales based on NFRs.
+
+- Horizontal scaling approach (which components scale independently)
+- Vertical scaling considerations
+- Database scaling strategy (read replicas, sharding, partitioning)
+- Cache scaling strategy
+- Queue scaling strategy
+- Auto-scaling policies (when applicable)
+- Bottleneck analysis
+
+## Non-Functional Requirements
+
+Document all NFRs from the PRD and how the architecture addresses each one.
+
+| NFR | Requirement | Architectural Decision | Verification Method |
+|-----|-------------|----------------------|---------------------|
+| Performance | ... | ... | ... |
+| Availability | ... | ... | ... |
+| Scalability | ... | ... | ... |
+| Security | ... | ... | ... |
+| Compliance | ... | ... | ... |
+
+## Mermaid Diagrams
+
+Produce at minimum the following diagrams embedded in the document.
+
+### System Architecture Diagram
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Database]
+    B --> D[Queue]
+```
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Service
+    participant DB
+    Client->>Service: Request
+    Service->>DB: Query
+    DB-->>Service: Result
+    Service-->>Client: Response
+```
+
+### Data Flow Diagram
+
+```mermaid
+graph LR
+    A[Source] --> B[Processing]
+    B --> C[Storage]
+    B --> D[Output]
+```
+
+Additional diagrams as needed (event flow, state machine, etc.).
+
+## ADR
+
+Document significant architectural decisions.
+
+### ADR-001: {Decision Title}
 
-- **Decision**: What was decided
 - **Context**: Why this decision was needed, including which PRD requirements drove it
-- **Alternatives**: What other options were considered
+- **Decision**: What was decided
-- **Rationale**: Why this option was chosen
 - **Consequences**: What trade-offs or implications result
+- **Alternatives**: What other options were considered
+
+(Add additional ADRs as needed for each significant decision.)
+
+## Risks
+
+Identify and document architectural 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. Every PRD functional requirement is traced to at least one architectural component
+1. All 18 required sections are present (or explicitly marked N/A with reason)
-2. Every PRD NFR is traced to at least one architectural decision
+2. Every PRD functional requirement is traced to at least one architectural component
-3. All 9 required sections are present (or explicitly marked N/A with reason)
+3. Every PRD NFR is traced to at least one architectural decision
 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
+9. ADRs exist for all significant decisions (minimum 1)
-10. No architectural element exists without traceability to a PRD requirement
+10. At least 3 Mermaid diagrams are present (system, sequence, data flow)
-
+11. Service boundaries are aligned with domain responsibilities
-Add explicit detail for these when relevant:
+12. Security boundaries are defined
-- Security boundaries and authentication
+13. Integration boundaries are defined for all external systems
-- Scalability considerations
+14. Observability strategy covers logs, metrics, and traces
-- Performance-critical paths
+15. Consistency model is explicit about strong vs eventual guarantees
-- Data consistency requirements
+16. No architectural element exists without traceability to a PRD requirement
 
 ## Guardrails
 
@@ -237,7 +414,9 @@ 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
+- Define error handling, retry, and consistency strategies
+- Define security boundaries and integration patterns
+- Produce Mermaid diagrams, DB schemas, API specs, and ADRs
 - Make architectural decisions with clear rationale and alternatives
 - Ensure traceability to PRD requirements
 
@@ -248,7 +427,7 @@ Do not:
 - 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`
+- Produce any file artifact other than `docs/architecture/{feature}.md`
 
 The Architect defines HOW the system is structured.
 The Engineering defines HOW the code is written.

skills/design_database_schema/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: design_database_schema
+description: "Produce database schema definitions including tables, collections, partition keys, indexes, relationships, denormalization strategy, and migration strategy. Supports PostgreSQL, Cassandra, MongoDB, Redis, SurrealDB. A deliverable skill referenced by design-architecture."
+---
+
+This skill provides guidance and format requirements for producing database schema definitions within the architecture document.
+
+This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when producing database schema artifacts.
+
+## Purpose
+
+The Architect must produce detailed database schema definitions that are specific enough for implementation. Schemas define the data layer of the system and must include tables, fields, indexes, partition keys, relationships, and migration strategies.
+
+## Supported Databases
+
+When designing database schema, consider the appropriate database for each data domain:
+
+| Database | Best For | Not Ideal For |
+|----------|----------|---------------|
+| PostgreSQL | Relational data, ACID transactions, complex queries | Massive write throughput, wide-column access patterns |
+| Cassandra | High write throughput, time-series, wide-column access patterns | Complex joins, ACID transactions, ad-hoc queries |
+| MongoDB | Document data, flexible schema, rapid iteration | Complex joins, strict ACID, relational data |
+| Redis | Caching, sessions, rate limiting, real-time leaderboards | Persistent primary data, complex queries |
+| SurrealDB | Multi-model data, real-time, graph relationships | Unknown maturity, limited ecosystem |
+
+## Schema Definition Format
+
+Each table/collection must include:
+
+### Table Definition
+
+```markdown
+### {table_name}
+
+**Purpose**: {Brief description of what this table stores}
+
+| Column | Type | Constraints | Default | Description |
+|--------|------|-------------|---------|-------------|
+| id | UUID | PK, NOT NULL | gen_random_uuid() | Primary key |
+| ... | ... | ... | ... | ... |
+
+**Indexes**:
+
+| Index Name | Columns | Type | Justification |
+|-----------|---------|------|---------------|
+| idx_{table}_{columns} | {columns} | B-tree / Hash / GIN | {query pattern this index supports} |
+
+**Partition Key**: {partition_key} (if applicable)
+
+**Foreign Keys**:
+
+| Column | References | On Delete |
+|--------|-----------|-----------|
+| {column} | {table}.{column} | CASCADE / SET NULL / RESTRICT |
+```
+
+### Collection Definition (for document databases)
+
+```markdown
+### {collection_name}
+
+**Purpose**: {Brief description}
+
+**Document Schema**:
+- `{field}`: `{type}` — {description}
+- ...
+
+**Indexes**:
+
+| Index Name | Fields | Type | Justification |
+|-----------|--------|------|---------------|
+| ... | ... | ... | ... |
+
+**Partition Key**: {partition_key} (if applicable)
+```
+
+## Required Schema Elements
+
+### Tables / Collections
+- Every entity identified in the architecture must have a table or collection definition
+- Each table must have a clear purpose statement
+- Each field must have type, constraints, and description
+
+### Indexes
+- Every index must be justified by a specific query pattern
+- Consider composite indexes for multi-column queries
+- Consider partial indexes for filtered queries
+- Consider unique indexes for business constraints
+
+### Partition Keys (when applicable)
+- Define partition keys for Cassandra, DynamoDB, or similar databases
+- Justify partition key choice based on access patterns
+- Document partition distribution expectations
+
+### Relationships
+- Define foreign key relationships with referential integrity constraints
+- Document one-to-one, one-to-many, many-to-many relationships
+- Define junction tables for many-to-many relationships
+- Document data ownership: each piece of data belongs to exactly one service
+
+### Denormalization Strategy
+- Document any intentional denormalization
+- Justify each denormalization decision with a specific read pattern
+- Describe the consistency implications of each denormalization
+- Define the synchronization mechanism for denormalized data
+
+### Migration Strategy
+- Document migration approach for schema changes
+- Define backward-compatible migration strategy
+- Note any data migration steps required
+- Define rollback strategy for schema changes
+
+## Knowledge Contract Reference
+
+This deliverable skill works alongside the `data-modeling` knowledge contract:
+- `data-modeling` provides the theoretical guidance on data modeling principles
+- This skill provides the concrete output format and completeness requirements
+
+## Embedding in Architecture Document
+
+All database schema definitions must be embedded within the `## Database Schema` section of `docs/architecture/{feature}.md`.
+
+Do NOT produce separate schema files. All schema definitions must be within the single architecture document.

skills/evaluate_tech_stack/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: evaluate_tech_stack
+description: "Evaluate and recommend technology stack including language, framework, database, queue, cache, and infrastructure. Document pros, cons, and justification for each choice. A deliverable skill referenced by design-architecture."
+---
+
+This skill provides guidance and format requirements for evaluating and recommending the technology stack within the architecture document.
+
+This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when evaluating technology choices.
+
+## Purpose
+
+The Architect must evaluate the technology stack for the system, considering requirements from the PRD, existing systems, team expertise, and operational constraints. Each technology choice must be justified with pros, cons, and rationale.
+
+## Technology Stack Evaluation Format
+
+When evaluating the technology stack for a feature, produce a structured evaluation for each stack layer:
+
+```markdown
+### {Layer}: {Technology}
+
+- **Pros**:
+  - {Specific advantage relevant to this use case}
+  - {Another advantage}
+
+- **Cons**:
+  - {Specific disadvantage relevant to this use case}
+  - {Another disadvantage}
+
+- **Why Chosen**:
+  - {Specific rationale tied to PRD requirements}
+  - {Why this technology is the best fit for this use case}
+
+- **Alternatives Considered**:
+  - {Alternative 1}: {Brief reason why not chosen}
+  - {Alternative 2}: {Brief reason why not chosen}
+```
+
+## Evaluation Layers
+
+### Language
+- Primary programming language for each service
+- Justification based on: ecosystem, performance, team expertise, library support
+- Consider: type safety, concurrency model, deployment size, development velocity
+
+### Framework
+- Application framework for each service
+- Justification based on: maturity, community, performance, developer experience
+- Consider: built-in features, middleware ecosystem, testing support, documentation
+
+### Database
+- Primary and secondary databases
+- Justification based on: data model fit, query patterns, write patterns, consistency requirements, scale expectations
+- Consider: ACID vs eventual consistency, operational complexity, backup/restore, migration path
+
+### Queue / Message Broker
+- Message queue or event streaming platform
+- Justification based on: throughput requirements, ordering guarantees, delivery semantics, durability
+- Consider: at-least-once vs exactly-once, partitioning, consumer groups, operational complexity
+
+### Cache
+- Caching layer
+- Justification based on: access patterns, TTL requirements, invalidation strategy
+- Consider: cache-aside vs read-through/write-through, memory limits, persistence options
+
+### Infrastructure
+- Deployment infrastructure
+- Justification based on: scalability, cost, team expertise, deployment model
+- Consider: containerization, orchestration, service mesh, CDN, monitoring
+
+## Decision Principles
+
+When evaluating technology choices, prioritize:
+
+1. **Simplicity**: Choose the simplest technology that meets requirements
+2. **Battle-tested**: Prefer technologies with proven production track records
+3. **Team expertise**: Prefer technologies the team already knows, unless the learning curve is justified
+4. **Operational maturity**: Prefer technologies with good monitoring, tooling, and debugging support
+5. **Community and ecosystem**: Prefer technologies with active communities and rich ecosystems
+6. **Fit for purpose**: Choose technologies that match the specific data model, access pattern, and consistency requirements
+
+## Anti-Patterns
+
+Avoid:
+- Choosing technologies based on hype or fashion without PRD justification
+- Choosing different technologies for each service without good reason (polyglot penalty)
+- Choosing bleeding-edge technologies without a fallback plan
+- Choosing technologies that require significant operational investment without clear benefit
+- Choosing technologies that don't match the data model or access pattern
+
+## Knowledge Contract Reference
+
+This deliverable skill works alongside the `storage-knowledge` and `architecture-patterns` knowledge contracts:
+- `storage-knowledge` provides detailed comparison of storage technologies
+- `architecture-patterns` provides guidance on which patterns suit which technologies
+
+## Embedding in Architecture Document
+
+Technology stack evaluation must be embedded within the `## System Architecture` section (Technology Stack subsection) of `docs/architecture/{feature}.md`.
+
+For significant technology decisions that affect the overall system structure, also document them as ADRs in the `## ADR` section.
+
+Do NOT produce separate evaluation documents. All technology evaluations must be within the single architecture document.

skills/finalize-architecture/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: finalize-architecture
+description: "Final completeness check and format validation for the architecture document. The Architect pipeline's final step before handoff to Planner."
+---
+
+This skill performs a final completeness check and format validation on the architecture document after challenge and revision.
+
+**Announce at start:** "I'm using the finalize-architecture skill to perform the final completeness check on the architecture document."
+
+## Primary Input
+
+- `docs/architecture/{feature}.md`
+
+## Primary Output (STRICT PATH)
+
+- Final `docs/architecture/{feature}.md`
+
+This is the **only** file artifact in the Architect pipeline. Finalization results are applied directly to this file.
+
+## Process
+
+You MUST complete these steps in order:
+
+### Step 1: Section Completeness Check
+
+Verify all 18 required sections are present and substantive (or explicitly marked N/A with reason):
+
+1. Overview
+2. System Architecture
+3. Service Boundaries
+4. Data Flow
+5. Database Schema
+6. API Contract
+7. Async / Queue Design
+8. Consistency Model
+9. Error Model
+10. Security Boundaries
+11. Integration Boundaries
+12. Observability
+13. Scaling Strategy
+14. Non-Functional Requirements
+15. Mermaid Diagrams
+16. ADR
+17. Risks
+18. Open Questions
+
+For each missing or empty section, add a placeholder with `N/A — [reason]` or flag it as a gap that must be filled.
+
+### Step 2: Mermaid Diagram Verification
+
+Verify the document contains at minimum:
+- **1 System Architecture Diagram** — showing all services, databases, queues, and external integrations
+- **1 Sequence Diagram** — showing the primary happy-path interaction flow
+- **1 Data Flow Diagram** — showing how data moves through the system
+
+For each diagram, verify:
+- Mermaid syntax is valid
+- All components referenced in the architecture are present in the diagram
+- No orphan components exist in diagrams that are not described elsewhere
+
+### Step 3: Database Schema Verification
+
+Verify the Database Schema section contains:
+- All tables with field names, types, constraints, and defaults
+- Indexes with justification based on query patterns
+- Partition keys where applicable
+- Relationships (foreign keys, references)
+- Denormalization strategy where applicable
+- Migration strategy notes
+
+### Step 4: API Contract Verification
+
+Verify the API Contract section contains:
+- All endpoints with method, path, request schema, response schema
+- Error codes and error response schemas
+- Idempotency requirements per endpoint (where applicable)
+- Pagination and filtering (where applicable)
+- Authentication requirements
+
+### Step 5: ADR Verification
+
+Verify the ADR section contains at minimum 1 ADR with:
+- ADR number and title
+- Context
+- Decision
+- Consequences
+- Alternatives considered
+
+### Step 6: Traceability Verification
+
+Verify:
+- Every API endpoint traces to a PRD functional requirement
+- Every DB table traces to a data requirement
+- Every service boundary traces to a domain responsibility
+- Every async flow traces to a PRD requirement
+- Every security boundary traces to a requirement
+- Every integration boundary traces to an external system requirement
+
+### Step 7: Format Verification
+
+Verify:
+- The document follows the exact section ordering from the template
+- Section headings use proper markdown hierarchy
+- Mermaid code blocks use ```mermaid syntax
+- Tables use proper markdown table syntax
+- No external files are referenced (all content is within the single document)
+
+### Step 8: Architecture Review Gate
+
+Verify the Architecture Review section from `challenge-architecture`:
+- Gate decision is either PASS or CONDITIONAL PASS
+- All identified issues have been addressed
+- No unresolved blockers remain
+
+## Finalization Checklist
+
+- [ ] All 18 required sections present and substantive (or N/A with reason)
+- [ ] At least 3 Mermaid diagrams present (system, sequence, data flow)
+- [ ] Database Schema has complete table definitions
+- [ ] API Contract has complete endpoint specifications
+- [ ] At least 1 ADR present with full format
+- [ ] All elements trace to PRD requirements
+- [ ] Architecture Review gate is PASS or CONDITIONAL PASS
+- [ ] Document format follows template ordering
+- [ ] No external file references (all content is inline)
+- [ ] Risks section is populated
+- [ ] Open Questions section is populated (or explicitly states "None")
+
+## Guardrails
+
+This is a pure validation and formatting skill.
+
+Do:
+- Verify completeness of all 18 sections
+- Validate Mermaid diagram syntax and coverage
+- Validate API contract completeness
+- Validate database schema completeness
+- Validate ADR format
+- Validate traceability
+- Fix formatting issues directly in `docs/architecture/{feature}.md`
+
+Do not:
+- Design new architecture
+- Change architectural decisions
+- Add significant new content that wasn't validated in challenge-architecture
+- Produce any file artifact other than `docs/architecture/{feature}.md`
+
+## Transition
+
+After finalization is complete and all checks pass, the architecture document is ready for handoff to the Planner. The Planner reads only `docs/architecture/{feature}.md`.

skills/generate_mermaid_diagram/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: generate_mermaid_diagram
+description: "Produce Mermaid diagrams for system architecture, sequence flows, data flows, event flows, and state machines. A deliverable skill referenced by design-architecture."
+---
+
+This skill provides guidance and format requirements for producing Mermaid diagrams within the architecture document.
+
+This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when producing visual architecture artifacts.
+
+## Purpose
+
+The Architect must produce Mermaid diagrams to visualize the system architecture. Diagrams are embedded directly in the architecture document within the `## Mermaid Diagrams` section.
+
+## Required Diagrams
+
+The architecture document must contain at minimum:
+
+### 1. System Architecture Diagram
+
+Shows all services, databases, queues, caches, and external integrations and how they connect.
+
+```mermaid
+graph TD
+    Client[Client App] --> Gateway[API Gateway]
+    Gateway --> AuthService[Auth Service]
+    Gateway --> OrderService[Order Service]
+    OrderService --> OrderDB[(Order DB)]
+    OrderService --> EventBus[Event Bus]
+    EventBus --> NotificationService[Notification Service]
+    NotificationService --> NotificationDB[(Notification DB)]
+    AuthService --> AuthDB[(Auth DB)]
+    AuthService --> Cache[(Redis Cache)]
+```
+
+### 2. Sequence Diagram
+
+Shows the primary happy-path interaction flow between components.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant GW as API Gateway
+    participant Auth as Auth Service
+    participant Order as Order Service
+    participant DB as Order DB
+    participant EventBus as Event Bus
+
+    C->>GW: POST /orders
+    GW->>Auth: Validate Token
+    Auth-->>GW: Token Valid
+    GW->>Order: Create Order
+    Order->>DB: Insert Order
+    DB-->>Order: Order Created
+    Order->>EventBus: Publish OrderCreated
+    Order-->>GW: 201 Created
+    GW-->>C: Order Response
+```
+
+### 3. Data Flow Diagram
+
+Shows how data moves through the system, including transformations and storage points.
+
+```mermaid
+graph LR
+    A[User Input] --> B[Validation]
+    B --> C[Command Handler]
+    C --> D[(Write DB)]
+    C --> E[Event Publisher]
+    E --> F[Event Bus]
+    F --> G[Projection Handler]
+    G --> H[(Read DB)]
+    H --> I[Query API]
+```
+
+## Optional Diagrams
+
+Produce these additional diagrams when the architecture requires them:
+
+### Event Flow Diagram
+
+Shows how events propagate through the system.
+
+```mermaid
+graph TD
+    A[Order Created] --> B[Event Bus]
+    B --> C[Inventory Update]
+    B --> D[Notification Sent]
+    B --> E[Analytics Recorded]
+    C --> F[(Inventory DB)]
+    D --> G[Email Service]
+    E --> H[(Analytics DB)]
+```
+
+### State Machine Diagram
+
+Shows entity lifecycle and state transitions.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending: Order Created
+    Pending --> Confirmed: Payment Received
+    Pending --> Cancelled: Cancel Request
+    Confirmed --> Processing: Process Start
+    Processing --> Completed: Process Done
+    Processing --> Failed: Process Error
+    Failed --> Processing: Retry
+    Completed --> [*]
+    Cancelled --> [*]
+```
+
+## Diagram Guidelines
+
+### General Rules
+- Use consistent naming conventions across all diagrams
+- All components in diagrams must be described in the architecture document text
+- No orphan components: every diagram element must appear in the document text
+- Use meaningful labels, not abbreviations (unless abbreviation is defined in the document)
+- Include external systems when they are part of the data flow
+
+### Component Naming
+- Services: PascalCase (e.g., `OrderService`, `AuthService`)
+- Databases: PascalCase with DB suffix (e.g., `OrderDB`)
+- Queues/Topics: PascalCase descriptive name (e.g., `OrderEventBus`)
+- External systems: Descriptive name (e.g., `PaymentGateway`)
+
+### Relationship Labels
+- Label all edges/connections with the interaction type
+- Use `-->` for synchronous calls
+- Use `-.->` for asynchronous messages/events
+- Include the protocol or verb when relevant (HTTP, gRPC, AMQP)
+
+## Embedding in Architecture Document
+
+All diagrams must be embedded within the `## Mermaid Diagrams` section of `docs/architecture/{feature}.md` using:
+
+````
+```mermaid
+graph TD
+    ...
+```
+````
+
+Do NOT produce separate diagram files. All diagrams must be within the single architecture document.

skills/generate_openapi_spec/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: generate_openapi_spec
+description: "Produce OpenAPI or gRPC API contract definitions including endpoints, request/response schemas, error codes, idempotency, pagination, and filtering. A deliverable skill referenced by design-architecture."
+---
+
+This skill provides guidance and format requirements for producing API contract definitions within the architecture document.
+
+This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when producing API contract artifacts.
+
+## Purpose
+
+The Architect must produce API contract definitions that are specific enough for implementation. API contracts define the interface between services and between clients and the system.
+
+## REST API (OpenAPI Style)
+
+For REST APIs, use OpenAPI-style definitions within the architecture document.
+
+### Endpoint Definition Format
+
+Each endpoint must include:
+
+```markdown
+### {METHOD} {path}
+
+**Description**: {What this endpoint does}
+
+**Authentication**: {None / Bearer Token / API Key / mTLS}
+
+**Idempotency**: {None / Idempotent by method / Requires Idempotency-Key header}
+
+**Request**:
+
+| Field | Location | Type | Required | Description |
+|-------|----------|------|----------|-------------|
+| ... | header / path / query / body | ... | yes/no | ... |
+
+**Request Body** (if applicable):
+```json
+{
+  "field1": "type",
+  "field2": "type"
+}
+```
+
+**Response** (Success):
+
+| Status Code | Description | Response Schema |
+|-------------|-------------|-----------------|
+| 200 / 201 | ... | ... |
+
+**Response Body**:
+```json
+{
+  "field1": "type",
+  "field2": "type"
+}
+```
+
+**Error Responses**:
+
+| Status Code | Error Code | Description | When |
+|-------------|-----------|-------------|------|
+| 400 | INVALID_INPUT | ... | ... |
+| 401 | UNAUTHORIZED | ... | ... |
+| 404 | NOT_FOUND | ... | ... |
+| 409 | CONFLICT | ... | ... |
+| 429 | RATE_LIMITED | ... | ... |
+| 500 | INTERNAL_ERROR | ... | ... |
+
+**Pagination** (if applicable):
+- Default page size: {n}
+- Maximum page size: {n}
+- Pagination parameters: `offset` / `cursor`
+- Response includes: `total_count`, `has_more`
+
+**Filtering** (if applicable):
+- Supported filters: {list of filterable fields}
+- Filter operators: `eq`, `ne`, `gt`, `lt`, `in`, `contains`
+```
+
+### Error Response Format
+
+Define a consistent error response format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "details": [
+      {
+        "field": "field_name",
+        "message": "Specific error message"
+      }
+    ],
+    "request_id": "uuid"
+  }
+}
+```
+
+### Error Code Catalog
+
+Define system-wide error codes:
+
+```markdown
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| INVALID_INPUT | 400 | Request validation failed |
+| UNAUTHORIZED | 401 | Authentication required |
+| FORBIDDEN | 403 | Insufficient permissions |
+| NOT_FOUND | 404 | Resource not found |
+| CONFLICT | 409 | Resource already exists |
+| RATE_LIMITED | 429 | Too many requests |
+| INTERNAL_ERROR | 500 | Unexpected server error |
+| SERVICE_UNAVAILABLE | 503 | Dependent service unavailable |
+```
+
+## gRPC API
+
+For gRPC APIs, define the service and method specifications.
+
+### Service Definition Format
+
+```markdown
+### {ServiceName}
+
+**Package**: {package.name}
+
+#### {MethodName}
+
+**Request**: {MessageName}
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| ... | ... | ... | ... |
+
+**Response**: {MessageName}
+
+| Field | Type | Description |
+|-------|------|-------------|
+| ... | ... | ... |
+
+**Error Codes**:
+
+| Code | Description |
+|------|-------------|
+| INVALID_ARGUMENT | ... |
+| NOT_FOUND | ... |
+| ... | ... |
+
+**Idempotency**: {None / Idempotent / Requires request_id}
+```
+
+## Required API Contract Elements
+
+### Endpoints
+- Every functional requirement from the PRD must have at least one API endpoint
+- Each endpoint must map to the PRD functional requirement it satisfies
+
+### Request / Response Schemas
+- Every field must have type, required/optional, and description
+- Nested objects must be fully defined
+- Enum values must be listed
+
+### Error Codes
+- Define consistent error codes across the system
+- Differentiate client errors (4xx) from server errors (5xx) from business rule violations
+- Include error response format
+
+### Idempotency
+- Identify which endpoints require idempotency
+- Define idempotency mechanism (method-based, key-based)
+- Define idempotency key format and TTL
+
+### Pagination
+- Define pagination mechanism for all list endpoints
+- Specify default and maximum page sizes
+- Define pagination response format
+
+### Filtering
+- Define supported filter fields for list endpoints
+- Define filter operators
+- Define sort options
+
+### Rate Limiting (when applicable)
+- Define rate limit expectations per endpoint
+- Define rate limit headers and response format
+
+## Knowledge Contract Reference
+
+This deliverable skill works alongside the `api-contract-design` knowledge contract:
+- `api-contract-design` provides the theoretical guidance on API design principles
+- This skill provides the concrete output format and completeness requirements
+
+## Embedding in Architecture Document
+
+All API contract definitions must be embedded within the `## API Contract` section of `docs/architecture/{feature}.md`.
+
+Do NOT produce separate OpenAPI YAML or gRPC proto files. All API contracts must be within the single architecture document.

skills/idempotency-design/SKILL.md

@@ -1,165 +0,0 @@
----
-name: idempotency-design
-description: "Knowledge contract for designing idempotent operations, idempotency keys, TTL, storage, duplicate behavior, and collision handling. Referenced by design-architecture when designing idempotency."
----
-
-This is a knowledge contract, not a workflow skill. It is referenced by `design-architecture` when the architect is designing idempotent operations.
-
-## Core Principle
-
-Idempotency must be driven by PRD requirements. Do not add idempotency to operations that do not need it. Do not skip idempotency on operations that the PRD explicitly requires to be idempotent.
-
-Common PRD requirements that imply idempotency:
-- "The system must not create duplicates when the same request is submitted twice"
-- "Users should be able to retry failed submissions safely"
-- "Payment processing must be exactly-once"
-- "Webhook deliveries may be retried"
-
-## Identifying Idempotent Operations
-
-An operation needs idempotency when:
-- The client may retry due to network timeout or failure
-- The operation has side effects that must not be duplicated (creating resources, charging money, sending notifications)
-- The PRD explicitly requires safe retry behavior
-- The operation is triggered by an unreliable delivery mechanism (webhooks, message queues)
-
-An operation is naturally idempotent when:
-- It is a read operation (GET, HEAD, OPTIONS)
-- It is a delete operation where deleting a non-existent resource returns 404 or 204
-- It is a PUT that fully replaces a resource (set state to X)
-- It is an operation where duplicated execution produces the same result
-
-## Idempotency Key Strategy
-
-### Key Source
-- Client-generated: the client provides a unique key (e.g., UUID, order reference). Preferred for API operations.
-- Deterministic: derived from request content (e.g., hash of user_id + action + parameters). Preferred when the client cannot provide a key.
-- System-generated: the server assigns a key. Only for internal operations where the client does not participate.
-
-### Key Format
-- Define the key format explicitly (e.g., `UUID v7`, `{prefix}-{unique-identifier}`, `sha256(payload)`)
-- Keys must be unique across the entire scope of the operation
-- Keys must be reproducible: the same logical request must produce the same key
-
-### Key Scope
-- Per-user: key is unique within the user's context
-- per-resource-type: key is unique within the resource type (e.g., all payment creation)
-- Global: key is unique across the entire system
-
-Define the scope based on the PRD requirement. Tighter scope is preferred when possible.
-
-## Idempotency Key Storage
-
-### Where to Store
-- Database table (preferred for persistent idempotency)
-  - Table: `idempotency_keys`
-  - Columns: `key`, `operation_type`, `request_hash`, `response_hash`, `status`, `created_at`, `expires_at`
-  - Index: unique index on `(key, operation_type)`
-- Redis (preferred for ephemeral idempotency with TTL)
-  - Key: `idempotency:{operation_type}:{key}`
-  - Value: serialized response or status reference
-  - TTL: set to expire after the idempotency window
-
-### Storage Decision Framework
-- Use database when: idempotency must survive restarts, keys must be queryable, audit trail is required
-- Use Redis when: idempotency is time-bounded, fast lookup is critical, keys can expire, persistence loss is acceptable
-
-## TTL (Time-to-Live)
-
-Define for each idempotent operation:
-- TTL duration: how long duplicate detection is active
-- TTL basis: when does the clock start (key creation time, last access time)
-- TTL scope: does the key expire or is it permanent
-
-### TTL Duration Guidelines
-- API operations: typically 24 hours (allows client retries within a day)
-- Payment operations: typically 30 days (matches settlement windows)
-- Webhook processing: typically 7 days (matches delivery retry windows)
-- Internal operations: match the operation's natural retry window
-
-### TTL Behavior
-- After TTL expires, the key is removed and a new request with the same key is processed as a new operation
-- Define whether TTL is strictly enforced (hard delete) or softly enforced (soft delete, kept for audit)
-
-## Duplicate Request Behavior
-
-When a duplicate request is detected (key already exists):
-
-### During Processing
-- The original request is still being processed
-- Return `202 Accepted` with a status URL (for async operations)
-- Or return `409 Conflict` if the client should not retry yet
-
-### After Successful Processing
-- Return the original successful response (stored or reconstructable)
-- Must return the same status code and response body as the original
-- This is the most common and recommended behavior
-
-### After Failed Processing
-- If the original processing permanently failed, allow retry with the same key
-- If the original processing was interrupted (timeout, crash), allow retry with the same key
-- Define whether the client must generate a new key or can reuse the original
-
-Define for each idempotent operation:
-- What the client receives when submitting a duplicate during processing
-- What the client receives when submitting a duplicate after success
-- What the client receives when submitting a duplicate after failure
-
-## Collision Handling
-
-A key collision occurs when two different logical requests produce the same idempotency key.
-
-### Prevention
-- Use UUID v7 or similar globally unique identifiers for client-generated keys
-- Use sufficiently random hash functions for content-derived keys
-- Include enough context in content-derived keys (user_id + action + parameters)
-
-### Detection
-- Compare the request hash of the new request with the stored request hash
-- If hashes match: this is a true duplicate, return the stored response
-- If hashes differ: this is a collision, different logical requests produced the same key
-
-### Resolution
-- Reject the new request with `409 Conflict` and ask the client to use a new key
-- This is the safest and most common approach
-- Never overwrite the original request's result with a different request's result
-
-## Idempotency for Different Operation Types
-
-### Create Operations
-- Most common use case for idempotency
-- Key: client-generated UUID or deterministic hash
-- Behavior: return original created resource on duplicate
-- Status codes: `201 Created` on first request, `200 OK` with original resource on duplicate
-
-### Update Operations
-- PUT operations that fully replace state are naturally idempotent
-- PATCH operations that set state to a specific value are idempotent
-- PATCH operations that increment or append are NOT naturally idempotent
-- Key: derived from resource ID + operation type if not naturally idempotent
-
-### Delete Operations
-- Naturally idempotent: deleting an already-deleted resource returns `204 No Content` or `404 Not Found`
-- Define which behavior the API contract specifies and stick with it consistently
-
-### Payment Operations
-- Must be idempotent (regulatory and financial requirement)
-- Key: payment reference or client-generated UUID
-- TTL: match settlement window (typically 30 days)
-- Behavior: return original payment result on duplicate; never double-charge
-
-### Webhook Processing
-- Must be idempotent (delivery services may retry)
-- Key: webhook event ID or delivery attempt ID
-- TTL: match delivery retry window (typically 7 days)
-- Behavior: skip processing on duplicate, return success
-
-## Anti-Patterns
-
-- Adding idempotency to naturally idempotent operations (wastes resources)
-- Not adding idempotency to operations the PRD requires to be safe for retry
-- Storing idempotency keys with no TTL, causing unbounded table growth
-- Using content-derived keys with insufficient entropy, causing collisions
-- Overwriting stored results on key collision instead of rejecting
-- Implementing idempotency at the wrong layer (e.g., only at the database level without API-level coordination)
-- Not documenting which operations are idempotent and which are not

skills/integration-boundary-design/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: integration-boundary-design
+description: "Knowledge contract for integration boundary design. Provides principles and patterns for external API integration, webhook handling, polling, retry strategies, rate limiting, and failure mode handling. Referenced by design-architecture when defining integration boundaries."
+---
+
+This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing integration boundaries. It does not produce artifacts directly.
+
+## Core Principles
+
+### Integration Isolation
+- External system failures must not cascade into system failures
+- Circuit breakers must protect internal services from external failures
+- Integration code must be isolated from business logic (anti-corruption layer)
+
+### Explicit Contracts
+- Every external integration must have an explicitly defined contract
+- Contracts must include request/response schemas, error codes, and SLAs
+- Changes to contracts must be versioned and backward-compatible whenever possible
+
+### Assume Failure
+- External systems will fail, timeout, return unexpected data, and change without notice
+- Design for failure: define timeout, retry, and fallback for every integration
+- Never assume external system availability or correctness
+
+## External API Integration
+
+### Patterns
+- **Synchronous API call**: Request-response, immediate feedback
+- **Asynchronous API call**: Request acknowledged, result via callback or polling
+- **Batch API call**: Accumulate requests and send in bulk
+- **Streaming API**: Continuous stream of data (SSE, WebSocket, gRPC streaming)
+
+### Design Considerations
+- Define timeout for every outbound API call (default: 5-30 seconds depending on SLA)
+- Define retry strategy for every outbound call (max retries, backoff, jitter)
+- Define circuit breaker thresholds (error rate, timeout rate, consecutive failures)
+- Define fallback behavior when circuit is open (cached data, default response, error)
+- Define data transformation at the boundary (anti-corruption layer)
+- Monitor all external calls: latency, error rate, circuit breaker state
+
+## Webhook Handling
+
+### Inbound Webhooks (Receiving)
+- Define webhook signature verification (HMAC, asymmetric)
+- Define idempotency for webhook processing (external systems may deliver duplicates)
+- Define webhook ordering assumptions (ordered vs unordered)
+- Define webhook timeout and response (always respond 200 quickly, process asynchronously)
+- Define webhook retry handling (what if processing fails?)
+
+### Outbound Webhooks (Sending)
+- Define webhook delivery guarantee (at-least-once, at-most-once)
+- Define webhook retry strategy (max retries, backoff, jitter)
+- Define webhook payload format (versioned, backward-compatible)
+- Define webhook authentication (HMAC signature, OAuth2, API key)
+- Define webhook status tracking (delivered, failed, pending)
+
+## Polling
+
+### When to Use Polling
+- When the external system doesn't support webhooks or streaming
+- When the external system has a polling-based API by design
+- When real-time updates are not required
+
+### Design Considerations
+- Define polling interval based on data freshness requirements
+- Use incremental polling (ETag, Last-Modified, since parameter) to avoid redundant data transfer
+- Define how to handle polling failures (skip and retry next interval)
+- Define how to handle data gaps (missed polls due to downtime)
+- Consider long-polling as an alternative when supported
+
+## Retry Strategy
+
+### Retry Decision Tree
+1. Is the error retryable? (network errors, timeouts, 429, 503 are typically retryable)
+2. What is the retry strategy? (exponential backoff with jitter)
+3. What is the max retry count? (3-5 is typical for transient errors)
+4. What is the max total retry time? (prevent infinite retry loops)
+5. What to do after max retries? (DLQ, alert, manual intervention)
+
+### Backoff Strategies
+- **Exponential backoff**: Delay doubles each retry (1s, 2s, 4s, 8s...)
+- **Exponential backoff with jitter**: Add randomness to prevent thundering herd
+- **Linear backoff**: Fixed additional delay each retry (1s, 2s, 3s, 4s...)
+- **Fixed retry**: Same delay every retry (simple but ineffective)
+
+### Retry Budget
+- Define maximum retries per time window (prevent retry storms)
+- Define retry budget per external system (don't overwhelm a recovering system)
+- Consider separate retry budgets for critical vs non-critical operations
+
+## Rate Limiting
+
+### Patterns
+- **Token bucket**: Fixed rate refill, burst-capable, most common
+- **Leaky bucket**: Fixed rate processing, smooths burst
+- **Fixed window**: Simple, but allows burst at window boundaries
+- **Sliding window**: More accurate than fixed window, slightly more complex
+
+### Design Considerations
+- Define rate limits per endpoint, per client, and per system
+- Define rate limit headers to return (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
+- Define response when rate limited (429 Too Many Requests with Retry-After header)
+- Define rate limit storage (Redis, memory, external service)
+- Define rate limit for outbound calls to external systems (respect their limits)
+
+## Failure Mode Handling
+
+### Failure Mode Classification
+- **Transient**: Network timeout, temporary service unavailable (retry with backoff)
+- **Permanent**: Invalid request, authentication failure (fail immediately, no retry)
+- **Partial**: Some data processed, some failed (compensate or retry partial)
+- **Cascading**: Failure in one service causing failures in others (circuit breaker)
+
+### Design Decision Matrix
+| Failure Type | Detection | Response |
+|-------------|-----------|----------|
+| Timeout | No response within threshold | Retry with backoff, circuit breaker |
+| 5xx Error | HTTP 500-599 | Retry with backoff, circuit breaker |
+| 429 Rate Limited | HTTP 429 | Backoff and retry after Retry-After |
+| 4xx Client Error | HTTP 400-499 | Fail immediately, log and alert |
+| Connection Refused | TCP connection failure | Circuit breaker, fail fast |
+| Invalid Data | Schema validation failure | Fail immediately, DLQ for investigation |
+
+### Circuit Breaker States
+- **Closed**: Normal operation, requests pass through
+- **Open**: Failure threshold exceeded, requests fail fast (fallback)
+- **Half-Open**: After cooldown, allow test request; if success, close; if fail, stay open
+
+### Fallback Strategies
+- **Cached data**: Serve stale data from cache (with staleness warning)
+- **Default response**: Return a sensible default (for non-critical data)
+- **Graceful degradation**: Return partial data if some services are unavailable
+- **Queue and retry**: Store the request and process later when the system recovers
+- **Fail fast**: Return error immediately (for critical operations that can't be degraded)
+
+## Anti-Patterns
+
+- **Synchronous chain of external calls**: Minimize synchronous external calls in request path
+- **Missing timeout on outbound calls**: Always set a timeout, never wait indefinitely
+- **Missing circuit breaker for external systems**: External failures must not cascade
+- **Missing idempotency for retries**: Retries will cause duplicate processing
+- **Missing rate limiting for outbound calls**: Will hit external system rate limits
+- **Missing data transformation at boundary**: External data models must not leak into internal models
+- **Missing monitoring on external calls**: External call latency and error rates must be tracked

skills/migration-rollout-design/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: migration-rollout-design
+description: "Knowledge contract for migration and rollout design. Provides principles and patterns for backward compatibility, rollout strategies, canary deployments, feature flags, schema evolution, and rollback. Referenced by design-architecture when defining migration and rollout strategy."
+---
+
+This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing migration and rollout strategies. It does not produce artifacts directly.
+
+## Core Principles
+
+### Backward Compatibility First
+- New versions must coexist with old versions during migration
+- APIs must be backward-compatible until all consumers have migrated
+- Database schemas must support both old and new code during migration
+- Never break existing functionality during migration
+
+### Incremental Over Big-Bang
+- Migrate incrementally, one step at a time
+- Each step must be independently deployable and reversible
+- Test each step before proceeding to the next
+- Big-bang migrations have higher risk and harder rollback
+
+### Rollback by Default
+- Every migration step must have a clear rollback plan
+- Practice rollback before you need it
+- Automated rollback is preferred over manual rollback
+- Feature flags enable instant rollback without deployment
+
+## Rollout Strategies
+
+### Blue-Green Deployment
+- Maintain two identical environments (blue and green)
+- Deploy new version to the inactive environment
+- Switch traffic from active to inactive environment
+- If issues are detected, switch traffic back
+- **Best for**: Infrastructure-level deployments with full environment replication
+
+### Canary Deployment
+- Deploy new version to a small percentage of traffic (1%, 5%, 10%, 25%, 50%, 100%)
+- Monitor metrics at each stage before increasing traffic
+- If issues are detected, shift traffic back to the old version
+- **Best for**: Application-level deployments where you want to test with real traffic gradually
+
+### Rolling Deployment
+- Deploy new version to instances one at a time (or in small batches)
+- Old and new versions run side by side during the rollout
+- If issues are detected, stop the rollout and roll back the updated instances
+- **Best for**: Stateless services where instances can be updated independently
+
+### Feature Flag Deployment
+- Deploy new code with features disabled (feature flags set to false)
+- Enable features gradually using feature flags
+- Can enable per-user, per-tenant, per-percentage
+- If issues are detected, disable the feature flag instantly
+- **Best for**: Feature-level deployments where you want to decouple code deployment from feature release
+
+## Feature Flags
+
+### Types of Feature Flags
+- **Release flags**: Enable/disable new features during rollout (short-lived)
+- **Operational flags**: Enable/disable operational features (circuit breakers, maintenance mode)
+- **Experiment flags**: A/B testing and gradual rollout (medium-lived)
+- **Permission flags**: Enable features for specific users/tenants (long-lived)
+
+### Design Considerations
+- Feature flags must not add significant latency (evaluate quickly)
+- Feature flag evaluation must be consistent within a request (don't re-evaluate mid-request)
+- Feature flags must have a defined lifecycle: create, enable, monitor, remove
+- Remove feature flags after full rollout to prevent technical debt
+- Use a feature flag management service (not hardcoded flags)
+- Log feature flag evaluations for debugging
+
+### Feature Flag Rollout
+- Start with 0% (flag off)
+- Enable for internal users (dogfood)
+- Enable for a small percentage of users (canary)
+- Enable for all users (full rollout)
+- Monitor metrics at each stage
+- Remove the flag after full rollout
+
+## Schema Evolution
+
+### Additive Changes (Safe)
+- Add a new column with a default value
+- Add a new table
+- Add a new index (with caution for large tables)
+- Add a new optional field to an API response
+- Add a new API endpoint
+
+### Destructive Changes (Require Migration)
+- Remove a column (requires migration)
+- Rename a column (requires migration)
+- Change a column type (requires migration)
+- Remove a table (requires migration)
+- Remove an API endpoint (requires consumer migration)
+
+### Migration Strategy for Destructive Changes
+1. **Expand**: Add the new structure alongside the old (both exist)
+2. **Migrate**: Migrate data and code to use the new structure (both exist)
+3. **Contract**: Remove the old structure (only new exists)
+
+Example: Renaming a column
+1. Add new column, keep old column, dual-write to both
+2. Migrate existing data from old to new column
+3. Update all reads to use new column
+4. Remove old column
+
+### Database Migration Best Practices
+- Every migration must be reversible (up and down migration)
+- Test migrations against production-like data volumes
+- Run migrations in a transaction when possible
+- For large tables, use online schema change tools (pt-online-schema-change, gh-ost)
+- Never lock a production table for more than seconds during a migration
+
+## Rollback
+
+### Application Rollback
+- Revert to previous deployment version
+- Feature flag disable (instant, no deployment needed)
+- Blue-green switch (instant, requires environment)
+- Canary shift-back (requires redirecting traffic)
+- Rolling redeploy of previous version (requires new deployment)
+
+### Database Rollback
+- Run the down migration (reverse of up migration)
+- Restore from backup (for destructive changes without down migration)
+- Feature flag to disable new code that uses new schema (code rollback, schema stays)
+
+### Rollback Decision Matrix
+| What Failed | Rollback Method | Data Loss Risk |
+|-------------|----------------|----------------|
+| Application bug | Deploy previous version | None |
+| Feature bug | Disable feature flag | None |
+| Schema migration bug | Run down migration | Low if reversible |
+| Data migration bug | Restore from backup | High if not reversible |
+| Integration failure | Circuit breaker / fallback | None |
+
+## Anti-Patterns
+
+- **Big-bang migration**: Migrating everything at once has high risk and hard rollback
+- **Breaking API changes without versioning**: Old clients will break
+- **Schema migration without backward compatibility**: Old code will fail against new schema
+- **Deploying without feature flags**: Can't instantly rollback if issues are detected
+- **Not testing rollback**: Rollback must be tested before you need it
+- **Removing old code before consumers have migrated**: Premature removal breaks dependencies
+- **Not monitoring during rollout**: Issues must be detected quickly to prevent wider impact

skills/observability-design/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: observability-design
+description: "Knowledge contract for observability design. Provides principles and patterns for logs, metrics, traces, correlation IDs, alerts, and SLOs. Referenced by design-architecture when defining observability strategy."
+---
+
+This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing observability. It does not produce artifacts directly.
+
+## Core Principles
+
+### Three Pillars of Observability
+- **Logs**: Discrete events with context (who, what, when, where)
+- **Metrics**: Numeric measurements aggregated over time (rates, histograms, gauges)
+- **Traces**: End-to-end request flow across services and boundaries
+
+### Observability Is Not Monitoring
+- Monitoring tells you when something is broken (known unknowns)
+- Observability lets you ask questions about why something is broken (unknown unknowns)
+- Design for observability: emit enough data to diagnose novel problems
+
+### Observability by Design
+- Observability must be designed into the architecture, not bolted on after
+- Every service must emit structured logs, metrics, and traces from day one
+- Every external integration must have observability hooks
+
+## Logs
+
+### Log Levels
+- **ERROR**: Something failed that requires investigation (not all errors are ERROR level)
+- **WARN**: Something unexpected happened but the system can continue
+- **INFO**: Business-significant events (order created, payment processed, user registered)
+- **DEBUG**: Detailed information for debugging (only in development, not in production)
+- **TRACE**: Very detailed information (almost never used in production)
+
+### Structured Logging
+- Use JSON format for all logs
+- Every log entry must include: timestamp, level, service name, correlation ID
+- Include relevant context: user ID, request ID, entity IDs, error details
+- Never log sensitive data: passwords, tokens, PII, secrets
+
+### Log Aggregation
+- Send all logs to a centralized log aggregation system
+- Define log retention period based on compliance requirements
+- Define log access controls (who can see what logs)
+- Consider log volume and cost (log only what you need)
+
+## Metrics
+
+### Metric Types
+- **Counter**: Monotonically increasing value (request count, error count)
+- **Gauge**: Point-in-time value (active connections, queue depth)
+- **Histogram**: Distribution of values (request latency, payload size)
+- **Summary**: Pre-calculated quantiles (p50, p90, p99 latency)
+
+### Key Business Metrics
+- Orders per minute
+- Revenue per minute
+- Active users
+- Conversion rate
+- Cart abandonment rate
+
+### Key System Metrics
+- Request rate (requests per second per endpoint)
+- Error rate (4xx rate, 5xx rate per endpoint)
+- Latency (p50, p90, p99 per endpoint)
+- Queue depth and age
+- Database connection pool usage
+- Cache hit rate
+- Memory and CPU usage per service
+
+### Metric Naming Convention
+- Use dot-separated names: `service.operation.metric`
+- Include units in the name or metadata: `request.duration.milliseconds`
+- Use consistent labels: `method`, `endpoint`, `status_code`, `tenant_id`
+
+## Traces
+
+### Distributed Tracing
+- Every request gets a trace ID that propagates across all services
+- Every operation within a request gets a span with operation name, start time, duration
+- Span boundaries: service calls, database queries, external API calls, queue operations
+
+### Correlation ID Propagation
+- Generate a correlation ID at the request entry point
+- Propagate correlation ID through all service calls (headers, message metadata)
+- Include correlation ID in all logs, metrics, and error responses
+- Use correlation ID to trace a request end-to-end across all services
+
+### Span Design
+- Include relevant context in spans: user ID, entity IDs, operation type
+- Tag spans with error information when operations fail
+- Keep span cardinality reasonable (avoid high-cardinality attributes as tags)
+
+## Alerts
+
+### Alert Design Principles
+- Alert on symptoms, not causes (user impact, not internal metrics)
+- Every alert must have a clear runbook or remediation steps
+- Every alert must be actionable (if you can't act on it, don't alert on it)
+- Avoid alert fatigue: set thresholds based on SLOs, not arbitrary numbers
+
+### Alert Categories
+- **Page-worthy**: System is broken, immediate action required (high error rate, service down)
+- **Ticket-worthy**: Degradation that needs investigation soon (rising latency, approaching limits)
+- **Log-worthy**: Informational, no immediate action (deployment completed, config changed)
+
+### Alert Thresholds
+- Base alert thresholds on SLOs, not arbitrary numbers
+- Use burn rate alerting: alert when the error budget is burning too fast
+- Define escalation paths: who gets paged, who gets a ticket, who gets an email
+
+## SLOs (Service Level Objectives)
+
+### SLO Design
+- Define SLOs based on user impact, not internal metrics
+- Typical SLO categories:
+  - **Availability**: % of requests that succeed (e.g., 99.9%)
+  - **Latency**: % of requests that complete within a threshold (e.g., p99 < 500ms)
+  - **Correctness**: % of operations that produce correct results
+  - **Freshness**: % of data that is within staleness threshold
+
+### Error Budget
+- Error budget = 100% - SLO target
+- If SLO is 99.9%, error budget is 0.1% per month
+- Track error budget burn rate: how fast are we consuming the budget?
+- When error budget is exhausted, focus shifts from feature development to reliability
+
+### SLO Framework
+- Define the SLO (what we promise)
+- Define the SLI (how we measure it)
+- Define the error budget (what we can afford to fail)
+- Define the alerting (when we're burning budget too fast)
+
+## Anti-Patterns
+
+- **Logging everything**: Generates noise, increases cost, makes debugging harder
+- **Missing correlation ID**: Can't trace requests across services
+- **Alerting on causes, not symptoms**: Alerts fire but users aren't impacted
+- **Missing business metrics**: Can't tell if the system is serving users well
+- **High-cardinality metrics**: Explosive metric count, expensive to store and query
+- **Missing observability for external calls**: External integration failures are invisible
+- **Logging sensitive data**: Passwords, tokens, PII in logs

skills/security-boundary-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: security-boundary-design
+description: "Knowledge contract for security boundary design. Provides principles and patterns for authentication, authorization, service identity, token propagation, tenant isolation, secret management, and audit logging. Referenced by design-architecture when defining security boundaries."
+---
+
+This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing security boundaries. It does not produce artifacts directly.
+
+## Core Principles
+
+### Defense in Depth
+- Never rely on a single security boundary
+- Apply security at every layer: network, service, data, application
+- Assume breach: design so that compromise of one layer doesn't compromise all
+
+### Least Privilege
+- Services and users should have the minimum permissions required
+- Default deny: start with no access, grant explicitly
+- Rotate and expire credentials regularly
+
+### Zero Trust
+- Don't trust internal network traffic by default
+- Authenticate and authorize every service-to-service call
+- Encrypt data in transit, even within the internal network
+
+## Authentication
+
+### Patterns
+- **Token-based authentication**: JWT, OAuth2 tokens
+- **API key authentication**: For service-to-service and public APIs
+- **Certificate-based authentication**: mTLS for internal service communication
+- **Session-based authentication**: For web applications with stateful sessions
+
+### Design Considerations
+- Define where authentication happens (edge gateway, service level, or both)
+- Define token format, issuer, audience, and expiration
+- Define token refresh and revocation strategy
+- Define credential rotation strategy
+- Consider token size impact on request headers
+
+## Authorization
+
+### Patterns
+- **RBAC (Role-Based Access Control)**: Assign permissions to roles, assign roles to users
+- **ABAC (Attribute-Based Access Control)**: Assign permissions based on attributes (user, resource, environment)
+- **ACL (Access Control List)**: Explicit list of who can access what
+- **ReBAC (Relationship-Based Access Control)**: Permissions based on relationships between entities
+
+### Design Considerations
+- Choose the simplest model that meets PRD requirements
+- Define permission granularity: coarse-grained (role-level) vs fine-grained (resource-level)
+- Define where authorization is enforced (gateway, service, or both)
+- Define how permissions are stored and cached
+- Consider multi-tenant authorization: can users in one tenant access resources in another?
+
+## Service Identity
+
+### Patterns
+- **Service accounts**: Each service has its own identity with specific permissions
+- **Workload identity**: Identity tied to the deployment (Kubernetes service accounts, cloud IAM roles)
+- **Service mesh identity**: Identity managed by the service mesh (Istio, Linkerd)
+
+### Design Considerations
+- Each service should have its own identity (no shared credentials)
+- Service identity should be short-lived and automatically rotated
+- Service identity should be bound to the deployment environment
+- Service identity permissions should follow least privilege
+
+## Token Propagation
+
+### Patterns
+- **Pass-through**: Gateway validates token, passes it to downstream services
+- **Token exchange**: Gateway validates external token, issues internal token
+- **Token relay**: Each service forwards the token to downstream services
+- **Impersonation**: Service calls downstream on behalf of the user
+
+### Design Considerations
+- Define token format for internal vs external communication
+- Define token lifecycle: creation, validation, refresh, revocation
+- Consider token size when propagating through multiple hops
+- Consider what context to propagate (user identity, tenant, permissions, correlation ID)
+
+## Tenant Isolation
+
+### Patterns
+- **Database-level isolation**: Separate database per tenant
+- **Schema-level isolation**: Separate schema per tenant, shared database
+- **Row-level isolation**: Shared schema, tenant_id column with enforcement
+- **Application-level isolation**: Shared infrastructure, application enforces isolation
+
+### Design Considerations
+- Choose isolation level based on PRD requirements (compliance, performance, cost)
+- Row-level isolation is simplest but requires careful query filtering
+- Database-level isolation provides strongest isolation but highest cost
+- Define how tenant context is resolved (subdomain, header, token claim)
+- Define how tenant isolation is enforced (middleware, query filter, database policy)
+
+## Secret Management
+
+### Patterns
+- **Environment variables**: Simple, but don't support rotation well
+- **Secret management service**: HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager
+- **Platform-native secrets**: Kubernetes Secrets, cloud IAM role-based access
+- **Configuration service**: Centralized configuration with encryption at rest
+
+### Design Considerations
+- Secrets must never be stored in code, configuration files in version control, or logs
+- Define secret rotation strategy for each type of secret
+- Define how services access secrets (sidecar, SDK, environment injection)
+- Define audit trail for secret access
+- Consider secret hierarchies (global, per-environment, per-service)
+
+## Audit Logging
+
+### Design Considerations
+- Log all authentication and authorization events (success and failure)
+- Log all data modification operations (who, what, when, from where)
+- Log all administrative actions
+- Define log retention period based on compliance requirements
+- Define log format: structured JSON with consistent fields
+- Log must be tamper-evident or append-only for compliance
+
+## Anti-Patterns
+
+- **Shared credentials across services**: Each service must have its own identity
+- **Hard-coded secrets**: Secrets must be externalized and rotated
+- **Overly broad permissions**: Grant least privilege, not convenience privilege
+- **Missing authentication for internal services**: Internal traffic must also be authenticated
+- **Missing audit logging for sensitive operations**: All auth events and data modifications must be logged
+- **Trust based on network location**: Don't assume internal network is safe

skills/write_adr/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: write_adr
+description: "Produce Architectural Decision Records with Context, Decision, Consequences, and Alternatives. A deliverable skill referenced by design-architecture."
+---
+
+This skill provides guidance and format requirements for producing Architectural Decision Records (ADRs) within the architecture document.
+
+This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when documenting significant architectural decisions.
+
+## Purpose
+
+The Architect must document significant architectural decisions using the ADR format. ADRs provide a permanent record of the context, decision, consequences, and alternatives considered for each important choice.
+
+## When to Write an ADR
+
+Write an ADR for any decision that:
+- Affects the system structure or service boundaries
+- Involves a technology selection (language, framework, database, queue, cache, infra)
+- Involves a consistency model choice (strong vs eventual, idempotency strategy)
+- Involves a security architecture decision
+- Involves a significant trade-off (performance vs consistency, complexity vs simplicity)
+- Would be difficult or costly to reverse
+- Other engineers would question "why was this chosen?"
+
+## ADR Format
+
+Each ADR must follow this format:
+
+```markdown
+### ADR-{N}: {Decision Title}
+
+- **Context**: Why this decision was needed. What is the problem or situation that requires a decision? Which PRD requirements drove this decision? What constraints exist?
+
+- **Decision**: What was decided. State the decision clearly and specifically. Include the specific technology, pattern, or approach chosen.
+
+- **Consequences**: What trade-offs or implications result from this decision. Include both positive and negative consequences. Address:
+  - What becomes easier?
+  - What becomes harder?
+  - What are the risks?
+  - What are the operational implications?
+
+- **Alternatives**: What other options were considered. For each alternative:
+  - Brief description
+  - Why it was not chosen
+  - Under what circumstances it might be the better choice
+```
+
+## ADR Numbering
+
+- Start with ADR-001 for the first decision
+- Number sequentially (ADR-001, ADR-002, etc.)
+- Each ADR in the architecture document gets a unique number
+
+## ADR Examples
+
+### ADR-001: Use Cassandra for Job Storage
+
+- **Context**: The system needs to handle high write throughput (10,000+ writes/second) for job status updates. Jobs are write-once with frequent status updates. Queries are primarily by job ID and by status+created_at. The PRD requires 99.9% availability for job status writes.
+
+- **Decision**: Use Cassandra as the primary storage for job data. Use PostgreSQL for relational data that requires complex queries and transactions.
+
+- **Consequences**:
+  - (+) High write throughput for job status updates
+  - (+) Horizontal scalability for job storage
+  - (+) 99.9% availability for job writes
+  - (-) Eventual consistency for job reads (stale reads possible within replication window)
+  - (-) No complex joins for job data
+  - (-) Additional operational complexity of managing two database systems
+  - (-) Data migration if requirements change
+
+- **Alternatives**:
+  - PostgreSQL only: Simpler operations, but may not handle write throughput under peak load. Would be appropriate if write throughput stays below 5,000 writes/second.
+  - MongoDB: Good balance of write throughput and query flexibility, but less mature for time-series-like access patterns.
+  - Redis + PostgreSQL: Redis for hot job data, PostgreSQL for cold storage. Adds complexity of data synchronization.
+
+### ADR-002: Use Event-Driven Architecture for Order Processing
+
+- **Context**: The PRD requires orders to be processed asynchronously with decoupled services. Order processing involves multiple steps (validation, payment, inventory, notification) that may fail independently. Each step must be retryable.
+
+- **Decision**: Use event-driven architecture with the outbox pattern for order processing. Publish OrderCreated events from the Order Service, consumed by downstream services.
+
+- **Consequences**:
+  - (+) Services are decoupled and can evolve independently
+  - (+) Individual steps can be retried without reprocessing the entire order
+  - (+) Natural fit for saga pattern for distributed transactions
+  - (-) Eventual consistency — downstream services may see stale data
+  - (-) More complex debugging and tracing
+  - (-) Requires outbox pattern implementation to ensure at-least-once delivery
+
+- **Alternatives**:
+  - Synchronous orchestration: Simpler to implement and debug, but creates tight coupling and doesn't handle partial failures well. Appropriate for simple, synchronous workflows.
+  - Saga orchestration with a central coordinator: More control over flow, but adds a single point of failure and operational complexity.
+
+## Embedding in Architecture Document
+
+All ADRs must be embedded within the `## ADR` section of `docs/architecture/{feature}.md`.
+
+Do NOT produce separate ADR files. All ADRs must be within the single architecture document.