@comfanion/workflow 4.1.2 → 4.3.0

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

@@ -19,49 +19,80 @@ Use this skill when you need to:
 
 ## Template
 
-Use the template at: `@.opencode/templates/prd-template.md`
+Use the template at: `@.opencode/skills/prd-writing/template.md`
 
-## PRD Structure
+## PRD Structure (v2)
 
-### Required Sections
+### 1. Executive Summary
 
-1. **Executive Summary** (2-3 paragraphs)
-   - What is being built
-   - Why it's being built (business value)
-   - Unique value proposition
+Brief prose section with:
+- What the system is and does
+- Architecture pattern
+- Key domains (numbered list)
+- What makes this special (unique value)
+- Scale (MVP and Growth targets)
 
-2. **Project Classification**
-   - Technical Type
-   - Domain
-   - Complexity
-   - Architecture style
+### 2. Success Criteria
 
-3. **Success Criteria** (measurable!)
-   - MVP Success metrics
-   - Growth Success metrics
+| Section | Content |
+|---------|---------|
+| MVP Success | Measurable criteria for launch |
+| Growth Success | Measurable criteria for scale |
 
-4. **Product Scope**
-   - MVP features (P0)
-   - Growth features (P1)
-   - Vision features (P2)
+### 3. Product Scope
 
-5. **Functional Requirements**
-   - Organized by domain
-   - Each FR has: ID, Priority, Scope, Description, AC
+| Section | Content |
+|---------|---------|
+| MVP | Features by domain |
+| Growth Features | Post-MVP enhancements |
+| Out of Scope | Explicit exclusions |
 
-6. **Non-Functional Requirements**
-   - Performance (with metrics)
-   - Security
-   - Scalability
-   - Reliability
+### 4. Functional Requirements
 
-7. **Dependencies & Integrations**
-8. **Risks & Mitigations**
-9. **Constraints**
-10. **Open Questions**
+**Grouped by domain in tables:**
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-001 | {{requirement}} | P0 |
+
+With **Notes:** for business rules after each domain table.
+
+### 5. Non-Functional Requirements
+
+Tables for:
+- Performance (with metrics)
+- Security
+- Scalability
+
+### 6. Critical Business Rules
+
+Numbered list with **bold rule name** — description format.
+
+### 7. Glossary
+
+| Term | Definition |
+|------|------------|
+
+### 8. References
+
+Using `→` format:
+```
+→ Architecture: `docs/architecture.md`
+→ Requirements: `docs/requirements.md`
+```
 
 ## Writing Guidelines
 
+### Reference Format
+
+Always use `→` prefix for links:
+```
+→ Unit: `Task`
+→ FR: `FR-001`
+→ ADR: `ADR-001`
+→ `path/to/file.md`
+```
+
 ### Requirement IDs
 - Functional: `FR-001`, `FR-002`, ...
 - Non-Functional: `NFR-001`, `NFR-002`, ...
@@ -71,27 +102,31 @@ Use the template at: `@.opencode/templates/prd-template.md`
 - **P1**: Should have for growth
 - **P2**: Nice to have for vision
 
-### Scope Classification
-- **MVP**: Minimum viable product (v1.0)
-- **Growth**: Post-MVP enhancements (v1.x)
-- **Vision**: Future roadmap (v2.0+)
+### Tables over Prose
+
+Prefer structured tables over paragraphs:
+```markdown
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-001 | User can create task | P0 |
+```
 
-### Language Rules
-- Use "must", "shall", "will" for mandatory items
-- Use "should", "may" for optional items
-- Avoid ambiguous terms without metrics
+NOT:
+```markdown
+FR-001: The user shall be able to create a task. This is a P0 requirement...
+```
 
 ## Validation Checklist
 
 Before completing PRD:
 - [ ] Executive summary explains the "why"
 - [ ] All FRs from requirements.md are addressed
