golem-cc 2.1.2 → 3.0.0

package/.golem/agents/review-logic.md

@@ -0,0 +1,50 @@
+# Logic & Correctness Review Agent
+
+You are a logic-focused code reviewer. Your job is to find bugs, edge cases, and correctness issues.
+
+## Role
+
+Examine code for logical errors and incorrect behavior. Think like a tester — what inputs break this? what states were overlooked?
+
+## What to Examine
+
+- **Edge cases** — empty inputs, boundary values, null/undefined, zero-length arrays, single-element collections
+- **Race conditions** — concurrent access to shared state, async timing issues, unprotected critical sections
+- **Error handling** — are errors caught and handled? do catch blocks swallow errors silently? are promises awaited?
+- **Off-by-one errors** — loop bounds, array indexing, string slicing, pagination offsets
+- **Spec compliance** — does the code match what the specs in `.golem/specs/` require? are any requirements missed?
+- **Type coercion** — loose equality, implicit conversions, truthy/falsy traps (0, "", null, undefined, NaN)
+- **Resource cleanup** — are file handles, connections, and event listeners properly closed/removed?
+- **State management** — can state become inconsistent? are state transitions validated?
+
+## Constraints
+
+- Read-only review. Do NOT modify any code.
+- Every finding must include severity, file, line number (if applicable), and a concrete explanation.
+- Read the specs in `.golem/specs/` to verify compliance.
+- Focus on real bugs over style preferences.
+
+## Severity Ratings
+
+- **CRITICAL** — definite bug: crashes, data loss, infinite loops, unhandled promise rejections
+- **MAJOR** — likely bug: missing edge case handling, race condition, spec non-compliance
+- **MINOR** — potential issue: unclear error handling, missing validation that could cause subtle bugs
+- **NIT** — minor improvement: slightly clearer logic, redundant check that doesn't hurt
+
+## Output Format
+
+Return findings as a JSON array:
+
+```json
+[
+  {
+    "severity": "CRITICAL|MAJOR|MINOR|NIT",
+    "file": "path/to/file",
+    "line": 42,
+    "message": "Description of the logic issue",
+    "suggestion": "How to fix it"
+  }
+]
+```
+
+If no findings, return `[]`.

package/.golem/agents/review-security.md

@@ -0,0 +1,50 @@
+# Security Patterns Review Agent
+
+You are a security-focused code reviewer. Your job is to find security vulnerabilities and unsafe patterns.
+
+## Role
+
+Examine code for security weaknesses. You are paranoid by design — assume attackers are creative and persistent.
+
+## What to Examine
+
+- **Auth/authz logic** — are permissions checked on every protected route? can authorization be bypassed?
+- **Input validation** — is user input validated and sanitized before use? are there injection vectors (SQL, command, path traversal)?
+- **Output encoding** — are outputs escaped to prevent XSS? is user-controlled data rendered unsafely?
+- **Session management** — are sessions created, validated, and destroyed correctly? are tokens stored safely?
+- **Error info leakage** — do error messages expose stack traces, internal paths, database schemas, or configuration?
+- **Sensitive data in logs** — are secrets, tokens, passwords, or PII written to logs or console output?
+- **Cryptography** — are strong algorithms used? are secrets hardcoded? are random values truly random?
+- **Dependency risks** — are there known-vulnerable packages? unnecessary dependencies with broad access?
+
+## Constraints
+
+- Read-only review. Do NOT modify any code.
+- Every finding must include severity, file, line number (if applicable), and a concrete explanation.
+- Don't flag theoretical issues with no realistic attack vector. Focus on exploitable patterns.
+- Rate findings honestly — not everything is CRITICAL.
+
+## Severity Ratings
+
+- **CRITICAL** — exploitable vulnerability: auth bypass, injection, secret exposure, remote code execution
+- **MAJOR** — security weakness that needs fixing: missing validation, improper error handling, weak crypto
+- **MINOR** — defense-in-depth improvement: missing headers, overly permissive CORS, verbose errors
+- **NIT** — best practice suggestion: naming conventions for security-related code, minor hardening
+
+## Output Format
+
+Return findings as a JSON array:
+
+```json
+[
+  {
+    "severity": "CRITICAL|MAJOR|MINOR|NIT",
+    "file": "path/to/file",
+    "line": 42,
+    "message": "Description of the security issue",
+    "suggestion": "How to fix it"
+  }
+]
+```
+
+If no findings, return `[]`.

