start-vibing 2.0.42 → 2.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.42",
+	"version": "2.0.45",
 	"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

@@ -13,6 +13,7 @@ The stop hook validates `/CLAUDE.md` before allowing task completion:
 | 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) |
+| Content depth     | Relevant rule/flow sections must also be updated          |
 | No stacking       | Only ONE Last Change section (latest only)                |
 | Branch            | Must be on main (PR merged)                               |
 | Git tree          | Must be clean (no uncommitted changes)                    |
@@ -21,6 +22,25 @@ The stop hook validates `/CLAUDE.md` before allowing task completion:
 
 **If not on main:** Complete PR workflow (commit, push, PR, merge, checkout main).
 
+### Content Depth Rule (CLAUDE_MD_SHALLOW_UPDATE)
+
+> **"Last Change" = WHAT was done. Other sections = HOW things work NOW. Both MUST be current.**
+
+The stop-validator categorizes changed files and maps them to CLAUDE.md sections:
+
+| Changed Files | Must Also Update |
+|---------------|-----------------|
+| API/CRUD routes | Critical Rules, HTTP Requests |
+| UI components | UI Architecture, Component Organization |
+| Pages/layouts | Architecture, Next.js App Router Patterns |
+| Styling/aesthetics | UI Architecture, Design System |
+| Auth/middleware | Critical Rules, Workflow |
+| Database/models | Architecture, Critical Rules |
+| Config files | Stack, Configuration |
+| Hooks/scripts | Workflow, Stop Hook Validations |
+
+If ONLY "Last Change" was modified but categorized source files changed, `CLAUDE_MD_SHALLOW_UPDATE` blocks completion.
+
 ---
 
 ## System Architecture