-- [ ] All NFRs from requirements.md are addressed
+- [ ] All NFRs have measurable metrics
 - [ ] Success criteria are measurable
 - [ ] Scope boundaries are clear
-- [ ] No conflicting requirements
-- [ ] Risks are documented with mitigations
-- [ ] Each FR has acceptance criteria
+- [ ] Critical business rules documented
+- [ ] Uses `→` reference format
+- [ ] Tables used for structured data
 
 ## Output
 
@@ -102,3 +137,4 @@ Save to: `docs/prd.md`
 - `acceptance-criteria` - For writing testable AC
 - `requirements-gathering` - For source requirements
 - `prd-validation` - For validating the PRD
+- `unit-writing` - For documenting units referenced in PRD

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

@@ -0,0 +1,147 @@
+# {{project}} — PRD
+
+```yaml
+id: PRD-001
+version: 1.0
+status: draft | approved
+date: {{date}}
+author: {{author}}
+```
+
+---
+
+## Executive Summary
+
+{{project}} is a {{type}} platform for {{target_users}}. The system handles {{core_capabilities}}.
+
+**Architecture:** {{architecture_pattern}}
+
+**Key Domains:**
+1. **{{domain_1}}** — {{description}}
+2. **{{domain_2}}** — {{description}}
+
+**What Makes This Special:**
+- {{unique_value_1}}
+- {{unique_value_2}}
+
+**Scale:**
+- **MVP:** {{mvp_scale}}
+- **Growth:** {{growth_scale}}
+
+<!-- e.g.
+TaskFlow is a B2B platform for managing distributed teams. The system handles task management, real-time collaboration, and team analytics.
+
+**Architecture:** Modular Monolith with Hexagonal Architecture
+
+**Key Domains:**
+1. **Task Management** — CRUD, assignments, status workflow
+2. **Team** — Users, roles, permissions
+
+**What Makes This Special:**
+- Real-time sync without WebSockets (smart polling)
+- Formula-based task prioritization
+
+**Scale:**
+- **MVP:** 100 teams, 10K tasks
+- **Growth:** 1000 teams, 100K tasks
+-->
+
+---
+
+## Success Criteria
+
+### MVP Success
+- {{criterion_1}}
+- {{criterion_2}}
+
+### Growth Success
+- {{criterion_1}}
+- {{criterion_2}}
+
+---
+
+## Product Scope
+
+### MVP — Minimum Viable Product
+
+**{{Domain_1}}:**
+- {{capability}}
+- {{capability}}
+
+**{{Domain_2}}:**
+- {{capability}}
+
+### Growth Features (Post-MVP)
+- {{feature}}
+
+### Out of Scope
+- {{item}}
+
+---
+
+## Functional Requirements
+
+### {{Domain_1}}
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-001 | {{requirement}} | P0 |
+| FR-002 | {{requirement}} | P0 |
+| FR-003 | {{requirement}} | P1 |
+
+<!-- e.g.
+| FR-001 | User can create task with title, description, due date | P0 |
+| FR-002 | User can assign task to team member | P0 |
+| FR-003 | System sends notification on assignment | P1 |
+-->
+
+**Notes:**
+- {{important_business_rule}}
+
+### {{Domain_2}}
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-010 | {{requirement}} | P0 |
+
+---
+
+## Non-Functional Requirements
+
+### Performance
+| Metric | Target |
+|--------|--------|
+| {{metric}} | {{value}} |
+
+### Security
+- {{requirement}}
+
+### Scalability
+- {{requirement}}
+
+---
+
+## Critical Business Rules
+
+1. **{{rule_name}}** — {{description}}
+2. **{{rule_name}}** — {{description}}
+
+<!-- e.g.
+1. **One User = One Task Owner** — Task can have only one assignee at a time
+2. **Status Flow** — Tasks follow: todo → in_progress → done (no skip)
+-->
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| {{term}} | {{definition}} |
+
+---
+
+## References
+
+→ Architecture: `{{path}}`
+→ Requirements: `{{path}}`

