@comfanion/workflow 4.36.39 → 4.36.41

package/src/opencode/skills/diagram-creation/SKILL.md

@@ -1,17 +1,19 @@
 ---
-description: Creates technical diagrams (C4, sequence, ER, flowcharts) in Mermaid or text format
-mode: subagent
-model: anthropic/claude-sonnet-4-20250514
-temperature: 0.2
-tools:
-  write: true
-  edit: true
-  bash: false
+name: diagram-creation
+description: Use when creating technical diagrams - C4 architecture, sequence flows, ER data models, flowcharts, state machines, or deployment infrastructure
+license: MIT
+compatibility: opencode
+metadata:
+  domain: documentation
+  formats: mermaid, ascii, plantuml
+  artifacts: docs/diagrams/
 ---
 
-# Diagram Creator
+# Diagram Creation Skill
 
-You are a Technical Diagram Specialist who creates clear, informative diagrams for software architecture documentation. You produce diagrams in Mermaid format (renderable in GitHub/GitLab) or ASCII art for universal compatibility.
+## Overview
+
+Creates clear, informative diagrams for software architecture documentation. Produces diagrams in Mermaid format (renderable in GitHub/GitLab) or ASCII art for universal compatibility.
 
 ## Core Responsibilities
 
@@ -21,6 +23,58 @@ You are a Technical Diagram Specialist who creates clear, informative diagrams f
 4. **Flowcharts** - Process and decision flows
 5. **State Diagrams** - State machines
 
+---
+
+## When to Use Which Diagram
+
+### Decision Guide
+
+| Question | Diagram Type |
+|----------|--------------|
+| What systems exist and how they connect? | **C4 Context** |
+| What are the main building blocks (services, DBs)? | **C4 Container** |
+| What's inside a service/module? | **C4 Component** |
+| How do components interact over time? | **Sequence** |
+| What data entities exist and relate? | **ER Diagram** |
+| What are the steps in a process? | **Flowchart** |
+| What states can an entity be in? | **State Diagram** |
+
+### By Audience
+
+| Audience | Best Diagrams |
+|----------|---------------|
+| **Stakeholders / Business** | C4 Context, high-level Flowchart |
+| **Architects** | C4 Container, C4 Component, ER |
+| **Developers** | Sequence, ER, State, C4 Component |
+| **New team members** | C4 Context → Container → Component (top-down) |
+| **Code reviewers** | Sequence (for specific flow) |
+
+### By Project Phase
+
+| Phase | Diagrams to Create |
+|-------|-------------------|
+| **Discovery** | C4 Context (rough), ER (draft) |
+| **Architecture** | C4 Container, C4 Component, ER (detailed) |
+| **Development** | Sequence (per feature), State (per entity) |
+| **Documentation** | All of above, refined |
+| **Troubleshooting** | Sequence (problem flow) |
+
+### C4 Model Zoom Levels
+
+```
+Level 1: CONTEXT     — System + external actors
+    ↓ zoom in
+Level 2: CONTAINER   — Services, DBs, queues inside system
+    ↓ zoom in  
+Level 3: COMPONENT   — Classes/modules inside a container
+    ↓ zoom in
+Level 4: CODE        — Class diagrams (usually auto-generated)
+```
+
+**Rule:** Start at Context, zoom in only as needed. Most projects need L1-L3.
+
+---
+
 ## Diagram Storage
 
 All diagrams go in `docs/diagrams/` with clear naming:
@@ -106,6 +160,86 @@ C4Container
 \`\`\`
 ```
 
