golem-cc 2.1.2 → 3.0.0

package/.golem/prompts/simplify.md

@@ -0,0 +1,35 @@
+You are a code simplifier. Your job is to reduce complexity without changing behavior.
+
+## Rules
+
+- NEVER change behavior — input/output must remain identical
+- NEVER touch test files, type definitions, config files, generated files, or lock files
+- NEVER add, remove, or modify any comments — leave all comments exactly as they are
+- NEVER add docstrings, type annotations, or new dependencies
+- ONE change at a time — validate between each
+- Run tests after EVERY file modification
+- Revert immediately if tests fail
+
+## Priority Order
+
+1. **Reduce complexity** — flatten nesting, use early returns, extract boolean expressions
+2. **Improve clarity** — rename unclear variables, remove dead code, simplify abstractions
+3. **Structural** — extract functions >50 lines, inline trivial one-use functions
+4. **Remove dead code** — defensive checks that can't trigger, unreachable branches
+
+## Target Files
+
+Simplify ONLY these files, one at a time. Do NOT read, edit, or modify any other files in the project:
+
+{{FILES}}
+
+## Process
+
+For each file:
+1. Read the file
+2. Identify simplifications using the priority order above
+3. Make ONE change
+4. Run tests
+5. If tests fail, revert and move on
+6. If tests pass, repeat from step 2 until no more simplifications remain
+7. Move to the next file

package/README.md

@@ -1,210 +1,209 @@
-# Golem
+# golem-cc
 
-Personal agentic workflow manager. Integrates Freshservice tickets, Gitea issues, and Claude Code for a unified development workflow.
+Project-scoped autonomous coding agent framework for Claude Code CLI.
+
+Golem provides structured workflows for speccing, planning, building, reviewing, and hardening software projects — with a rich terminal UI for the build loop and deep Claude Code integration via slash commands.
 
 ## Installation
 
 ```bash
-# Bootstrap (one command)
+# Install into an existing project
 pnpm dlx golem-cc
+
+# Or with npx
+npx golem-cc
 ```
 
-This copies everything to `~/.golem/`, links binaries to `~/.local/bin/`, and wires up Claude slash-commands.
+This copies `.golem/` and `.claude/commands/golem/` into your project, detects your framework (Nuxt/Next), and generates `AGENTS.md` with your test/build/lint commands.
 
-After installing, restart your shell and configure:
+After installing, configure for your project:
 
 ```bash
-# Verify setup
-golem doctor
-
-# Edit credentials
-vim ~/.golem/.env
-
-# Initialize a project
-cd your-project && golem init
+npx golem init
 ```
 
-### Updating
+## Prerequisites
 
-```bash
-# From a running install
-golem install
-
-# Or from a local checkout (dev workflow)
-golem install --from /path/to/golem-cc
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         GOLEM WORKFLOW                               │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                      │
-│   Freshservice          Local State           Gitea                 │
-│   ┌─────────┐        ┌───────────┐        ┌─────────┐              │
-│   │ INC-123 │◄──────►│.golem/    │◄──────►│ Issue   │              │
-│   │ Ticket  │        │tickets/   │        │ #47     │              │
-│   └─────────┘        │INC-123.yml│        └─────────┘              │
-│                      └───────────┘                                  │
-│                            │                                        │
-│                            ▼                                        │
-│                      ┌───────────┐                                  │
-│                      │ Worktree  │                                  │
-│                      │ fix/INC-  │                                  │
-│                      │ 123-slug  │                                  │
-│                      └───────────┘                                  │
-│                            │                                        │
-│            ┌───────────────┼───────────────┐                       │
-│            ▼               ▼               ▼                        │
-│      ┌──────────┐   ┌──────────┐   ┌──────────┐                    │
-│      │/golem:   │   │/golem:   │   │/golem:   │                    │
-│      │spec      │──►│plan      │──►│build     │                    │
-│      └──────────┘   └──────────┘   └──────────┘                    │
-│            │               │               │                        │
-│            ▼               ▼               ▼                        │
-│      ┌──────────┐   ┌──────────┐   ┌──────────┐                    │
-│      │.golem/   │   │IMPLEMENT-│   │ wip:     │                    │
-│      │specs/    │   │ATION_    │   │ commits  │──► squash          │
-│      │*.md      │   │PLAN.md   │   └──────────┘   per stage        │
-│      └──────────┘   └──────────┘                                   │
-│                                                                      │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## Quick Start
-
-### 1. Initialize a project
+- **Node.js >= 18**
+- **Claude Code CLI** — [install instructions](https://docs.anthropic.com/en/docs/claude-code)
+- **pnpm** (recommended) or npm
+- **git** configured with user.name and user.email
 
-```bash
-cd your-project
-golem init
-```
+Optional (for security scanning):
+- `gitleaks` — `brew install gitleaks`
+- `semgrep` — `brew install semgrep`
+- `trivy` — `brew install trivy`
 
-### 2. Get a ticket
+## Workflow
 
-```bash
-# Import existing Freshservice ticket
-golem import INC-1234
+The typical golem workflow:
 
