start-vibing 2.0.7 → 2.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "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/CLAUDE.md

@@ -4,19 +4,62 @@ This file provides context for all agents. For user-facing rules, see `/CLAUDE.m
 
 ---
 
+## CLAUDE.md Validation (STOP HOOK ENFORCED)
+
+The stop hook validates `/CLAUDE.md` before allowing task completion:
+
+| Check | Requirement |
+|-------|-------------|
+| Character limit | Max 40,000 chars |
+| Required sections | Last Change, 30s Overview, Stack, Architecture |
+| Last Change | Must be updated with session info (branch, date, summary) |
+| No stacking | Only ONE Last Change section (latest only) |
+| Branch | Must be on main (PR merged) |
+| Git tree | Must be clean (no uncommitted changes) |
+
+**If CLAUDE.md exceeds 40k chars:** Compact it by removing verbose explanations, keeping critical sections.
+
+**If not on main:** Complete PR workflow (commit, push, PR, merge, checkout main).
+
+---
+
 ## System Architecture
 
 ```
 .claude/
-├── agents/          # 11 specialized agents (READ before acting)
-├── skills/          # 8 skill systems with cache
+├── agents/          # 82 specialized agents in 14 categories
+├── skills/          # 22 skill systems with cache
+├── scripts/         # Validation scripts (validate-claude-md.ts)
 ├── config/          # Project-specific configuration
 ├── commands/        # Slash commands