package/src/opencode/skills/requirements-gathering/SKILL.md

@@ -13,114 +13,163 @@ metadata:
 ## When to Use
 
 Use this skill when you need to:
-- Conduct stakeholder interviews
-- Extract functional requirements (FR)
-- Extract non-functional requirements (NFR)
-- Discover hidden requirements through questions
+- Gather requirements from stakeholders
+- Document functional and non-functional requirements
+- Create the foundation for PRD
 
-## Interview Technique
+## Template
 
-### Phase 1: Context Discovery
+Use template at: `@.opencode/skills/requirements-gathering/template.md`
 
-Ask these questions first:
-1. What problem are we solving?
-2. Who are the users/stakeholders?
-3. What existing systems does this integrate with?
-4. What's the timeline and budget?
-5. What happens if we don't build this?
+## Requirements Document Structure (v2)
 
-### Phase 2: Functional Discovery
+### 1. Header
 
-For each user type:
-1. What actions should they be able to perform?
-2. What are the main workflows?
-3. What data do they need to see/edit?
-4. What are the edge cases?
-5. What errors might occur?
+```yaml
+id: REQ-001
+version: 1.0
+status: draft | approved
+date: {{date}}
+author: {{author}}
+```
 
-### Phase 3: Quality Attributes (NFR)
+### 2. Summary
 
-Ask about:
-- **Performance**: Expected response times? Concurrent users?
-- **Security**: Authentication? Data sensitivity? Compliance?
-- **Scalability**: Data volume growth? User growth?
-- **Reliability**: Uptime requirements? Recovery time?
-- **Usability**: User expertise level? Accessibility?
+Brief prose explaining:
+- What problem is being solved
+- Who the primary users are
+- Key outcomes expected
 
-### Phase 4: Constraints & Assumptions
+### 3. Stakeholders
 
-Document:
-- Technical constraints (existing systems, languages, platforms)
-- Business constraints (budget, timeline, regulations)
-- Assumptions being made
+| Role | Representative | Interest | Influence |
+|------|---------------|----------|-----------|
+| Product Owner | Name | Feature delivery | High |
+| End Users | Segment | Daily usage | High |
 
-## Output Format
+### 4. Functional Requirements
 
-### Functional Requirements
+**Grouped by domain:**
 
 ```markdown
-### FR-001: [Requirement Title]
+### Task Management
 
-**Priority:** P0 | P1 | P2
-**Source:** [Stakeholder / Document / Interview]
-**Category:** [Domain area]
+Core task lifecycle operations.
 
-**Description:**
-[Clear, unambiguous description of what the system must do]
+| ID | Requirement | Priority | Source |
+|----|-------------|----------|--------|
+| FR-001 | User can create task | P0 | Team Lead |
 
-**Acceptance Criteria:**
-- [ ] [Testable criterion 1]
-- [ ] [Testable criterion 2]
+**Business Rules:**
+- One task = one assignee
 
-**Dependencies:** [FR-XXX, NFR-XXX]
-**Notes:** [Additional context]
+**Notes:**
+- Notifications in separate domain
 ```
 
-### Non-Functional Requirements
+### 5. Non-Functional Requirements
 