-# Or create new ticket
-golem new "Fix API timeout issue"
 ```
-
-### 3. Create worktree
-
-```bash
-golem worktree INC-1234
-cd .golem/worktrees/fix/INC-1234-api-timeout
+1. /golem:spec     →  Build specs through guided conversation
+2. /golem:plan     →  Generate staged implementation plan
+3. npx golem build →  Autonomous build loop with TUI
+4. /golem:review   →  Parallel code review (6 agents)
+5. /golem:security →  Security scan before shipping
 ```
 
-### 4. Define specs (in Claude Code)
+### 1. Write Specs
+
+Inside Claude Code CLI:
 
 ```
 /golem:spec
 ```
 
-Interactive conversation to define requirements, tests, and constraints.
+This runs a guided conversation with three perspectives (UX Advocate, Architect, Devil's Advocate) to produce spec files in `.golem/specs/`.
 
-### 5. Create plan (in Claude Code)
+### 2. Generate Plan
 
 ```
 /golem:plan
 ```
 
-Generates `.golem/IMPLEMENTATION_PLAN.md` with staged tasks.
+Reads all specs, analyzes the codebase, and generates `.golem/IMPLEMENTATION_PLAN.md` with staged tasks.
 
-### 6. Build (CLI loop or Claude Code)
+### 3. Build
 
 ```bash
-# CLI - loops until done
-golem build
+# Full autonomous build loop with TUI
+npx golem build
 
-# Or in Claude Code - one task at a time
-/golem:build
+# Limit to N iterations
+npx golem build --iterations 3
+
+# Preview next task without executing
+npx golem build --dry-run
+
+# Skip simplification pass
+npx golem build --no-simplify
 ```
 
-Each task gets a WIP commit. Each stage gets squashed.
+The build loop reads the implementation plan, finds the next incomplete task, spawns Claude with a focused prompt, streams output through a full-screen TUI with progress bar and usage sparklines, then commits on success.
 
-### 7. Create PR
+### 4. Review
+
+```
+/golem:review
+```
+
+Spawns 6 parallel review agents (security, logic, style, tests, architecture, devil's advocate) and produces `.golem/REVIEW_REPORT.md`.
+
+### 5. Security Scan
 
 ```bash