-└── hooks/           # Security hooks
+└── hooks/           # stop-validator.ts, user-prompt-submit.ts
 ```
 
 ---
 
+## MCP Servers (MANDATORY FOR AGENTS)
+
+All agents MUST use these MCP servers when applicable:
+
+| Server              | Purpose                                   | Use In Agents                            |
+| ------------------- | ----------------------------------------- | ---------------------------------------- |
+| `context7`          | Up-to-date library documentation          | research, analyzer, tester               |
+| `sequential-thinking` | Complex problem-solving                 | orchestrator, analyzer, final-validator  |
+| `memory`            | Persistent knowledge graph                | domain-updater, commit-manager           |
+| `playwright`        | Browser automation and E2E testing        | tester, ui-ux-reviewer                   |
+| `nextjs-devtools`   | Next.js specific development tools        | analyzer (Next.js projects)              |
+| `mongodb`           | MongoDB database operations               | tester, security-auditor                 |
+
+### Agent MCP Usage Rules
+
+- **research agent**: MUST use `context7` for library docs before recommending patterns
+- **tester agent**: MUST use `playwright` for E2E tests
+- **analyzer agent**: SHOULD use `context7` to verify current API patterns
+- **domain-updater**: SHOULD use `memory` to persist patterns across sessions
+- **ui-ux-reviewer**: MUST use `playwright` to verify UI implementations
+
+---
+
 ## Configuration Files
 
 Project-specific settings are in `.claude/config/`:

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

@@ -1,19 +1,31 @@
 #!/usr/bin/env node
 /**
- * Stop Validator Hook - TypeScript version (fallback when Python not available)
+ * Stop Validator Hook - Complete Validation System
  *
- * VALIDATES:
- * 1. NOT on main branch (unless no source changes)
- * 2. All modified files are documented
- * 3. Documenter agent was executed for source changes
+ * THIS HOOK BLOCKS TASK COMPLETION IF ANY OF THESE CONDITIONS FAIL:
  *
- * BLOCKS completion if validations fail.
+ * 1. BRANCH CHECK: Must be on 'main' branch (PR must be merged)
+ * 2. GIT TREE CHECK: Working tree must be clean (no uncommitted changes)
+ * 3. CLAUDE.MD CHECK: Must be updated with session changes
+ * 4. CLAUDE.MD STRUCTURE: Must have required sections
+ * 5. CLAUDE.MD SIZE: Must not exceed 40,000 characters
+ * 6. DOCUMENTATION CHECK: All source files must be documented
+ *
+ * ERROR MESSAGES ARE DESCRIPTIVE: They guide the agent on exactly what to do.
  */
 
 import { execSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, basename, extname } from 'path';
 
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+const CLAUDE_MD_PATH = join(PROJECT_DIR, 'CLAUDE.md');
+const MAX_CHARACTERS = 40000;
+
 const IGNORE_DIRS = new Set([
   '.next', 'node_modules', 'dist', 'build', 'coverage',
   '.git', '__pycache__', '.turbo', '.cache', '.husky',
@@ -32,24 +44,27 @@ const SOURCE_EXTENSIONS = new Set([
   '.java', '.kt', '.swift', '.vue', '.svelte'
 ]);
 
-const SYSTEM_CONFIG_PATTERNS = [
-  'CLAUDE.md',
-  '.claude/',
-  'PROJECT.md',
-  '.env.example',
+// Required sections in CLAUDE.md
+const REQUIRED_SECTIONS = [
+  { pattern: /^# .+/m, name: 'Project Title (H1)' },
+  { pattern: /^## Last Change/m, name: 'Last Change' },
+  { pattern: /^## 30 Seconds Overview/m, name: '30 Seconds Overview' },
+  { pattern: /^## Stack/m, name: 'Stack' },
+  { pattern: /^## Architecture/m, name: 'Architecture' },
 ];
 
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
 function shouldIgnoreFile(filePath: string): boolean {
   const parts = filePath.split(/[/\\]/);
-
   for (const part of parts) {
     if (IGNORE_DIRS.has(part)) return true;
   }
-
   for (const pattern of IGNORE_PATTERNS) {
     if (filePath.includes(pattern)) return true;
   }
-
   return false;
 }
 
@@ -58,39 +73,34 @@ function isSourceFile(filePath: string): boolean {
   return SOURCE_EXTENSIONS.has(ext) && !shouldIgnoreFile(filePath);
 }
 
-function isSystemConfigFile(filePath: string): boolean {
-  return SYSTEM_CONFIG_PATTERNS.some(pattern => filePath.includes(pattern));
-}
-
-function getCurrentBranch(projectDir: string): string {
+function getCurrentBranch(): string {
   try {
-    const result = execSync('git rev-parse --abbrev-ref HEAD', {
-      cwd: projectDir,
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: PROJECT_DIR,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe']
-    });
-    return result.trim();
+    }).trim();
   } catch {
     return 'unknown';
   }
 }
 
-function getModifiedFiles(projectDir: string): string[] {
+function getModifiedFiles(): string[] {
   try {
     const staged = execSync('git diff --name-only --cached', {
-      cwd: projectDir,
+      cwd: PROJECT_DIR,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe']
     }).trim().split('\n').filter(Boolean);
 
     const unstaged = execSync('git diff --name-only', {
-      cwd: projectDir,
+      cwd: PROJECT_DIR,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe']
     }).trim().split('\n').filter(Boolean);
 
     const untracked = execSync('git ls-files --others --exclude-standard', {
-      cwd: projectDir,
+      cwd: PROJECT_DIR,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe']
     }).trim().split('\n').filter(Boolean);
@@ -103,7 +113,6 @@ function getModifiedFiles(projectDir: string): string[] {
 
 function* walkDir(dir: string): Generator<string> {
   if (!existsSync(dir)) return;
-
   const entries = readdirSync(dir);
   for (const entry of entries) {
     const fullPath = join(dir, entry);
@@ -120,22 +129,20 @@ function* walkDir(dir: string): Generator<string> {
   }
 }
 
-function searchInDocs(projectDir: string, filePath: string): boolean {
+function searchInDocs(filePath: string): boolean {
   const fileName = basename(filePath);
   const fileStem = basename(filePath, extname(filePath));
 
   const docDirs = [
-    join(projectDir, 'docs'),
-    join(projectDir, '.claude', 'skills', 'codebase-knowledge', 'domains'),
+    join(PROJECT_DIR, 'docs'),
+    join(PROJECT_DIR, '.claude', 'skills', 'codebase-knowledge', 'domains'),
   ];
 
   for (const docDir of docDirs) {
     if (!existsSync(docDir)) continue;
-
     for (const docFile of walkDir(docDir)) {
       const ext = extname(docFile);
       if (!DOC_EXTENSIONS.has(ext)) continue;
-
       try {
         const content = readFileSync(docFile, 'utf8');
         if (content.includes(fileName) || content.includes(fileStem) || content.includes(filePath)) {
@@ -146,27 +153,456 @@ function searchInDocs(projectDir: string, filePath: string): boolean {
       }
     }
   }
-
   return false;
 }
 
-function validateDocumentation(projectDir: string, modifiedFiles: string[]): { undocumented: string[], documented: string[] } {
-  const undocumented: string[] = [];
-  const documented: string[] = [];
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+
+interface ValidationError {
+  type: string;
+  message: string;
+  action: string;
+}
+
+function validateBranch(currentBranch: string, modifiedFiles: string[]): ValidationError | null {
+  const isMainBranch = currentBranch === 'main' || currentBranch === 'master';
+
+  // Case 1: On feature branch with changes - need to complete workflow
+  if (!isMainBranch && modifiedFiles.length > 0) {
+    return {
+      type: 'FEATURE_BRANCH_NOT_MERGED',
+      message: `Currently on branch '${currentBranch}' with uncommitted changes. The task cannot complete until work is merged to main.`,
+      action: `
+================================================================================
+COMPLETE THE GIT WORKFLOW BEFORE TASK COMPLETION
+================================================================================
+
+You are on branch '${currentBranch}' with ${modifiedFiles.length} modified file(s).
+
+REQUIRED STEPS (execute in order):
+
+1. STAGE all changes:
+   git add -A
+
+2. COMMIT with conventional message:
+   git commit -m "feat: description of changes"
+
+3. PUSH to remote:
+   git push -u origin ${currentBranch}
+
+4. CREATE Pull Request:
+   gh pr create --title "Title" --body "$(cat <<'EOF'
+## Summary
+- What was changed
+
+## Test plan
+- How to verify
+
+Generated with Claude Code
+EOF
+)"
+
+5. MERGE the PR (auto-delete branch):
+   gh pr merge --merge --delete-branch
+
+6. SWITCH to main and pull:
+   git checkout main && git pull
+
+THEN the task can complete. The stop hook will verify main branch + clean tree.
+================================================================================`
+    };
+  }
+
+  // Case 2: On feature branch with clean tree - just need to switch
+  if (!isMainBranch && modifiedFiles.length === 0) {
+    return {
+      type: 'NOT_ON_MAIN_BRANCH',
+      message: `Currently on branch '${currentBranch}'. Task completion requires being on 'main'.`,
+      action: `
+================================================================================
+SWITCH TO MAIN BRANCH
+================================================================================
+
+The working tree is clean but you're on branch '${currentBranch}'.
+
+If your PR was merged:
+   git checkout main && git pull
+
+If you still need to create/merge PR:
+   gh pr create (if not created)
+   gh pr merge --merge --delete-branch (to merge)
+   git checkout main && git pull
+
+IMPORTANT: Task completion is BLOCKED until you are on 'main' with a clean tree.
+================================================================================`
+    };
+  }
+
+  // Case 3: On main with changes - FORBIDDEN
+  if (isMainBranch && modifiedFiles.length > 0) {
+    const fileList = modifiedFiles.slice(0, 10).map(f => `  - ${f}`).join('\n');
+    return {
+      type: 'DIRECT_MAIN_COMMIT_FORBIDDEN',
+      message: `CRITICAL: Attempting to work directly on '${currentBranch}' branch with changes!`,
+      action: `
+================================================================================
+FORBIDDEN: DIRECT COMMITS TO MAIN
+================================================================================
+
+You have ${modifiedFiles.length} modified file(s) on main branch:
+${fileList}${modifiedFiles.length > 10 ? '\n  ... and more' : ''}
+
+ALL work MUST be done on feature branches. This is MANDATORY.
+
+REQUIRED STEPS:
+
+1. CREATE a feature branch:
+   git checkout -b feature/your-feature-name
+   (or fix/, refactor/, chore/, test/ as appropriate)
+
+2. CONTINUE your work on the new branch
+
+3. When done, create PR to merge back to main
+
+NEVER commit directly to main. The stop hook will BLOCK this.
+================================================================================`
+    };
+  }
+
+  return null; // All good - on main with clean tree
+}
+
+function validateGitTree(modifiedFiles: string[]): ValidationError | null {
+  if (modifiedFiles.length === 0) return null;
+
+  const fileList = modifiedFiles.slice(0, 15).map(f => `  - ${f}`).join('\n');
+
+  return {
+    type: 'GIT_TREE_NOT_CLEAN',
+    message: `Git working tree is not clean. Found ${modifiedFiles.length} modified/untracked file(s).`,
+    action: `
+================================================================================
+GIT TREE MUST BE CLEAN FOR TASK COMPLETION
+================================================================================
+
+Modified files:
+${fileList}${modifiedFiles.length > 15 ? '\n  ... and more' : ''}
+
+The task cannot complete with uncommitted work.
+
+OPTIONS:
+
+1. COMMIT the changes (recommended):
+   git add -A
+   git commit -m "type: description"
+   git push
+
+2. STASH for later:
+   git stash push -m "WIP: description"
+
+3. DISCARD changes (use with caution):
+   git checkout -- .
+   git clean -fd
+
+After cleaning the tree, the stop hook will pass.
+================================================================================`
+  };
+}
+
+function validateClaudeMdExists(): ValidationError | null {
+  if (!existsSync(CLAUDE_MD_PATH)) {
+    return {
+      type: 'CLAUDE_MD_MISSING',
+      message: 'CLAUDE.md file not found at project root.',
+      action: `
+================================================================================
+CLAUDE.MD IS REQUIRED
+================================================================================
+
+The project MUST have a CLAUDE.md file at the root with these sections:
+
+# Project Name
+
+## Last Change
+**Branch:** branch-name
+**Date:** YYYY-MM-DD
+**Summary:** What was done in this session
+
+## 30 Seconds Overview
+Quick description of what this project does.
+
+## Stack
+| Component | Technology |
+|-----------|------------|
+| Runtime   | Bun        |
+| Language  | TypeScript |
+| Database  | MongoDB    |
+
+## Architecture
+Project structure and key directories.
+
+CREATE this file before the task can complete.
+================================================================================`
+    };
+  }
+  return null;
+}
+
+function validateClaudeMdSize(): ValidationError | null {
+  if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+  const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+  if (content.length <= MAX_CHARACTERS) return null;
+
+  const excess = content.length - MAX_CHARACTERS;
+
+  return {
+    type: 'CLAUDE_MD_SIZE_EXCEEDED',
+    message: `CLAUDE.md exceeds 40,000 character limit by ${excess} characters (current: ${content.length}).`,
+    action: `
+================================================================================
+CLAUDE.MD MUST BE COMPACTED (MAX 40,000 CHARACTERS)
+================================================================================
+
+Current size: ${content.length} characters
+Maximum allowed: ${MAX_CHARACTERS} characters
+Excess: ${excess} characters
+
+COMPACTION RULES (what to keep vs remove):
+
+KEEP (critical):
+- # Project Title
+- ## Last Change (only the MOST RECENT)
+- ## 30 Seconds Overview
+- ## Stack
+- ## Architecture
+- ## Critical Rules
+- ## FORBIDDEN Actions
+- ## Quality Gates
+
+REMOVE/CONDENSE:
+- Verbose explanations (use bullet points)
+- Duplicate information
+- Old/outdated sections
+- Long code examples (keep minimal)
+- Multiple "Last Change" entries (keep only latest)
+
+After editing, verify: wc -m CLAUDE.md
+================================================================================`
+  };
+}
+
+function validateClaudeMdStructure(): ValidationError | null {
+  if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+  const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+  const missingSections: string[] = [];
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!section.pattern.test(content)) {
+      missingSections.push(section.name);
+    }
+  }
+
+  if (missingSections.length === 0) return null;
+
+  return {
+    type: 'CLAUDE_MD_MISSING_SECTIONS',
+    message: `CLAUDE.md is missing required sections: ${missingSections.join(', ')}`,
+    action: `
+================================================================================
+CLAUDE.MD MISSING REQUIRED SECTIONS
+================================================================================
+
+Missing sections:
+${missingSections.map(s => `  - ${s}`).join('\n')}
+
+REQUIRED STRUCTURE:
+
+# Project Name                    <- H1 title
+
+## Last Change                    <- ONLY the most recent change
+**Branch:** feature/xxx
+**Date:** YYYY-MM-DD
+**Summary:** What was done
 
