claude-code-scanner 1.0.0

package/template/.claude/scripts/verify-setup.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// Cross-platform verification of Claude Code environment — replaces verify-setup.sh
+const fs = require('fs');
+const path = require('path');
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+let PASS = 0, FAIL = 0, WARN = 0;
+
+function check(label, condition) {
+  if (condition) { console.log(`  ${GREEN}[PASS]${RESET} ${label}`); PASS++; }
+  else { console.log(`  ${RED}[FAIL]${RESET} ${label}`); FAIL++; }
+}
+
+function warn(label, condition) {
+  if (condition) { console.log(`  ${GREEN}[OK]  ${RESET} ${label}`); }
+  else { console.log(`  ${YELLOW}[WARN]${RESET} ${label}`); WARN++; }
+}
+
+function lineCount(filePath) {
+  try { return fs.readFileSync(filePath, 'utf-8').split('\n').length; } catch { return 999; }
+}
+
+function fileContains(filePath, text) {
+  try { return fs.readFileSync(filePath, 'utf-8').includes(text); } catch { return false; }
+}
+
+function fileMatchesRegex(filePath, regex) {
+  try { return regex.test(fs.readFileSync(filePath, 'utf-8')); } catch { return false; }
+}
+
+function isValidJSON(filePath) {
+  try { JSON.parse(fs.readFileSync(filePath, 'utf-8')); return true; } catch { return false; }
+}
+
+function globDir(dir, ext) {
+  try { return fs.readdirSync(dir).filter(f => f.endsWith(ext)).map(f => path.join(dir, f)); } catch { return []; }
+}
+
+function readFile(filePath) {
+  try { return fs.readFileSync(filePath, 'utf-8'); } catch { return ''; }
+}
+
+const cwd = process.cwd();
+
+console.log('=== Claude Code Environment Verification ===\n');
+
+// --- CLAUDE.md ---
+console.log('--- CLAUDE.md ---');
+const claudeMd = path.join(cwd, 'CLAUDE.md');
+check('Exists', fs.existsSync(claudeMd));
+check('Under 200 lines (recommended)', fs.existsSync(claudeMd) && lineCount(claudeMd) <= 200);
+warn('Under 150 lines (optimal)', fs.existsSync(claudeMd) && lineCount(claudeMd) <= 150);
+warn('No placeholders', fs.existsSync(claudeMd) && !fileMatchesRegex(claudeMd, /\{[^}]+\}/));
+
+// --- Rules ---
+console.log('--- Rules ---');
+const rulesDir = path.join(cwd, '.claude', 'rules');
+check('Directory exists', fs.existsSync(rulesDir));
+for (const f of globDir(rulesDir, '.md')) {
+  const name = path.basename(f);
+  check(`${name} under 50 lines`, lineCount(f) <= 50);
+  check(`${name} has paths:`, fileContains(f, 'paths:'));
+}
+
+// --- Agents (12 required) ---
+console.log('--- Agents ---');
+const agentsDir = path.join(cwd, '.claude', 'agents');
+const requiredAgents = [
+  'team-lead', 'architect', 'product-owner', 'qa-lead',
+  'explorer', 'reviewer', 'security', 'debugger', 'tester',
+  'frontend', 'api-builder', 'infra'
+];
+const readOnlyAgents = ['explorer', 'reviewer', 'security', 'architect', 'product-owner', 'qa-lead'];
+const worktreeAgents = ['frontend', 'api-builder'];
+
+for (const agentName of requiredAgents) {
+  const agentFile = path.join(agentsDir, `${agentName}.md`);
+  check(`${agentName}.md exists`, fs.existsSync(agentFile));
+}
+
+for (const f of globDir(agentsDir, '.md')) {
+  const name = path.basename(f, '.md');
+  const content = readFile(f);
+  check(`${name} has name:`, fileMatchesRegex(f, /^name:/m));
+  check(`${name} has description:`, fileMatchesRegex(f, /^description:/m));
+  check(`${name} has memory: project`, content.includes('memory: project'));
+  check(`${name} has HANDOFF block`, content.includes('HANDOFF'));
+  check(`${name} has Limitations section`, content.includes('Limitations') || content.includes('limitations'));
+
+  if (readOnlyAgents.includes(name)) {
+    check(`${name} has permissionMode: plan`, content.includes('permissionMode: plan'));
+    check(`${name} has disallowedTools`, content.includes('disallowedTools:'));
+  }
+
+  if (worktreeAgents.includes(name)) {
+    warn(`${name} has isolation: worktree`, content.includes('isolation: worktree'));
+  }
+}
+
+// --- Skills ---
+console.log('--- Skills ---');
+const skillsDir = path.join(cwd, '.claude', 'skills');
+if (fs.existsSync(skillsDir)) {
+  for (const d of fs.readdirSync(skillsDir, { withFileTypes: true }).filter(e => e.isDirectory())) {
+    const skillMd = path.join(skillsDir, d.name, 'SKILL.md');
+    check(`${d.name} has SKILL.md`, fs.existsSync(skillMd));
+    if (fs.existsSync(skillMd)) {
+      check(`${d.name} has name:`, fileMatchesRegex(skillMd, /^name:/m));
+      check(`${d.name} has description:`, fileMatchesRegex(skillMd, /^description:/m));
+    }
+  }
+}
+
+// Check heavy skills have context: fork
+const heavySkills = ['scan-codebase', 'generate-environment', 'workflow', 'task-tracker', 'impact-analysis', 'metrics', 'progress-report', 'execution-report'];
+for (const skillName of heavySkills) {
+  const skillMd = path.join(skillsDir, skillName, 'SKILL.md');
+  if (fs.existsSync(skillMd)) {
+    check(`${skillName} has context: fork`, fileContains(skillMd, 'context: fork'));
+  }
+}
+
+// Check workflow has disable-model-invocation and handoff protocol
+const workflowSkill = path.join(skillsDir, 'workflow', 'SKILL.md');
+if (fs.existsSync(workflowSkill)) {
+  check('workflow has disable-model-invocation', fileContains(workflowSkill, 'disable-model-invocation: true'));
+  check('workflow has handoff protocol', fileContains(workflowSkill, 'HANDOFF'));
+}
+
+// --- Settings ---
+console.log('--- Settings ---');
+const settingsPath = path.join(cwd, '.claude', 'settings.json');
+check('settings.json valid JSON', fs.existsSync(settingsPath) && isValidJSON(settingsPath));
+
+if (fs.existsSync(settingsPath) && isValidJSON(settingsPath)) {
+  const settings = JSON.parse(readFile(settingsPath));
+  check('has permissions.defaultMode', settings.permissions && settings.permissions.defaultMode);
+  check('has permissions.allow', settings.permissions && Array.isArray(settings.permissions.allow));
+  check('has permissions.deny', settings.permissions && Array.isArray(settings.permissions.deny));
+  check('has env section', settings.hasOwnProperty('env'));
+  check('has hooks section', settings.hasOwnProperty('hooks'));
+
+  // Check all hook scripts referenced in settings actually exist
+  if (settings.hooks) {
+    for (const [event, matchers] of Object.entries(settings.hooks)) {
+      for (const matcher of matchers) {
+        for (const hook of (matcher.hooks || [])) {
+          if (hook.type === 'command' && hook.command) {
+            const match = hook.command.match(/node\s+(.+\.js)/);
+            if (match) {
+              const hookFile = path.join(cwd, match[1]);
+              check(`${event} hook ${path.basename(match[1])} exists`, fs.existsSync(hookFile));
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+const gitignorePath = path.join(cwd, '.gitignore');
+warn('settings.local.json in .gitignore', fs.existsSync(gitignorePath) && fileContains(gitignorePath, 'settings.local.json'));
+
+// --- Hooks ---
+console.log('--- Hooks ---');
+const hooksDir = path.join(cwd, '.claude', 'hooks');
+if (fs.existsSync(hooksDir)) {
+  for (const f of fs.readdirSync(hooksDir).filter(f => f.endsWith('.js'))) {
+    const hookPath = path.join(hooksDir, f);
+    check(`${f} exists`, fs.existsSync(hookPath));
+  }
+}
+
+// --- Task Record Schema ---
+console.log('--- Docs ---');
+const taskSchema = path.join(cwd, '.claude', 'docs', 'task-record-schema.md');
+if (fs.existsSync(taskSchema)) {
+  check('Task schema has Loop State section', fileContains(taskSchema, 'Loop State'));
+  check('Task schema has Handoff Log section', fileContains(taskSchema, 'Handoff Log'));
+}
+
+const flowEngine = path.join(cwd, '.claude', 'docs', 'flow-engine.md');
+if (fs.existsSync(flowEngine)) {
+  check('Flow engine has Handoff Protocol', fileContains(flowEngine, 'Handoff Protocol'));
+  check('Flow engine has Orchestration Model', fileContains(flowEngine, 'Orchestration Model'));
+  check('Flow engine documents subagent limitation', fileContains(flowEngine, 'cannot spawn other subagents'));
+}
+
+// --- Context Budget ---
+console.log('--- Context Budget ---');
+const clLines = fs.existsSync(claudeMd) ? lineCount(claudeMd) : 999;
+let rlLines = 0;
+for (const f of globDir(rulesDir, '.md')) {
+  rlLines += lineCount(f);
+}
+console.log(`  CLAUDE.md: ${clLines} lines | Rules: ${rlLines} lines | Total: ${clLines + rlLines}`);
+check('Combined under 200 lines', (clLines + rlLines) <= 200);
+
+// --- Summary ---
+console.log(`\n=== PASS: ${PASS} | FAIL: ${FAIL} | WARN: ${WARN} ===`);
+if (FAIL === 0) {
+  console.log('STATUS: ALL CHECKS PASSED');
+} else {
+  console.log(`STATUS: ${FAIL} FAILURES — fix before using`);
+  process.exit(1);
+}

package/template/.claude/settings.json

@@ -0,0 +1,154 @@
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(git status)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git branch *)",
+      "Bash(git checkout -b *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(sudo *)",
+      "Bash(git push --force *)",
+      "Bash(git reset --hard)"
+    ]
+  },
+  "env": {},
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/session-start.js"
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/drift-detector.js",
+            "statusMessage": "Checking for environment drift..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/protect-files.js"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/validate-bash.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-edit-format.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/track-file-changes.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/tool-failure-tracker.js",
+            "statusMessage": "Logging tool failure..."
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-compact-save.js",
+            "statusMessage": "Saving critical state before compaction..."
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-compact-recovery.js",
+            "statusMessage": "Recovering workflow state..."
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "permission_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/notify-approval.js"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/execution-report.js",
+            "statusMessage": "Collecting execution metrics..."
+          },
+          {
+            "type": "prompt",
+            "prompt": "MANDATORY POST-EXECUTION REPORT: Before confirming completion, you MUST generate an execution report. Do the following:\n\n1. Check if task is complete (tests pass, no lint errors, no type errors)\n2. Read the latest execution snapshot from .claude/reports/executions/\n3. Generate a summary report with:\n   - SUCCESS SCORE (0-100): completeness + quality + efficiency\n   - TOKEN/CONTEXT USAGE: estimate tokens used, peak context %\n   - AGENT COMMUNICATION: which agents ran, handoff count, loop iterations\n   - HALLUCINATION CHECK: verify all file:line refs exist, function names are real, patterns match project conventions\n   - REGRESSION IMPACT: run test suite, check coverage delta, flag new failures\n4. Save the report to .claude/reports/executions/\n5. Return {\"ok\": true/false, \"score\": N, \"hallucination\": 0-3, \"regression\": 0-3, \"summary\": \"one-line\"}\n\nIf score < 50 or hallucination >= 2 or regression >= 2, set ok=false with reason.",
+            "model": "haiku"
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "matcher": "rate_limit|authentication_failed|billing_error|invalid_request|server_error|max_output_tokens",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/stop-failure-handler.js",
+            "statusMessage": "Preserving state after failure..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/context-check/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: context-check
+description: Check current context usage and enforce the 60% working budget. Use between workflow phases, after heavy operations, or when context feels slow. Recommends compaction if over budget.
+user-invocable: true
+allowed-tools: Read, Bash, Grep, Glob
+argument-hint: "[--compact] [--force]"
+---
+
+# Context Check: $ARGUMENTS
+
+## Step 1: Measure Current Context
+
+**Important:** If running inside a `context: fork` skill (like `/workflow`), `/context` measures the FORK's context, not the parent session. This is still useful — the fork has its own context budget that must be managed.
+
+Run the built-in context command to get actual usage:
+```
+/context
+```
+
+Read the output and extract:
+- **Current context %**: the primary metric (of fork or parent, depending on where you are)
+- **Largest consumers**: what's taking the most space
+- **Conversation history size**: how much is accumulated messages
+
+## Step 2: Evaluate Against Budget
+
+| Threshold | Status | Action Required |
+|-----------|--------|----------------|
+| Under 20% | STARTUP | Normal — plenty of room |
+| 20-40% | GREEN | Good — working comfortably |
+| 40-60% | YELLOW | Caution — approaching budget limit |
+| 60-75% | ORANGE | OVER BUDGET — compact immediately |
+| 75-90% | RED | CRITICAL — compact with focus, clear if possible |
+| 90%+ | EMERGENCY | Auto-compaction imminent — state may be lost |
+
+## Step 3: Context Reduction Actions
+
+### If YELLOW (40-60%):
+1. Check: are there large file reads in history that are no longer needed?
+2. Check: have any non-fork skills been invoked inline?
+3. Recommend: `/compact "focus on [current phase] for [task-id]"`
+
+### If ORANGE (60-75%) — MANDATORY ACTION:
+1. **Compact NOW**: `/compact "Preserve: task [id] phase [N], loop state, pending decisions. Discard: file contents, exploration results, completed phase details."`
+2. After compaction, verify: re-read active task file to restore state
+3. Log context pressure event in task record
+
+### If RED (75-90%) — EMERGENCY:
+1. **Save state**: Read active task file, note current phase and loop state
+2. **Compact aggressively**: `/compact "ONLY preserve: task [id], current phase [N], loop counters, acceptance criteria status. Discard everything else."`
+3. **Consider session split**: If a long workflow, start a new session for remaining phases: `claude --continue`
+4. **Route remaining work through fork**: Use `context: fork` skills or subagents for all remaining operations
+
+### If EMERGENCY (90%+):
+1. Auto-compaction will fire — PreCompact hook preserves critical state
+2. After compaction, PostCompact hook re-injects loop state, handoffs, blockers
+3. Re-read the active task file immediately to restore full context
+4. Consider: `/clear` and start fresh if task can resume from saved state
+
+## Step 4: Context Optimization Recommendations
+
+Check and report on each:
+
+### Conversation History
+- **Accumulated file reads**: Large files read but no longer relevant — compact will reclaim this
+- **Agent return values**: Each agent invocation in main context adds its full output — use fork agents when possible
+- **Tool outputs**: Bash command outputs accumulate — long outputs are especially expensive
+
+### Loaded Resources
+- **MCP servers**: Each server loads tool definitions on every request (~200-2k tokens each)
+- **Rules without paths**: Rules missing `paths:` frontmatter load unconditionally
+- **Unfork'd skills**: Skills without `context: fork` load their full body into parent context
+
+### Optimization Actions
+1. **Largest consumer**: Identify what's using the most context and recommend action
+2. **Unnecessary loads**: Flag any always-loaded content that could be on-demand
+3. **Session hygiene**: Recommend `/clear` if switching to an unrelated task
+
+## Step 5: Log Context Pressure
+
+If context > 60%, append to active task record:
+```markdown
+## Context Pressure Log
+| Timestamp | Context % | Action Taken | Result |
+|-----------|-----------|-------------|--------|
+| {timestamp} | {N}% | compacted with focus on Phase {N} | reduced to {M}% |
+```
+
+## Output Format
+```
+CONTEXT CHECK RESULT
+====================
+Current Usage:  {N}%
+Status:         {GREEN/YELLOW/ORANGE/RED/EMERGENCY}
+Budget (60%):   {WITHIN/OVER by N%}
+
+Top Consumers:
+  1. Conversation history: ~{N}%
+  2. CLAUDE.md + rules: ~{N}%
+  3. Skill/agent metadata: ~{N}%
+  4. MCP tools: ~{N}%
+
+Action: {NONE / COMPACT RECOMMENDED / COMPACT REQUIRED / EMERGENCY}
+Command: {specific /compact command if needed}
+```
+
+## Auto-Invocation
+This skill should be called:
+1. By `/workflow` between every phase transition
+2. By `@team-lead` before assigning heavy work
+3. Manually whenever responses feel slow or truncated
+4. After any operation that reads many large files