claude-code-scanner 1.0.0

package/template/.claude/hooks/protect-files.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Pre-tool hook: block edits to protected files
+const path = require('path');
+
+// Timeout: exit if stdin hangs
+setTimeout(() => { process.stderr.write('BLOCKED: Hook timeout.\n'); process.exit(2); }, 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file) process.exit(0);
+
+    // Normalize path separators for cross-platform matching
+    const normalized = path.resolve(file).split(path.sep).join('/');
+
+    const PROTECTED_DIRS = ['.github/workflows/'];
+    for (const p of PROTECTED_DIRS) {
+      if (normalized.includes(p)) {
+        process.stderr.write(`BLOCKED: ${file} is protected.\n`);
+        process.exit(2);
+      }
+    }
+    const basename = path.basename(normalized);
+    const PROTECTED_EXACT = ['.env', '.env.local', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+    for (const p of PROTECTED_EXACT) {
+      if (basename === p) {
+        process.stderr.write(`BLOCKED: ${file} is protected.\n`);
+        process.exit(2);
+      }
+    }
+  } catch {
+    process.stderr.write('BLOCKED: Failed to parse hook input.\n');
+    process.exit(2);
+  }
+});

package/template/.claude/hooks/session-start.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Re-inject critical context on session start, resume, and after compaction
+const fs = require('fs');
+const path = require('path');
+
+const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+if (!fs.existsSync(tasksDir)) process.exit(0);
+
+const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+let activeFound = false;
+
+for (const file of files) {
+  const filePath = path.join(tasksDir, file);
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  // Show active tasks
+  if (/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING|QA_SIGNOFF|BIZ_SIGNOFF|TECH_SIGNOFF|DEPLOYING|MONITORING)/.test(content)) {
+    const titleMatch = content.match(/^title:\s*(.+)$/m);
+    const statusMatch = content.match(/^status:\s*(.+)$/m);
+    if (titleMatch && statusMatch) {
+      console.log(`ACTIVE TASK: ${titleMatch[1].trim()} | STATUS: ${statusMatch[1].trim()}`);
+      console.log('Check .claude/tasks/ for full details.');
+      activeFound = true;
+    }
+    break;
+  }
+}
+
+// Warn about ON_HOLD tasks
+for (const file of files) {
+  const filePath = path.join(tasksDir, file);
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  if (/status:\s*ON_HOLD/.test(content)) {
+    const idMatch = content.match(/^id:\s*(.+)$/m);
+    const titleMatch = content.match(/^title:\s*(.+)$/m);
+    const updatedMatch = content.match(/^updated:\s*(.+)$/m);
+
+    if (idMatch && titleMatch) {
+      const id = idMatch[1].trim();
+      const title = titleMatch[1].trim();
+
+      // Check how long it's been on hold
+      let daysOnHold = 0;
+      if (updatedMatch) {
+        const updated = new Date(updatedMatch[1].trim());
+        daysOnHold = Math.floor((Date.now() - updated.getTime()) / (1000 * 60 * 60 * 24));
+      }
+
+      if (daysOnHold > 30) {
+        console.log(`WARNING: ${id} "${title}" has been ON_HOLD for ${daysOnHold} days. Consider cancelling: /workflow cancel ${id}`);
+      } else if (daysOnHold > 7) {
+        console.log(`REMINDER: ${id} "${title}" is ON_HOLD (${daysOnHold} days). Resume: /workflow resume ${id}`);
+      } else {
+        console.log(`ON_HOLD: ${id} "${title}". Resume: /workflow resume ${id}`);
+      }
+    }
+  }
+}
+
+if (!activeFound) {
+  // Check for blocked tasks
+  for (const file of files) {
+    const filePath = path.join(tasksDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    if (/status:\s*BLOCKED/.test(content)) {
+      const idMatch = content.match(/^id:\s*(.+)$/m);
+      const titleMatch = content.match(/^title:\s*(.+)$/m);
+      if (idMatch && titleMatch) {
+        console.log(`BLOCKED: ${idMatch[1].trim()} "${titleMatch[1].trim()}". Check blockers in task file.`);
+      }
+    }
+  }
+}
+
+process.exit(0);

package/template/.claude/hooks/stop-failure-handler.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// StopFailure hook: handle rate limits, auth failures, max tokens, and other session-ending errors
+// Preserves task state and provides recovery instructions
+
+const fs = require('fs');
+const path = require('path');
+
+// Timeout: exit if stdin hangs
+setTimeout(() => process.exit(0), 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const errorType = data.stop_failure_error_type || data.error_type || 'unknown';
+
+    // Log the failure
+    const reportsDir = path.join(process.cwd(), '.claude', 'reports');
+    if (!fs.existsSync(reportsDir)) {
+      fs.mkdirSync(reportsDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString();
+    const logPath = path.join(reportsDir, 'session-failures.log');
+    fs.appendFileSync(logPath, `| ${timestamp} | ${errorType} | ${JSON.stringify(data).substring(0, 500)} |\n`);
+
+    // Save task state snapshot for recovery
+    const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+    if (fs.existsSync(tasksDir)) {
+      const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+      for (const tf of taskFiles) {
+        const taskPath = path.join(tasksDir, tf);
+        const content = fs.readFileSync(taskPath, 'utf-8');
+        if (/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING)/.test(content)) {
+          // Mark task as interrupted
+          const id = (content.match(/^id:\s*(.+)$/m) || [])[1] || 'UNKNOWN';
+          const snapshotDir = path.join(reportsDir, 'executions');
+          if (!fs.existsSync(snapshotDir)) {
+            fs.mkdirSync(snapshotDir, { recursive: true });
+          }
+          const snapshot = {
+            timestamp,
+            task_id: id.trim(),
+            error_type: errorType,
+            recovery_action: getRecoveryAction(errorType),
+            state_preserved: true
+          };
+          const snapshotPath = path.join(snapshotDir, `${id.trim()}_interrupted_${Date.now()}.json`);
+          fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+          break;
+        }
+      }
+    }
+
+    // Output recovery instructions
+    console.log(`\nSESSION FAILURE: ${errorType}`);
+    console.log(`Recovery: ${getRecoveryAction(errorType)}`);
+    console.log('Task state has been preserved. Resume with: claude --continue');
+  } catch (e) {
+    console.log('Session ended unexpectedly. Resume with: claude --continue');
+  }
+  process.exit(0);
+});
+
+function getRecoveryAction(errorType) {
+  const actions = {
+    'rate_limit': 'Wait 60 seconds, then resume: claude --continue',
+    'authentication_failed': 'Re-authenticate: check API key or run claude auth login',
+    'billing_error': 'Check billing at console.anthropic.com, then resume',
+    'invalid_request': 'Review last action — may need to reduce context. Resume with /compact first',
+    'server_error': 'Transient error — retry: claude --continue',
+    'max_output_tokens': 'Output was truncated. Resume to continue generation: claude --continue'
+  };
+  return actions[errorType] || 'Resume session: claude --continue';
+}

