specweave 0.1.0 → 0.1.2

package/src/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

package/src/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`)

package/src/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`

package/src/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`

package/src/skills/diagrams-architect/test-cases/test-1-c4-context.yaml

@@ -0,0 +1,13 @@
+name: "Create C4 Context Diagram"
+description: "Test creating a C4 Level 1 context diagram for a system"
+user_input: "Create a C4 context diagram for an e-commerce platform"
+expected_behavior:
+  - Generates valid Mermaid C4Context diagram
+  - Includes system boundary
+  - Shows external actors (users, external systems)
+  - Shows relationships and dependencies
+validation:
+  - Diagram starts with C4Context keyword
+  - Contains Person/System elements
+  - Includes Boundary definition
+  - Has BiRel or Rel relationship arrows

package/src/skills/diagrams-architect/test-cases/test-2-sequence-diagram.yaml

@@ -0,0 +1,13 @@
+name: "Create Sequence Diagram"
+description: "Test creating a sequence diagram for API authentication flow"
+user_input: "Create a sequence diagram for OAuth 2.0 authentication flow"
+expected_behavior:
+  - Generates valid Mermaid sequence diagram
+  - Shows participants (client, auth server, resource server)
+  - Includes authentication steps in correct order
+  - Shows token exchange flow
+validation:
+  - Diagram starts with sequenceDiagram keyword
+  - Contains participant declarations
+  - Has sequential messages (->>, -->)
+  - Includes notes for clarity

package/src/skills/diagrams-architect/test-cases/test-3-er-diagram.yaml

@@ -0,0 +1,13 @@
+name: "Create Entity Relationship Diagram"
+description: "Test creating an ER diagram for database schema"
+user_input: "Create an ER diagram for a multi-tenant SaaS database"
+expected_behavior:
+  - Generates valid Mermaid ER diagram
+  - Shows entities (tables)
+  - Shows relationships with cardinality
+  - Includes key attributes
+validation:
+  - Diagram starts with erDiagram keyword
+  - Contains entity definitions
+  - Has relationships (||--o{, etc.)
+  - Shows primary/foreign key fields