daniel.w
/
opencode-workflow
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add AGENTS

This commit is contained in:
王性驊 2026-04-10 22:39:08 +08:00
parent b61495d34d
commit a91e805c2d
9 changed files with 239 additions and 337 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
agents/architect-agent.md
View File

@ -129,6 +129,8 @@ The Architect must produce at least:
- **1 Sequence Diagram**: Show the primary happy-path interaction flow
- **1 Data Flow Diagram**: Show how data moves through the system
Reference `generate_mermaid_diagram` for format requirements.
### API Contract
The Architect must produce API specifications including:
- All endpoints with method, path, request/response schemas
@ -136,6 +138,8 @@ The Architect must produce API specifications including:
- Idempotency requirements per endpoint
- Pagination and filtering where applicable
Reference `generate_openapi_spec` for format requirements.
### Database Schema
The Architect must produce schema definitions including:
- All tables with field names, types, constraints, and defaults
@ -145,6 +149,8 @@ The Architect must produce schema definitions including:
- Denormalization strategy (where applicable)
- Migration strategy notes
Reference `design_database_schema` for format requirements.
### ADR (Minimum 1)
Each ADR must follow the format:
- ADR number and title
@ -153,6 +159,11 @@ Each ADR must follow the format:
- Consequences
- Alternatives considered
Reference `write_adr` for format requirements.
### Anti-Placeholder Rule
Examples in deliverable skills are illustrative only. Do not reuse placeholder components, fields, endpoints, schemas, or technologies unless explicitly required by the PRD. Every element in the architecture document must be grounded in actual requirements.
## Architecture Traceability Rules
Every architectural element must trace back to at least one PRD requirement:

32
skills/architecture-research/SKILL.md
View File

@ -1,13 +1,34 @@
---
name: architecture-research
description: "Optional pre-work for investigating technical landscape, existing system constraints, and comparable architectures before the strict Architect pipeline begins. This skill produces internal analysis only — no file artifacts."
description: "Optional pre-work for investigating technical landscape, existing system constraints, and comparable architectures before the strict Architect pipeline begins. This skill produces internal analysis only — no file artifacts. Research may only compile constraints, options, and trade-offs — it MUST NOT make final architecture decisions."
---
This is optional pre-work, not part of the strict Architect pipeline. It is invoked before `analyze-prd` when the PRD involves significant technical constraints that benefit from landscape understanding.
## 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.
## Boundary: Research vs Design
This skill is strictly **research**. It may only:
- **Compile constraints**: Document existing system constraints, service boundaries, data flow, technology stack, integration dependencies, SLAs, and compliance requirements
- **Catalog options**: List available technology options, architecture patterns, and integration approaches with their trade-offs
- **Surface trade-offs**: Present pros, cons, and trade-offs of candidate approaches without making a final selection
- **Identify risks**: Flag technical risks, unknowns, and potential blockers
This skill **MUST NOT**:
- Make final architecture decisions (those belong exclusively to `design-architecture`)
- Select a technology stack (that is a final decision)
- Define service boundaries (that is a final decision)
- Define API contracts, data models, or database schemas (those are final decisions)
- Write ADRs (those are final decisions)
- Recommend a single approach over others without presenting alternatives (that is a disguised final decision)
- Produce any architecture document or artifact
The boundary is simple: **research compiles what is possible; design decides what we build.** If the output reads like a decision rather than a list of options, it has crossed the boundary into `design-architecture` territory.
## Goals
@ -29,15 +50,15 @@ Use research to answer:
- Do not design architecture yet; this is research only
- Do not make technology selections; catalog options and trade-offs only
- Do not make final architecture decisions of any kind
- Do not reverse-engineer competitor internal implementation details
- Do not produce architecture decisions or recommendations
- Do not write code, schemas, or API definitions
- Do not break down tasks or create milestones
- Do not produce file artifacts
## Process
1. Read the PRD file at `docs/prd/{date}-{feature}.md` to understand requirements
1. Read the PRD file at `docs/prd/{feature}.md` to understand requirements
2. Inspect the existing codebase for current architecture, service boundaries, and technology stack
3. Identify technical constraints and integration dependencies from the PRD and codebase
4. Research comparable system architectures and proven patterns for this problem domain
@ -54,4 +75,5 @@ This skill produces **internal analysis only**. Findings are carried forward in
- Prefer 3-5 proven patterns over 20 theoretical possibilities
- Call out confidence level when evidence is weak
- Tie findings back to specific PRD requirements and NFRs
- Do not make architecture decisions; that belongs in `design-architecture`
- Present options with trade-offs, not recommendations with conclusions
- All final architecture decisions must appear in `docs/architecture/{feature}.md` produced by `design-architecture`

