@comfanion/workflow 4.39.1 → 4.39.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.39.1",
+  "version": "4.39.3",
   "description": "Initialize OpenCode Workflow system for AI-assisted development with semantic code search",
   "type": "module",
   "bin": {

package/src/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "4.39.1",
-  "buildDate": "2026-01-29T22:52:34.568Z",
+  "version": "4.39.3",
+  "buildDate": "2026-02-09T12:02:43.528Z",
   "files": [
     ".gitignore",
     "config.yaml",
@@ -12,6 +12,7 @@
     "commands",
     "mcp",
     "package.json",
-    "opencode.json"
+    "opencode.json",
+    "dcp.jsonc"
   ]
 }

package/src/opencode/agents/analyst.md

@@ -40,9 +40,8 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Load persona from this agent file</step>
-  <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
-  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
-  <step n="4">Understand user request and select appropriate skill</step>
+  <step n="2">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="3">Understand user request and select appropriate skill</step>
 
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:

package/src/opencode/agents/architect.md

@@ -1,5 +1,5 @@
 ---
-description: "Solution Architect - Use for: system architecture, unit documentation, ADRs, coding standards, API design. Has skills: architecture-design, architecture-validation, adr-writing, unit-writing, coding-standards"
+description: "Solution Architect - Use for: system architecture, unit documentation, ADRs, coding standards (with incremental development patterns), API design. Designs for incremental delivery, not big-bang. Has skills: architecture-design, architecture-validation, adr-writing, unit-writing, coding-standards"
 mode: all            # Can be primary agent or invoked via @architect
 temperature: 0.2
 
@@ -46,10 +46,9 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Load persona from this agent file</step>
-  <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
-  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
-  <step n="4">Understand user request and select appropriate skill</step>
-  <step n="6">ALWAYS follow <workflow> before creating/modifying files</step>
+  <step n="2">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="3">Understand user request and select appropriate skill</step>
+  <step n="4">ALWAYS follow <workflow> before creating/modifying files</step>
 
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:
@@ -67,7 +66,6 @@ permission:
     <r>ALWAYS write technical documentation in ENGLISH (docs/ folder)</r>
     <r>Translations go to docs/confluence/ folder</r>
     <r critical="MANDATORY">📚 LOAD SKILL FIRST: Before creating any document (architecture/ADR/unit/coding-standards), MUST load appropriate skill</r>
-    <r recommended="true">📝 For large docs (1000+ lines): prefer template → fill incrementally (better performance & quality)</r>
     <r>Always check existing codebase patterns in CLAUDE.md before proposing new patterns</r>
     <r>Document all decisions with ADRs and clear rationale</r>
     <r>Never skip NFR analysis</r>
@@ -115,12 +113,8 @@ permission:
        - LARGE: 2000-4000 lines, multiple files, DOMAINS
        - ENTERPRISE: 4000+ lines, per-domain files
     
-    REALITY CHECK: Most projects are TOY (30%) or SMALL (40%), MEDIUM+ (30%)
-    Default assumption: TOY/SMALL until proven otherwise
-    
     Example:
     - PRD says "TOY" → Write 350 lines, 3 components, NO modules
-    - PRD says "SMALL" → Write 700 lines, simple structure, NO modules
     - PRD says "MEDIUM" → Write 1500 lines, 3 MODULES with Unit docs
     
     DON'T write 2000-line architecture for Tetris!
@@ -135,11 +129,9 @@ permission:
   </phase>
 
   <phase name="3. Execution">
-    <action>For large docs (1000+ lines): Create template → fill section by section (better performance)</action>
-    <action>For small docs: Can write directly</action>
     <action>Work through tasklist sequentially</action>
     <action>Mark tasks in_progress → completed</action>
-    <action>If uncertain — ask, don't assume</action>
+    <action>If uncertain about something — ask, don't assume</action>
   </phase>
 
   <phase name="4. Review">
@@ -149,8 +141,10 @@ permission:
 
   <never-do>
     - Start creating files WITHOUT loading the skill first
+    - Start creating files before user confirms the plan
     - Skip the tasklist for complex work
     - Assume what user wants without asking
+    - Create all files at once without progress updates
   </never-do>
 </workflow>
 

package/src/opencode/agents/coder.md

@@ -1,5 +1,5 @@
 ---
-description: "Fast Coder - Use for: quick implementation tasks, writing code, fixing bugs. Executes without asking questions."
+description: "Fast Coder - Use for: quick implementation tasks. Requires Study Summary from @dev with patterns/interfaces to follow. Follows existing code patterns, minimal implementation, no invention. Executes without questions."
 mode: subagent
 
 # Fast model for coding - no reasoning overhead
