golem-cc 0.2.8 → 1.0.1

package/.env.example

@@ -0,0 +1,17 @@
+# Freshworks/Freshservice
+FRESH_DOMAIN=yourcompany.freshservice.com
+FRESH_API_KEY=your_api_key_here
+
+# Gitea (on-prem)
+GITEA_URL=https://dev.pearlriverresort.com
+GITEA_TOKEN=your_token_here
+GITEA_ORG=CRDE
+
+# Default repo for issues (can be overridden per-project)
+GITEA_REPO=
+
+# Freshservice defaults for ticket creation (get these from your instance)
+FRESH_DEFAULT_GROUP_ID=
+FRESH_DEFAULT_CATEGORY=Applications
+FRESH_SOURCE_ID=
+FRESH_DEFAULT_EMAIL=

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade npm for OIDC support
+        run: npm install -g npm@latest
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Sync package.json version from git tag
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "Setting version to $VERSION"
+          npm version $VERSION --no-git-tag-version --allow-same-version
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance

package/.golem/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,59 @@
+# Implementation Plan
+
+Ticket: LOCAL-DEV (no external ticket)
+Generated: 2026-02-04
+Based on: .golem/specs/config-command.md, .golem/specs/doctor-command.md
+
+## Status
+- Stages: 2
+- Completed: 0
+- Current: Stage 1
+
+---
+
+## Stage 1: Config Command
+Commit: feat(cli): add golem config command to display configuration status
+
+### [x] 1.1. Add cmd_config function to bin/golem
+Files: bin/golem
+Notes: Add function that displays GOLEM_HOME, env file locations, and all env vars with appropriate masking for secrets. Use existing color helpers (GREEN for set, YELLOW for unset optional, RED for unset required). Required vars: FRESH_DOMAIN, FRESH_API_KEY, GITEA_URL, GITEA_TOKEN.
+Tests: Run `golem config` and verify output shows env status correctly
+
+### [x] 1.2. Add config to main case statement and help text
+Files: bin/golem
+Notes: Add "config)" case to main(), add to cmd_help() under OTHER section
+Tests: `golem help` shows config command, `golem config` routes correctly
+
+### [x] 1.3. Create /golem:config Claude command
+Files: commands/golem/config.md
+Notes: Follow pattern from status.md - use bash context blocks to read env status, display formatted output
+Tests: Run `/golem:config` in Claude and verify it shows configuration
+
+---
+
+## Stage 2: Doctor Command
+Commit: feat(cli): add golem doctor command to diagnose setup issues
+Depends on: Stage 1
+
+### [x] 2.1. Add cmd_doctor function to bin/golem
+Files: bin/golem
+Notes: Implement environment checks (~/.golem dir, .env file, required vars), dependency checks (node, pnpm, git, golem-api with versions), installation checks (prompts, agents, commands, claude symlink). Track pass/fail count. Support --check-apis flag for optional API tests.
+Tests: Run `golem doctor` and verify all checks run and display correctly
+
+### [x] 2.2. Add doctor to main case statement and help text
+Files: bin/golem
+Notes: Add "doctor)" case to main(), add to cmd_help() under OTHER section
+Tests: `golem help` shows doctor command, `golem doctor` routes correctly
+
+### [x] 2.3. Create /golem:doctor Claude command
+Files: commands/golem/doctor.md
+Notes: Follow same pattern, run diagnostic checks and display results
+Tests: Run `/golem:doctor` in Claude and verify diagnostics display
+
+---
+
+## Notes
+
+- No external services needed - all local checks
+- Install script may need re-run after adding new commands to copy them to ~/.golem
+- Exit codes: config always 0 (informational), doctor 0 if all pass / 1 if any fail

package/README.md

@@ -1,296 +1,198 @@
-```
-
-   ██████╗  ██████╗ ██╗     ███████╗███╗   ███╗
-  ██╔════╝ ██╔═══██╗██║     ██╔════╝████╗ ████║
-  ██║  ███╗██║   ██║██║     █████╗  ██╔████╔██║
-  ██║   ██║██║   ██║██║     ██╔══╝  ██║╚██╔╝██║
-  ╚██████╔╝╚██████╔╝███████╗███████╗██║ ╚═╝ ██║
-   ╚═════╝  ╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝
-
-```
+# Golem
 
-> *"Ruby's son is a doctor, and you're letting a computer write your code?"*
+Personal agentic workflow manager. Integrates Freshservice tickets, Gitea issues, and Claude Code for a unified development workflow.
 
-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.
+## Installation
 
-<p align="center">
-  <img src="demo.gif" alt="golem-cc demo" width="700">
-</p>
+```bash
+# Install globally via npm
+npm install -g golem-cc
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  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
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Or run directly with pnpm
+pnpm dlx golem-cc
 ```
 