238
skills/challenge-architecture/SKILL.md
View File

@ -1,15 +1,11 @@
---
name: challenge-architecture
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."
description: "Silent audit and batch review of architecture decisions. Validates traceability, scalability, consistency, security, integration, observability, and detects over/under-engineering. 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.
Perform a silent, structured audit of the architecture document against the PRD. Produce a single batch review with fixed output groups. Apply all fixes directly to the architecture file. Do not ask interactive questions.
Focus on system design validation, not implementation details. If a question drifts into code-level patterns, library choices, or implementation specifics, redirect it back to architecture-level concerns.
**Announce at start:** "I'm using the challenge-architecture skill to validate and stress-test the architecture."
Ask the questions one at a time.
**Announce at start:** "I'm using the challenge-architecture skill to audit and review the architecture."
## Primary Input
@ -20,60 +16,54 @@ Ask the questions one at a time.
- 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.
This is the **only** file artifact in the Architect pipeline. Review findings and fixes are applied directly to this file. No intermediate files are written.
## Process
## Audit Mode
### Phase 1: Traceability Audit
This skill operates in **silent audit / batch review** mode:
- Read the architecture document and PRD in full
- Perform all validation phases silently
- Produce a single structured review with all findings grouped into fixed categories
- Apply all fixes directly to the architecture document
- Do NOT ask questions one at a time or interactively prompt the user
## Audit Phases
Perform the following validations silently, collecting all findings before producing the review.
### Phase 1: Traceability
For every architectural element, verify it traces back to at least one PRD requirement:
- Does every API endpoint serve a PRD functional requirement?
- Does every DB table serve a data requirement from functional requirements or NFRs?
- 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 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?
- Every API endpoint serves a PRD functional requirement
- Every DB table serves a data requirement from FRs or NFRs
- Every service boundary serves a domain responsibility from the PRD scope
- Every async flow serves a PRD requirement
- Every error handling strategy serves a PRD edge case or NFR
- Every consistency decision serves a PRD requirement
- Every security boundary serves a security or compliance requirement
- Every integration boundary serves an external system requirement
- Every observability decision serves an NFR
Flag any architectural element that exists without PRD traceability as **potential over-engineering**.
### Phase 2: Requirement Coverage Audit
### Phase 2: Coverage
For every PRD requirement, verify it is covered by the architecture:
- Does every functional requirement have at least one architectural component serving it?
- Does every NFR have at least one architectural decision addressing it?
- Does every edge case have an error handling strategy?
- Does every acceptance criterion have architectural support?
- Are there PRD requirements that the architecture does not address?
- Every functional requirement has at least one architectural component
- Every NFR has at least one architectural decision
- Every edge case has an error handling strategy
- Every acceptance criterion has architectural support
Flag any uncovered PRD requirement as a **gap**.
### Phase 3: Architecture Decision Validation
For each Architectural Decision Record, challenge:
- Is the decision necessary, or could a simpler approach work?
- Are the alternatives fairly evaluated, or is there a strawman?
- Is the rationale specific to this use case, or generic boilerplate?
- Are the consequences honestly assessed?
- 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: Scalability Validation
### Phase 3: Scalability
- 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?
- Is database scaling addressed?
- Are there unbounded data growth scenarios?
- Are there operations that degrade under load?
### Phase 5: Consistency Validation
### Phase 4: Consistency
- Is the consistency model explicit for each data domain?
- Are eventual consistency windows acceptable for the use case?
@ -85,150 +75,142 @@ For each Architectural Decision Record, challenge:
- Is the outbox pattern used where needed?
- Are saga/compensation patterns defined for multi-step operations?
### Phase 6: Security Validation
### Phase 5: Security
- Are authentication boundaries clearly defined?
- Is authorization modeled correctly (RBAC, ABAC)?
- Is authorization modeled correctly?
- Is service-to-service authentication specified?
- Is token propagation defined?
- Is tenant isolation clearly defined (for multi-tenant systems)?
- Is tenant isolation 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
### Phase 6: Integration
- 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)?
- Is the integration pattern appropriate for each?
- Are rate limits and quotas addressed?
- Are failure modes defined for each integration?
- 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
### Phase 7: Observability
- 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
### Phase 8: Data Integrity
- 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 data ownership clear?
- Are cascading deletes or updates handled correctly?
- Are there data migration risks?
### Phase 10: Over-Engineering Detection
Check for common over-engineering patterns:
### Phase 9: Over-Engineering Detection
- Services that could be modules
- Patterns applied "just in case" without PRD justification
- Storage choices that exceed what the requirements demand
- Patterns applied without PRD justification
- Storage choices exceeding requirements
- Async processing where sync would suffice
- Abstraction layers that add complexity without solving a real problem
- Consistency guarantees stronger than what the requirements demand
- Security boundaries more complex than the threat model requires
- Abstraction layers without clear benefit
- Consistency guarantees stronger than requirements
- Security boundaries more complex than the threat model
- Observability granularity beyond operational need
### Phase 11: Under-Engineering Detection
### Phase 10: Under-Engineering Detection
Check for common under-engineering patterns:
- Missing error handling for edge cases identified in the PRD
- Missing idempotency for operations the PRD marks as requiring it
- Missing NFR accommodations (scaling, latency, availability)
- Missing async processing for operations that the PRD requires to be non-blocking
- Missing security boundaries or authentication where the PRD requires it
- Missing error handling for PRD edge cases
- Missing idempotency for operations requiring it
- Missing NFR accommodations
- Missing async processing for non-blocking requirements
- Missing security boundaries where the PRD requires them
- Missing observability for critical operations
- Missing consistency model specification
- Missing integration failure handling
- Missing retry strategies for external dependencies
## Validation Checklist
## Review Output Format
After challenging, verify the architecture satisfies:
1. Every architectural element traces to at least one PRD requirement
2. Every PRD requirement is covered by at least one architectural element
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 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. 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:
After completing all audit phases, produce a single structured review section. Append or update the `## Architecture Review` section in `docs/architecture/{feature}.md` with the following fixed groups:
```markdown
## Architecture Review
### Traceability Gaps
List every architectural element that cannot be traced to a PRD requirement, and every PRD requirement not covered by the architecture.
| Element / Requirement | Issue | Proposed Fix |
|----------------------|-------|-------------|
| ... | Untraceable / Uncovered | ... |
### Missing Decisions
List required architectural decisions that are absent or incomplete.
- [ ] ...
### Over-Engineering
List elements that exceed what the PRD requires.
- ... (specific item, why it is over-engineered, proposed simplification)
### Under-Engineering
List PRD requirements that lack adequate architectural support.
- ... (specific requirement, what is missing, proposed addition)
### Risks
| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|------------|
| ... | High/Medium/Low | High/Medium/Low | ... |
### Missing Parts
- [ ] ...
### Required Revisions
### Over-Engineering
- ... (specific items identified as over-engineered)
Numbered list of all changes that MUST be applied before handoff:
### 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)
1. ...
2. ...
```
When the gate decision is PASS or CONDITIONAL PASS (after adjustments), the architecture is ready for the next step: `finalize-architecture`.
After producing the review, apply all Required Revisions directly to `docs/architecture/{feature}.md`.
## Outcomes
## Gate Decision
For each issue found:
1. Document the issue
2. Propose a fix
3. Apply the fix directly to `docs/architecture/{feature}.md`
4. Re-verify the fix against the PRD
After applying revisions, evaluate the final state:
After all issues are resolved, proceed to `finalize-architecture`.
- **PASS** — All revisions applied, no remaining blockers
- **CONDITIONAL PASS** — Minor gaps remain but do not block Planner handoff
- **FAIL** — Significant revision required; return to `design-architecture`
Record the gate decision at the end of the Architecture Review section.
If FAIL, do NOT proceed to `finalize-architecture`. The architecture must be redesigned in `design-architecture` first.
If PASS or CONDITIONAL PASS, proceed to `finalize-architecture`.
## Guardrails
This is a pure validation skill.
This is a pure validation and revision skill.
Do:
- Challenge architectural decisions with evidence
- Validate traceability to PRD requirements
- Audit the architecture silently and produce a single batch review
- Validate traceability, scalability, consistency, security, integration, observability
- Detect over-engineering and under-engineering
- Validate scalability, consistency, security, integration, observability
- Propose specific fixes for identified issues
- Apply fixes directly to `docs/architecture/{feature}.md`
- Propose specific fixes for all identified issues
- Apply all fixes directly to `docs/architecture/{feature}.md`
- Record the gate decision
Do not:
- Ask questions interactively
- Change PRD requirements or scope
- Design architecture from scratch
- Make implementation-level decisions
@ -238,4 +220,4 @@ Do not:
## Transition
After challenge is complete and issues are resolved, invoke `finalize-architecture` for final completeness check and format validation.
If gate decision is PASS or CONDITIONAL PASS, invoke `finalize-architecture` for final completeness check and format validation.

