@comfanion/workflow 3.9.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "3.9.0",
+  "version": "4.1.0",
   "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:06:57.357Z",
+  "buildDate": "2026-01-23T17:40:44.228Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/config.yaml

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

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

@@ -206,26 +206,27 @@ S01 (Domain) ──┬──► S02 (Repo Interface) ──► S04 (Repo Impl)
                └──► S03 (Use Cases) ──► S05 (HTTP) ─┴──► S06 (Events) ──► S07 (Tests)
 ```
 
-### Total Effort Calculation
+### Story Breakdown
 
 ```markdown
-### Effort Summary
-
-| Story | Tasks | Hours | Days |
-|-------|-------|-------|------|
-| S01 | 4 | 20h | 2.5d |
-| S02 | 3 | 15h | 2d |
-| S03 | 5 | 26h | 3d |
-| S04 | 4 | 22h | 3d |
-| S05 | 3 | 16h | 2d |
-| S06 | 3 | 15h | 2d |
-| S07 | 3 | 15h | 2d |
-| **Total** | **25** | **129h** | **~16d** |
+### 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
-**With Parallelism:** ~10 days (2 weeks)
 ```
 
+**Note:** No hour estimates. Use T-shirt sizes (XS/S/M/L/XL) for relative complexity.
+
 ## Epic Sizing
 
 ### Guidelines

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:
@@ -85,37 +85,54 @@ 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]
 
 **Story ID:** [MODULE]-S[EPIC]-[NN]
 **Epic:** [MODULE]-E[EPIC] - [Epic Title]
-**Status:** TODO | IN_PROGRESS | REVIEW | DONE
-**Priority:** P0 | P1 | P2
-**Estimate:** XS | S | M | L | XL
+**Status:** draft | ready-for-dev | in-progress | review | done
+**Size:** XS | S | M | L | XL
+```
+
+### Goal (1-2 sentences)
+
+```markdown
+## Goal
+
+Implement CRUD use cases for merchant products with validation and event publishing.
 ```
 
-### User Story Format (MANDATORY)
+**NOT** the verbose "As a... I want... So that..." format. Just state what the story achieves.
+
+### 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)
 
-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
+Self-contained tasks with documentation links. See Task Structure below.
+
+### Sections (Simplified)
+
+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
 
@@ -141,65 +158,23 @@ Examples:
 - INVENTORY-S10-01
 ```
 
-## Acceptance Criteria (MANDATORY)
+## Self-Contained Tasks (NO ESTIMATES)
 
-Use skill: `acceptance-criteria`
+### Task Philosophy
 
-### Format: Given/When/Then
+**CRITICAL:** Tasks must be **SELF-CONTAINED** - an AI agent or developer can take ANY task and execute it independently without asking questions.
 
-```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
-
-## Atomic Tasks (4-6 hours each)
+**NO ESTIMATES** - Don't estimate time. Focus on clear scope and outcomes.
 
 ### Task Decomposition Rules
 
-**MANDATORY**: Every story MUST be broken into atomic tasks:
-
 | Rule | Description |
 |------|-------------|
-| **4-6 hours** | Each task should be 4-6 hours of focused work |
-| **Single responsibility** | One clear deliverable per task |
-| **Explicit dependencies** | Every task declares what it depends on |
-| **Parallel opportunities** | Independent tasks can run in parallel |
-| **Red-Green-Refactor** | Follow TDD cycle in task types |
+| **Self-contained** | Task has ALL information needed to execute |
+| **Documentation links** | Every task links to relevant docs, schemas, examples |
+| **Clear input/output** | What exists before, what must exist after |
+| **Testable outcome** | How to verify task is complete |
+| **Independent execution** | Can be picked up without context from other tasks |
 
 ## Development Methodologies
 
@@ -235,203 +210,137 @@ Interface → Stub Implementation → Tests → Real Implementation
 
 **Best for:** Exploratory work, unclear requirements, rapid prototyping
 
-### Task Structure by Methodology
+### Task Structure (MANDATORY FORMAT)
 
