@comfanion/workflow 4.36.64 → 4.36.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.36.64",
+  "version": "4.36.66",
   "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.36.64",
-  "buildDate": "2026-01-26T02:48:11.947Z",
+  "version": "4.36.66",
+  "buildDate": "2026-01-26T20:05:21.512Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/FLOW.yaml

@@ -2,7 +2,7 @@
 # This file defines the complete workflow pipeline for AI-assisted development
 
 name: documentation-workflow
-version: "3.0"
+version: "3.1"
 description: |
   End-to-end workflow from research to implementation and review.
   
@@ -12,6 +12,11 @@ description: |
   - Skills: Knowledge (HOW to do things)
   
   Config: .opencode/config.yaml
+  
+  Project Size Classification:
+  - Defined in PRD (first section, mandatory)
+  - Agents read PRD to understand project size
+  - Size determines depth of all artifacts (PRD, Architecture, Epics, Stories)
 
 # =============================================================================
 # CONFIGURATION

package/src/opencode/agents/analyst.md

@@ -28,7 +28,7 @@ tools:
 permission:
   edit: allow        # Can write documentation
   bash:
-    "*": ask
+    "*": allow
     "ls *": allow
     "cat *": allow
     "tree *": allow

package/src/opencode/agents/dev.md

@@ -4,9 +4,8 @@ mode: all            # Can be primary agent or invoked via @dev
 temperature: 0.2
 
 model: anthropic/claude-opus-4-5  # Strong
-#model: z.ai/glm-4.7  # Better for orchestration as for me but slow (can broke) 
-#model: openai/gpt-5.2-codex
-#model: anthropic/claude-opus-4-5 
+#model: z.ai/glm-4.7  # Can break
+#model: openai/gpt-5.2-codex 
 
 # Tools - FULL ACCESS for implementation
 tools:
@@ -232,7 +231,7 @@ permission:
 **What I Don't Do:**
 - Define product scope (→ @pm)
 - Make architecture decisions (→ @architect)
-- Implement without a story
+- Implement without a story-зж
 - Skip tests or lie about test status
 
 **Red-Green-Refactor:** 🔴 Write failing test → 🟢 Minimal code to pass → 🔵 Refactor

package/src/opencode/agents/pm.md

@@ -129,11 +129,21 @@ permission:
   </principles>
 </persona>
 
-<sizing-guidelines>
-  <epic>1-2 weeks of work, 3-8 stories</epic>
-  <story>1-3 days of work, clear AC</story>
-  <rule>If too big: Split it. If too small: Merge it.</rule>
-</sizing-guidelines>
+<project-size-awareness critical="MANDATORY">
+  <instruction>BEFORE starting ANY work (PRD, epics, stories):</instruction>
+  
+  <step n="1">If PRD exists: Read "Project Classification" section (first section)</step>
+  <step n="2">If no PRD: Load skill `prd-writing` to understand size classification</step>
+  <step n="3">Adapt your approach based on size</step>
+  
+  <key-principle>
+    TOY/SMALL → Flat structure, no modules
+    MEDIUM+ → Break into Modules/Domains, create Unit docs
+    
+    Don't over-engineer small projects!
+    Don't under-structure large projects!
+  </key-principle>
+</project-size-awareness>
 
 <methodologies>
   <method name="Problem Framing">What's the REAL problem? Who experiences it? Why does it matter?</method>

package/src/opencode/agents/reviewer.md

@@ -88,13 +88,7 @@ permission:
     <action>search() in docs for architecture requirements</action>
   </phase>
 
-  <phase name="2. Run Tests & Lint">
-    <action>Run test suite: go test / npm test / pytest / cargo test</action>
-    <action>Run linter: golangci-lint / eslint / ruff / cargo clippy</action>
-    <action>If failures → include in review report as HIGH priority</action>
-  </phase>
-
-  <phase name="3. Security First">
+  <phase name="2. Security Analysis">
     <action>Check for hardcoded secrets</action>
     <action>Verify input validation on all user inputs</action>
     <action>Check SQL injection, XSS vulnerabilities</action>
@@ -102,20 +96,26 @@ permission:
     <action>Check if sensitive data is logged</action>
   </phase>
 