275
skills/design-architecture/SKILL.md
View File

@ -1,6 +1,6 @@
---
name: design-architecture
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."
description: "Design system architecture based on PRD requirements. The Architect pipeline's core step, producing the single strict output file. References deliverable skills for format details and knowledge contracts for design principles."
---
This skill produces the complete architecture document for a feature, including all required deliverables.
@ -15,7 +15,7 @@ This skill produces the complete architecture document for a feature, including
- `docs/architecture/{feature}.md`
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.
This is the **only** file artifact produced by the Architect pipeline. No intermediate files are written to disk. All deliverables — diagrams, schemas, specs, ADRs — must be embedded within this single document.
## Hard Gate
@ -42,14 +42,14 @@ You MUST complete these steps in order:
- `integration-boundary-design` when defining external API integration patterns
- `observability-design` when defining logs, metrics, traces, alerts, SLOs
- `migration-rollout-design` when defining rollout strategy, feature flags, rollback
5. **Apply deliverable skills** 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
5. **Apply deliverable skills** for format requirements when producing sections:
- `generate_mermaid_diagram` when producing the Mermaid Diagrams section
- `design_database_schema` when producing the Database Schema section
- `generate_openapi_spec` when producing the API Contract section
- `write_adr` when producing the ADR section
- `evaluate_tech_stack` when producing the Technology Stack subsection
6. **Ensure traceability** — every architectural decision must trace back to at least one PRD requirement
7. **Write completeness check** — verify all 18 required sections are present and substantive
7. **Verify completeness** — all 18 required sections are present and substantive
8. **Write the architecture document** to `docs/architecture/{feature}.md`
## Architect Behavior Principles
@ -62,8 +62,14 @@ Apply these principles in priority order when making design decisions:
5. **Event Driven First** — Prefer event-driven communication for cross-service coordination
6. **Async First** — Prefer asynchronous processing for non-realtime operations
## Anti-Placeholder Rule
Examples in deliverable skills and this template are illustrative only. Do not reuse placeholder components, fields, endpoints, or schemas unless explicitly required by the PRD. Every element in the architecture document must be grounded in actual requirements, not copied from examples.
## Architecture Document Template
The following 18 sections are required. If a section is not applicable, write `N/A` with a brief reason. Each section states what it must contain and which deliverable skill to reference for format details.
```markdown
# Architecture: {Feature Name}
@ -79,18 +85,15 @@ High-level description of the system architecture. Map every major PRD requireme
## System Architecture
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.
Describe the complete system architecture including all services, databases, message queues, caches, and external integrations. Show how components are organized and how they communicate.
### Technology Stack
Reference `evaluate_tech_stack` deliverable skill for evaluation format.
| Layer | Technology | Justification |
|-------|-----------|---------------|
| Language | ... | ... |
| Framework | ... | ... |
| Database | ... | ... |
| Queue | ... | ... |
| Cache | ... | ... |
| Infrastructure | ... | ... |
| ... | ... | ... |
If the feature has no backend component, write `N/A` with a brief reason.
@ -100,7 +103,7 @@ Describe each major component, its responsibility, and how it fits into the over
## Service Boundaries
Define service boundaries with clear responsibilities and communication patterns.
Define service boundaries with clear responsibilities.
For each service or module:
- Name and single responsibility
@ -116,70 +119,26 @@ For each service or module:
## 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
Describe how data moves through the system end-to-end. Include request lifecycle, background job processing, event propagation, and data transformation 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.
Reference `design_database_schema` deliverable skill for table definition format, index format, partition key format, and relationship format.
### Table Definitions
Define all tables with field names, types, constraints, indexes, partition keys, and relationships. Include denormalization strategy and migration strategy where applicable.
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.
If the feature requires no database changes, write `N/A` with a brief reason.
## 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.
Reference `generate_openapi_spec` deliverable skill for endpoint definition format, error code format, idempotency format, and pagination format.
### 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.
Define all API endpoints with method, path, request/response schemas, error codes, idempotency, and pagination. Include an endpoint catalog and endpoint details.
## Async / Queue Design
Define asynchronous operations and their behavior. If the feature has no asynchronous requirements, write `N/A` with a brief reason.
### Async Operations
For each async operation:
- Operation name and trigger
- Queue or event topic
@ -190,25 +149,11 @@ For each async operation:
## Consistency Model
Define the consistency guarantees of the system.
Define the consistency guarantees of the system. Reference `consistency-transaction-design` knowledge contract for design principles.
### 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
- Idempotency design per idempotent operation
- Deduplication and retry strategy
- Outbox pattern usage (when applicable)
- Saga / compensation patterns (when applicable)
@ -218,94 +163,58 @@ If the feature has no consistency or idempotency requirements, write `N/A` with
Define error handling strategy across the system.
### Error Categories
- Client errors (4xx)
- Server errors (5xx)
- Business rule violations
- Timeout errors
- Cascading failure modes
### Error Propagation Strategy
- Fail-fast vs graceful degradation vs circuit breaker
- Fallback behavior
### Error Response Format
Consistent error response schema across the system.
### PRD Edge Case Mapping
| Error Category | PRD Edge Case | Handling Strategy |
|---------------|---------------|-------------------|
| ... | ... | ... |
- Error categories (client errors, server errors, business rule violations, timeout, cascading failure)
- Error propagation strategy (fail-fast, graceful degradation, circuit breaker)
- Error response format
- PRD edge case mapping
## Security Boundaries
Define security architecture for the system.
Define security architecture. Reference `security-boundary-design` knowledge contract for design principles.
- Authentication mechanism
- Authorization model (RBAC, ABAC, etc.)
- Authorization model
- Service identity and service-to-service auth
- Token propagation strategy
- Tenant isolation (multi-tenancy model)
- Secret management approach
- Audit logging requirements
- Tenant isolation
- Secret management
- Audit logging
If the feature has no security implications, write `N/A` with a brief reason.
## Integration Boundaries
Define all integrations with external systems.
Define all integrations with external systems. Reference `integration-boundary-design` knowledge contract for design principles.
For each external system integration:
- External system name and purpose
- Integration pattern (API call, webhook, polling, event subscription)
For each external system:
- Integration pattern (API, webhook, polling, event)
- Rate limits and quotas
- Failure modes and fallback behavior
- Failure modes and fallback
- Retry strategy
- Data contract (request/response schemas)
- Authentication mechanism
- Data contract
- Authentication
If the feature has no external integrations, write `N/A` with a brief reason.
## Observability
Define observability strategy for the system.
Define observability strategy. Reference `observability-design` knowledge contract for design principles.
### 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
- Logs: levels, format, aggregation
- Metrics: business metrics, system metrics, naming conventions
- Traces: distributed tracing, correlation ID, span boundaries
- Alerts: conditions, thresholds, routing
- SLOs: availability, latency, error budget
## Scaling Strategy
Define how the system scales based on NFRs.
- Horizontal scaling approach (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)
- Horizontal scaling approach
- Database scaling (read replicas, sharding, partitioning)
- Cache scaling
- Queue scaling
- Auto-scaling policies
- Bottleneck analysis
## Non-Functional Requirements
@ -314,73 +223,34 @@ 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.
Reference `generate_mermaid_diagram` deliverable skill for diagram format and guidelines.
### 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]
```
Produce at minimum:
- 1 System Architecture Diagram
- 1 Sequence Diagram
- 1 Data Flow Diagram
Additional diagrams as needed (event flow, state machine, etc.).
## ADR
Document significant architectural decisions.
Reference `write_adr` deliverable skill for ADR format.
### ADR-001: {Decision Title}
- **Context**: Why this decision was needed, including which PRD requirements drove it
- **Decision**: What was decided
- **Consequences**: What trade-offs or implications result
- **Alternatives**: What other options were considered
(Add additional ADRs as needed for each significant decision.)
Document significant architectural decisions. Each ADR must include Context, Decision, Consequences, and Alternatives. Minimum 1 ADR.
## 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:
List any unresolved questions that need PM or Engineering input.
1. ...
2. ...
@ -393,19 +263,14 @@ Before finalizing the architecture document, verify:
1. All 18 required sections are present (or explicitly marked N/A with reason)
2. Every PRD functional requirement is traced to at least one architectural component
3. Every PRD NFR is traced to at least one architectural decision
4. Every architecture section that is not N/A has substantive content
4. Every architecture section that is not N/A has substantive content grounded in PRD requirements
5. All API endpoints map to PRD functional requirements
6. All DB tables map to data requirements from functional requirements or NFRs
7. All async flows map to PRD requirements
8. All error handling strategies map to PRD edge cases
9. ADRs exist for all significant decisions (minimum 1)
10. At least 3 Mermaid diagrams are present (system, sequence, data flow)
11. Service boundaries are aligned with domain responsibilities
12. Security boundaries are defined
13. Integration boundaries are defined for all external systems
14. Observability strategy covers logs, metrics, and traces
15. Consistency model is explicit about strong vs eventual guarantees
16. No architectural element exists without traceability to a PRD requirement
11. No placeholder content reused from examples — all content must be grounded in actual requirements
## Guardrails
@ -416,9 +281,10 @@ Do:
- Define API contracts and data models
- 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
- Reference deliverable skills for format requirements of specific sections
- Reference knowledge contracts for design principles
- Ensure traceability to PRD requirements
- Ensure all content is grounded in actual PRD requirements, not placeholder examples
Do not:
- Change PRD requirements or scope
@ -428,10 +294,11 @@ Do not:
- Choose specific libraries or frameworks at the implementation level
- Prescribe code patterns, class structures, or function-level logic
- Produce any file artifact other than `docs/architecture/{feature}.md`
- Reuse placeholder components, fields, endpoints, or schemas from examples unless explicitly required by the PRD
The Architect defines HOW the system is structured.
The Engineering defines HOW the code is written.
## Transition
After completing the architecture document, invoke `challenge-architecture` to validate and stress-test the architecture.
After completing the architecture document, invoke `challenge-architecture` to audit and review the architecture.