package/template/.claude/hooks/tool-failure-tracker.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// PostToolUseFailure hook: track tool failures for debugging and execution reports
+// Logs every tool failure with context so patterns can be identified
+
+const fs = require('fs');
+const path = require('path');
+
+// Timeout: exit if stdin hangs
+setTimeout(() => process.exit(0), 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || 'unknown';
+    const error = data.tool_error || data.error || 'unknown error';
+    const toolInput = data.tool_input || {};
+
+    // Log to failure tracking file
+    const reportsDir = path.join(process.cwd(), '.claude', 'reports');
+    if (!fs.existsSync(reportsDir)) {
+      fs.mkdirSync(reportsDir, { recursive: true });
+    }
+
+    const logPath = path.join(reportsDir, 'tool-failures.log');
+    const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const entry = `| ${timestamp} | ${toolName} | ${String(error).substring(0, 200).replace(/\n/g, ' ')} | ${JSON.stringify(toolInput).substring(0, 200)} |\n`;
+
+    fs.appendFileSync(logPath, entry);
+
+    // Also log to active task's changes log if one exists
+    const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+    if (fs.existsSync(tasksDir)) {
+      const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+      for (const tf of taskFiles) {
+        const taskPath = path.join(tasksDir, tf);
+        const content = fs.readFileSync(taskPath, 'utf-8');
+        if (/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING)/.test(content)) {
+          const taskLogPath = taskPath.replace(/\.md$/, '_changes.log');
+          fs.appendFileSync(taskLogPath, `| ${timestamp} | TOOL_FAILURE | ${toolName}: ${String(error).substring(0, 100)} |\n`);
+          break;
+        }
+      }
+    }
+
+    // Output warning to stderr (visible to user)
+    process.stderr.write(`Tool failure tracked: ${toolName} — ${String(error).substring(0, 100)}\n`);
+  } catch (e) {
+    // Don't block on tracking failure
+  }
+  process.exit(0);
+});