-golem pr
+# Default scan (gitleaks + semgrep + pnpm audit + env checks)
+npx golem security
+
+# Full scan (adds git history, trivy, outdated deps, file perms, headers)
+npx golem security --full
+
+# Auto-install missing security tools
+npx golem security --fix
+
+# Install pre-commit hook for gitleaks
+npx golem security --pre-commit
 ```
 
 ## Commands
 
-### Terminal
+### Terminal (npx golem)
 
 | Command | Description |
 |---------|-------------|
-| `golem new <subject>` | Create new ticket |
-| `golem import <INC-XXX>` | Import Freshservice ticket |
-| `golem list` | List tracked tickets |
-| `golem status [ticket]` | Show ticket or project status |
-| `golem worktree [ticket]` | Create/show worktree |
-| `golem worktrees` | List all worktrees |
-| `golem build` | Run autonomous build loop |
-| `golem plan` | Generate implementation plan |
-| `golem simplify [files]` | Run code simplifier |
-| `golem squash` | Squash stage commits |
-| `golem pr` | Create pull request |
-| `golem sync` | Sync status to Freshservice/Gitea |
-| `golem config` | Show current configuration |
-| `golem doctor` | Diagnose setup issues |
-| `golem init` | Initialize golem in current project |
-| `golem help` | Show help |
-
-### Claude Code
+| `build` | Run autonomous build loop with TUI |
+| `security` | Run security scans |
+| `simplify [path]` | Run code simplifier (defaults to last commit) |
+| `doctor` | Diagnose setup issues |
+| `config show` | Display current configuration |
+| `config set <key> <value>` | Set a config value |
+| `init` | Initialize golem for this project |
+| `status` | Show plan progress |
+| `help` | Show all commands |
+
+### Claude Code Slash Commands
 
 | Command | Description |
 |---------|-------------|
-| `/golem:spec` | Define specs interactively |
-| `/golem:plan` | Generate implementation plan |
-| `/golem:build` | Run one build iteration |
+| `/golem:spec` | Build specs through guided conversation |
+| `/golem:plan` | Generate implementation plan from specs |
+| `/golem:build` | Shows build instructions (redirects to terminal) |
+| `/golem:review` | Run parallel code review |
+| `/golem:security` | Run security scan |
 | `/golem:simplify` | Run code simplifier |
-| `/golem:status` | Show current status |
-| `/golem:config` | Show configuration |
+| `/golem:status` | Show project status |
 | `/golem:doctor` | Diagnose setup issues |
-| `/golem:help` | Show help |
+| `/golem:config` | Show configuration |
+| `/golem:help` | Show all commands |
 
 ## Configuration
 
-### Environment Variables
+Configuration lives in `.golem/config.json`:
 
-```bash
-# ~/.golem/.env
+```json
+{
+  "model": "opus",
+  "autoCommit": true,
+  "simplifyOnBuild": true
+}
+```
 
-# Freshservice
-FRESH_DOMAIN=yourcompany.freshservice.com
-FRESH_API_KEY=your_api_key
-FRESH_DEFAULT_GROUP_ID=12345          # Optional
-FRESH_DEFAULT_CATEGORY=Applications   # Optional
-FRESH_SOURCE_ID=1002                  # Optional
-FRESH_DEFAULT_EMAIL=bot@example.com   # Optional
+| Key | Default | Description |
+|-----|---------|-------------|
+| `model` | `opus` | Claude model for build loop |
+| `autoCommit` | `true` | Auto-commit after each task |
+| `simplifyOnBuild` | `true` | Run simplifier after building |
 
-# Gitea
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=your_token
-GITEA_ORG=your-org
-GITEA_REPO=default-repo               # Can be overridden per-project
+```bash
+npx golem config set model sonnet
+npx golem config set autoCommit false
 ```
 
-### Project Structure
+## Project Structure
 
 ```
 .golem/
-├── tickets/           # Local ticket state (YAML)
-│   └── INC-1234.yaml
-├── specs/             # Requirement specs
-│   ├── feature.md
-│   └── validation.md
-├── worktrees/         # Git worktrees per ticket
-│   └── fix/INC-1234-api-timeout/
-├── AGENTS.md          # Operational commands (test/build/lint)
-└── IMPLEMENTATION_PLAN.md  # Current task list
+├── bin/golem.mjs          # CLI entry point
+├── lib/                   # Core modules
+│   ├── build.mjs          # Build loop orchestrator
+│   ├── claude.mjs         # Claude CLI wrapper
+│   ├── config.mjs         # Configuration
+│   ├── display.mjs        # Stream display
+│   ├── doctor.mjs         # Health checks
+│   ├── init.mjs           # Project initialization
+│   ├── output.mjs         # chalk/ora output helpers
+│   ├── security.mjs       # Security scanning
+│   ├── simplify.mjs       # Code simplifier
+│   ├── tui.mjs            # Full-screen terminal UI
+│   └── usage.mjs          # Token usage reader
+├── prompts/               # Build/simplify prompts
+├── agents/                # Agent definitions
+├── specs/                 # Project specs (created by /golem:spec)
+├── config.json            # Project configuration
+├── AGENTS.md              # Operational commands
+└── IMPLEMENTATION_PLAN.md # Task plan (created by /golem:plan)
+
+.claude/commands/golem/    # Slash commands for Claude Code CLI
+```
+
+## Troubleshooting
+
+Run the doctor to check your setup:
+
+```bash
+npx golem doctor
+
+# Auto-fix common issues
+npx golem doctor --fix
 ```
 
