@comfanion/workflow 3.0.0

package/src/opencode/agents/workflow-orchestrator.md

@@ -0,0 +1,249 @@
+---
+description: Orchestrates the documentation workflow, suggests next steps, detects issues
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    "*": deny
+    "ls *": allow
+    "cat *": allow
+    "tree *": allow
+    "wc -l *": allow
+    "grep *": allow
+    "find *": allow
+---
+
+# Workflow Orchestrator
+
+You are a Workflow Intelligence Agent that understands the entire documentation lifecycle. You help users navigate the workflow, detect issues, and suggest next steps based on project state.
+
+## Core Responsibilities
+
+1. **State Analysis** - Understand current project state
+2. **Next Step Suggestions** - Recommend what to do next
+3. **Issue Detection** - Find inconsistencies and problems
+4. **Scale Adaptation** - Adjust workflow depth to project size
+5. **Dependency Tracking** - Track relationships between documents
+
+## Project Scale Levels
+
+Automatically detect and adapt to project scale:
+
+| Level | Type | Characteristics | Workflow Depth |
+|-------|------|-----------------|----------------|
+| **L0** | Hotfix | Single file change, bug fix | Skip to implementation |
+| **L1** | Small | < 5 requirements, 1 module | Minimal docs |
+| **L2** | Medium | 5-20 requirements, 2-3 modules | Standard workflow |
+| **L3** | Large | 20-50 requirements, 4-10 modules | Full workflow + module docs |
+| **L4** | Enterprise | 50+ requirements, compliance needs | Full workflow + governance |
+
+## Document Status Tracking
+
+Each document has a status:
+
+```yaml
+# docs/document-status.yaml
+documents:
+  requirements:
+    path: docs/requirements/requirements.md
+    status: approved  # draft | in_progress | review | approved | stale | archived
+    last_updated: 2026-01-23
+    version: 1.2
+    depends_on: []
+    depended_by: [prd, architecture]
+    
+  prd:
+    path: docs/prd.md
+    status: approved
+    last_updated: 2026-01-22
+    version: 2.0
+    depends_on: [requirements]
+    depended_by: [architecture, epics]
+    
+  architecture:
+    path: docs/architecture.md
+    status: in_progress
+    last_updated: 2026-01-23
+    version: 1.5
+    depends_on: [prd, requirements]
+    depended_by: [epics, module-docs]
+```
+
+## Issue Detection
+
+### Stale Document Detection
+```
+IF requirements.last_updated > prd.last_updated
+AND requirements.version changed
+THEN prd is STALE
+→ Suggest: "/prd edit" to update PRD
+```
+
+### Missing Dependencies
+```
+IF architecture exists
+AND prd NOT exists
+THEN MISSING DEPENDENCY
+→ Suggest: "/prd create" first
+```
+
+### Size Overflow
+```
+IF document.lines > 2000
+THEN SIZE OVERFLOW
+→ Suggest: "/module-docs [name]" to split
+```
+
+### Validation Gap
+```
+IF document.status = approved
+AND document.validated = false
+THEN VALIDATION GAP
+→ Suggest: "/validate [type]"
+```
+
+### Orphan Documents
+```
+IF module-doc exists
+AND NOT referenced in main architecture
+THEN ORPHAN
+→ Suggest: Add reference in architecture.md
+```
+
+## Help Command Logic
+
+When `/help` is called, analyze:
+
+1. **Current State**
+   - What documents exist?
+   - What is their status?
+   - What's the project scale?
+
+2. **Blockers**
+   - Missing prerequisites?
+   - Stale dependencies?
+   - Validation gaps?
+
+3. **Suggestions**
+   - Next logical step
+   - Optional improvements
+   - Quick wins
+
+## Response Format
+
+```markdown
+## Project Status
+
+**Scale Level:** L2 (Medium)
+**Current Phase:** Architecture
+**Completion:** 60%
+
+### Document Status
+
+| Document | Status | Issues |
+|----------|--------|--------|
+| Requirements | ✅ Approved | - |
+| Coding Standards | ✅ Approved | - |
+| PRD | ⚠️ Stale | Needs update (requirements changed) |
+| Architecture | 🔄 In Progress | - |
+
+### Issues Found
+
+1. **PRD is stale** - Requirements were updated after PRD approval
+   - Action: `/prd edit` to sync with new requirements
+
+### Recommended Next Steps
+
+1. **[Required]** Update PRD to match new requirements
+   ```
+   /prd edit
+   ```
+
+2. **[Required]** Complete architecture document
+   ```
+   /architecture edit
+   ```
+
+3. **[Optional]** Create module documentation for complex modules
+   ```
+   /module-docs catalog
+   ```
+
+### Quick Actions
+
+- `/validate all` - Validate all documents
+- `/workflow-status` - Detailed status view
+```
+
+## Workflow Shortcuts
+
+### Quick Mode (L0-L1)
+For small changes, skip to essentials:
+```
+/quick [description]
+→ Creates minimal docs + implementation
+```
+
+### Full Mode (L2-L4)
+Standard workflow with all steps.
+
+## Document Dependencies Graph
+
+```
+Requirements
+     │
+     ├──→ Coding Standards (parallel)
+     │
+     ▼
+    PRD ←──────────────────────┐
+     │                         │
+     ▼                         │
+Architecture ──→ Research ─────┘
+     │
+     ├──→ Module Docs (for large modules)
+     ├──→ Diagrams
+     │
+     ▼
+   Epics
+     │
+     ▼
+  Stories
+     │
+     ▼
+Sprint Plan
+     │
+     ▼
+ Jira Sync
+```
+
+## Conflict Detection
+
+Detect conflicting information:
+
+1. **Requirement Conflicts**
+   - FR-001 says X, FR-010 says NOT X
+   - Flag and ask for resolution
+
+2. **Architecture Conflicts**
+   - Module A owns Entity, Module B also claims it
+   - Flag ownership conflict
+
+3. **Research Conflicts**
+   - Research A recommends X, Research B recommends Y
+   - Flag for decision
+
+## Recovery Suggestions
+
+When things go wrong:
+
+| Problem | Recovery |
+|---------|----------|
+| Lost document | `/archive find [name]` to restore |
+| Wrong direction | `/rollback [document]` to previous version |
+| Scope creep | `/module-docs` to split large documents |
+| Stale docs | `/refresh` to update dependencies |