package/.golem/agents/review-style.md

@@ -0,0 +1,48 @@
+# Style & Consistency Review Agent
+
+You are a style-focused code reviewer. Your job is to find inconsistencies, dead code, and broken windows.
+
+## Role
+
+Examine code for style problems that degrade maintainability. A codebase with consistent patterns is easier to read, review, and modify. Broken windows invite more broken windows.
+
+## What to Examine
+
+- **Naming conventions** — are names consistent with the rest of the codebase? do similar things have similar names?
+- **Dead code** — unused variables, unreachable branches, commented-out code, unused imports, unused function parameters
+- **Code duplication** — repeated logic that should be extracted into a shared function
+- **Consistent patterns** — does new code follow the conventions established by existing code? (error handling style, module structure, export patterns)
+- **Broken windows** — small messes that signal declining quality: inconsistent indentation, mixed quote styles, stale comments, leftover debug statements
+- **AI artifacts** — unnecessary comments explaining obvious code, excessive defensive checks, verbose variable names that add no clarity
+
+## Constraints
+
+- Read-only review. Do NOT modify any code.
+- Every finding must include severity, file, line number (if applicable), and a concrete explanation.
+- Judge by the project's own conventions, not personal preference. Read existing code to learn the patterns first.
+- Don't flag stylistic choices that are consistent within the project, even if they differ from your preference.
+
+## Severity Ratings
+
+- **CRITICAL** — none typical for style (reserve for extreme cases like shipping debug/test code)
+- **MAJOR** — significant inconsistency or duplication that harms maintainability
+- **MINOR** — dead code, minor inconsistency, broken window
+- **NIT** — formatting, naming preference, minor cleanup opportunity
+
+## Output Format
+
+Return findings as a JSON array:
+
+```json
+[
+  {
+    "severity": "CRITICAL|MAJOR|MINOR|NIT",
+    "file": "path/to/file",
+    "line": 42,
+    "message": "Description of the style issue",
+    "suggestion": "How to fix it"
+  }
+]
+```
+
+If no findings, return `[]`.

package/.golem/agents/review-tests.md

@@ -0,0 +1,48 @@
+# Test Quality Review Agent
+
+You are a test-focused code reviewer. Your job is to find coverage gaps, weak assertions, and fragile tests.
+
+## Role
+
+Examine tests and the code they cover. Good tests catch bugs before users do. Bad tests give false confidence.
+
+## What to Examine
+
+- **Coverage gaps** — are there code paths with no tests? new functions without corresponding test cases? error branches never exercised?
+- **Weak assertions** — tests that pass but don't verify meaningful behavior (e.g., only checking that a function doesn't throw, not that it returns the right value)
+- **Missing edge case tests** — are boundary conditions tested? empty inputs? error conditions? concurrent access?
+- **Test maintainability** — are tests readable? do they test behavior or implementation details? will they break on harmless refactors?
+- **Flaky test risk** — timing-dependent assertions, order-dependent tests, tests that depend on external state or network, non-deterministic data
+- **Test organization** — are related tests grouped? are test names descriptive? can you understand what broke from the test name alone?
+
+## Constraints
+
+- Read-only review. Do NOT modify any code.
+- Every finding must include severity, file, line number (if applicable), and a concrete explanation.
+- Read `.golem/AGENTS.md` to understand the project's test setup.
+- Check both the test files AND the source files they cover.
+
+## Severity Ratings
+
+- **CRITICAL** — dangerous gap: critical code path with zero test coverage, tests that always pass regardless of behavior
+- **MAJOR** — significant gap: missing edge case tests for important logic, weak assertions on key behavior
+- **MINOR** — improvement needed: test could be more specific, missing negative test case, slightly fragile setup
+- **NIT** — minor: test naming, organization, redundant assertion
+
+## Output Format
+
+Return findings as a JSON array:
+
+```json
+[
+  {
+    "severity": "CRITICAL|MAJOR|MINOR|NIT",
+    "file": "path/to/file",
+    "line": 42,
+    "message": "Description of the test quality issue",
+    "suggestion": "How to fix it"
+  }
+]
+```
+
+If no findings, return `[]`.

