start-vibing 2.0.24 → 2.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.24",
+	"version": "2.0.26",
 	"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/07-documentation/claude-md-compactor.md

@@ -1,49 +1,43 @@
+---
+name: claude-md-compactor
+description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars. Triggers: stop hook CLAUDE_MD_SIZE_EXCEEDED, 'compact CLAUDE.md'. Compacts while preserving critical knowledge per Anthropic best practices."
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+skills: codebase-knowledge, docs-tracker
+---
+
 # Claude MD Compactor Agent
 
-> **Purpose:** Intelligently compact CLAUDE.md when it exceeds 40,000 characters while preserving critical project knowledge.
+Intelligently compact CLAUDE.md when it exceeds 40,000 characters while preserving critical project knowledge.
 
----
+## Research-Based Best Practices (Sources)
 
-## Trigger
+Per [Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-best-practices):
+- Keep CLAUDE.md concise and human-readable
+- Treat it like a frequently-used prompt - iterate on effectiveness
+- Use emphasis ("IMPORTANT", "YOU MUST") for critical rules
 
-AUTOMATICALLY invoke when:
+Per [HumanLayer Research](https://www.humanlayer.dev/blog/writing-a-good-claude-md):
+- **Target: <60 lines** (their production CLAUDE.md)
+- **Maximum: <300 lines** (general consensus)
+- LLMs can follow ~150-200 instructions max, Claude Code uses ~50 already
+- Only include **universally applicable** content
 
-- CLAUDE.md exceeds 40,000 characters
-- Stop hook blocks with `CLAUDE_MD_SIZE_EXCEEDED` error
-- User says "compact", "reduce", "shrink" CLAUDE.md
-
----
+Per [Context Management Research](https://mcpcat.io/guides/managing-claude-code-context/):
+- Performance degrades as file grows ("fading memory" phenomenon)
+- Move task-specific content to separate files (Progressive Disclosure)
+- Use external docs/ folder for ad-hoc content
 
 ## Execution Steps
 
 ### Step 1: Analyze Current State
 
 ```bash
-# Get current size
-wc -m CLAUDE.md
-
-# Get section breakdown
-grep -n "^## " CLAUDE.md
-```
-
-### Step 2: Research Best Practices
-
-Use MCP servers to get latest recommendations:
-
-```
-1. context7 - Query Claude Code documentation patterns
-2. WebSearch - "Anthropic Claude system prompt best practices 2024 2025"
-3. WebSearch - "Claude context window optimization techniques"
-```
-
-### Step 3: Read Template for Structure
-
-```
-Read: .claude/skills/codebase-knowledge/TEMPLATE.md
-Read: .claude/CLAUDE.md (agent context file for reference)
+wc -m CLAUDE.md              # Current size
+grep -n "^## " CLAUDE.md     # Section breakdown
 ```
 
-### Step 4: Apply Compaction Rules
+### Step 2: Apply Compaction Rules
 
 #### MUST KEEP (Critical Sections)
 

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

@@ -932,12 +932,18 @@ interface HookInput {
 }
 
 interface HookResult {
+	continue: boolean;
 	decision: 'approve' | 'block';
 	reason: string;
 }
 
 /**
  * Maps error types to the subagent that should be launched to fix them.
+ * IMPORTANT: Only use built-in Claude Code agent types that exist in the Task tool.
+ * Custom agents defined in .claude/agents/ are NOT available as subagent_type.
+ *
+ * Available built-in types: general-purpose, documenter, commit-manager, branch-manager,
+ * analyzer, tester, security-auditor, quality-checker, debugger, etc.
  */
 const ERROR_TO_SUBAGENT: Record<string, { agent: string; prompt: string }> = {
 	FEATURE_BRANCH_NOT_MERGED: {
@@ -961,8 +967,16 @@ const ERROR_TO_SUBAGENT: Record<string, { agent: string; prompt: string }> = {
 		prompt: 'Create CLAUDE.md with required sections: Last Change, 30s Overview, Stack, Architecture',
 	},
 	CLAUDE_MD_SIZE_EXCEEDED: {
-		agent: 'claude-md-compactor',
-		prompt: 'Compact CLAUDE.md to under 40k characters while preserving critical project knowledge',
+		agent: 'general-purpose',
+		prompt: `Compact CLAUDE.md to under 40,000 characters. Follow these rules from Anthropic best practices:
+
+1. KEEP (critical): Title, Last Change (latest only), 30s Overview, Stack table, Architecture tree
+2. REMOVE: Verbose prose (use bullets), code examples >5 lines (use file refs), duplicate info, old Last Change entries, commented sections
+3. TARGET: <60 lines ideal, <300 max per HumanLayer research
+4. CONDENSE: "Auth uses JWT via lib/auth.ts" instead of paragraphs explaining JWT
+
+Read .claude/agents/07-documentation/claude-md-compactor.md for detailed compaction template.
+Validate with: wc -m CLAUDE.md (must be < 40000)`,
 	},
 	CLAUDE_MD_TEMPLATE_MERGE_NEEDED: {
 		agent: 'documenter',
@@ -1099,6 +1113,7 @@ async function main(): Promise<void> {
 	// Prevent infinite loops
 	if (hookInput.stop_hook_active) {
 		const result: HookResult = {
+			continue: false,
 			decision: 'approve',
 			reason: 'Stop hook cycle detected, allowing exit',
 		};
@@ -1166,7 +1181,8 @@ The stop hook will check for remaining issues. Repeat until ALL CHECKS PASSED.
 
 		// Stop hooks MUST return JSON with decision field
 		// Exit code 2 signals blocking, but the JSON format is required for Stop hooks
-		const result: HookResult = { decision: 'block', reason: blockReason.trim() };
+		// continue: true tells Claude to KEEP WORKING after receiving this block
+		const result: HookResult = { continue: true, decision: 'block', reason: blockReason.trim() };
 		console.log(JSON.stringify(result));
 		process.exit(2);
 	}
@@ -1185,7 +1201,8 @@ All validations passed. Task may complete.
 ################################################################################
 `;
 
-	const result: HookResult = { decision: 'approve', reason: successOutput.trim() };
+	// continue: false tells Claude the task is DONE and can stop
+	const result: HookResult = { continue: false, decision: 'approve', reason: successOutput.trim() };
 	console.log(JSON.stringify(result));
 	process.exit(0);
 }
@@ -1193,7 +1210,7 @@ All validations passed. Task may complete.
 main().catch((err) => {
 	console.error('Hook error:', err);
 	// On error, allow to continue to not block user
-	const result: HookResult = { decision: 'approve', reason: 'Hook error, allowing by default' };
+	const result: HookResult = { continue: false, decision: 'approve', reason: 'Hook error, allowing by default' };
 	console.log(JSON.stringify(result));
 	process.exit(0);
 });