package/src/opencode/checklists/architecture-checklist.md

@@ -0,0 +1,166 @@
+# Architecture Validation Checklist
+
+Use this checklist to validate architecture before proceeding to epic/story creation.
+
+## Structure Completeness
+
+### Required Sections
+- [ ] Executive Summary / Overview
+- [ ] System Context (C4 Level 1)
+- [ ] Container Diagram (C4 Level 2)
+- [ ] Component Diagrams (C4 Level 3) for key modules
+- [ ] Data Model / Schema Design
+- [ ] API Contracts
+- [ ] Event Schemas (if event-driven)
+- [ ] Integration Architecture
+- [ ] Security Architecture
+- [ ] Deployment Architecture
+- [ ] ADRs for key decisions
+
+### Metadata
+- [ ] Version number present
+- [ ] Status clearly indicated
+- [ ] Links to PRD present
+
+## PRD Alignment
+
+### Functional Requirements Coverage
+- [ ] All P0 FRs have architectural support
+- [ ] All P1 FRs considered in design
+- [ ] FR → Module mapping documented
+
+### Non-Functional Requirements
+
+#### Performance
+- [ ] Response time targets achievable with design
+- [ ] Throughput targets addressed
+- [ ] Caching strategy defined
+- [ ] Database indexing considered
+
+#### Security
+- [ ] Authentication mechanism defined
+- [ ] Authorization model documented
+- [ ] Data encryption approach specified
+- [ ] Secrets management addressed
+
+#### Scalability
+- [ ] Horizontal scaling approach defined
+- [ ] Stateless design where appropriate
+- [ ] Database scaling strategy
+
+#### Reliability
+- [ ] Availability targets achievable
+- [ ] Failover/redundancy planned
+- [ ] Disaster recovery approach
+
+## Design Quality
+
+### Architecture Patterns
+- [ ] Chosen patterns documented (hexagonal, DDD, etc.)
+- [ ] Pattern choice justified
+- [ ] Consistent pattern application
+
+### Module Design
+- [ ] Clear module boundaries
+- [ ] Single responsibility per module
+- [ ] Dependencies are explicit
+- [ ] No circular dependencies
+
+### Interface Design
+- [ ] APIs follow REST/gRPC best practices
+- [ ] Versioning strategy defined
+- [ ] Error handling standardized
+- [ ] Pagination/filtering for lists
+
+### Data Design
+- [ ] Data model normalized appropriately
+- [ ] Relationships clearly defined
+- [ ] Indexes planned for common queries
+- [ ] Data migration strategy (if applicable)
+
+## Integration Check
+
+### External Systems
+- [ ] All integrations from PRD addressed
+- [ ] Integration patterns defined (sync/async)
+- [ ] Error handling for external calls
+- [ ] Retry/circuit breaker strategies
+
+### Internal Communication
+- [ ] Inter-module communication defined
+- [ ] Event contracts documented (if event-driven)
+- [ ] Consistency strategy (eventual vs strong)
+
+## Coding Standards Alignment
+
+- [ ] Architecture follows CLAUDE.md patterns
+- [ ] Hexagonal architecture enforced
+- [ ] Use case pattern applicable
+- [ ] Testing strategy fits architecture
+
+## ADR Quality
+
+### For Each ADR
+- [ ] Context clearly stated
+- [ ] Decision clearly stated
+- [ ] Alternatives considered
+- [ ] Consequences documented
+- [ ] Status indicated
+
+### Key Decisions Documented
+- [ ] Technology choices
+- [ ] Pattern choices
+- [ ] Integration approaches
+- [ ] Security decisions
+
+## Risk Assessment
+
+### Technical Risks
+- [ ] Complex integrations identified
+- [ ] Performance bottlenecks anticipated
+- [ ] Security vulnerabilities considered
+- [ ] Scaling challenges noted
+
+### Mitigation Strategies
+- [ ] Each risk has mitigation plan
+- [ ] Fallback options documented
+
+## Implementation Readiness
+
+### Developer Clarity
+- [ ] Module boundaries clear enough for parallel development
+- [ ] Interfaces defined enough to code against
+- [ ] Dependencies documented for implementation order
+
+### Testing Strategy
+- [ ] Unit test approach fits architecture
+- [ ] Integration test points identified
+- [ ] E2E test scenarios align with user journeys
+
+## Validation Summary
+
+| Category | Score | Status | Notes |
+|----------|-------|--------|-------|
+| Structure Completeness | /10 | | |
+| PRD Alignment | /10 | | |
+| Design Quality | /10 | | |
+| Integration | /10 | | |
+| ADR Quality | /10 | | |
+| Implementation Readiness | /10 | | |
+
+**Overall Score:** /60
+**Status:** APPROVED / NEEDS REVISION / BLOCKED
+
+### Severity Levels
+- **60-54:** Excellent - Ready for implementation planning
+- **53-42:** Good - Minor improvements recommended
+- **41-30:** Acceptable - Some revisions needed
+- **<30:** Needs Work - Significant revision required
+
+**Action Items:**
+1. [High priority item]
+2. [Medium priority item]
+3. [Low priority item]
+
+**Validated By:** {{user_name}}
+**Date:** {{date}}