@@ -46,17 +66,16 @@ All agents MUST use these MCP servers when applicable:
 | `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                  |
+| `playwright`          | Browser automation (via MCP tools) | 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
+- **ui-ux-reviewer**: MUST use `playwright` MCP tools to verify UI implementations
 
 ---
 
@@ -205,9 +224,8 @@ All implementations MUST:
 - [ ] Pass typecheck (command from config)
 - [ ] Pass lint (command from config)
 - [ ] Pass unit tests (command from config)
-- [ ] Pass E2E tests (command from config)
 - [ ] Pass build (command from config)
-- [ ] Have E2E tests with real auth
+- [ ] Use Playwright MCP for browser testing when needed
 - [ ] Have documentation in `docs/`
 - [ ] Be security audited
 - [ ] Be committed with conventional commits
@@ -215,6 +233,142 @@ All implementations MUST:
 
 ---
 
+## Claude 4.6 Best Practices
+
+> **Source:** [Anthropic Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+
+### Model Selection
+
+| Model | API ID | Cost (In/Out) | Best For |
+|-------|--------|---------------|----------|
+| **Opus 4.6** | `claude-opus-4-6` | $5/$25 MTok | Orchestrators, long-horizon tasks, 128K output |
+| **Sonnet 4.6** | `claude-sonnet-4-6` | $3/$15 MTok | Daily coding, teammates (5x cheaper) |
+| **Haiku 4.5** | `claude-haiku-4-5-20251001` | $1/$5 MTok | Classification, simple tasks |
+
+### Effort Levels
+
+| Level | Behavior | Use Case |
+|-------|----------|----------|
+| `max` | Always thinks, no limits | Complex architecture (**Opus ONLY**) |
+| `high` | Deep thinking (DEFAULT) | Agentic tasks, complex coding |
+| `medium` | Moderate, may skip simple | Most workloads |
+| `low` | Minimal thinking | Subagents, teammates, high-volume |
+
+**CLI:** `/model` then arrow keys to adjust effort.
+
+### Adaptive Thinking (Replaces budget_tokens)
+
+```typescript
+// CORRECT for 4.6 models
+thinking: { type: "adaptive" },
+output_config: { effort: "medium" }
+
+// DEPRECATED (will be removed)
+thinking: { type: "enabled", budget_tokens: 10000 }
+```
+
+Adaptive thinking enables **interleaved thinking** — Claude reasons BETWEEN tool calls.
+
+### Prompting Rules (CRITICAL)
+
+**AVOID (causes overtriggering):**
+- "CRITICAL: You MUST use..."
+- "be thorough", "think carefully", "do not be lazy"
+- "use the think tool to plan your approach"
+
+**USE INSTEAD:**
+- "Use this tool when..." (softer language)
+- Remove anti-laziness prompts entirely
+- Lower effort level instead of adding constraints
+
+**Why:** Opus 4.6 does MORE upfront exploration than older models. Anti-laziness prompts cause runaway thinking.
+
+### Tool Use Patterns
+
+```text
+# Claude will only SUGGEST:
+"Can you suggest some changes?"
+
+# Claude will IMPLEMENT:
+"Change this function to improve performance."
+```
+
+For proactive action by default, add to system prompt:
+```text
+By default, implement changes rather than only suggesting them.
+```
+
+### Subagent Control
+
+Opus 4.6 has a **strong predilection for subagents** — may spawn them when direct grep/read is faster.
+
+**Use subagents when:** Parallel tasks, isolated context, independent workstreams
+**Work directly when:** Sequential operations, single-file edits, shared state needed
+
+```text
+# Add if seeing excessive subagent use:
+For simple tasks, sequential operations, or single-file edits, work directly.
+```
+
+### Avoid Over-Engineering
+
+Opus 4.6 tends to create extra files and unnecessary abstractions.
+
+```text
+# Add to prompt:
+Avoid over-engineering. Only make changes directly requested.
+Don't add features, docstrings, or error handling beyond what's asked.
+```
+
+### Parallel Tool Calls
+
+```text
+# Add for maximum efficiency:
+If calling multiple tools with no dependencies, make all calls in parallel.
+```
+
+### Cost Control
+
+| Issue | Solution |
+|-------|----------|
+| Runaway thinking | Lower effort (not prompt constraints) |
+| `stop_reason: "max_tokens"` | Increase `max_tokens` to 64K+ |
+| High costs | Use `low` effort for subagents |
+| Billing confusion | Billed for FULL thinking, not visible summary |
+
+### Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| `max` effort on Sonnet/Haiku | Error — Opus only |
+| Prefilled responses | Deprecated in 4.6 |
+| Multiple agents editing same file | Isolate files per agent |
+| Aggressive prompts from older models | Remove "MUST", "CRITICAL" |
+
+### API Examples
+
+```typescript
+// Standard agentic call
+await client.messages.create({
+  model: "claude-opus-4-6",
+  max_tokens: 64000,
+  thinking: { type: "adaptive" },
+  output_config: { effort: "high" },
+  messages: [...]
+});
+
+// Cost-optimized subagent
+await client.messages.create({
+  model: "claude-sonnet-4-6",
+  max_tokens: 16000,
+  thinking: { type: "adaptive" },
+  output_config: { effort: "low" },
+  messages: [...]
+});
+```
+
+---
+
 ## Domain Updater Agent
 
 The **domain-updater** runs BEFORE commit-manager to ensure git stays clean.

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

@@ -54,6 +54,93 @@ const IGNORE_PATTERNS = [
 
 const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst']);
 
+// ============================================================================
+// FILE CHANGE CATEGORIES → CLAUDE.MD SECTIONS MAPPING
+// ============================================================================
+
+interface ChangeCategory {
+	name: string;
+	claudeMdSections: string[];
+	filePatterns: RegExp[];
+}
+
+const CHANGE_CATEGORIES: ChangeCategory[] = [
+	{
+		name: 'API/CRUD',
+		claudeMdSections: ['Critical Rules', 'HTTP Requests'],
+		filePatterns: [/\/api\//, /\/routers\//, /\/server\//, /\.route\./, /\.controller\./],
+	},
+	{
+		name: 'UI Components',
+		claudeMdSections: ['UI Architecture', 'Component Organization', 'Design System'],
+		filePatterns: [/\/components\//, /\/ui\//],
+	},
+	{
+		name: 'Pages/Layouts',
+		claudeMdSections: ['Next.js App Router Patterns', 'Architecture'],
+		filePatterns: [/\/app\/.*page\.tsx/, /\/app\/.*layout\.tsx/, /\/app\/.*loading\.tsx/],
+	},
+	{
+		name: 'Styling/Aesthetics',
+		claudeMdSections: ['UI Architecture', 'Design System', 'Design Trends'],
+		filePatterns: [/\.css$/, /globals\.css/, /theme/, /tailwind\.config/],
+	},
+	{
+		name: 'Auth/Middleware',
+		claudeMdSections: ['Critical Rules', 'Workflow'],
+		filePatterns: [/middleware/, /auth/, /session/],
+	},
+	{
+		name: 'Database/Models',
+		claudeMdSections: ['Architecture', 'Critical Rules'],
+		filePatterns: [/\/models\//, /\.model\./, /\/schema\//, /\.schema\./],
+	},
+	{
+		name: 'Configuration',
+		claudeMdSections: ['Stack', 'Configuration'],
+		filePatterns: [/\.config\./, /next\.config/, /tsconfig/],
+	},
+	{
+		name: 'Testing',
+		claudeMdSections: ['Quality Gates'],
+		filePatterns: [/\.test\./, /\.spec\./, /playwright/, /vitest/],
+	},
+	{
+		name: 'Workflow/Hooks',
+		claudeMdSections: ['Workflow', 'Stop Hook Validations'],
+		filePatterns: [/\.claude\/hooks\//, /\.claude\/scripts\//, /\.husky\//],
+	},
+];
+
+function categorizeChangedFiles(
+	files: string[]
+): Array<{ category: string; sections: string[]; files: string[] }> {
+	const result = new Map<string, { sections: string[]; files: string[] }>();
+
+	for (const file of files) {
+		const normalizedFile = file.replace(/\\/g, '/');
+		for (const cat of CHANGE_CATEGORIES) {
+			for (const pattern of cat.filePatterns) {
+				if (pattern.test(normalizedFile)) {
+					if (!result.has(cat.name)) {
+						result.set(cat.name, { sections: [...cat.claudeMdSections], files: [] });
+					}
+					const entry = result.get(cat.name)!;
+					if (!entry.files.includes(file)) {
+						entry.files.push(file);
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	return Array.from(result.entries()).map(([category, data]) => ({
+		category,
+		...data,
+	}));
+}
+
 const SOURCE_EXTENSIONS = new Set([
 	'.ts',
 	'.tsx',
@@ -603,7 +690,8 @@ 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);
+	// Use negative lookbehind to avoid matching ### Last Change (H3 subheadings)
+	const multipleChanges = content.match(/(?<!#)## Last Change/g);
 	if (multipleChanges && multipleChanges.length > 1) {
 		return {
 			type: 'CLAUDE_MD_STACKED_CHANGES',
@@ -628,8 +716,10 @@ This keeps the file focused and within the 40k character limit.
 	return null;
 }
 
-function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
-	// Files that don't require CLAUDE.md update (auto-generated, locks, etc)
+/**
+ * Helper: Get files exempt from CLAUDE.md update requirement
+ */
+function getSignificantFiles(modifiedFiles: string[]): string[] {
 	const EXEMPT_PATTERNS = [
 		'bun.lockb',
 		'package-lock.json',
@@ -641,13 +731,10 @@ function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | nul
 		/^packages\/start-vibing\/template\//,
 	];
 
-	// Filter out exempt files
-	const significantFiles = modifiedFiles.filter((f) => {
-		// Always exempt CLAUDE.md itself
+	return modifiedFiles.filter((f) => {
 		if (f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')) {
 			return false;
 		}
-		// Check exempt patterns
 		for (const pattern of EXEMPT_PATTERNS) {
 			if (typeof pattern === 'string') {
 				if (f === pattern || f.includes(pattern)) return false;
@@ -657,17 +744,39 @@ function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | nul
 		}
 		return true;
 	});
+}
+
+/**
+ * Helper: Build categorized section guidance for error messages
+ */
+function buildSectionGuidance(significantFiles: string[]): string {
+	const categories = categorizeChangedFiles(significantFiles);
+	if (categories.length === 0) return '';
+
+	const lines = categories.map((c) => {
+		const uniqueSections = [...new Set(c.sections)];
+		return `  - ${c.category} (${c.files.length} file${c.files.length > 1 ? 's' : ''}) → Update sections: ${uniqueSections.join(', ')}`;
+	});
+
+	return `
+DETECTED CHANGE CATEGORIES (update these CLAUDE.md sections):
 