-  <phase name="4. Correctness">
+  <phase name="3. Correctness Analysis">
     <action>Verify all acceptance criteria are met</action>
     <action>Check edge cases and error handling</action>
     <action>Look for logic errors and race conditions</action>
     <action>Verify tests cover critical paths</action>
   </phase>
 
-  <phase name="5. Code Quality">
+  <phase name="4. Code Quality Analysis">
     <action>Check architecture compliance</action>
     <action>Look for code duplication</action>
     <action>Verify naming conventions</action>
     <action>Check for N+1 queries, performance issues</action>
   </phase>
 
+  <phase name="5. Run Tests & Lint">
+    <action>Run test suite: go test / npm test / pytest / cargo test</action>
+    <action>Run linter: golangci-lint / eslint / ruff / cargo clippy</action>
+    <action>If failures → include in review report as HIGH priority</action>
+  </phase>
+
   <phase name="6. Report">
     <action>Categorize issues: High/Medium/Low</action>
     <action>Provide specific fixes for each issue</action>

package/src/opencode/opencode.json

@@ -4,6 +4,7 @@
   "instructions": [
     "AGENTS.md",
     ".opencode/FLOW.yaml",
+    ".opencode/config.yaml",
     "docs/prd.md",
     "docs/architecture.md"
   ],

package/src/opencode/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.35"
+    "@opencode-ai/plugin": "1.1.36"
   }
 }

package/src/opencode/plugins/custom-compaction.ts

@@ -1,7 +1,26 @@
 import type { Plugin } from "@opencode-ai/plugin"
-import { readFile, access, readdir } from "fs/promises"
+import { readFile, access, readdir, appendFile } from "fs/promises"
 import { join } from "path"
 
