specweave 0.1.0 → 0.1.2

package/src/skills/diagrams-generator/SKILL.md

@@ -1,25 +1,225 @@
 ---
 name: diagrams-generator
-description: Generate Mermaid diagrams following C4 conventions. Activates for create diagram, system diagram, architecture diagram, C4 diagram, sequence diagram, ER diagram, data model. Coordinates with diagrams-architect agent.
+description: Generate Mermaid diagrams following C4 conventions. Activates for create diagram, draw diagram, visualize, system diagram, architecture diagram, C4 diagram, context diagram, container diagram, component diagram, sequence diagram, ER diagram, entity relationship, data model, deployment diagram. Coordinates with diagrams-architect agent.
 allowed-tools: Read, Write, Edit, Task
 ---
 
 # Diagrams Generator Skill
 
-Coordinates diagram generation by delegating to `diagrams-architect` agent.
+Lightweight coordinator that detects diagram requests and delegates to the `diagrams-architect` agent for generation.
 
-## Responsibilities
+## Your Role
 
-1. Detect diagram requests (C4, sequence, ER, deployment)
-2. Load source documentation
-3. Invoke `diagrams-architect` agent
-4. Save diagrams to correct locations
+You are a **coordinator**, not a diagram generator. Your job is to:
+1. **Detect** when user wants a diagram
+2. **Identify** diagram type and scope
+3. **Load context** (if available)
+4. **Invoke** diagrams-architect agent
+5. **Save** diagram to correct location
+6. **Confirm** completion to user
 
-## Usage
+**DO NOT generate diagrams yourself** - Always delegate to `diagrams-architect` agent.
 
-**C4 Context**: "Create C4 context diagram"
-**C4 Component** (LLD): "Create component diagram for Auth Service"
-**Sequence**: "Create login flow diagram"
-**ER Diagram**: "Create data model for auth module"
+## Activation Keywords
 