-  for (const filePath of modifiedFiles) {
-    if (!isSourceFile(filePath)) continue;
+## 30 Seconds Overview            <- Quick project description
 
-    if (searchInDocs(projectDir, filePath)) {
-      documented.push(filePath);
-    } else {
+## Stack                          <- Technology table
+
+## Architecture                   <- Project structure
+
+ADD the missing sections before the task can complete.
+================================================================================`
+  };
+}
+
+function validateClaudeMdLastChange(): ValidationError | null {
+  if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+  const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+  const lastChangeMatch = content.match(/## Last Change\n([\s\S]*?)(?=\n## |$)/);
+
+  if (!lastChangeMatch) return null; // Covered by structure check
+
+  const lastChangeContent = lastChangeMatch[1].trim();
+
+  // Check for meaningful content
+  if (lastChangeContent.length < 50) {
+    return {
+      type: 'CLAUDE_MD_LAST_CHANGE_EMPTY',
+      message: 'The "Last Change" section exists but lacks sufficient content.',
+      action: `
+================================================================================
+UPDATE "LAST CHANGE" SECTION
+================================================================================
+
+The "## Last Change" section must contain:
+
+**Branch:** the-branch-name-used
+**Date:** ${new Date().toISOString().split('T')[0]}
+**Summary:** 1-2 sentences describing what was changed/implemented
+
+Example:
+## Last Change
+
+**Branch:** feature/add-auth
+**Date:** 2025-01-05
+**Summary:** Implemented JWT authentication with refresh tokens and session management.
+
+IMPORTANT: This section should ONLY contain the LAST change, not a history.
+================================================================================`
+    };
+  }
+
+  // Check for multiple Last Change sections (stacking is forbidden)
+  const multipleChanges = content.match(/## Last Change/g);
+  if (multipleChanges && multipleChanges.length > 1) {
+    return {
+      type: 'CLAUDE_MD_STACKED_CHANGES',
+      message: `Found ${multipleChanges.length} "## Last Change" sections. Only ONE is allowed.`,
+      action: `
+================================================================================
+REMOVE STACKED CHANGES - KEEP ONLY THE LATEST
+================================================================================
+
+Rule: CLAUDE.md should only have ONE "## Last Change" section.
+Previous changes belong in git history, not in the documentation.
+
+Found ${multipleChanges.length} instances of "## Last Change".
+
+ACTION: Remove all but the most recent "## Last Change" section.
+
+This keeps the file focused and within the 40k character limit.
+================================================================================`
+    };
+  }
+
+  return null;
+}
+
+function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
+  // If no source files modified, no need to check
+  const sourceFiles = modifiedFiles.filter(isSourceFile);
+  if (sourceFiles.length === 0) return null;
+
+  // Check if CLAUDE.md is in the modified files
+  const claudeMdModified = modifiedFiles.some(f =>
+    f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')
+  );
+
+  if (claudeMdModified) return null;
+
+  return {
+    type: 'CLAUDE_MD_NOT_UPDATED',
+    message: `${sourceFiles.length} source file(s) were modified but CLAUDE.md was not updated.`,
+    action: `
+================================================================================
+UPDATE CLAUDE.MD WITH SESSION CHANGES (MANDATORY)
+================================================================================
+
+You modified source files but did not update CLAUDE.md.
+
+Modified source files:
+${sourceFiles.slice(0, 10).map(f => `  - ${f}`).join('\n')}${sourceFiles.length > 10 ? '\n  ... and more' : ''}
+
+REQUIRED UPDATES TO CLAUDE.MD:
+
+1. Update "## Last Change" section:
+   **Branch:** current-branch-name
+   **Date:** ${new Date().toISOString().split('T')[0]}
+   **Summary:** What you implemented/fixed
+
+2. If architecture changed:
+   Update "## Architecture" section
+
+3. If new patterns/rules were established:
+   Add to appropriate section
+
+4. If user mentioned preferences or corrections:
+   Add as rules in relevant section
+
+CONTEXT SYNTHESIS:
+Think about what the user asked and what you learned.
+Capture important decisions and patterns for the next session.
+
+The stop hook will BLOCK until CLAUDE.md is updated.
+================================================================================`
+  };
+}
+
+function validateDocumentation(sourceFiles: string[]): ValidationError | null {
+  if (sourceFiles.length === 0) return null;
+
+  const undocumented: string[] = [];
+  for (const filePath of sourceFiles) {
+    if (!searchInDocs(filePath)) {
       undocumented.push(filePath);
     }
   }
 
-  return { undocumented, documented };
+  if (undocumented.length === 0) return null;
+
+  const fileList = undocumented.slice(0, 15).map(f => `  - ${f}`).join('\n');
+
+  return {
+    type: 'SOURCE_FILES_NOT_DOCUMENTED',
+    message: `${undocumented.length} source file(s) are not documented.`,
+    action: `
+================================================================================
+DOCUMENT ALL MODIFIED SOURCE FILES (MANDATORY)
+================================================================================
+
+Undocumented files:
+${fileList}${undocumented.length > 15 ? '\n  ... and more' : ''}
+
+REQUIRED ACTION:
+
+Run the documenter agent to update documentation:
+
+  Task(subagent_type="documenter", prompt="Update documentation for all modified files")
+
+The documenter will:
+1. Detect changed files via git diff
+2. Update domain files in .claude/skills/codebase-knowledge/domains/
+3. Update docs/ as needed
+4. Ensure all modified files are mentioned in documentation
+
+A file is considered documented if its name appears in:
+- docs/ folder
+- .claude/skills/codebase-knowledge/domains/ folder
+
+The stop hook will BLOCK until all source files are documented.
+================================================================================`
+  };
 }
 
+// ============================================================================
+// MAIN HOOK LOGIC
+// ============================================================================
+
 interface HookInput {
   stop_hook_active?: boolean;
 }
@@ -205,8 +641,6 @@ async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
 }
 
 async function main(): Promise<void> {
-  const projectDir = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
-
   let hookInput: HookInput = {};
   try {
     const stdin = await readStdinWithTimeout(1000);
@@ -224,122 +658,107 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
-  const currentBranch = getCurrentBranch(projectDir);
-  const modifiedFiles = getModifiedFiles(projectDir);
+  // Gather state
+  const currentBranch = getCurrentBranch();
+  const modifiedFiles = getModifiedFiles();
   const sourceFiles = modifiedFiles.filter(isSourceFile);
-  const systemConfigFiles = modifiedFiles.filter(isSystemConfigFile);
+  const isMainBranch = currentBranch === 'main' || currentBranch === 'master';
+  const isCleanTree = modifiedFiles.length === 0;
 
-  const errors: Array<{ type: string; message: string }> = [];
+  // Run all validations
+  const errors: ValidationError[] = [];
 
-  // Check 1: ANY changes on main branch are FORBIDDEN
-  if ((currentBranch === 'main' || currentBranch === 'master') && modifiedFiles.length > 0) {
-    const fileList = modifiedFiles.slice(0, 15).map(f => `  - ${f}`).join('\n');
-    const more = modifiedFiles.length > 15 ? '\n  ... and more' : '';
+  // Validation order matters - most critical first
+  const branchError = validateBranch(currentBranch, modifiedFiles);
+  if (branchError) errors.push(branchError);
 
-    errors.push({
-      type: 'DIRECT_MAIN_COMMIT',
-      message: `
-BLOCKED: Attempting to work directly on '${currentBranch}' branch!
+  // Only check these if we're close to completion (on main or clean tree)
+  if (isMainBranch || isCleanTree) {
+    const treeError = validateGitTree(modifiedFiles);
+    if (treeError) errors.push(treeError);
+  }
 
-You have ${modifiedFiles.length} modified file(s):
-${fileList}${more}
+  const claudeMdExistsError = validateClaudeMdExists();
+  if (claudeMdExistsError) errors.push(claudeMdExistsError);
 
-REQUIRED ACTION:
-1. Create a feature branch: git checkout -b feature/[name]
-2. Or fix/chore branch: git checkout -b fix/[name] or git checkout -b chore/[name]
-3. Continue your work on the new branch
-4. Create PR to merge back to main
+  if (!claudeMdExistsError) {
+    const sizeError = validateClaudeMdSize();
+    if (sizeError) errors.push(sizeError);
 
-NEVER make ANY changes directly on main. ALL work must be done on branches.
-`
-    });
-  }
+    const structureError = validateClaudeMdStructure();
+    if (structureError) errors.push(structureError);
 
-  // Check 2: Documentation for source files
-  if (sourceFiles.length > 0) {
-    const { undocumented } = validateDocumentation(projectDir, sourceFiles);
+    const lastChangeError = validateClaudeMdLastChange();
+    if (lastChangeError) errors.push(lastChangeError);
 
-    if (undocumented.length > 0) {
-      const fileList = undocumented.slice(0, 15).map(f => `  - ${f}`).join('\n');
-      const more = undocumented.length > 15 ? '\n  ... and more' : '';
+    const updatedError = validateClaudeMdUpdated(modifiedFiles);
+    if (updatedError) errors.push(updatedError);
+  }
 
-      errors.push({
-        type: 'MISSING_DOCUMENTATION',
-        message: `
-BLOCKED: ${undocumented.length} source file(s) are NOT documented!
+  const docError = validateDocumentation(sourceFiles);
+  if (docError) errors.push(docError);
 
-Undocumented files:
-${fileList}${more}
+  // ============================================================================
+  // OUTPUT RESULTS
+  // ============================================================================
 
-REQUIRED ACTION:
-Run the documenter agent to update documentation:
+  if (errors.length > 0) {
+    let output = `
+################################################################################
+#                    STOP VALIDATOR - TASK COMPLETION BLOCKED                  #
+################################################################################
 
-  Task(subagent_type="documenter", prompt="Update documentation for all modified files")
+${errors.length} validation(s) failed. You MUST fix these before the task can complete.
 
-The documenter will:
-1. Detect changed files via git diff
-2. Update domain files in .claude/skills/codebase-knowledge/domains/
-3. Update docs/CHANGELOG.md
-4. Ensure all modified files are mentioned in documentation
+`;
 
-DOCUMENTATION IS MANDATORY before task completion.
-`
-      });
-    }
-  }
+    for (let i = 0; i < errors.length; i++) {
+      const err = errors[i];
+      output += `
+--------------------------------------------------------------------------------
+ERROR ${i + 1}/${errors.length}: ${err.type}
+--------------------------------------------------------------------------------
 
-  if (errors.length > 0) {
-    let errorOutput = `
-================================================================================
-STOP VALIDATOR - BLOCKING TASK COMPLETION
-================================================================================
-`;
-    for (const err of errors) {
-      errorOutput += `
---- ${err.type} ---
 ${err.message}
+
+${err.action}
 `;
     }
 
-    errorOutput += `
-================================================================================
-FIX THE ABOVE ISSUES BEFORE COMPLETING THE TASK
-================================================================================
+    output += `
+################################################################################
+#               FIX ALL ERRORS ABOVE BEFORE TASK CAN COMPLETE                  #
+################################################################################
+
+SYNTHESIS REMINDER:
+Before completing, ask yourself:
+- Did the user mention any preferences I should remember?
+- Did I learn any patterns that should be documented?
+- Were there any corrections I should add as rules?
+
+Update CLAUDE.md with any learnings from this session.
 `;
 
-    const result: HookResult = { decision: 'block', reason: errorOutput.trim() };
+    const result: HookResult = { decision: 'block', reason: output.trim() };
     console.log(JSON.stringify(result));
     process.exit(0);
   }
 
   // All validations passed
-  let nextStepMessage: string;
-  if (modifiedFiles.length > 0) {
-    nextStepMessage = `
-================================================================================
-✓ ALL VALIDATIONS PASSED
-================================================================================
+  const successOutput = `
+################################################################################
+#                    STOP VALIDATOR - ALL CHECKS PASSED                        #
+################################################################################
 
 Branch: ${currentBranch}
-Modified files: ${modifiedFiles.length} (source: ${sourceFiles.length}, config: ${systemConfigFiles.length})
-
-MANDATORY NEXT STEP:
-You MUST now commit, push, and create a PR:
-
-1. git add -A
-2. git commit with conventional commit message
-3. git push -u origin ${currentBranch}
-4. gh pr create to main branch
+Tree: ${isCleanTree ? 'Clean' : `${modifiedFiles.length} modified files`}
+CLAUDE.md: Valid
 
-DO NOT ask the user - just execute the commit-manager flow.
-
-================================================================================
+All validations passed. Task may complete.
+################################################################################
 `;
-  } else {
-    nextStepMessage = `All validations passed. Branch: ${currentBranch}, no files modified.`;
-  }
 
-  const result: HookResult = { decision: 'approve', reason: nextStepMessage.trim() };
+  const result: HookResult = { decision: 'approve', reason: successOutput.trim() };
   console.log(JSON.stringify(result));
   process.exit(0);
 }

package/template/.claude/hooks/user-prompt-submit.ts

@@ -29,14 +29,18 @@ const STRICT_WORKFLOW = `
 │ 4. BRANCH       → Create feature/ | fix/ | refactor/ | test/   │
 │ 5. IMPLEMENT    → Follow rules + analyzer approval             │
 │ 6. DOCUMENT     → Document ALL modified files (MANDATORY)      │
-│ 7. QUALITY      → typecheck + lint + test (Husky enforced)     │
-│ 8. FINISH       → commit-manager creates PR with task summary  │
+│ 7. UPDATE       → Update CLAUDE.md with session changes        │
+│ 8. QUALITY      → typecheck + lint + test (Husky enforced)     │
+│ 9. FINISH       → PR + merge to main (clean tree required)     │
 └─────────────────────────────────────────────────────────────────┘
 
 ⚠️  STOP HOOK ACTIVE - Task completion will be BLOCKED if:
-    - Working directly on main branch (must use feature/fix branch)
-    - Source files not documented (must run documenter agent)
-    - Documenter agent not executed for code changes
+    - NOT on main branch (PR must be merged first)
+    - Git tree NOT clean (all changes must be committed)
+    - CLAUDE.md NOT updated (must reflect session changes)
+    - CLAUDE.md missing required sections (Last Change, Stack, etc.)
+    - CLAUDE.md exceeds 40,000 characters (must compact)
+    - Source files NOT documented (must run documenter agent)
 `;
 
 // ============================================================================
@@ -725,11 +729,36 @@ async function main(): Promise<void> {
 
   const recommendedStr = bestAgents.map(([cat, agent, reason], i) => `    ${i + 1}. ${cat}/${agent} - ${reason}`).join('\n');
 
+  const claudeMdReminder = `
+================================================================================
+CLAUDE.MD UPDATE REQUIREMENT (MANDATORY)
+================================================================================
+
+Before completing ANY task, you MUST update CLAUDE.md at project root with:
+
+1. "## Last Change" section (ONLY keep the latest, do NOT stack):
+   **Branch:** your-branch-name
+   **Date:** ${new Date().toISOString().split('T')[0]}
+   **Summary:** What you implemented/fixed
+
+2. Update "## Architecture" if structure changed
+
+3. Add new rules/patterns learned to appropriate sections
+
+4. SYNTHESIZE: If user mentioned preferences or corrections, add as rules
+
+CHARACTER LIMIT: 40,000 max. If exceeded, COMPACT the file (keep critical sections).
+
+STOP HOOK WILL BLOCK if CLAUDE.md is not properly updated!
+================================================================================
+`;
+
   const output = `
 ================================================================================
 STRICT WORKFLOW ENFORCEMENT - UserPromptSubmit Hook
 ================================================================================
 ${STRICT_WORKFLOW}
+${claudeMdReminder}
 
 ${isNewFeature ? '⚠️  NEW FEATURE DETECTED - RESEARCH AGENT IS MANDATORY!' : ''}
 ${isUiTask ? '⚠️  UI TASK DETECTED - SEPARATE UIs FOR MOBILE/TABLET/DESKTOP REQUIRED!' : ''}

package/template/CLAUDE.md

@@ -4,16 +4,47 @@
 
 ---
 
-## Workflow
+## Workflow (STRICT FLOW)
 
 ```
-1. READ AGENTS    →  .claude/agents/*.md
-2. START TASK     →  python .claude/hooks/workflow-manager.py start-task --type feature --description "..."
-3. IMPLEMENT      →  Follow project rules
-4. QUALITY CHECK  →  Run all quality gates
-5. COMMIT         →  Conventional commits
+0. INIT TASK      →  Run commit-manager to REGISTER task start
+1. TODO LIST      →  ALWAYS create detailed todo list from prompt
+2. RESEARCH       →  Run research agent for NEW features (MANDATORY)
+3. AUDIT          →  Check docs from last audit OR run fresh audit
+4. CREATE BRANCH  →  feature/ | fix/ | refactor/ | test/
+5. IMPLEMENT      →  Follow project rules + analyzer approval
+6. DOCUMENT       →  Document ALL modified files (MANDATORY)
+7. QUALITY GATES  →  Run typecheck && lint && test (Husky enforced)
+8. FINISH         →  commit-manager creates PR with task summary
 ```
 
+> **CRITICAL:** Research agent is MANDATORY for any new feature or complex bug fix.
+> **CRITICAL:** All documentation must reference commit hashes for audit trail.
+> **CRITICAL:** Stop hook BLOCKS task completion if files not documented.
+> **FALLBACK:** If Task tool fails to invoke an agent, READ the agent file directly from `.claude/agents/[agent-name].md` and follow its instructions manually.
+
+---
+
+## MCP Servers (MANDATORY)
+
+Configure these in `.mcp.json` at project root:
+
+| Server              | Purpose                                   | When to Use                              |
+| ------------------- | ----------------------------------------- | ---------------------------------------- |
+| `context7`          | Up-to-date library documentation          | Before implementing with ANY library     |
+| `sequential-thinking` | Complex problem-solving                 | Multi-step tasks, planning               |
+| `memory`            | Persistent knowledge graph                | Store/recall project patterns            |
+| `playwright`        | Browser automation and E2E testing        | UI testing, page verification            |
+| `nextjs-devtools`   | Next.js specific development tools        | Next.js projects only                    |
+| `mongodb`           | MongoDB database operations               | Database queries, schema inspection      |
+
+### Usage Rules
+
+- **ALWAYS** use `context7` before implementing features with external libraries
+- **ALWAYS** use `playwright` for E2E tests instead of manual browser testing
+- **ALWAYS** check `memory` for existing patterns before creating new ones
+- **NEVER** hardcode library APIs - query `context7` for current docs
+
 ---
 
 ## Agent System
@@ -36,6 +67,18 @@ This project uses 11 specialized AI agents:
 
 ---
 
+## Stop Hook Enforcement
+
+The Stop hook runs when Claude is about to finish and BLOCKS if:
+
+| Violation | Action Required |
+|-----------|-----------------|
+| On main branch with source changes | Create feature/fix branch first |
+| Source files not documented | Run documenter agent |
+| Documenter not executed | Invoke documenter via Task tool |
+
+---
+
 ## Configuration
 
 Edit these files in `.claude/config/` for your project:
@@ -46,39 +89,17 @@ Edit these files in `.claude/config/` for your project:
 | `quality-gates.json`  | Quality check commands     |
 | `testing-config.json` | Test framework config      |
 | `security-rules.json` | Security audit rules       |
-
----
-
-## Quick Start
-
-```bash
-# 1. Start a task
-python .claude/hooks/workflow-manager.py start-task --type feature --description "Add user authentication"
-
-# 2. Approve files for modification
-python .claude/hooks/workflow-manager.py approve-files --files "src/auth/*.ts"
-
-# 3. Mark agents as executed
-python .claude/hooks/workflow-manager.py agent-executed --agent analyzer --result approved
-
-# 4. Run quality gates
-python .claude/hooks/workflow-manager.py quality-gate --gate typecheck --passed true
-
-# 5. Final validation
-python .claude/hooks/workflow-manager.py final-validation --result approved --ready-to-commit true
-
-# 6. Complete task
-python .claude/hooks/workflow-manager.py complete-task --commit-hash abc123
-```
+| `domain-mapping.json` | File patterns to domains   |
 
 ---
 
 ## Critical Rules
 
-1. **ALWAYS start task first** - Hooks block without active task
-2. **ALWAYS approve files** - Pre-tool-use hook blocks unapproved edits
+1. **ALWAYS use MCP servers** - Context7 for docs, Playwright for E2E
+2. **ALWAYS start with todo list** - Track progress with TodoWrite tool
 3. **NEVER skip agents** - Stop hook blocks incomplete workflows
 4. **ALWAYS use conventional commits** - feat:, fix:, refactor:, docs:
+5. **NEVER commit to main** - Create feature/fix branches
 
 ---