-	// If no significant files modified, no need to check
+${lines.join('\n')}
+`;
+}
+
+function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
+	const significantFiles = getSignificantFiles(modifiedFiles);
 	if (significantFiles.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;
 
+	const sectionGuidance = buildSectionGuidance(significantFiles);
+
 	return {
 		type: 'CLAUDE_MD_NOT_UPDATED',
 		message: `${significantFiles.length} file(s) were modified but CLAUDE.md was not updated.`,
@@ -683,7 +792,7 @@ ${significantFiles
 	.slice(0, 10)
 	.map((f) => `  - ${f}`)
 	.join('\n')}${significantFiles.length > 10 ? '\n  ... and more' : ''}
-
+${sectionGuidance}
 REQUIRED UPDATES TO CLAUDE.MD:
 
 1. Update "## Last Change" section:
@@ -691,24 +800,193 @@ REQUIRED UPDATES TO CLAUDE.MD:
    **Date:** ${new Date().toISOString().split('T')[0]}
    **Summary:** What you implemented/fixed
 
-2. If architecture changed:
-   Update "## Architecture" section
+2. UPDATE RELEVANT RULE/FLOW SECTIONS (NOT just Last Change!):
+   - Changed API/CRUD logic? → Update "Critical Rules" or "HTTP Requests"
+   - Changed UI components? → Update "UI Architecture" or "Component Organization"
+   - Changed page structure? → Update "Architecture" or "Next.js App Router Patterns"
+   - Changed aesthetic rules? → Update "Design System" or "UI Architecture"
+   - Changed auth/middleware? → Update "Critical Rules" or "Workflow"
+   - Changed config? → Update "Stack" or "Configuration"
+   - Changed testing? → Update "Quality Gates"
+
+3. CONTEXT SYNTHESIS:
+   Think about what the user asked and what you learned.
+   If a rule changed, document the NEW rule in the relevant section.
+   If a flow changed, document the NEW flow.
+   CLAUDE.md is the single source of truth for ALL project rules.
+
+The stop hook will BLOCK until CLAUDE.md is updated with ALL relevant sections.
+================================================================================`,
+	};
+}
 