-All diagram logic is handled by the `diagrams-architect` agent.
+This skill activates when user mentions:
+- **General**: "create diagram", "draw diagram", "visualize", "generate diagram"
+- **C4 Model**: "C4 diagram", "context diagram", "container diagram", "component diagram"
+- **Flows**: "sequence diagram", "flow diagram", "interaction diagram"
+- **Data**: "ER diagram", "entity relationship", "data model", "database schema"
+- **Infrastructure**: "deployment diagram", "architecture diagram", "infrastructure diagram"
+
+## Workflow
+
+### Step 1: Detect Diagram Type
+
+Analyze user's request to determine:
+
+**C4 Context (Level 1)**: System boundaries, external actors
+- Keywords: "context", "system", "boundaries", "external"
+- Example: "Create C4 context diagram for authentication"
+
+**C4 Container (Level 2)**: Services, applications, databases
+- Keywords: "container", "services", "applications", "microservices"
+- Example: "Create container diagram showing our services"
+
+**C4 Component (Level 3)**: Internal module structure
+- Keywords: "component", "internal", "module", "service internals"
+- Example: "Create component diagram for Auth Service"
+
+**Sequence**: Interaction flows
+- Keywords: "sequence", "flow", "interaction", "steps", "process"
+- Example: "Create login flow diagram"
+
+**ER Diagram**: Data models
+- Keywords: "ER", "entity", "relationship", "data model", "schema"
+- Example: "Create data model for users and sessions"
+
+**Deployment**: Infrastructure
+- Keywords: "deployment", "infrastructure", "hosting", "cloud"
+- Example: "Create deployment diagram for production"
+
+### Step 2: Load Context (Optional)
+
+If relevant specifications exist, load them:
+
+```typescript
+// For authentication diagram:
+const spec = await Read('.specweave/docs/internal/strategy/auth/spec.md');
+const architecture = await Read('.specweave/docs/internal/architecture/auth-design.md');
+
+// Pass to agent as context
+```
+
+### Step 3: Invoke diagrams-architect Agent
+
+Delegate to agent via Task tool:
+
+```typescript
+const result = await Task({
+  subagent_type: "diagrams-architect",
+  prompt: `Create ${diagramType} diagram for ${scope}
+
+Context:
+${loadedContext}
+
+Requirements:
+- Follow SpecWeave C4 conventions
+- Use correct file naming
+- Include validation instructions`,
+  description: `Generate ${diagramType} diagram`
+});
+```
+
+### Step 4: Save Diagram
+
+The agent returns diagram content. Save to correct location:
+
+**C4 Context/Container**: `.specweave/docs/internal/architecture/diagrams/`
+**C4 Component**: `.specweave/docs/internal/architecture/diagrams/{module}/`
+**Sequence**: `.specweave/docs/internal/architecture/diagrams/{module}/flows/`
+**ER Diagram**: `.specweave/docs/internal/architecture/diagrams/{module}/data-model.mmd`
+**Deployment**: `.specweave/docs/internal/operations/diagrams/deployment-{env}.mmd`
+
+### Step 5: Confirm to User
+
+```
+✅ Diagram created: {path}
+📋 Please verify rendering in VS Code with Mermaid Preview extension
+```
+
+## Examples
+
+### Example 1: C4 Context Diagram
+
+**User**: "Create C4 context diagram for authentication"
+
+**You**:
+1. Detect: C4 Context (Level 1)
+2. Load context: Read auth spec if exists
+3. Invoke agent:
+```typescript
+await Task({
+  subagent_type: "diagrams-architect",
+  prompt: "Create C4 context diagram for authentication system. Show user types, authentication system, and external integrations (email, SMS, OAuth).",
+  description: "Generate C4 Level 1 diagram"
+});
+```
+4. Agent returns diagram content
+5. Save to `.specweave/docs/internal/architecture/diagrams/auth-context.mmd`
+6. Confirm: "✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth-context.mmd"
+
+### Example 2: Sequence Diagram
+
+**User**: "Create login flow diagram"
+
+**You**:
+1. Detect: Sequence diagram
+2. Load context: Read login spec/flow docs if exist
+3. Invoke agent:
+```typescript
+await Task({
+  subagent_type: "diagrams-architect",
+  prompt: "Create sequence diagram for login flow. Show: User → Browser → AuthService → Database → SessionStore. Include success and failure paths.",
+  description: "Generate sequence diagram"
+});
+```
+4. Agent returns diagram
+5. Save to `.specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd`
+6. Confirm completion
+
+### Example 3: ER Diagram
+
+**User**: "Create data model for users and sessions"
+
+**You**:
+1. Detect: ER diagram
+2. Load context: Read database schema docs if exist
+3. Invoke agent:
+```typescript
+await Task({
+  subagent_type: "diagrams-architect",
+  prompt: "Create ER diagram for authentication data model. Entities: USER, SESSION, REFRESH_TOKEN, PASSWORD_RESET. Show relationships and key fields.",
+  description: "Generate ER diagram"
+});
+```
+4. Agent returns diagram
+5. Save to `.specweave/docs/internal/architecture/diagrams/auth/data-model.mmd`
+6. Confirm completion
+
+## Validation
+
+After saving diagram, ALWAYS tell user to validate:
+
+```
+✅ Diagram created: {path}
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Install Mermaid Preview extension if needed
+3. Verify diagram renders correctly
+4. Report any syntax errors
+
+If diagram fails to render, I will regenerate with fixes.
+```
+
+## File Naming Conventions
+
+**C4 Context**: `{system-name}-context.mmd` or `system-context.mmd`
+**C4 Container**: `{system-name}-container.mmd` or `system-container.mmd`
+**C4 Component**: `component-{service-name}.mmd`
+**Sequence**: `{flow-name}-flow.mmd` or `{flow-name}.sequence.mmd`
+**ER Diagram**: `data-model.mmd` or `{module}-data-model.mmd`
+**Deployment**: `deployment-{environment}.mmd`
+
+## Error Handling
+
+**If diagram type is unclear**:
+- Ask user for clarification
+- Example: "Do you want a C4 context diagram (system level) or container diagram (service level)?"
+
+**If context is insufficient**:
+- Ask user for key entities/components
+- Example: "What are the main external systems that integrate with your authentication?"
+
+**If agent returns error**:
+- Report error to user
+- Suggest corrections
+- Retry with adjusted prompt
+
+## Test Cases
+
+See `test-cases/` directory:
+- `test-1.yaml` - Diagram type detection
+- `test-2.yaml` - Agent coordination
+- `test-3.yaml` - File placement and naming
+
+## Integration
+
+**Invoked by**: User request (auto-activation via description keywords)
+**Invokes**: `diagrams-architect` agent (via Task tool)
+**Output**: Mermaid diagram files in correct locations
+
+---
+
+**Remember**: You are a coordinator. Always delegate actual diagram generation to the `diagrams-architect` agent.

