golem-cc 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+```
+   ██████╗  ██████╗ ██╗     ███████╗███╗   ███╗
+  ██╔════╝ ██╔═══██╗██║     ██╔════╝████╗ ████║
+  ██║  ███╗██║   ██║██║     █████╗  ██╔████╔██║
+  ██║   ██║██║   ██║██║     ██╔══╝  ██║╚██╔╝██║
+  ╚██████╔╝╚██████╔╝███████╗███████╗██║ ╚═╝ ██║
+   ╚═════╝  ╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝
+```
+
+> Let it build. Let it test. Let it simplify. Let it loop.
+
+Golem is an autonomous coding loop that implements features while you watch (or grab coffee). Define your specs, kick off the loop, and let it work through your task list—implementing, testing, simplifying, and committing along the way.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ITERATION 3  │  9 tasks remaining
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+▶ Step 1: Implement
+  ✓ Added user authentication endpoint
+  ✓ Tests passing (14 passed)
+  ✓ Committed: feat(auth): add login endpoint
+
+▶ Step 2: Simplify
+  ✓ Flattened nested conditionals
+  ✓ Tests passing (14 passed)
+  ✓ Committed: refactor: simplify auth logic
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ITERATION 4  │  8 tasks remaining
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         YOU                                     │
+│                                                                 │
+│   "I need user auth, a REST API for tasks, and filtering"      │
+│                              │                                  │
+│                              ▼                                  │
+│                      ┌──────────────┐                           │
+│                      │  golem spec  │  ← Interactive            │
+│                      └──────────────┘    conversation           │
+│                              │                                  │
+│                              ▼                                  │
+│                        specs/*.md                               │
+│                              │                                  │
+├──────────────────────────────┼──────────────────────────────────┤
+│                         GOLEM                                   │
+│                              │                                  │
+│                              ▼                                  │
+│                      ┌──────────────┐                           │
+│                      │  golem plan  │  ← Analyzes specs         │
+│                      └──────────────┘    vs. codebase           │
+│                              │                                  │
+│                              ▼                                  │
+│                   IMPLEMENTATION_PLAN.md                        │
+│                              │                                  │
+│                              ▼                                  │
+│                      ┌──────────────┐                           │
+│                      │ golem build  │  ← Autonomous loop        │
+│                      └──────────────┘                           │
+│                              │                                  │
+│            ┌─────────────────┼─────────────────┐                │
+│            ▼                 ▼                 ▼                │
+│     ┌────────────┐   ┌────────────┐   ┌────────────┐           │
+│     │ Implement  │ → │    Test    │ → │  Simplify  │ → Commit  │
+│     └────────────┘   └────────────┘   └────────────┘     │     │
+│            ▲                                             │     │
+│            └─────────────── Loop ────────────────────────┘     │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npx golem-cc --global
+source ~/.zshrc
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize in your project
+cd my-project
+golem --install
+
+# 2. Define what you're building (interactive)
+golem spec
+
+# 3. Generate the task list
+golem run plan
+
+# 4. Let it rip
+golem run build
+```
+
+## The Loop
+
+Each iteration runs two separate sessions with fresh context:
+
+**Step 1: Implement**
+- Picks the next task from `IMPLEMENTATION_PLAN.md`
+- Implements the feature/fix
+- Runs tests until they pass
+- Updates the plan
+- Commits
+
+**Step 2: Simplify**
+- Analyzes the code just written
+- Removes AI artifacts (unnecessary comments, dead code)
+- Flattens nested logic
+- Improves naming
+- Runs tests to verify no regressions
+- Commits
+
+Then it loops. Fresh context each time. No degradation.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `golem --install` | Initialize golem in current project |
+| `golem spec` | Build specs through guided conversation |
+| `golem run plan` | Create implementation plan from specs |
+| `golem run build` | Run the autonomous build loop |
+| `golem simplify` | Run code simplifier on demand |
+| `golem status` | Show progress |
+
+### Options
+
+```bash
+golem run build --iterations 10    # Stop after 10 tasks
+golem run build --no-simplify      # Skip simplification step
+```
+
+## Project Structure
+
+After running `golem --install`:
+
+```
+my-project/
+├── .golem/
+│   ├── prompts/          # Loop instructions (customizable)
+│   │   ├── PROMPT_build.md
+│   │   └── PROMPT_plan.md
+│   └── agents/           # AI agent definitions
+│       ├── spec-builder.md
+│       └── code-simplifier.md
+├── specs/                # Your requirements (one file per topic)
+│   ├── authentication.md
+│   └── task-api.md
+├── AGENTS.md             # Test/build/lint commands
+└── IMPLEMENTATION_PLAN.md # Generated task list
+```
+
+## Writing Specs
+
+Specs are simple markdown files describing what you want:
+
+```markdown
+# Authentication
+
+## Purpose
+User authentication for the API.
+
+## Requirements
+
+### Must Have
+- Email/password registration
+- JWT-based sessions with refresh tokens
+- Password hashing with bcrypt
+
+### Should Have
+- Password reset via email
+
+### Must Not
+- Store plain text passwords
+- Allow unlimited login attempts
+
+## Acceptance Criteria
+- [ ] POST /auth/register creates user
+- [ ] POST /auth/login returns JWT
+- [ ] Invalid credentials return 401
+- [ ] Tokens expire after 24 hours
+```
+
+## Backpressure
+
+The loop uses your test suite as a quality gate. Configure in `AGENTS.md`:
+
+```markdown
+# Operational Guide
+
+## Commands
+
+### Testing
+\`\`\`bash
+npm test
+\`\`\`
+
+### Type Checking
+\`\`\`bash
+npm run typecheck
+\`\`\`
+
+### Linting
+\`\`\`bash
+npm run lint
+\`\`\`
+```
+
+If tests fail, it fixes and retries. If they pass, it moves on. Your tests are the contract.
+
+## Philosophy
+
+**Fresh context beats accumulated context.** Each iteration starts clean. No confusion from previous work bleeding in.
+
+**Tests are the spec.** The loop trusts passing tests. Write good tests, get good code.
+
+**Simplification is not optional.** AI-written code tends toward verbosity. The simplifier pass keeps it clean.
+
+**You steer via specs, not prompts.** Change what you want by editing `specs/*.md`, not by micromanaging the AI.
+
+## Based On
+
+- [Ralph Wiggum Playbook](https://claytonfarr.github.io/ralph-playbook/) by Clayton Farr — the autonomous loop methodology
+- [Code Simplifier](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier) from Anthropic — the simplification patterns
+
+## Requirements
+
+- Node.js 18+
+- [Claude Code](https://claude.ai/code) CLI installed and authenticated
+
+## License
+
+MIT