-3. If new patterns/rules were established:
-   Add to appropriate section
+/**
+ * NEW VALIDATION: Checks if CLAUDE.md was updated but only the "Last Change"
+ * section was modified (shallow update). When source files in categorized areas
+ * changed, CLAUDE.md sections beyond Last Change should also be updated.
+ *
+ * This catches the common pattern where Claude updates only "Last Change"
+ * but ignores updating the actual rules/flows that changed.
+ */
+function validateClaudeMdContentDepth(modifiedFiles: string[]): ValidationError | null {
+	const significantFiles = getSignificantFiles(modifiedFiles);
+	if (significantFiles.length === 0) return null;
 
-4. If user mentioned preferences or corrections:
-   Add as rules in relevant section
+	// Only run if CLAUDE.md WAS modified (otherwise validateClaudeMdUpdated handles it)
+	const claudeMdModified = modifiedFiles.some(
+		(f) => f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')
+	);
+	if (!claudeMdModified) return null;
+
+	// Categorize the source changes
+	const categories = categorizeChangedFiles(significantFiles);
+	if (categories.length === 0) return null; // No categorizable changes, Last Change is enough
+
+	// Try to detect if only "Last Change" section was modified in CLAUDE.md
+	// Check git diff of CLAUDE.md (staged, unstaged, or last commit)
+	let claudeMdDiff = '';
+	const diffCommands = [
+		'git diff -- CLAUDE.md',
+		'git diff --cached -- CLAUDE.md',
+		'git diff HEAD~1 HEAD -- CLAUDE.md',
+	];
 
-CONTEXT SYNTHESIS:
-Think about what the user asked and what you learned.
-Capture important decisions and patterns for the next session.
+	for (const cmd of diffCommands) {
+		try {
+			const result = execSync(cmd, {
+				cwd: PROJECT_DIR,
+				encoding: 'utf8',
+				stdio: ['pipe', 'pipe', 'pipe'],
+			}).trim();
+			if (result) {
+				claudeMdDiff = result;
+				break;
+			}
+		} catch {
+			continue;
+		}
+	}
+
+	if (!claudeMdDiff) return null; // Can't determine diff, skip this check
+
+	// Parse the diff to detect which sections were modified
+	const modifiedSections = parseClaudeMdDiffSections(claudeMdDiff);
+
+	// Check if ONLY "Last Change" was modified
+	const onlyLastChange =
+		modifiedSections.size > 0 &&
+		modifiedSections.size === 1 &&
+		modifiedSections.has('Last Change');
+
+	if (!onlyLastChange) return null; // Other sections were also modified, good
+
+	// Build specific guidance for what sections need updating
+	const sectionGuidance = categories
+		.map((c) => {
+			const uniqueSections = [...new Set(c.sections)];
+			const fileExamples = c.files.slice(0, 3).join(', ');
+			return `  - ${c.category}: ${fileExamples}\n    → Must review/update: ${uniqueSections.join(', ')}`;
+		})
+		.join('\n');
+
+	return {
+		type: 'CLAUDE_MD_SHALLOW_UPDATE',
+		message: `CLAUDE.md was updated but ONLY "Last Change" was modified. ${categories.length} change category(ies) require updating additional rule/flow sections.`,
+		action: `
+================================================================================
+CLAUDE.MD SHALLOW UPDATE DETECTED - MUST UPDATE RELEVANT SECTIONS
+================================================================================
+
+You updated CLAUDE.md but ONLY modified the "Last Change" section.
+This is NOT sufficient when source files that affect rules/flows were changed.
+
+CHANGES DETECTED THAT REQUIRE SECTION UPDATES:
+
+${sectionGuidance}
+
+--------------------------------------------------------------------------------
+WHAT TO DO
+--------------------------------------------------------------------------------
+
+For EACH category above, review the corresponding CLAUDE.md section and:
+
+1. If a RULE changed (e.g., CRUD validation, auth flow):
+   → UPDATE the rule in its section (Critical Rules, Workflow, etc.)
 
-The stop hook will BLOCK until CLAUDE.md is updated.
+2. If an AESTHETIC/UI pattern changed (e.g., new component style):
+   → UPDATE UI Architecture, Design System, or Component Organization
+
+3. If a FLOW changed (e.g., new middleware, data fetching pattern):
+   → UPDATE Workflow, Architecture, or Next.js App Router Patterns
+
+4. If NOTHING changed in rules/flows (just implementation):
+   → Add a comment in the relevant section noting the implementation
+
+EXAMPLES:
+  - Changed how users are fetched? → Update HTTP Requests section
+  - Changed button styles? → Update Design System section
+  - Added new page? → Update Architecture section
+  - Changed form validation? → Update Critical Rules section
+
+RULE: "Last Change" documents WHAT was done.
+      Other sections document HOW things work NOW.
+      Both must be current.
+
+The stop hook will BLOCK until relevant sections are also updated.
 ================================================================================`,
 	};
 }
 
