---

name: dev-swarm-stage-architecture description: Design the complete system architecture including components, data flow, infrastructure, database schema, and API design. Use when starting stage 06 (architecture) or when user asks about system design, tech stack, or database schema.

Stage 06 - Architecture

Design the complete system architecture including components, data flow, infrastructure, and technical decisions that will guide all subsequent development work.

When to Use This Skill

• User asks to start stage 06 (architecture)
• User wants to design system architecture or select tech stack
• User asks about database design, API architecture, or infrastructure

Your Roles in This Skill

See dev-swarm/docs/general-dev-stage-rule.md for role selection guidance.

Role Communication

See dev-swarm/docs/general-dev-stage-rule.md for the required role announcement format.

Pre-Stage Check

Before starting, verify previous stages:

1. Check if 00-init-ideas/ through 05-ux/ folders have content (not just .gitkeep)
2. If any previous stage is empty and has no SKIP.md:
   • Ask user: "Stage {XX} is not complete. Would you like to skip it or start from that stage first?"

Instructions

Step 1: Context Review

Read all files to understand the project:

• ideas.md
• 00-init-ideas/*.md through 05-ux/*.md - All markdown files

Step 2: Create Stage Proposal

General Rules: See dev-swarm/docs/general-dev-stage-rule.md → "Create Stage Proposal Rules" section.

If this stage is skipped (has SKIP.md), execute the next non-skipped stage's agent skill. Otherwise, create the file 06-architecture/README.md with the following content:

2.1 Stage Goal

Brief the goal in 2-3 paragraphs:

• What this stage aims to achieve (define system architecture, tech stack, data models, APIs)
• Why architecture design is critical before development begins
• How this builds upon previous stages (UX flows, PRD requirements, MVP scope)
• What deliverables will be produced

2.2 File Selection

Select files from these options based on project needs:

System Architecture:

• system-architecture.md - Overall system architecture describing components and interactions
• architecture-diagram/ - High-level system architecture diagrams
• C4-component-diagram/ - C4 model diagrams: Context, Containers, Components Technology Stack:
• tech-stack.md - Selected languages, frameworks, libraries, and tools
• tech-stack-rationale.md - Detailed reasoning for each technology choice

Database Design:

• database-design.md - Database schema design and data modeling approach
• database-schema/ - ER diagrams showing tables and relationships

API Architecture:

• api-design.md - API architecture patterns, authentication, versioning strategy
• api-endpoints.md - Complete listing of API endpoints

Infrastructure:

• infrastructure-design.md - Overview of infrastructure components
• infrastructure-diagram/ - Infrastructure topology diagrams Security & Scalability:
• security-architecture.md - Security design including authentication and authorization
• scalability-plan.md - Scalability considerations and strategies

Data & Integrations:

• data-flow-diagram/ - Data flow diagrams
• integration-architecture.md - Third-party service integrations

For each selected file, provide:

• Short description
• Why it's essential for this project
• Key information it should include

2.3 Request User Approval

Ask user: "Please check the Stage Proposal in 06-architecture/README.md. Update it directly or tell me how to update it."

Step 3: Execute Stage Plan

Once user approves 06-architecture/README.md:

3.1 Create All Planned Files

Create each file listed in the approved README:

• For .md files: Write comprehensive content with clear sections and technical details
• For diagram folders: Follow dev-swarm/docs/mermaid-diagram-guide.md to create related diagrams files

Quality Guidelines:

• Base architecture decisions on PRD requirements and UX designs
• Ensure tech stack choices align with team capabilities
• Design for MVP scope first, with considerations for future scalability
• Include clear component boundaries and interfaces
• Document all major architectural decisions and trade-offs

3.2 Request User Approval for Files

After creating all files:

• Provide a summary of what was created
• Highlight key architectural decisions and trade-offs
• Ask: "Please review the architecture design. You can update or delete files, or let me know how to modify them."

Step 4: Finalize Stage

Once user approves all files:

4.1 Documentation Finalization

• Sync 06-architecture/README.md to remove any deleted files
• Ensure all files are complete and well-formatted
• Check that all diagrams render correctly

4.2 Prepare for Next Stage

• Summarize key architectural decisions for reference in tech-specs stage
• Identify any technical risks or open questions

4.3 Announce Completion

Inform user:

• "Stage 06 (Architecture) is complete"
• Summary of deliverables created
• Key architectural decisions made
• "Ready to proceed to Stage 07 (Tech Specs) when you are"

Stage Completion Rules

See dev-swarm/docs/general-dev-stage-rule.md for stage completion, commit, and skip rules.

Key Principles

• Document architectural decisions and trade-offs
• Design for MVP scope first
• Consider security and scalability from the start
• Support smooth transition to tech specs