@comfanion/workflow 4.36.22 → 4.36.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.36.22",
+  "version": "4.36.24",
   "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.22",
-  "buildDate": "2026-01-24T17:58:25.989Z",
+  "version": "4.36.24",
+  "buildDate": "2026-01-24T19:02:10.302Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/agents/analyst.md

@@ -34,6 +34,16 @@ permission:
   <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">Load .opencode/skills/{skill-name}/SKILL.md and follow instructions</step>
+  
+  <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
+    BEFORE using glob or grep, you MUST call search() first:
+    1. search({ query: "your topic", index: "docs" })  - for documentation
+    2. THEN use glob/grep if you need specific files
+    
+    Example: Looking for existing requirements?
+    ✅ CORRECT: search({ query: "user requirements authentication", index: "docs" })
+    ❌ WRONG: glob("**/*requirements*.md") without search first
+  </search-first>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>
@@ -43,7 +53,8 @@ permission:
     <r>Always validate requirements against SMART criteria</r>
     <r>Never assume - always ask clarifying questions</r>
     <r>Find and use `**/project-context.md` as source of truth if exists</r>
-    <r>USE SEMANTIC SEARCH for existing docs: search({ query: "requirements", index: "docs" })</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>
   </rules>
 </activation>
 

package/src/opencode/agents/architect.md

@@ -45,6 +45,18 @@ permission:
   <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">Load .opencode/skills/{skill-name}/SKILL.md and follow instructions</step>
+  <step n="6">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:
+    1. search({ query: "your topic", index: "docs" })  - for documentation
+    2. search({ query: "your topic", index: "code" })  - for source code
+    3. THEN use glob/grep if you need specific files
+
+    Example: Looking for database schema?
+    ✅ CORRECT: search({ query: "database schema users teams", index: "docs" })
+    ❌ WRONG: glob("**/*schema*.md") without search first
+  </search-first>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>
@@ -56,13 +68,45 @@ permission:
     <r>User journeys drive technical decisions</r>
     <r>Each doc file < 2000 lines (RAG-friendly)</r>
     <r>Find and use `**/project-context.md` and `CLAUDE.md` as source of truth</r>
-    <r critical="true">USE SEMANTIC SEARCH FIRST! Before using glob/grep, ALWAYS try search tool:
-       - search({ query: "concept", index: "docs" }) for documentation
-       - search({ query: "pattern", index: "code" }) for code exploration
-       - glob/grep ONLY for exact filenames or literal strings</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>
+    <r critical="MANDATORY">📋 NEVER create/modify files without user confirmation. Follow <workflow>.</r>
   </rules>
 </activation>
 
+<workflow critical="MANDATORY - FOLLOW FOR EVERY TASK">
+  <phase name="1. Discovery">
+    <action>Search for related documents (search → then glob/grep if needed)</action>
+    <action>Read existing architecture, PRD, related modules</action>
+    <action>Identify what needs to be created/updated</action>
+  </phase>
+  
+  <phase name="2. Planning">
+    <action>Create tasklist with todowrite()</action>
+    <action>Present plan to user with specific files/changes</action>
+    <action>Ask for confirmation with question() tool</action>
+    <action>WAIT for user approval before proceeding</action>
+  </phase>
+  
+  <phase name="3. Execution">
+    <action>Work through tasklist sequentially</action>
+    <action>Mark tasks in_progress → completed</action>
+    <action>If uncertain about something — ask, don't assume</action>
+  </phase>
+  
+  <phase name="4. Review">
+    <action>Summarize what was done</action>
+    <action>Ask if user wants to review or adjust</action>
+  </phase>
+  
+  <never-do>
+    - 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>
+
 <persona>
   <role>System Architect + Technical Design Leader</role>
   <identity>Senior architect with expertise in distributed systems, cloud infrastructure, API design. DDD and hexagonal architecture expert.</identity>
@@ -81,7 +125,7 @@ permission:
   <skill name="architecture-validation">NFR compliance, dependency analysis, security</skill>
   <skill name="adr-writing">Decision record format, context, consequences</skill>
   <skill name="coding-standards">Code patterns, naming conventions, best practices</skill>
-  <skill name="unit-writing">Universal Unit format for modules, domains, entities, services, features</skill>
+  <skill name="unit-writing">Document modules, domains, services, entities with folder-based structure</skill>
 </skills>
 
 <design-principles>
@@ -93,14 +137,17 @@ permission:
   6. Observability First - Design for debugging and monitoring
 </design-principles>
 
