@comfanion/workflow 4.1.2 → 4.3.0

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

@@ -0,0 +1,214 @@
+# Story {{E}}.{{N}}: {{title}}
+
+```yaml
+id: {{PREFIX}}-S{{E}}-{{N}}
+epic: {{PREFIX}}-E{{E}}
+status: draft | ready | in_progress | review | done
+size: S | M | L
+```
+
+---
+
+## Goal
+
+{{one_sentence_describing_what_user_or_system_can_do_after_this}}
+
+**Context:** This story is part of Epic {{E}} ({{epic_title}}). It focuses on {{specific_aspect}}.
+
+**Out of Scope:**
+- {{what_this_story_does_NOT_do}}
+
+<!-- e.g.
+Implement CRUD operations for Task entity following hexagonal architecture.
+
+**Context:** This story is part of Epic 1 (Task Management Core). It focuses on the domain layer and repository.
+
+**Out of Scope:**
+- HTTP handlers (separate story)
+- Notifications (separate epic)
+-->
+
+---
+
+## Units Affected
+
+| Unit | Action | Description |
+|------|--------|-------------|
+| → Unit: `{{unit}}` | Create | {{what_is_created}} |
+| → Unit: `{{unit}}` | Modify | {{what_changes}} |
+
+---
+
+## Required Reading
+
+**Before starting, read these documents:**
+
+| Document | Section | Why |
+|----------|---------|-----|
+| → `CLAUDE.md` | All | Project patterns, conventions |
+| → `docs/coding-standards/` | All | **MANDATORY** — code style, patterns |
+| → Unit: `{{unit}}` | Data Model | Field definitions, constraints |
+| → `docs/architecture.md` | {{module}} Module | Service structure, events |
+| → Epic: `{{epic_path}}` | Technical Decisions | ADRs for this epic |
+
+<!-- e.g.
+| → `CLAUDE.md` | All | Project patterns, naming |
+| → `docs/coding-standards/` | All | **MANDATORY** — hexagonal, error handling |
+| → Unit: `Task` | Data Model, Operations | Fields, validation rules |
+| → `docs/architecture.md` | Task Module | Internal services, events |
+| → `docs/architecture.md#error-handling` | Error Handling | Error codes format |
+-->
+
+---
+
+## Acceptance Criteria
+
+Story is complete when:
+- [ ] {{user_can_or_system_does}}
+- [ ] {{edge_case_handled}}
+- [ ] {{error_case_handled}}
+- [ ] Tests pass (unit + integration)
+- [ ] Follows coding-standards
+- [ ] No lint errors
+
+<!-- e.g.
+- [ ] User can create task with title and description
+- [ ] Empty title returns validation error (400, TASK_001)
+- [ ] Task ID is UUID format
+- [ ] Tests cover: create, validation, duplicate handling
+- [ ] Code follows hexagonal architecture from coding-standards
+-->
+
+---
+
+## Tasks
+
+| # | Task | Output | Status |
+|---|------|--------|--------|
+| T1 | {{task}} | `{{file_path}}` | ⬜ |
+| T2 | {{task}} | `{{file_path}}` | ⬜ |
+| T3 | {{task}} | `{{file_path}}` | ⬜ |
+
+---
+
+### T1: {{task_name}}
+
+**Goal:** {{what_this_achieves}}
+
+**Read First:**
+| Document | Section | What to Look For |
+|----------|---------|------------------|
+| → `docs/coding-standards/` | Naming | Struct/method naming |
+| → `docs/coding-standards/` | Validation | Validation patterns |
+| → Unit: `{{unit}}` | Data Model | All fields and types |
+| → `{{existing_code_path}}` | Example | Similar implementation |
+
+**Output Files:**
+- `{{path/to/file}}`
+- `{{path/to/file}}_test.go`
+
+**Approach:**
+1. {{step}}
+2. {{step}}
+3. Write tests: {{test_cases}}
+
+**Done when:**
+- [ ] {{specific_criterion}}
+- [ ] Follows patterns from coding-standards
+- [ ] Tests pass
+
+<!-- e.g.
+### T1: Domain Model
+
+**Goal:** Define Task entity with validation logic
+
+**Read First:**
+| Document | Section | What to Look For |
+|----------|---------|------------------|
+| → `docs/coding-standards/` | Domain Layer | Entity patterns |
+| → `docs/coding-standards/` | Validation | How to validate |
+| → `docs/coding-standards/` | Errors | Error types, codes |
+| → Unit: `Task` | Data Model | All fields |
+| → `internal/user/domain/user.go` | Example | Similar entity |
+
+**Output Files:**
+- `internal/task/domain/task.go`
+- `internal/task/domain/task_test.go`
+
+**Approach:**
+1. Create Task struct with fields from Unit doc
+2. Add NewTask() constructor with validation
+3. Add Validate() method
+4. Write tests: valid task, empty title, invalid status
+
+**Done when:**
+- [ ] Task struct matches Unit data model
+- [ ] Validation follows coding-standards patterns
+- [ ] Error codes match architecture.md#error-handling
+- [ ] Tests cover happy path + all error cases
+-->
+
+---
+
+### T2: {{task_name}}
+
+**Goal:** {{what_this_achieves}}
+
+**Depends on:** T1
+
+**Read First:**
+| Document | Section | What to Look For |
+|----------|---------|------------------|
+| → `docs/coding-standards/` | Repository | Interface patterns |
+| → `docs/coding-standards/` | Database | SQLC usage |
+| → `{{similar_repo_path}}` | Example | Query patterns |
+
+**Output Files:**
+- `{{path}}`
+
+**Approach:**
+1. {{step}}
+2. {{step}}
+
+**Done when:**
+- [ ] {{criterion}}
+- [ ] Uses SQLC per coding-standards
+
+---
+
+### T3: {{task_name}}
+
+**Goal:** {{what_this_achieves}}
+
+**Depends on:** T1, T2
+
+**Read First:**
+| Document | Section | What to Look For |
+|----------|---------|------------------|
+| → `docs/coding-standards/` | Use Cases | Handler patterns |
+| → `docs/coding-standards/` | Testing | Test structure |
+
+**Output Files:**
+- `{{path}}`
+
+**Done when:**
+- [ ] {{criterion}}
+- [ ] Integration tests pass
+
+---
+
+## Notes
+
+- {{important_implementation_detail}}
+- {{gotcha_or_warning}}
+
+---
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] All tasks completed
+- [ ] Code follows `docs/coding-standards/`
+- [ ] Tests pass
+- [ ] Code reviewed
+- [ ] No lint errors

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