4
skills/design_database_schema/SKILL.md
View File

@ -116,6 +116,10 @@ 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
## Anti-Placeholder Rule
Examples in this skill are illustrative only. Do not reuse placeholder table names, column names, types, indexes, or relationships unless explicitly required by the PRD. Every table, field, index, and relationship must be grounded in actual requirements and match the architecture document's data model.
## Embedding in Architecture Document
All database schema definitions must be embedded within the `## Database Schema` section of `docs/architecture/{feature}.md`.

4
skills/evaluate_tech_stack/SKILL.md
View File

@ -93,6 +93,10 @@ This deliverable skill works alongside the `storage-knowledge` and `architecture
- `storage-knowledge` provides detailed comparison of storage technologies
- `architecture-patterns` provides guidance on which patterns suit which technologies
## Anti-Placeholder Rule
Examples in this skill are illustrative only. Do not reuse placeholder technologies, justifications, or alternatives unless explicitly required by the PRD. Every technology selection, justification, and alternative must be grounded in actual requirements and reflect real evaluation for this system.
## Embedding in Architecture Document
Technology stack evaluation must be embedded within the `## System Architecture` section (Technology Stack subsection) of `docs/architecture/{feature}.md`.

4
skills/generate_mermaid_diagram/SKILL.md
View File