-<unit-structure hint="For unit-writing skill">
-  docs/units/[unit-name]/
-  ├── unit.md            # Universal Unit format: overview, boundaries, contracts
-  ├── data-model.md      # If has database
-  ├── api/               # HTTP/gRPC specs
-  ├── events/            # Event schemas
-  └── flows/             # Flow diagrams
-</unit-structure>
+<documentation-structure hint="For unit-writing skill">
+  docs/architecture/
+  ├── modules/{name}/           # Bounded contexts
+  │   ├── index.md
+  │   ├── data-model.md
+  │   ├── services/{name}/      # Services inside module
+  │   └── domains/{name}/       # Domains inside module
+  ├── services/{name}/          # Standalone services
+  └── domains/{name}/           # Standalone domains
+      └── entities/{name}.md    # Entities inside domain
+</documentation-structure>
 
 <lsp-architecture hint="Use LSP for architecture analysis - requires OPENCODE_EXPERIMENTAL_LSP_TOOL=true">
   <use-case name="Module boundaries">
@@ -123,13 +170,13 @@ permission:
 
 <codesearch-architecture hint="Semantic search with MULTI-INDEX for architecture analysis">
   <check>codeindex({ action: "list" }) → See all indexes (code, docs, config)</check>
-  
+
   <indexes hint="Use different indexes for different architecture analysis">
     <index name="code">Source code - patterns, implementations, boundaries</index>
     <index name="docs">Documentation - ADRs, design docs, architecture decisions</index>
     <index name="config">Configuration - infrastructure settings, feature flags</index>
   </indexes>
-  
+
   <use-cases>
     <use-case name="Discover patterns" index="code">
       codesearch({ query: "repository pattern implementation", index: "code" })
@@ -157,7 +204,7 @@ permission:
       codesearch({ query: "feature flags", index: "config" })
     </use-case>
   </use-cases>
-  
+
   <architecture-exploration-flow>
     1. codeindex({ action: "list" }) → Check available indexes
     2. codesearch({ query: "architecture overview", index: "docs" }) → Read existing docs
@@ -167,7 +214,7 @@ permission:
     6. codesearch({ query: "infrastructure config", index: "config" }) → See settings
     7. lsp for detailed analysis of key files
   </architecture-exploration-flow>
-  
+
   <cross-index-analysis hint="Combine indexes for full picture">
     - Code + Docs: "How is authentication implemented?" (code) + "Why this approach?" (docs)
     - Code + Config: "Database usage patterns" (code) + "Connection settings" (config)
@@ -194,5 +241,7 @@ permission:
 **My Output:**
 - `docs/architecture.md`
 - `docs/architecture/adr/*.md`
-- `docs/units/[unit-name]/` ← unit docs (Universal Unit format)
+- `docs/architecture/modules/` — bounded contexts
+- `docs/architecture/services/` — standalone services
+- `docs/architecture/domains/` — domains
 - `docs/coding-standards/`

package/src/opencode/agents/dev.md

@@ -37,6 +37,17 @@ permission:
   <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">Load .opencode/skills/{skill-name}/SKILL.md and follow instructions</step>
+  
+  <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
+    BEFORE using glob or grep, you MUST call search() first:
+    1. search({ query: "your topic", index: "code" })  - for source code patterns
+    2. search({ query: "your topic", index: "docs" })  - for documentation
+    3. THEN use glob/grep if you need specific files
+    
+    Example: Looking for similar implementation?
+    ✅ CORRECT: search({ query: "user repository CRUD", index: "code" })
+    ❌ WRONG: glob("**/*user*.go") without search first
+  </search-first>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>
@@ -48,7 +59,8 @@ permission:
     <r>All existing tests must pass 100% before story is ready for review</r>
     <r>NEVER lie about tests being written or passing</r>
     <r>Find and use `**/project-context.md` and `CLAUDE.md` as source of truth</r>
-    <r>USE SEMANTIC SEARCH for finding existing patterns: search({ query: "similar feature", index: "code" })</r>
+    <r critical="MANDATORY">🔍 SEARCH FIRST: Call search() BEFORE glob when exploring codebase.
+       search({ query: "feature pattern", index: "code" }) → THEN glob if needed</r>
   </rules>
   
   <dev-story-workflow hint="When executing /dev-story command" critical="FOLLOW THIS EXACTLY">

package/src/opencode/agents/pm.md

@@ -42,6 +42,16 @@ permission:
   <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">Load .opencode/skills/{skill-name}/SKILL.md and follow instructions</step>