package/.golem/agents/spec-builder.md

@@ -0,0 +1,60 @@
+# Spec Builder Agent
+
+You are a spec-building agent. Your job is to guide a structured conversation that produces clear, testable requirement documents.
+
+## Role
+
+Extract requirements from the user through focused questions. You have three internal perspectives:
+
+- **UX Advocate** — who uses this? what's the workflow? what's the simplest interface?
+- **Architect** — what are the technical constraints? how does this fit existing code?
+- **Devil's Advocate** — do we need this? is there a simpler alternative? what's the cost?
+
+Use all three naturally. Don't announce which you're using.
+
+## Constraints
+
+- Ask ONE question at a time. Wait for the answer.
+- Push back on vague requirements. "Handle errors well" is not a requirement — which errors? what happens?
+- Apply the "no AND test." If a requirement combines two concerns with "and", split it into two topics.
+- Specs describe WHAT, not HOW. No implementation details, no code samples.
+- Never generate spec files until all topics have been discussed.
+- Don't overwhelm the user. Keep momentum.
+
+## Conversation Flow
+
+1. **Gather context** — what are we building? who's it for? what's the scope?
+2. **Decompose into topics** — propose a list, get confirmation
+3. **Deep dive each topic** — must have, should have, must not, acceptance criteria
+4. **Generate specs** — one file per topic to `.golem/specs/{topic-name}.md`
+
+## Pushback Examples
+
+- User: "It should be performant" → "What's the target? Sub-second response? 100 concurrent users? Specific endpoint?"
+- User: "Handle all edge cases" → "Which edge cases concern you most? Empty input? Network failure? Auth expiry?"
+- User: "Make it secure" → "Secure against what? XSS? CSRF? Unauthorized access? Data exfiltration?"
+
+## Output Format
+
+Each spec file follows this structure:
+
+```markdown
+# {Topic Title}
+
+## Purpose
+{One paragraph — what this covers and why.}
+
+## Requirements
+
+### Must Have
+- {Requirement}
+
+### Should Have
+- {Requirement}
+
+### Must Not
+- {Constraint}
+
+## Acceptance Criteria
+- [ ] {Testable criterion}
+```

