@comfanion/workflow 3.0.0

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

@@ -0,0 +1,273 @@
+---
+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
+---
+
+# Diagram Creator
+
+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.
+
+## Core Responsibilities
+
+1. **C4 Diagrams** - Context, Container, Component, Code levels
+2. **Sequence Diagrams** - Interaction flows
+3. **ER Diagrams** - Entity relationships
+4. **Flowcharts** - Process and decision flows
+5. **State Diagrams** - State machines
+
+## Diagram Storage
+
+All diagrams go in `docs/diagrams/` with clear naming:
+
+```
+docs/diagrams/
+├── README.md                    # Diagram index
+├── c4/
+│   ├── system-context.md        # L1: System context
+│   ├── containers.md            # L2: Containers
+│   └── [module]-components.md   # L3: Module components
+├── sequences/
+│   ├── [flow-name].md
+│   └── ...
+├── data/
+│   ├── erd-overview.md          # High-level ERD
+│   └── [module]-erd.md          # Module-specific ERD
+├── flows/
+│   ├── [process-name].md
+│   └── ...
+└── states/
+    └── [entity]-states.md
+```
+
+## Diagram Templates
+
+### C4 Context Diagram (Mermaid)
+
+```markdown
+# System Context Diagram
+
+## Overview
+[What this diagram shows]
+
+## Diagram
+
+\`\`\`mermaid
+C4Context
+    title System Context Diagram for [System Name]
+    
+    Person(user, "User", "Description")
+    System(system, "System Name", "Description")
+    System_Ext(ext1, "External System", "Description")
+    
+    Rel(user, system, "Uses")
+    Rel(system, ext1, "Integrates with")
+\`\`\`
+
+## Elements
+
+| Element | Type | Description |
+|---------|------|-------------|
+| User | Person | ... |
+
+## Relationships
+
+| From | To | Description |
+|------|-----|-------------|
+```
+
+### C4 Container Diagram
+
+```markdown
+# Container Diagram
+
+\`\`\`mermaid
+C4Container
+    title Container Diagram for [System Name]
+    
+    Person(user, "User")
+    
+    Container_Boundary(system, "System Name") {
+        Container(api, "API Gateway", "Go", "Routes requests")
+        Container(svc1, "Service 1", "Go", "Handles X")
+        ContainerDb(db, "Database", "PostgreSQL", "Stores data")
+        ContainerQueue(queue, "Message Queue", "Kafka", "Events")
+    }
+    
+    Rel(user, api, "HTTPS")
+    Rel(api, svc1, "gRPC")
+    Rel(svc1, db, "SQL")
+    Rel(svc1, queue, "Publishes")
+\`\`\`
+```
+
+### Sequence Diagram
+
+```markdown
+# [Flow Name] Sequence
+
+## Context
+[When this flow occurs]
+
+## Diagram
+
+\`\`\`mermaid
+sequenceDiagram
+    autonumber
+    participant U as User
+    participant A as API
+    participant S as Service
+    participant D as Database
+    
+    U->>A: Request
+    A->>S: Process
+    S->>D: Query
+    D-->>S: Result
+    S-->>A: Response
+    A-->>U: Result
+    
+    Note over S,D: Transaction boundary
+\`\`\`
+
+## Steps
+
+1. **Request**: User sends...
+2. **Process**: Service validates...
+
+## Error Scenarios
+
+[What happens on failure]
+```
+
+### ER Diagram
+
+```markdown
+# [Domain] Entity Relationship Diagram
+
+\`\`\`mermaid
+erDiagram
+    MERCHANT ||--o{ PRODUCT : owns
+    PRODUCT ||--|{ OFFER : has
+    PRODUCT }o--|| CATEGORY : belongs_to
+    
+    MERCHANT {
+        uuid id PK
+        string name
+        string status
+        timestamp created_at
+    }
+    
+    PRODUCT {
+        uuid id PK
+        uuid merchant_id FK
+        string sku
+        string name
+    }
+    
+    OFFER {
+        uuid id PK
+        uuid product_id FK
+        decimal price
+        int quantity
+    }
+\`\`\`
+
+## Entities
+
+### MERCHANT
+[Description and business rules]
+
+### PRODUCT
+[Description and business rules]
+```
+
+### Flowchart
+
+```markdown
+# [Process Name] Flow
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B{Condition?}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+    
+    style A fill:#f9f
+    style E fill:#9f9
+\`\`\`
+
+## Decision Points
+
+| Point | Condition | Yes Path | No Path |
+|-------|-----------|----------|---------|
+```
+
+### State Diagram
+
+```markdown
+# [Entity] State Machine
+
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Pending: submit()
+    Pending --> Approved: approve()
+    Pending --> Rejected: reject()
+    Approved --> Active: activate()
+    Active --> Suspended: suspend()
+    Suspended --> Active: resume()
+    Rejected --> [*]
+    Active --> [*]: close()
+\`\`\`
+
+## States
+
+| State | Description | Allowed Transitions |
+|-------|-------------|---------------------|
+| Draft | Initial state | submit |
+```
+
+## Diagram Index (README.md)
+
+```markdown
+# Diagrams Index
+
+## Architecture Diagrams
+
+| Diagram | Level | Description |
+|---------|-------|-------------|
+| [System Context](./c4/system-context.md) | C4-L1 | High-level system view |
+| [Containers](./c4/containers.md) | C4-L2 | Service boundaries |
+
+## Sequence Diagrams
+
+| Flow | Description |
+|------|-------------|
+| [User Registration](./sequences/user-registration.md) | ... |
+
+## Data Diagrams
+
+| Diagram | Scope |
+|---------|-------|
+| [Overview ERD](./data/erd-overview.md) | All domains |
+
+## Process Flows
+
+| Process | Description |
+|---------|-------------|
+```
+
+## Best Practices
+
+1. **One concept per diagram** - Don't overcrowd
+2. **Consistent naming** - Same names across diagrams
+3. **Include legend** - Explain symbols/colors
+4. **Version with docs** - Update diagrams when architecture changes
+5. **Cross-reference** - Link diagrams to relevant docs

