@comfanion/workflow 3.8.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "3.8.0",
+  "version": "4.0.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:01:07.473Z",
+  "buildDate": "2026-01-23T17:21:08.417Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/config.yaml

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

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

@@ -168,15 +168,15 @@ Track which FRs are covered:
 
 ```
 EPIC (1-2 weeks)
-  └── STORY (1-3 days)
-        └── TASK (1-2 hours)
+  └── STORY (2-5 days)
+        └── TASK (4-6 hours)
 ```
 
 | Level | Duration | Count | Deliverable |
 |-------|----------|-------|-------------|
 | **Epic** | 1-2 weeks | 1 | Complete feature |
-| **Story** | 1-3 days | 3-8 per epic | User-facing capability |
-| **Task** | 1-2 hours | 4-10 per story | Atomic code change |
+| **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
 
@@ -206,40 +206,41 @@ 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 | 6 | 8h | 1d |
-| S02 | 3 | 4h | 0.5d |
-| S03 | 8 | 12h | 1.5d |
-| S04 | 6 | 9h | 1d |
-| S05 | 5 | 7h | 1d |
-| S06 | 4 | 5h | 0.5d |
-| S07 | 4 | 6h | 1d |
-| **Total** | **36** | **51h** | **6.5d** |
+### 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:** ~5 days
 ```
 
+**Note:** No hour estimates. Use T-shirt sizes (XS/S/M/L/XL) for relative complexity.
+
 ## Epic Sizing
 
 ### Guidelines
 
 - **Duration:** 1-2 weeks of work
 - **Stories:** 3-8 stories per epic
-- **Tasks:** 25-60 tasks per epic (total across stories)
+- **Tasks:** 15-35 tasks per epic (total across stories)
 - **Scope:** One logical feature/capability
 
 ### Too Big? Split it!
 
 Signs an epic is too big:
 - More than 10 stories
-- More than 80 tasks total
+- More than 40 tasks total
 - Spans multiple sprints
 - Multiple unrelated features
 - Different team members for different parts
@@ -248,8 +249,8 @@ Signs an epic is too big:
 
 Signs an epic is too small:
 - Only 1-2 stories
-- Less than 15 tasks
-- Can be done in 2-3 days
+- Less than 8 tasks
+- Can be done in 3-4 days
 - Part of a larger feature
 
 ### Parallel Execution Opportunities
@@ -261,11 +262,11 @@ Identify which stories can run in parallel:
 
 | Phase | Stories (Parallel) | Duration |
 |-------|-------------------|----------|
-| 1 | S01 | 1d |
-| 2 | S02, S03 | 1.5d |
-| 3 | S04, S05 | 1d |
-| 4 | S06 | 0.5d |
-| 5 | S07 | 1d |
+| 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

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

@@ -92,11 +92,13 @@ Use template at: `@.opencode/templates/story-template.md`
 
 **Story ID:** [MODULE]-S[EPIC]-[NN]
 **Epic:** [MODULE]-E[EPIC] - [Epic Title]
-**Status:** TODO | IN_PROGRESS | REVIEW | DONE
+**Status:** draft | ready-for-dev | in-progress | review | done
 **Priority:** P0 | P1 | P2
-**Estimate:** XS | S | M | L | XL
+**Size:** XS | S | M | L | XL
 ```
 
+**Note:** Size is relative complexity (T-shirt sizing). NO hour estimates for tasks.
+
 ### User Story Format (MANDATORY)
 
 ```markdown
@@ -187,19 +189,23 @@ Each story should have:
 - **Authorization** - Permission checks
 - **Edge cases** - Boundary conditions
 
-## Atomic Tasks (1-2 hours each)
+## Self-Contained Tasks (NO ESTIMATES)
 
-### Task Decomposition Rules
+### Task Philosophy
+
+**CRITICAL:** Tasks must be **SELF-CONTAINED** - an AI agent or developer can take ANY task and execute it independently without asking questions.
+
+**NO ESTIMATES** - Don't estimate time. Focus on clear scope and outcomes.
 
-**MANDATORY**: Every story MUST be broken into atomic tasks:
+### Task Decomposition Rules
 
 | Rule | Description |
 |------|-------------|
-| **Max 2 hours** | No task should exceed 2 hours of 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,208 +241,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
-- **Estimate:** 1.5h
-- **Depends on:** T1
-- **Methodology:** TDD
-- **Deliverables:**
-  - [ ] Aggregate: `domain/aggregate/entity.go`
-- **Validation Test:** `domain/aggregate/entity_test.go`
-  - [ ] Test creation happy path
-  - [ ] Test validation errors  
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-```
+Each task MUST have this structure to be self-contained:
 