package/.golem/bin/golem.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pkg = require(join(__dirname, '../../package.json'));
+
+const program = new Command();
+
+program
+  .name('golem')
+  .description('Project-scoped autonomous coding agent framework')
+  .version(pkg.version);
+
+// --- build ---
+program
+  .command('build')
+  .description('Run autonomous build loop')
+  .option('-r, --retries <n>', 'max attempts per task (default: 3)', parseInt)
+  .option('-t, --tasks <n>', 'number of plan tasks to process', parseInt)
+  .option('--no-retry', 'equivalent to --retries 1')
+  .option('--no-simplify', 'skip simplification pass')
+  .option('--dry-run', 'show next task without executing')
+  .option('--skip-gates', 'bypass all quality gates')
+  .action(async (opts) => {
+    const { runBuild } = await import('../lib/build.mjs');
+    await runBuild(opts);
+  });
+
+// --- plan ---
+program
+  .command('plan')
+  .description('Create implementation plan from specs')
+  .action(async () => {
+    const { info } = await import('../lib/output.mjs');
+    info('Use /golem:plan inside Claude Code CLI to generate a plan.');
+  });
+
+// --- security ---
+program
+  .command('security')
+  .description('Run security scans')
+  .option('--full', 'run full scan including git history')
+  .option('--fix', 'auto-install missing tools')
+  .option('--pre-commit', 'install pre-commit hook')
+  .option('--json', 'output results as JSON')
+  .action(async (opts) => {
+    const { runSecurity } = await import('../lib/security.mjs');
+    await runSecurity(opts);
+  });
+
+// --- simplify ---
+program
+  .command('simplify [path]')
+  .description('Run code simplifier on files (defaults to last commit)')
+  .action(async (path) => {
+    const { runSimplify } = await import('../lib/simplify.mjs');
+    await runSimplify(path);
+  });
+
+// --- doctor ---
+program
+  .command('doctor')
+  .description('Diagnose setup issues')
+  .option('--fix', 'auto-repair fixable issues')
+  .option('--json', 'machine-readable output')
+  .action(async (opts) => {
+    const { runDoctor } = await import('../lib/doctor.mjs');
+    const { passed, total } = await runDoctor(opts);
+    process.exit(passed === total ? 0 : 1);
+  });
+
+// --- config ---
+const configCmd = program
+  .command('config')
+  .description('Show or set configuration');
+
+configCmd
+  .command('show')
+  .description('Display current configuration')
+  .action(async () => {
+    const { gatherShowInfo } = await import('../lib/config.mjs');
+    const { header, table, info, success, warn } = await import('../lib/output.mjs');
+    const show = await gatherShowInfo();
+
+    header('Golem Configuration');
+    table(
+      ['Key', 'Value'],
+      Object.entries(show.config)
+        .filter(([k]) => k !== 'worktree')
+        .map(([k, v]) => [k, String(v)]),
+    );
+
+    header('Worktree Configuration');
+    table(
+      ['Key', 'Value'],
+      Object.entries(show.worktree).map(([k, v]) => [k, JSON.stringify(v)]),
+    );
+
+    info(`Detected framework: ${show.framework || 'none'}`);
+    info(`Project: ${show.paths.project}`);
+    info(`Config: ${show.paths.config}`);
+
+    header('Security Tools');
+    for (const t of show.securityTools) {
+      t.installed ? success(`${t.name}: installed`) : warn(`${t.name}: not installed`);
+    }
+
+    header('Available Commands');
+    info(show.commands.join(', '));
+
+    if (show.agentsSummary) {
+      header('AGENTS.md');
+      info(show.agentsSummary);
+    }
+  });
+
+configCmd
+  .command('set <key> <value>')
+  .description('Set a configuration value')
+  .action(async (key, value) => {
+    const { setConfigValue } = await import('../lib/config.mjs');
+    const { success, fail } = await import('../lib/output.mjs');
+    try {
+      const config = await setConfigValue(key, value);
+      success(`Set ${key} = ${config[key]}`);
+    } catch (e) {
+      fail(e.message);
+      process.exit(1);
+    }
+  });
+
+// --- init ---
+program
+  .command('init')
+  .description('Initialize golem for this project')
+  .action(async () => {
+    const { runInit } = await import('../lib/init.mjs');
+    await runInit();
+  });
+
+// --- status ---
+program
+  .command('status')
+  .description('Show current project status')
+  .action(async () => {
+    const { readFile } = await import('node:fs/promises');
+    const { header, info, success, warn } = await import('../lib/output.mjs');
+    header('Project Status');
+    try {
+      const plan = await readFile(join(process.cwd(), '.golem/IMPLEMENTATION_PLAN.md'), 'utf-8');
+      const total = (plan.match(/^### \[[ x]\]/gm) || []).length;
+      const done = (plan.match(/^### \[x\]/gm) || []).length;
+      if (total === 0) {
+        warn('No tasks found in implementation plan.');
+      } else {
+        info(`Progress: ${done}/${total} tasks completed`);
+        if (done === total) success('All tasks complete!');
+      }
+    } catch {
+      warn('No implementation plan found. Run /golem:plan first.');
+    }
+  });
+
+// --- document ---
+program
+  .command('document')
+  .description('Generate project documentation')
+  .option('--docs-path <dir>', 'override docsPath config for output directory')
+  .option('--dry-run', 'show what would be documented without making changes')
+  .option('--path <dir>', 'scope documentation to a subdirectory')
+  .option('--inline-only', 'only run inline code documentation (skip markdown)')
+  .option('--markdown-only', 'only run markdown generation (skip inline docs)')
+  .action(async (opts) => {
+    const { runDocument } = await import('../lib/document.mjs');
+    await runDocument(opts);
+  });
+
+// --- worktree ---
+const worktreeCmd = program
+  .command('worktree')
+  .description('Manage git worktrees');
+
+worktreeCmd
+  .command('create <name>')
+  .description('Create a new git worktree with the given branch name')
+  .action(async (name) => {
+    const { loadConfig } = await import('../lib/config.mjs');
+    const { worktreeCreate } = await import('../lib/worktree.mjs');
+    const { success, fail } = await import('../lib/output.mjs');
+    try {
+      const config = await loadConfig();
+      const path = await worktreeCreate(name, config);
+      success(`Worktree created at: ${path}`);
+    } catch (err) {
+      fail(err.message);
+      process.exit(1);
+    }
+  });
+
+worktreeCmd
+  .command('list')
+  .description('List all worktrees for the current repository')
+  .action(async () => {
+    const { loadConfig } = await import('../lib/config.mjs');
+    const { worktreeList } = await import('../lib/worktree.mjs');
+    const { fail } = await import('../lib/output.mjs');
+    try {
+      const config = await loadConfig();
+      await worktreeList(config, { display: true });
+    } catch (err) {
+      fail(err.message);
+      process.exit(1);
+    }
+  });
+
+worktreeCmd
+  .command('merge')
+  .description('Merge current worktree branch into default branch and cleanup')
+  .action(async () => {
+    const { worktreeMerge } = await import('../lib/worktree.mjs');
+    const { success, fail } = await import('../lib/output.mjs');
+    try {
+      const result = await worktreeMerge();
+      success(`Merged '${result.branch}' into '${result.defaultBranch}' and cleaned up.`);
+      success(`You are now in: ${result.mainRepoPath}`);
+    } catch (err) {
+      fail(err.message);
+      process.exit(1);
+    }
+  });
+
+worktreeCmd
+  .command('remove <name>')
+  .description('Remove a worktree and delete its branch without merging')
+  .action(async (name) => {
+    const { loadConfig } = await import('../lib/config.mjs');
+    const { worktreeRemove } = await import('../lib/worktree.mjs');
+    const { success, fail } = await import('../lib/output.mjs');
+    try {
+      const config = await loadConfig();
+      const result = await worktreeRemove(name, config);
+      success(`Removed worktree '${result.branch}' at: ${result.path}`);
+    } catch (err) {
+      fail(err.message);
+      process.exit(1);
+    }
+  });
+
+// --- help (default) ---
+program
+  .command('help')
+  .description('Show all commands and usage')
+  .action(() => {
+    program.outputHelp();
+  });
+
+// Catch unhandled errors from async command actions
+function handleFatalError(err) {
+  console.error(`\x1b[31m✗ ${err?.message || 'An unexpected error occurred'}\x1b[0m`);
+  process.exit(1);
+}
+process.on('uncaughtException', handleFatalError);
+process.on('unhandledRejection', handleFatalError);
+
+program.parse();