claude-code-pilot 2.0.0

package/gsd/hooks/gsd-context-monitor.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 3s (e.g. pipe issues on
+// Windows/Git Bash), exit silently instead of hanging until Claude Code
+// kills the process and reports "hook error". See #775.
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GSD is active (has .planning/STATE.md in working directory)
+    const cwd = data.cwd || process.cwd();
+    const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/gsd:pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+          'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
+    } else {
+      message = isGsdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/gsd/hooks/gsd-statusline.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Claude Code Statusline - GSD Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+// Timeout guard: if stdin doesn't close within 3s (e.g. pipe issues on
+// Windows/Git Bash), exit silently instead of hanging. See #775.
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to usable context)
+    // Claude Code reserves ~16.5% for autocompact buffer, so usable context
+    // is 83.5% of the total window. We normalize to show 100% at that point.
+    const AUTO_COMPACT_BUFFER_PCT = 16.5;
+    let ctx = '';
+    if (remaining != null) {
+      // Normalize: subtract buffer from remaining, scale to usable range
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+
+      // Write context metrics to bridge file for the context-monitor PostToolUse hook.
+      // The monitor reads this file to inject agent-facing warnings when context is low.
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
+          const bridgeData = JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000)
+          });
+          fs.writeFileSync(bridgePath, bridgeData);
+        } catch (e) {
+          // Silent fail -- bridge is best-effort, don't break statusline
+        }
+      }
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usable context thresholds
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    // Respect CLAUDE_CONFIG_DIR for custom config directory setups (#870)
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+    const todosDir = path.join(claudeDir, 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {
+        // Silently fail on file system errors - don't break statusline
+      }
+    }
+
+    // GSD update available?
+    let gsdUpdate = '';
+    const cacheFile = path.join(claudeDir, 'cache', 'gsd-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          gsdUpdate = '\x1b[33m⬆ /gsd:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/kit/CLAUDE.md

@@ -0,0 +1,43 @@
+# Project Agent Guide
+
+> **First time?** Run `/setup` to auto-configure this project.
+> **Update kit?** Run `/kit:update` to get the latest version.
+
+This file will be generated by `/setup` with project-specific details.
+
+## Methodology — GSD (Get Shit Done)
+
+Spec-driven development with fresh 200k contexts per task:
+
+- `/gsd:new-project` → Initialize with roadmap and milestones
+- `/gsd:discuss-phase N` → Capture requirements
+- `/gsd:plan-phase N` → Atomic plans
+- `/gsd:execute-phase N` → Build with fresh contexts, atomic commits
+- `/gsd:verify-work N` → Goal-backward verification ("does it match the spec?")
+- `/gsd:quick "task"` → Lightweight mode
+- `/gsd:help` → All 32 GSD commands
+
+## Toolbox — ECC (Everything Claude Code)
+
+Quality gates, learning, and session management:
+
+- `/verify` → Multi-phase verification (build → types → lint → tests → security)
+- `/checkpoint create "name"` → Git-backed snapshots with before/after comparison
+- `/save-session` → Persist session state (what worked, what didn't, next step)
+- `/resume-session` → Load previous session context
+- `/learn` → Extract reusable patterns from current session
+- `/evolve` → Promote learned instincts into skills/commands/agents
+- `/quality-gate` → On-demand quality pipeline
+- `/model-route` → Recommend model tier for current task
+
+## Before ANY Work
+
+```bash
+npx skills find <keywords>    # Discover ecosystem skills
+```
+
+## Reference Docs & MCP
+
+- `docs/agent-guides/*.md` — Detailed guides (loaded on demand)
+- `.claude/contexts/` — dev.md, research.md, review.md (mode switching)
+- MCP: **github.com/mcp** (official) or **mcp.so** (8000+ servers)

package/kit/commands/kit/update.md

@@ -0,0 +1,46 @@
+---
+description: "Update the Claude Code Pilot and all bundled dependencies (GSD, ECC)"
+---
+
+# Update Pilot
+
+## Step 1 — Check Versions
+
+```bash
+cat .claude/kit-version/VERSION          # Kit version
+cat .claude/kit-version/manifest.json    # Bundled dependency versions
+cat .claude/get-shit-done/VERSION        # GSD version
+```
+
+Check npm:
+```bash
+npm view claude-code-pilot version   # Latest kit
+npm view get-shit-done-cc version          # Latest GSD
+npm view ecc-universal version             # Latest ECC
+```
+
+Present:
+```
+📦 Pilot:  [installed] → [latest]
+📦 GSD:          [installed] → [latest]
+📦 ECC:          [installed] → [latest]
+```
+
+## Step 2 — Update
+
+If updates available:
+```bash
+npx claude-code-pilot@latest --local --update
+```
+
+Preserves: CLAUDE.md (if customized), architecture docs, settings customizations.
+Updates: GSD commands/agents/workflows, ECC commands/skills/hooks/rules, kit hooks.
+
+## Step 3 — Report
+
+```
+✅ Updated!
+  Kit: [old] → [new]
+  GSD: [old] → [new]
+  ECC: [old] → [new]
+```

package/kit/commands/setup-refresh.md

@@ -0,0 +1,50 @@
+---
+description: "Re-scan codebase and update CLAUDE.md, rules, directory CLAUDE.md files, and architecture docs after major changes"
+---
+
+# Refresh Project Configuration
+
+Re-scan and update after the project has evolved.
+
+## Step 1 — Diff Check
+
+1. Read current `CLAUDE.md`
+2. Scan for dependency/directory/command changes
+3. Check if detected languages changed (may need new rules from available-rules/)
+
+Present differences.
+
+## Step 2 — Update
+
+1. Update CLAUDE.md (keep under 100 lines)
+2. Activate/deactivate language rules if stack changed
+3. Update docs/agent-guides/architecture.md if structural changes
+4. Regenerate directory-scoped CLAUDE.md files:
+   - Scan for recognized directories: `src/`, `test/`, `tests/`, `lib/`, `app/`, `api/`, `scripts/`, `docs/`
+   - For each existing recognized directory with a CLAUDE.md file:
+     - Read the file's first line
+     - If it contains `<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->`: regenerate using the same stack-aware templates from /setup Stage 4
+     - If the marker is absent: skip (print: "Skipping {dir}/CLAUDE.md -- customized by user")
+   - For each recognized directory WITHOUT a CLAUDE.md file:
+     - Generate a new one using the same stack-aware templates from /setup Stage 4
+   - Show summary of changes:
+     ```
+     Directory CLAUDE.md refresh:
+       [REGENERATED] src/CLAUDE.md (Next.js conventions)
+       [SKIPPED]     test/CLAUDE.md (customized by user)
+       [CREATED]     api/CLAUDE.md (REST conventions)
+
+     Regenerated: 1, Skipped: 1, Created: 1
+     ```
+5. Search for new skills: `npx skills find [new-tech]`
+
+Show diff before writing.
+
+Note: MCP detection is NOT re-run during refresh. Binaries rarely change. Re-run `/setup` to re-detect MCP tools.
+
+## Step 3 — Commit
+
+```bash
+git add CLAUDE.md */CLAUDE.md .claude/rules/ docs/
+git commit -m "chore: refresh Claude Code configuration"
+```