-**STUB Task:**
 ```markdown
-### T2: Implement Repository (Stub → Real)
-- **Estimate:** 1.5h
-- **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 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:** 1h | 1.5h | 2h
-- **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 | Write aggregate test | 1h | - | ⬜ |
-| T2 | Implement aggregate | 1.5h | T1 | ⬜ |
-| T3 | Write repository interface | 0.5h | T1 | ⬜ |
-| T4 | Write use case test | 1h | T2 | ⬜ |
-| T5 | Implement use case | 1.5h | T3, T4 | ⬜ |
-| T6 | Implement repository | 1.5h | T3 | ⬜ |
-| T7 | Write HTTP handler test | 1h | T5 | ⬜ |
-| T8 | Implement HTTP handler | 1h | T7 | ⬜ |
-| T9 | Integration tests | 1.5h | T6, T8 | ⬜ |
-| T10 | Refactor & docs | 1h | T9 | ⬜ |
+| 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:
-
-```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:** 12h
-**Parallel Savings:** ~3h (25%)
-```
+### Dependency Graph (Optional)
 
-### Example: CreateProduct Story Tasks
-
-```markdown
-| ID | Task | Est | Depends On | Type |
-|----|------|-----|------------|------|
-| T1 | Write Product aggregate test | 1h | - | 🔴 |
-| T2 | Implement Product aggregate | 1.5h | T1 | 🟢 |
-| T3 | Write ProductRepository interface | 0.5h | - | 📝 |
-| T4 | Write CreateProduct use case test | 1h | T2, T3 | 🔴 |
-| T5 | Implement CreateProduct handler | 1.5h | T4 | 🟢 |
-| T6 | Implement PostgreSQL repository | 1.5h | T3 | 🟢 |
-| T7 | Write HTTP handler test | 1h | T5 | 🔴 |
-| T8 | Implement HTTP handler | 1h | T7 | 🟢 |
-| T9 | Write integration tests | 1.5h | T6, T8 | 🔴 |
-| T10 | Refactor & documentation | 1h | T9 | 🔵 |
-
-**Graph:**
-T1 ──► T2 ──┬──► T4 ──► T5 ──► T7 ──► T8 ──┬──► T9 ──► T10
-            │                               │
-T3 ─────────┴───────────► T6 ───────────────┘
 ```
-
-### Splitting Large Tasks
-
-If a task exceeds 2h, split it. **Each split task MUST have validation test.**
-
-| Original (4h) | Split Into (with tests) |
-|---------------|------------------------|
-| "Implement repository" | **T1:** Interface + contract test (0.5h)<br>**T2:** Save method + test (1h)<br>**T3:** FindByID + test (1h)<br>**T4:** List + test (1.5h) |
-| "Write aggregate" | **T1:** Value objects + tests (1h)<br>**T2:** Aggregate + creation test (1h)<br>**T3:** Business rules + tests (1h) |
-
-### Task Template with Validation
-
-```markdown
-### T{N}: {Task Name}
-- **Estimate:** 1.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
+T1 ──► T2 ──┬──► T3 ──┬──► T5
+            │         │
+            └──► T4 ──┘
 ```
 
-### 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` |
+---
 
-### TDD vs STUB Task Examples
+## Full Task Example
 