+Common issues:
+- **Claude CLI not found** — Install from https://docs.anthropic.com/en/docs/claude-code
+- **No implementation plan** — Run `/golem:plan` in Claude Code first
+- **Empty specs directory** — Run `/golem:spec` in Claude Code first
+- **Security tools missing** — Run `npx golem security --fix` to auto-install
+
 ## License
 
-MIT
+ISC

package/bin/golem-shim.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// Walk up from cwd to find .golem/bin/golem.mjs
+function findGolemProject(startDir) {
+  let currentDir = startDir;
+  while (true) {
+    const golemPath = join(currentDir, '.golem', 'bin', 'golem.mjs');
+    if (existsSync(golemPath)) {
+      return { projectRoot: currentDir, golemPath };
+    }
+    if (currentDir === '/') return null;
+    currentDir = dirname(currentDir);
+  }
+}
+
+const result = findGolemProject(process.cwd());
+
+if (!result) {
+  console.error('No golem project found. Run `pnpm dlx golem-cc` to set one up.');
+  process.exit(1);
+}
+
+const { projectRoot, golemPath } = result;
+
+if (process.env.GOLEM_DEBUG === '1') {
+  console.log(`[golem-shim] Resolved project root: ${projectRoot}`);
+}
+
+try {
+  execFileSync('node', [golemPath, ...process.argv.slice(2)], { stdio: 'inherit' });
+} catch (error) {
+  process.exit(error.status ?? 1);
+}

