start-vibing 2.0.13 → 2.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.13",
+	"version": "2.0.15",
 	"description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
 	"type": "module",
 	"bin": {

package/template/.claude/agents/01-orchestration/workflow-router.md

@@ -33,17 +33,20 @@ You analyze requests and route them to the correct specialized agent.
 
 ### By File Type
 
-| File Pattern                | Agents                                   |
-| --------------------------- | ---------------------------------------- |
-| `*.ts` (not test)           | ts-strict-checker, zod-validator         |
-| `*.spec.ts`, `*.test.ts`    | tester-unit, vitest-config               |
-| `*.e2e.ts`                  | playwright-e2e, playwright-fixtures      |
-| `Dockerfile*`               | dockerfile-optimizer, docker-multi-stage |
-| `docker-compose*.yml`       | docker-compose-designer                  |
-| `*schema*.ts`, `*model*.ts` | mongoose-schema-designer                 |
-| `*.md`                      | documenter, readme-generator             |
-| `auth*.ts`, `session*.ts`   | security-auditor, auth-session-validator |
-| `*.json` (config)           | deployment-validator                     |
+| File Pattern                | Agents                                            |
+| --------------------------- | ------------------------------------------------- |
+| `*.tsx`, `*.jsx`            | **ui-mobile + ui-tablet + ui-desktop** (MANDATORY)|
+| `*.ts` (not test)           | ts-strict-checker, zod-validator                  |
+| `*.spec.ts`, `*.test.ts`    | tester-unit, vitest-config                        |
+| `*.e2e.ts`                  | playwright-e2e, playwright-fixtures               |
+| `Dockerfile*`               | dockerfile-optimizer, docker-multi-stage          |
+| `docker-compose*.yml`       | docker-compose-designer                           |
+| `*schema*.ts`, `*model*.ts` | mongoose-schema-designer                          |
+| `*.md`                      | documenter, readme-generator                      |
+| `auth*.ts`, `session*.ts`   | security-auditor, auth-session-validator          |
+| `*.json` (config)           | deployment-validator                              |
+
+> **CRITICAL:** ANY task touching `.tsx` or `.jsx` files MUST invoke UI agents in parallel.
 
 ### By Workflow Phase
 
@@ -112,3 +115,5 @@ If multiple routes are valid:
 2. **CHECK FILE TYPES** - Files often indicate correct agent
 3. **CONSIDER PHASE** - Where are we in the workflow?
 4. **PARALLEL WHEN POSSIBLE** - Route to multiple if independent
+5. **PLAN FIRST** - Use EnterPlanMode for non-trivial tasks before implementing
+6. **JSX = UI AGENTS** - Any .tsx/.jsx file REQUIRES ui-mobile + ui-tablet + ui-desktop

package/template/.claude/agents/07-documentation/documenter.md

@@ -1,76 +1,184 @@
 ---
 name: documenter
-description: 'AUTOMATICALLY invoke AFTER any code implementation completes. Triggers: code was written/edited, new files created, feature implemented. Detects changes via git diff, updates domain files, maintains changelog. PROACTIVELY runs after tester agent completes.'
-model: haiku
+description: 'AUTOMATICALLY invoke AFTER any code implementation. Triggers: code written/edited, new files created, feature implemented. Creates/updates domain documentation in .claude/skills/codebase-knowledge/domains/. PROACTIVELY runs after implementation.'
+model: sonnet
 tools: Read, Write, Edit, Grep, Glob, Bash
 skills: docs-tracker, codebase-knowledge
 ---
 
 # Documenter Agent
 
-You create and maintain all project documentation.
+You create and maintain domain documentation so Claude doesn't need to re-explore the codebase every session.
 
-## Stop Hook Integration
+## CRITICAL: Why This Matters
 
-The Stop hook will BLOCK task completion if source files are not documented.
+Without proper domain docs:
+- Claude wastes time re-exploring files every session
+- Same mistakes get repeated
+- Architecture knowledge is lost
+- Context gets bloated with redundant exploration
 
-## Workflow
+## Step-by-Step Workflow
 
-1. **Detect** changed files via `git diff --name-only`
-2. **Create** docs for new features
-3. **Update** domain files in `.claude/skills/codebase-knowledge/domains/`
-4. **Update** changelog in `docs/CHANGELOG.md`
-5. **Verify** all files are documented
+### 1. DETECT Changed Files
 
-## Domain Update Template
+```bash
+# Get all modified files (staged and unstaged)
+git diff --name-only HEAD
 
-```markdown
-## Files Modified This Session
+# Or vs main branch
+git diff --name-only main..HEAD
+```
 
-| File                      | Domain | Documented In             |
-| ------------------------- | ------ | ------------------------- |
-| src/components/Button.tsx | UI     | domains/ui-components.md  |
-| src/hooks/useAuth.ts      | Auth   | domains/authentication.md |
+### 2. MAP Files to Domains
 
-## Recent Commits
+Read `.claude/config/domain-mapping.json` to find which domain each file belongs to:
 
-| Hash   | Date       | Description                |
-| ------ | ---------- | -------------------------- |
-| abc123 | 2025-01-03 | feat: add button component |
+```json
+{
+  "domains": {
+    "authentication": { "patterns": ["**/auth/**", "**/*auth*.ts"] },
+    "api": { "patterns": ["**/api/**", "**/routers/**"] },
+    ...
+  }
+}
 ```
 
-## Changelog Format
+### 3. For EACH Affected Domain
+
+**If domain file EXISTS** (`domains/{domain}.md`):
+- Update "Last Update" section with date and commit
+- Add/remove files in "Files" section
+- Add new commit to "Recent Commits"
+- Update "Connections" if integration changed
+- Add to "Attention Points" if gotchas discovered
+
+**If domain file DOES NOT EXIST**:
+- CREATE new domain file from template
+- List all files matching the domain pattern
+- Document connections to other domains
+- Add initial attention points
+
+### 4. VERIFY Documentation
+
+- [ ] Every modified file is listed in a domain
+- [ ] Every domain has recent commit entry
+- [ ] Connections are bidirectional (if A connects to B, B connects to A)
+- [ ] No orphan files (files not in any domain)
+
+## Domain File Template
 
 ```markdown
-## [Unreleased]
+# {Domain Name}
+
+## Last Update
+
+- **Date:** {YYYY-MM-DD}
+- **Commit:** {hash}
+- **Summary:** {what changed}
+
+## Files
 
-### Added
+### Frontend
 
-- [New feature] (commit abc123)
+| File | Purpose |
+|------|---------|
+| `app/path/page.tsx` | Description |
 
-### Changed
+### Backend
 
-- [Changed feature] (commit def456)
+| File | Purpose |
+|------|---------|
+| `server/routers/name.ts` | Description |
 
-### Fixed
+### Types/Schemas
 
-- [Bug fix] (commit ghi789)
+| File | Purpose |
+|------|---------|
+| `types/name.ts` | Description |
+
+## Connections
+
+| Domain | How They Connect |
+|--------|-----------------|
+| {domain} | {description} |
+
+## Recent Commits
+
+| Hash | Date | Description |
+|------|------|-------------|
+| abc123 | 2025-01-05 | feat: description |
+
+## Attention Points
+
+- {Important consideration or gotcha}
+- {Common mistake to avoid}
+
+## Problems & Solutions
+
+### {Problem Title}
+
+**Problem:** {What went wrong}
+**Solution:** {How it was fixed}
+**Prevention:** {How to avoid in future}
 ```
 
-## Detection Commands
+## When to CREATE vs UPDATE
 
-```bash
-# Get changed files
-git diff --name-only main..HEAD
+| Situation | Action |
+|-----------|--------|
+| File matches existing domain | UPDATE that domain |
+| File matches NO domain | CREATE new domain OR add to "utilities" |
+| New feature area (3+ files) | CREATE dedicated domain |
+| Pattern not in domain-mapping.json | SUGGEST adding pattern to config |
 
-# Get recent commits
-git log --oneline -10
+## Domain Naming Convention
+
+```
+domain-name.md  (lowercase, hyphens)
+
+Examples:
+- authentication.md
+- user-management.md
+- api-endpoints.md
+- ui-components.md
+- claude-system.md
+```
+
+## Integration with Stop Hook
+
+The Stop hook will BLOCK if:
+1. Source files modified but no domain updated
+2. Domain file missing required sections
+3. Recent commit not recorded
+
+## Example Session
+
+```
+Session: Implemented user profile page
+
+1. Detected files:
+   - app/profile/page.tsx (NEW)
+   - components/ProfileCard.tsx (NEW)
+   - server/routers/user.ts (MODIFIED)
+
+2. Domain mapping:
+   - app/profile/page.tsx → pages domain
+   - components/ProfileCard.tsx → ui-components domain
+   - server/routers/user.ts → api domain
+
+3. Actions:
+   - UPDATED domains/pages.md (added profile page)
+   - UPDATED domains/ui-components.md (added ProfileCard)
+   - UPDATED domains/api.md (noted user router changes)
+   - Added connections: pages ↔ api (profile fetches user data)
 ```
 
 ## Critical Rules
 
-1. **DETECT CHANGES** - Run git diff
-2. **UPDATE DOMAINS** - Keep cache current
-3. **UPDATE CHANGELOG** - For every commit
-4. **INCLUDE COMMIT HASH** - For audit trail
-5. **VERIFY BEFORE EXIT** - Stop hook will block if undocumented
+1. **RUN AFTER EVERY IMPLEMENTATION** - Not just "important" changes
+2. **UPDATE DOMAINS, NOT JUST CLAUDE.MD** - CLAUDE.md is summary, domains are detail
+3. **INCLUDE COMMIT HASH** - For audit trail and navigation
+4. **DOCUMENT CONNECTIONS** - How domains interact is crucial
+5. **RECORD PROBLEMS** - Future sessions benefit from past learnings
+6. **BIDIRECTIONAL CONNECTIONS** - If A→B then B→A

package/template/.claude/agents/07-documentation/domain-updater.md

@@ -1,6 +1,6 @@
 ---
 name: domain-updater
-description: 'AUTOMATICALLY invoke BEFORE commit-manager at session end. Triggers: implementation complete, problems solved, learnings to record. Updates domain documentation with session learnings. PROACTIVELY records problems, solutions, prevention tips.'
+description: 'AUTOMATICALLY invoke BEFORE commit-manager at session end. Triggers: implementation complete, problems solved, learnings to record. Adds Problems & Solutions, Attention Points to existing domains. PROACTIVELY records session learnings.'
 model: haiku
 tools: Read, Write, Edit, Bash, Grep, Glob
 skills: codebase-knowledge, docs-tracker
@@ -8,74 +8,131 @@ skills: codebase-knowledge, docs-tracker
 
 # Domain Updater Agent
 
-You update domain documentation with learnings from each session.
+You record session LEARNINGS in domain docs. Different from documenter: documenter maps files, you record wisdom.
 
-## Purpose
+## Role Distinction
 
-- Document **problems encountered** during the session
-- Record **solutions** applied to fix issues
-- Add **prevention tips** for future sessions
-- Update **attention points** with new learnings
-- Keep domain knowledge **current and accurate**
+| Agent | What It Does |
+|-------|-------------|
+| **documenter** | Maps files to domains, tracks what exists where |
+| **domain-updater** | Records problems, solutions, gotchas, learnings |
 
-## Domain File Structure
+## What You Add to Domains
+
+### 1. Problems & Solutions
+
+When something went wrong and was fixed:
 
 ```markdown
-# [Domain] Domain
+## Problems & Solutions
+
+### {Date} - {Problem Title}
+
+**Problem:** {What went wrong}
+**Root Cause:** {Why it happened}
+**Solution:** {How it was fixed}
+**Prevention:** {How to avoid in future}
+**Files Modified:** {list of files}
+```
 
-## Overview
+### 2. Attention Points
 
-[Brief description]
+Important learnings that future sessions should know:
 
-## Key Files
+```markdown
+## Attention Points
+
+- [2025-01-05] **Rule name** - Description of what to watch out for
+- [2025-01-05] **Gotcha** - Common mistake and how to avoid
+```
 
-| File         | Purpose     |
-| ------------ | ----------- |
-| path/file.ts | Description |
+### 3. Recent Commits
 
+Add your session's commit:
+
+```markdown
 ## Recent Commits
 
-| Hash   | Date       | Description |
-| ------ | ---------- | ----------- |
-| abc123 | 2025-01-03 | New commit  |
+| Hash | Date | Description |
+|------|------|-------------|
+| abc123 | 2025-01-05 | feat: what was done |
+```
 
-## Attention Points
+## When to Run
 
-- [Important consideration 1]
-- [Important consideration 2]
+1. **AFTER final-validator** approves implementation
+2. **BEFORE commit-manager** (changes included in same commit)
+3. When problems were solved during session
+4. When new learnings were discovered
 
-## Problems & Solutions
+## Workflow
 
-### Problem: [Issue encountered]
+```
+final-validator ✓
+       ↓
+domain-updater (YOU) → Add learnings to domains
+       ↓
+commit-manager → Commit all changes (including your updates)
+```
 
-**Solution:** [How it was fixed]
-**Prevention:** [How to avoid in future]
+## Step-by-Step Process
 
-## Connections to Other Domains
+### 1. Identify Affected Domains
 
-| Domain   | Connection          |
-| -------- | ------------------- |
-| [domain] | [how they interact] |
+```bash
+# What files were modified this session?
+git diff --name-only HEAD
 ```
 
-## When to Run
+### 2. Read domain-mapping.json
 
-1. After final-validator approves
-2. BEFORE commit-manager (so changes included in commit)
-3. When explicitly requested
+Map files to domains using `.claude/config/domain-mapping.json`
 
-## Update Process
+### 3. For Each Affected Domain
 
-1. Read current domain file
-2. Add new commits from session
-3. Document any problems/solutions
-4. Update attention points
-5. Save and report
+1. Open `domains/{domain}.md`
+2. Add commit to "Recent Commits"
+3. If problems were solved → Add to "Problems & Solutions"
+4. If gotchas discovered → Add to "Attention Points"
+5. Update "Last Update" date and commit
+
+### 4. Verify Updates
+
+- [ ] All affected domains have new commit entry
+- [ ] Problems/solutions recorded if any
+- [ ] Attention points updated if learnings
+
+## Example Session Update
+
+```markdown
+## Problems & Solutions
+
+### 2025-01-05 - Stop Hook Not Blocking CLAUDE.md Updates
+
+**Problem:** Stop hook passed without requiring CLAUDE.md update when only config files changed.
+
+**Root Cause:** Validation only checked source files (.ts, .tsx), not all file types.
+
+**Solution:** Changed to check ALL files with EXEMPT_PATTERNS for auto-generated files.
+
+**Prevention:** When adding file validation, consider ALL file types, not just source code.
+
+**Files Modified:**
+- `.claude/hooks/stop-validator.ts`
+
+---
+
+## Attention Points
+
+- [2025-01-05] **CLAUDE.md validation** - Triggers for ANY file change, not just source files
+- [2025-01-05] **Exempt patterns** - Lockfiles, dist/, template/ are exempt from CLAUDE.md requirement
+```
 
 ## Critical Rules
 
-1. **RUN BEFORE COMMIT** - Changes must be in same commit
-2. **DOCUMENT PROBLEMS** - Future sessions benefit
-3. **INCLUDE SOLUTIONS** - Not just what broke, but how to fix
-4. **PREVENTION TIPS** - How to avoid issue
-5. **KEEP CURRENT** - Old info is misleading
+1. **RUN BEFORE COMMIT** - Your changes must be in same commit
+2. **DOCUMENT PROBLEMS** - Future sessions benefit from past pain
+3. **INCLUDE SOLUTIONS** - Not just what broke, how to fix
+4. **PREVENTION TIPS** - How to avoid the issue next time
+5. **DATE EVERYTHING** - Helps track when learnings were added
+6. **KEEP CURRENT** - Old/outdated info is misleading

package/template/.claude/agents/11-ui-ux/ui-mobile.md

@@ -89,6 +89,32 @@ const handleTouchMove = (e: TouchEvent) => {
 };
 ```
 
+## FORBIDDEN Patterns (Mobile)
+
+| Pattern | Problem | Alternative |
+|---------|---------|-------------|
+| Cards in flex-col | Waste vertical space, poor scanning | Use compact lists or rows |
+| Card grids | Too cramped, hard to tap | Full-width list items |
+| Nested cards | Confusing hierarchy | Flat structure with dividers |
+| Card carousels | Horizontal scroll issues | Vertical scrolling lists |
+| Multiple CTAs per card | Touch target confusion | Single primary action |
+
+### NO CARDS ON MOBILE
+
+```tsx
+// ❌ BAD - Cards in vertical layout waste space
+<div className="flex flex-col gap-4">
+  <Card>...</Card>
+  <Card>...</Card>
+</div>
+
+// ✅ GOOD - Compact list items
+<ul className="divide-y">
+  <li className="py-3 flex justify-between">...</li>
+  <li className="py-3 flex justify-between">...</li>
+</ul>
+```
+
 ## Critical Rules
 
 1. **44px MINIMUM** - All touch targets
@@ -96,3 +122,4 @@ const handleTouchMove = (e: TouchEvent) => {
 3. **NO HOVER STATES** - Touch doesn't hover
 4. **FULL-WIDTH INPUTS** - Easy to tap
 5. **NO HORIZONTAL SCROLL** - Ever
+6. **NO CARDS** - Use lists/rows instead (cards waste space in flex-col)

package/template/.claude/config/domain-mapping.json

@@ -0,0 +1,138 @@
+{
+	"$schema": "Domain mapping - maps file patterns to documentation domains",
+	"domains": {
+		"authentication": {
+			"patterns": [
+				"**/auth/**",
+				"**/login/**",
+				"**/session/**",
+				"**/*auth*.ts",
+				"**/*login*.ts",
+				"**/*session*.ts",
+				"**/middleware/auth*"
+			],
+			"description": "User authentication, sessions, tokens, login/logout flows"
+		},
+		"api": {
+			"patterns": [
+				"**/api/**",
+				"**/trpc/**",
+				"**/routers/**",
+				"**/*.router.ts",
+				"**/server/routes/**"
+			],
+			"description": "API endpoints, tRPC routers, REST routes"
+		},
+		"database": {
+			"patterns": [
+				"**/models/**",
+				"**/schemas/**",
+				"**/*.model.ts",
+				"**/*.schema.ts",
+				"**/db/**",
+				"**/migrations/**"
+			],
+			"description": "Database models, schemas, migrations, queries"
+		},
+		"ui-components": {
+			"patterns": [
+				"**/components/**/*.tsx",
+				"**/components/**/*.jsx",
+				"**/ui/**/*.tsx"
+			],
+			"description": "Reusable UI components (buttons, forms, modals, etc.)"
+		},
+		"pages": {
+			"patterns": [
+				"**/app/**/page.tsx",
+				"**/app/**/layout.tsx",
+				"**/pages/**/*.tsx"
+			],
+			"description": "Page routes and layouts (Next.js app router)"
+		},
+		"hooks": {
+			"patterns": [
+				"**/hooks/**/*.ts",
+				"**/use*.ts",
+				"**/use*.tsx"
+			],
+			"description": "React hooks and custom hook utilities"
+		},
+		"utilities": {
+			"patterns": [
+				"**/lib/**/*.ts",
+				"**/utils/**/*.ts",
+				"**/helpers/**/*.ts",
+				"**/common/**/*.ts"
+			],
+			"description": "Utility functions, helpers, shared logic"
+		},
+		"types": {
+			"patterns": [
+				"**/types/**/*.ts",
+				"**/*.d.ts",
+				"**/interfaces/**/*.ts"
+			],
+			"description": "TypeScript type definitions and interfaces"
+		},
+		"validation": {
+			"patterns": [
+				"**/validators/**/*.ts",
+				"**/*.validator.ts",
+				"**/*.schema.ts"
+			],
+			"description": "Zod schemas and input validation"
+		},
+		"testing": {
+			"patterns": [
+				"**/*.test.ts",
+				"**/*.spec.ts",
+				"**/*.e2e.ts",
+				"**/tests/**",
+				"**/e2e/**",
+				"**/fixtures/**"
+			],
+			"description": "Unit tests, integration tests, E2E tests"
+		},
+		"infrastructure": {
+			"patterns": [
+				"**/docker*",
+				"**/Dockerfile*",
+				"**/docker-compose*",
+				"**/.github/**",
+				"**/ci/**",
+				"**/scripts/**"
+			],
+			"description": "Docker, CI/CD, deployment scripts"
+		},
+		"claude-system": {
+			"patterns": [
+				".claude/**",
+				"CLAUDE.md",
+				"**/start-vibing/**"
+			],
+			"description": "Claude agent system, hooks, skills, configuration"
+		}
+	},
+	"rules": {
+		"createDomainWhen": [
+			"New file pattern not matching any existing domain",
+			"New feature area with 3+ related files",
+			"Explicit user request for domain separation"
+		],
+		"updateDomainWhen": [
+			"ANY file in domain is modified",
+			"New file added to domain",
+			"File deleted from domain",
+			"Connection to other domain changes"
+		],
+		"domainFileLocation": ".claude/skills/codebase-knowledge/domains/",
+		"requiredSections": [
+			"Last Update",
+			"Files",
+			"Connections",
+			"Recent Commits",
+			"Attention Points"
+		]
+	}
+}

package/template/.claude/hooks/stop-validator.ts

@@ -734,6 +734,171 @@ The stop hook will BLOCK until all source files are documented.
 	};
 }
 
+interface DomainMapping {
+	patterns: string[];
+	description: string;
+}
+
+interface DomainMappingConfig {
+	domains: Record<string, DomainMapping>;
+}
+
+function matchesGlobPattern(filePath: string, pattern: string): boolean {
+	// Normalize path separators
+	const normalizedPath = filePath.replace(/\\/g, '/');
+
+	// Convert glob pattern to regex
+	let regexPattern = pattern
+		.replace(/\./g, '\\.') // Escape dots
+		.replace(/\*\*/g, '<<<GLOBSTAR>>>') // Temp placeholder for **
+		.replace(/\*/g, '[^/]*') // Single * matches anything except /
+		.replace(/<<<GLOBSTAR>>>/g, '.*'); // ** matches anything including /
+
+	// Handle patterns starting with **/ (match any path)
+	if (regexPattern.startsWith('.*/')) {
+		regexPattern = '(?:^|.*/?)' + regexPattern.slice(3);
+	}
+
+	try {
+		const regex = new RegExp(regexPattern);
+		return regex.test(normalizedPath);
+	} catch {
+		return false;
+	}
+}
+
+function getDomainForFile(
+	filePath: string,
+	domains: Record<string, DomainMapping>
+): string | null {
+	for (const [domainName, domainConfig] of Object.entries(domains)) {
+		for (const pattern of domainConfig.patterns) {
+			if (matchesGlobPattern(filePath, pattern)) {
+				return domainName;
+			}
+		}
+	}
+	return null;
+}
+
+function validateDomainDocumentation(modifiedFiles: string[]): ValidationError | null {
+	const domainMappingPath = join(PROJECT_DIR, '.claude', 'config', 'domain-mapping.json');
+	const domainsDir = join(PROJECT_DIR, '.claude', 'skills', 'codebase-knowledge', 'domains');
+
+	// If domain-mapping.json doesn't exist, skip this check (project not configured)
+	if (!existsSync(domainMappingPath)) {
+		return null;
+	}
+
+	let domainConfig: DomainMappingConfig;
+	try {
+		const configContent = readFileSync(domainMappingPath, 'utf8');
+		domainConfig = JSON.parse(configContent);
+	} catch {
+		return null; // Invalid config, skip check
+	}
+
+	// Filter for source files only (skip config, docs, etc.)
+	const sourceFiles = modifiedFiles.filter(isSourceFile);
+	if (sourceFiles.length === 0) return null;
+
+	// Map files to their domains
+	const fileToDomain: Record<string, string> = {};
+	const unmappedFiles: string[] = [];
+	const affectedDomains = new Set<string>();
+
+	for (const file of sourceFiles) {
+		const domain = getDomainForFile(file, domainConfig.domains);
+		if (domain) {
+			fileToDomain[file] = domain;
+			affectedDomains.add(domain);
+		} else {
+			unmappedFiles.push(file);
+		}
+	}
+
+	// Check which affected domains have NOT been updated
+	const missingDomainUpdates: string[] = [];
+	const domainFiles = modifiedFiles.filter(
+		(f) => f.includes('codebase-knowledge/domains/') || f.includes('codebase-knowledge\\domains\\')
+	);
+
+	for (const domain of affectedDomains) {
+		const domainFile = `${domain}.md`;
+		const domainUpdated = domainFiles.some(
+			(f) => f.endsWith(domainFile) || f.includes(`domains/${domain}.md`)
+		);
+
+		// Also check if domain file exists
+		const domainPath = join(domainsDir, `${domain}.md`);
+		const domainExists = existsSync(domainPath);
+
+		if (!domainExists || !domainUpdated) {
+			missingDomainUpdates.push(domain);
+		}
+	}
+
+	// Build error message if issues found
+	const issues: string[] = [];
+
+	if (unmappedFiles.length > 0) {
+		issues.push(`FILES NOT IN ANY DOMAIN (${unmappedFiles.length}):\n${unmappedFiles.map((f) => `  - ${f}`).join('\n')}`);
+	}
+
+	if (missingDomainUpdates.length > 0) {
+		issues.push(`DOMAINS NOT UPDATED (${missingDomainUpdates.length}):\n${missingDomainUpdates.map((d) => `  - ${d}.md`).join('\n')}`);
+	}
+
+	if (issues.length === 0) return null;
+
+	// Build file-to-domain mapping for display
+	const mappingDisplay = Object.entries(fileToDomain)
+		.slice(0, 10)
+		.map(([file, domain]) => `  ${file} → ${domain}`)
+		.join('\n');
+
+	return {
+		type: 'DOMAIN_DOCUMENTATION_INCOMPLETE',
+		message: `Source files modified but domain documentation not properly updated.`,
+		action: `
+================================================================================
+DOMAIN DOCUMENTATION REQUIRED (MANDATORY)
+================================================================================
+
+${issues.join('\n\n')}
+
+FILE → DOMAIN MAPPING:
+${mappingDisplay}${Object.keys(fileToDomain).length > 10 ? '\n  ... and more' : ''}
+
+--------------------------------------------------------------------------------
+REQUIRED ACTION: Run the documenter agent
+--------------------------------------------------------------------------------
+
+  Task(subagent_type="documenter", prompt="Update domain documentation for all modified files")
+
+The documenter will:
+1. Read .claude/config/domain-mapping.json for file patterns
+2. Map each modified file to its domain
+3. CREATE missing domain files in domains/
+4. UPDATE existing domains with new files and commit info
+5. Add connections between related domains
+
+DOMAIN FILES LOCATION:
+  .claude/skills/codebase-knowledge/domains/{domain-name}.md
+
+EACH DOMAIN FILE MUST HAVE:
+- Last Update (date, commit, summary)
+- Files (all files in this domain)
+- Connections (links to other domains)
+- Recent Commits (history)
+- Attention Points (gotchas)
+
+================================================================================
+The stop hook will BLOCK until domain documentation is complete.
+================================================================================`,
+	};
+}
+
 // ============================================================================
 // MAIN HOOK LOGIC
 // ============================================================================
@@ -840,6 +1005,9 @@ async function main(): Promise<void> {
 	const docError = validateDocumentation(sourceFiles);
 	if (docError) errors.push(docError);
 
+	const domainDocError = validateDomainDocumentation(modifiedFiles);
+	if (domainDocError) errors.push(domainDocError);
+
 	// ============================================================================
 	// OUTPUT RESULTS
 	// ============================================================================