golem-cc 2.1.1 → 3.0.0

package/.claude/commands/golem/build.md

@@ -0,0 +1,18 @@
+The build loop should be run at the terminal, not inside Claude Code.
+
+Run this command in your terminal:
+
+```
+npx golem build
+```
+
+**Why the terminal?** The build loop ("Ralph loop") spawns a fresh Claude context for each task. Running it here would nest Claude inside Claude, wasting tokens and losing the key benefit: each iteration starts clean with no accumulated confusion. The terminal version also provides rich real-time output (progress bars, spinners, token usage) that doesn't work inside this chat.
+
+**Options:**
+- `npx golem build --iterations 3` — limit to 3 tasks
+- `npx golem build --dry-run` — preview the next task without running it
+- `npx golem build --no-simplify` — skip the simplification pass
+
+If you'd like, I can show you the current plan status — read `.golem/IMPLEMENTATION_PLAN.md` and summarize which stages are complete, what's next, and how many tasks remain.
+
+Want me to show the current plan status?

package/.claude/commands/golem/config.md

@@ -0,0 +1,39 @@
+Show current configuration for this golem project.
+
+## Steps
+
+1. Read `.golem/config.json` (if it doesn't exist, note that defaults are in use)
+2. Detect the project framework by checking for `nuxt.config.*` or `next.config.*`
+3. Check which security tools are installed: `which gitleaks`, `which semgrep`, `which trivy`
+4. Read `.golem/AGENTS.md` for the configured test/build/lint commands
+
+## Output
+
+Present the configuration as a clear summary:
+
+```
+Configuration (.golem/config.json):
+  model:           {value} (default: opus)
+  autoCommit:      {value} (default: true)
+  simplifyOnBuild: {value} (default: true)
+
+Project:
+  Framework: {nuxt | next | none detected}
+  Path:      {cwd}
+
+Security Tools:
+  gitleaks: {installed | not installed}
+  semgrep:  {installed | not installed}
+  trivy:    {installed | not installed}
+
+AGENTS.md Commands:
+  Test:  {command or "not configured"}
+  Build: {command or "not configured"}
+  Lint:  {command or "not configured"}
+```
+
+If `$ARGUMENTS` contains `set`, tell the user to use the terminal command instead: `npx golem config set <key> <value>`. Valid keys: `model`, `autoCommit`, `simplifyOnBuild`.
+
+## Begin
+
+Read the config file and gather project info now.

package/.claude/commands/golem/continue.md

@@ -0,0 +1,73 @@
+Resume work from a previous session by reading the handoff document and project context.
+
+## Steps
+
+1. **Check for handoff document**
+   - Read `.golem/HANDOFF.md`
+   - If it doesn't exist, tell the user: "No handoff document found. Run `/golem:pause` to create one first, or start fresh with `/golem:status`."
+   - Extract the timestamp/date from the handoff to show how fresh it is
+
+2. **Load project context**
+   - Read `.golem/AGENTS.md` for test/build/lint commands
+   - Read `.golem/config.json` for current settings
+   - Read `.golem/IMPLEMENTATION_PLAN.md` if it exists
+
+3. **Read memory files**
+   - Check for `.claude/projects/{project}/memory/MEMORY.md` and other memory files
+   - Incorporate any gotchas or learnings from memory
+
+4. **Present summary**
+   - Show when the handoff was created (date/timestamp from handoff)
+   - Current Focus: What was being worked on
+   - Next Steps: What to do next (from the handoff)
+   - Key Gotchas: Important things to remember
+   - Plan Progress: If there's an implementation plan, show X/Y tasks complete
+
+5. **Handle optional focus argument**
+   - If `$ARGUMENTS` is provided, note it as the narrowed focus
+   - Example: `/golem:continue "finish the pause/continue commands"`
+   - Incorporate the argument into the summary and next steps
+
+6. **Confirm before proceeding**
+   - Ask the user: "Does this match your understanding? Should I proceed with these next steps, or would you like to redirect?"
+   - Wait for user confirmation
+   - DO NOT modify any files or start work until the user confirms
+
+## Output Format
+
+```
+# Resuming Session
+
+Handoff created: {date/time from handoff}
+
+## Current Focus
+{what was being worked on}
+
+## Next Steps
+{prioritized list of what to do next}
+
+## Key Gotchas
+{important caveats from handoff/memory}
+
+## Plan Progress
+{X}/{Y} tasks complete ({percent}%)
+
+{if $ARGUMENTS provided:}
+**Narrowed Focus:** {$ARGUMENTS}
+
+---
+
+Does this match your understanding? Should I proceed with these next steps, or would you like to redirect?
+```
+
+## Rules
+
+- **Read-only until confirmed** — do not modify any files during the continue process
+- Show the handoff timestamp so the user can judge if it's stale
+- Keep the summary concise — hit the key points, don't reproduce the entire handoff
+- If the handoff mentions specific files to read, read them to build deeper context before presenting the summary
+- After user confirms, proceed with the work without additional ceremony
+
+## Begin
+
+Read the handoff document now. If it's missing, stop and tell the user to run `/golem:pause` first.

package/.claude/commands/golem/doctor.md

@@ -0,0 +1,46 @@
+Diagnose setup issues for this golem project. Run all checks inline and report results.
+
+## Checks
+
+Run these checks in order, reporting pass/fail for each.
+
+### Project Checks
+
+1. **`.golem/` directory** — verify it exists with subdirs: `lib/`, `bin/`, `specs/`, `prompts/`, `agents/`
+2. **`AGENTS.md`** — verify `.golem/AGENTS.md` exists and is non-empty
+3. **Slash commands** — verify `.claude/commands/golem/` exists and contains `.md` files
+4. **`.env` in `.gitignore`** — read `.gitignore` and check that `.env` is listed
+5. **Specs** — check if `.golem/specs/` has any `.md` files
+6. **Implementation plan** — check if `.golem/IMPLEMENTATION_PLAN.md` exists
+
+### User Checks
+
+7. **Claude CLI** — run `claude --version` and report the version
+8. **Node.js >= 18** — run `node --version` and verify major version >= 18
+9. **Git configured** — run `git config user.name` and `git config user.email`
+10. **Old installations** — check if `~/.golem/` exists (it shouldn't)
+
+### Security Tools
+
+11. **gitleaks** — `which gitleaks`
+12. **semgrep** — `which semgrep`
+13. **trivy** — `which trivy`
+
+For missing security tools, show install commands: `brew install gitleaks`, `brew install semgrep`, `brew install trivy`.
+
+### Test Validation
+
+14. Read the test command from `.golem/AGENTS.md` (first bash code block) and run it to verify it works.
+
+## Output
+
+For each check, show a clear pass/fail indicator. At the end, show a summary: `{passed}/{total} checks passed`.
+
+If `$ARGUMENTS` contains `--fix`, also attempt to fix issues:
+- Create missing `.golem/` subdirectories
+- Add `.env` to `.gitignore` if missing
+- Note what was fixed
+
+## Begin
+
+Start running the checks now.

package/.claude/commands/golem/document.md

@@ -0,0 +1,138 @@
+You are running a full documentation pass for this project. Your goal is to detect the project type, add inline code documentation, generate markdown docs, update the changelog, and update the README.
+
+## Rules
+
+- Do NOT change any code behavior — documentation only
+- Do NOT touch test files, generated files, lock files, or node_modules
+- Do NOT delete existing markdown documentation — archive deprecated content to `{docsPath}/deprecated/` with a deprecation date
+- Do NOT add type annotations to JavaScript files
+- Preserve existing accurate documentation — only update what has drifted from the code
+- Documentation should be educational and clear, not boilerplate that restates function signatures
+
+## Options
+
+Parse `$ARGUMENTS` for these flags:
+
+- `--path <dir>` — scope documentation to a subdirectory instead of the whole project
+- `--inline-only` — only run inline code documentation (Phase 2), skip markdown generation
+- `--markdown-only` — only run markdown generation (Phase 3+), skip inline docs
+- `--docs-path <dir>` — override the output directory for markdown docs (default: `docs/` or `docsPath` from `.golem/config.json`)
+- `--dry-run` — report what would be documented without making any changes
+
+If no flags are provided, run the full documentation pass (all phases).
+
+## Phase 1: Detect Project Type
+
+Read `package.json`, `tsconfig.json`, `pyproject.toml`, and other manifest files to determine:
+
+- **Language**: javascript, typescript, python
+- **Framework**: vue, nuxt, react, next, none
+- **Module system**: esm, commonjs, n/a
+- **Database tooling**: prisma, drizzle, knex, sqlalchemy, alembic, raw-sql, none
+- **Inline doc standard**: jsdoc, tsdoc, google-docstring, sql-comments
+
+Report the detection results before proceeding.
+
+## Phase 2: Inline Documentation (skip if `--markdown-only`)
+
+Find all source files in the project (or scoped path). For each file:
+
+1. Read the file completely
+2. Add a file header comment explaining its purpose and role in the system
+3. Add documentation to non-obvious functions, methods, classes, and types
+4. Use the correct standard for the detected project type:
+   - JavaScript/ESM: JSDoc (`/** ... */`)
+   - TypeScript: TSDoc (`/** ... */`) with `@param`, `@returns`, `@example`
+   - Vue/Nuxt SFCs: JSDoc in `<script>`, `<!-- -->` comments for non-obvious template/style sections
+   - React/Next: JSDoc/TSDoc
+   - Python: Google-style docstrings
+   - SQL: `--` comment blocks on tables, columns, procedures
+5. Skip trivially obvious functions (simple getters, self-documenting one-liners)
+6. Document complex conditionals and non-obvious "why" decisions inline
+
+After documenting files, run the test command from `.golem/AGENTS.md` to verify no behavior was changed. If tests fail, revert the changes that broke them.
+
+## Phase 3: Markdown Documentation (skip if `--inline-only`)
+
+Generate or update project documentation in the docs directory (`docs/` by default, or the path from `--docs-path` / `docsPath` config).
+
+### Directory Structure
+
+```
+{docsPath}/
+  index.md              — project overview
+  architecture.md       — system design, component connections
+  getting-started.md    — setup, install, prerequisites
+  configuration.md      — all config options explained
+  modules/
+    {module-name}.md    — one per major module/component
+  api/
+    {resource}.md       — API reference (if project has endpoints)
+  database/
+    schema.md           — schema overview with relationships
+  guides/
+    setup.md            — dev environment setup
+    {workflow}.md       — project-specific how-tos
+  deprecated/
+    {old-thing}.md      — archived docs with deprecation date
+```
+
+### Frontmatter
+
+Every markdown file must include YAML frontmatter:
+
+```yaml
+---
+title: "Page Title"
+description: "Brief description"
+navigation:
+  order: 1
+---
+```
+
+### Content Rules
+
+- Only create docs for things that actually exist — no empty placeholders
+- Explain behavior and usage — do not dump source code into docs
+- Use standard CommonMark markdown, no platform-specific extensions
+- Cross-link related docs where appropriate
+
+## Phase 4: Changelog
+
+Generate or update `CHANGELOG.md` at the project root from git history:
+
+- Group by date with sections: **New Features**, **Improvements**, **Bug Fixes**
+- Write in plain language for non-technical audiences (managers, stakeholders)
+- No jargon — translate developer actions into user-facing impact
+- Only include sections that have entries
+
+## Phase 5: README
+
+Generate or update `README.md` at the project root:
+
+- Include project name and description
+- Link into the docs directory for detailed documentation
+- Preserve any existing user-written content outside of golem-generated markers
+
+## Phase 6: Archive Deprecated
+
+Check if any documented modules have been removed from the codebase. If so, move their docs to `{docsPath}/deprecated/` with:
+
+- A `deprecated_date` field in frontmatter
+- A `replaced_by` field (empty if no direct replacement)
+
+## Phase 7: Summary
+
+Present a summary of what was done:
+
+- Number of source files documented inline
+- Number of markdown files created or updated
+- Number of commits included in changelog
+- README action (created or updated)
+- Number of deprecated docs archived
+
+If `--dry-run` was specified, report what would have been done without making changes.
+
+## Begin
+
+Start by reading `.golem/config.json` for `docsPath` and model settings, then detect the project type (Phase 1). Announce that you're beginning the documentation pass.

package/.claude/commands/golem/help.md

@@ -0,0 +1,58 @@
+Show all golem commands and how to use them.
+
+Present the following help text to the user:
+
+---
+
+## Golem Commands
+
+### Slash Commands (Claude Code)
+
+| Command | Description |
+|---------|-------------|
+| `/golem:spec` | Build project specs through guided conversation |
+| `/golem:plan` | Create implementation plan from specs |
+| `/golem:build` | Run autonomous build loop (redirects to terminal) |
+| `/golem:review` | Run parallel code review before PR |
+| `/golem:security` | Run automated security scans |
+| `/golem:simplify` | Simplify recent or staged code changes |
+| `/golem:status` | Show plan progress and recent commits |
+| `/golem:doctor` | Diagnose setup issues |
+| `/golem:config` | Show current configuration |
+| `/golem:help` | Show this help text |
+
+### Terminal Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx golem build` | Run the build loop (recommended over slash command) |
+| `npx golem build --iterations 3` | Limit to 3 tasks |
+| `npx golem build --dry-run` | Preview next task without running |
+| `npx golem security` | Run default security scan |
+| `npx golem security --full` | Run full security scan with git history |
+| `npx golem doctor` | Run health checks |
+| `npx golem doctor --fix` | Run health checks and auto-fix issues |
+| `npx golem config show` | Show current config |
+| `npx golem config set <key> <value>` | Set a config value |
+| `npx golem simplify [path]` | Simplify code |
+
+### Typical Workflow
+
+1. `/golem:spec` — define what you're building
+2. `/golem:plan` — create a staged implementation plan
+3. `npx golem build` — execute the plan (in terminal)
+4. `/golem:review` — review the code before shipping
+5. `/golem:security` — final security check
+
+### Key Files
+
+- `.golem/specs/` — project specifications
+- `.golem/IMPLEMENTATION_PLAN.md` — staged task plan
+- `.golem/AGENTS.md` — test, build, lint commands
+- `.golem/config.json` — project configuration
+- `.golem/SECURITY_REPORT.md` — last security scan
+- `.golem/REVIEW_REPORT.md` — last code review
+
+---
+
+That's all the golem commands. Ask if you need details on any specific command.

package/.claude/commands/golem/pause.md

@@ -0,0 +1,130 @@
+You are generating a session handoff document. Your goal is to capture the full project state so a fresh Claude session can resume seamlessly using `/golem:continue`.
+
+The handoff has two layers:
+1. **Factual sections** — gathered by reading files and running commands (deterministic, not from memory)
+2. **Conversational sections** — written by you based on what happened in this session
+
+## Phase 1: Gather Project Facts
+
+Perform these steps to collect project state. If any file is missing, skip that section and note it was unavailable.
+
+### 1. Project Summary
+
+Read `package.json` and extract the `name`, `version`, and `description` fields. Format as a one-liner.
+
+### 2. Git State
+
+Run these commands:
+```bash
+git branch --show-current
+git status --short
+git log --oneline -15
+```
+
+Record the current branch, whether the working tree is clean or dirty (list changed files if dirty), and the last 15 commit subjects.
+
+### 3. Implementation Plan Progress
+
+Read `.golem/IMPLEMENTATION_PLAN.md`. Count:
+- Total tasks (lines matching `- [x]` or `- [ ]`)
+- Completed (`[x]`)
+- In-progress or pending (`[ ]`)
+
+List any in-progress items. If the file doesn't exist, note: "No implementation plan found."
+
+### 4. Spec Status
+
+List all files in `.golem/specs/` using a glob for `*.md`. For each spec file, note whether it appears to be implemented (check if its features exist in the codebase or if it's referenced in completed plan stages) or not yet implemented. If no specs exist, note: "No specs found."
+
+### 5. Config Snapshot
+
+Read `.golem/config.json` and summarize the key settings: model, autoCommit, simplifyOnBuild, maxRetries, enabled gates, and any worktree configuration.
+
+### 6. Key Files
+
+Read `package.json` for the entry points. List important project files from `.golem/lib/` and `.golem/bin/` with a one-line description of each file's purpose (read the first few lines of each if needed).
+
+### 7. Verified Commands
+
+List commands that are known to work based on `package.json` scripts, `.golem/AGENTS.md`, and the CLI help output. Include the full command syntax.
+
+### 8. Gotchas
+
+Read the existing `.golem/HANDOFF.md` (if it exists) for any "Don't Forget" or gotchas section. Also check `.claude/projects/` memory files for recorded gotchas. Preserve any known pitfalls.
+
+## Phase 2: Add Conversational Context
+
+Based on what happened in this conversation session, write these sections:
+
+### Current Focus
+What was actively being worked on in this session? What problem were we solving? Be specific — name files, features, bugs, or tasks.
+
+### What's Next
+What are the concrete next steps to pick up from? List them in priority order. Be actionable — "run X", "implement Y", "fix Z".
+
+### Decisions Made
+Any decisions from this conversation that aren't captured elsewhere. Include rationale so a fresh session understands the "why".
+
+## Phase 3: Assemble and Write HANDOFF.md
+
+Combine all sections into a single markdown document with this structure:
+
+```markdown
+# {project name} Handoff Document
+
+## Project Summary
+{one-liner from package.json}
+
+## Git State
+- **Branch:** {branch}
+- **Working tree:** {clean or list of files}
+- **Recent commits:**
+{last 15 commits}
+
+## Plan Progress
+{completed}/{total} tasks ({percent}%) — {in-progress count} in progress
+{list in-progress items if any}
+
+## Spec Status
+| Spec | Status |
+|------|--------|
+{each spec with status}
+
+## Config Snapshot
+{key settings formatted as a list}
+
+## Key Files
+| File | Purpose |
+|------|---------|
+{important files with descriptions}
+
+## Verified Commands
+```bash
+{commands that work}
+```
+
+## Gotchas
+{known pitfalls and caveats}
+
+## Current Focus
+{what was being worked on — from conversation}
+
+## What's Next
+{concrete next steps — from conversation}
+
+## Decisions Made
+{decisions and rationale — from conversation}
+```
+
+Write the assembled document to `.golem/HANDOFF.md`, overwriting any existing content.
+
+## Phase 4: Confirm
+
+After writing the file, tell the user:
+- The handoff was written to `.golem/HANDOFF.md`
+- How many sections were populated vs skipped
+- They can now `/clear` or start a new session, and use `/golem:continue` to resume
+
+## Begin
+
+Start by gathering project facts (Phase 1). Read all the files and run the commands now.

package/.claude/commands/golem/plan.md

@@ -0,0 +1,111 @@
+You are a planning agent for a software project. Your job is to analyze specs, investigate the codebase, and generate a staged implementation plan. You do NOT write code — you only plan.
+
+## Rules
+
+- Do NOT modify any source code, config files, or test files
+- Do NOT create new source files
+- The ONLY file you write is `.golem/IMPLEMENTATION_PLAN.md`
+- Ask the user to confirm the plan before writing it
+- Every task must be atomic and independently testable
+- Every stage must produce a working, committable state
+
+## Process
+
+### Phase 1: Read Specs
+
+Read ALL spec files in `.golem/specs/`. Summarize what you find — list each spec and its core requirements. If no specs exist, tell the user to run `/golem:spec` first and stop.
+
+### Phase 2: Investigate Codebase
+
+Search the codebase extensively:
+
+1. Read `package.json` for dependencies, scripts, and project structure
+2. Read `.golem/AGENTS.md` for test, build, and lint commands
+3. Scan source directories for existing implementations
+4. Check for existing tests, configs, and infrastructure
+5. Read any existing `.golem/IMPLEMENTATION_PLAN.md` to understand prior progress
+
+Build a mental map of what exists and how it's structured.
+
+### Phase 3: Gap Analysis
+
+For each spec requirement, classify it:
+
+- **Done** — fully implemented and tested
+- **Partial** — started but incomplete (note what's missing)
+- **Missing** — not implemented at all
+- **Blocked** — can't be implemented yet (note the blocker)
+
+Present the gap analysis to the user as a table. Ask if anything looks wrong before proceeding.
+
+### Phase 4: Generate Plan
+
+Create staged tasks from the gaps:
+
+1. **Group by dependency** — things that must come first go in earlier stages
+2. **Group by coherence** — related tasks belong in the same stage
+3. **Order within stages** — foundational pieces first, then features, then polish
+4. **Keep stages small** — 3-6 tasks per stage is ideal
+5. **Each stage gets a conventional commit message** — `feat(scope): description`, `fix(scope): description`, etc.
+
+For each task, specify:
+- **Title** — what gets built
+- **Files** — which files will be created or modified
+- **Model** — `opus` for complex architecture, refactoring, multi-file features, or tricky logic. `sonnet` for straightforward tasks like adding tests, renaming, simple CRUD, config changes, documentation, or single-file modifications with clear specs. Default to `sonnet` — only use `opus` when reasoning depth matters.
+- **Notes** — implementation hints (what to do, not how to code it)
+- **Tests** — how to verify it works
+- **Depends on** — other tasks that must complete first (only if within the same stage)
+
+Preserve completed tasks from any existing plan — mark them `[x]` and keep their content.
+
+### Phase 5: Write Plan
+
+Present the full plan to the user. After they confirm, write it to `.golem/IMPLEMENTATION_PLAN.md` using this format:
+
+```markdown
+# Implementation Plan
+
+Generated: {date}
+Based on: .golem/specs/*.md
+
+## Status
+- Stages: {N}
+- Completed: {count}
+
+---
+
+## Stage 1: {Name}
+Commit: {type}({scope}): {description}
+
+### [ ] 1.1. {Task title}
+Files: {expected files}
+Model: {opus or sonnet}
+Notes: {implementation hints}
+Tests: {verification criteria}
+
+### [ ] 1.2. {Task title}
+Files: {files}
+Model: {opus or sonnet}
+Notes: {notes}
+Depends on: 1.1
+Tests: {tests}
+
+---
+
+## Stage 2: {Name}
+Commit: {type}({scope}): {description}
+
+...
+
+---
+
+## Risks & Mitigations
+
+- **{Risk}** — {description}. Mitigation: {strategy}.
+```
+
+End with a summary: how many stages, how many tasks, estimated scope.
+
+## Starting
+
+Begin by reading all files in `.golem/specs/`. Then investigate the codebase. Do not ask the user any questions until you've completed your analysis and are ready to present the gap analysis.