+### C4 Component Diagram
+
+```markdown
+# [Service Name] Component Diagram
+
+## Overview
+Internal structure of [Service Name] container.
+
+## Diagram
+
+\`\`\`mermaid
+C4Component
+    title Component Diagram for [Service Name]
+    
+    Container_Boundary(svc, "[Service Name]") {
+        Component(ctrl, "API Controller", "Go", "HTTP handlers")
+        Component(usecase, "Use Cases", "Go", "Business logic orchestration")
+        Component(domain, "Domain", "Go", "Core business rules")
+        Component(repo, "Repository", "Go", "Data access")
+    }
+    
+    ContainerDb(db, "Database", "PostgreSQL")
+    Container(queue, "Message Queue", "Kafka")
+    
+    Rel(ctrl, usecase, "Calls")
+    Rel(usecase, domain, "Uses")
+    Rel(usecase, repo, "Persists via")
+    Rel(repo, db, "SQL")
+    Rel(usecase, queue, "Publishes events")
+\`\`\`
+
+## Components
+
+| Component | Responsibility | Dependencies |
+|-----------|---------------|--------------|
+| API Controller | HTTP routing, validation | Use Cases |
+| Use Cases | Orchestration, transactions | Domain, Repository |
+| Domain | Business rules, entities | None (pure) |
+| Repository | Data persistence | Database |
+
+## Patterns Used
+
+- Hexagonal Architecture (Ports & Adapters)
+- Dependency injection
+- Repository pattern
+```
+
+### C4 with ASCII (Alternative)
+
+When Mermaid C4 not supported, use ASCII:
+
+```markdown
+# System Context (ASCII)
+
+\`\`\`
+                         ┌─────────────┐
+                         │   Admin     │
+                         │   (Person)  │
+                         └──────┬──────┘
+                                │ manages
+                                ▼
+┌─────────────┐          ┌─────────────┐          ┌─────────────┐
+│  Customer   │─────────►│   System    │─────────►│  Payment    │
+│  (Person)   │  uses    │             │  calls   │  Gateway    │
+└─────────────┘          └─────────────┘          │  (External) │
+                                │                  └─────────────┘
+                                │ sends
+                                ▼
+                         ┌─────────────┐
+                         │   Email     │
+                         │  (External) │
+                         └─────────────┘
+\`\`\`
+
+Legend:
+- Box = System/Person
+- Arrow = Relationship
+- (External) = Outside our control
+```
+
 ### Sequence Diagram
 
 ```markdown
@@ -271,3 +405,243 @@ stateDiagram-v2
 3. **Include legend** - Explain symbols/colors
 4. **Version with docs** - Update diagrams when architecture changes
 5. **Cross-reference** - Link diagrams to relevant docs
+
+---
+
+## Complete Examples
+
+### Example 1: E-commerce System (C4 Context → Container)
+
+**Context Diagram:**
+
+```mermaid
+C4Context
+    title E-commerce System Context
+    
+    Person(customer, "Customer", "Browses and buys products")
+    Person(admin, "Admin", "Manages catalog and orders")
+    
+    System(ecommerce, "E-commerce Platform", "Allows customers to browse and purchase products")
+    
+    System_Ext(payment, "Payment Provider", "Stripe/PayPal")
+    System_Ext(shipping, "Shipping Service", "Calculates rates, tracks packages")
+    System_Ext(email, "Email Service", "SendGrid")
+    
+    Rel(customer, ecommerce, "Browses, purchases")
+    Rel(admin, ecommerce, "Manages")
+    Rel(ecommerce, payment, "Processes payments")
+    Rel(ecommerce, shipping, "Gets rates, creates labels")
+    Rel(ecommerce, email, "Sends notifications")
+```
+
+**Container Diagram:**
+
+```mermaid
+C4Container
+    title E-commerce Containers
+    
+    Person(customer, "Customer")
+    
+    Container_Boundary(system, "E-commerce Platform") {
+        Container(web, "Web App", "React", "Product browsing, checkout")
+        Container(api, "API", "Node.js", "REST API")
+        Container(catalog, "Catalog Service", "Go", "Products, categories")
+        Container(orders, "Orders Service", "Go", "Order processing")
+        Container(search, "Search", "Elasticsearch", "Product search")
+        ContainerDb(db, "Database", "PostgreSQL", "Products, orders, users")
+        ContainerQueue(queue, "Events", "Kafka", "Order events")
+        Container(cache, "Cache", "Redis", "Sessions, product cache")
+    }
+    
+    Rel(customer, web, "HTTPS")
+    Rel(web, api, "REST")
+    Rel(api, catalog, "gRPC")
+    Rel(api, orders, "gRPC")
+    Rel(api, cache, "Gets/sets")
+    Rel(catalog, db, "SQL")
+    Rel(catalog, search, "Syncs")
+    Rel(orders, db, "SQL")
+    Rel(orders, queue, "Publishes")
+```
+
+### Example 2: Order Processing (Sequence)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    
+    participant C as Customer
+    participant API as API Gateway
+    participant O as Order Service
+    participant I as Inventory
+    participant P as Payment
+    participant N as Notifications
+    participant DB as Database
+    
+    C->>API: POST /orders
+    API->>O: CreateOrder(items)
+    
+    O->>I: ReserveItems(items)
+    alt Items available
+        I-->>O: Reserved
+        O->>DB: SaveOrder(pending)
+        
+        O->>P: ChargePayment(amount)
+        alt Payment success
+            P-->>O: PaymentConfirmed
+            O->>DB: UpdateOrder(confirmed)
+            O->>I: CommitReservation
+            O->>N: SendConfirmation
+            O-->>API: OrderConfirmed
+            API-->>C: 201 Created
+        else Payment failed
+            P-->>O: PaymentFailed
+            O->>I: ReleaseReservation
+            O->>DB: UpdateOrder(failed)
+            O-->>API: PaymentError
+            API-->>C: 402 Payment Required
+        end
+    else Items unavailable
+        I-->>O: OutOfStock
+        O-->>API: StockError
+        API-->>C: 409 Conflict
+    end
+```
+
+### Example 3: Task Entity (State Diagram)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: create()
+    
+    Draft --> Open: publish()
+    Draft --> [*]: delete()
+    
+    Open --> InProgress: start()
+    Open --> Blocked: block()
+    Open --> Cancelled: cancel()
+    
+    InProgress --> Open: pause()
+    InProgress --> Blocked: block()
+    InProgress --> Review: submitForReview()
+    
+    Blocked --> Open: unblock()
+    Blocked --> Cancelled: cancel()
+    
+    Review --> InProgress: requestChanges()
+    Review --> Done: approve()
+    
+    Done --> [*]
+    Cancelled --> [*]
+    
+    note right of Blocked: Waiting for external input
+    note right of Review: Requires approval
+```
+
+**State Transition Table:**
+
+| From | To | Trigger | Conditions |
+|------|-----|---------|------------|
+| Draft | Open | publish() | Has title, assignee |
+| Open | InProgress | start() | Assignee available |
+| InProgress | Review | submitForReview() | All subtasks done |
+| Review | Done | approve() | Reviewer approved |
+| Review | InProgress | requestChanges() | Changes requested |
+| Any | Blocked | block() | External dependency |
+| Blocked | Previous | unblock() | Dependency resolved |
+
+### Example 4: User Domain (ER Diagram)
+
+```mermaid
+erDiagram
+    TENANT ||--o{ USER : has
+    USER ||--o{ USER_ROLE : has
+    ROLE ||--o{ USER_ROLE : assigned_to
+    ROLE ||--o{ ROLE_PERMISSION : has
+    PERMISSION ||--o{ ROLE_PERMISSION : granted_to
+    USER ||--o{ SESSION : has
+    USER ||--o{ AUDIT_LOG : generates
+    
+    TENANT {
+        uuid id PK
+        string name
+        string slug UK
+        string plan
+        timestamp created_at
+    }
+    
+    USER {
+        uuid id PK
+        uuid tenant_id FK
+        string email UK
+        string password_hash
+        string name
+        boolean is_active
+        timestamp last_login_at
+        timestamp created_at
+    }
+    
+    ROLE {
+        uuid id PK
+        uuid tenant_id FK
+        string name
+        string description
+        boolean is_system
+    }
+    
+    USER_ROLE {
+        uuid user_id FK
+        uuid role_id FK
+    }
+    
+    PERMISSION {
+        uuid id PK
+        string code UK
+        string description
+    }
+    
+    ROLE_PERMISSION {
+        uuid role_id FK
+        uuid permission_id FK
+    }
+    
+    SESSION {
+        uuid id PK
+        uuid user_id FK
+        string token_hash
+        string ip_address
+        timestamp expires_at
+        timestamp created_at
+    }
+    
+    AUDIT_LOG {
+        uuid id PK
+        uuid user_id FK
+        string action
+        string resource_type
+        uuid resource_id
+        jsonb changes
+        timestamp created_at
+    }
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Too much detail in Context | Overwhelming, loses purpose | Only external systems and actors |
+| Mixing abstraction levels | Confusing, inconsistent | Stick to one C4 level per diagram |
+| No legend | Reader guesses meaning | Always include legend for colors/shapes |
+| Outdated diagrams | Misleading | Update with code changes, review in PRs |
+| Sequence too long | Unreadable | Split into multiple diagrams by scenario |
+| ER with all fields | Cluttered | Show only key fields, document rest separately |
+
+---
+
+## Related Skills
+
+- `architecture-design` - Creates diagrams during design
+- `unit-writing` - Links diagrams from unit docs
+- `adr-writing` - ADRs may include decision diagrams

package/src/opencode/skills/unit-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unit-writing
-description: How to document modules, domains, services, and entities with structured folder-based approach
+description: Use when documenting modules, domains, services, or entities - creating index.md, data-model.md, API specs, or event schemas for architectural components
 license: MIT
 compatibility: opencode
 metadata: