start-vibing 2.0.18 → 2.0.19

package/package.json

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

@@ -0,0 +1,220 @@
+# Claude MD Compactor Agent
+
+> **Purpose:** Intelligently compact CLAUDE.md when it exceeds 40,000 characters while preserving critical project knowledge.
+
+---
+
+## Trigger
+
+AUTOMATICALLY invoke when:
+
+- CLAUDE.md exceeds 40,000 characters
+- Stop hook blocks with `CLAUDE_MD_SIZE_EXCEEDED` error
+- User says "compact", "reduce", "shrink" CLAUDE.md
+
+---
+
+## 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)
+```
+
+### Step 4: Apply Compaction Rules
+
+#### MUST KEEP (Critical Sections)
+
+| Section              | Max Size | Notes                        |
+| -------------------- | -------- | ---------------------------- |
+| # Project Title      | 1 line   | Just the name                |
+| ## Last Change       | 200 char | ONLY latest, no history      |
+| ## 30 Seconds        | 300 char | 2-3 sentences max            |
+| ## Stack             | 500 char | Table format only            |
+| ## Architecture      | 800 char | Tree structure, no prose     |
+| ## Critical Rules    | 2000 char | Bullet points only          |
+| ## FORBIDDEN Actions | 1000 char | Table format                 |
+| ## Quality Gates     | 500 char | Commands only                |
+
+#### MUST REMOVE/CONDENSE
+
+| Remove                      | Why                                  |
+| --------------------------- | ------------------------------------ |
+| Verbose explanations        | Use bullet points instead            |
+| Code examples > 5 lines     | Reference file paths instead         |
+| Duplicate information       | Keep only in most relevant section   |
+| Old "Last Change" entries   | Git history has this                 |
+| Long tables with examples   | Keep headers + 1-2 rows max          |
+| Commented-out sections      | Delete completely                    |
+| Multiple H1 headers         | Only one allowed                     |
+| Nested sub-sub-sections     | Flatten to H2 max                    |
+
+#### CONDENSE TECHNIQUES
+
+```markdown
+# BAD (verbose)
+## Authentication
+The authentication system uses JWT tokens for secure session management.
+When a user logs in, the server generates a token that contains...
+[50 more lines of explanation]
+
+# GOOD (compact)
+## Auth
+- JWT tokens via `lib/auth.ts`
+- Session: 7 days, refresh: 30 days
+- Middleware: `middleware/auth.ts`
+```
+
+### Step 5: Rewrite File
+
+Create new CLAUDE.md with:
+
+1. **Header** - Project name only
+2. **Last Change** - Latest only (branch, date, 1-line summary)
+3. **30 Seconds** - What it does in 2 sentences
+4. **Stack** - Technology table (no descriptions)
+5. **Architecture** - Tree only, no explanations
+6. **Workflow** - Numbered steps, no prose
+7. **Critical Rules** - Bullets, max 10 rules
+8. **FORBIDDEN** - Table format
+9. **Quality Gates** - Commands only
+
+### Step 6: Validate Size
+
+```bash
+# Must be under 40,000
+wc -m CLAUDE.md
+
+# If still over, remove more:
+# 1. Reduce examples
+# 2. Shorten rule descriptions
+# 3. Remove optional sections
+```
+
+---
+
+## Compaction Template
+
+```markdown
+# {Project Name}
+
+> Max 40k chars. Validate: `wc -m CLAUDE.md`
+
+---
+
+## Last Change
+
+**Branch:** {branch}
+**Date:** {YYYY-MM-DD}
+**Summary:** {1 sentence}
+
+---
+
+## Overview
+
+{2-3 sentences max}
+
+---
+
+## Stack
+
+| Component | Tech |
+|-----------|------|
+| Runtime   | Bun  |
+| Language  | TS   |
+
+---
+
+## Architecture
+
+\`\`\`
+project/
+├── app/      # Routes
+├── lib/      # Utils
+└── types/    # Types
+\`\`\`
+
+---
+
+## Rules
+
+- Rule 1
+- Rule 2
+- Rule 3
+
+---
+
+## FORBIDDEN
+
+| Action | Reason |
+|--------|--------|
+| X      | Y      |
+
+---
+
+## Commands
+
+\`\`\`bash
+bun run typecheck
+bun run lint
+bun run test
+\`\`\`
+```
+
+---
+
+## Research Queries (MCP)
+
+When compacting, query these for best practices:
+
+```
+context7: "Claude Code CLAUDE.md structure"
+WebSearch: "Anthropic system prompt optimization 2025"
+WebSearch: "Claude context efficiency best practices"
+WebSearch: "LLM prompt compression techniques"
+```
+
+---
+
+## Output
+
+After compaction:
+
+1. Show before/after character count
+2. List removed sections
+3. Confirm all critical sections preserved
+4. Verify file validates with stop hook
+
+---
+
+## Integration
+
+The stop hook will:
+
+1. Detect CLAUDE.md > 40k chars
+2. Block with message suggesting this agent
+3. Agent compacts file
+4. Stop hook re-validates
+5. Task completes if under limit

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