+// Debug logging to file
+async function log(directory: string, message: string): Promise<void> {
+  const logPath = join(directory, ".opencode", "compaction.log")
+  const timestamp = new Date().toISOString()
+  try {
+    await appendFile(logPath, `[${timestamp}] ${message}\n`)
+  } catch {
+    // ignore logging errors
+  }
+}
+
+// Service agents that should be ignored
+const SERVICE_AGENTS = ["title", "compaction", "summary", "system"]
+
+function isRealAgent(agent: string | null): boolean {
+  if (!agent) return false
+  return !SERVICE_AGENTS.includes(agent.toLowerCase())
+}
+
 interface TaskStatus {
   id: string
   content: string
@@ -486,30 +505,55 @@ Previous task was completed successfully.
   return {
     // Track active agent from chat messages
     "chat.message": async (input, output) => {
+      await log(directory, `chat.message: agent=${input.agent}, sessionID=${input.sessionID}`)
       if (input.agent) {
         // Handle both string and object agent (e.g., { name: "dev" })
-        lastActiveAgent = typeof input.agent === 'string' 
+        const agent = typeof input.agent === 'string' 
           ? input.agent 
           : (input.agent as any)?.name || null
-        lastSessionId = input.sessionID
+        
+        // Only track real agents, not service agents
+        if (isRealAgent(agent)) {
+          lastActiveAgent = agent
+          lastSessionId = input.sessionID
+          await log(directory, `  -> tracked agent: ${lastActiveAgent}`)
+        } else {
+          await log(directory, `  -> ignored service agent: ${agent}`)
+        }
       }
     },
 
     // Also track from chat params (backup)
     "chat.params": async (input, output) => {
+      await log(directory, `chat.params: agent=${input.agent}`)
       if (input.agent) {
-        lastActiveAgent = typeof input.agent === 'string' 
+        const agent = typeof input.agent === 'string' 
           ? input.agent 
           : (input.agent as any)?.name || null
+        
+        // Only track real agents, not service agents
+        if (isRealAgent(agent)) {
+          lastActiveAgent = agent
+          await log(directory, `  -> tracked agent: ${lastActiveAgent}`)
+        } else {
+          await log(directory, `  -> ignored service agent: ${agent}`)
+        }
       }
     },
 
     "experimental.session.compacting": async (input, output) => {
+      await log(directory, `=== COMPACTION STARTED ===`)
+      await log(directory, `  lastActiveAgent: ${lastActiveAgent}`)
+      
       // Use tracked agent or try to detect from session
       const agent = lastActiveAgent
       const ctx = await buildContext(agent)
       ctx.activeAgent = agent
       
+      await log(directory, `  story: ${ctx.story?.path || 'none'}`)
+      await log(directory, `  todos: ${ctx.todos.length}`)
+      await log(directory, `  relevantFiles: ${ctx.relevantFiles.length}`)
+      
       const context = formatContext(ctx)
       const instructions = formatInstructions(ctx)
       const readCommands = generateReadCommands(agent, ctx.story)
@@ -532,12 +576,17 @@ ${context}
 ---
 
 ${instructions}`)
+      
+      await log(directory, `  -> output.context pushed (${output.context.length} items)`)
+      await log(directory, `=== COMPACTION DONE ===`)
     },
 
     event: async ({ event }) => {
+      await log(directory, `event: ${event.type}`)
       if (event.type === "session.idle") {
         const story = await getActiveStory()
         if (story && story.pendingTasks.length === 0) {
+          await log(directory, `  -> Story complete: ${story.title}`)
           console.log(`[compaction] Story complete: ${story.title}`)
         }
       }

package/src/opencode/skills/architecture-design/SKILL.md

@@ -30,6 +30,132 @@ Always check project standards: `@CLAUDE.md`
 
 Use template at: `@.opencode/skills/architecture-design/template.md`
 
+## CRITICAL: Adapt Depth to Project Size
+
+**BEFORE writing architecture, read PRD's Project Classification section!**
+
+Your architecture document size should match project size:
+
+| Project Size | Target Lines | Diagrams | ADRs | Focus |
+|--------------|--------------|----------|------|-------|
+| **TOY** | 200-500 | C4 Context + Container | None | Core components only |
+| **SMALL** | 500-1000 | + C4 Component | 2-3 major decisions | Clear module boundaries |
+| **MEDIUM** | 1000-2000 | + Sequences + ER | 5-10 significant | Complete system design |
+| **LARGE** | 2000-4000 | + Deployment + State | 10-20 all decisions | Multiple files OK |
+| **ENTERPRISE** | 4000+ | All diagrams | 20+ per domain | Per-domain files |
+
+**Examples:**
+
+**TOY (Tetris - 350 lines):**
+```
+Executive Summary (50 lines)
+System Context diagram (ASCII)
+3 Modules: GameEngine, Renderer, ScoreManager
+Data Model: GameState object (no DB)
+Tech Stack: HTML5 Canvas, Vanilla JS
+```
+
+**SMALL (Blog - 800 lines):**
+```
+Executive Summary
+Decision Summary (pattern choice)
+C4 Context + Container + Component
+5 Modules: Auth, Posts, Comments, Media, Admin
+ER Diagram (users, posts, comments)
+2-3 ADRs (why SQLite, why server-side rendering)
+```
+
+**MEDIUM (E-commerce - 1500 lines):**
+```
+Full C4 model
+8 Modules across 3 domains
+Complete ER diagram
+Sequence diagrams for checkout flow
+5-10 ADRs
+Integration points documented
+```
+
+**Don't over-engineer small projects!** If PRD says "toy", keep it under 500 lines.
+
+---
+
+## Module/Unit Breakdown by Size
+
+**CRITICAL:** Read PRD's Project Classification to determine module strategy.
+
+| Project Size | Module Strategy | Structure |
+|--------------|-----------------|-----------|
+| **TOY** | No modules | Flat components (GameEngine, Renderer, ScoreManager) |
+| **SMALL** | No modules | Flat components (AuthService, PostService, CommentService) |
+| **MEDIUM** | **YES - Modules** | 3-5 modules (OrderModule, InventoryModule, PaymentModule) |
+| **LARGE** | **YES - Domains** | 5-10 domains (OrderDomain, PaymentDomain, UserDomain) |
+| **ENTERPRISE** | **YES - Bounded Contexts** | 10+ contexts with subdomains |
+
+**For MEDIUM+ projects:**
+
+1. **Identify Modules from PRD:**
+   - Read PRD's Executive Summary → "Key Domains"
+   - Each domain = Module in architecture
+   - Example: PRD lists "Order Management, Inventory, Payment" → 3 modules
+
+2. **Document Each Module:**
+   - Create section per module in architecture.md
+   - Define module boundaries (what's in, what's out)
+   - Define module's internal services
+   - Define module's data ownership
+   - Define module's API (what other modules can call)
+
+3. **Create Unit Documentation:**
+   - For each module, create `docs/units/module-name/index.md`
+   - Use `unit-writing` skill
+   - Include: data model, API spec, events (if event-driven)
+
+4. **Module Communication:**
+   - Document how modules interact
+   - Synchronous (REST/GraphQL) or Asynchronous (events)
+   - Integration diagram showing module dependencies
+
+**Example - MEDIUM E-commerce (3 modules):**
+
+```markdown
+## Modules Overview
+
+### Order Management Module
+
+**Purpose:** Handles order lifecycle from creation to fulfillment
+
+**Internal Services:**
+- OrderService: CRUD operations
+- OrderWorkflowService: Status transitions
+- OrderValidationService: Business rules
+
+**Data Ownership:**
+- orders table
+- order_items table
+- order_history table
+
+**API (exposed to other modules):**
+- `POST /orders` - Create order
+- `GET /orders/{id}` - Get order details
+- `PUT /orders/{id}/status` - Update status
+
+**Events Published:**
+- OrderCreated
+- OrderPaid
+- OrderShipped
+
+→ Unit: `docs/units/order-management/`
+
+### Payment Module
+...
+
+### Inventory Module
+...
+```
+
+**TOY/SMALL projects - NO modules:**
+Just list components/services in flat structure.
+
 ## Architecture Document Structure (v2)
 
 ### 1. Executive Summary

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

@@ -15,30 +15,44 @@ How to transform story tasks into executable instructions for @coder.
 
 ## Task Transformation
 
-Story task is a specification. @coder needs executable instruction with full context.
+Story task is specification with Approach steps. Transform it into executable instruction with full context.
 
-### Add Context
+### Step 1: Read Required Reading
 
-@coder doesn't see the full story. Include:
-- **Existing files** - actual paths to domain entities, interfaces, services that exist
-- **Patterns to follow** - link to existing similar code ("follow pattern from X")
-- **What was done** - results of previous tasks that this task depends on
+Story has "Required Reading" and task has "Read First":
+1. Open each linked document
+2. Find the specific sections mentioned
+3. Extract patterns, signatures, constraints
+
+### Step 2: Find Existing Code
+
+From "Read First" paths:
+1. Read existing similar code (e.g., "existing service example")
+2. Note the structure, imports, error handling
+3. This becomes "Pattern Reference" for @coder
+
+### Step 3: Build Context
+
+@coder doesn't see story. Provide:
+- **Existing files** - actual paths with what they contain
+- **Patterns to follow** - link to existing similar code
+- **What was done** - results of previous tasks this depends on
 - **Imports** - what packages to use
 
-### Add Implementation Direction
+### Step 4: Add Direction
 
-Provide guidance, not code:
-- Interface signatures (what methods to implement)
+Story has "Approach" with high-level steps. Expand with:
+- Interface signatures (method names, params, return types)
 - Error handling approach (what errors to return)
-- Logging requirements (what to log)
 - Validation rules (what to validate)
+- Constraints from documentation
 
-### Add Verification
+### Step 5: Make Verification Concrete
 
-Story has "Done when". Make it concrete:
+Story has "Done when". Add:
 - Specific test commands to run
-- Expected output format
 - Files that must compile
+- Test coverage expectations
 
 ## Formulating Task for @coder
 

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

@@ -22,6 +22,93 @@ Use this skill when you need to:
 
 Use template at: `@.opencode/skills/epic-writing/template.md`
 
+## CRITICAL: What is an Epic?
+
+**Epic scope changes with project size!** Read PRD's Project Classification first.
+
+| Project Size | Epic = | Example | Stories |
+|--------------|--------|---------|---------|
+| **TOY** | Major feature | "Game Logic", "UI Rendering", "Scoring" | 3-8 tasks |
+| **SMALL** | Feature area | "User Authentication", "Post Management" | 5-12 tasks |
+| **MEDIUM** | **Module/Unit** | "Order Management Module", "Payment Module" | 8-15 features |
+| **LARGE** | **Domain** | "Order Domain", "Payment Domain" | 10-20 features |
+| **ENTERPRISE** | **Bounded Context** | "Core Banking Context" | 15-30 features |
+
+**For MEDIUM+ projects:**
+- Each Epic = One Module from PRD
+- Epic should reference Unit documentation: `→ Unit: docs/units/order-management/`
+- Stories within epic are features of that module
+- Epic owns a set of FRs (e.g., FR-ORD-001 through FR-ORD-015)
+
+**Example - MEDIUM E-commerce:**
+```
+Epic: Order Management Module
+  → Unit: docs/units/order-management/
+  → FRs: FR-ORD-001 to FR-ORD-012
+  → Stories:
+    - Customer can create order
+    - System validates inventory
+    - Order status workflow
+    - Order history view
+    ...
+```
+
+**Example - TOY Tetris:**
+```
+Epic: Game Logic
+  → Stories:
+    - Implement block rotation
+    - Add collision detection
+    - Clear full lines
+    - Increase fall speed
+  → No Unit docs needed
+  → Simple AC: "Game logic works correctly"
+```
+
+**Example - SMALL Blog:**
+```
+Epic: Post Management
+  → Stories:
+    - User can create post
+    - User can edit post
+    - User can delete post
+    - User can publish/unpublish
+    - Posts show in list
+  → No Unit docs (flat structure)
+  → AC: "Users can manage posts through full lifecycle"
+```
+
+---
+
+## Epic Depth by Project Size
+
+**CRITICAL:** Epic structure changes with project size!
+
+**TOY/SMALL:**
+- Simple overview (1-2 paragraphs)
+- No Units Affected section (no modules)
+- Simple AC checklist
+- Stories listed as bullet points
+- No Technical Decisions section
+- No Risks section
+
+**MEDIUM:**
+- Detailed overview with business value
+- **Units Affected section** (references Unit docs)
+- Comprehensive AC
+- Stories in table with dependencies
+- Technical Decisions with ADR links
+- Risks identified
+
+**LARGE/ENTERPRISE:**
+- Complete overview with strategic context
+- **Multiple Units Affected** (cross-domain)
+- Exhaustive AC with compliance
+- Stories with estimates and confidence levels
+- All Technical Decisions documented
+- Risks with mitigation plans
+- Security considerations
+
 ## Epic Structure (v2)
 
 ### 1. Header

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

@@ -21,7 +21,194 @@ Use this skill when you need to:
 
 Use the template at: `@.opencode/skills/prd-writing/template.md`
 
-## PRD Structure (v2)
+## PRD Structure (v3 - with Project Classification)
+
+### 0. Project Classification (MANDATORY FIRST SECTION)
+
+**Purpose:** This section determines how deep and detailed ALL subsequent artifacts will be.
+
+**CRITICAL - Fill this FIRST:**
+1. Ask user about project (or infer from requirements)
+2. Classify size based on timeline and complexity
+3. Fill the classification table
+4. Adapt your writing style for the rest of PRD
+
+**Classification Table:**
+
+| Attribute | Value | Notes |
+|-----------|-------|-------|
+| **Size** | toy / small / medium / large / enterprise | See guide below |
+| **Complexity** | simple / moderate / complex / very_complex | Business logic depth |
+| **Team Size** | 1-100+ | Number of developers |
+| **Timeline** | Days/weeks/months | Expected duration |
+| **Domain** | game / web_app / api / library / cli / mobile_app / embedded | Project type |
+
+**Size Impact Table:**
+
+| Attribute | Value |
+|-----------|-------|
+| **PRD Depth** | X-Y pages |
+| **Architecture** | X-Y lines |
+| **Epics** | X-Y (scope: feature/module/domain) |
+| **Stories per Epic** | X-Y |
+| **Sprints** | X |
+
+---
+
+### How to Classify Project Size
+
+**Ask yourself:**
+- What's the scope? (single feature vs full system)
+- How complex is the business logic? (simple CRUD vs complex workflows)
+- How many integrations? (none vs many external systems)
+- What's the data model? (few entities vs complex relationships)
+- Who's the team? (solo vs multiple teams)
+
+---
+
+**TOY** - Learning/Prototype
+- **Examples:** Tetris, Calculator, Tic-tac-toe, Todo list
+- **Scope:** Single feature or concept exploration
+- **Complexity:** Minimal business logic, no integrations
+- **Data:** No database or simple localStorage
+- **Team:** Solo developer
+- **What to write:**
+  - PRD: 2-3 pages, bullet points OK
+  - Architecture: 200-500 lines, simple component diagram
+  - Structure: Flat components (GameEngine, Renderer, ScoreManager)
+  - Epics: 3-5 major features ("Game Logic", "UI", "Scoring")
+  - No modules, no Unit docs
+
+---
+
+**SMALL** - Simple Application
+- **Examples:** Blog, Portfolio site, Simple REST API, Chrome extension, CLI tool
+- **Scope:** Single application with basic CRUD
+- **Complexity:** Simple business logic, 1-2 integrations max
+- **Data:** Basic database (5-10 tables), simple relationships
+- **Team:** 1-2 developers
+- **What to write:**
+  - PRD: 3-5 pages, structured tables
+  - Architecture: 500-1000 lines, C4 Context + Container + Component
+  - Structure: Flat services (AuthService, PostService, CommentService)
+  - Epics: 5-10 feature areas ("User Auth", "Post Management")
+  - No modules yet, no Unit docs
+
+---
+
+**MEDIUM** - Multi-Module System
+- **Examples:** E-commerce site, CRM, Mobile app, Booking system
+- **Scope:** Multiple interconnected features
+- **Complexity:** Moderate business logic, 3-5 integrations, workflows
+- **Data:** 15-30 tables, complex relationships, transactions
+- **Team:** 2-5 developers (small team)
+- **What to write:**
+  - PRD: 5-10 pages, break into **MODULES**
+  - Architecture: 1000-2000 lines, full C4 model + sequences
+  - Structure: **Modules** (OrderModule, InventoryModule, PaymentModule)
+  - Epics: 8-15, **each Epic = one Module**
+  - **Create Unit docs** for each module: `docs/units/module-name/`
+  - Module boundaries matter - define what's in/out
+
+---
+
+**LARGE** - Multi-Domain Platform
+- **Examples:** Multi-tenant SaaS, Payment platform, Social network, Marketplace
+- **Scope:** Multiple domains with complex interactions
+- **Complexity:** Complex business logic, 10+ integrations, event-driven
+- **Data:** 50-100+ tables, multiple databases, caching layers
+- **Team:** 5-20 developers (multiple teams)
+- **What to write:**
+  - PRD: 10-20 pages, think in **DOMAINS**
+  - Architecture: 2000-4000 lines, likely multiple files per domain
+  - Structure: **Domains/Bounded Contexts** (OrderDomain, PaymentDomain)
+  - Epics: 15-30, **each Epic = one Domain**
+  - **Complete Unit docs** with API specs, events, data models
+  - ADRs for all major decisions (affects multiple teams)
+  - Security review required
+
+---
+
+**ENTERPRISE** - Mission-Critical System
+- **Examples:** Banking system, Healthcare platform, ERP, Trading platform
+- **Scope:** Enterprise-wide system with governance
+- **Complexity:** Very complex, regulatory compliance, high availability
+- **Data:** 100+ tables, distributed databases, audit trails
+- **Team:** 20+ developers (large organization)
+- **What to write:**
+  - PRD: 20-50 pages, strategic document
+  - Architecture: 4000+ lines, per-domain files
+  - Structure: **Bounded Contexts** with subdomains
+  - Compliance requirements in every section
+  - Multiple review stages (security, compliance, legal)
+  - Audit-ready documentation
+
+---
+
+### How Size Affects Your Writing
+
+**TOY/SMALL - Keep it lean:**
+```markdown
+## Functional Requirements
+
+### Game Logic
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-001 | User can rotate block | P0 |
+| FR-002 | Blocks fall automatically | P0 |
+| FR-003 | Full lines disappear | P0 |
+
+**Notes:**
+- Rotation uses standard Tetris rules
+- Fall speed increases with score
+```
+
+**MEDIUM - Structured by modules:**
+```markdown
+## Functional Requirements
+
+### Order Management Module
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-ORD-001 | Customer can create order with items | P0 |
+| FR-ORD-002 | System validates inventory before order | P0 |
+| FR-ORD-003 | Order status follows workflow (pending → paid → shipped) | P0 |
+
+**Notes:**
+- Order cannot be modified after payment
+- Inventory reserved on order creation, committed on payment
+
+→ Unit: `docs/units/order-management/`
+
+### Payment Module
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-PAY-001 | System integrates with Stripe | P0 |
+| FR-PAY-002 | Payment failures trigger order cancellation | P0 |
+
+→ Unit: `docs/units/payment/`
+```
+
+**LARGE/ENTERPRISE - Domain-driven:**
+```markdown
+## Functional Requirements
+
+### Order Domain
+→ Unit: `docs/units/order-domain/`
+
+#### Order Lifecycle
+| ID | Requirement | Priority | Compliance |
+|----|-------------|----------|------------|
+| FR-ORD-001 | Customer can create order | P0 | GDPR: consent required |
+| FR-ORD-002 | Order audit trail maintained | P0 | SOX: 7 year retention |
+
+#### Order Validation
+...
+
+### Payment Domain
+→ Unit: `docs/units/payment-domain/`
+...
+```
 
 ### 1. Executive Summary
 
@@ -47,9 +234,28 @@ Brief prose section with:
 | Growth Features | Post-MVP enhancements |
 | Out of Scope | Explicit exclusions |
 
+**IMPORTANT - Module Breakdown by Size:**
+
+- **TOY/SMALL:** No modules needed, flat feature list
+- **MEDIUM+:** Break into modules/domains (Units)
+  - Each module = separate section in scope
+  - Each module will become Epic later
+  - Example: "Order Management Module", "Payment Module"
+
 ### 4. Functional Requirements
 
-**Grouped by domain in tables:**
+**Grouping by Project Size:**
+
+**TOY/SMALL projects:**
+- Group by feature area (flat structure)
+- Example: "Game Logic", "UI", "Scoring"
+
+**MEDIUM+ projects:**
+- Group by Module/Unit (hierarchical)
+- Each module gets its own FR table
+- Example: "Order Management Module" → FR-ORD-001, FR-ORD-002
+
+**Table format:**
 
 | ID | Requirement | Priority |
 |----|-------------|----------|
@@ -57,6 +263,13 @@ Brief prose section with:
 
 With **Notes:** for business rules after each domain table.
 
+**Module-based FR IDs (MEDIUM+):**
+```
+FR-ORD-001  # Order Management module
+FR-PAY-001  # Payment module
+FR-INV-001  # Inventory module
+```
+
 ### 5. Non-Functional Requirements
 
 Tables for:
@@ -81,13 +294,40 @@ Using `→` format:
 → Requirements: `docs/requirements.md`
 ```
 
+## Units (Modules/Domains)
+
+**What is a Unit?**
+A Unit is a module, domain, or bounded context - a cohesive piece of the system.
+
+**When to create Units?**
+
+| Project Size | Units? | Scope | Examples |
+|--------------|--------|-------|----------|
+| **TOY** | No | Flat features | "Game Logic", "UI", "Scoring" |
+| **SMALL** | No | Flat features | "Auth", "Posts", "Comments" |
+| **MEDIUM** | Yes | Modules | "Order Management", "Inventory", "Payment" |
+| **LARGE** | Yes | Domains | "Order Domain", "Payment Domain" |
+| **ENTERPRISE** | Yes | Bounded Contexts | "Core Banking", "Risk Management" |
+
+**For MEDIUM+ projects:**
+1. Identify modules/domains in Executive Summary
+2. Create separate scope section per module
+3. Group FRs by module (FR-ORD-001, FR-PAY-001)
+4. Each module → separate Epic later
+5. Each module → separate Unit documentation (docs/units/module-name/)
+
+**Unit Documentation:**
+- For MEDIUM+ projects, create `docs/units/module-name/index.md` for each module
+- Use `unit-writing` skill to document each unit
+- Link from PRD: `→ Unit: Order Management - docs/units/order-management/`
+
 ## Writing Guidelines
 
 ### Reference Format
 
 Always use `→` prefix for links:
 ```
-→ Unit: `Task`
+→ Unit: `Order Management` - docs/units/order-management/
 → FR: `FR-001`
 → ADR: `ADR-001`
 → `path/to/file.md`

package/src/opencode/skills/prd-writing/template.md

@@ -10,6 +10,42 @@ author: {{author}}
 
 ---
 
+## Project Classification
+
+> **Purpose:** Determines workflow depth and artifact sizes. Agents use this to adapt their approach.
+> See `.opencode/project-size-guide.yaml` for detailed guidelines.
+
+| Attribute | Value | Notes |
+|-----------|-------|-------|
+| **Size** | {{size}} | toy / small / medium / large / enterprise |
+| **Complexity** | {{complexity}} | simple / moderate / complex / very_complex |
+| **Team Size** | {{team_size}} | Number of developers |
+| **Timeline** | {{timeline}} | Expected duration |
+| **Domain** | {{domain}} | web_app / mobile_app / api / library / cli / game / embedded |
+
+**Size Impact:**
+- **PRD Depth:** {{prd_pages}} pages
+- **Architecture:** {{arch_lines}} lines
+- **Epics:** {{epic_count}} ({{epic_scope}})
+- **Stories per Epic:** {{stories_per_epic}}
+- **Sprints:** {{sprint_count}}
+
+<!-- Examples:
+TOY (Tetris):
+  Size: toy | Complexity: simple | Team: 1 | Timeline: < 1 week | Domain: game
+  PRD: 2-3 pages | Arch: 200-500 lines | Epics: 3-5 (major features) | Stories: 3-8 | Sprints: 1
+
+SMALL (Blog):
+  Size: small | Complexity: simple | Team: 1-2 | Timeline: 1-4 weeks | Domain: web_app
+  PRD: 3-5 pages | Arch: 500-1000 lines | Epics: 5-10 (features) | Stories: 5-12 | Sprints: 1-2
+
+MEDIUM (E-commerce):
+  Size: medium | Complexity: moderate | Team: 2-5 | Timeline: 1-3 months | Domain: web_app
+  PRD: 5-10 pages | Arch: 1000-2000 lines | Epics: 8-15 (modules) | Stories: 8-15 | Sprints: 2-4
+-->
+
+---
+
 ## Executive Summary
 
 {{project}} is a {{type}} platform for {{target_users}}. The system handles {{core_capabilities}}.

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

@@ -22,6 +22,35 @@ Use this skill when you need to:
 
 Use template at: `@.opencode/skills/story-writing/template.md`
 
+## CRITICAL: Story Depth by Project Size
+
+**Read PRD's Project Classification to understand appropriate depth!**
+
+| Project Size | Story Depth | AC Detail | Tasks | Example |
+|--------------|-------------|-----------|-------|---------|
+| **TOY** | Simple | Basic Given/When/Then | 1-3 tasks, no subtasks | "Implement block rotation" |
+| **SMALL** | Moderate | Given/When/Then + edge cases | 2-5 tasks, optional subtasks | "User can create post" |
+| **MEDIUM** | Detailed | Comprehensive Given/When/Then | 3-8 tasks, subtasks recommended | "Customer can place order" |
+| **LARGE** | Comprehensive | All scenarios + edge cases | 5-10 tasks, subtasks required | "Process payment with retry logic" |
+| **ENTERPRISE** | Exhaustive | All scenarios + compliance | 8-15 tasks, subtasks + estimates | "Execute trade with audit trail" |
+
+**Key differences:**
+
+**TOY/SMALL:**
+- Simple AC: "Given block at top, When user presses rotate, Then block rotates 90°"
+- Tasks are straightforward: "Add rotation logic", "Add tests"
+- No Required Reading section needed (no coding standards yet)
+
+**MEDIUM:**
+- Detailed AC with edge cases: "Given order with out-of-stock item, When customer submits, Then show error"
+- Tasks reference coding standards and Unit docs
+- Required Reading section mandatory
+
+**LARGE/ENTERPRISE:**
+- Exhaustive AC with compliance: "Given payment failure, When retry limit reached, Then log to audit, notify customer, update order status"
+- Tasks include security considerations
+- Multiple review stages
+
 ## MANDATORY: Read Before Writing
 
 **Before writing ANY story, read these documents:**