+  
+  <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
+    BEFORE using glob or grep, you MUST call search() first:
+    1. search({ query: "your topic", index: "docs" })  - for PRD, architecture, requirements
+    2. THEN use glob/grep if you need specific files
+    
+    Example: Looking for existing stories?
+    ✅ CORRECT: search({ query: "user authentication stories", index: "docs" })
+    ❌ WRONG: glob("**/*story*.md") without search first
+  </search-first>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>
@@ -53,7 +63,8 @@ permission:
     <r>NEVER create stories without acceptance criteria</r>
     <r critical="true">BEFORE writing epic/story: USE SEMANTIC SEARCH (see before-epic-story)</r>
     <r>Find and use `**/project-context.md` as source of truth if exists</r>
-    <r>USE SEMANTIC SEARCH FIRST: search({ query: "topic", index: "docs" }) before glob/grep</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>
   </rules>
   
   <before-epic-story critical="MANDATORY">

package/src/opencode/plugins/file-indexer.ts

@@ -366,13 +366,12 @@ async function processPendingFiles(projectRoot: string, config: VectorizerConfig
         try {
           const wasIndexed = await indexer.indexSingleFile(filePath)
           if (wasIndexed) {
-            // Only log in debug mode, successful reindex is silent
-            debug(`Reindexed: ${path.relative(projectRoot, filePath)} -> ${indexName}`)
+            log(`Reindexed: ${path.relative(projectRoot, filePath)} → ${indexName}`)
           } else {
-            debug(`Skipped (unchanged): ${path.relative(projectRoot, filePath)}`)
+            logFile(`Skipped (unchanged): ${path.relative(projectRoot, filePath)}`)
           }
         } catch (e) {
-          debug(`Error: ${(e as Error).message}`)
+          log(`Error reindexing ${path.relative(projectRoot, filePath)}: ${(e as Error).message}`)
         }
       }
       
@@ -478,7 +477,7 @@ export const FileIndexerPlugin: Plugin = async ({ directory, client }) => {
         const props = (event as any).properties || {}
         const filePath = props.file || props.path || props.filePath
         if (filePath) {
-          debug(`${event.type}: ${filePath}`)
+          log(`Event: ${event.type} → ${filePath}`)
           queueFileForIndexing(filePath)
         }
       }

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

@@ -1,185 +1,394 @@
 ---
 name: unit-writing
-description: How to document modules, domains, entities, services, and features using the universal Unit format
+description: How to document modules, domains, services, and entities with structured folder-based approach
 license: MIT
 compatibility: opencode
 metadata:
   domain: documentation
