start-vibing-stacks 1.4.1 → 1.5.0

package/dist/setup.js

@@ -65,6 +65,7 @@ export async function setupProject(projectDir, config, options = {}) {
         mkdirSync(join(claudeDir, 'hooks'), { recursive: true });
         mkdirSync(join(claudeDir, 'config'), { recursive: true });
         mkdirSync(join(claudeDir, 'commands'), { recursive: true });
+        mkdirSync(join(claudeDir, 'rules'), { recursive: true });
         mkdirSync(join(claudeDir, 'skills', 'codebase-knowledge', 'domains'), { recursive: true });
         spinner.text = 'Directory structure created';
         // 2. Copy shared agents (universal)
@@ -129,6 +130,14 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = 'Imported .cursorrules into Claude config';
             }
         }
+        // 11b. Ensure CLAUDE.local.md is gitignored
+        const gitignorePath = join(projectDir, '.gitignore');
+        if (existsSync(gitignorePath)) {
+            const gitignore = readFileSync(gitignorePath, 'utf8');
+            if (!gitignore.includes('CLAUDE.local.md')) {
+                writeFileSync(gitignorePath, gitignore.trimEnd() + '\n\n# Claude Code local preferences\nCLAUDE.local.md\n');
+            }
+        }
         // 12. Copy commands
         const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
         if (existsSync(sharedCommandsDir)) {
@@ -140,6 +149,7 @@ export async function setupProject(projectDir, config, options = {}) {
             max_tokens: 8192,
             max_turns: 100,
             enableAllProjectMcpServers: true,
+            autoMemoryEnabled: true,
             context: {
                 compaction_threshold: 0.85,
                 enable_compaction: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/agents/claude-md-compactor.md

@@ -1,44 +1,159 @@
 ---
 name: claude-md-compactor
-description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars. Compacts while preserving critical knowledge."
+description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars OR auto memory MEMORY.md exceeds 200 lines. Compacts while preserving critical knowledge by offloading to topic files."
 model: sonnet
-tools: Read, Write, Edit, Bash, Grep
+tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 
 # Claude MD Compactor Agent
 
-Compact CLAUDE.md when it exceeds 40,000 characters.
+## Understanding Claude Code's Memory Architecture
 
-## Target Sizes
+Claude Code has a **hierarchical memory system**. Know it before compacting:
 
-| Section | Max Size |
-|---------|----------|
-| # Title | 1 line |
-| ## Last Change | 200 chars |
-| ## Overview | 300 chars |
-| ## Stack | 500 chars (table) |
-| ## Architecture | 800 chars (tree) |
-| ## Critical Rules | 2000 chars (bullets) |
-| ## FORBIDDEN | 1000 chars (table) |
+```
+Memory Hierarchy (loaded at session start):
+┌─────────────────────────────────────────────────┐
+│ Managed Policy (/etc/claude-code/CLAUDE.md)     │ ← Org-wide (IT/DevOps)
+├─────────────────────────────────────────────────┤
+│ User Memory (~/.claude/CLAUDE.md)               │ ← Personal (all projects)
+├─────────────────────────────────────────────────┤
+│ Project Memory (./CLAUDE.md or .claude/CLAUDE.md│ ← Team-shared (git tracked)
+├─────────────────────────────────────────────────┤
+│ Project Rules (.claude/rules/*.md)              │ ← Modular rules (git tracked)
+├─────────────────────────────────────────────────┤
+│ Project Local (./CLAUDE.local.md)               │ ← Personal (gitignored)
+├─────────────────────────────────────────────────┤
+│ Auto Memory (~/.claude/projects/<proj>/memory/)  │ ← Claude's own notes
+│   ├─ MEMORY.md (first 200 lines loaded)         │
+│   ├─ debugging.md (on-demand)                    │
+│   └─ patterns.md (on-demand)                     │
+└─────────────────────────────────────────────────┘
+```
+
+**Key facts:**
+- `CLAUDE.md` is loaded IN FULL at session start → keep it lean
+- Auto memory `MEMORY.md` only loads **first 200 lines** → index only, details in topic files
+- `.claude/rules/*.md` load in full → use for modular, topic-specific rules
+- `@path/to/file` imports work inside CLAUDE.md (max depth 5)
+- Child directory CLAUDE.md files load **on demand** (not at startup)
+
+## When to Trigger
+
+1. `CLAUDE.md` exceeds **40,000 characters**
+2. Auto memory `MEMORY.md` exceeds **200 lines**
+3. Context window is running hot (>80% usage)
+4. Session start is slow (too much context loaded)
+
+## Compaction Strategy
+
+### Step 1: Audit Current Size
+
+```bash
+wc -m CLAUDE.md                                    # Project CLAUDE.md
+wc -l ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null  # Auto memory
+du -sh .claude/                                     # Total .claude size
+```
+
+### Step 2: Offload to Rules Files (NOT delete)
+
+Move detailed sections from CLAUDE.md to `.claude/rules/`:
+
+```
+CLAUDE.md (before — bloated):
+  ## Stack (500 chars)
+  ## Critical Rules (5000 chars of detailed rules)
+  ## API Patterns (3000 chars of examples)
+  ## Security (2000 chars)
+  ## Frontend Patterns (4000 chars)
+
+CLAUDE.md (after — lean index):
+  ## Stack (500 chars)
+  ## Critical Rules (summary bullets + @.claude/rules/critical.md)
+  ## API Patterns (summary + @.claude/rules/api.md)
+  ## Security (summary + @.claude/rules/security.md)
+  ## Frontend Patterns (summary + @.claude/rules/frontend.md)
+```
 
-## Must Remove
+### Step 3: Use @imports for Details
 
-- Verbose explanations → bullet points
-- Code examples > 5 lines → file references
-- Old "Last Change" entries → git has history
+```markdown
+# MyProject
+
+## Critical Rules
+- Always use UUIDs for primary keys
+- Prepared statements only (no raw SQL)
+- Full details: @.claude/rules/critical.md
+
+## API Standards  
+- UTC storage, timezone in Resource layer only
+- Full patterns: @.claude/rules/api-standards.md
+```
+
+### Step 4: Compact Auto Memory MEMORY.md
+
+If `MEMORY.md` > 200 lines, offload to topic files:
+
+```
+~/.claude/projects/<proj>/memory/
+├── MEMORY.md          # INDEX ONLY (< 200 lines)
+│   → "Debugging notes: see debugging.md"
+│   → "API patterns: see api-conventions.md"  
+│   → "Performance learnings: see performance.md"
+├── debugging.md       # Detailed debugging notes (on-demand)
+├── api-conventions.md # API decisions (on-demand)
+└── performance.md     # Performance learnings (on-demand)
+```
+
+### Step 5: Clean Stale Content
+
+Remove from CLAUDE.md:
+- Old "Last Change" entries (keep only latest)
+- Resolved problems (move to domain docs)
+- Code examples > 10 lines (reference file instead)
 - Duplicate information
 - Commented-out sections
 
-## Must Keep
+## Target Sizes After Compaction
+
+| Section | Max in CLAUDE.md | Overflow to |
+|---------|-----------------|-------------|
+| Title + Overview | 500 chars | — |
+| Last Change | 200 chars | git history |
+| Stack table | 500 chars | — |
+| Architecture tree | 800 chars | — |
+| Critical Rules | 500 chars summary | `.claude/rules/critical.md` |
+| FORBIDDEN table | 500 chars | `.claude/rules/security.md` |
+| Quality Gates | 300 chars | `config/quality-gates.json` |
+| Per-domain rules | 200 chars each | `.claude/rules/{domain}.md` |
+| **Total CLAUDE.md** | **< 15,000 chars** | Rules files |
+
+## FORBIDDEN During Compaction
 
-- Project title, overview, stack table
-- Architecture tree
-- Critical rules (bullets)
-- FORBIDDEN actions table
-- Quality gate commands
+| Don't | Why |
+|---|---|
+| Delete rules entirely | Move to rules/ files instead |
+| Remove FORBIDDEN table | Security must stay visible |
+| Delete Last Change | Keep latest, remove older |
+| Remove architecture tree | Essential for navigation |
+| Compact code examples by truncating | Reference the file instead |
+| Edit auto memory of other projects | Stay in current project only |
 
-## After Compaction
+## After Compaction Verification
 
 ```bash
-wc -m CLAUDE.md  # Must be < 40000
+# CLAUDE.md under limit
+wc -m CLAUDE.md  # Must be < 40000 (target: < 15000)
+
+# Auto memory index under limit
+wc -l ~/.claude/projects/*/memory/MEMORY.md  # Must be < 200 lines
+
+# Rules files exist for offloaded content
+ls .claude/rules/
+
+# @imports are valid
+grep -o '@[^ ]*' CLAUDE.md | while read f; do
+  path="${f#@}"
+  [ -f "$path" ] && echo "✅ $path" || echo "❌ MISSING: $path"
+done
 ```

package/stacks/php/skills/laravel-octane/SKILL.md

@@ -47,6 +47,21 @@ $_POST['name']; // ❌
 $_SESSION['user']; // ❌
 ```
 
+### AppServiceProvider — Connection Flush
+
+```php
+// app/Providers/AppServiceProvider.php
+use Laravel\Octane\Facades\Octane;
+
+public function boot(): void
+{
+    // MANDATORY: flush DB connections between requests
+    Octane::prepare(fn ($sandbox) => $sandbox->flushDatabaseConnections());
+}
+```
+
+**Rule:** ALWAYS pair persistent connections with `Octane::prepare` flush in AppServiceProvider.
+
 ### Memoization in Workers
 
 ```php

package/stacks/php/skills/laravel-patterns/SKILL.md

@@ -100,7 +100,25 @@ class UserResource extends JsonResource
 }
 ```
 
-**Rule:** Backend/DB in UTC. Timezone conversion ONLY in API Resources.
+**Implementation:**
+
+```php
+// app/Traits/FormatsDatesForApi.php
+trait FormatsDatesForApi
+{
+    protected function formatDateTime(
+        ?\Carbon\Carbon $date,
+        Request $request,
+        string $format = 'Y-m-d\TH:i:sP'
+    ): ?string {
+        if (!$date) return null;
+        $tz = $request->header('X-Timezone', $request->user()?->timezone ?? 'UTC');
+        return $date->copy()->setTimezone($tz)->format($format);
+    }
+}
+```
+
+**Rule:** Backend/DB in UTC. Timezone conversion ONLY in API Resources. ALL Resources with dates MUST use this trait.
 
 ### Action Endpoints