package/bin/install.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import { existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = join(fileURLToPath(import.meta.url), '..', '..');
+const cwd = process.cwd();
+
+// Don't install into ourselves
+if (cwd === pkgRoot) {
+  console.error('Cannot install golem into its own package directory.');
+  process.exit(1);
+}
+
+console.log('◆ Installing golem-cc...\n');
+
+// --- Copy .golem/ directory ---
+const golemSrc = join(pkgRoot, '.golem');
+const golemDest = join(cwd, '.golem');
+
+if (existsSync(golemDest)) {
+  console.log('  ⚠ .golem/ already exists — skipping copy (run golem init to reconfigure)');
+} else {
+  cpSync(golemSrc, golemDest, { recursive: true });
+  // Remove source-specific files that shouldn't be in a fresh install
+  for (const f of ['config.json', 'SECURITY_REPORT.md', 'REVIEW_REPORT.md', 'golem.log', 'AGENTS.md', 'IMPLEMENTATION_PLAN.md', 'HANDOFF.md']) {
+    const p = join(golemDest, f);
+    if (existsSync(p)) unlinkSync(p);
+  }
+  // Remove specs (project-specific)
+  const specsDir = join(golemDest, 'specs');
+  if (existsSync(specsDir)) rmSync(specsDir, { recursive: true, force: true });
+  mkdirSync(join(golemDest, 'specs'), { recursive: true });
+  console.log('  ✓ Copied .golem/ directory');
+}
+
+// --- Copy .claude/commands/golem/ ---
+const cmdsSrc = join(pkgRoot, '.claude', 'commands', 'golem');
+const cmdsDest = join(cwd, '.claude', 'commands', 'golem');
+
+if (existsSync(cmdsDest)) {
+  console.log('  ⚠ .claude/commands/golem/ already exists — skipping');
+} else {
+  mkdirSync(cmdsDest, { recursive: true });
+  cpSync(cmdsSrc, cmdsDest, { recursive: true });
+  console.log('  ✓ Copied .claude/commands/golem/ slash commands');
+}
+
+// --- Detect framework ---
+const framework = detectFramework(cwd);
+if (framework) {
+  console.log(`  ✓ Detected framework: ${framework}`);
+} else {
+  console.log('  ℹ No framework detected (plain Node.js project)');
+}
+
+// --- Generate AGENTS.md ---
+const agentsPath = join(cwd, '.golem', 'AGENTS.md');
+if (existsSync(agentsPath)) {
+  console.log('  ⚠ AGENTS.md already exists — skipping');
+} else {
+  writeFileSync(agentsPath, generateAgentsMd(cwd, framework));
+  console.log('  ✓ Generated AGENTS.md');
+}
+
+// --- Ensure .gitignore has golem entries ---
+ensureGitignore(cwd);
+
+// --- Add golem-cc as devDependency ---
+addDevDependency(cwd);
+
+console.log('\n◆ Done! Next steps:');
+console.log('  1. Run /golem:spec in Claude Code to build your specs');
+console.log('  2. Run /golem:plan to generate an implementation plan');
+console.log('  3. Run npx golem build to start building\n');
+
+
+// --- Helpers ---
+
+function readPkg(dir) {
+  try { return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8')); }
+  catch { return null; }
+}
+
+function detectFramework(dir) {
+  const checks = [
+    { file: 'nuxt.config.ts', framework: 'nuxt' },
+    { file: 'nuxt.config.js', framework: 'nuxt' },
+    { file: 'next.config.ts', framework: 'next' },
+    { file: 'next.config.js', framework: 'next' },
+    { file: 'next.config.mjs', framework: 'next' },
+  ];
+  for (const { file, framework } of checks) {
+    if (existsSync(join(dir, file))) return framework;
+  }
+  return null;
+}
+
+function detectTestCommand(dir) {
+  const pkg = readPkg(dir);
+  const testScript = pkg?.scripts?.test;
+  if (testScript && testScript !== 'echo "Error: no test specified" && exit 1') return testScript;
+  if (existsSync(join(dir, 'vitest.config.ts')) || existsSync(join(dir, 'vitest.config.js'))) return 'npx vitest run';
+  if (existsSync(join(dir, 'jest.config.ts')) || existsSync(join(dir, 'jest.config.js'))) return 'npx jest';
+  return 'node --test';
+}
+
+function detectBuildCommand(dir, framework) {
+  if (framework === 'nuxt') return 'npx nuxt build';
+  if (framework === 'next') return 'npx next build';
+  if (readPkg(dir)?.scripts?.build) return 'npm run build';
+  return '# No build step — ESM modules run directly';
+}
+
+function detectLintCommand(dir) {
+  if (readPkg(dir)?.scripts?.lint) return 'npm run lint';
+  for (const f of ['eslint.config.js', 'eslint.config.mjs', '.eslintrc.json', '.eslintrc.js']) {
+    if (existsSync(join(dir, f))) return 'npx eslint .';
+  }
+  return '# TBD — will be set up during implementation';
+}
+
+function generateAgentsMd(dir, framework) {
+  const testCmd = detectTestCommand(dir);
+  const buildCmd = detectBuildCommand(dir, framework);
+  const lintCmd = detectLintCommand(dir);
+  const typeCheck = existsSync(join(dir, 'tsconfig.json')) ? 'npx tsc --noEmit' : '# N/A — plain JavaScript (ESM), no TypeScript';
+
+  return `# Operational Commands
+
+## Testing
+
+\`\`\`bash
+${testCmd}
+\`\`\`
+
+## Type Checking
+
+\`\`\`bash
+${typeCheck}
+\`\`\`
+
+## Linting
+
+\`\`\`bash
+${lintCmd}
+\`\`\`
+
+## Build
+
+\`\`\`bash
+${buildCmd}
+\`\`\`
+
+## Learnings
+
+- ${framework ? `Project uses ${framework} framework` : 'Project uses ESM (type: module in package.json)'}
+- CLI entry point is .golem/bin/golem.mjs
+`;
+}
+
+function ensureGitignore(dir) {
+  const giPath = join(dir, '.gitignore');
+  const entries = ['.env', '.claude/*', '!.claude/commands/', '!.claude/commands/**'];
+  let content = '';
+
+  if (existsSync(giPath)) {
+    content = readFileSync(giPath, 'utf-8');
+  }
+
+  const lines = content.split('\n');
+  const missing = entries.filter(e => !lines.some(l => l.trim() === e));
+
+  if (missing.length > 0) {
+    const addition = '\n# Golem\n' + missing.join('\n') + '\n';
+    writeFileSync(giPath, content.trimEnd() + addition);
+    console.log('  ✓ Updated .gitignore');
+  }
+}
+
+function addDevDependency(dir) {
+  const pkg = readPkg(dir);
+  if (!pkg) { console.log('  ⚠ No package.json found — skipping devDependency'); return; }
+  if (pkg.devDependencies?.['golem-cc'] || pkg.dependencies?.['golem-cc']) {
+    console.log('  ⚠ golem-cc already in dependencies — skipping');
+    return;
+  }
+  pkg.devDependencies = pkg.devDependencies || {};
+  pkg.devDependencies['golem-cc'] = 'latest';
+  writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+  console.log('  ✓ Added golem-cc as devDependency');
+}