package/src/skills/dotnet-backend/test-cases/test-1-rest-api.yaml

@@ -0,0 +1,14 @@
+name: "Create ASP.NET Core REST API"
+description: "Test creating a REST API controller with Entity Framework"
+user_input: "Create a REST API for managing products with CRUD operations"
+expected_behavior:
+  - Generates ASP.NET Core controller with appropriate attributes
+  - Includes Entity Framework DbContext integration
+  - Implements CRUD endpoints (GET, POST, PUT, DELETE)
+  - Includes async/await pattern
+  - Adds proper HTTP status codes
+validation:
+  - Uses [ApiController] and [Route] attributes
+  - Controller inherits from ControllerBase
+  - Methods use async Task<ActionResult> pattern
+  - Includes dependency injection for DbContext

package/src/skills/dotnet-backend/test-cases/test-2-authentication.yaml

@@ -0,0 +1,13 @@
+name: "Implement JWT Authentication"
+description: "Test implementing JWT authentication in ASP.NET Core"
+user_input: "Add JWT token-based authentication to my API"
+expected_behavior:
+  - Configures JWT authentication in Program.cs/Startup.cs
+  - Creates login endpoint that generates JWT tokens
+  - Includes claims-based authorization
+  - Protects endpoints with [Authorize] attribute
+validation:
+  - Uses Microsoft.AspNetCore.Authentication.JwtBearer
+  - Configures token validation parameters
+  - Generates tokens with claims
+  - Implements token refresh logic

package/src/skills/dotnet-backend/test-cases/test-3-minimal-api.yaml

@@ -0,0 +1,13 @@
+name: "Create Minimal API"
+description: "Test creating .NET 6+ minimal API endpoints"
+user_input: "Create a minimal API for user management"
+expected_behavior:
+  - Uses app.MapGet/MapPost/MapPut/MapDelete
+  - Implements endpoints in Program.cs
+  - Includes route parameters and query strings
+  - Uses dependency injection
+validation:
+  - No controller classes needed
+  - Uses lambda expressions for endpoints
+  - Implements proper HTTP verbs
+  - Includes validation and error handling

package/src/skills/figma-designer/test-cases/test-1-design-system.yaml

@@ -0,0 +1,13 @@
+name: "Create Design System Foundation"
+description: "Test creating design tokens and base components in Figma"
+user_input: "Create a design system with color palette, typography, and spacing"
+expected_behavior:
+  - Defines color tokens (primary, secondary, neutral, semantic)
+  - Sets up typography scale (headings, body, captions)
+  - Creates spacing tokens (4px, 8px, 16px, etc.)
+  - Organizes tokens in Figma variables
+validation:
+  - Uses Figma variables for colors
+  - Defines text styles for typography
+  - Creates spacing components
+  - Follows naming conventions (color/primary/500)

package/src/skills/figma-designer/test-cases/test-2-component-library.yaml

@@ -0,0 +1,13 @@
+name: "Build Component Library"
+description: "Test creating reusable UI components using atomic design"
+user_input: "Create a button component library with all variants"
+expected_behavior:
+  - Creates button component with variants (primary, secondary, ghost)
+  - Implements states (default, hover, active, disabled)
+  - Uses auto-layout for responsive sizing
+  - Includes icon support
+validation:
+  - Component uses variants
+  - States implemented as component properties
+  - Uses auto-layout
+  - Properly linked to design tokens