package/template/.claude/hooks/track-file-changes.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Post-tool hook: track file changes for active task
+const fs = require('fs');
+const path = require('path');
+
+// Timeout: exit if stdin hangs
+setTimeout(() => process.exit(0), 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file) process.exit(0);
+
+    const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+    if (!fs.existsSync(tasksDir)) process.exit(0);
+
+    const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+    for (const tf of taskFiles) {
+      const taskPath = path.join(tasksDir, tf);
+      const content = fs.readFileSync(taskPath, 'utf-8');
+      if (/status:\s*(DEVELOPING|DEV_TESTING|REVIEWING|CI_PENDING|QA_TESTING)/.test(content)) {
+        const logPath = taskPath.replace(/\.md$/, '_changes.log');
+        const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+        fs.appendFileSync(logPath, `| ${timestamp} | file_changed | ${file} |\n`);
+        break;
+      }
+    }
+  } catch {}
+  process.exit(0);
+});

package/template/.claude/hooks/validate-bash.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Pre-tool hook: block dangerous bash commands
+
+// Timeout: exit if stdin hangs
+setTimeout(() => { process.stderr.write('BLOCKED: Hook timeout.\n'); process.exit(2); }, 10000);
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const cmd = (data.tool_input && data.tool_input.command) || '';
+    if (!cmd) process.exit(0);
+
+    const DANGEROUS_STRINGS = ['rm -rf /', ':(){ :|:& };:', '> /dev/sda', 'mkfs', 'dd if='];
+    const DANGEROUS_PATTERNS = [/curl\s.*\|\s*bash/, /wget\s.*\|\s*bash/];
+    for (const p of DANGEROUS_STRINGS) {
+      if (cmd.includes(p)) {
+        process.stderr.write('BLOCKED: Dangerous command.\n');
+        process.exit(2);
+      }
+    }
+    for (const rx of DANGEROUS_PATTERNS) {
+      if (rx.test(cmd)) {
+        process.stderr.write('BLOCKED: Dangerous command.\n');
+        process.exit(2);
+      }
+    }
+  } catch {
+    process.stderr.write('BLOCKED: Failed to parse hook input.\n');
+    process.exit(2);
+  }
+});

package/template/.claude/manifest.json

@@ -0,0 +1,22 @@
+{
+  "last_sync": null,
+  "last_scan": null,
+  "environment_version": "1.0.0",
+  "scanner_version": "1.0.0",
+  "agents": {},
+  "skills": {},
+  "hooks": {},
+  "rules": {},
+  "tech_stack": {},
+  "claude_md": {
+    "hash": null,
+    "line_count": null,
+    "agents_listed": null
+  },
+  "project_structure": {
+    "source_dirs": [],
+    "test_dirs": [],
+    "config_files": []
+  },
+  "_note": "This file is auto-generated by /sync. Do not edit manually."
+}

package/template/.claude/profiles/backend.md

@@ -0,0 +1,34 @@
+# Backend Developer Profile
+
+## Role
+Backend developer focused on API endpoints, services, data layer, and server-side logic.
+
+## Primary Agents
+- `@api-builder` — your main development agent
+- `@debugger` — for investigating backend issues
+- `@tester` — for writing integration tests
+
+## Key Skills
+- `/add-endpoint` — scaffold new API endpoints
+- `/fix-bug` — systematic debugging
+- `/migrate` — database migrations
+
+## Typical Workflow
+```
+/workflow new "backend feature description"
+# Phase 5 routes to @api-builder automatically
+```
+
+## Focus Areas
+- API routes, handlers, middleware
+- Database queries, migrations, seeds
+- Background jobs, queues
+- External service integrations
+- Input validation, error handling
+
+## Context Loading
+Your session loads:
+- CLAUDE.md (project overview)
+- `.claude/rules/api.md` (endpoint conventions)
+- `.claude/rules/database.md` (data layer rules)
+- `.claude/rules/security.md` (when touching auth)