+/**
+ * Parse a git diff of CLAUDE.md to determine which ## sections were modified.
+ * Returns a Set of section names that had actual content changes.
+ */
+function parseClaudeMdDiffSections(diff: string): Set<string> {
+	const modifiedSections = new Set<string>();
+	const lines = diff.split('\n');
+	let currentSection = '';
+
+	for (const line of lines) {
+		// Skip diff metadata
+		if (
+			line.startsWith('diff ') ||
+			line.startsWith('index ') ||
+			line.startsWith('--- ') ||
+			line.startsWith('+++ ')
+		) {
+			continue;
+		}
+
+		// Parse @@ hunk headers - they sometimes contain section context
+		const hunkMatch = line.match(/^@@ .+ @@\s*(## .+)?/);
+		if (hunkMatch && hunkMatch[1]) {
+			currentSection = hunkMatch[1].replace('## ', '').trim();
+			continue;
+		}
+		if (line.startsWith('@@')) continue;
+
+		// Detect section headers in changed or context lines
+		const sectionMatch = line.match(/^[+ -]?## (.+)/);
+		if (sectionMatch) {
+			currentSection = sectionMatch[1].trim();
+			// If the section header itself is a change, count it
+			if (line.startsWith('+') || line.startsWith('-')) {
+				modifiedSections.add(currentSection);
+			}
+			continue;
+		}
+
+		// Track actual content changes (+ or - lines, not context)
+		if (line.startsWith('+') || line.startsWith('-')) {
+			if (currentSection) {
+				modifiedSections.add(currentSection);
+			}
+		}
+	}
+
+	return modifiedSections;
+}
+
 function validateDocumentation(sourceFiles: string[]): ValidationError | null {
 	if (sourceFiles.length === 0) return null;
 
@@ -996,7 +1274,13 @@ Validate with: wc -m CLAUDE.md (must be < 40000)`,
 	},
 	CLAUDE_MD_NOT_UPDATED: {
 		agent: 'documenter',
-		prompt: 'Update CLAUDE.md Last Change section with current session summary',
+		prompt:
+			'Update CLAUDE.md: Last Change section AND all relevant rule/flow sections based on what files were changed (API rules, UI rules, workflow, architecture, etc.)',
+	},
+	CLAUDE_MD_SHALLOW_UPDATE: {
+		agent: 'documenter',
+		prompt:
+			'CLAUDE.md was updated but only Last Change was modified. Review changed source files, categorize them, and update the corresponding CLAUDE.md sections (Critical Rules, UI Architecture, Workflow, etc.) to reflect current rules and flows.',
 	},
 	SOURCE_FILES_NOT_DOCUMENTED: {
 		agent: 'documenter',
@@ -1087,11 +1371,15 @@ function collectAllErrors(
 	const updatedError = validateClaudeMdUpdated(modifiedFiles);
 	if (updatedError) errors.push(updatedError);
 
-	// 9. Source files must be documented
+	// 9. CLAUDE.md must have relevant sections updated (not just Last Change)
+	const contentDepthError = validateClaudeMdContentDepth(modifiedFiles);
+	if (contentDepthError) errors.push(contentDepthError);
+
+	// 11. Source files must be documented
 	const docError = validateDocumentation(sourceFiles);
 	if (docError) errors.push(docError);
 
-	// 10. Domain documentation must be complete
+	// 12. Domain documentation must be complete
 	const domainDocError = validateDomainDocumentation(modifiedFiles);
 	if (domainDocError) errors.push(domainDocError);
 

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

@@ -55,17 +55,43 @@ async function main(): Promise<void> {
 
 	const systemMessage = `TASK WORKFLOW (English only):
 
-0. READ both CLAUDE.md (project root) and .claude/CLAUDE.md before making any changes. These contain project rules, architecture, and context you need.
-1. CREATE a detailed todo-list (TaskCreate) breaking down the user's request into subtopics/steps.
+0. READ both CLAUDE.md (project root) and .claude/CLAUDE.md before making any changes.
+
+1. CREATE a detailed todo-list (TaskCreate) breaking down the request into steps.
+   - This is MANDATORY for ALL tasks, not optional.
+   - Include "Update CLAUDE.md with changes" as final task.
+
 2. WORK through each item sequentially — mark in_progress when starting, completed when done.
-3. COMMIT using conventional commits (feat/fix/refactor/docs/chore). Use the commit-manager agent for proper git workflow: branch → implement → commit → merge to main.
-4. UPDATE CLAUDE.md before finishing — this is the project's fast-recall memory across sessions:
-   a. "## Last Change" section (date: ${today}, branch, summary). Keep only the latest, never stack.
-   b. If you changed how the app works (new flows, changed workflows, new patterns): update the relevant CLAUDE.md sections (Architecture, Workflow, Rules, UI patterns, etc.) so the next session knows.
-   c. If you added new rules, gotchas, or forbidden patterns: add them to the appropriate section.
-   d. If you changed config, stack, or tooling: update the Stack/Configuration sections.
-   CLAUDE.md is the single source of truth for quick context. Anything not recorded here will be forgotten next session.
-5. RUN stop-validator before finishing: npx tsx .claude/hooks/stop-validator.ts`;
+
+3. UI/UX IMPLEMENTATION:
+   - BEFORE implementing any UI: invoke ui-mobile, ui-tablet, ui-desktop agents in PARALLEL.
+   - RESEARCH competitors in the same niche using competitor-analyzer or research-web agent.
+   - UI changes without market research will be REJECTED by final-validator.
+
+4. TESTING (via Playwright MCP):
+   - Use the Playwright MCP server (mcp__playwright__*) for browser testing.
+   - Do NOT run bun run test:e2e - use MCP tools directly.
+   - Test on 3 viewports: mobile (375px), tablet (768px), desktop (1280px).
+
+5. COMMIT using conventional commits via commit-manager agent.
+
+6. UPDATE CLAUDE.md BEFORE finishing (MANDATORY - NOT JUST "Last Change"!):
+   a. "## Last Change" section (date: ${today}, branch, summary). Keep only latest.
+   b. THEN update ALL sections affected by your changes:
+      - Changed API/CRUD rules? → Update "Critical Rules" or "HTTP Requests"
+      - Changed UI components/aesthetics? → Update "UI Architecture", "Design System", "Component Organization"
+      - Changed pages/layouts? → Update "Architecture" or "Next.js App Router Patterns"
+      - Changed auth/middleware? → Update "Critical Rules" or "Workflow"
+      - Changed config/stack? → Update "Stack" or "Configuration"
+      - Changed testing patterns? → Update "Quality Gates"
+      - Changed workflow/hooks? → Update "Workflow" or "Stop Hook Validations"
+      - New gotchas discovered? → Add to "FORBIDDEN" or "NRY"
+
+   RULE: "Last Change" = WHAT was done. Other sections = HOW things work NOW.
+   If you ONLY update Last Change, the stop-validator will BLOCK with CLAUDE_MD_SHALLOW_UPDATE.
+   CLAUDE.md is the SINGLE SOURCE OF TRUTH for ALL project rules and flows.
+
+7. RUN stop-validator before finishing: npx tsx .claude/hooks/stop-validator.ts`;
 
 	console.log(JSON.stringify({ continue: true, systemMessage }));
 	process.exit(0);

package/template/.claude/settings.json

@@ -1,5 +1,5 @@
 {
-	"model": "claude-opus-4-5-20251101",
+	"model": "opus",
 	"max_tokens": 8192,
 	"max_turns": 100,
 
@@ -239,7 +239,7 @@
 		},
 		"testing": {
 			"unit_tests_required": true,
-			"e2e_for_ui_features": true,
+			"playwright_mcp_for_browser_tests": true,
 			"data_testid_required": true,
 			"edge_cases_research_required": true
 		},
@@ -266,11 +266,6 @@
 			"required": true,
 			"blocking": true
 		},
-		"test_e2e": {
-			"command": "bun run test:e2e",
-			"required": "when_ui_changes",
-			"blocking": true
-		},
 		"build": {
 			"command": "bun run build",
 			"required": true,