-**TDD Task:**
-```markdown
-### T2: Implement {{Entity}} Aggregate + Tests
-- **Estimate:** 5h
-- **Depends on:** T1
-- **Methodology:** TDD
-- **Deliverables:**
-  - [ ] Aggregate: `domain/aggregate/entity.go`
-  - [ ] Value objects: `domain/valueobject/*.go`
-- **Validation Test:** `domain/aggregate/entity_test.go`
-  - [ ] Test creation happy path
-  - [ ] Test validation errors
-  - [ ] Test business rules
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-```
+Each task MUST have this structure to be self-contained:
 
-**STUB Task:**
 ```markdown
-### T2: Implement Repository (Stub → Real) + Tests
-- **Estimate:** 6h
-- **Depends on:** T1
-- **Methodology:** STUB
-- **Deliverables:**
-  - [ ] Stub: `infrastructure/repo/entity_memory_repo.go`
-  - [ ] Real: `infrastructure/repo/entity_postgres_repo.go`
-- **Validation Test:** `infrastructure/repo/entity_repo_test.go`
-  - [ ] Test Save, FindByID, List
-  - [ ] Test with stub first
-  - [ ] Replace stub with real
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-```
-
----
+### T{N}: {Clear Task Name}
 
-### Task Types
+**Goal:** One sentence describing what this task achieves.
 
-| Type | Icon | Description |
-|------|------|-------------|
-| INTERFACE | 📐 | Define interface/contract |
-| RED | 🔴 | Write failing test first (TDD) |
-| GREEN | 🟢 | Implement to pass tests |
-| STUB | 🧪 | Stub implementation (STUB methodology) |
-| REFACTOR | 🔵 | Clean up, no new functionality |
-| INTEGRATION | 🔗 | E2E integration test |
-| DOCS | 📝 | Documentation only |
+**Documentation:**
+- [AGENTS.md#section](../../../AGENTS.md#section) - Relevant coding patterns
+- [data-model.md#table](../docs/data-model.md#table) - Database schema
+- [example.go](../src/path/example.go) - Pattern to follow
 
-### Task Structure
+**Input (Prerequisites):**
+- T{N-1} completed (if dependent)
+- Existing file: `path/to/existing.go` - what it provides
+- Repository interface defined in: `path/to/interface.go`
 
-```markdown
-### T{N}: {Task Name}
-- **Estimate:** 4h | 5h | 6h
-- **Depends on:** T1, T2 | - (none)
-- **Blocks:** T5, T6 | - (none)
-- **Type:** 🔴 RED | 🟢 GREEN | 🔵 REFACTOR | 📝 DOCS
-- **Files:** `path/to/file.go`
-- **Definition of Done:**
-  - [ ] Specific deliverable 1
-  - [ ] Specific deliverable 2
-- **Notes:** Implementation hints
-```
+**Output (Deliverables):**
+- `path/to/new_file.go` - Description of what this file does
+- `path/to/new_file_test.go` - Tests covering X, Y, Z
 
-### Dependency Graph (ASCII)
+**Implementation Steps:**
+1. Read documentation links above
+2. Create file structure following pattern from [example.go]
+3. Implement X following AGENTS.md conventions
+4. Write tests covering: happy path, validation errors, edge cases
+5. Run tests, ensure all pass
 
-Visualize task dependencies:
+**Acceptance Criteria:**
+- [ ] File created at correct path
+- [ ] Follows naming conventions from AGENTS.md
+- [ ] All tests pass: `go test ./path/to/...`
+- [ ] No linting errors: `golangci-lint run`
 
+**Notes:** Additional hints, gotchas, or context
 ```
-T1 ──┬──► T2 ──► T4
-     │           │
-     └──► T3 ────┴──► T5 ──► T6
-```
 
-- `──►` = depends on (must complete before)
-- `┬` = fork (parallel branches)
-- `┴` = join (waits for all)
+### Why This Structure?
+
+| Section | Purpose |
+|---------|---------|
+| **Goal** | Agent knows the "why" |
+| **Documentation** | Agent can read all needed context |
+| **Input** | Agent knows what must exist before starting |
+| **Output** | Agent knows exactly what to create |
+| **Implementation Steps** | Agent has step-by-step guidance |
+| **Acceptance Criteria** | Agent can verify completion |
 
-### Summary Table (MANDATORY)
+### Tasks Summary Table
 
 ```markdown
-| ID | Task | Est | Depends On | Status |
-|----|------|-----|------------|--------|
-| T1 | Domain layer (aggregates, value objects, tests) | 6h | - | ⬜ |
-| T2 | Repository interface + use case tests | 5h | T1 | ⬜ |
-| T3 | Use case implementation | 5h | T2 | ⬜ |
-| T4 | Repository implementation (PostgreSQL) | 6h | T2 | ⬜ |
-| T5 | HTTP handlers + tests | 5h | T3 | ⬜ |
-| T6 | Integration tests + refactor | 5h | T4, T5 | ⬜ |
+| ID | Task | Deps | Status |
+|----|------|------|--------|
+| T1 | MerchantProduct Aggregate + Value Objects | - | ⬜ |
+| T2 | Repository Interface | T1 | ⬜ |
+| T3 | CreateProduct Use Case | T2 | ⬜ |
+| T4 | PostgreSQL Repository Implementation | T2 | ⬜ |
+| T5 | HTTP Handler + Routes | T3, T4 | ⬜ |
 ```
 
 **Status:** ⬜ TODO | 🔄 IN_PROGRESS | ✅ DONE | ⏸️ BLOCKED
 
-### Execution Phases
-
-Group tasks by parallel execution opportunity:
+### Dependency Graph (Optional)
 
-```markdown
-### Execution Order
-
-Phase 1: T1 (no deps)
-Phase 2: T2, T3 (parallel - both depend only on T1)
-Phase 3: T4, T6 (parallel - independent branches)
-Phase 4: T5 (waits for T3, T4)
-Phase 5: T7 (waits for T5)
-Phase 6: T8, T6-continued (parallel)
-Phase 7: T9 (waits for T6, T8)
-Phase 8: T10 (final)
-
-**Critical Path:** T1 → T2 → T4 → T5 → T7 → T8 → T9 → T10
-**Total Estimate:** 32h (4 days)
-**Parallel Savings:** ~3h (25%)
 ```
-
-### Example: CreateProduct Story Tasks
-
-```markdown
-| ID | Task | Est | Depends On | Type |
-|----|------|-----|------------|------|
-| T1 | Domain layer: Product aggregate + value objects + tests | 6h | - | 🔴🟢 |
-| T2 | Repository interface + CreateProduct use case tests | 5h | T1 | 🔴 |
-| T3 | CreateProduct use case implementation | 5h | T2 | 🟢 |
-| T4 | PostgreSQL repository implementation + tests | 6h | T2 | 🟢 |
-| T5 | HTTP handler + tests | 5h | T3 | 🔴🟢 |
-| T6 | Integration tests + refactor + documentation | 5h | T4, T5 | 🔵 |
-
-**Graph:**
-T1 ──► T2 ──┬──► T4 ──► T5 ──► T7 ──► T8 ──┬──► T9 ──► T10
-            │                               │
-T3 ─────────┴───────────► T6 ───────────────┘
+T1 ──► T2 ──┬──► T3 ──┬──► T5
+            │         │
+            └──► T4 ──┘
 ```
 
-### Splitting Large Tasks
-
-If a task exceeds 6h, consider splitting it. **Each task MUST have validation test.**
-
-| Original (8h+) | Split Into (with tests) |
-|----------------|------------------------|
-| "Full domain layer" (10h) | **T1:** Value objects + tests (4h)<br>**T2:** Aggregate + business rules + tests (6h) |
-| "Full repository" (10h) | **T1:** Interface + Save/FindByID + tests (5h)<br>**T2:** List/Search + advanced queries + tests (5h) |
-
-### Task Template with Validation
-
-```markdown
-### T{N}: {Task Name}
-- **Estimate:** 5h
-- **Depends on:** T{N-1}
-- **Methodology:** TDD | STUB
-- **Deliverables:**
-  - [ ] File: `path/to/implementation.go`
-  - [ ] File: `path/to/implementation2.go`
-- **Validation Test:** `path/to/implementation_test.go`
-  - [ ] Test case 1: happy path
-  - [ ] Test case 2: error handling
-  - [ ] Test case 3: edge case
-  - [ ] **⚠️ ALL TESTS MUST PASS** ← MANDATORY
-- **Notes:** Implementation hints
-```
-
-### Validation Test Requirements
-
-**Every task MUST have:**
+---
 
-| Test Type | Required | Description |
-|-----------|----------|-------------|
-| Happy path | ✅ Yes | Normal success case |
-| Error handling | ✅ Yes | Expected failures |
-| Edge cases | Recommended | Boundary conditions |
-| **Pass gate** | ✅ MANDATORY | `⚠️ ALL TESTS MUST PASS` |
+## Full Task Example
 
-### TDD vs STUB Task Examples
+Here's a complete example of a self-contained task:
 
-**TDD Example:**
 ```markdown
-### T2: Implement Product Aggregate
-- **Methodology:** TDD
-- **Deliverables:**
-  - [ ] `domain/aggregate/product.go`
-- **Validation Test:** `domain/aggregate/product_test.go`
-  - [ ] 🔴 Write test first (should FAIL)
-  - [ ] 🟢 Implement until test PASSES
-  - [ ] 🔵 Refactor, tests still PASS
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-```
-
-**STUB Example:**
-```markdown
-### T4: Implement Repository
-- **Methodology:** STUB
-- **Deliverables:**
-  - [ ] Stub: `infrastructure/repo/product_memory_repo.go`
-  - [ ] Real: `infrastructure/repo/product_postgres_repo.go`
-- **Validation Test:** `infrastructure/repo/product_repo_test.go`
-  - [ ] 🧪 Write stub (mock data)
-  - [ ] ✅ Write tests against stub
-  - [ ] 🟢 Replace with real impl
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-```
+### T1: MerchantProduct Aggregate + Value Objects
+
+**Goal:** Create the MerchantProduct aggregate with all value objects and domain validation.
+
+**Documentation:**
+- [AGENTS.md#type-safety](../../../AGENTS.md#type-safety) - Value object patterns
+- [AGENTS.md#naming-conventions](../../../AGENTS.md#naming-conventions) - File/package naming
+- [catalog-data-model.md#merchant_products](../docs/catalog-data-model.md#31-merchant-products) - Database schema
+- [modules/catalog/domain/entity/marketplace_category.go](../src/services/catalog/modules/catalog/domain/entity/marketplace_category.go) - Example entity pattern
+
+**Input (Prerequisites):**
+- None (first task in story)
+- Existing patterns in `modules/catalog/domain/` to follow
+
+**Output (Deliverables):**
+- `modules/catalog/domain/valueobject/merchant_id.go` - UUID wrapper with validation
+- `modules/catalog/domain/valueobject/product_id.go` - UUID wrapper
+- `modules/catalog/domain/valueobject/merchant_sku.go` - String with max length validation
+- `modules/catalog/domain/valueobject/ean.go` - GTIN-13 checksum validation
+- `modules/catalog/domain/valueobject/product_status.go` - Enum (pending, active, etc.)
+- `modules/catalog/domain/entity/merchant_product.go` - Aggregate with private fields + getters
+- `modules/catalog/domain/entity/merchant_product_test.go` - All tests
+
+**Implementation Steps:**
+1. Read AGENTS.md sections on value objects and naming
+2. Look at existing `marketplace_category.go` for entity pattern
+3. Create value objects with `New*()` factory functions that validate
+4. Create aggregate with private fields, public getters, factory method
+5. Write tests: creation happy path, validation errors, status transitions
+6. Run `go test ./modules/catalog/domain/...`
+
+**Acceptance Criteria:**
+- [ ] All files created at correct paths
+- [ ] Value objects validate on construction (not setters)
+- [ ] EAN validates GTIN-13 checksum
+- [ ] Aggregate uses private fields with getters
+- [ ] Tests cover: valid creation, invalid data rejection, status transitions
+- [ ] `go test ./modules/catalog/domain/...` passes
+- [ ] `golangci-lint run ./modules/catalog/domain/...` passes
+
+**Notes:** 
+- EAN checksum algorithm: sum odd positions × 1, even × 3, check digit makes sum divisible by 10
+- Status enum values from PRD: pending, pending_category, pending_dedup, pending_pim, active, declined
+```
+
+### What Makes This Task Self-Contained?
+
+1. **Agent can start immediately** - all documentation links provided
+2. **No guessing** - exact file paths specified  
+3. **Pattern to follow** - links to existing code examples
+4. **Clear verification** - specific test commands and criteria
+5. **Context included** - notes explain non-obvious details (EAN algorithm)
 
 ## Definition of Done
 
@@ -610,13 +519,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/epic-template.md

@@ -84,8 +84,8 @@ S01 ──► S02 ──► S03 ──► S04
 ### Story Decomposition Rules
 
 Each story MUST:
-1. Be completable in 2-5 days
-2. Have 3-6 atomic tasks (4-6h each)
+1. Be completable (not too big, not too small)
+2. Have self-contained tasks with documentation links
 3. Have clear dependencies on other stories
 4. Map to specific Acceptance Criteria
 
@@ -99,15 +99,17 @@ Each story MUST:
 6. **Events** - Domain events, Kafka publishers
 7. **Integration Tests** - End-to-end verification
 
-### Total Effort Breakdown
+### Stories by Layer
 
-| Layer | Stories | Tasks | Hours |
-|-------|---------|-------|-------|
-| Domain | 1 | 4 | 20h |
-| Application | 1 | 4 | 22h |
-| Infrastructure | 2 | 5 | 28h |
-| Testing | 1 | 3 | 15h |
-| **Total** | **5** | **16** | **85h** |
+| Layer | Stories | Tasks | Size |
+|-------|---------|-------|------|
+| Domain | 1 | 4 | M |
+| Application | 2 | 6 | M |
+| Infrastructure | 2 | 5 | L |
+| Testing | 1 | 3 | S |
+| **Total** | **6** | **18** | |
+
+**Note:** No hour estimates. Size = relative complexity (XS/S/M/L/XL).
 
 ---
 

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

@@ -8,436 +8,170 @@ 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
-**Estimate:** XS | S | M | L | XL
-**Created:** {{date}}
-**Last Updated:** {{date}}
+**Status:** draft | ready-for-dev | in-progress | review | done
+**Size:** XS | S | M | L | XL
 
 ---
 
-## 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
-
-### AC1: {{criterion_name}}
-
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
-**And** {{additional_check}}
-
-### AC2: {{criterion_name}}
-
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
-
-### AC3: {{criterion_name}}
-
-**Given** {{precondition}}
-**When** {{action}}
-**Then** {{expected_result}}
+- [ ] `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
 
 ---
 
-## Atomic Tasks
-
-<!-- 
-METHODOLOGY: {{methodology}} (tdd | stub)
-- TDD:  Interface → Test (failing) → Implementation → Refactor
-- STUB: Interface → Stub → Test → Full Implementation
-
-RULES:
-- Each task is 4-6 hours of focused work
-- Each task includes TEST as validation gate
-- Tasks have explicit dependencies
-- Dev agent respects dependency order
--->
-
-### Development Methodology: **{{methodology}}**
+## Goal
 
-```
-{{#if methodology == "tdd"}}
-TDD Flow per Task:
-  1. Define Interface/Contract
-  2. Write Failing Test (RED)
-  3. Implement Minimal Code (GREEN)
-  4. Refactor
-  5. Validate: Test MUST pass
-{{/if}}
-{{#if methodology == "stub"}}
-STUB Flow per Task:
-  1. Define Interface/Contract
-  2. Write Stub Implementation (returns mock data)
-  3. Write Tests against Stub
-  4. Replace Stub with Real Implementation
-  5. Validate: Test MUST pass
-{{/if}}
-```
+{{Short description - 1-2 sentences. What this story achieves. Same as in epic's stories table.}}
 
 ---
 
-### Task Dependency Graph
-
-```
-T1 ──┬──► T2 ──► T3
-     │
-     └──► T4 ──► T5
-                  │
-T3 ───────────────┴──► T6
-```
-
-### Tasks Summary
-
-| ID | Task | Est | Deps | Test | Status |
-|----|------|-----|------|------|--------|
-| T1 | {{task_1}} | 5h | - | unit | ⬜ |
-| T2 | {{task_2}} | 6h | T1 | unit | ⬜ |
-| T3 | {{task_3}} | 5h | T2 | unit | ⬜ |
-| T4 | {{task_4}} | 5h | T1 | unit | ⬜ |
-| T5 | {{task_5}} | 5h | T3,T4 | integration | ⬜ |
+## Acceptance Criteria
 
-**Status:** ⬜ TODO | 🔄 IN_PROGRESS | ✅ DONE | ⏸️ BLOCKED | ❌ FAILED
+- [ ] {{criterion_1}}
+- [ ] {{criterion_2}}
+- [ ] {{criterion_3}}
+- [ ] All tests pass
+- [ ] No linting errors
 
 ---
 
-### T1: Domain Layer (Aggregates, Value Objects)
-- **Estimate:** 6h
-- **Depends on:** -
-- **Blocks:** T2
-- **Deliverables:**
-  - [ ] Interface/contract defined
-  - [ ] Value objects with validation
-  - [ ] Aggregate with business rules
-  - [ ] Factory methods
-- **Validation Test:** 
-  - [ ] Value object tests (validation, equality)
-  - [ ] Aggregate creation tests
-  - [ ] Business rules tests
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+## Tasks
 
----
+| ID | Task | Deps | Status |
+|----|------|------|--------|
+| T1 | {{task_1_name}} | - | ⬜ |
+| T2 | {{task_2_name}} | T1 | ⬜ |
+| T3 | {{task_3_name}} | T2 | ⬜ |
 
-### T2: Repository Interface + Use Case Tests
-- **Estimate:** 5h
-- **Depends on:** T1
-- **Blocks:** T3, T4
-- **Deliverables:**
-  - [ ] Repository interface (ports)
-  - [ ] Use case interface
-  - [ ] Use case DTOs (input/output)
-  - [ ] Use case tests (with mock repository)
-- **Validation Test:**
-  - [ ] Use case happy path test
-  - [ ] Use case error handling tests
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+**Status:** ⬜ TODO | 🔄 IN_PROGRESS | ✅ DONE | ⏸️ BLOCKED
 
 ---
 
-### T3: Use Case Implementation
-- **Estimate:** 5h
-- **Depends on:** T2
-- **Blocks:** T5
-- **Deliverables:**
-  - [ ] Use case handler implementation
-  - [ ] Mappers (entity ↔ DTO)
-  - [ ] Error handling
-- **Validation Test:**
-  - [ ] All use case tests pass
-  - [ ] Edge cases covered
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
-
----
+### T1: {{task_1_name}}
 
-### T4: Repository Implementation
-- **Estimate:** 6h
-- **Depends on:** T2
-- **Blocks:** T5
-- **Deliverables (TDD):**
-  - [ ] Write repository tests first
-  - [ ] PostgreSQL repository implementation
-- **Deliverables (STUB):**
-  - [ ] In-memory stub first
-  - [ ] PostgreSQL implementation
-- **Validation Test:**
-  - [ ] Test Save
-  - [ ] Test FindByID (found/not found)
-  - [ ] Test List with filters
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+**Goal:** {{what_this_task_achieves}}
 
----
+**Documentation:**
+- [AGENTS.md#section](../../../AGENTS.md#section) - {{what_pattern}}
+- [data-model.md#table](../../../docs/data-model.md#section) - {{schema_info}}
+- [existing_example.go](../path/to/example.go) - Pattern to follow
 
-### T5: HTTP Handlers + Integration Tests
-- **Estimate:** 5h
-- **Depends on:** T3, T4
-- **Blocks:** -
-- **Deliverables:**
-  - [ ] HTTP handler/controller
-  - [ ] Routes registered
-  - [ ] Request/response validation
-  - [ ] Integration tests
-  - [ ] Documentation updated
-- **Validation Test:**
-  - [ ] Test 201 Created
-  - [ ] Test 400 Bad Request (validation)
-  - [ ] Test 404 Not Found
-  - [ ] E2E: API → Service → Repo → DB
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-  - [ ] **⚠️ NO REGRESSIONS**
-- **Notes:** {{implementation_hint}}
+**Input (Prerequisites):**
+- {{what_must_exist_before_starting}}
+- Existing file: `path/to/dependency.go` - provides {{what}}
 
----
+**Output (Deliverables):**
+- `path/to/new_file.go` - {{description}}
+- `path/to/new_file_test.go` - Tests for {{what}}
 
-### Execution Phases
+**Implementation Steps:**
+1. Read documentation links above
+2. {{step_2}}
+3. {{step_3}}
+4. Write tests covering: happy path, errors, edge cases
+5. Run: `go test ./path/to/...`
 
-| Phase | Tasks (Parallel) | Duration | Tests Required |
-|-------|-----------------|----------|----------------|
-| 1 | T1 | 6h | Domain layer tests |
-| 2 | T2 | 5h | Use case tests |
-| 3 | T3, T4 | 6h | Implementation tests |
-| 4 | T5 | 5h | Integration tests |
-| **Total** | | **22h** | **All green** |
+**Acceptance Criteria:**
+- [ ] Files created at specified paths
+- [ ] Follows patterns from AGENTS.md
+- [ ] Tests pass: `go test ./path/to/...`
+- [ ] Lint passes: `golangci-lint run`
 
-**Critical Path:** T1 → T2 → T3 → T5 = 21h (~3 days)
-**With Parallelism (T3 || T4):** ~2.5 days
+**Notes:** {{additional_context_or_gotchas}}
 
 ---
 
-## TODO Placeholders
+### T2: {{task_2_name}}
 
-<!-- 
-When implementing, leave TODO comments for:
-- Next tasks in this story
-- Future stories/epics
-- Technical debt
-- Planned improvements
-
-Format: TODO({TYPE}:{ID}): {description}
--->
+**Goal:** {{what_this_task_achieves}}
 
-### TODOs to Create During Implementation
+**Documentation:**
+- [AGENTS.md#section](link) - {{pattern}}
+- [T1 output](../path/from/T1) - Uses types from T1
 
-| 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 | - |
+**Input (Prerequisites):**
+- T1 completed
+- Files from T1: `path/to/aggregate.go`
 
-### 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
-
-// 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
-```
+**Output (Deliverables):**
+- `path/to/file.go` - {{description}}
+- `path/to/file_test.go` - Tests
 
-**GoLand/IntelliJ Setup:**
-```
-Settings → Editor → TODO → Add Pattern:
-  \bTODO\(.*\):.*
-  \bFIXME\(.*\):.*
-  \bHACK:.*
-```
+**Implementation Steps:**
+1. {{step}}
+2. {{step}}
 
-### Related Future Work
+**Acceptance Criteria:**
+- [ ] {{criterion}}
+- [ ] Tests pass
 
-| ID | Type | Description | Blocks This? |
-|----|------|-------------|--------------|
-| T3 | Task | Validation logic | No |
-| S{{epic}}-04 | Story | Pagination | No |
-| E{{next_epic}} | Epic | Event-driven | No |
+**Notes:** {{notes}}
 
 ---
 
-## 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}}
+### T3: {{task_3_name}}
 
-### Reference Files
-- `src/path/to/related/file` - [why relevant]
-- `docs/architecture.md#section` - [architecture guidance]
-- `CLAUDE.md#section` - [coding patterns]
+**Goal:** {{goal}}
 
-### Patterns to Follow
-- **MANDATORY:** Follow patterns from `CLAUDE.md`
-- **MANDATORY:** Follow `docs/coding-standards/`
-- Match existing code style in module
+**Documentation:**
+- {{links}}
 
-### API/Interface
-```
-// Expected interface or function signature
-// (language-specific syntax)
-```
+**Input (Prerequisites):**
+- T2 completed
+- {{dependencies}}
 
----
+**Output (Deliverables):**
+- {{files}}
 
-## Test Scenarios
+**Implementation Steps:**
+1. {{steps}}
 
-### Unit Tests
-1. {{test_scenario_1}}
-2. {{test_scenario_2}}
-3. {{edge_case_1}}
+**Acceptance Criteria:**
+- [ ] {{criteria}}
+- [ ] All tests pass
+- [ ] **⚠️ NO REGRESSIONS** (run full test suite)
 
-### Integration Tests
-1. {{integration_scenario_1}}
-2. {{integration_scenario_2}}
+**Notes:** {{notes}}
 
 ---
 
-## Dev Agent Record
-
-<!-- Automatically updated by Dev agent during implementation -->
-
-### Implementation Plan
-<!-- Dev agent documents approach here -->
+## Notes
 
-### Debug Log
-<!-- Dev agent logs debugging notes here -->
-
-### Completion Notes
-<!-- Dev agent summarizes what was implemented -->
+<!-- Optional: additional context, learnings, blockers -->
 
 ---
 
-## 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