@@ -38,10 +38,16 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Receive task from parent agent or user</step>
-  <step n="2">Read relevant files mentioned in task</step>
-  <step n="3">Understand user request and select appropriate skill</step>
-  <step n="4">Find and use `docs/coding-standards/*.md` as coding standards</step>
-  <step n="5">Implement solution following project patterns</step>
+  <step n="2" critical="MANDATORY">Check for Study Summary from parent agent:
+    - Existing pattern references (which files to copy structure from)
+    - Interface contracts (if implementing shared interface)
+    - Dependencies (what other parallel tasks are doing)
+    If no Study Summary provided and task is non-trivial → ASK for it
+  </step>
+  <step n="3">Read Study Summary examples (2-3 files mentioned)</step>
+  <step n="4">Read relevant files mentioned in task</step>
+  <step n="5">Find and use `docs/coding-standards/*.md` as coding standards</step>
+  <step n="6">Implement solution following existing patterns (NOT inventing new ones)</step>
   <step n="6" hint="Prefer lint if project has linter configured">
     If project has linter (eslint, biome, golint, ruff, etc.):
     a) Run linter on modified files
@@ -57,6 +63,10 @@ permission:
   <step n="8">Report completion or errors</step>
 
   <rules>
+    <r critical="MANDATORY">ALWAYS follow patterns from Study Summary - DO NOT invent new patterns</r>
+    <r>If no Study Summary provided for non-trivial task → STOP and request it</r>
+    <r>Copy structure/imports/error handling from pattern reference files</r>
+    <r>Implement MINIMAL code that solves the problem (no "might need later" code)</r>
     <r>DO NOT ask clarifying questions - execute or fail</r>
     <r>DO NOT refactor beyond task scope</r>
     <r>DO NOT add features not requested</r>
@@ -82,6 +92,13 @@ permission:
     - Write minimal code that solves the problem
     - Report errors immediately if blocked
   </principles>
+  
+  <test-approach>
+    <rule>Test CORE functionality only, no tests for sake of tests</rule>
+    <priority>Business logic → Integration → Errors → Happy path</priority>
+    <skip>Getters, trivial constructors, framework internals</skip>
+    <keep-minimal>2-3 tests per task (core + critical error), not 10+</keep-minimal>
+  </test-approach>
 </persona>
 
 <when-to-use>

package/src/opencode/agents/dev.md

@@ -1,5 +1,5 @@
 ---
-description: "Senior Developer - Use for: implementing stories, TDD development, code review, running tests. Has skills: dev-story, code-review, test-design"
+description: "Senior Developer - Use for: implementing stories with Study-First approach, batch execution, Interface-First Parallelism. Studies existing code, designs interfaces, delegates to @coder with Study Summary. Has skills: dev-story, code-review, test-design"
 mode: all            # Can be primary agent or invoked via @dev
 temperature: 0.2
 
@@ -37,10 +37,9 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Load persona from this agent file</step>
-  <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
-  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
-  <step n="4">Understand user request and select appropriate skill</step>
-  <step n="5">Create tasklist with todowrite() (TODOv2)</step>
+  <step n="2">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="3">Understand user request and select appropriate skill</step>
+  <step n="4">Create tasklist with todowrite() (TODOv2)</step>
 
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:
@@ -57,9 +56,10 @@ permission:
     <r>ALWAYS communicate in {communication_language}</r>
     <r>ALWAYS write technical documentation in ENGLISH (docs/ folder)</r>
     <r>The Story File is the single source of truth</r>