-**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**
-```
+Here's a complete example of a self-contained task:
 
-**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
 

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 1-3 days
-2. Have 4-10 atomic tasks (1-2h 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 | 6 | 8h |
-| Application | 1 | 8 | 12h |
-| Infrastructure | 2 | 9 | 14h |
-| Testing | 1 | 4 | 6h |
-| **Total** | **5** | **27** | **40h** |
+| 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

@@ -10,7 +10,7 @@ workflowType: 'story'
 **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
+**Size:** XS | S | M | L | XL
 **Created:** {{date}}
 **Last Updated:** {{date}}
 
@@ -47,177 +47,112 @@ workflowType: 'story'
 
 ---
 
-## Atomic Tasks
+## Self-Contained Tasks
 
 <!-- 
-METHODOLOGY: {{methodology}} (tdd | stub)
-- TDD:  Interface → Test (failing) → Implementation → Refactor
-- STUB: Interface → Stub → Test → Full Implementation
-
-RULES:
-- Each task is 1-2 hours max
-- Each task includes TEST as validation gate
-- Tasks have explicit dependencies
-- Dev agent respects dependency order
+Each task MUST be self-contained:
+- Agent can execute WITHOUT asking questions
+- All documentation links provided
+- Clear input/output/acceptance criteria
 -->
 
-### Development Methodology: **{{methodology}}**
+### Tasks Summary
 
-```
-{{#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}}
-```
+| ID | Task | Deps | Status |
+|----|------|------|--------|
+| T1 | {{task_1_name}} | - | ⬜ |
+| T2 | {{task_2_name}} | T1 | ⬜ |
+| T3 | {{task_3_name}} | T2 | ⬜ |
+
+**Status:** ⬜ TODO | 🔄 IN_PROGRESS | ✅ DONE | ⏸️ BLOCKED
 
 ---
 
-### Task Dependency Graph
+### T1: {{task_1_name}}
 
-```
-T1 ──┬──► T2 ──► T3
-     │
-     └──► T4 ──► T5
-                  │
-T3 ───────────────┴──► T6
-```
+**Goal:** {{what_this_task_achieves}}
 
-### Tasks Summary
+**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
 
-| ID | Task | Est | Deps | Test | Status |
-|----|------|-----|------|------|--------|
-| T1 | {{task_1}} | 1h | - | unit | ⬜ |
-| T2 | {{task_2}} | 1.5h | T1 | unit | ⬜ |
-| T3 | {{task_3}} | 1h | T2 | unit | ⬜ |
-| T4 | {{task_4}} | 1.5h | T1 | unit | ⬜ |
-| T5 | {{task_5}} | 1h | T4 | unit | ⬜ |
-| T6 | {{task_6}} | 1.5h | T3,T5 | integration | ⬜ |
+**Input (Prerequisites):**
+- {{what_must_exist_before_starting}}
+- Existing file: `path/to/dependency.go` - provides {{what}}
 
-**Status:** ⬜ TODO | 🔄 IN_PROGRESS | ✅ DONE | ⏸️ BLOCKED | ❌ FAILED
+**Output (Deliverables):**
+- `path/to/new_file.go` - {{description}}
+- `path/to/new_file_test.go` - Tests for {{what}}
 
----
+**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/...`
+
+**Acceptance Criteria:**
+- [ ] Files created at specified paths
+- [ ] Follows patterns from AGENTS.md
+- [ ] Tests pass: `go test ./path/to/...`
+- [ ] Lint passes: `golangci-lint run`
 
-### T1: Define {{entity}} Interface
-- **Estimate:** 1h
-- **Depends on:** -
-- **Blocks:** T2, T4
-- **Deliverables:**
-  - [ ] Interface/contract defined
-  - [ ] Value objects defined (if needed)
-- **Validation Test:** 
-  - [ ] Contract test (compile/type check)
-- **Notes:** {{implementation_hint}}
+**Notes:** {{additional_context_or_gotchas}}
 
 ---
 
-### T2: Implement {{entity}} Entity/Model
-- **Estimate:** 1.5h
-- **Depends on:** T1
-- **Blocks:** T3
-- **Deliverables:**
-  - [ ] Entity/model with business logic
-  - [ ] Factory method with validation
-- **Validation Test:**
-  - [ ] Test creation happy path
-  - [ ] Test validation errors
-  - [ ] Test business rules
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+### T2: {{task_2_name}}
 
----
+**Goal:** {{what_this_task_achieves}}
 
-### T3: Implement Use Case / Service
-- **Estimate:** 1h
-- **Depends on:** T2
-- **Blocks:** T6
-- **Deliverables:**
-  - [ ] Use case handler/service
-  - [ ] Input/Output DTOs
-  - [ ] Mappers (entity ↔ DTO)
-- **Validation Test:**
-  - [ ] Test happy path (mock repository)
-  - [ ] Test validation errors
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+**Documentation:**
+- [AGENTS.md#section](link) - {{pattern}}
+- [T1 output](../path/from/T1) - Uses types from T1
 
----
+**Input (Prerequisites):**
+- T1 completed
+- Files from T1: `path/to/aggregate.go`
 
-### T4: Implement Repository / Data Access
-- **Estimate:** 1.5h
-- **Depends on:** T1
-- **Blocks:** T5
-- **Deliverables (TDD):**
-  - [ ] Write test first
-  - [ ] Implement repository
-- **Deliverables (STUB):**
-  - [ ] In-memory stub first
-  - [ ] Real implementation
-- **Validation Test:**
-  - [ ] Test Save
-  - [ ] Test FindByID
-  - [ ] Test FindByID not found
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+**Output (Deliverables):**
+- `path/to/file.go` - {{description}}
+- `path/to/file_test.go` - Tests
 
----
+**Implementation Steps:**
+1. {{step}}
+2. {{step}}
+
+**Acceptance Criteria:**
+- [ ] {{criterion}}
+- [ ] Tests pass
 
-### T5: Implement API Handler
-- **Estimate:** 1h
-- **Depends on:** T4
-- **Blocks:** T6
-- **Deliverables:**
-  - [ ] API handler/controller
-  - [ ] Routes registered
-- **Validation Test:**
-  - [ ] Test 201 Created
-  - [ ] Test 400 Bad Request
-  - [ ] Test 403 Forbidden
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-- **Notes:** {{implementation_hint}}
+**Notes:** {{notes}}
 
 ---
 
-### T6: Integration Test & Refactor
-- **Estimate:** 1.5h
-- **Depends on:** T3, T5
-- **Blocks:** -
-- **Deliverables:**
-  - [ ] Integration test
-  - [ ] Code refactored, no smells
-  - [ ] Documentation updated
-- **Validation Test:**
-  - [ ] E2E: API → Service → Repo → DB
-  - [ ] Event published (if applicable)
-  - [ ] **⚠️ ALL TESTS MUST PASS**
-  - [ ] **⚠️ NO REGRESSIONS**
-- **Notes:** {{implementation_hint}}
+### T3: {{task_3_name}}
 
----
+**Goal:** {{goal}}
+
+**Documentation:**
+- {{links}}
+
+**Input (Prerequisites):**
+- T2 completed
+- {{dependencies}}
+
+**Output (Deliverables):**
+- {{files}}
 
-### Execution Phases
+**Implementation Steps:**
+1. {{steps}}
 
-| Phase | Tasks (Parallel) | Duration | Tests Required |
-|-------|-----------------|----------|----------------|
-| 1 | T1 | 1h | Interface contract |
-| 2 | T2, T4 | 1.5h | Unit tests |
-| 3 | T3, T5 | 1h | Unit tests |
-| 4 | T6 | 1.5h | Integration tests |
-| **Total** | | **5h** | **All green** |
+**Acceptance Criteria:**
+- [ ] {{criteria}}
+- [ ] All tests pass
+- [ ] **⚠️ NO REGRESSIONS** (run full test suite)
 
-**Critical Path:** T1 → T2 → T3 → T6 = 5h
-**With Parallelism:** ~4h
+**Notes:** {{notes}}
 
 ---
 

package/src/opencode/workflows/dev-story/instructions.md

@@ -363,9 +363,9 @@ Read from `config.yaml → development.methodology`:
   <output>
     | ID | Task | Est | Depends On | Status |
     |----|------|-----|------------|--------|
-    | T1 | ... | 1h | - | ✅ |
-    | T2 | ... | 1.5h | T1 | 🔄 | ← Current
-    | T3 | ... | 1h | T1 | ⬜ | ← Can run parallel with T2
+    | T1 | ... | 5h | - | ✅ |
+    | T2 | ... | 6h | T1 | 🔄 | ← Current
+    | T3 | ... | 5h | T1 | ⬜ | ← Can run parallel with T2
   </output>
 </step>
 ```