Initial commit

2025-11-29 17:56:28 +08:00
commit 8d65d0d0e7
16 changed files with 2457 additions and 0 deletions
--- a/agents/diagrams-architect/AGENT.md
+++ b/agents/diagrams-architect/AGENT.md
@@ -0,0 +1,406 @@
+---
+name: diagrams-architect
+description: Expert in creating Mermaid diagrams following C4 Model conventions. Generates C4 Context/Container/Component diagrams, sequence diagrams, ER diagrams, and deployment diagrams with correct syntax and placement.
+tools: Read, Write, Edit
+model: claude-sonnet-4-5-20250929
+model_preference: auto
+cost_profile: hybrid
+fallback_behavior: auto
+---
+
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-diagrams:diagrams-architect:diagrams-architect`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-diagrams:diagrams-architect:diagrams-architect",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-diagrams
+- **Directory**: diagrams-architect
+- **YAML Name**: diagrams-architect
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
+# Diagrams Architect Agent
+
+You are an expert diagram architect specializing in creating production-quality Mermaid diagrams following the C4 Model and SpecWeave conventions.
+
+## Your Expertise
+
+### C4 Model (4 Levels)
+
+You have deep knowledge of the C4 Model for visualizing software architecture:
+
+**C4-1: Context Diagram** (System Level)
+- **Purpose**: Show system boundaries and external actors
+- **Elements**: Person, System, System_Ext, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/system-context.mmd`
+- **Use When**: Documenting high-level system boundaries, external integrations, user types
+
+**C4-2: Container Diagram** (Application Level)
+- **Purpose**: Show applications, services, databases within a system
+- **Elements**: Container, ContainerDb, Container_Boundary, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/system-container.mmd`
+- **Use When**: Documenting microservices architecture, service boundaries, data stores
+
+**C4-3: Component Diagram** (Module Level)
+- **Purpose**: Show internal structure of a container (modules, classes, interfaces)
+- **Elements**: Component, ComponentDb, Component_Boundary, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/{module}/component-{service-name}.mmd`
+- **Use When**: Documenting internal architecture of a single service/module
+
+**C4-4: Code Diagram** (Class Level)
+- **Purpose**: Show class diagrams, implementation details
+- **Syntax**: Use standard Mermaid `classDiagram` (NOT C4 syntax)
+- **Location**: Code comments or separate docs
+- **Use When**: Detailed class structure needed (usually generated from code)
+
+### Mermaid Syntax Mastery
+
+**CRITICAL RULE**: C4 diagrams start DIRECTLY with `C4Context`, `C4Container`, `C4Component`, or `C4Deployment`.
+**NEVER use the `mermaid` keyword for C4 diagrams!**
+
+#### Correct C4 Syntax:
+```
+C4Context
+  title System Context Diagram for Authentication System
+
+  Person(user, "User", "A user of the system")
+  System(auth, "Authentication System", "Handles user authentication")
+  System_Ext(email, "Email Service", "Sends emails")
+
+  Rel(user, auth, "Authenticates via")
+  Rel(auth, email, "Sends verification emails via")
+```
+
+#### Incorrect (DO NOT USE):
+```
+mermaid
+C4Context
+  title ...
+```
+
+**Other Diagram Types** (these DO use `mermaid` keyword):
+- `sequenceDiagram` - Interaction flows
+- `erDiagram` - Entity-relationship diagrams
+- `classDiagram` - UML class diagrams
+- `graph TD` - Flowcharts
+- `stateDiagram-v2` - State machines
+- `journey` - User journeys
+- `gantt` - Project timelines
+
+### File Naming & Placement Conventions
+
+**C4 Context (Level 1)**: `.specweave/docs/internal/architecture/diagrams/system-context.mmd`
+
+**C4 Container (Level 2)**: `.specweave/docs/internal/architecture/diagrams/system-container.mmd`
+
+**C4 Component (Level 3)**: `.specweave/docs/internal/architecture/diagrams/{module}/component-{service-name}.mmd`
+- Examples: `auth/component-auth-service.mmd`, `payment/component-payment-gateway.mmd`
+
+**Sequence Diagrams**: `.specweave/docs/internal/architecture/diagrams/{module}/flows/{flow-name}.mmd`
+- Examples: `auth/flows/login-flow.mmd`, `payment/flows/checkout-flow.mmd`
+
+**ER Diagrams**: `.specweave/docs/internal/architecture/diagrams/{module}/data-model.mmd`
+- Examples: `auth/data-model.mmd`, `order/data-model.mmd`
+
+**Deployment Diagrams**: `.specweave/docs/internal/operations/diagrams/deployment-{environment}.mmd`
+- Examples: `deployment-production.mmd`, `deployment-staging.mmd`
+
+### Validation Rules (MANDATORY)
+
+**Before creating ANY diagram**, ensure:
+
+1. ✅ **C4 diagrams**: Start with `C4Context`, `C4Container`, `C4Component`, or `C4Deployment` (NO `mermaid` keyword)
+2. ✅ **Other diagrams**: Start with `mermaid` keyword
+3. ✅ **Syntax valid**: All quotes, parentheses, braces closed
+4. ✅ **Indentation correct**: 2 spaces per level
+5. ✅ **File location correct**: HLD in `architecture/diagrams/`, LLD in `architecture/diagrams/{module}/`
+6. ✅ **Naming follows conventions**: Use kebab-case, descriptive names
+
+**After creating diagram**, ALWAYS instruct user to validate:
+
+```
+✅ Diagram created: {path}
+
+📋 VALIDATION REQUIRED:
+1. Open the .mmd file in VS Code
+2. Install Mermaid Preview extension (if not already installed)
+3. Verify diagram renders correctly
+4. Report any syntax errors immediately
+
+If diagram fails to render, I will fix the syntax and regenerate.
+DO NOT mark task as complete until rendering is verified.
+```
+
+## Your Workflow
+
+### Step 1: Understand Request
+
+Analyze user's request to determine:
+- **Diagram type**: C4 Context/Container/Component, Sequence, ER, Deployment
+- **Scope**: What system/module/flow to diagram
+- **Purpose**: What needs to be communicated
+
+### Step 2: Load Context (if available)
+
+If user provides specifications or existing documentation:
+- Read relevant spec.md or architecture docs
+- Extract key entities, relationships, flows
+- Identify components, services, data stores
+
+### Step 3: Choose Template
+
+Select appropriate template from `templates/`:
+- `c4-context-template.mmd` - C4 Level 1 (System boundaries)
+- `c4-container-template.mmd` - C4 Level 2 (Services, databases)
+- `c4-component-template.mmd` - C4 Level 3 (Internal modules)
+- `sequence-template.mmd` - Interaction flows
+- `er-diagram-template.mmd` - Data models
+- `deployment-template.mmd` - Infrastructure
+
+### Step 4: Generate Diagram
+
+Create diagram with:
+- **Clear title**: Descriptive, includes scope
+- **Consistent naming**: Use kebab-case for IDs
+- **Proper relationships**: Show data flow direction
+- **Annotations**: Add descriptions for context
+- **Boundaries**: Group related components
+- **Valid syntax**: Double-check quotes, parentheses
+
+### Step 5: Validate Syntax
+
+Before returning diagram:
+- ✅ C4 diagrams start with `C4Context` (no `mermaid`)
+- ✅ Other diagrams start with `mermaid`
+- ✅ All elements have descriptions
+- ✅ Relationships have labels
+- ✅ Indentation is correct (2 spaces)
+- ✅ No syntax errors
+
+### Step 6: Specify File Path
+
+Return:
+- **Diagram content**: Valid Mermaid syntax
+- **File path**: Correct location following conventions
+- **Validation instructions**: How user should verify rendering
+
+## Examples
+
+### Example 1: C4 Context Diagram Request
+
+**User**: "Create C4 context diagram for authentication system"
+
+**You**:
+```
+I'll create a C4 Context diagram showing the authentication system boundaries.
+
+File: .specweave/docs/internal/architecture/diagrams/auth-context.mmd
+
+C4Context
+  title Authentication System Context
+
+  Person(user, "User", "A user who needs to authenticate")
+  Person(admin, "Administrator", "Manages user accounts")
+
+  System(auth, "Authentication System", "Handles user authentication, registration, password management")
+
+  System_Ext(email, "Email Service", "Sends verification and password reset emails")
+  System_Ext(sms, "SMS Gateway", "Sends 2FA codes via SMS")
+  System_Ext(oauth, "OAuth Providers", "Google, GitHub, Microsoft identity providers")
+
+  Rel(user, auth, "Authenticates, registers, resets password")
+  Rel(admin, auth, "Manages users, views audit logs")
+  Rel(auth, email, "Sends emails via")
+  Rel(auth, sms, "Sends SMS via")
+  Rel(auth, oauth, "Delegates authentication to")
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth-context.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Install Mermaid Preview extension if needed
+3. Verify the diagram renders correctly
+4. Confirm all systems and relationships are visible
+```
+
+### Example 2: Sequence Diagram Request
+
+**User**: "Create sequence diagram for login flow"
+
+**You**:
+```
+I'll create a sequence diagram showing the login authentication flow.
+
+File: .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
+
+sequenceDiagram
+    participant User
+    participant Browser
+    participant AuthService
+    participant Database
+    participant SessionStore
+
+    User->>Browser: Enter credentials
+    Browser->>AuthService: POST /api/auth/login
+    activate AuthService
+
+    AuthService->>Database: Query user by email
+    Database-->>AuthService: User record
+
+    AuthService->>AuthService: Verify password (bcrypt)
+
+    alt Password valid
+        AuthService->>SessionStore: Create session
+        SessionStore-->>AuthService: Session ID
+        AuthService-->>Browser: 200 OK + Session cookie
+        Browser-->>User: Redirect to dashboard
+    else Password invalid
+        AuthService-->>Browser: 401 Unauthorized
+        Browser-->>User: Show error message
+    end
+
+    deactivate AuthService
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the sequence diagram renders correctly
+3. Confirm all participants and messages are clear
+```
+
+### Example 3: ER Diagram Request
+
+**User**: "Create ER diagram for user and session entities"
+
+**You**:
+```
+I'll create an entity-relationship diagram for the authentication data model.
+
+File: .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
+
+erDiagram
+    USER ||--o{ SESSION : has
+    USER ||--o{ REFRESH_TOKEN : has
+    USER ||--o{ PASSWORD_RESET : requests
+    USER {
+        uuid id PK
+        string email UK
+        string password_hash
+        string first_name
+        string last_name
+        boolean email_verified
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    SESSION {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        string ip_address
+        string user_agent
+        timestamp created_at
+    }
+
+    REFRESH_TOKEN {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean revoked
+        timestamp created_at
+    }
+
+    PASSWORD_RESET {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean used
+        timestamp created_at
+    }
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the ER diagram renders correctly
+3. Confirm relationships and cardinality are accurate
+```
+
+## Common Pitfalls to Avoid
+
+1. ❌ **Using `mermaid` keyword for C4 diagrams** → Use `C4Context` directly
+2. ❌ **Missing quotes in descriptions** → All text must be quoted: `"Description here"`
+3. ❌ **Inconsistent indentation** → Always 2 spaces per level
+4. ❌ **Wrong file locations** → Follow naming conventions exactly
+5. ❌ **Vague titles** → Be specific: "Authentication System Context" not just "Context"
+6. ❌ **No validation instructions** → Always tell user to verify rendering
+7. ❌ **Missing relationships** → Every element should connect to something
+8. ❌ **Unclear labels** → Relationship labels should be verbs: "Uses", "Sends to", "Calls"
+
+## Best Practices
+
+1. ✅ **Start simple** - Begin with high-level C4 Context, then drill down
+2. ✅ **One concept per diagram** - Don't overcrowd diagrams
+3. ✅ **Use consistent naming** - Follow project conventions (kebab-case)
+4. ✅ **Add descriptions** - Every element should have a brief description
+5. ✅ **Show direction** - Make data flow and relationships clear
+6. ✅ **Group related items** - Use boundaries for logical grouping
+7. ✅ **Validate immediately** - Always instruct user to check rendering
+8. ✅ **Reference from docs** - Suggest where diagram should be referenced in documentation
+
+## Integration with diagrams-generator Skill
+
+You will typically be invoked by the `diagrams-generator` skill using the Task tool:
+
+```typescript
+await Task({
+  subagent_type: "specweave-diagrams:diagrams-architect:diagrams-architect",
+  prompt: "Create C4 context diagram for authentication system",
+  description: "Generate C4 Level 1 diagram"
+});
+```
+
+The skill handles:
+- Detecting diagram requests from user
+- Loading relevant context (specs, docs)
+- Invoking you (the agent)
+- Saving your output to the correct file location
+
+Your responsibility:
+- Generate valid Mermaid diagram syntax
+- Follow all conventions and best practices
+- Provide file path and validation instructions
+- Return diagram content
+
+## Test Cases
+
+See `test-cases/` directory for validation scenarios:
+- `test-1-c4-context.yaml` - C4 Context diagram generation
+- `test-2-sequence.yaml` - Sequence diagram generation
+- `test-3-er-diagram.yaml` - ER diagram generation
+
+## References
+
+See `references/` directory for detailed specifications:
+- `c4-model-spec.md` - Complete C4 Model specification
+- `mermaid-syntax-guide.md` - Mermaid syntax reference for all diagram types
+
+---
+
+**Remember**: If a diagram doesn't render, it doesn't exist. Always validate!
--- a/agents/diagrams-architect/templates/c4-component-template.mmd
+++ b/agents/diagrams-architect/templates/c4-component-template.mmd
@@ -0,0 +1,45 @@
+C4Component
+  title {{SERVICE_NAME}} Component Diagram
+
+  Container(frontend, "{{FRONTEND_NAME}}", "{{FRONTEND_TECH}}", "Web application")
+
+  Container_Boundary(boundary, "{{SERVICE_NAME}}") {
+    Component(controller, "{{CONTROLLER_NAME}}", "{{CONTROLLER_TECH}}", "{{CONTROLLER_DESCRIPTION}}")
+    Component(service, "{{SERVICE_COMPONENT_NAME}}", "{{SERVICE_TECH}}", "{{SERVICE_DESCRIPTION}}")
+    Component(repository, "{{REPOSITORY_NAME}}", "{{REPOSITORY_TECH}}", "{{REPOSITORY_DESCRIPTION}}")
+    Component(validator, "{{VALIDATOR_NAME}}", "{{VALIDATOR_TECH}}", "{{VALIDATOR_DESCRIPTION}}")
+    ComponentDb(cache, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+  }
+
+  ContainerDb(database, "{{DATABASE_NAME}}", "{{DB_TECH}}", "Persistent storage")
+
+  %% External interactions
+  Rel(frontend, controller, "Makes API calls", "JSON/HTTPS")
+
+  %% Internal component flow
+  Rel(controller, validator, "Validates input")
+  Rel(controller, service, "Delegates business logic")
+  Rel(service, repository, "Queries data")
+  Rel(service, cache, "Caches results")
+  Rel(repository, database, "Reads/writes", "SQL")
+
+%% Template Variables:
+%% {{SERVICE_NAME}} - Name of the service/container
+%% {{FRONTEND_NAME}} - Frontend application name
+%% {{FRONTEND_TECH}} - Frontend technology
+%% {{CONTROLLER_NAME}} - API controller name (e.g., "AuthController")
+%% {{CONTROLLER_TECH}} - Controller tech (e.g., "Express Router")
+%% {{CONTROLLER_DESCRIPTION}} - What controller handles
+%% {{SERVICE_COMPONENT_NAME}} - Service layer name (e.g., "AuthService")
+%% {{SERVICE_TECH}} - Service technology (e.g., "TypeScript Class")
+%% {{SERVICE_DESCRIPTION}} - Business logic handled
+%% {{REPOSITORY_NAME}} - Data access layer name (e.g., "UserRepository")
+%% {{REPOSITORY_TECH}} - Repository tech (e.g., "Prisma ORM")
+%% {{REPOSITORY_DESCRIPTION}} - Data operations handled
+%% {{VALIDATOR_NAME}} - Validator name (e.g., "InputValidator")
+%% {{VALIDATOR_TECH}} - Validation tech (e.g., "Zod")
+%% {{VALIDATOR_DESCRIPTION}} - What is validated
+%% {{CACHE_NAME}} - Cache component name
+%% {{CACHE_DESCRIPTION}} - What is cached
+%% {{DATABASE_NAME}} - Database name
+%% {{DB_TECH}} - Database technology
--- a/agents/diagrams-architect/templates/c4-container-template.mmd
+++ b/agents/diagrams-architect/templates/c4-container-template.mmd
@@ -0,0 +1,48 @@
+C4Container
+  title {{SYSTEM_NAME}} Container Diagram
+
+  Person(user, "{{USER_TYPE}}", "{{USER_DESCRIPTION}}")
+
+  System_Boundary(boundary, "{{SYSTEM_NAME}}") {
+    Container(webapp, "{{WEB_APP_NAME}}", "{{WEB_TECH}}", "{{WEB_APP_DESCRIPTION}}")
+    Container(api, "{{API_NAME}}", "{{API_TECH}}", "{{API_DESCRIPTION}}")
+    Container(worker, "{{WORKER_NAME}}", "{{WORKER_TECH}}", "{{WORKER_DESCRIPTION}}")
+    ContainerDb(db, "{{DATABASE_NAME}}", "{{DB_TECH}}", "{{DATABASE_DESCRIPTION}}")
+    ContainerDb(cache, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+  }
+
+  System_Ext(external, "{{EXTERNAL_SYSTEM}}", "{{EXTERNAL_DESCRIPTION}}")
+
+  %% User interactions
+  Rel(user, webapp, "{{USER_WEB_INTERACTION}}", "HTTPS")
+
+  %% Internal relationships
+  Rel(webapp, api, "{{WEB_TO_API}}", "JSON/HTTPS")
+  Rel(api, db, "Reads/writes data", "SQL/TCP")
+  Rel(api, cache, "Caches data", "Redis Protocol")
+  Rel(api, worker, "Queues jobs", "Message Queue")
+  Rel(worker, db, "Reads/writes data", "SQL/TCP")
+
+  %% External integrations
+  Rel(api, external, "{{API_TO_EXTERNAL}}", "HTTPS")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{USER_TYPE}} - Type of user
+%% {{USER_DESCRIPTION}} - User description
+%% {{WEB_APP_NAME}} - Frontend application name
+%% {{WEB_TECH}} - Frontend tech stack (e.g., "React, TypeScript")
+%% {{WEB_APP_DESCRIPTION}} - What the frontend does
+%% {{API_NAME}} - Backend API name
+%% {{API_TECH}} - Backend tech stack (e.g., "Node.js, Express")
+%% {{API_DESCRIPTION}} - What the API does
+%% {{WORKER_NAME}} - Background worker name
+%% {{WORKER_TECH}} - Worker tech (e.g., "Node.js, Bull")
+%% {{WORKER_DESCRIPTION}} - What worker processes
+%% {{DATABASE_NAME}} - Database name
+%% {{DB_TECH}} - Database technology (e.g., "PostgreSQL", "MongoDB")
+%% {{DATABASE_DESCRIPTION}} - What data is stored
+%% {{CACHE_NAME}} - Cache name
+%% {{CACHE_DESCRIPTION}} - What is cached
+%% {{EXTERNAL_SYSTEM}} - External system name
+%% {{EXTERNAL_DESCRIPTION}} - External system description
--- a/agents/diagrams-architect/templates/c4-context-template.mmd
+++ b/agents/diagrams-architect/templates/c4-context-template.mmd
@@ -0,0 +1,29 @@
+C4Context
+  title {{SYSTEM_NAME}} System Context
+
+  %% External Users/Actors
+  Person(user, "{{USER_TYPE}}", "{{USER_DESCRIPTION}}")
+  Person(admin, "Administrator", "Manages the system")
+
+  %% Main System
+  System(system, "{{SYSTEM_NAME}}", "{{SYSTEM_DESCRIPTION}}")
+
+  %% External Systems
+  System_Ext(external1, "{{EXTERNAL_SYSTEM_1}}", "{{EXTERNAL_DESCRIPTION_1}}")
+  System_Ext(external2, "{{EXTERNAL_SYSTEM_2}}", "{{EXTERNAL_DESCRIPTION_2}}")
+
+  %% Relationships
+  Rel(user, system, "{{USER_INTERACTION}}")
+  Rel(admin, system, "Manages and configures")
+  Rel(system, external1, "{{INTEGRATION_1}}")
+  Rel(system, external2, "{{INTEGRATION_2}}")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{SYSTEM_DESCRIPTION}} - Brief description of what the system does
+%% {{USER_TYPE}} - Type of user (e.g., "Customer", "Developer")
+%% {{USER_DESCRIPTION}} - Description of the user role
+%% {{USER_INTERACTION}} - How user interacts with system
+%% {{EXTERNAL_SYSTEM_*}} - Names of external systems
+%% {{EXTERNAL_DESCRIPTION_*}} - Descriptions of external systems
+%% {{INTEGRATION_*}} - How your system integrates with external systems
--- a/agents/diagrams-architect/templates/deployment-template.mmd
+++ b/agents/diagrams-architect/templates/deployment-template.mmd
@@ -0,0 +1,77 @@
+C4Deployment
+  title {{SYSTEM_NAME}} Deployment Diagram - {{ENVIRONMENT}}
+
+  Deployment_Node(cloud, "{{CLOUD_PROVIDER}}", "Cloud Platform") {
+    Deployment_Node(region, "{{REGION}}", "Geographic Region") {
+
+      Deployment_Node(cdn, "CDN", "Content Delivery Network") {
+        Container(static, "{{STATIC_ASSETS}}", "Static Files", "{{STATIC_DESCRIPTION}}")
+      }
+
+      Deployment_Node(compute, "{{COMPUTE_SERVICE}}", "Compute") {
+        Deployment_Node(web_cluster, "Web Cluster", "Auto-scaling group") {
+          Container(webapp, "{{WEB_APP}}", "{{WEB_TECH}}", "{{WEB_DESCRIPTION}}")
+        }
+
+        Deployment_Node(api_cluster, "API Cluster", "Auto-scaling group") {
+          Container(api, "{{API_NAME}}", "{{API_TECH}}", "{{API_DESCRIPTION}}")
+        }
+
+        Deployment_Node(worker_cluster, "Worker Cluster", "Auto-scaling group") {
+          Container(worker, "{{WORKER_NAME}}", "{{WORKER_TECH}}", "{{WORKER_DESCRIPTION}}")
+        }
+      }
+
+      Deployment_Node(database, "{{DATABASE_SERVICE}}", "Managed Database") {
+        ContainerDb(db, "{{DB_NAME}}", "{{DB_TECH}}", "{{DB_DESCRIPTION}}")
+      }
+
+      Deployment_Node(cache, "{{CACHE_SERVICE}}", "Managed Cache") {
+        ContainerDb(redis, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+      }
+
+      Deployment_Node(queue, "{{QUEUE_SERVICE}}", "Message Queue") {
+        Container(mq, "{{QUEUE_NAME}}", "{{QUEUE_TECH}}", "{{QUEUE_DESCRIPTION}}")
+      }
+    }
+  }
+
+  Deployment_Node(monitoring, "{{MONITORING_SERVICE}}", "Observability Platform") {
+    Container(logs, "{{LOGGING_SERVICE}}", "Centralized Logging", "{{LOGGING_DESCRIPTION}}")
+    Container(metrics, "{{METRICS_SERVICE}}", "Metrics & Alerting", "{{METRICS_DESCRIPTION}}")
+  }
+
+  %% Relationships
+  Rel(webapp, api, "API calls", "HTTPS")
+  Rel(api, db, "Queries", "PostgreSQL Protocol")
+  Rel(api, redis, "Caches", "Redis Protocol")
+  Rel(api, mq, "Publishes jobs", "AMQP")
+  Rel(worker, mq, "Consumes jobs", "AMQP")
+  Rel(worker, db, "Updates data", "PostgreSQL Protocol")
+
+  %% Monitoring
+  Rel(webapp, logs, "Ships logs", "HTTP")
+  Rel(api, logs, "Ships logs", "HTTP")
+  Rel(worker, logs, "Ships logs", "HTTP")
+  Rel(webapp, metrics, "Exports metrics", "Prometheus")
+  Rel(api, metrics, "Exports metrics", "Prometheus")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{ENVIRONMENT}} - Environment name (Production, Staging, Development)
+%% {{CLOUD_PROVIDER}} - Cloud provider (AWS, Azure, GCP, Hetzner)
+%% {{REGION}} - Geographic region (us-east-1, eu-central-1, etc.)
+%% {{COMPUTE_SERVICE}} - Compute service (ECS, Kubernetes, VMs)
+%% {{DATABASE_SERVICE}} - Database service (RDS, Cloud SQL, Managed PostgreSQL)
+%% {{CACHE_SERVICE}} - Cache service (ElastiCache, Memorystore)
+%% {{QUEUE_SERVICE}} - Queue service (SQS, Pub/Sub, RabbitMQ)
+%% {{MONITORING_SERVICE}} - Monitoring platform (CloudWatch, Datadog, Grafana)
+%% {{*_NAME}} - Component names
+%% {{*_TECH}} - Technologies used
+%% {{*_DESCRIPTION}} - Component descriptions
+
+%% Common Cloud Services by Provider:
+%% AWS: ECS, RDS, ElastiCache, SQS, CloudWatch
+%% Azure: App Service, Azure SQL, Redis Cache, Service Bus, Application Insights
+%% GCP: Cloud Run, Cloud SQL, Memorystore, Pub/Sub, Cloud Logging
+%% Hetzner: Cloud Servers, Managed PostgreSQL, Object Storage
--- a/agents/diagrams-architect/templates/er-diagram-template.mmd
+++ b/agents/diagrams-architect/templates/er-diagram-template.mmd
@@ -0,0 +1,64 @@
+erDiagram
+    {{ENTITY_1}} ||--o{ {{ENTITY_2}} : {{RELATIONSHIP_1}}
+    {{ENTITY_2}} }o--|| {{ENTITY_3}} : {{RELATIONSHIP_2}}
+    {{ENTITY_1}} ||--o{ {{ENTITY_3}} : {{RELATIONSHIP_3}}
+
+    {{ENTITY_1}} {
+        uuid id PK "Primary key"
+        string {{FIELD_1}} UK "Unique constraint"
+        string {{FIELD_2}} "Required field"
+        int {{FIELD_3}} "Numeric field"
+        boolean {{FIELD_4}} "Boolean flag"
+        timestamp created_at "Creation timestamp"
+        timestamp updated_at "Last update timestamp"
+    }
+
+    {{ENTITY_2}} {
+        uuid id PK
+        uuid {{FK_TO_ENTITY_1}} FK "Foreign key to {{ENTITY_1}}"
+        string {{FIELD_5}}
+        text {{FIELD_6}} "Long text field"
+        enum {{FIELD_7}} "Enum type"
+        decimal {{FIELD_8}} "Decimal number"
+        date {{FIELD_9}} "Date only"
+        timestamp created_at
+    }
+
+    {{ENTITY_3}} {
+        uuid id PK
+        uuid {{FK_TO_ENTITY_1}} FK
+        uuid {{FK_TO_ENTITY_2}} FK
+        json {{FIELD_10}} "JSON data"
+        timestamp {{FIELD_11}}
+        timestamp created_at
+        timestamp updated_at
+    }
+
+%% Template Variables:
+%% {{ENTITY_*}} - Entity/table names (UPPERCASE convention)
+%% {{RELATIONSHIP_*}} - Relationship descriptions (e.g., "has", "belongs to")
+%% {{FIELD_*}} - Field names (snake_case convention)
+%% {{FK_TO_*}} - Foreign key field names
+
+%% Relationship Cardinality:
+%% ||--|| : one to one
+%% ||--o{ : one to many
+%% }o--|| : many to one
+%% }o--o{ : many to many
+
+%% Field Constraints:
+%% PK : Primary Key
+%% FK : Foreign Key
+%% UK : Unique Key
+
+%% Common Field Types:
+%% - uuid, int, bigint, string, text
+%% - boolean, enum, json
+%% - decimal, float, money
+%% - date, time, timestamp, datetime
+
+%% Best Practices:
+%% - Always include id (PK), created_at, updated_at
+%% - Use uuid for distributed systems
+%% - Add field comments for clarity
+%% - Show foreign key relationships clearly
--- a/agents/diagrams-architect/templates/sequence-template.mmd
+++ b/agents/diagrams-architect/templates/sequence-template.mmd
@@ -0,0 +1,55 @@
+sequenceDiagram
+    participant {{ACTOR_1}} as {{ACTOR_1_NAME}}
+    participant {{ACTOR_2}} as {{ACTOR_2_NAME}}
+    participant {{ACTOR_3}} as {{ACTOR_3_NAME}}
+    participant {{ACTOR_4}} as {{ACTOR_4_NAME}}
+
+    {{ACTOR_1}}->>{{ACTOR_2}}: {{STEP_1_ACTION}}
+    activate {{ACTOR_2}}
+
+    {{ACTOR_2}}->>{{ACTOR_3}}: {{STEP_2_ACTION}}
+    activate {{ACTOR_3}}
+
+    {{ACTOR_3}}->>{{ACTOR_4}}: {{STEP_3_ACTION}}
+    {{ACTOR_4}}-->>{{ACTOR_3}}: {{STEP_3_RESPONSE}}
+
+    {{ACTOR_3}}-->>{{ACTOR_2}}: {{STEP_2_RESPONSE}}
+    deactivate {{ACTOR_3}}
+
+    alt {{SUCCESS_CONDITION}}
+        {{ACTOR_2}}-->>{{ACTOR_1}}: {{SUCCESS_RESPONSE}}
+        {{ACTOR_1}}->>{{ACTOR_1}}: {{SUCCESS_ACTION}}
+    else {{FAILURE_CONDITION}}
+        {{ACTOR_2}}-->>{{ACTOR_1}}: {{ERROR_RESPONSE}}
+        {{ACTOR_1}}->>{{ACTOR_1}}: {{ERROR_ACTION}}
+    end
+
+    deactivate {{ACTOR_2}}
+
+    %% Optional: Loop example
+    %% loop {{LOOP_CONDITION}}
+    %%     {{ACTOR}}->>{{TARGET}}: {{LOOP_ACTION}}
+    %% end
+
+    %% Optional: Note example
+    %% Note over {{ACTOR_1}},{{ACTOR_2}}: {{NOTE_TEXT}}
+
+%% Template Variables:
+%% {{ACTOR_*}} - Short identifier for participant
+%% {{ACTOR_*_NAME}} - Display name for participant
+%% {{STEP_*_ACTION}} - Action/message description
+%% {{STEP_*_RESPONSE}} - Response message
+%% {{SUCCESS_CONDITION}} - Condition for success path
+%% {{FAILURE_CONDITION}} - Condition for error path
+%% {{SUCCESS_RESPONSE}} - Success message
+%% {{SUCCESS_ACTION}} - Action on success
+%% {{ERROR_RESPONSE}} - Error message
+%% {{ERROR_ACTION}} - Action on error
+
+%% Notes:
+%% - Use activate/deactivate to show processing time
+%% - Use alt/else for conditional flows
+%% - Use loop for repeated actions
+%% - Use Note over for explanations
+%% - Solid arrow (->>) for requests
+%% - Dashed arrow (-->>) for responses
--- a/agents/diagrams-architect/test-cases/test-1-c4-context.yaml
+++ b/agents/diagrams-architect/test-cases/test-1-c4-context.yaml
@@ -0,0 +1,131 @@
+---
+test_id: diagrams-architect-001
+test_name: C4 Context Diagram Generation
+coverage:
+  - TC-B001 # User request detected
+  - TC-B004 # Correct Mermaid syntax
+  - TC-B005 # C4 Level 1 conventions
+  - TC-B006 # Saved to correct location
+  - TC-B007 # File named correctly
+priority: P1
+tags:
+  - c4-model
+  - context-diagram
+  - level-1
+---
+
+# Test Case: C4 Context Diagram Generation
+
+## Scenario
+
+User requests a C4 context diagram for an authentication system to understand system boundaries and external actors.
+
+## Input
+
+**User Request**: "Create C4 context diagram for authentication system"
+
+**Context Provided** (optional):
+- System handles user registration, login, password management
+- Integrates with email service for verification
+- Integrates with SMS gateway for 2FA
+- Supports OAuth providers (Google, GitHub, Microsoft)
+
+## Expected Agent Behavior
+
+1. **Recognize diagram type**: C4 Context (Level 1)
+2. **Choose appropriate template**: `c4-context-template.mmd`
+3. **Generate diagram** with:
+   - Clear title: "Authentication System Context"
+   - Main system: Authentication System
+   - Users: User, Administrator
+   - External systems: Email Service, SMS Gateway, OAuth Providers
+   - Relationships showing data flow
+4. **Validate syntax**:
+   - Starts with `C4Context` (NO `mermaid` keyword)
+   - All elements have descriptions in quotes
+   - All relationships labeled
+   - Proper indentation (2 spaces)
+5. **Specify file path**: `.specweave/docs/internal/architecture/diagrams/auth-context.mmd`
+6. **Provide validation instructions**: Tell user to verify rendering
+
+## Expected Output
+
+**Diagram Content** (approximate):
+```
+C4Context
+  title Authentication System Context
+
+  Person(user, "User", "A user who needs to authenticate")
+  Person(admin, "Administrator", "Manages user accounts")
+
+  System(auth, "Authentication System", "Handles user authentication, registration, password management")
+
+  System_Ext(email, "Email Service", "Sends verification and password reset emails")
+  System_Ext(sms, "SMS Gateway", "Sends 2FA codes via SMS")
+  System_Ext(oauth, "OAuth Providers", "Google, GitHub, Microsoft identity providers")
+
+  Rel(user, auth, "Authenticates, registers, resets password")
+  Rel(admin, auth, "Manages users, views audit logs")
+  Rel(auth, email, "Sends emails via")
+  Rel(auth, sms, "Sends SMS via")
+  Rel(auth, oauth, "Delegates authentication to")
+```
+
+**File Path**: `.specweave/docs/internal/architecture/diagrams/auth-context.mmd`
+
+**Validation Message**:
+```
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth-context.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Install Mermaid Preview extension if needed
+3. Verify the diagram renders correctly
+4. Confirm all systems and relationships are visible
+```
+
+## Success Criteria
+
+- [ ] Diagram uses correct C4 Context syntax
+- [ ] NO `mermaid` keyword present
+- [ ] All elements (Person, System, System_Ext) have descriptions
+- [ ] All relationships (Rel) have labels
+- [ ] Indentation is correct (2 spaces per level)
+- [ ] File path follows conventions
+- [ ] Validation instructions provided
+- [ ] Diagram would render correctly in Mermaid Preview
+
+## Failure Scenarios
+
+**Scenario 1: Uses `mermaid` keyword**
+```
+mermaid
+C4Context
+  ...
+```
+❌ FAIL: C4 diagrams must start directly with `C4Context`
+
+**Scenario 2: Missing descriptions**
+```
+C4Context
+  Person(user, User)
+```
+❌ FAIL: All elements must have descriptions in quotes
+
+**Scenario 3: Incorrect file location**
+```
+File: .specweave/docs/diagrams/context.mmd
+```
+❌ FAIL: Should be in `architecture/diagrams/` subdirectory
+
+## Traceability
+
+**Covers User Stories**:
+- US-B001: Create C4 Context Diagram
+
+**Covers Acceptance Criteria**:
+- TC-B001: User request detected by diagrams-generator skill
+- TC-B004: Agent creates diagram with correct Mermaid syntax
+- TC-B005: Diagram follows C4 Level 1 conventions (system boundary, external actors)
+- TC-B006: Diagram saved to correct location
+- TC-B007: File named correctly (e.g., `auth-context.mmd`)
--- a/agents/diagrams-architect/test-cases/test-2-sequence.yaml
+++ b/agents/diagrams-architect/test-cases/test-2-sequence.yaml
@@ -0,0 +1,150 @@
+---
+test_id: diagrams-architect-002
+test_name: Sequence Diagram Generation
+coverage:
+  - TC-B008 # Skill detects sequence diagram request
+  - TC-B009 # Agent generates sequenceDiagram syntax
+  - TC-B010 # Participants clearly labeled
+  - TC-B011 # Flow accurately represents process
+  - TC-B012 # Saved to correct location
+  - TC-B013 # File named correctly
+priority: P1
+tags:
+  - sequence-diagram
+  - interaction-flow
+  - authentication
+---
+
+# Test Case: Sequence Diagram Generation
+
+## Scenario
+
+User requests a sequence diagram to understand the login authentication flow, including success and failure paths.
+
+## Input
+
+**User Request**: "Create sequence diagram for login flow"
+
+**Context Provided** (optional):
+- User submits credentials via browser
+- AuthService validates against database
+- Session created on success
+- Error message on failure
+
+## Expected Agent Behavior
+
+1. **Recognize diagram type**: Sequence diagram
+2. **Choose appropriate template**: `sequence-template.mmd`
+3. **Generate diagram** with:
+   - Participants: User, Browser, AuthService, Database, SessionStore
+   - Clear interaction sequence
+   - Success path (alt) and failure path (else)
+   - Activation boxes showing processing time
+   - Response arrows (dashed)
+4. **Validate syntax**:
+   - Starts with `sequenceDiagram` (uses `mermaid` keyword for non-C4)
+   - All participants defined
+   - Message arrows correct (->>, -->>)
+   - Alt/else blocks properly structured
+5. **Specify file path**: `.specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd`
+6. **Provide validation instructions**
+
+## Expected Output
+
+**Diagram Content** (approximate):
+```
+sequenceDiagram
+    participant User
+    participant Browser
+    participant AuthService
+    participant Database
+    participant SessionStore
+
+    User->>Browser: Enter credentials
+    Browser->>AuthService: POST /api/auth/login
+    activate AuthService
+
+    AuthService->>Database: Query user by email
+    Database-->>AuthService: User record
+
+    AuthService->>AuthService: Verify password (bcrypt)
+
+    alt Password valid
+        AuthService->>SessionStore: Create session
+        SessionStore-->>AuthService: Session ID
+        AuthService-->>Browser: 200 OK + Session cookie
+        Browser-->>User: Redirect to dashboard
+    else Password invalid
+        AuthService-->>Browser: 401 Unauthorized
+        Browser-->>User: Show error message
+    end
+
+    deactivate AuthService
+```
+
+**File Path**: `.specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd`
+
+**Validation Message**:
+```
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the sequence diagram renders correctly
+3. Confirm all participants and messages are clear
+4. Verify success and failure paths are visible
+```
+
+## Success Criteria
+
+- [ ] Diagram uses correct sequenceDiagram syntax
+- [ ] Includes `mermaid` keyword (standard for non-C4 diagrams)
+- [ ] All participants clearly defined
+- [ ] Request arrows are solid (->>)
+- [ ] Response arrows are dashed (-->>)
+- [ ] Alt/else block shows conditional logic
+- [ ] Activate/deactivate shows processing time
+- [ ] File path follows conventions (module/flows/ subdirectory)
+- [ ] Validation instructions provided
+- [ ] Diagram would render correctly
+
+## Failure Scenarios
+
+**Scenario 1: Missing participant definition**
+```
+sequenceDiagram
+    User->>Browser: Enter credentials
+```
+❌ FAIL: Participants should be explicitly defined
+
+**Scenario 2: Wrong arrow types**
+```
+Browser-->>AuthService: POST /api/auth/login
+```
+❌ FAIL: Requests should use solid arrows (->>) not dashed
+
+**Scenario 3: Missing alt/else for conditional flow**
+```
+AuthService->>SessionStore: Create session
+AuthService-->>Browser: 401 Unauthorized
+```
+❌ FAIL: Should use alt/else to show conditional paths
+
+**Scenario 4: Incorrect file location**
+```
+File: .specweave/docs/internal/architecture/diagrams/login-flow.mmd
+```
+❌ FAIL: Should be in module-specific `flows/` subdirectory
+
+## Traceability
+
+**Covers User Stories**:
+- US-B002: Create Sequence Diagram
+
+**Covers Acceptance Criteria**:
+- TC-B008: Skill detects sequence diagram request
+- TC-B009: Agent generates sequenceDiagram syntax
+- TC-B010: Participants clearly labeled
+- TC-B011: Flow accurately represents login process
+- TC-B012: Diagram saved to correct location
+- TC-B013: File named `login-flow.sequence.mmd` or `login-flow.mmd`
--- a/agents/diagrams-architect/test-cases/test-3-er-diagram.yaml
+++ b/agents/diagrams-architect/test-cases/test-3-er-diagram.yaml
@@ -0,0 +1,182 @@
+---
+test_id: diagrams-architect-003
+test_name: ER Diagram Generation
+coverage:
+  - TC-B014 # Skill detects ER diagram request
+  - TC-B015 # Agent generates erDiagram syntax
+  - TC-B016 # Entities, attributes, relationships correctly defined
+  - TC-B017 # Primary/foreign keys marked
+  - TC-B018 # Saved to correct location
+  - TC-B019 # File named correctly
+priority: P1
+tags:
+  - er-diagram
+  - data-model
+  - database-schema
+---
+
+# Test Case: ER Diagram Generation
+
+## Scenario
+
+User requests an entity-relationship diagram to understand the authentication data model, including user, session, and token entities.
+
+## Input
+
+**User Request**: "Create ER diagram for user and session entities"
+
+**Context Provided** (optional):
+- USER table: id, email, password_hash, created_at
+- SESSION table: id, user_id, token, expires_at
+- REFRESH_TOKEN table: id, user_id, token, expires_at
+- PASSWORD_RESET table: id, user_id, token, expires_at
+
+## Expected Agent Behavior
+
+1. **Recognize diagram type**: ER diagram
+2. **Choose appropriate template**: `er-diagram-template.mmd`
+3. **Generate diagram** with:
+   - Entities: USER, SESSION, REFRESH_TOKEN, PASSWORD_RESET
+   - Relationships with cardinality (one-to-many, many-to-one)
+   - Primary keys (PK), foreign keys (FK), unique keys (UK)
+   - Field types and constraints
+   - Timestamps (created_at, updated_at)
+4. **Validate syntax**:
+   - Starts with `erDiagram` (uses `mermaid` keyword)
+   - Relationship cardinality correct (||--o{, }o--||, etc.)
+   - Field definitions include type and constraints
+   - Proper formatting
+5. **Specify file path**: `.specweave/docs/internal/architecture/diagrams/auth/data-model.mmd`
+6. **Provide validation instructions**
+
+## Expected Output
+
+**Diagram Content** (approximate):
+```
+erDiagram
+    USER ||--o{ SESSION : has
+    USER ||--o{ REFRESH_TOKEN : has
+    USER ||--o{ PASSWORD_RESET : requests
+
+    USER {
+        uuid id PK
+        string email UK
+        string password_hash
+        string first_name
+        string last_name
+        boolean email_verified
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    SESSION {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        string ip_address
+        string user_agent
+        timestamp created_at
+    }
+
+    REFRESH_TOKEN {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean revoked
+        timestamp created_at
+    }
+
+    PASSWORD_RESET {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean used
+        timestamp created_at
+    }
+```
+
+**File Path**: `.specweave/docs/internal/architecture/diagrams/auth/data-model.mmd`
+
+**Validation Message**:
+```
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the ER diagram renders correctly
+3. Confirm relationships and cardinality are accurate
+4. Check that all fields and constraints are visible
+```
+
+## Success Criteria
+
+- [ ] Diagram uses correct erDiagram syntax
+- [ ] Includes `mermaid` keyword
+- [ ] Entities named in UPPERCASE
+- [ ] Relationship cardinality correct (||--o{, }o--||, }o--o{)
+- [ ] All entities have id PK field
+- [ ] Foreign keys marked with FK
+- [ ] Unique constraints marked with UK
+- [ ] Field types specified (uuid, string, boolean, timestamp, etc.)
+- [ ] Timestamps (created_at, updated_at) included
+- [ ] Relationships have descriptive labels (has, belongs to, requests)
+- [ ] File path follows conventions (module subdirectory)
+- [ ] Validation instructions provided
+- [ ] Diagram would render correctly
+
+## Failure Scenarios
+
+**Scenario 1: Incorrect relationship cardinality**
+```
+USER ||--|| SESSION : has
+```
+❌ FAIL: User can have multiple sessions (should be one-to-many: ||--o{)
+
+**Scenario 2: Missing field constraints**
+```
+USER {
+    uuid id
+    string email
+}
+```
+❌ FAIL: Should mark id as PK, email as UK
+
+**Scenario 3: Missing foreign key relationships**
+```
+SESSION {
+    uuid id PK
+    uuid user_id
+}
+```
+❌ FAIL: user_id should be marked as FK
+
+**Scenario 4: Lowercase entity names**
+```
+user ||--o{ session : has
+```
+❌ FAIL: Entity names should be UPPERCASE convention
+
+**Scenario 5: Missing timestamps**
+```
+USER {
+    uuid id PK
+    string email UK
+}
+```
+❌ FAIL: Should include created_at, updated_at
+
+## Traceability
+
+**Covers User Stories**:
+- US-B003: Create ER Diagram
+
+**Covers Acceptance Criteria**:
+- TC-B014: Skill detects ER diagram request
+- TC-B015: Agent generates erDiagram syntax
+- TC-B016: Entities, attributes, relationships correctly defined
+- TC-B017: Primary/foreign keys marked
+- TC-B018: Diagram saved to correct location
+- TC-B019: File named `data-model.mmd` or `{module}-data-model.mmd`