@comfanion/workflow 4.0.0 → 4.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Initialize OpenCode Workflow system for AI-assisted development",
   "type": "module",
   "bin": {

package/src/build-info.json

@@ -1,6 +1,6 @@
 {
   "version": "3.0.0",
-  "buildDate": "2026-01-23T17:21:08.417Z",
+  "buildDate": "2026-01-23T17:46:51.919Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/config.yaml

@@ -6,7 +6,7 @@
 # PROJECT CONFIGURATION
 # =============================================================================
 project_name: "ai-wf"
-version: "4.0.0"
+version: "4.1.1"
 
 # =============================================================================
 # USER CONFIGURATION

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

@@ -18,44 +18,57 @@ Use this skill when you need to:
 - Define epic-level acceptance criteria
 - Track PRD coverage
 
-## MANDATORY: Load Technical Context First
+## MANDATORY: Read Before Writing Epic
 
-**Before writing ANY epic, you MUST read and understand:**
+**⚠️ STOP! Before writing ANY epic, execute these steps:**
 
-### 1. Project Architecture (REQUIRED)
-```
-Search and read in order:
-1. CLAUDE.md (root) - Project patterns, conventions, tech stack
-2. docs/architecture.md - System architecture, module boundaries
-3. docs/architecture/[module]/ - Module-specific documentation
-```
+### Step 1: Find and Read Project Standards
 
-### 2. Module/Domain Documentation (REQUIRED)
+```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
 ```
-For the specific module this epic covers:
-1. docs/architecture/[module]/index.md - Module overview
-2. docs/architecture/[module]/architecture.md - Module architecture
-3. docs/architecture/[module]/data-model.md - Database schema
-4. docs/architecture/[module]/api/ - API contracts
-5. docs/architecture/[module]/events/ - Event schemas
+
+**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
 ```
 
-### 3. PRD Requirements (REQUIRED)
+### Step 3: Find and Read PRD
+
+```bash
+Glob "**/prd.md"                            # → Read PRD for FR-XXX references
+Glob "**/requirements/*.md"                 # → Read detailed requirements if exist
 ```
-1. docs/prd.md - Functional requirements (FR-XXX)
-2. docs/requirements/ - Detailed requirements if exists
+
+### 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 have read:
-- [ ] CLAUDE.md - coding patterns and conventions
-- [ ] Architecture document - system design
-- [ ] Module documentation - specific module architecture
-- [ ] PRD - requirements this epic implements
+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 proceed without reading technical documentation!**
-**Epic MUST reference architecture sections and follow established patterns.**
+**⛔ DO NOT WRITE EPIC WITHOUT COMPLETING ALL STEPS ABOVE!**
+**Epic without proper architecture references = REJECTED.**
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: story-writing
-description: How to write user stories with proper format, acceptance criteria in Given/When/Then, and technical tasks
+description: How to write stories as execution plans with self-contained tasks
 license: MIT
 compatibility: opencode
 metadata:
@@ -18,42 +18,57 @@ Use this skill when you need to:
 - Define technical implementation tasks
 - Specify test scenarios
 
-## MANDATORY: Load Technical Standards First
+## MANDATORY: Read Before Writing Tasks
 
-**Before writing ANY story with tasks, you MUST read and understand:**
+**⚠️ STOP! Before writing ANY task, execute these steps:**
 
-### 1. Coding Standards (REQUIRED)
-```
-Search and read in order:
-1. CLAUDE.md (root) - Project patterns, code style, conventions
-2. docs/coding-standards/ - Detailed coding standards
-3. docs/coding-standards/testing-standards.md - Test patterns
-```
+### Step 1: Find and Read Coding Standards
 
-### 2. Module Architecture (REQUIRED)
+```bash
+# Execute these Glob searches:
+Glob "**/AGENTS.md" OR "**/CLAUDE.md"      # → Read the file found
+Glob "**/coding-standards/**/*.md"          # → Read ALL files found
+Glob "**/testing-standards*.md"             # → Read if exists
 ```
-For the specific module this story covers:
-1. docs/architecture/[module]/architecture.md - Module design
-2. docs/architecture/[module]/data-model.md - Database schema
-3. Existing code in src/services/[module]/ - Current patterns
+
+**You MUST read these files before writing tasks!**
+
+### Step 2: Find and Read Module Architecture
+
+```bash
+# For the module this story covers (e.g., "catalog"):
+Glob "**/docs/**/catalog/**/*.md"           # → Read architecture docs
+Glob "**/catalog-data-model*.md"            # → Read data model
 ```
 
-### 3. Parent Epic (REQUIRED)
+### Step 3: Find and Read Existing Code Patterns
+
+```bash
+# Find existing code to use as patterns:
+Glob "**/src/services/[module]/modules/*/domain/entity/*.go"      # → Example entities
+Glob "**/src/services/[module]/modules/*/domain/valueobject/*.go" # → Example VOs
+Glob "**/src/services/[module]/modules/*/application/usecase/*"   # → Example use cases
 ```
-1. The epic this story belongs to - for context and dependencies
-2. Other stories in the epic - for coordination
+
+**Pick 1-2 existing files as patterns for Documentation links in tasks.**
+
+### Step 4: Read Parent Epic
+
+```bash
+Glob "**/epic-[NN]*.md"                     # → Find and read the epic
 ```
 
 ### Pre-Story Checklist
 
-Before writing story tasks, confirm you have read:
-- [ ] CLAUDE.md - coding patterns and file structure
-- [ ] Coding standards - naming, error handling, testing
-- [ ] Module architecture - component boundaries
-- [ ] Parent epic - scope and dependencies
+Before writing tasks, confirm you executed:
+- [ ] **Glob + Read** AGENTS.md/CLAUDE.md 
+- [ ] **Glob + Read** coding-standards/*.md (ALL files)
+- [ ] **Glob + Read** module architecture and data-model
+- [ ] **Glob + Read** existing code patterns (at least 2 files)
+- [ ] **Read** parent epic
 
-**⚠️ DO NOT write technical tasks without reading coding standards!**
-**Tasks MUST follow project conventions and patterns from CLAUDE.md.**
+**⛔ DO NOT WRITE TASKS WITHOUT COMPLETING ALL STEPS ABOVE!**
+**Tasks without proper Documentation links = REJECTED.**
 
 ### Task File Paths
 
@@ -85,7 +100,9 @@ Use template at: `@.opencode/templates/story-template.md`
 
 ## Story Structure
 
-### Header
+**Philosophy:** Story = execution plan. Tasks are the main content, not ceremony.
+
+### Header (Minimal)
 
 ```markdown
 # Story N.M: [Title]
@@ -93,31 +110,44 @@ Use template at: `@.opencode/templates/story-template.md`
 **Story ID:** [MODULE]-S[EPIC]-[NN]
 **Epic:** [MODULE]-E[EPIC] - [Epic Title]
 **Status:** draft | ready-for-dev | in-progress | review | done
-**Priority:** P0 | P1 | P2
 **Size:** XS | S | M | L | XL
 ```
 
-**Note:** Size is relative complexity (T-shirt sizing). NO hour estimates for tasks.
+### Goal (1-2 sentences)
+
+```markdown
+## Goal
+
+Implement CRUD use cases for merchant products with validation and event publishing.
+```
+
+**NOT** the verbose "As a... I want... So that..." format. Just state what the story achieves.
 
-### User Story Format (MANDATORY)
+### Acceptance Criteria (Brief List)
 
 ```markdown
-## User Story
+## Acceptance Criteria
 
-**As a** [user type],
-**I want** [capability/action],
-**So that** [benefit/value].
+- [ ] Products can be created with EAN validation
+- [ ] Products can be retrieved by ID
+- [ ] Products can be updated with optimistic locking
+- [ ] Products can be listed with filters and pagination
+- [ ] All operations publish domain events
 ```
 
-### Sections
+**NOT** detailed Given/When/Then for each. Just a checklist of what "done" looks like.
+
+### Tasks (MAIN CONTENT - 80% of file)
+
+Self-contained tasks with documentation links. See Task Structure below.
+
+### Sections (Simplified)
 
-1. **User Story** - As a... I want... So that...
-2. **Acceptance Criteria** - Given/When/Then (MANDATORY)
-3. **Technical Tasks** - Implementation checklist
-4. **Definition of Done** - Quality gates
-5. **Technical Context** - Related files, patterns
-6. **Test Scenarios** - Unit and integration tests
-7. **Notes** - Additional context
+1. **Header** - Minimal metadata
+2. **Goal** - 1-2 sentences
+3. **Acceptance Criteria** - Brief checklist
+4. **Tasks** - MAIN CONTENT (80% of file)
+5. **Notes** - Optional additional context
 
 ## Naming Conventions
 
@@ -143,52 +173,6 @@ Examples:
 - INVENTORY-S10-01
 ```
 
-## Acceptance Criteria (MANDATORY)
-
-Use skill: `acceptance-criteria`
-
-### Format: Given/When/Then
-
-```markdown
-## Acceptance Criteria
-
-### AC1: Create product with valid data
-
-**Given** authenticated merchant with "product:create" permission
-**When** POST /api/v1/products with:
-  - name: "Test Product"
-  - price: 100.00
-  - currency: "UAH"
-**Then** 201 Created returned
-**And** response contains product with generated UUID
-**And** product status is "pending"
-**And** "product.created" event published to Kafka
-
-### AC2: Reject invalid product data
-
-**Given** authenticated merchant
-**When** POST /api/v1/products with missing required field "name"
-**Then** 400 Bad Request returned
-**And** error response contains:
-  - field: "name"
-  - message: "name is required"
-**And** no product is created in database
-
-### AC3: Unauthorized access rejected
-
-**Given** user without "product:create" permission
-**When** POST /api/v1/products
-**Then** 403 Forbidden returned
-```
-
-### AC Coverage
-
-Each story should have:
-- **Happy path** - At least 1 success scenario
-- **Validation errors** - Invalid input handling
-- **Authorization** - Permission checks
-- **Edge cases** - Boundary conditions
-
 ## Self-Contained Tasks (NO ESTIMATES)
 
 ### Task Philosophy
@@ -550,13 +534,11 @@ Add to each story:
 
 Before completing story:
 - [ ] Story ID is unique
-- [ ] User story follows format
-- [ ] **Acceptance criteria in Given/When/Then** (MANDATORY!)
-- [ ] At least 3 AC (happy path, error, edge case)
-- [ ] Technical tasks are specific
-- [ ] **TODO placeholders defined for future work**
+- [ ] Goal is clear (1-2 sentences)
+- [ ] Acceptance criteria as checklist (what "done" looks like)
+- [ ] Tasks are self-contained with documentation links
+- [ ] Each task has: Goal, Documentation, Input, Output, Steps, AC
 - [ ] Definition of Done is complete
-- [ ] Estimate is reasonable
 - [ ] Links to epic are correct
 
 ## Output

package/src/opencode/templates/story-template.md

@@ -8,55 +8,39 @@ workflowType: 'story'
 
 **Story ID:** {{module}}-S{{epic_number}}-{{story_number}}
 **Epic:** {{module}}-E{{epic_number}} - {{epic_title}}
-**Status:** draft | ready-for-dev | in-progress | review | done | blocked
-**Priority:** P0 | P1 | P2
+**Status:** draft | ready-for-dev | in-progress | review | done
 **Size:** XS | S | M | L | XL
-**Created:** {{date}}
-**Last Updated:** {{date}}
 
 ---
 
-## User Story
+## Prerequisites (PM reads before writing tasks)
 
-**As a** {{user_type}},
-**I want** {{capability}},
-**So that** {{benefit}}.
+<!-- ⚠️ MANDATORY: Read these docs before writing tasks! -->
 
----
-
-## Acceptance Criteria
+- [ ] `AGENTS.md` / `CLAUDE.md` - coding patterns, naming, error handling
+- [ ] `docs/coding-standards/` - detailed coding standards
+- [ ] `docs/architecture/{{module}}/` - module architecture, data model
+- [ ] Existing code in `src/services/{{module}}/` - patterns to follow
 
-### AC1: {{criterion_name}}
+---
 
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
-**And** {{additional_check}}
+## Goal
 
-### AC2: {{criterion_name}}
+{{Short description - 1-2 sentences. What this story achieves. Same as in epic's stories table.}}
 
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
+---
 
-### AC3: {{criterion_name}}
+## Acceptance Criteria
 
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
+- [ ] {{criterion_1}}
+- [ ] {{criterion_2}}
+- [ ] {{criterion_3}}
+- [ ] All tests pass
+- [ ] No linting errors
 
 ---
 
-## Self-Contained Tasks
-
-<!-- 
-Each task MUST be self-contained:
-- Agent can execute WITHOUT asking questions
-- All documentation links provided
-- Clear input/output/acceptance criteria
--->
-
-### Tasks Summary
+## Tasks
 
 | ID | Task | Deps | Status |
 |----|------|------|--------|
@@ -156,230 +140,38 @@ Each task MUST be self-contained:
 
 ---
 
-## TODO Placeholders
-
-<!-- 
-When implementing, leave TODO comments for:
-- Next tasks in this story
-- Future stories/epics
-- Technical debt
-- Planned improvements
-
-Format: TODO({TYPE}:{ID}): {description}
--->
-
-### TODOs to Create During Implementation
-
-| Location | TODO | Type | Reference |
-|----------|------|------|-----------|
-| `src/domain/{{entity}}` | Add validation for X | TASK | T3 |
-| `src/application/{{usecase}}` | Add caching | STORY | S{{epic}}-04 |
-| `src/infrastructure/repo/` | Add batch operations | EPIC | E{{next_epic}} |
-| `src/api/` | Add rate limiting | BACKLOG | - |
-
-### TODO Format Reference (IDE-compatible)
-
-```go
-// TODO(TASK:T3): Implement validation logic here
-//   Called from: T2 implementation
-//   Blocked until: T3 starts
-
-// TODO(STORY:{{module}}-S05-04): Add pagination support
-//   This story implements basic list, pagination in next story
-//   See: docs/sprint-artifacts/sprint-1/stories/story-05-04.md
+## Notes
 
-// TODO(EPIC:{{module}}-E06): Replace with event-driven approach
-//   Current sync implementation, async in Epic 6
-//   See: docs/sprint-artifacts/backlog/epic-06.md
-
-// TODO(SPRINT:SP3): Performance optimization needed
-//   Current O(n²), optimize in Sprint 3
-
-// TODO(BACKLOG): Consider adding retry logic
-//   Not planned yet, but would improve reliability
-
-// TODO(TECH_DEBT): Refactor this duplication
-//   Copy-pasted from X, extract common logic
-
-// FIXME(BUG:GH-123): Fix null pointer exception
-//   Occurs when input is empty
-//   Ticket: https://github.com/org/repo/issues/123
-
-// HACK: Temporary workaround for API limitation
-//   Remove when: STORY:{{module}}-S05-08 implemented
-```
-
-**GoLand/IntelliJ Setup:**
-```
-Settings → Editor → TODO → Add Pattern:
-  \bTODO\(.*\):.*
-  \bFIXME\(.*\):.*
-  \bHACK:.*
-```
-
-### Related Future Work
-
-| ID | Type | Description | Blocks This? |
-|----|------|-------------|--------------|
-| T3 | Task | Validation logic | No |
-| S{{epic}}-04 | Story | Pagination | No |
-| E{{next_epic}} | Epic | Event-driven | No |
+<!-- Optional: additional context, learnings, blockers -->
 
 ---
 
-## Dev Notes
-
-<!-- Context for the developer implementing this story -->
-
-### Coding Standards Applied (MANDATORY)
-
-**Standards documents used for this story:**
-- [ ] `CLAUDE.md` - Project patterns, file structure, conventions
-- [ ] `docs/coding-standards/` - Detailed coding standards
-  - [ ] Naming conventions
-  - [ ] Error handling patterns
-  - [ ] Testing patterns
-- [ ] `docs/architecture/{{module}}/architecture.md` - Module-specific patterns
-
-**Key patterns from CLAUDE.md:**
-- File naming: `{{file_naming_pattern}}`
-- Package structure: `{{package_structure}}`
-- Error handling: `{{error_handling_pattern}}`
-- Test file naming: `{{test_naming_pattern}}`
-
-### Architecture Requirements
-- Follow hexagonal architecture patterns
-- Domain layer must not import infrastructure
-- Use value objects for domain concepts
-
-### Technical Specifications
-- {{technical_specs}}
-
-### Dependencies
-- Depends on: {{dependencies}}
-- Blocked by: {{blockers}}
-
-### Previous Learnings
-- {{learnings_from_similar_work}}
-
-### Reference Files
-- `src/path/to/related/file` - [why relevant]
-- `docs/architecture.md#section` - [architecture guidance]
-- `CLAUDE.md#section` - [coding patterns]
-
-### Patterns to Follow
-- **MANDATORY:** Follow patterns from `CLAUDE.md`
-- **MANDATORY:** Follow `docs/coding-standards/`
-- Match existing code style in module
-
-### API/Interface
-```
-// Expected interface or function signature
-// (language-specific syntax)
-```
-
----
-
-## Test Scenarios
-
-### Unit Tests
-1. {{test_scenario_1}}
-2. {{test_scenario_2}}
-3. {{edge_case_1}}
-
-### Integration Tests
-1. {{integration_scenario_1}}
-2. {{integration_scenario_2}}
-
----
-
-## Dev Agent Record
-
-<!-- Automatically updated by Dev agent during implementation -->
-
-### Implementation Plan
-<!-- Dev agent documents approach here -->
-
-### Debug Log
-<!-- Dev agent logs debugging notes here -->
-
-### Completion Notes
-<!-- Dev agent summarizes what was implemented -->
-
----
-
-## File List
-
-<!-- Dev agent updates with all changed files -->
-
-### Created Files
-- 
-
-### Modified Files
-- 
+## Definition of Done
 
-### Deleted Files
-- 
+- [ ] All acceptance criteria met
+- [ ] All tasks completed
+- [ ] Tests passing (>80% coverage)
+- [ ] Code follows AGENTS.md patterns
+- [ ] No linting errors
+- [ ] PR merged to epic branch
 
 ---
 
 ## Changelog
 
-<!-- UPDATE AT END OF SESSION -->
-
 | Version | Date | Author | Changes |
 |---------|------|--------|---------|
-| 0.1 | {{date}} | @sm | Story created |
+| 0.1 | {{date}} | @pm | Story created |
 
 <!-- 
 Changelog Guidelines:
 - Update at END of work session
 - Dev: summarize what was implemented
 - Version: 0.x=draft, 1.0=ready-for-dev, 1.x=in-progress, 2.0=done
-
-Example session entries:
-| 2.0 | 2024-01-25 | @dev | Complete: T1-T7 done; All tests pass; Ready for review |
-| 1.1 | 2024-01-23 | @dev | Progress: T1-T4 complete; T5 blocked by API issue |
-| 1.0 | 2024-01-20 | @sm | Ready for dev: 7 tasks defined; AC reviewed |
 -->
 
 ---
 
-## Definition of Done
-
-- [ ] All acceptance criteria implemented and verified
-- [ ] All tasks/subtasks marked complete [x]
-- [ ] Unit tests written and passing (>80% coverage)
-- [ ] Integration tests written and passing
-- [ ] Code follows CLAUDE.md patterns
-- [ ] Code reviewed and approved
-- [ ] No linting errors
-- [ ] No failing tests (full suite)
-- [ ] File List complete
-- [ ] Change Log updated
-- [ ] PR merged to epic branch
-
----
-
-## Senior Developer Review (AI)
-
-<!-- Added after code-review workflow runs -->
-
-### Review Date
-<!-- Date of review -->
-
-### Review Outcome
-<!-- Approve | Changes Requested | Blocked -->
-
-### Action Items
-- [ ] {{action_item_1}}
-- [ ] {{action_item_2}}
-
-### Review Follow-ups (AI)
-<!-- Tasks added based on review findings -->
-
----
-
 ## Jira Metadata
 
 ```yaml