package/src/skills/figma-designer/test-cases/test-3-responsive-layout.yaml

@@ -0,0 +1,13 @@
+name: "Design Responsive Layout"
+description: "Test creating responsive layouts with constraints"
+user_input: "Design a responsive dashboard layout for desktop and mobile"
+expected_behavior:
+  - Creates frames for different breakpoints (mobile, tablet, desktop)
+  - Uses auto-layout for flexible content
+  - Implements proper constraints
+  - Shows responsive behavior
+validation:
+  - Multiple frames for breakpoints
+  - Auto-layout on parent containers
+  - Constraints set appropriately
+  - Components adapt to different widths

package/src/skills/figma-implementer/test-cases/test-1-design-to-react.yaml

@@ -0,0 +1,13 @@
+name: "Convert Figma Design to React Component"
+description: "Test converting a Figma component to production React code"
+user_input: "Convert this Figma button component to React with TypeScript"
+expected_behavior:
+  - Extracts design tokens (colors, spacing, typography)
+  - Generates React component with proper props
+  - Implements all variants from Figma
+  - Includes Tailwind CSS or CSS modules
+validation:
+  - Component matches Figma design pixel-perfect
+  - Props match Figma variants
+  - Uses design tokens correctly
+  - Includes TypeScript interfaces

package/src/skills/figma-implementer/test-cases/test-2-storybook.yaml

@@ -0,0 +1,13 @@
+name: "Create Storybook Stories for Figma Components"
+description: "Test generating Storybook stories from Figma components"
+user_input: "Create Storybook stories for my button component from Figma"
+expected_behavior:
+  - Generates .stories.tsx file
+  - Creates stories for each variant
+  - Includes controls for interactive props
+  - Matches Figma design exactly
+validation:
+  - Stories show all variants
+  - Controls allow testing different states
+  - Visual regression tests possible
+  - Documentation includes usage examples

package/src/skills/figma-implementer/test-cases/test-3-design-tokens.yaml

@@ -0,0 +1,13 @@
+name: "Extract and Implement Design Tokens"
+description: "Test extracting design tokens from Figma and generating code"
+user_input: "Extract all design tokens from this Figma file"
+expected_behavior:
+  - Extracts colors, typography, spacing, shadows, borders
+  - Generates token files (JSON, CSS variables, or TypeScript)
+  - Creates Tailwind config if needed
+  - Maintains consistency with Figma
+validation:
+  - All token categories extracted
+  - Proper naming conventions
+  - Values match Figma exactly
+  - Tokens are importable and usable

package/src/skills/frontend/test-cases/test-1-react-component.yaml

@@ -0,0 +1,13 @@
+name: "Create React Component with Hooks"
+description: "Test creating a React component using hooks"
+user_input: "Create a user profile component with state management"
+expected_behavior:
+  - Generates functional component with TypeScript
+  - Uses useState for local state
+  - Uses useEffect for side effects
+  - Implements proper prop types
+validation:
+  - Uses React.FC or function component syntax
+  - Includes TypeScript interfaces for props
+  - Implements useState hook
+  - Includes proper cleanup in useEffect

package/src/skills/frontend/test-cases/test-2-form-validation.yaml

@@ -0,0 +1,13 @@
+name: "Implement Form with Validation"
+description: "Test creating a form with validation using React Hook Form"
+user_input: "Create a registration form with validation"
+expected_behavior:
+  - Uses react-hook-form for form management
+  - Implements Zod schema validation
+  - Includes error message display
+  - Handles form submission
+validation:
+  - Uses useForm hook
+  - Implements Zod schema with zodResolver
+  - Shows validation errors
+  - Includes submit handler

package/src/skills/frontend/test-cases/test-3-state-management.yaml