@ -129,6 +129,10 @@ stateDiagram-v2
- Use `-.->` for asynchronous messages/events
- Include the protocol or verb when relevant (HTTP, gRPC, AMQP)
## Anti-Placeholder Rule
Examples in this skill are illustrative only. Do not reuse placeholder components, services, databases, or relationships unless explicitly required by the PRD. Every element in a Mermaid diagram must be grounded in actual requirements and match the architecture document's content.
## Embedding in Architecture Document
All diagrams must be embedded within the `## Mermaid Diagrams` section of `docs/architecture/{feature}.md` using:

4
skills/generate_openapi_spec/SKILL.md
View File

@ -192,6 +192,10 @@ This deliverable skill works alongside the `api-contract-design` knowledge contr
- `api-contract-design` provides the theoretical guidance on API design principles
- This skill provides the concrete output format and completeness requirements
## Anti-Placeholder Rule
Examples in this skill are illustrative only. Do not reuse placeholder endpoints, field names, response schemas, or error codes unless explicitly required by the PRD. Every endpoint, field, status code, and error code must be grounded in actual requirements and match the architecture document's functional requirements.
## Embedding in Architecture Document
All API contract definitions must be embedded within the `## API Contract` section of `docs/architecture/{feature}.md`.

4
skills/write_adr/SKILL.md
View File

@ -91,6 +91,10 @@ Each ADR must follow this format:
- 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.
## Anti-Placeholder Rule
Examples in this skill are illustrative only. Do not reuse placeholder ADR titles, contexts, decisions, or alternatives unless explicitly required by the PRD. Every ADR must document an actual architectural decision made for this system, with real context, real consequences, and real alternatives considered.
## Embedding in Architecture Document
All ADRs must be embedded within the `## ADR` section of `docs/architecture/{feature}.md`.