package/template/.claude/profiles/devops.md

@@ -0,0 +1,36 @@
+# DevOps Profile
+
+## Role
+DevOps engineer focused on infrastructure, CI/CD, deployment, monitoring, and cloud resources.
+
+## Primary Agents
+- `@infra` — your main agent
+- `@security` — for infrastructure security review
+- `@explorer` — for investigating system architecture
+
+## Key Skills
+- `/deploy` — deploy with checks
+- `/rollback` — rollback failed deployments
+- `/architecture` — system architecture diagrams
+
+## Typical Workflow
+```
+/workflow new --hotfix "infrastructure issue"
+# Or for infra tasks:
+/workflow new "infrastructure change description"
+# Phase 5 routes to @infra automatically
+```
+
+## Focus Areas
+- Dockerfile, docker-compose
+- CI/CD pipelines (GitHub Actions, GitLab CI)
+- Cloud resources (AWS, GCP, Azure)
+- Infrastructure as Code (Terraform, Pulumi)
+- Monitoring, logging, alerting
+- Environment configuration
+
+## Context Loading
+Your session loads:
+- CLAUDE.md (project overview)
+- `.claude/rules/infrastructure.md` (deployment patterns)
+- `.claude/rules/security.md` (when touching secrets/auth)

package/template/.claude/profiles/frontend.md

@@ -0,0 +1,34 @@
+# Frontend Developer Profile
+
+## Role
+Frontend developer focused on UI components, pages, styling, state management, and accessibility.
+
+## Primary Agents
+- `@frontend` — your main development agent
+- `@debugger` — for investigating UI issues
+- `@tester` — for writing component tests
+
+## Key Skills
+- `/add-component` — scaffold new UI components
+- `/add-page` — create new routes/pages
+- `/fix-bug` — systematic debugging
+
+## Typical Workflow
+```
+/workflow new "frontend feature description"
+# Phase 5 routes to @frontend automatically
+```
+
+## Focus Areas
+- Components, pages, layouts
+- Styling (CSS modules, Tailwind, styled-components)
+- State management (Redux, Zustand, Context)
+- Client-side routing
+- Accessibility (ARIA, keyboard, screen readers)
+- Responsive design
+
+## Context Loading
+Your session loads:
+- CLAUDE.md (project overview)
+- `.claude/rules/frontend.md` (component patterns)
+- `.claude/rules/testing.md` (when writing tests)

package/template/.claude/rules/context-budget.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - "**/*"
+---
+# Context Budget Enforcement
+
+## Limits
+- Root CLAUDE.md: max 150 lines (hard limit 200)
+- Module CLAUDE.md: max 80 lines each
+- Rules: max 50 lines each, MUST have `paths:` for scoping
+- Skills: MUST use `context: fork` for anything over 30 lines
+- MCP servers: max 5 active, scoped to agents via `mcpServers:`
+- Startup: under 20% context
+- Working: under 60% context — THIS IS THE HARD BUDGET
+
+## Runtime Enforcement
+- Run `/context-check` between EVERY workflow phase transition
+- If context > 60%: STOP and compact before continuing
+- If context > 75%: compact aggressively, consider session split
+- Compact command: `/compact "focus on [current task/phase]"`
+- `/clear` between unrelated tasks — never reuse a bloated session
+
+## What Costs Zero
+- Subagent context (separate window)
+- `context: fork` skills (isolated)
+- Templates, profiles, docs (never auto-loaded)
+- Agent bodies (load only in subagent)
+
+## What Accumulates (danger)
+- File reads in main context stay in history
+- Agent results returned to main context
+- Bash outputs (especially long ones)
+- Non-forked skill invocations
+- Inline code review diffs