@comfanion/workflow 4.38.4-dev.1 → 4.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.4-dev.1",
+  "version": "4.39.0",
   "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.38.4-dev.1",
-  "buildDate": "2026-01-28T14:53:02.088Z",
+  "version": "4.39.0",
+  "buildDate": "2026-01-29T21:27:00.960Z",
   "files": [
     ".gitignore",
     "config.yaml",

package/src/opencode/agents/architect.md

@@ -67,6 +67,7 @@ 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>
@@ -114,8 +115,12 @@ 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!
@@ -130,9 +135,11 @@ 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 about something — ask, don't assume</action>
+    <action>If uncertain — ask, don't assume</action>
   </phase>
 
   <phase name="4. Review">
@@ -142,10 +149,8 @@ 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/pm.md

@@ -64,6 +64,7 @@ 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>
@@ -112,9 +113,12 @@ 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 about something — ask, don't assume</action>
+    <action>If uncertain — ask, don't assume</action>
   </phase>
 
   <phase name="4. Review">
@@ -124,10 +128,9 @@ 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
-    - Create all documents at once without progress updates
+    - For PRD: Skip "Project Classification" section or fill it last (MUST BE FIRST!)
   </never-do>
 </workflow>
 
@@ -162,6 +165,9 @@ 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/gitignore

@@ -9,6 +9,7 @@ vectorizer/node_modules/
 
 # Vectorizer cache (re-indexable, large binary files)
 vectors/
+graph/
 
 # Build artifacts (regenerated by npm run build)
 cli/src/

package/src/opencode/skills/acceptance-criteria/SKILL.md

@@ -1,132 +1,71 @@
 ---
 name: acceptance-criteria
-description: Use when writing testable acceptance criteria in Given/When/Then format
+description: Write testable acceptance criteria in Given/When/Then (Gherkin) format for stories, epics, and features. Use when defining acceptance criteria, writing test scenarios, or when user mentions "acceptance criteria", "Given/When/Then", "Gherkin", "test scenarios", or "AC".
 license: MIT
 compatibility: opencode
 metadata:
-  domain: quality-assurance
+  domain: agile
   format: gherkin
 ---
 
 # Acceptance Criteria Writing Skill
 
-## When to Use
-
-Use this skill when you need to:
-- Write acceptance criteria for FRs in PRD
-- Write AC for epics and stories
-- Define testable behavior specifications
-- Create QA test scenarios
-
-## Given/When/Then Format
-
-### Structure
-
-```gherkin
-Given [precondition/context]
-When [action/trigger]
-Then [expected outcome]
-And [additional outcome]
-```
-
-### Example
-
-```gherkin
-AC1: Successful product creation
-Given a merchant is authenticated
-And the merchant has permission to create products
-When the merchant submits a valid product with:
-  - name: "Test Product"
-  - price: 100.00 UAH
-  - SKU: "TEST-001"
-Then a new product is created with status "pending"
-And the product is assigned a unique ID
-And an event "product.created" is published
+```xml
+<acceptance_criteria>
+  <definition>Write testable AC in Given/When/Then format</definition>
+  
+  <format>
+    <given>Precondition/context</given>
+    <when>Action/trigger</when>
+    <then>Expected outcome</then>
+    <and>Additional outcomes</and>
+  </format>
+  
+  <quality>
+    <testable>Can be verified as pass/fail</testable>
+    <independent>No execution order dependency</independent>
+    <specific>Exact expected behavior</specific>
+    <complete>Covers one complete scenario</complete>
+  </quality>
+  
+  <types>
+    <happy_path>Normal, successful flow</happy_path>
+    <edge_case>Boundary conditions (min/max/empty)</edge_case>
+    <error_case>Invalid input, failures, no side effects</error_case>
+    <security>AuthN/AuthZ, 403 Forbidden</security>
+    <performance>NFR with measurable metrics (e.g., &lt;200ms p95)</performance>
+  </types>
+  
+  <depth_by_artifact>
+    <prd>High-level checklist (Merchant can create product, Validation works)</prd>
+    <epic>Feature-level checklist (All CRUD works, Events published, Coverage >80%)</epic>
+    <story>Detailed Given/When/Then for each scenario (AC1, AC2, AC3...)</story>
+  </depth_by_artifact>
+  
+  <common_mistakes>
+    <vague>Too vague → Define exact behavior</vague>
+    <multiple_scenarios>Split into separate ACs</multiple_scenarios>
+    <implementation>Focus on WHAT, not HOW</implementation>
+    <missing_errors>Always include negative scenarios</missing_errors>
+    <no_metrics>Use measurable outcomes (&lt;200ms, not "fast")</no_metrics>
+  </common_mistakes>
+  
+  <templates>
+    <crud>
+      <create>Given valid data, When POST, Then 201 Created</create>
+      <read>Given existing ID, When GET, Then 200 OK</read>
+      <update>Given existing ID, When PUT, Then 200 OK</update>
+      <delete>Given existing ID, When DELETE, Then 204 No Content</delete>
+    </crud>
+    <validation>Given invalid field, When create/update, Then 400 Bad Request</validation>
+    <authorization>Given user with role, When accessing resource, Then allowed/denied</authorization>
+  </templates>
+</acceptance_criteria>
 ```
 
-## AC Quality Checklist
-
-Each acceptance criterion must be:
-- [ ] **Testable** - Can be verified as pass/fail
-- [ ] **Independent** - Doesn't depend on other AC execution order
-- [ ] **Specific** - Exact expected behavior, not vague
-- [ ] **Complete** - Covers one complete scenario
-
-## Types of Acceptance Criteria
-
-### 1. Happy Path AC
-Normal, successful flow.
-
-```gherkin
-Given valid input
-When action performed
-Then success result
-```
-
-### 2. Edge Case AC
-Boundary conditions.
-
-```gherkin
-Given input at boundary (min/max/empty)
-When action performed
-Then appropriate handling
-```
-
-### 3. Error Case AC
-Invalid input or failure scenarios.
-
-```gherkin
-Given invalid input
-When action attempted
-Then error returned with message
-And no side effects occur
-```
-
-### 4. Security AC
-Authorization and authentication.
-
-```gherkin
-Given user without permission
-When action attempted
-Then access denied (403)
-```
-
-### 5. Performance AC
-Non-functional behavior.
-
-```gherkin
-Given 1000 concurrent requests
-When action performed
-Then response time < 200ms p95
-```
-
-## AC for Different Artifacts
-
-### PRD Level (High-level)
-
-```markdown
-## FR-001: Product Creation
-
-**Acceptance Criteria:**
-- [ ] Merchant can create product with required fields
-- [ ] Product validation rejects invalid data
-- [ ] Created product appears in product list
-- [ ] Product creation event is published
-```
-
-### Epic Level (Feature-level)
-
-```markdown
-## Acceptance Criteria
-
-- [ ] All CRUD operations for products work
-- [ ] Validation rules are enforced
-- [ ] Events are published for all state changes
-- [ ] API follows REST conventions
-- [ ] Unit test coverage > 80%
-```
+---
 
-### Story Level (Detailed)
+## Example: Story-Level AC
 
 ```markdown
 ## Acceptance Criteria
@@ -137,7 +76,7 @@ Then response time < 200ms p95
 **Then** 201 Created returned
 **And** product has generated UUID
 **And** product status is "pending"
-**And** "product.created" event published to Kafka
+**And** "product.created" event published
 
 ### AC2: Reject invalid product data
 **Given** authenticated merchant
@@ -147,66 +86,9 @@ Then response time < 200ms p95
 **And** no product is created
 
 ### AC3: Reject unauthorized access
-**Given** authenticated user without "product:create" permission
+**Given** user without "product:create" permission
 **When** POST /api/v1/products
 **Then** 403 Forbidden returned
 ```
 
-## Common Mistakes to Avoid
-
-1. **Too vague**: "System works correctly" → Define WHAT "correctly" means
-2. **Multiple scenarios in one AC**: Split into separate ACs
-3. **Implementation details**: "Use PostgreSQL" → Focus on WHAT, not HOW
-4. **Missing error cases**: Always include negative scenarios
-5. **No measurable outcome**: "Fast response" → "< 200ms"
-
-## AC Templates
-
-### CRUD Operations
-
-```gherkin
-# Create
-Given valid [entity] data
-When POST /api/v1/[entities]
-Then 201 Created with [entity] details
-
-# Read
-Given existing [entity] with ID
-When GET /api/v1/[entities]/{id}
-Then 200 OK with [entity] details
-
-# Update
-Given existing [entity] with ID
-When PUT /api/v1/[entities]/{id} with updates
-Then 200 OK with updated [entity]
-
-# Delete
-Given existing [entity] with ID
-When DELETE /api/v1/[entities]/{id}
-Then 204 No Content
-And [entity] no longer retrievable
-```
-
-### Validation
-
-```gherkin
-Given [entity] with invalid [field]
-When create/update attempted
-Then 400 Bad Request
-And error identifies [field] and reason
-```
-
-### Authorization
-
-```gherkin
-Given user with role [role]
-When accessing [resource]
-Then [allowed/denied] based on permissions
-```
-
-## Related Skills
-
-- `story-writing` - For complete user stories
-- `epic-writing` - For epic-level AC
-- `prd-writing` - For FR-level AC
-- `integration-testing` - For test implementation
+See `template.md` for full format.