@@ -0,0 +1,13 @@
+name: "Implement Global State Management"
+description: "Test setting up Zustand for global state"
+user_input: "Add global state management for user authentication"
+expected_behavior:
+  - Creates Zustand store
+  - Implements actions and selectors
+  - Uses TypeScript for type safety
+  - Includes persistence if needed
+validation:
+  - Uses create from zustand
+  - Implements store interface
+  - Exports custom hooks
+  - Includes proper typing

package/src/skills/nextjs/test-cases/test-1-app-router.yaml

@@ -0,0 +1,13 @@
+name: "Create Next.js App Router Page"
+description: "Test creating a page using Next.js 14+ App Router"
+user_input: "Create a products listing page using App Router"
+expected_behavior:
+  - Creates app/products/page.tsx
+  - Uses Server Components by default
+  - Implements async data fetching
+  - Includes proper metadata export
+validation:
+  - File located in app directory
+  - Uses default export function
+  - Implements async component if needed
+  - Exports metadata object

package/src/skills/nextjs/test-cases/test-2-server-actions.yaml

@@ -0,0 +1,13 @@
+name: "Implement Server Actions"
+description: "Test creating server actions for form handling"
+user_input: "Create a contact form using server actions"
+expected_behavior:
+  - Creates server action with 'use server' directive
+  - Implements form submission handler
+  - Uses FormData for input
+  - Includes validation with Zod
+validation:
+  - Uses 'use server' at top of action file
+  - Accepts FormData parameter
+  - Returns appropriate response
+  - Implements revalidatePath or redirect

package/src/skills/nextjs/test-cases/test-3-api-routes.yaml

@@ -0,0 +1,13 @@
+name: "Create API Route Handler"
+description: "Test creating API routes in App Router"
+user_input: "Create an API endpoint for fetching user data"
+expected_behavior:
+  - Creates app/api/users/route.ts
+  - Implements GET, POST handlers
+  - Uses NextRequest and NextResponse
+  - Includes error handling
+validation:
+  - File named route.ts in app/api directory
+  - Exports GET, POST functions
+  - Uses NextResponse.json() for responses
+  - Implements proper status codes

package/src/skills/nodejs-backend/test-cases/test-1-express-api.yaml

@@ -0,0 +1,13 @@
+name: "Create Express.js REST API"
+description: "Test creating Express REST API with TypeScript"
+user_input: "Create an Express API for managing tasks with CRUD operations"
+expected_behavior:
+  - Generates Express router with TypeScript
+  - Implements CRUD endpoints
+  - Includes middleware (validation, error handling)
+  - Uses async/await with proper error handling
+validation:
+  - Uses express.Router()
+  - Implements GET, POST, PUT, DELETE routes
+  - Includes request validation (Zod or class-validator)
+  - Has centralized error handling middleware

package/src/skills/nodejs-backend/test-cases/test-2-prisma-orm.yaml

@@ -0,0 +1,13 @@
+name: "Implement Prisma ORM Integration"
+description: "Test setting up Prisma with PostgreSQL"
+user_input: "Add Prisma ORM to my Node.js project for user management"
+expected_behavior:
+  - Creates Prisma schema with User model
+  - Generates Prisma Client
+  - Implements database queries using Prisma
+  - Includes migrations setup
+validation:
+  - Has schema.prisma file
+  - Uses @prisma/client
+  - Implements proper typing
+  - Includes seed scripts

package/src/skills/nodejs-backend/test-cases/test-3-authentication.yaml

@@ -0,0 +1,13 @@
+name: "Implement JWT Authentication"
+description: "Test adding JWT authentication to Express API"
+user_input: "Add JWT authentication and authorization to my API"
+expected_behavior:
+  - Creates login/register endpoints
+  - Generates and validates JWT tokens
+  - Implements auth middleware
+  - Includes password hashing (bcrypt)
+validation:
+  - Uses jsonwebtoken package
+  - Implements bcrypt for password hashing
+  - Creates authentication middleware
+  - Protects routes with middleware

package/src/skills/python-backend/test-cases/test-1-fastapi-crud.yaml