@@ -400,39 +400,63 @@ function validateClaudeMdSize(): ValidationError | null {
 	if (content.length <= MAX_CHARACTERS) return null;
 
 	const excess = content.length - MAX_CHARACTERS;
+	const percentOver = ((excess / MAX_CHARACTERS) * 100).toFixed(1);
 
 	return {
 		type: 'CLAUDE_MD_SIZE_EXCEEDED',
-		message: `CLAUDE.md exceeds 40,000 character limit by ${excess} characters (current: ${content.length}).`,
+		message: `CLAUDE.md exceeds 40,000 character limit by ${excess} characters (${percentOver}% over).`,
 		action: `
 ================================================================================
-CLAUDE.MD MUST BE COMPACTED (MAX 40,000 CHARACTERS)
+CLAUDE.MD MUST BE COMPACTED - RUN COMPACTOR AGENT (MANDATORY)
 ================================================================================
 
 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
+Excess: ${excess} characters (${percentOver}% over limit)
+
+--------------------------------------------------------------------------------
+REQUIRED ACTION: Run the claude-md-compactor agent
+--------------------------------------------------------------------------------
+
+  Task(subagent_type="claude-md-compactor", prompt="Compact CLAUDE.md to under 40k characters while preserving critical project knowledge")
+
+The compactor agent will:
+1. Research best practices via context7 and web search
+2. Analyze current CLAUDE.md structure
+3. Apply intelligent compaction rules:
+   - Keep: Title, Last Change, Overview, Stack, Architecture, Rules
+   - Remove: Verbose prose, old history, long examples, duplicates
+4. Rewrite file in compact format
+5. Validate final size < 40,000 chars
+
+--------------------------------------------------------------------------------
+COMPACTION PRIORITIES (agent follows these)
+--------------------------------------------------------------------------------
+
+MUST KEEP (max sizes):
+  - # Project Title (1 line)
+  - ## Last Change (200 chars, ONLY latest)
+  - ## 30 Seconds Overview (300 chars)
+  - ## Stack (500 chars, table only)
+  - ## Architecture (800 chars, tree only)
+  - ## Critical Rules (2000 chars, bullets)
+  - ## FORBIDDEN (1000 chars, table)
+
+MUST REMOVE:
+  - Verbose explanations → bullet points
+  - Code examples > 5 lines → file references
+  - Old "Last Change" entries → git has history
+  - Duplicate information → keep in one place
+  - Long tables → header + 2 rows max
+
+--------------------------------------------------------------------------------
+MANUAL VERIFICATION (after agent runs)
+--------------------------------------------------------------------------------
+
+  wc -m CLAUDE.md  # Must show < 40000
+
+================================================================================
+The stop hook will BLOCK until CLAUDE.md is under 40,000 characters.
 ================================================================================`,
 	};
 }

package/template/.claude/settings.json

@@ -151,6 +151,11 @@
 			"file": "agents/domain-updater.md",
 			"description": "Updates domain documentation with session learnings and problems solved. FINAL step after commit.",
 			"priority": 11
+		},
+		"claude-md-compactor": {
+			"file": "agents/07-documentation/claude-md-compactor.md",
+			"description": "Compacts CLAUDE.md when it exceeds 40k chars. Uses research + template to intelligently reduce size while preserving critical knowledge.",
+			"priority": 12
 		}
 	},