start-vibing 2.0.25 → 2.0.27

package/package.json

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

@@ -939,6 +939,11 @@ interface HookResult {
 
 /**
  * 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: {
@@ -962,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',
@@ -1155,14 +1168,26 @@ ${error.message}
 ${error.action}
 
 --------------------------------------------------------------------------------
-REQUIRED ACTION: Launch the following subagent to fix this issue
+STEP 1: Fix the issue using this subagent
 --------------------------------------------------------------------------------
 
   Task(subagent_type="${subagentInfo.agent}", prompt="${subagentInfo.prompt}")
 
 --------------------------------------------------------------------------------
-AFTER FIXING: You MUST try to complete the task again to trigger re-validation.
-The stop hook will check for remaining issues. Repeat until ALL CHECKS PASSED.
+STEP 2: After fixing, run the validator MANUALLY to verify
+--------------------------------------------------------------------------------
+
+  Bash(command="npx tsx .claude/hooks/stop-validator.ts", description="Run stop validator manually")
+
+This will show if the fix worked or if there are more issues to resolve.
+DO NOT try to complete the task until the validator returns "ALL CHECKS PASSED".
+
+--------------------------------------------------------------------------------
+STEP 3: Repeat Steps 1-2 until ALL CHECKS PASSED
+--------------------------------------------------------------------------------
+
+Only after seeing "ALL CHECKS PASSED" from the manual validator run,
+you may proceed to complete the task.
 ================================================================================
 `;