-  artifacts: docs/architecture/units/*.md
+  artifacts: docs/architecture/{modules,services,domains}/
 ---
 
 # Unit Writing Skill
 
-## When to Use
+## Overview
 
-Use this skill when you need to document any logical piece of the system:
-- **Module** - Large bounded context (e.g., `catalog`, `billing`)
-- **Domain** - Medium business area (e.g., `Order`, `Payment`)
-- **Entity** - Small data object (e.g., `User`, `Task`, `Product`)
-- **Service** - Medium component (e.g., `NotificationService`)
-- **Feature** - Varies (e.g., `Search`, `Import`)
+Documentation follows a **folder-based structure** organized by type: modules, services, domains. Agent determines the appropriate type based on what is being documented.
 
-## Template
+**Core Principles:**
+- Each file focuses on one concern
+- Files stay under 500 lines (RAG-friendly)
+- Agent decides the type — no rigid rules
 
-Use template at: `@.opencode/skills/unit-writing/template.md`
+## When to Use
 
-## Unit Document Structure
+Use this skill to document any logical piece of the system:
 
-### 1. Header
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `module` | Deployable bounded context, largest scope | `catalog`, `auth`, `billing` |
+| `domain` | Business concept grouping within module | `Order`, `Payment`, `Identity` |
+| `service` | Stateless component with clear API | `NotificationService`, `CorrelationEngine` |
+| `entity` | Core data object with business rules | `User`, `Product`, `Invoice` |
+| `feature` | Cross-cutting capability | `Search`, `Import`, `Export` |
 
-```yaml
-id: {{ID}}
-type: module | domain | entity | service | feature
-status: draft | approved
-```
+### Hierarchy
 
-### 2. Overview
+Components can be nested when logical:
 
-Prose paragraph explaining:
-- What the unit is responsible for
-- What it owns
-- What it provides to others
-- Key characteristics
+| Parent | Can contain |
+|--------|-------------|
+| `module` | services, domains |
+| `service` | domains, entities |
+| `domain` | entities |
+| `entity` | — (leaf node) |
 
-### 3. Boundaries
+Agent decides based on project context — no strict rules.
 
-| Aspect | Details |
-|--------|---------|
-| **Owns** | Data and behavior this unit controls |
-| **Uses** | → Unit: `dependency` |
-| **Provides** | What others can use from this unit |
+### Documentation Depth by Type
 
-### 4. Data Model
+| Type | Location | Required Files | Optional |
+|------|----------|----------------|----------|
+| `module` | `modules/{name}/` | index, data-model | api/, events/, services/, domains/ |
+| `service` | `services/{name}/` OR `modules/{m}/services/{name}/` | index | api/, data-model |
+| `domain` | `domains/{name}/` OR inside module/service | index, data-model | entities/ |
+| `entity` | inside domain | {entity}.md | — |
 
-| Field | Type | Constraints | Description |
-|-------|------|-------------|-------------|
-| id | UUID | PK | Primary identifier |
-| name | string | required, max 200 | Display name |
+**When to use separate folder vs inline:**
+- **Separate folder** — has own API, events, or multiple child units
+- **Single file** — simple entity, no children, < 200 lines
 
-### 5. Relations
+**Don't create units for:**
+- Simple value objects (document inline in parent)
+- Internal implementation details
+- DTOs, request/response objects
 
-ASCII diagram + table:
+---
+
+## Folder Structure
+
+Documentation organized under `docs/architecture/`:
 
 ```
-Task ──► User (assignee)
-Task ──< Comment (1:N)
+docs/architecture/
+├── modules/                    # Bounded contexts
+│   └── {module}/
+│       ├── index.md
+│       ├── data-model.md
+│       ├── api/
+│       ├── events/
+│       ├── services/           # Services INSIDE module
+│       │   └── {service}/
+│       └── domains/            # Domains INSIDE module
+│           └── {domain}/
+│
+├── services/                   # Standalone services (outside modules)
+│   └── {service}/
+│       ├── index.md
+│       └── api/
+│
+└── domains/                    # Standalone domains (rare)
+    └── {domain}/
 ```
 
-| Relation | Target | Type | Description |
-|----------|--------|------|-------------|
-| assignee | → Unit: `User` | N:1 | Task assigned to user |
+### Placement rules
 
-### 6. Operations
+| Component | Standalone | Inside module |
+|-----------|------------|---------------|
+| service | `services/{name}/` | `modules/{m}/services/{name}/` |
+| domain | `domains/{name}/` | `modules/{m}/domains/{name}/` |
+| entity | — | always inside domain |
 
-| Operation | Input | Output | Description |
-|-----------|-------|--------|-------------|
-| Create | params | Entity | Creates new instance |
+Agent decides based on:
+- **Standalone service** — independent, used by multiple modules
+- **Service inside module** — belongs to one bounded context
 
-With **Business Rules:** list.
+### File Purposes
 
-### 7. State Machine (if applicable)
+| File | Purpose | Max Lines |
+|------|---------|-----------|
+| `index.md` | Overview, boundaries, navigation, key decisions | ~150 |
+| `data-model.md` | Database schema, relations, constraints, migrations | ~400 |
+| `api/*.yaml` | OpenAPI specs for each resource | ~300 each |
+| `events/index.md` | Event flow overview, topic mapping | ~200 |
+| `events/*.avsc` | Individual event schemas | ~100 each |
 
-```
-todo ──► in_progress ──► done
+---
+
+## Required Files
+
+### 1. index.md (Overview)
+
+The main entry point for the unit. Contains:
+- Unit metadata (YAML frontmatter)
+- Overview paragraph
+- Boundaries table (owns/uses/provides)
+- Architecture diagram
+- Document navigation
+- Key decisions/ADRs
+
+**Template:** See `@.opencode/skills/unit-writing/templates/index.md`
+
+```yaml
+# index.md frontmatter
+---
+id: MOD-COLLABORATION
+type: module
+status: draft | approved
+version: "1.0"
+created: 2026-01-24
+---
 ```
 
-| State | Description | Transitions To |
-|-------|-------------|----------------|
+**Boundaries Table Format:**
 
-### 8. Errors
+| Aspect | Details |
+|--------|---------|
+| **Owns** | meetings, channels, focus_blocks (tables + behavior) |
+| **Uses** | → Unit: `identity` (contributor resolution) |
+| **Uses** | → Unit: `teams` (team attribution) |
+| **Provides** | Collaboration metrics API, Team health signals |
+
+### 2. data-model.md (Database Schema)
+
+Complete database schema documentation:
+- Entity Relationship Diagram (ASCII/Mermaid)
+- Table definitions (SQL or structured tables)
+- Indexes and constraints
+- Migration strategy (if applicable)
+
+**Structure:**
+1. Overview (design principles)
+2. ERD diagram
+3. Core tables (with full SQL or field tables)
+4. Supporting tables
+5. Indexes
+6. Views/Aggregates (if any)
+7. Migration notes
+
+**Example header:**
+```markdown
+# Collaboration Data Model
 
-| Error | Code | When |
-|-------|------|------|
-| NotFound | UNIT_001 | Entity doesn't exist |
+**Version:** 1.0
+**Date:** 2026-01-24
+**Status:** Active
 
-### 9. References
+## 1. Design Principles
 
+| Principle | Description |
+|-----------|-------------|
+| **Single Source of Truth** | PostgreSQL primary, Redis for cache |
+| **SCD2 History** | Time-scoped team membership |
 ```
-→ Architecture: `docs/architecture.md`
-→ Related: → Unit: `OtherUnit`
+
+### 3. events/index.md (Events Overview)
+
+Overview of all events the unit produces/consumes:
+- Event flow diagram
+- Topic naming convention
+- Event types table
+- Schema file references
+
+**Structure:**
+```markdown
+# {Unit} Events
+
+## Overview
+Brief description of event-driven patterns.
+
+## Event Flow
+ASCII/Mermaid diagram showing producers/consumers.
+
+## Topics
+
+| Topic | Events | Partition Key | Direction |
+|-------|--------|---------------|-----------|
+| `events.teams.canonical` | meeting_* | tenant_id | inbound |
+
+## Schema Files
+
+| Schema | Description |
+|--------|-------------|
+| `meeting-scheduled.avsc` | New meeting created |
 ```
 
-## Unit Types Guide
+### 4. api/*.yaml (OpenAPI Specs)
 
-| Type | When to Use | Example |
-|------|-------------|---------|
-| `module` | Deployable bounded context | `catalog`, `auth` |
-| `domain` | Business concept grouping | `Order`, `Inventory` |
-| `entity` | Core data object | `User`, `Task` |
-| `service` | Stateless component | `EmailService` |
-| `feature` | Cross-cutting capability | `Search`, `Export` |
+One OpenAPI file per resource or logical grouping:
+- `meetings.yaml` - Meeting endpoints
+- `focus-time.yaml` - Focus time endpoints
+- `graph.yaml` - Collaboration graph endpoints
+
+Follow OpenAPI 3.1 format.
+
+---
 
 ## Naming Conventions
 
-### File Names
+### Folder Names
 
 ```
-unit-{name}.md
+kebab-case, lowercase
 
 Examples:
-- unit-task.md
-- unit-catalog.md
-- unit-notification-service.md
+- modules/billing/
+- services/notification/
+- domains/subscription/
 ```
 
-### Unit IDs
+### File Names
 
 ```
-{TYPE}-{NAME}
-
-Examples:
-- MOD-CATALOG
-- ENT-TASK
-- SVC-NOTIFICATION
+index.md                # Entry point (always)
+data-model.md           # Database schema
+{resource}.yaml         # API specs by resource
+{event-type}.avsc       # Event schemas by type
 ```
 
+---
+
 ## Reference Format
 
-Always use `→` prefix when referencing units:
+Reference other components with relative paths:
 
 ```markdown
-→ Unit: `Task`
-→ Unit: `catalog/Product`
-→ Unit: `NotificationService`
+| Uses | [identity](../domains/identity/) (contributor resolution) |
+| Uses | [teams](../modules/teams/) (team attribution) |
 ```
 
-In other documents (PRD, Architecture, Stories):
+Or with `→` shorthand:
 ```markdown
-| Feature | Unit |
-|---------|------|
-| Task CRUD | → Unit: `Task` |
+→ modules/billing
+→ services/notification
+→ domains/subscription/data-model.md#plans
 ```
 
-## When to Create Unit Doc
+---
+
+## Creating Documentation
+
+### Step 1: Determine type
+
+Agent analyzes what is being documented:
+- Has own deployment/bounded context? → `modules/`
+- Stateless with clear API? → `services/`
+- Business logic grouping? → `domains/`
+
+### Step 2: Create folder
+
+```bash
+mkdir -p docs/architecture/{type}/{name}
+```
+
+### Step 3: Start with index.md
+
+Create `index.md` with:
+1. Overview paragraph
+2. Boundaries table (owns/uses/provides)
+3. Architecture diagram (if complex)
+4. Navigation to other files
+
+### Step 4: Add supporting files as needed
 
-| Situation | Create Unit Doc? |
-|-----------|-----------------|
-| New module in architecture | Yes |
-| Complex entity with business rules | Yes |
-| Entity referenced from multiple places | Yes |
-| Simple value object | No (document inline) |
-| Internal implementation detail | No |
+- `data-model.md` — if has database
+- `api/*.yaml` — if has REST/gRPC API
+- `events/` — if event-driven
+- `entities/*.md` — for leaf entities
+
+---
 
 ## Validation Checklist
 
-- [ ] Type is correctly specified
+### index.md
+- [ ] Has YAML frontmatter (id, type, status, version)
 - [ ] Overview explains single responsibility
-- [ ] Boundaries are clear (owns/uses/provides)
-- [ ] Data model complete with constraints
-- [ ] Relations use `→ Unit:` format
-- [ ] Operations list all public methods
-- [ ] Business rules documented
-- [ ] Errors have codes
-- [ ] References link to related docs
+- [ ] Boundaries table complete (owns/uses/provides)
+- [ ] Architecture diagram present
+- [ ] Navigation links to other files
+- [ ] References to related units
+
+### data-model.md
+- [ ] ERD diagram present
+- [ ] All tables documented
+- [ ] Constraints and indexes listed
+- [ ] Follows project DB conventions
+
+### events/
+- [ ] index.md with topic mapping
+- [ ] Individual schema files for each event
+- [ ] Event flow diagram
+
+### api/
+- [ ] OpenAPI 3.1 format
+- [ ] Consistent naming
+- [ ] Request/response examples
+
+---
+
+## Example
+
+```
+docs/architecture/
+├── modules/
+│   └── billing/                        # Module
+│       ├── index.md
+│       ├── data-model.md
+│       ├── services/
+│       │   └── payment-gateway/        # Service INSIDE module
+│       │       ├── index.md
+│       │       └── api/
+│       └── domains/
+│           └── subscription/           # Domain INSIDE module
+│               ├── index.md
+│               └── entities/
+│                   └── plan.md
+│
+└── services/
+    └── notification/                   # Standalone service
+        ├── index.md
+        └── api/
+```
+
+**Key patterns:**
+1. `payment-gateway` is inside `billing` — it belongs to that module
+2. `notification` is standalone — used by multiple modules
+3. Each component has `index.md` as entry point
+4. Entities are leaf nodes (single files inside domain)
+
+---
+
+## Anti-Patterns
+
+❌ **DON'T:**
+- Create 500+ line monolithic files
+- Mix data model with API with events in one file
+- Embed full SQL schemas in index.md
+- Force everything into rigid structure
+
+✅ **DO:**
+- Keep files focused and under 500 lines
+- Separate concerns (data model, API, events)
+- Let agent decide appropriate structure
+- Use relative paths for references
+
+---
 
 ## Output
 
-Save to: `docs/architecture/units/unit-{name}.md`
+```
+docs/architecture/
+├── modules/{name}/                 # Bounded contexts
+│   ├── services/{name}/            # Services inside module
+│   └── domains/{name}/             # Domains inside module
+├── services/{name}/                # Standalone services
+└── domains/{name}/                 # Standalone domains
+```
 
-Or inline in architecture doc for simple units.
+Agent decides placement based on component relationships.
 
 ## Related Skills
 
-- `architecture-design` - References units
+- `architecture-design` - Creates units during architecture phase
 - `story-writing` - Tasks reference units
 - `epic-writing` - Epics affect units
+- `adr-writing` - ADRs may be linked from unit index

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

@@ -1,136 +1,11 @@
-# Unit: {{name}}
+# DEPRECATED
 
-```yaml
-id: {{ID}}
-type: module | domain | entity | service | feature
-status: draft | approved
-```
+This file is deprecated. Unit templates have been moved to folder-based structure.
 
----
+See: `templates/` directory
 
-## Overview
+- `templates/index.md` — Main unit overview
+- `templates/data-model.md` — Database schema
+- `templates/events-index.md` — Events overview
 
-{{name}} is responsible for {{single_responsibility}}. It owns {{what_it_owns}} and provides {{what_it_exposes}} to other parts of the system.
-
-**Type:** {{module/domain/entity/service/feature}}
-
-**Key Characteristics:**
-- {{characteristic_1}}
-- {{characteristic_2}}
-
-<!-- e.g.
-Task is responsible for representing a unit of work in the system. It owns title, description, status, and due date, and provides CRUD operations and status transitions to other parts of the system.
-
-**Type:** entity
-
-**Key Characteristics:**
-- Immutable ID after creation
-- Status follows defined workflow
-- Always belongs to one workspace
--->
-
----
-
-## Boundaries
-
-| Aspect | Details |
-|--------|---------|
-| **Owns** | {{data_and_behavior}} |
-| **Uses** | → Unit: `{{dependency}}` |
-| **Provides** | {{exposed_operations}} |
-
-**Notes:**
-- {{boundary_clarification}}
-
----
-
-## Data Model
-
-| Field | Type | Constraints | Description |
-|-------|------|-------------|-------------|
-| id | {{type}} | PK | Primary identifier |
-| {{field}} | {{type}} | {{constraints}} | {{description}} |
-| {{field}} | {{type}} | {{constraints}} | {{description}} |
-
-<!-- e.g.
-| id | UUID | PK | Primary identifier |
-| title | string | required, max 200 | Task title |
-| status | enum | required | todo, in_progress, done |
-| assignee_id | UUID | FK → User, nullable | Assigned user |
-| due_date | datetime | nullable | Deadline |
--->
-
----
-
-## Relations
-
-```
-{{this}} ──► {{other}} ({{relation_type}})
-{{this}} ──< {{other}} ({{relation_type}})
-```
-
-| Relation | Target | Type | Description |
-|----------|--------|------|-------------|
-| {{name}} | → Unit: `{{target}}` | {{1:1/1:N/N:M}} | {{description}} |
-
-<!-- e.g.
-| assignee | → Unit: `User` | N:1 | Task assigned to user |
-| comments | → Unit: `Comment` | 1:N | Task has many comments |
-| tags | → Unit: `Tag` | N:M | Task can have multiple tags |
--->
-
----
-
-## Operations
-
-| Operation | Input | Output | Description |
-|-----------|-------|--------|-------------|
-| {{op}} | {{params}} | {{result}} | {{what_it_does}} |
-
-**Business Rules:**
-- {{rule}}
-
-<!-- e.g.
-| Create | title, description | Task | Creates new task with status=todo |
-| Assign | task_id, user_id | Task | Assigns task to user |
-| ChangeStatus | task_id, new_status | Task | Transitions status |
-
-**Business Rules:**
-- Cannot assign to deactivated user
-- Status can only move forward (todo→progress→done)
--->
-
----
-
-## State Machine
-
-```
-{{state_1}} ──► {{state_2}} ──► {{state_3}}
-     │              │
-     └──────────────┘ ({{condition}})
-```
-
-| State | Description | Transitions To |
-|-------|-------------|----------------|
-| {{state}} | {{meaning}} | {{next_states}} |
-
----
-
-## Errors
-
-| Error | Code | When |
-|-------|------|------|
-| {{error}} | {{code}} | {{condition}} |
-
-<!-- e.g.
-| TaskNotFound | TASK_001 | Task with ID doesn't exist |
-| InvalidTransition | TASK_002 | Status change not allowed |
-| AssigneeInactive | TASK_003 | Cannot assign to deactivated user |
--->
-
----
-
-## References
-
-→ Architecture: `{{path}}`
-→ Related: → Unit: `{{related}}`
+Refer to `SKILL.md` for usage instructions.

package/src/opencode/skills/unit-writing/templates/data-model.md

@@ -0,0 +1,57 @@
+# {{Unit Name}} Data Model
+
+**Version:** 1.0
+**Date:** {{YYYY-MM-DD}}
+**Status:** Active
+
+---
+
+## Design Principles
+
+| Principle | Description |
+|-----------|-------------|
+| {{Principle}} | {{Why this matters}} |
+
+---
+
+## Entity Relationship Diagram
+
+```
+{{ASCII or Mermaid diagram}}
+```
+
+---
+
+## Tables
+
+### {{Table Name}}
+
+{{Purpose of this table}}
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| id | UUID | PK | Primary identifier |
+| {{field}} | {{type}} | {{constraints}} | {{description}} |
+
+**Indexes:**
+- `({{fields}})` — {{purpose}}
+
+---
+
+## Relations
+
+| Relation | Type | Description |
+|----------|------|-------------|
+| {{table_a}} → {{table_b}} | 1:N | {{description}} |
+
+---
+
+## Status Lifecycle
+
+```
+{{state_a}} ──► {{state_b}} ──► {{state_c}}
+```
+
+| Status | Description | Transitions To |
+|--------|-------------|----------------|
+| {{status}} | {{meaning}} | {{allowed_next}} |

package/src/opencode/skills/unit-writing/templates/entity.md

@@ -0,0 +1,85 @@
+# {{Name}}
+
+```yaml
+type: entity
+status: draft | approved
+version: "1.0"
+```
+
+---
+
+## Overview
+
+{{What this entity represents, its role in the domain.}}
+
+---
+
+## Boundaries
+
+| Aspect | Details |
+|--------|---------|
+| **Owns** | {{fields, behavior}} |
+| **Part of** | {{parent domain/module path}} |
+
+---
+
+## Data Model
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| id | UUID | PK | Primary identifier |
+| {{field}} | {{type}} | {{constraints}} | {{description}} |
+
+---
+
+## Relations
+
+```
+{{Entity}} ──► {{Other}} ({{type}})
+{{Entity}} ──< {{Other}} ({{type}})
+```
+
+| Relation | Target | Type | Description |
+|----------|--------|------|-------------|
+| {{name}} | {{target}} | N:1 / 1:N / N:M | {{description}} |
+
+---
+
+## State Machine
+
+```
+{{state_a}} ──► {{state_b}} ──► {{state_c}}
+```
+
+| State | Description | Transitions To |
+|-------|-------------|----------------|
+| {{state}} | {{meaning}} | {{allowed_next}} |
+
+---
+
+## Operations
+
+| Operation | Input | Output | Description |
+|-----------|-------|--------|-------------|
+| Create | {{params}} | Entity | {{description}} |
+| {{op}} | {{params}} | {{result}} | {{description}} |
+
+**Business Rules:**
+- {{rule}}
+
+---
+
+## Errors
+
+| Error | Code | When |
+|-------|------|------|
+| {{Error}} | {{CODE}} | {{condition}} |
+
+---
+
+## References
+
+```
+→ Parent: {{parent path}}
+→ Related: {{related path}}
+```

package/src/opencode/skills/unit-writing/templates/events-index.md

@@ -0,0 +1,42 @@
+# {{Unit Name}} Events
+
+**Version:** 1.0
+**Date:** {{YYYY-MM-DD}}
+
+---
+
+## Overview
+
+{{Brief description of event patterns in this unit}}
+
+---
+
+## Event Flow
+
+```
+{{ASCII diagram: sources → processing → sinks}}
+```
+
+---
+
+## Topics
+
+### Produced Events
+
+| Topic | Events | Key | Description |
+|-------|--------|-----|-------------|
+| {{topic}} | {{EventType}} | {{partition_key}} | {{description}} |
+
+### Consumed Events
+
+| Topic | Events | Source |
+|-------|--------|--------|
+| {{topic}} | {{EventType}} | {{source_system}} |
+
+---
+
+## Schema Files
+
+| Schema | Description |
+|--------|-------------|
+| [{{event}}.avsc]({{event}}.avsc) | {{description}} |

package/src/opencode/skills/unit-writing/templates/index.md

@@ -0,0 +1,61 @@
+# {{Name}}
+
+```yaml
+type: module | domain | service | entity
+status: draft | approved
+version: "1.0"
+created: {{YYYY-MM-DD}}
+```
+
+---
+
+## Overview
+
+{{One paragraph describing what this unit does, what problem it solves, and key characteristics.}}
+
+**Not responsible for:**
+- {{What this unit explicitly doesn't handle}}
+
+---
+
+## Boundaries
+
+| Aspect | Details |
+|--------|---------|
+| **Owns** | {{tables, domain objects, behavior}} |
+| **Uses** | → Unit: `{{dependency}}` ({{purpose}}) |
+| **Provides** | {{APIs, events, services to others}} |
+
+---
+
+## Architecture
+
+```
+{{ASCII diagram showing high-level structure}}
+```
+
+---
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [data-model.md](data-model.md) | Database schema |
+| [api/](api/) | API specifications |
+| [events/](events/) | Event schemas |
+
+## Child Units
+
+| Unit | Type | Description |
+|------|------|-------------|
+| [services/{{service}}/](services/{{service}}/) | service | {{description}} |
+| [domains/{{domain}}/](domains/{{domain}}/) | domain | {{description}} |
+
+---
+
+## References
+
+```
+→ Architecture: docs/architecture.md
+→ Related: modules/{{related}}/ or services/{{related}}/
+```