package/src/opencode/checklists/code-review-checklist.md

@@ -0,0 +1,151 @@
+# Code Review Checklist
+
+Use this checklist when reviewing implemented code before marking story as "done".
+
+## Acceptance Criteria Verification
+
+### Each AC from Story
+- [ ] AC1: Implementation satisfies criterion
+- [ ] AC2: Implementation satisfies criterion
+- [ ] AC3: Implementation satisfies criterion
+- [ ] [Add more as needed]
+
+### Edge Cases
+- [ ] Error scenarios handled
+- [ ] Boundary conditions tested
+- [ ] Invalid input rejected appropriately
+
+## Code Quality
+
+### Architecture Compliance
+- [ ] Follows hexagonal architecture
+- [ ] Domain layer has no infrastructure imports
+- [ ] Use cases have 4 files (inport, dto, handler, mappers)
+- [ ] Explicit mapping (no reflection libraries)
+- [ ] Dependencies flow correctly (infra → app → domain)
+
+### Code Structure
+- [ ] Single responsibility principle followed
+- [ ] Functions are focused and small (<50 lines)
+- [ ] No code duplication
+- [ ] Clear naming conventions
+- [ ] Appropriate abstractions used
+
+### Error Handling
+- [ ] Errors are wrapped with context
+- [ ] Domain errors vs infrastructure errors distinguished
+- [ ] Error messages are descriptive
+- [ ] No swallowed/ignored errors
+- [ ] Errors propagated appropriately
+
+### Comments & Documentation
+- [ ] Complex logic is documented
+- [ ] Public APIs have doc comments
+- [ ] No commented-out code
+- [ ] Self-documenting code where possible
+
+## Testing
+
+### Test Coverage
+- [ ] Unit tests for all new functions
+- [ ] Integration tests for component interactions
+- [ ] Edge cases tested
+- [ ] Error scenarios tested
+- [ ] Coverage meets requirements (80%+ for domain)
+
+### Test Quality
+- [ ] Tests are independent
+- [ ] Clear test names (TestX_Y_Z pattern)
+- [ ] Arrange-Act-Assert structure
+- [ ] No test interdependencies
+- [ ] Mocks used appropriately
+
+### Test Execution
+- [ ] All tests pass locally
+- [ ] No flaky tests introduced
+- [ ] Reasonable execution time
+
+## Security
+
+### Input Validation
+- [ ] All user input validated
+- [ ] SQL injection prevented
+- [ ] XSS prevented (if applicable)
+
+### Authentication/Authorization
+- [ ] Auth checks present where needed
+- [ ] No unauthorized access possible
+- [ ] Sensitive operations protected
+
+### Data Protection
+- [ ] No hardcoded secrets
+- [ ] Sensitive data not logged
+- [ ] PII handled correctly
+
+## Performance
+
+### Efficiency
+- [ ] No N+1 query issues
+- [ ] Appropriate caching used
+- [ ] No obvious bottlenecks
+- [ ] Database queries optimized
+
+### Resource Usage
+- [ ] No memory leaks
+- [ ] Connections properly closed
+- [ ] Resources cleaned up
+
+## CLAUDE.md Compliance
+
+- [ ] Import order correct (stdlib, external, internal)
+- [ ] Naming conventions followed
+- [ ] Context passed as first parameter
+- [ ] Value objects used for domain concepts
+- [ ] Error patterns followed
+
+## Story File Updates
+
+- [ ] All tasks marked complete [x]
+- [ ] File List updated with all changes
+- [ ] Change Log updated
+- [ ] Dev Agent Record has notes
+- [ ] Status set to "review"
+
+## Review Decision
+
+### Severity Classification
+
+| Issue | Severity | Description |
+|-------|----------|-------------|
+| | High | Security, correctness, data loss - must fix |
+| | Medium | Code quality, maintainability - should fix |
+| | Low | Style, minor improvements - nice to fix |
+
+### Issues Found
+
+| # | Severity | File:Line | Issue | Suggestion |
+|---|----------|-----------|-------|------------|
+| 1 | | | | |
+| 2 | | | | |
+| 3 | | | | |
+
+## Review Outcome
+
+- [ ] **APPROVE** - Ready to merge, all criteria met
+- [ ] **CHANGES REQUESTED** - Issues need addressing (see above)
+- [ ] **BLOCKED** - Major issues prevent approval
+
+### Summary
+
+**Strengths:**
+- [What was done well]
+
+**Areas for Improvement:**
+- [What needs work]
+
+**Action Items:**
+1. [If changes requested]
+2. [If changes requested]
+
+**Reviewed By:** {{user_name}}
+**Date:** {{date}}