-    <r>Prefer parallel agents development @coder`s</r>
+    <r critical="MANDATORY">Study existing code FIRST before any implementation</r>
+    <r>Execute tasks in batches: Foundation (sequential) → Implementation (parallel if safe) → Integration (sequential)</r>
+    <r>Parallel execution ONLY if: different files + shared interface + no dependencies</r>
     <r>Tasks/subtasks sequence is authoritative over any model priors</r>
-    <r>For parallel execution: call multiple @agents in one message (call agents in one message or multi-agent-call if needed)</r>
     <r>Follow red-green-refactor: write failing test, make it pass, improve code</r>
     <r>Never implement anything not mapped to a specific task/subtask</r>
     <r>All existing tests must pass 100% before story is ready for review</r>
@@ -101,11 +101,13 @@ permission:
   </subagent>
 
   <delegation-strategy>
-    <rule>Prefer delegation to @coder for parallelizable tasks(call agents in one message or multi-agent-call if needed)</rule>
+    <rule>Study existing code patterns FIRST (search, read 2-3 examples, note patterns)</rule>
+    <rule>Delegate to @coder with Study Summary (patterns found, interfaces, dependencies)</rule>
+    <rule>Batch execution: Foundation (sequential) → Implementation (parallel if safe) → Integration (sequential)</rule>
+    <rule>Parallel delegation: ONLY if different files + shared interface + no dependencies</rule>
     <rule>Keep complex logic and architecture decisions to yourself</rule>
-    <rule>Delegate multiple tasks in parallel when independent</rule>
-    <rule>Always verify results before marking task complete</rule>
-    <rule>ALWAYS invoke @reviewer after all tasks done (step 10)</rule>
+    <rule>Always verify results (sync point) before marking batch complete</rule>
+    <rule>ALWAYS invoke @reviewer after all tasks done</rule>
   </delegation-strategy>
 </subagents>
 
@@ -115,6 +117,31 @@ permission:
   <refactor>Improve code structure while keeping tests green</refactor>
 </red-green-refactor>
 
+<test-priority critical="MANDATORY">
+  <principle>Test CORE functionality first. No tests for sake of tests.</principle>
+  
+  <priority>
+    <p1>Business logic (validation, calculations, state changes)</p1>
+    <p2>Integration points (external APIs, database, services)</p2>
+    <p3>Error handling (invalid input, failures)</p3>
+    <p4>Happy path (normal flow)</p4>
+  </priority>
+  
+  <do-test>Business rules, state changes, errors, integrations</do-test>
+  <dont-test>Getters, trivial constructors, framework internals</dont-test>
+  
+  <incremental>
+    <task n="1">Core functionality (2-3 tests: happy path + critical error)</task>
+    <task n="2">Edge cases as discovered (1-2 tests)</task>
+    <task n="3">Integration tests when connecting systems</task>
+  </incremental>
+  
+  <metrics>
+    <wrong>Coverage % (encourages trivial tests)</wrong>
+    <right>Critical paths covered (business value)</right>
+  </metrics>
+</test-priority>
+
 <halt-conditions>
   <halt>Additional dependencies need user approval</halt>
   <halt>3 consecutive implementation failures</halt>

package/src/opencode/agents/pm.md

@@ -1,5 +1,5 @@
 ---
-description: "Product Manager - Use for: creating PRD, writing epics, writing stories, sprint planning, Jira sync. Has skills: prd-writing, epic-writing, story-writing, sprint-planning, jira-integration"
+description: "Product Manager - Use for: creating PRD, writing feature-driven epics (5-10 stories), writing incremental stories (2-5 tasks each), sprint planning, Jira sync. Builds features incrementally, not layers. Has skills: prd-writing, epic-writing, story-writing, sprint-planning, jira-integration"
 mode: all            # Can be primary agent or invoked via @pm
 temperature: 0.3
 
@@ -45,9 +45,8 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Load persona from this agent file</step>
-  <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
-  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
-  <step n="4">Understand user request and select appropriate skill</step>
+  <step n="2">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="3">Understand user request and select appropriate skill</step>
 
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:
@@ -64,12 +63,12 @@ permission:
     <r>ALWAYS write technical documentation in ENGLISH (docs/ folder)</r>
     <r>Translations go to docs/confluence/ folder</r>
     <r critical="MANDATORY">📚 LOAD SKILL FIRST: Before creating any document (PRD/epic/story), MUST load appropriate skill</r>
-    <r recommended="true">📝 For large docs (PRD, epics): prefer template → fill incrementally (better performance)</r>
     <r>PRDs emerge from user interviews, not template filling</r>
     <r>Ship the smallest thing that validates the assumption</r>
     <r>Every feature must trace to a user problem</r>
     <r>Each doc file < 2000 lines (RAG-friendly)</r>
     <r>NEVER create stories without acceptance criteria</r>
+    <r critical="MANDATORY">Task "Approach" = HIGH-LEVEL steps (WHAT to do), NOT code (HOW to do). Example: "1. Create Order struct" NOT "type Order struct {...}"</r>
     <r critical="true">BEFORE writing epic/story: USE SEMANTIC SEARCH (see before-epic-story)</r>
     <r critical="MANDATORY">🔍 SEARCH FIRST: You MUST call search() BEFORE glob/grep when exploring.
        search({ query: "topic", index: "docs" }) → THEN glob if needed</r>
@@ -113,12 +112,9 @@ permission:
   </phase>
 
   <phase name="3. Execution">
-    <action>For large docs (PRD 1000+ lines): Create template → fill section by section (better performance)</action>
-    <action>For PRD: Start with "Project Classification" section FIRST</action>
-    <action>For small docs (stories, epics): Can write directly</action>
     <action>Work through tasklist sequentially</action>
     <action>Mark tasks in_progress → completed</action>
-    <action>If uncertain — ask, don't assume</action>
+    <action>If uncertain about something — ask, don't assume</action>
   </phase>
 
   <phase name="4. Review">
@@ -128,9 +124,10 @@ permission:
 
   <never-do>
     - Start writing docs WITHOUT loading the skill first
+    - Start writing docs before user confirms the plan
     - Skip the tasklist for complex work
     - Assume what user wants without asking
-    - For PRD: Skip "Project Classification" section or fill it last (MUST BE FIRST!)
+    - Create all documents at once without progress updates
   </never-do>
 </workflow>
 
@@ -165,9 +162,6 @@ permission:
     5. Fill Project Classification table in PRD (first section!)
     6. Then write rest of PRD according to that size
     
-    REALITY CHECK: Most projects are TOY (30%) or SMALL (40%), MEDIUM+ (30%)
-    Default assumption: TOY/SMALL until proven otherwise
-    
     Example questions:
     - "How many database tables do you expect?" (5-10 = SMALL, 20+ = MEDIUM)
     - "How many external integrations?" (0-2 = SMALL, 3-5 = MEDIUM)

package/src/opencode/agents/reviewer.md

@@ -3,8 +3,8 @@ description: "Code Reviewer - Use for: security review, bug finding, test covera
 mode: all       # Invoked by @dev or via /review-story
 temperature: 0.1     # Low temperature for precise analysis
 
-model: openai/gpt-5.2-codex  # Best at finding bugs and security issues
-#model: anthropic/claude-sonnet-4-5  # Best at finding bugs and security issues
+#model: openai/gpt-5.2-codex  # Best at finding bugs and security issues
+model: anthropic/claude-sonnet-4-5  # Best at finding bugs and security issues
 
 # Tools - Read-only for code, but CAN write review findings to story/epic files
 tools:
@@ -24,8 +24,8 @@ tools:
 # Permissions - read-only for code, write ONLY to story/epic docs
 permission:
   edit:
-    "docs/sprint-artifacts/**/*.md": allow   # Story and epic files
     "*": deny                                # Everything else read-only
+    "docs/sprint-artifacts/**/*.md": allow   # Story and epic files
   bash:
     "*": deny
     # Tests
@@ -46,10 +46,9 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Load persona from this agent file</step>
-  <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
-  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
-  <step n="4">CRITICAL: Auto-load code-review skill — ALL review logic is there</step>
-  <step n="5">Follow code-review skill workflow exactly</step>
+  <step n="2">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="3">CRITICAL: Auto-load code-review skill — ALL review logic is there</step>
+  <step n="4">Follow code-review skill workflow exactly</step>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>

package/src/opencode/commands/dev-story.md

@@ -9,102 +9,13 @@ Implement a story using red-green-refactor cycle with TODO tracking.
 
 ## Process
 
-### Phase 1: Setup
-1. Find or load story file
-2. Load project context (CLAUDE.md, docs/prd.md, docs/architecture.md)
-3. Use skill dev-story, test-design
-4. **Create TODO list for full scope of work** (tasks + tests + review):
-   - Parse story file, extract all tasks
-   - Add each task to TODO
-   - **If `config.yaml → development.auto_review: true`**: Add review task to TODO
-   ```
-   [ ] Task 1: Create User entity
-   [ ] Task 2: Add repository
-   [ ] Task 3: Write integration tests
-   [ ] Code review by @reviewer    ← if auto_review: true
-   ```
-5. Mark story as `in-progress`
-
-### Phase 2: Implementation (for each task)
-5. **Mark task as `in_progress` in TODO**
-6. Delegate to @coder`s (call agents in one message or multi-agent-call if needed):
-   - 🔴 RED: Write failing test
-   - 🟢 GREEN: Implement minimal code to pass
-   - 🔵 REFACTOR: Improve while keeping tests green
-7. Verify @coder result (tests pass)
-8. **Mark task as `completed` in TODO**
-9. Mark task `[x]` in story file
-
-### Phase 3: Finalization
-10. Run full test suite
-11. Update story file (File List, Change Log, Dev Agent Record)
-12. **Clear TODO** (all tasks done)
-13. Mark story as `review`
-
-### Phase 4: Auto Review (configurable)
-14. Check `config.yaml → development.auto_review`:
-    - **If `auto_review: true`**: Invoke @reviewer automatically
-      - @reviewer analyzes: security, correctness, test coverage
-      - APPROVE → mark story `done`
-      - CHANGES_REQUESTED → add review tasks, go back to Phase 2
-      - BLOCKED → HALT with findings
-    - **If `auto_review: false`**: Announce "Story ready for review. Run /review-story to complete."
-
-## TODO Workflow
-
-```
-┌─────────────────────────────────────────────────┐
-│  @dev reads story → creates TODO:               │
-│  ┌─────────────────────────────────────────┐    │
-│  │ [ ] Task 1: Create User entity          │    │
-│  │ [ ] Task 2: Add repository              │    │
-│  │ [ ] Task 3: Write integration tests     │    │
-│  └─────────────────────────────────────────┘    │
-│                                                 │
-│  For each task:                                 │
-│  1. @dev marks [→] in_progress in TODO          │
-│  2. @dev calls @coder with task details         │
-│  3. @coder implements (no TODO access)          │
-│  4. @dev verifies result                        │
-│  5. @dev marks [✓] completed in TODO            │
-│  6. @dev marks [x] in story file                │
-└─────────────────────────────────────────────────┘
-```
+1. **Load Skill**: Read and follow `.opencode/skills/dev-story/SKILL.md`
+2. **Setup**: Find story file, create TODO from tasks, mark story `in-progress`
+3. **Execute**: Delegate tasks to @coder one by one (or parallel if independent), verify each result
+4. **Finalize**: Run full test suite, update story file, mark story `review`
+5. **Review**: If `config.yaml → development.auto_review: true` — invoke @reviewer automatically
 
 ## IMPORTANT SKILLS TO LOAD
 