@@ -0,0 +1,13 @@
+name: "Create FastAPI CRUD API"
+description: "Test creating FastAPI REST API with Pydantic models"
+user_input: "Create a FastAPI application for managing products"
+expected_behavior:
+  - Generates FastAPI app with CRUD endpoints
+  - Uses Pydantic models for validation
+  - Implements async route handlers
+  - Includes automatic OpenAPI documentation
+validation:
+  - Uses FastAPI() instance
+  - Implements @app.get, @app.post, @app.put, @app.delete decorators
+  - Uses Pydantic BaseModel for schemas
+  - Includes type hints and async def

package/src/skills/python-backend/test-cases/test-2-sqlalchemy.yaml

@@ -0,0 +1,13 @@
+name: "Implement SQLAlchemy ORM"
+description: "Test integrating SQLAlchemy with FastAPI"
+user_input: "Add SQLAlchemy database integration to my FastAPI project"
+expected_behavior:
+  - Creates SQLAlchemy models
+  - Sets up database session management
+  - Implements dependency injection for db session
+  - Includes Alembic migrations
+validation:
+  - Uses SQLAlchemy declarative_base
+  - Implements database.py with engine and SessionLocal
+  - Uses Depends() for dependency injection
+  - Includes migration scripts

package/src/skills/python-backend/test-cases/test-3-authentication.yaml

@@ -0,0 +1,13 @@
+name: "Implement OAuth2 JWT Authentication"
+description: "Test adding OAuth2 JWT authentication to FastAPI"
+user_input: "Add OAuth2 password bearer authentication to my API"
+expected_behavior:
+  - Creates OAuth2PasswordBearer dependency
+  - Implements JWT token generation and validation
+  - Uses passlib for password hashing
+  - Protects routes with Depends(get_current_user)
+validation:
+  - Uses fastapi.security.OAuth2PasswordBearer
+  - Implements python-jose for JWT
+  - Uses passlib[bcrypt] for password hashing
+  - Includes login endpoint with OAuth2PasswordRequestForm

package/src/skills/specweave-ado-mapper/test-cases/test-1-export-to-ado.yaml

@@ -0,0 +1,13 @@
+name: "Export SpecWeave Increment to Azure DevOps"
+description: "Test exporting a SpecWeave increment to ADO Epic/Features/Stories"
+user_input: "Export increment 0001-user-auth to Azure DevOps"
+expected_behavior:
+  - Creates Epic from increment spec
+  - Creates Features from main sections
+  - Creates User Stories from tasks
+  - Maps test cases to Test Cases in ADO
+validation:
+  - Epic title matches increment name
+  - Features map to spec sections
+  - User Stories have acceptance criteria
+  - Work item IDs stored in SpecWeave

package/src/skills/specweave-ado-mapper/test-cases/test-2-import-from-ado.yaml

@@ -0,0 +1,13 @@
+name: "Import Azure DevOps Epic to SpecWeave"
+description: "Test importing ADO Epic as a SpecWeave increment"
+user_input: "Import ADO Epic #12345 into SpecWeave"
+expected_behavior:
+  - Creates increment folder with ADO Epic name
+  - Generates spec.md from Epic description
+  - Converts Features to sections in spec
+  - Creates tasks.md from User Stories
+validation:
+  - Increment follows SpecWeave structure
+  - spec.md has proper sections
+  - tasks.md includes all stories
+  - ADO references preserved

package/src/skills/specweave-ado-mapper/test-cases/test-3-bidirectional-sync.yaml

@@ -0,0 +1,13 @@
+name: "Bidirectional Sync with Conflict Resolution"
+description: "Test syncing changes between SpecWeave and ADO"
+user_input: "Sync increment 0002-payment with ADO, handle conflicts"
+expected_behavior:
+  - Detects changes in both systems
+  - Shows conflicts for manual resolution
+  - Syncs approved changes bidirectionally
+  - Maintains traceability
+validation:
+  - Conflict detection works
+  - User can choose resolution strategy
+  - Sync maintains data integrity
+  - Audit log of sync operations