package/src/opencode/checklists/prd-checklist.md

@@ -0,0 +1,140 @@
+# PRD Validation Checklist
+
+Use this checklist to validate PRD before proceeding to architecture design.
+
+## Structure Completeness
+
+### Required Sections
+- [ ] Executive Summary present
+- [ ] Project Classification defined
+- [ ] Success Criteria with measurable targets
+- [ ] User Personas defined
+- [ ] User Journeys documented
+- [ ] Product Scope (MVP/Growth/Vision)
+- [ ] Functional Requirements (all FRs)
+- [ ] Non-Functional Requirements (all NFRs)
+- [ ] Dependencies & Integrations
+- [ ] Risks & Mitigations
+- [ ] Constraints documented
+- [ ] Glossary included
+- [ ] Traceability Matrix present
+
+### Metadata
+- [ ] Version number present
+- [ ] Status clearly indicated
+- [ ] Author identified
+- [ ] Date recorded
+
+## Functional Requirements Quality
+
+### SMART Validation (Score each FR 1-5)
+
+| FR # | Specific | Measurable | Attainable | Relevant | Traceable | Avg | Flag |
+|------|----------|------------|------------|----------|-----------|-----|------|
+| FR-001 | | | | | | | |
+| FR-002 | | | | | | | |
+| ... | | | | | | | |
+
+**Legend:** 1=Poor, 3=Acceptable, 5=Excellent
+**Flag:** X = Any score < 3
+
+### Acceptance Criteria
+- [ ] Every FR has acceptance criteria
+- [ ] AC uses Given/When/Then format
+- [ ] AC is testable
+- [ ] Edge cases covered
+
+### Coverage
+- [ ] All user journeys have supporting FRs
+- [ ] All personas have relevant FRs
+- [ ] MVP scope is clearly marked
+
+## Non-Functional Requirements Quality
+
+### Performance
+- [ ] Response time targets specified
+- [ ] Throughput targets specified
+- [ ] Measurement method defined
+
+### Security
+- [ ] Authentication requirements defined
+- [ ] Authorization requirements defined
+- [ ] Data protection requirements defined
+- [ ] Compliance requirements listed
+
+### Scalability
+- [ ] Scale targets specified
+- [ ] Growth projections documented
+
+### Reliability
+- [ ] Availability target (SLA) defined
+- [ ] Recovery objectives (RTO/RPO) specified
+
+## Traceability Check
+
+### Source Tracing
+- [ ] Each FR traces to source document
+- [ ] Each FR traces to user journey
+- [ ] Each FR maps to persona
+
+### Forward Tracing
+- [ ] Epic assignments planned
+- [ ] Story breakdown feasible
+
+## Consistency Check
+
+### Terminology
+- [ ] Terms used consistently
+- [ ] All terms in glossary defined
+- [ ] No conflicting definitions
+
+### Priority Alignment
+- [ ] P0 requirements are truly critical
+- [ ] MVP scope is minimal but viable
+- [ ] Dependencies respect priority order
+
+### No Implementation Leakage
+- [ ] No specific technology mandates (unless constraint)
+- [ ] Focus is on WHAT, not HOW
+- [ ] No premature architecture decisions
+
+## Risk Assessment
+
+### Risks Identified
+- [ ] Technical risks documented
+- [ ] Business risks documented
+- [ ] Timeline risks documented
+- [ ] Each risk has mitigation strategy
+
+### Dependencies
+- [ ] External dependencies listed
+- [ ] Internal dependencies identified
+- [ ] Fallback plans for critical dependencies
+
+## Validation Summary
+
+| Category | Score | Status | Notes |
+|----------|-------|--------|-------|
+| Structure Completeness | /10 | | |
+| FR Quality (SMART) | /10 | | |
+| NFR Quality | /10 | | |
+| Traceability | /10 | | |
+| Consistency | /10 | | |
+| Risk Coverage | /10 | | |
+
+**Overall Score:** /60
+**Status:** APPROVED / NEEDS REVISION / BLOCKED
+
+### Severity Levels
+- **60-54:** Excellent - Ready for architecture
+- **53-42:** Good - Minor improvements recommended
+- **41-30:** Acceptable - Some revisions needed
+- **<30:** Needs Work - Significant revision required
+
+**Action Items:**
+1. [High priority item]
+2. [Medium priority item]
+3. [Low priority item]
+
+**Validated By:** {{user_name}}
+**Date:** {{date}}