@comfanion/workflow 4.1.2 → 4.3.0

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

@@ -13,334 +13,186 @@ metadata:
 ## When to Use
 
 Use this skill when you need to:
-- Create epics from PRD requirements
-- Structure implementation work into manageable chunks
-- Define epic-level acceptance criteria
-- Track PRD coverage
-
-## MANDATORY: Read Before Writing Epic
-
-**⚠️ STOP! Before writing ANY epic, execute these steps:**
-
-### Step 1: Find and Read Project Standards
-
-```bash
-# Execute these Glob searches:
-Glob "**/AGENTS.md" OR "**/CLAUDE.md"       # → Read the file found
-Glob "**/docs/architecture.md"              # → Read system architecture
-Glob "**/coding-standards/**/*.md"          # → Read ALL coding standards
-```
-
-**You MUST read these files before writing epic!**
-
-### Step 2: Find and Read Module Documentation
-
-```bash
-# For the module this epic covers (e.g., "catalog"):
-Glob "**/docs/**/catalog/**/*.md"           # → Read ALL module docs
-Glob "**/catalog-data-model*.md"            # → Read data model
-Glob "**/catalog-architecture*.md"          # → Read module architecture
-```
-
-### Step 3: Find and Read PRD
-
-```bash
-Glob "**/prd.md"                            # → Read PRD for FR-XXX references
-Glob "**/requirements/*.md"                 # → Read detailed requirements if exist
-```
-
-### Step 4: Find Existing Code Patterns (for technical notes)
-
-```bash
-# Find existing code to reference in Technical Notes:
-Glob "**/src/services/[module]/modules/*/domain/**/*.go"       # → Domain patterns
-Glob "**/src/services/[module]/modules/*/application/**/*.go"  # → Use case patterns
-```
-
-### Pre-Epic Checklist
-
-Before writing epic, confirm you executed:
-- [ ] **Glob + Read** AGENTS.md/CLAUDE.md
-- [ ] **Glob + Read** docs/architecture.md
-- [ ] **Glob + Read** coding-standards/*.md (ALL files)
-- [ ] **Glob + Read** module documentation (architecture, data-model)
-- [ ] **Glob + Read** PRD for requirements
-- [ ] **Glob** existing code patterns (for Technical Notes section)
-
-**⛔ DO NOT WRITE EPIC WITHOUT COMPLETING ALL STEPS ABOVE!**
-**Epic without proper architecture references = REJECTED.**
-
----
+- Create epics from PRD
+- Define epic scope and acceptance criteria
+- Plan stories within an epic
+- Track PRD requirement coverage
 
 ## Template
 
-Use template at: `@.opencode/templates/epic-template.md`
+Use template at: `@.opencode/skills/epic-writing/template.md`
 
-## Epic Structure
+## Epic Structure (v2)
 
-### Header (YAML-like)
+### 1. Header
 
-```markdown
-# Epic N: [Title]
-
-**Epic ID:** [MODULE]-E[NN]
-**Status:** TODO | IN_PROGRESS | DONE
-**Priority:** P0 | P1 | P2
-**Sprint:** sprint-[N]
-**Branch:** feature/epic-[NN]-[short-name]
+```yaml
+id: {{PREFIX}}-E{{N}}
+status: backlog | ready | in_progress | done
+priority: P0 | P1
+sprint: {{sprint}}
 ```
 
-### Sections
-
-1. **Overview** - 2-3 sentences on goal and value
-2. **Business Value** - Why this epic matters
-3. **Dependencies** - What must come before/after
-4. **Architecture References** - Links to architecture sections
-5. **PRD Coverage** - Which FRs this epic implements
-6. **Acceptance Criteria** - MANDATORY, high-level
-7. **Stories** - Table of stories in this epic
-8. **Technical Notes** - Implementation hints
-9. **Risks & Mitigations**
-
-## Naming Conventions
+### 2. Overview
 
-### File Naming
+Prose section with:
+- What epic delivers (bold the outcome)
+- Business value
+- Scope (included)
+- Not included
 
-```
-epic-[NN]-[module]-[description].md
+```markdown
+## Overview
 
-Examples:
-- epic-01-catalog-data-layer.md
-- epic-05-catalog-products-service.md
-- epic-10-inventory-reservations.md
-```
+This epic delivers **complete task management** for team members. When complete, users will be able to create, assign, and track tasks.
 
-### Epic ID Format
+**Business Value:** Core functionality for MVP launch
 
-```
-[MODULE]-E[NN]
+**Scope:**
+- Task CRUD
+- Assignments
+- Status workflow
 
-Examples:
-- CATALOG-E01
-- CATALOG-E05
-- INVENTORY-E10
+**Not Included:**
+- Recurring tasks (Growth)
 ```
 
-### Branch Naming
+### 3. Units Affected
 
-```
-feature/epic-[NN]-[short-name]
+| Unit | Changes | Impact |
+|------|---------|--------|
+| → Unit: `Task` | Create | New entity |
+| → Unit: `User` | Modify | Add relation |
 
-Examples:
-- feature/epic-01-data-layer
-- feature/epic-05-products-service
-```
+### 4. Dependencies
 
-## Acceptance Criteria (MANDATORY)
+| Type | Item | Why |
+|------|------|-----|
+| **Requires** | Auth system | Users must exist |
+| **Enables** | Notifications epic | Triggers on assignment |
 
-Every epic MUST have acceptance criteria. Use skill: `acceptance-criteria`
+### 5. PRD Coverage
 
-### Epic-level AC Format
+| FR | Requirement | Notes |
+|----|-------------|-------|
+| → FR: `FR-001` | Create task | Core feature |
+| → FR: `FR-002` | Assign task | |
 
-```markdown
-## Acceptance Criteria
+### 6. Acceptance Criteria
 
-- [ ] All CRUD operations for [entity] implemented
-- [ ] API endpoints follow REST conventions
-- [ ] Events published for all state changes
-- [ ] Unit test coverage > 80%
-- [ ] Integration tests passing
-- [ ] Documentation updated
-- [ ] Code review passed
+Checklist format:
+- [ ] User can create task
+- [ ] User can assign task
 - [ ] All stories completed
-```
-
-### AC Quality Rules
-
-- **Testable** - Each criterion can be verified
-- **Feature-complete** - Covers the entire epic scope
-- **Not story-level** - Higher level than individual stories
-
-## PRD Coverage Matrix
-
-Track which FRs are covered:
-
-```markdown
-### PRD Coverage
+- [ ] Tests pass (>80%)
+- [ ] Documentation updated
 
-| FR ID | Requirement | Covered | Story |
-|-------|-------------|---------|-------|
-| FR-001 | Product creation | ✅ | S05-01 |
-| FR-002 | Product validation | ✅ | S05-02 |
-| FR-003 | Product search | ⏳ | S05-05 |
-```
+### 7. Stories
 
-## Epic → Story → Task Hierarchy
+Table + dependency diagram:
 
-### Decomposition Rules (MANDATORY)
+| ID | Title | Size | Focus | Status |
+|----|-------|------|-------|--------|
+| S01-01 | Task Domain | M | → Unit: `Task` | ⬜ |
+| S01-02 | Task Repository | M | → Unit: `Task` | ⬜ |
 
 ```
-EPIC (1-2 weeks)
-  └── STORY (2-5 days)
-        └── TASK (4-6 hours)
+S01 ──► S02 ──► S03
 ```
 
-| Level | Duration | Count | Deliverable |
-|-------|----------|-------|-------------|
-| **Epic** | 1-2 weeks | 1 | Complete feature |
-| **Story** | 2-5 days | 3-8 per epic | User-facing capability |
-| **Task** | 4-6 hours | 3-6 per story | Atomic code change with tests |
-
-### Story Decomposition Pattern
+### 8. Technical Decisions
 
-Break epic into stories by **architectural layer**:
+| Decision | Rationale | ADR |
+|----------|-----------|-----|
+| UUID for IDs | Distributed generation | → ADR: `ADR-001` |
 
-```markdown
-## Stories
-
-| # | Layer | Story | Est | Tasks |
-|---|-------|-------|-----|-------|
-| S01 | Domain | Aggregates & Value Objects | M | 6 |
-| S02 | Domain | Repository Interfaces | S | 3 |
-| S03 | Application | Use Cases | M | 8 |
-| S04 | Infrastructure | Repository Implementations | M | 6 |
-| S05 | Infrastructure | HTTP Handlers | S | 5 |
-| S06 | Infrastructure | Event Publishers | S | 4 |
-| S07 | Testing | Integration Tests | S | 4 |
-```
+### 9. Risks
 
-### Story Dependency Graph
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Complex validation | M | Start simple, iterate |
 
-Visualize story dependencies:
+### 10. References
 
 ```
-S01 (Domain) ──┬──► S02 (Repo Interface) ──► S04 (Repo Impl)
-               │                                    │
-               └──► S03 (Use Cases) ──► S05 (HTTP) ─┴──► S06 (Events) ──► S07 (Tests)
+→ PRD: `docs/prd.md`
+→ Architecture: `docs/architecture.md`
+→ Unit: `Task`
 ```
 
-### Story Breakdown
+## Reference Format
+
+Always use `→` prefix:
 
 ```markdown
-### Stories Summary
-
-| Story | Tasks | Size | Deps |
-|-------|-------|------|------|
-| S01 | 4 | M | - |
-| S02 | 3 | S | S01 |
-| S03 | 5 | L | S01 |
-| S04 | 4 | M | S02 |
-| S05 | 3 | S | S03 |
-| S06 | 3 | S | S04 |
-| S07 | 3 | S | S05,S06 |
-| **Total** | **25** | | |
-
-**Parallel Opportunities:** S02+S03, S04+S05
+→ Unit: `Task`
+→ FR: `FR-001`
+→ ADR: `ADR-001`
+→ PRD: `docs/prd.md`
 ```
 
-**Note:** No hour estimates. Use T-shirt sizes (XS/S/M/L/XL) for relative complexity.
-
-## Epic Sizing
+## Story Planning
 
-### Guidelines
+### Story Order
 
-- **Duration:** 1-2 weeks of work
-- **Stories:** 3-8 stories per epic
-- **Tasks:** 15-35 tasks per epic (total across stories)
-- **Scope:** One logical feature/capability
+Recommended order within epic:
+1. Domain layer (entities, value objects)
+2. Repository interfaces
+3. Use cases
+4. Repository implementations
+5. HTTP handlers
+6. Integration tests
 
-### Too Big? Split it!
+### Story Focus
 
-Signs an epic is too big:
-- More than 10 stories
-- More than 40 tasks total
-- Spans multiple sprints
-- Multiple unrelated features
-- Different team members for different parts
+Each story should focus on one unit:
 
-### Too Small? Merge it!
+| ID | Title | Focus |
+|----|-------|-------|
+| S01-01 | Task Domain | → Unit: `Task` |
+| S01-02 | Task Repository | → Unit: `Task` |
 
-Signs an epic is too small:
-- Only 1-2 stories
-- Less than 8 tasks
-- Can be done in 3-4 days
-- Part of a larger feature
-
-### Parallel Execution Opportunities
+## Naming Conventions
 
-Identify which stories can run in parallel:
+### File Names
 
-```markdown
-### Execution Phases
-
-| Phase | Stories (Parallel) | Duration |
-|-------|-------------------|----------|
-| 1 | S01 | 2.5d |
-| 2 | S02, S03 | 3d |
-| 3 | S04, S05 | 3d |
-| 4 | S06 | 2d |
-| 5 | S07 | 2d |
-| **Total** | | **5d** |
-
-**Sequential would be:** 6.5d
-**Savings from parallelism:** 1.5d (23%)
 ```
+epic-[NN]-[description].md
 
-## Dependencies
-
-### Documenting Dependencies
-
-```markdown
-### Dependencies
-
-**Requires (must complete first):**
-- CATALOG-E01: Data layer must exist before domain
-- CATALOG-E02: Domain types needed for repository
-
-**Enables (unlocks these):**
-- CATALOG-E10: Search requires products to exist
-- INVENTORY-E01: Inventory needs product IDs
+Examples:
+- epic-01-task-management.md
+- epic-02-user-auth.md
 ```
 
-### Dependency Rules
-
-1. Dependencies form a DAG (no cycles!)
-2. Sprint planning respects dependencies
-3. Blocked epics cannot start
-
-## Directory Structure
+### Epic IDs
 
 ```
-docs/sprint-artifacts/
-├── backlog/
-│   └── epic-10-search-integration.md  # Not yet scheduled
-├── sprint-0/
-│   ├── epic-01-data-layer.md         # Completed
-│   └── stories/
-├── sprint-1/
-│   ├── epic-05-products-service.md   # Current
-│   └── stories/
+[PREFIX]-E[NN]
+
+Examples:
+- TASK-E01
+- AUTH-E02
 ```
 
 ## Validation Checklist
 
-Before completing epic:
-- [ ] Epic ID is unique
-- [ ] Branch name follows convention
-- [ ] PRD coverage is documented
-- [ ] Dependencies are identified
-- [ ] Architecture references included
-- [ ] **Acceptance criteria present** (MANDATORY!)
-- [ ] Stories table is complete
-- [ ] Estimate is reasonable (1-2 weeks)
+- [ ] Overview explains what and why
+- [ ] Units affected listed with `→ Unit:` format
+- [ ] All FRs from scope are listed with `→ FR:` format
+- [ ] Acceptance criteria are measurable
+- [ ] Stories have dependency order
+- [ ] Technical decisions link to ADRs
+- [ ] Uses `→` reference format throughout
 
 ## Output
 
-Save to: `docs/sprint-artifacts/sprint-[N]/epic-[NN]-[module]-[description].md`
+Save to: `docs/sprint-artifacts/sprint-[N]/epic-[NN]-[description].md`
+
+Or backlog: `docs/sprint-artifacts/backlog/epic-[NN]-[description].md`
 
 ## Related Skills
 
-- `story-writing` - For creating stories within epic
-- `acceptance-criteria` - For writing AC
-- `sprint-planning` - For organizing epics into sprints
-- `jira-integration` - For syncing to Jira
+- `story-writing` - For creating stories
+- `prd-writing` - Source of requirements
+- `unit-writing` - For documenting affected units
+- `sprint-planning` - For organizing epics

package/src/opencode/skills/epic-writing/template.md

@@ -0,0 +1,119 @@
+# Epic {{N}}: {{title}}
+
+```yaml
+id: {{PREFIX}}-E{{N}}
+status: backlog | ready | in_progress | done
+priority: P0 | P1
+sprint: {{sprint}}
+```
+
+---
+
+## Overview
+
+This epic delivers **{{user_visible_outcome}}** for {{target_users}}. When complete, users will be able to {{what_they_can_do}}.
+
+**Business Value:** {{why_this_matters}}
+
+**Scope:**
+- {{included_1}}
+- {{included_2}}
+
+**Not Included:**
+- {{excluded}}
+
+<!-- e.g.
+This epic delivers **complete task management** for team members. When complete, users will be able to create, assign, and track tasks through their lifecycle.
+
+**Business Value:** Core functionality needed for MVP launch
+
+**Scope:**
+- Task CRUD operations
+- Assignment to team members
+- Status workflow (todo → in_progress → done)
+
+**Not Included:**
+- Recurring tasks (Growth feature)
+- Task templates
+-->
+
+---
+
+## Units Affected
+
+| Unit | Changes | Impact |
+|------|---------|--------|
+| → Unit: `{{unit}}` | Create | New entity |
+| → Unit: `{{unit}}` | Modify | Add {{what}} |
+
+---
+
+## Dependencies
+
+| Type | Item | Why |
+|------|------|-----|
+| **Requires** | {{epic/system}} | {{reason}} |
+| **Enables** | {{epic/system}} | {{reason}} |
+
+---
+
+## PRD Coverage
+
+| FR | Requirement | Notes |
+|----|-------------|-------|
+| → FR: `FR-{{N}}` | {{short_description}} | {{notes}} |
+| → FR: `FR-{{N}}` | {{short_description}} | |
+
+---
+
+## Acceptance Criteria
+
+Epic is complete when:
+- [ ] {{measurable_outcome}}
+- [ ] {{measurable_outcome}}
+- [ ] All stories completed
+- [ ] Tests pass (coverage >{{N}}%)
+- [ ] Documentation updated
+
+---
+
+## Stories
+
+| ID | Title | Size | Focus | Status |
+|----|-------|------|-------|--------|
+| S{{E}}-01 | {{title}} | S/M/L | → Unit: `{{unit}}` | ⬜ |
+| S{{E}}-02 | {{title}} | S/M/L | → Unit: `{{unit}}` | ⬜ |
+
+**Dependency Flow:**
+```
+S01 ──► S02 ──► S03
+         │
+         └──► S04
+```
+
+**Notes:**
+- {{implementation_note}}
+
+---
+
+## Technical Decisions
+
+| Decision | Rationale | ADR |
+|----------|-----------|-----|
+| {{decision}} | {{why}} | → ADR: `ADR-{{N}}` |
+
+---
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {{risk}} | H/M/L | {{approach}} |
+
+---
+
+## References
+
+→ PRD: `{{path}}`
+→ Architecture: `{{path}}`
+→ Unit: `{{unit}}`

package/src/opencode/skills/prd-validation/SKILL.md

@@ -141,7 +141,7 @@ After fixing issues:
 ### Action Required
 
 Create the QA artifact using template:
-`@.opencode/templates/prd-acceptance-criteria-template.md`
+`@.opencode/skills/acceptance-criteria/template.md`
 
 This artifact is MANDATORY before proceeding to architecture.