@@ -0,0 +1,185 @@
+---
+name: unit-writing
+description: How to document modules, domains, entities, services, and features using the universal Unit format
+license: MIT
+compatibility: opencode
+metadata:
+  domain: documentation
+  artifacts: docs/architecture/units/*.md
+---
+
+# Unit Writing Skill
+
+## When to Use
+
+Use this skill when you need to document any logical piece of the system:
+- **Module** - Large bounded context (e.g., `catalog`, `billing`)
+- **Domain** - Medium business area (e.g., `Order`, `Payment`)
+- **Entity** - Small data object (e.g., `User`, `Task`, `Product`)
+- **Service** - Medium component (e.g., `NotificationService`)
+- **Feature** - Varies (e.g., `Search`, `Import`)
+
+## Template
+
+Use template at: `@.opencode/skills/unit-writing/template.md`
+
+## Unit Document Structure
+
+### 1. Header
+
+```yaml
+id: {{ID}}
+type: module | domain | entity | service | feature
+status: draft | approved
+```
+
+### 2. Overview
+
+Prose paragraph explaining:
+- What the unit is responsible for
+- What it owns
+- What it provides to others
+- Key characteristics
+
+### 3. Boundaries
+
+| Aspect | Details |
+|--------|---------|
+| **Owns** | Data and behavior this unit controls |
+| **Uses** | → Unit: `dependency` |
+| **Provides** | What others can use from this unit |
+
+### 4. Data Model
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| id | UUID | PK | Primary identifier |
+| name | string | required, max 200 | Display name |
+
+### 5. Relations
+
+ASCII diagram + table:
+
+```
+Task ──► User (assignee)
+Task ──< Comment (1:N)
+```
+
+| Relation | Target | Type | Description |
+|----------|--------|------|-------------|
+| assignee | → Unit: `User` | N:1 | Task assigned to user |
+
+### 6. Operations
+
+| Operation | Input | Output | Description |
+|-----------|-------|--------|-------------|
+| Create | params | Entity | Creates new instance |
+
+With **Business Rules:** list.
+
+### 7. State Machine (if applicable)
+
+```
+todo ──► in_progress ──► done
+```
+
+| State | Description | Transitions To |
+|-------|-------------|----------------|
+
+### 8. Errors
+
+| Error | Code | When |
+|-------|------|------|
+| NotFound | UNIT_001 | Entity doesn't exist |
+
+### 9. References
+
+```
+→ Architecture: `docs/architecture.md`
+→ Related: → Unit: `OtherUnit`
+```
+
+## Unit Types Guide
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `module` | Deployable bounded context | `catalog`, `auth` |
+| `domain` | Business concept grouping | `Order`, `Inventory` |
+| `entity` | Core data object | `User`, `Task` |
+| `service` | Stateless component | `EmailService` |
+| `feature` | Cross-cutting capability | `Search`, `Export` |
+
+## Naming Conventions
+
+### File Names
+
+```
+unit-{name}.md
+
+Examples:
+- unit-task.md
+- unit-catalog.md
+- unit-notification-service.md
+```
+
+### Unit IDs
+
+```
+{TYPE}-{NAME}
+
+Examples:
+- MOD-CATALOG
+- ENT-TASK
+- SVC-NOTIFICATION
+```
+
+## Reference Format
+
+Always use `→` prefix when referencing units:
+
+```markdown
+→ Unit: `Task`
+→ Unit: `catalog/Product`
+→ Unit: `NotificationService`
+```
+
+In other documents (PRD, Architecture, Stories):
+```markdown
+| Feature | Unit |
+|---------|------|
+| Task CRUD | → Unit: `Task` |
+```
+
+## When to Create Unit Doc
+
+| Situation | Create Unit Doc? |
+|-----------|-----------------|
+| New module in architecture | Yes |
+| Complex entity with business rules | Yes |
+| Entity referenced from multiple places | Yes |
+| Simple value object | No (document inline) |
+| Internal implementation detail | No |
+
+## Validation Checklist
+
+- [ ] Type is correctly specified
+- [ ] Overview explains single responsibility
+- [ ] Boundaries are clear (owns/uses/provides)
+- [ ] Data model complete with constraints
+- [ ] Relations use `→ Unit:` format
+- [ ] Operations list all public methods
+- [ ] Business rules documented
+- [ ] Errors have codes
+- [ ] References link to related docs
+
+## Output
+
+Save to: `docs/architecture/units/unit-{name}.md`
+
+Or inline in architecture doc for simple units.
+
+## Related Skills
+
+- `architecture-design` - References units
+- `story-writing` - Tasks reference units
+- `epic-writing` - Epics affect units

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

@@ -0,0 +1,136 @@
+# Unit: {{name}}
+
+```yaml
+id: {{ID}}
+type: module | domain | entity | service | feature
+status: draft | approved
+```
+
+---
+
+## Overview
+
+{{name}} is responsible for {{single_responsibility}}. It owns {{what_it_owns}} and provides {{what_it_exposes}} to other parts of the system.
+
+**Type:** {{module/domain/entity/service/feature}}
+
+**Key Characteristics:**
+- {{characteristic_1}}
+- {{characteristic_2}}
+
+<!-- e.g.
+Task is responsible for representing a unit of work in the system. It owns title, description, status, and due date, and provides CRUD operations and status transitions to other parts of the system.
+
+**Type:** entity
+
+**Key Characteristics:**
+- Immutable ID after creation
+- Status follows defined workflow
+- Always belongs to one workspace
+-->
+
+---
+
+## Boundaries
+
+| Aspect | Details |
+|--------|---------|
+| **Owns** | {{data_and_behavior}} |
+| **Uses** | → Unit: `{{dependency}}` |
+| **Provides** | {{exposed_operations}} |
+
+**Notes:**
+- {{boundary_clarification}}
+
+---
+
+## Data Model
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| id | {{type}} | PK | Primary identifier |
+| {{field}} | {{type}} | {{constraints}} | {{description}} |
+| {{field}} | {{type}} | {{constraints}} | {{description}} |
+
+<!-- e.g.
+| id | UUID | PK | Primary identifier |
+| title | string | required, max 200 | Task title |
+| status | enum | required | todo, in_progress, done |
+| assignee_id | UUID | FK → User, nullable | Assigned user |
+| due_date | datetime | nullable | Deadline |
+-->
+
+---
+
+## Relations
+
+```
+{{this}} ──► {{other}} ({{relation_type}})
+{{this}} ──< {{other}} ({{relation_type}})
+```
+
+| Relation | Target | Type | Description |
+|----------|--------|------|-------------|
+| {{name}} | → Unit: `{{target}}` | {{1:1/1:N/N:M}} | {{description}} |
+
+<!-- e.g.
+| assignee | → Unit: `User` | N:1 | Task assigned to user |
+| comments | → Unit: `Comment` | 1:N | Task has many comments |
+| tags | → Unit: `Tag` | N:M | Task can have multiple tags |
+-->
+
+---
+
+## Operations
+
+| Operation | Input | Output | Description |
+|-----------|-------|--------|-------------|
+| {{op}} | {{params}} | {{result}} | {{what_it_does}} |
+
+**Business Rules:**
+- {{rule}}
+
+<!-- e.g.
+| Create | title, description | Task | Creates new task with status=todo |
+| Assign | task_id, user_id | Task | Assigns task to user |
+| ChangeStatus | task_id, new_status | Task | Transitions status |
+
+**Business Rules:**
+- Cannot assign to deactivated user
+- Status can only move forward (todo→progress→done)
+-->
+
+---
+
+## State Machine
+
+```
+{{state_1}} ──► {{state_2}} ──► {{state_3}}
+     │              │
+     └──────────────┘ ({{condition}})
+```
+
+| State | Description | Transitions To |
+|-------|-------------|----------------|
+| {{state}} | {{meaning}} | {{next_states}} |
+
+---
+
+## Errors
+
+| Error | Code | When |
+|-------|------|------|
+| {{error}} | {{code}} | {{condition}} |
+
+<!-- e.g.
+| TaskNotFound | TASK_001 | Task with ID doesn't exist |
+| InvalidTransition | TASK_002 | Status change not allowed |
+| AssigneeInactive | TASK_003 | Cannot assign to deactivated user |
+-->
+
+---
+
+## References
+
+→ Architecture: `{{path}}`
+→ Related: → Unit: `{{related}}`

package/src/repo-structure/docs/README.md

@@ -47,11 +47,11 @@ docs/
 
 ## Templates
 
-Templates are in `.opencode/templates/`:
-- `prd-template.md`
-- `architecture-template.md`
-- `epic-template.md`
-- `story-template.md`
+Templates are co-located with skills in `.opencode/skills/`:
+- `skills/prd-writing/template.md`
+- `skills/architecture-design/template.md`
+- `skills/epic-writing/template.md`
+- `skills/story-writing/template.md`
 
 ## Writing Guidelines
 

package/src/repo-structure/docs/requirements/README.md

@@ -19,7 +19,7 @@ This folder contains requirements gathered from stakeholders.
 
 ## Template
 
-See `.opencode/templates/requirements-template.md`
+See `.opencode/skills/requirements-gathering/template.md`
 
 ## Next Steps
 

package/src/opencode/templates/CHANGELOG.md

@@ -1,82 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- 
-
-### Changed
-- 
-
-### Deprecated
-- 
-
-### Removed
-- 
-
-### Fixed
-- 
-
-### Security
-- 
-
----
-
-## [1.0.0] - YYYY-MM-DD
-
-### Added
-- Initial release
-- Feature X
-- Feature Y
-
-### Changed
-- 
-
-### Fixed
-- 
-
----
-
-## [0.1.0] - YYYY-MM-DD
-
-### Added
-- Project skeleton
-- Basic documentation
-
----
-
-<!-- 
-CHANGELOG GUIDELINES:
-
-## Entry Format
-- Start with verb: Add, Change, Fix, Remove, Deprecate
-- Be specific: "Add user registration API" not "Add feature"
-- Reference issues/PRs: "Fix login bug (#123)"
-- Group related changes
-
-## Categories
-- Added: New features
-- Changed: Changes in existing functionality
-- Deprecated: Soon-to-be removed features
-- Removed: Removed features
-- Fixed: Bug fixes
-- Security: Vulnerability fixes
-
-## Versioning (SemVer)
-- MAJOR: Breaking changes
-- MINOR: New features (backward compatible)
-- PATCH: Bug fixes (backward compatible)
-
-## Example Entries
-- Add product catalog API with CRUD operations
-- Add user authentication via JWT tokens
-- Change order status from string to enum
-- Fix race condition in inventory reservation (#234)
-- Remove deprecated v1 API endpoints
-- Security: Fix SQL injection in search query
--->