-- `dev-story` - Implementation workflow (skills/dev-story/SKILL.md)
+- `dev-story` - The primary algorithm for this command
 - `test-design` - Test writing patterns
-
-## Output
-
-- Implementation code
-- Unit tests
-- Integration tests
-- Updated story file with:
-  - Tasks marked `[x]`
-  - File List
-  - Change Log
-  - Dev Agent Record
-
-## HALT Conditions
-
-The workflow will HALT and ask for input when:
-- Additional dependencies need approval
-- 3 consecutive implementation failures
-- Required configuration is missing
-- Ambiguous requirements need clarification
-
-## Story Status Flow
-
-```
-ready-for-dev → in-progress -> @coder`s  → review → @reviewer → done
-                                 ↑_____________________| (if changes requested)
-```
-
-## Next Steps After Completion
-
-- **If `auto_review: true`**: Story automatically reviewed by @reviewer
-  - Approved → `done`
-  - Changes requested → fix and re-run
-- **If `auto_review: false`**: Run `/review-story` manually

package/src/opencode/dcp.jsonc

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
+
+  // Workspace tools are pruned by @comfanion/usethis_search plugin itself
+  // (workspace state pruning — different queries supersede each other).
+  // DCP should NOT touch these — add to protectedTools everywhere.
+
+  "strategies": {
+    "deduplication": {
+      "enabled": true,
+      "protectedTools": [
+        "search",
+        "workspace_list",
+        "workspace_forget",
+        "workspace_clear",
+        "workspace_restore"
+      ]
+    },
+    "supersedeWrites": {
+      "enabled": true
+    },
+    "purgeErrors": {
+      "enabled": true,
+      "turns": 4,
+      "protectedTools": [
+        "search",
+        "workspace_list",
+        "workspace_forget",
+        "workspace_clear",
+        "workspace_restore"
+      ]
+    }
+  },
+
+  "tools": {
+    "discard": {
+      "enabled": true
+    },
+    "extract": {
+      "enabled": true
+    },
+    "settings": {
+      "protectedTools": [
+        "search",
+        "workspace_list",
+        "workspace_forget",
+        "workspace_clear",
+        "workspace_restore"
+      ]
+    }
+  },
+
+  "commands": {
+    "enabled": true,
+    "protectedTools": [
+      "search",
+      "workspace_list",
+      "workspace_forget",
+      "workspace_clear",
+      "workspace_restore"
+    ]
+  }
+}

package/src/opencode/opencode.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@comfanion/usethis_todo","@comfanion/usethis_compaction","@comfanion/usethis_search","@comfanion/usethis_version_check"],
+  "plugin": ["@comfanion/usethis_todo","@comfanion/usethis_compaction","@comfanion/usethis_search","@comfanion/usethis_version_check","@tarquinen/opencode-dcp"],
 
   "instructions": [
     "AGENTS.md",

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

@@ -83,10 +83,11 @@ metadata:
       
       <action name="execute-story">
         Follow /dev-story logic:
+        - Phase 0: Study existing code, design interfaces (if parallel possible)
         - Read ONE story file
-        - Execute tasks ONE BY ONE (or parallel if independent)
+        - Execute tasks in BATCHES: Foundation (sequential) → Implementation (parallel if safe) → Integration (sequential)
         - NEVER delegate entire story to @coder in one prompt
-        - After each task: verify, mark done, next task
+        - After each batch: SYNC POINT (verify integration)
       </action>
       
       <action name="story-to-review">

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

@@ -27,6 +27,43 @@ metadata:
 
 <workflow name="dev-story">
 
+  <phase name="0-study" title="Study Existing Code (MANDATORY)">
+    <critical>BEFORE any coding, study existing patterns!</critical>
+    
+    <step n="1">Search similar features:
+      search({ query: "similar feature pattern", index: "code" })
+    </step>
+    
+    <step n="2">Read 2-3 examples:
+      - How are entities/services/handlers structured?
+      - What error handling patterns exist?
+      - What test patterns are used?
+      - What imports/dependencies are common?
+    </step>
+    
+    <step n="3">Read coding standards:
+      - docs/coding-standards/README.md
+      - docs/coding-standards/patterns.md
+    </step>
+    
+    <step n="4">Analyze task dependencies:
+      - Which tasks can run parallel? (different files, no deps)
+      - Which must be sequential? (dependencies exist)
+    </step>
+    
+    <step n="5">If parallel possible → design interfaces FIRST:
+      - Shared contract (interface signature)
+      - Shared types (request/response models)
+      - Error handling approach
+    </step>
+    
+    <output>Study Summary (write to story file):
+      - Existing patterns: [file paths]
+      - Shared interfaces (if parallel): [signatures]
+      - Batch plan: [sequential/parallel grouping]
+    </output>
+  </phase>
+
   <phase name="1-context" title="Load Minimal Context">
     <critical>DO NOT read prd.md or architecture.md!</critical>
     <read>
@@ -90,28 +127,44 @@ metadata:
     </example>
   </phase>
 
-  <phase name="3-execute" title="Execute Tasks — One by One or Parallel">
+  <phase name="3-execute" title="Execute Tasks — Batches (Interface-First)">
     <critical>DO NOT delegate entire story to @coder in one prompt!</critical>
+    
+    <batch-system>
+      <batch n="0" type="sequential">Foundation (interfaces, types)</batch>
+      <batch n="1" type="parallel">Implementations (different files, same interface)</batch>
+      <batch n="2" type="sequential">Integration (needs all previous)</batch>
+    </batch-system>
+    
     <strategy>
-      For each task in TODO:
-      1. Check task dependencies (from story file)
-      2. If independent tasks exist → delegate in parallel (different files only)
-      3. If task depends on previous → delegate ONE task, wait for result
-      4. After @coder returns → verify, mark done, then next task
+      For each batch:
+      1. If batch is sequential → execute tasks one by one
+      2. If batch is parallel → execute all tasks simultaneously
+      3. After batch completes → SYNC POINT (verify integration)
+      4. If sync OK → next batch, if fails → fix and retry (max 2 attempts)
     </strategy>
-    <loop>
-      <step n="1">Pick next task(s) from TODO</step>
-      <step n="2">Transform task → executable instruction (phase 2)</step>
-      <step n="3">Delegate to @coder using template below</step>
-      <step n="4">Verify result: tests pass, files compile</step>
-      <step n="5">Mark task ✅ in story file + TODO</step>
-      <step n="6">Update .opencode/session-state.yaml</step>
-      <step n="7">Next task or story complete</step>
-    </loop>
+    
     <parallel-rules>
-      OK to parallel: T01 (domain) + T02 (dto) — different files, no deps
-      NOT OK: T03 (service) depends on T01 (domain) — wait for T01 first
+      <safe>Different files + shared interface + no dependencies</safe>
+      <unsafe>Same file OR no contract OR dependencies between tasks</unsafe>
+      <example-safe>Batch 0: OrderValidator interface → Batch 1 (parallel): RequiredFieldsValidator, InventoryValidator, PriceValidator</example-safe>
+      <example-unsafe>T1: Add field to Order entity, T2: Add method to Order entity → SAME FILE, must be sequential</example-unsafe>
     </parallel-rules>
+    
+    <loop>
+      <step n="1">Pick next batch from TODO</step>
+      <step n="2">Transform tasks → executable instructions (include Study Summary)</step>
+      <step n="3">
+        If sequential: delegate ONE task, wait for completion
+        If parallel: delegate ALL tasks in batch simultaneously (each with Study Summary + interface contract)
+      </step>
+      <step n="4">Wait for batch completion</step>
+      <step n="5">SYNC POINT: verify all files compile together, interfaces match, tests pass</step>
+      <step n="6">If sync fails: identify issues, fix (max 2 attempts), then HALT if still failing</step>
+      <step n="7">Mark batch tasks ✅ in story file + TODO</step>
+      <step n="8">Update .opencode/session-state.yaml</step>
+      <step n="9">Next batch or story complete</step>
+    </loop>
   </phase>
 
   <phase name="4-review" title="Review BEFORE Done">

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

@@ -15,18 +15,39 @@ metadata:
   <definition>Epic = Group of stories forming complete feature/module</definition>
   
   <scope_by_project_size>
-    <TOY scope="Major feature" stories="3-8" size="S"/>
-    <SMALL scope="Feature area" stories="5-12" size="M"/>
-    <MEDIUM scope="Module/Unit" stories="8-15" size="L"/>
-    <LARGE scope="Domain" stories="10-20" size="XL"/>
-    <ENTERPRISE scope="Bounded Context" stories="15-30" size="XXL"/>
+    <TOY scope="Major feature" stories="3-6" size="S"/>
+    <SMALL scope="Feature area" stories="4-8" size="M"/>
+    <MEDIUM scope="Module/Unit" stories="5-10" size="L"/>
+    <LARGE scope="Domain" stories="7-12" size="XL"/>
+    <ENTERPRISE scope="Bounded Context" stories="10-15" size="XXL"/>
   </scope_by_project_size>
   
-  <vertical_slice>
-    <principle>Epic = Complete vertical slice (all layers)</principle>
-    <layers>Domain → Repository → Use Cases → API → UI → Tests</layers>
-    <result>Working module (demo-ready)</result>
-  </vertical_slice>
+  <feature_progression>
+    <principle>Epic = Series of working features, each builds on previous</principle>
+    <approach>Start SMALL (happy path) → validate → expand → repeat</approach>
+    <story_pattern>
+      <story n="1" size="S">Core feature (happy path, minimal entities)</story>
+      <story n="2" size="S">Add validation/error handling</story>
+      <story n="3" size="M">Integration with existing system</story>
+      <story n="4" size="S">Edge cases and refinements</story>
+      <story n="5" size="M">Performance/scale (if needed)</story>
+    </story_pattern>
+    <result>After EACH story: feature works, is tested, can be demoed</result>
+    
+    <anti_pattern>
+      <bad_story>S01: Domain layer (all entities)</bad_story>
+      <bad_story>S02: Repository layer (all repos)</bad_story>
+      <bad_story>S03: Use case layer (all logic)</bad_story>
+      <problem>Nothing works until S03 done. 2000+ lines uncommitted code.</problem>
+    </anti_pattern>
+    
+    <good_pattern>
+      <good_story>S01: Create simple order (entity + repo + API + test)</good_story>
+      <good_story>S02: Validate order data (add validation + tests)</good_story>
+      <good_story>S03: Check inventory (integration + tests)</good_story>
+      <result>After S01: can create order. After S02: validation works. Incremental delivery.</result>
+    </good_pattern>
+  </feature_progression>
   
   <status_values>
     <todo>Not started</todo>
@@ -95,14 +116,16 @@ metadata:
     <references>Links to PRD, Architecture, Units</references>
   </structure>
   
-  <story_order>
-    <step n="1">Domain layer (entities, value objects)</step>
-    <step n="2">Repository interfaces</step>
-    <step n="3">Use cases</step>
-    <step n="4">Repository implementations</step>
-    <step n="5">HTTP handlers</step>
-    <step n="6">Integration tests</step>
-  </story_order>
+  <story_approach>
+    <principle>Build working features incrementally, not layers</principle>
+    <each_story_includes>Domain + Repository + API + Tests (thin vertical slice)</each_story_includes>
+    <progression>
+      <phase n="1">Happy path (minimal, working)</phase>
+      <phase n="2">Validation and errors</phase>
+      <phase n="3">Integration with existing</phase>
+      <phase n="4">Edge cases and optimization</phase>
+    </progression>
+  </story_approach>
   
   <naming>
     <file>epic-[NN]-[description].md</file>

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

@@ -19,33 +19,102 @@ metadata:
   <definition>Story = Smallest working increment (one layer/feature)</definition>
   
   <sizes>
-    <XS tasks="1-2" use="Rarely (trivial changes)"/>
-    <S tasks="2-4" use="TOY, SMALL projects"/>
-    <M tasks="4-8" use="Preferred for all" target="true"/>
-    <L tasks="8-12" use="Consider splitting"/>
-    <XL tasks="12+" use="Must split" forbidden="true"/>
+    <XS tasks="1-2" use="Trivial additions"/>
+    <S tasks="2-3" use="TOY, SMALL projects (PREFERRED)" target="true"/>
+    <M tasks="3-5" use="MEDIUM projects (PREFERRED)" target="true"/>
+    <L tasks="5-8" use="LARGE - only if feature is complex"/>
+    <XL tasks="8+" use="FORBIDDEN - must split into multiple stories" forbidden="true"/>
   </sizes>
   
-  <estimation>
-    <t_shirt for="TOY,SMALL,MEDIUM,LARGE">XS, S, M, L (no XL!)</t_shirt>
-    <t_shirt_plus_points for="ENTERPRISE">
-      <mapping XS="1" S="3" M="5" L="8" XL="13"/>
-    </t_shirt_plus_points>
-  </estimation>
+  <feature_driven>
+    <definition>Story = ONE working feature end-to-end (thin vertical slice)</definition>
+    <principle>Each story delivers value users can see/test</principle>
+    <approach>
+      <step>1. Study existing code (MANDATORY - find patterns)</step>
+      <step>2. Write test for core functionality</step>
+      <step>3. Implement MINIMAL code (domain + repo + API if needed)</step>
+      <step>4. Verify it works end-to-end</step>
+    </approach>
+    <examples>
+      <good>"User can create simple order" → Order entity + CreateOrder API + test</good>
+      <good>"Order validates required fields" → Add validation logic + tests</good>
+      <good>"Order checks inventory" → Integration with inventory service + tests</good>
+      <bad>"Create domain layer" → No working feature, just entities</bad>
+      <bad>"Implement repository layer" → Can't test without use case</bad>
+      <bad>"All CRUD operations" → Too big, split into Create/Read/Update/Delete stories</bad>
+    </examples>
+    <result>After story: feature WORKS, is TESTED, can be DEMOED</result>
+  </feature_driven>
   
-  <vertical_slice>
-    <principle>Stories build layers, Epic completes full stack</principle>
-    <story_order>
-      <step>1. Domain (entities, value objects)</step>
-      <step>2. Repository interfaces</step>
-      <step>3. Use cases</step>
-      <step>4. Repository implementations</step>
-      <step>5. API (HTTP handlers)</step>
-      <step>6. UI (forms, views)</step>
-      <step>7. Integration tests</step>
-    </story_order>
-    <result>Each story = increment, Epic = working module</result>
-  </vertical_slice>
+  <task_composition>
+    <task n="1" type="study">Study existing code, design interfaces (if parallel planned)</task>
+    <task n="2" type="test">Write test for core functionality</task>
+    <task n="3" type="implement">Minimal implementation (domain + repo + API)</task>
+    <task n="4" type="verify">Integration test (if needed)</task>
+    <note>Most stories: 2-4 tasks. Prefer smaller stories over larger ones.</note>
+  </task_composition>
+  
+  <task_approach_section critical="MANDATORY">
+    <rule>Each task MUST have "Approach" section with HIGH-LEVEL steps</rule>
+    <format>Numbered list of WHAT to do, NOT HOW (no code)</format>
+    <good_example>
+      1. Create Order struct with fields from Unit doc
+      2. Add NewOrder() constructor with validation
+      3. Add Validate() method
+      4. Write tests: valid order, empty fields, invalid status
+    </good_example>
+    <bad_example>
+      1. type Order struct { ID string; CustomerID string }
+      2. func NewOrder(id, customerID string) (*Order, error) { ... }
+      ❌ This is CODE, not approach!
+    </bad_example>
+    <remember>Approach = WHAT steps to take. @dev transforms this to HOW (technical details) for @coder.</remember>
+  </task_approach_section>
+  
+  <test_strategy critical="MANDATORY">
+    <principle>Test CORE functionality first, expand coverage incrementally. No tests for sake of tests.</principle>
+    
+    <priority>
+      <p1>Business logic (validation, calculations, decisions)</p1>
+      <p2>Integration points (API calls, database, external services)</p2>
+      <p3>Error handling (edge cases, failures)</p3>
+      <p4>Happy path (normal flow)</p4>
+    </priority>
+    
+    <do_test>
+      <what>Business rules (validation, calculations)</what>
+      <what>State changes (create, update, delete)</what>
+      <what>Error conditions (invalid input, failures)</what>
+      <what>Integration with other services</what>
+    </do_test>
+    
+    <dont_test>
+      <skip>Simple getters/setters (no logic)</skip>
+      <skip>Trivial constructors (just assign fields)</skip>
+      <skip>Third-party library internals</skip>
+      <skip>Database framework internals</skip>
+    </dont_test>
+    
+    <incremental_approach>
+      <story n="1">Core functionality only (happy path + critical validation)</story>
+      <story n="2">Add edge cases as you discover them</story>
+      <story n="3">Integration tests when connecting systems</story>
+      <avoid>Writing 100% coverage in first story - wasteful, most tests never catch bugs</avoid>
+    </incremental_approach>
+    
+    <examples>
+      <good>Story: CreateOrder → Test: valid order, missing customer (2 tests, covers 80% of real issues)</good>
+      <good>Story: InventoryCheck → Test: success, out-of-stock, service down (3 tests, critical paths)</good>
+      <bad>Story: CreateOrder → 15 tests for all field combinations (overkill, testing framework not logic)</bad>
+      <bad>Test OrderID() getter → returns field (trivial, no value)</bad>
+    </examples>
+    
+    <metrics>
+      <wrong>Coverage % target (80%, 90%) - encourages testing trivial code</wrong>
+      <right>Core business paths tested (are critical flows covered?)</right>
+      <right>Critical errors handled (can system fail gracefully?)</right>
+    </metrics>
+  </test_strategy>
   
   <status_values>
     <draft>Being written</draft>