package/src/opencode/skills/doc-todo/SKILL.md

@@ -0,0 +1,325 @@
+# Documentation TODO Skill
+
+> **Purpose**: Incremental document writing with TODO placeholders
+> **Used by**: All agents writing documentation
+
+## Why Use Doc TODOs?
+
+- **Think incrementally** - Don't write everything at once
+- **Mark unknowns** - Explicitly show what needs work
+- **Track progress** - See document completion status
+- **Enable collaboration** - Others can fill in TODOs
+- **Reduce pressure** - It's OK to leave placeholders
+
+---
+
+## TODO Types for Documentation
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `DRAFT` | Section is rough, needs polish | First pass at requirements |
+| `EXPAND` | Section needs more detail | Add edge cases |
+| `RESEARCH` | Needs investigation | Check competitor approach |
+| `REVIEW` | Needs stakeholder input | Validate with PM |
+| `DECISION` | Decision pending | Choose between A or B |
+| `DEPENDENCY` | Waiting on other doc | Needs architecture first |
+| `EXAMPLE` | Add concrete examples | Add code sample |
+| `DIAGRAM` | Add visual diagram | Add sequence diagram |
+| `NUMBERS` | Add metrics/data | Add performance targets |
+| `LINK` | Add references | Link to ADR |
+
+---
+
+## Format
+
+### Inline TODO (short)
+
+```markdown
+<!-- TODO(EXPAND): Add error handling scenarios -->
+```
+
+### Block TODO (with context)
+
+```markdown
+<!-- TODO(RESEARCH): Investigate payment provider options
+- Need to compare: Stripe, Adyen, LiqPay
+- Criteria: fees, UA support, API quality
+- Ask: @john for vendor contacts
+-->
+```
+
+### Section Placeholder
+
+```markdown
+## API Design
+
+<!-- TODO(DEPENDENCY): Waiting on architecture.md
+This section will define API contracts after architecture is finalized.
+Blocked by: ARCH-001
+Expected: Sprint 2
+-->
+
+[Section to be written]
+```
+
+### With Status
+
+```markdown
+## Feature X
+
+**Status:** 🚧 DRAFT
+
+<!-- TODO(DRAFT): This section needs review
+- Written quickly, needs polish
+- Missing: edge cases, error scenarios
+- Review by: @analyst
+-->
+```
+
+---
+
+## Document Status Badges
+
+Add at document top:
+
+```markdown
+# PRD: Product Catalog
+
+**Status:** 🚧 IN PROGRESS | ✅ COMPLETE | 📝 DRAFT
+**TODOs:** 5 remaining
+**Last Updated:** 2024-01-15
+**Completeness:** 70%
+
+<!-- 
+Document TODOs:
+- [ ] TODO(EXPAND): FR-003 acceptance criteria
+- [ ] TODO(REVIEW): NFR section with architect
+- [ ] TODO(NUMBERS): Add performance targets
+- [ ] TODO(DIAGRAM): Add data flow diagram
+- [ ] TODO(DECISION): Choose sync vs async approach
+-->
+```
+
+---
+
+## Progressive Document Writing
+
+### Phase 1: Skeleton
+
+```markdown
+# Architecture Document
+
+## Overview
+<!-- TODO(DRAFT): Write overview after components defined -->
+
+## Components
+<!-- TODO(EXPAND): List all components -->
+
+## Data Flow
+<!-- TODO(DIAGRAM): Add sequence diagram -->
+
+## Decisions
+<!-- TODO(DEPENDENCY): After PRD finalized -->
+```
+
+### Phase 2: First Pass
+
+```markdown
+# Architecture Document
+
+## Overview
+The system consists of 3 main services...
+<!-- TODO(REVIEW): Review with team -->
+
+## Components
+
+### Catalog Service
+Manages product catalog...
+<!-- TODO(EXPAND): Add API endpoints -->
+
+### Order Service
+<!-- TODO(DRAFT): Write after catalog complete -->
+
+## Data Flow
+<!-- TODO(DIAGRAM): Add sequence diagram -->
+
+## Decisions
+<!-- TODO(DEPENDENCY): After PRD finalized -->
+```
+
+### Phase 3: Detailed
+
+```markdown
+# Architecture Document
+
+## Overview
+The system consists of 3 main services... ✅
+
+## Components
+
+### Catalog Service
+Manages product catalog...
+
+#### API Endpoints
+- `POST /products` - Create product
+- `GET /products/{id}` - Get product
+<!-- TODO(EXAMPLE): Add request/response examples -->
+
+### Order Service
+Handles order processing...
+<!-- TODO(EXPAND): Add order states diagram -->
+
+## Data Flow
+```mermaid
+sequenceDiagram
+...
+```
+✅
+
+## Decisions
+- ADR-001: Use PostgreSQL
+<!-- TODO(LINK): Link to ADR files -->
+```
+
+---
+
+## Templates with TODOs
+
+### PRD Section
+
+```markdown
+## Functional Requirements
+
+### FR-001: User Registration
+
+**Priority:** P0
+**Status:** 🚧 DRAFT
+
+**Description:**
+Users can register with email and password.
+
+<!-- TODO(EXPAND): Add social login options -->
+
+**Acceptance Criteria:**
+- [ ] User can register with valid email
+- [ ] Password must be 8+ characters
+<!-- TODO(EXPAND): Add password complexity rules -->
+
+**Edge Cases:**
+<!-- TODO(RESEARCH): Check GDPR requirements for registration -->
+
+**Dependencies:**
+<!-- TODO(DEPENDENCY): Needs auth architecture from ARCH-002 -->
+```
+
+### Architecture Section
+
+```markdown
+## Database Design
+
+### Products Table
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR | Product name |
+<!-- TODO(EXPAND): Add all columns -->
+
+**Indexes:**
+<!-- TODO(NUMBERS): Add expected query patterns and index strategy -->
+
+**Migrations:**
+<!-- TODO(LINK): Link to migration files when created -->
+```
+
+### Story Section
+
+```markdown
+## Acceptance Criteria
+
+### AC1: Create product successfully
+
+**Given** authenticated merchant
+**When** POST /products with valid data
+**Then** 201 Created
+<!-- TODO(EXAMPLE): Add sample request/response -->
+
+### AC2: Validation errors
+<!-- TODO(DRAFT): Write after AC1 reviewed -->
+
+### AC3: Authorization
+<!-- TODO(DECISION): Check if need merchant-level permissions -->
+```
+
+---
+
+## Workflow Integration
+
+### When Writing PRD
+
+```
+1. Create skeleton with TODOs
+2. Fill critical sections first (P0 requirements)
+3. Mark DRAFT sections for review
+4. Get stakeholder input on DECISION items
+5. Expand with details
+6. Add DIAGRAM and EXAMPLE items
+7. Final REVIEW pass
+8. Mark document COMPLETE
+```
+
+### When Writing Architecture
+
+```
+1. Start with high-level overview
+2. Add TODO(DEPENDENCY) for PRD items
+3. Make DECISION items explicit
+4. Add TODO(DIAGRAM) placeholders
+5. Fill in as decisions are made
+6. Add TODO(EXAMPLE) for code samples
+7. Review and complete
+```
+
+---
+
+## Tracking TODOs
+
+### Summary Block
+
+Add at document end:
+
+```markdown
+---
+
+## Document TODOs
+
+| Type | Description | Owner | Status |
+|------|-------------|-------|--------|
+| EXPAND | FR-003 acceptance criteria | @analyst | ⬜ |
+| REVIEW | NFR section | @architect | 🔄 |
+| DECISION | Sync vs async | @pm | ⬜ |
+| DIAGRAM | Data flow | @architect | ⬜ |
+
+**Completion:** 12/17 sections (70%)
+```
+
+### Grep for TODOs
+
+```bash
+# Find all doc TODOs
+grep -r "TODO(" docs/ --include="*.md"
+
+# Count by type
+grep -o "TODO([A-Z]*)" docs/*.md | sort | uniq -c
+```
+
+---
+
+## Best Practices
+
+1. **Be specific** - "TODO(EXPAND): Add error codes" not "TODO: More details"
+2. **Add context** - Why is this TODO here?
+3. **Set owner** - Who should address this?
+4. **Link dependencies** - What blocks this?
+5. **Review regularly** - Don't let TODOs rot
+6. **Celebrate completion** - Mark ✅ when done!