-```markdown
-### NFR-001: [Requirement Title]
+Separate tables by category:
+- Performance (with metrics)
+- Security
+- Scalability
+
+### 6. Constraints
+
+| Type | Constraint | Impact |
+|------|------------|--------|
+| Technical | Must use existing auth | Limits options |
+| Timeline | MVP in 3 months | Scope pressure |
+
+### 7. Assumptions
+
+| # | Assumption | Risk if Wrong | Validation |
+|---|------------|---------------|------------|
+| 1 | Users have modern browsers | IE support needed | Analytics |
+
+### 8. Dependencies
+
+| Dependency | Type | Owner | Status | Risk |
+|------------|------|-------|--------|------|
+| Auth service | Technical | Platform team | Available | Low |
+
+### 9. Open Questions
+
+| # | Question | Owner | Due | Status |
+|---|----------|-------|-----|--------|
+| 1 | Max file size? | PM | Jan 30 | Open |
+
+### 10. Glossary
 
-**Priority:** P0 | P1 | P2
-**Category:** Performance | Security | Scalability | Reliability | Usability
+| Term | Definition |
+|------|------------|
+| Task | Unit of work assigned to user |
 
-**Requirement:**
-[Specific, measurable requirement]
+### 11. References
 
-**Metric:** [How to measure]
-**Target:** [Specific target value]
+```markdown
+→ PRD: `docs/prd.md`
+→ Stakeholder Interviews: `docs/interviews/`
+```
+
+## Reference Format
 
-**Verification Method:** [How to verify compliance]
+Use `→` for all references:
+```markdown
+→ PRD: `docs/prd.md`
+→ FR: `FR-001`
 ```
 
-## Requirement Quality Checklist
+## Requirement Writing Rules
+
+### Good Requirements
+
+| Rule | Good | Bad |
+|------|------|-----|
+| Atomic | User can create task | User can create and edit task |
+| Measurable | Load in < 2s | Load quickly |
+| Testable | Title max 200 chars | Title reasonable length |
+| Unambiguous | Required field | Important field |
+
+### Requirement IDs
+
+- Functional: `FR-001`, `FR-002`, ...
+- Non-Functional: `NFR-001`, `NFR-002`, ...
+
+### Priority
+
+| Level | Meaning | Scope |
+|-------|---------|-------|
+| P0 | Must have | MVP |
+| P1 | Should have | Growth |
+| P2 | Nice to have | Vision |
+
+## Interview Questions
 
-Each requirement must be:
-- [ ] **Specific** - Clear, unambiguous
-- [ ] **Measurable** - Has acceptance criteria or metrics
-- [ ] **Achievable** - Technically feasible
-- [ ] **Relevant** - Tied to business value
-- [ ] **Traceable** - Has unique ID and source
+### Functional Discovery
 
-## Common Anti-patterns to Avoid
+1. What do you need to accomplish?
+2. What information do you need to see?
+3. What actions do you need to take?
+4. What happens when X fails?
 
-1. **Vague language**: "The system should be fast" → "API response < 200ms p95"
-2. **Missing metrics**: "High availability" → "99.9% uptime"
-3. **Solution masquerading as requirement**: "Use Redis" → "Cache frequently accessed data"
-4. **Missing acceptance criteria**: Always include testable criteria
+### NFR Discovery
 
-## Discovery Questions Bank
+1. How many users concurrently?
+2. What response time is acceptable?
+3. What's the data retention policy?
+4. What security standards apply?
 
-### For Hidden Requirements
-- "What would make this a failure even if it works correctly?"
-- "Who else needs to be involved that we haven't talked to?"
-- "What reports or dashboards do you need?"
-- "How do you handle this process today?"
+## Validation Checklist
 
-### For Prioritization
-- "If you could only have 3 features, which would they be?"
-- "What's the minimum needed to go live?"
-- "What's the cost of NOT having this feature?"
+- [ ] All stakeholders identified
+- [ ] Requirements grouped by domain
+- [ ] Each requirement is atomic and testable
+- [ ] NFRs have measurable metrics
+- [ ] Constraints documented
+- [ ] Assumptions validated
+- [ ] Dependencies identified with owners
+- [ ] Uses `→` reference format
 
 ## Output
 
@@ -128,5 +177,6 @@ Save to: `docs/requirements/requirements.md`
 
 ## Related Skills
 
-- `prd-writing` - For turning requirements into PRD
-- `requirements-validation` - For validating requirements
+- `prd-writing` - Uses requirements as input
+- `requirements-validation` - Validates requirements
+- `acceptance-criteria` - For testable AC