-## How It Works
+After installing, run the setup:
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         YOU                                     │
-│                                                                 │
-│   "I need user auth, a REST API for tasks, and filtering"      │
-│                              │                                  │
-│                              ▼                                  │
-│                  ┌────────────────────┐                         │
-│                  │ claude             │  ← Interactive          │
-│                  │   → /golem:spec    │    conversation         │
-│                  └────────────────────┘                         │
-│                              │                                  │
-│                              ▼                                  │
-│                      .golem/specs/*.md                          │
-│                              │                                  │
-├──────────────────────────────┼──────────────────────────────────┤
-│                         GOLEM                                   │
-│                              │                                  │
-│                              ▼                                  │
-│                    ┌────────────────┐                           │
-│                    │ golem run plan │  ← Analyzes specs         │
-│                    └────────────────┘    vs. codebase           │
-│                              │                                  │
-│                              ▼                                  │
-│               .golem/IMPLEMENTATION_PLAN.md                     │
-│                              │                                  │
-│                              ▼                                  │
-│                   ┌─────────────────┐                           │
-│                   │ golem run build │  ← Autonomous loop        │
-│                   └─────────────────┘                           │
-│                              │                                  │
-│            ┌─────────────────┼─────────────────┐                │
-│            ▼                 ▼                 ▼                │
-│     ┌────────────┐   ┌────────────┐   ┌────────────┐           │
-│     │ Implement  │ → │    Test    │ → │  Simplify  │ → Commit  │
-│     └────────────┘   └────────────┘   └────────────┘     │     │
-│            ▲                                             │     │
-│            └─────────────── Loop ────────────────────────┘     │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
+```bash
+# Check your installation
+golem doctor
+
+# Configure credentials
+vim ~/.golem/.env
+```
+
+## 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        │
+│      └──────────┘   └──────────┘                                   │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
-## Installation
+## Quick Start
 
-### Quick Install (curl)
+### 1. Initialize a project
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/daresTheDevil/golem-cc/main/install.sh | bash
+cd your-project
+golem init
 ```
 
-### Package Managers
+### 2. Get a ticket
 
 ```bash
-# npm
-npx golem-cc
-
-# pnpm
-pnpm dlx golem-cc
-
-# yarn
-yarn dlx golem-cc
+# Import existing Freshservice ticket
+golem import INC-1234
 
-# bun
-bunx golem-cc
+# Or create new ticket
+golem new "Fix API timeout issue"
 ```
 
-### Homebrew (macOS/Linux)
+### 3. Create worktree
 
 ```bash
-brew tap daresTheDevil/golem
-brew install golem-cc
+golem worktree INC-1234
+cd .golem/worktrees/fix/INC-1234-api-timeout
 ```
 
-Then reload your shell:
-```bash
-source ~/.zshrc  # or ~/.bashrc (or ~/.profile for sh)
+### 4. Define specs (in Claude Code)
+
+```
+/golem:spec
 ```
 
-## Quick Start
+Interactive conversation to define requirements, tests, and constraints.
 
-```bash
-# 1. Initialize in your project
-cd my-project
-golem --init
+### 5. Create plan (in Claude Code)
 
-# 2. Define what you're building (interactive)
-claude
-> /golem:spec
-> exit
+```
+/golem:plan
+```
 
-# 3. Generate the task list
-golem run plan
+Generates `.golem/IMPLEMENTATION_PLAN.md` with staged tasks.
 
-# 4. Let it rip
-golem run build
-```
+### 6. Build (CLI loop or Claude Code)
 
-## The Loop
+```bash
+# CLI - loops until done
+golem build
 
-Each iteration runs two separate sessions with fresh context:
+# Or in Claude Code - one task at a time
+/golem:build
+```
 
-**Step 1: Implement**
-- Picks the next task from `.golem/IMPLEMENTATION_PLAN.md`
-- Implements the feature/fix
-- Runs tests until they pass
-- Updates the plan
-- Commits
+Each task gets a WIP commit. Each stage gets squashed.
 
-**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
+### 7. Create PR
 
-Then it loops. Fresh context each time. No degradation.
+```bash
+golem pr
+```
 
 ## Commands
 
-### CLI Commands
+### Terminal
+
 | Command | Description |
 |---------|-------------|
-| `golem --init` | Initialize golem in current project |
-| `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 |
+| `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
 
-### Slash Commands (inside Claude)
 | Command | Description |
 |---------|-------------|
-| `/golem:spec` | Build specs through guided conversation |
-| `/golem:plan` | Create implementation plan |
-| `/golem:build` | Run build loop (single iteration) |
+| `/golem:spec` | Define specs interactively |
+| `/golem:plan` | Generate implementation plan |
+| `/golem:build` | Run one build iteration |
 | `/golem:simplify` | Run code simplifier |
-| `/golem:status` | Show project status |
-| `/golem:help` | Show all commands |
+| `/golem:status` | Show current status |
+| `/golem:config` | Show configuration |
+| `/golem:doctor` | Diagnose setup issues |
+| `/golem:help` | Show help |
 
-### Options
+## Configuration
 
-```bash
-golem run build --iterations 10    # Stop after 10 tasks
-golem run build --no-simplify      # Skip simplification step
-```
+### Environment Variables
 
-## Project Structure
+```bash
+# ~/.golem/.env
 
-After running `golem --init`:
+# 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
 
+# Gitea
+GITEA_URL=https://gitea.example.com
+GITEA_TOKEN=your_token
+GITEA_ORG=your-org
+GITEA_REPO=default-repo               # Can be overridden per-project
 ```
-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
+### Project Structure
 
-### 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 `.golem/AGENTS.md`:
-
-```markdown
-# Operational Guide
-
-## Commands
-
-### Testing
-\`\`\`bash
-npm test
-\`\`\`
-
-### Type Checking
-\`\`\`bash
-npm run typecheck
-\`\`\`
-
-### Linting
-\`\`\`bash
-npm run lint
-\`\`\`
+.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
 ```
 
-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 `.golem/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
-
-## Supported Platforms
-
-- **macOS** (Intel and Apple Silicon)
-- **Linux** (Ubuntu, Debian, Fedora, Arch, Alpine)
-- **WSL2** (Windows Subsystem for Linux)
-
-Shells supported: bash, zsh, sh (POSIX)
-
 ## License
 
 MIT