golem-cc 2.0.0 → 2.1.1

package/bin/golem

@@ -8,7 +8,7 @@
 
 set -euo pipefail
 
-VERSION="2.0.0"
+VERSION="2.1.1"
 GOLEM_HOME="${GOLEM_HOME:-$HOME/.golem}"
 GOLEM_API="golem-api"
 
@@ -132,9 +132,11 @@ OTHER:
     help                  Show this help
 
 CLAUDE COMMANDS (inside Claude Code):
-    /golem:spec           Define specs interactively
-    /golem:plan           Create implementation plan
-    /golem:build          Run build loop (one task at a time)
+    /golem:spec           Define specs (agent team: UX, Architect, Devil's Advocate)
+    /golem:plan           Create implementation plan (agent team per layer)
+    /golem:build          Build lead + builders (observable, interruptible)
+    /golem:security       Run security scans (gitleaks, semgrep, pnpm audit, trivy)
+    /golem:review         Security + code review (runs security first, then agent team)
     /golem:simplify       Run code simplifier
     /golem:status         Show current status
     /golem:help           Show help
@@ -424,19 +426,30 @@ Files to simplify: $files"
 }
 
 cmd_squash() {
-  local ticket_id
+  local ticket_id message=""
   ticket_id=$(get_current_ticket)
   [[ -z "$ticket_id" ]] && die "Not in a ticket worktree"
 
+  # Parse arguments for -m flag
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -m|--message)
+        message="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
   check_api
   load_env
 
-  # Find current stage commit message from plan
   if [[ ! -f .golem/IMPLEMENTATION_PLAN.md ]]; then
     die "No implementation plan found"
   fi
 
-  # Get the commit message for current stage (simplified - just prompt user)
   echo -e "${BOLD}Squashing commits for $ticket_id${NC}"
   echo ""
 
@@ -449,9 +462,12 @@ cmd_squash() {
     return 0
   fi
 
-  echo ""
-  read -p "Commit message: " message
-  [[ -z "$message" ]] && die "Commit message required"
+  # If message not provided via flag, prompt interactively
+  if [[ -z "$message" ]]; then
+    echo ""
+    read -p "Commit message: " message
+    [[ -z "$message" ]] && die "Commit message required"
+  fi
 
   info "Squashing..."
   $GOLEM_API git:squash "$ticket_id" -m "$message"

package/commands/golem/build.md

@@ -1,11 +1,11 @@
 ---
 name: golem:build
-description: Run autonomous build loop - implement, test, simplify, commit
+description: Run autonomous build loop with observability
 allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task]
 ---
 
 <objective>
-Execute the autonomous build loop: select a task, implement it, validate with tests, simplify the code, and commit. Each task gets its own commit. When a stage is complete, all commits in that stage are squashed into one.
+Act as a build lead that orchestrates sequential builder teammates. Each task gets its own builder with fresh context. You coordinate the work, track progress, and handle issues. The user can observe progress and intervene when needed.
 </objective>
 
 <execution_context>
@@ -20,6 +20,7 @@ TICKET_ID=$(basename "$(pwd)" | grep -oE '(INC|SR)-[0-9]+' || echo "")
 if [ -n "$TICKET_ID" ]; then
   cat .golem/tickets/$TICKET_ID.yaml 2>/dev/null
 fi
+echo "TICKET_ID=$TICKET_ID"
 ```
 
 Load specs:
@@ -39,7 +40,11 @@ cat .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No plan - run /golem:plan
 
 Check remaining tasks:
 ```bash
+echo "Remaining tasks:"
 grep -c '^\- \[ \]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
+echo ""
+echo "Completed tasks:"
+grep -c '^\- \[x\]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
 ```
 </context>
 
@@ -54,117 +59,177 @@ grep -c '^\- \[ \]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
 
 If missing prerequisites, instruct user to run appropriate command first.
 
-## Build Loop
+## Build Lead Role
 
-For each iteration:
+You are the **build lead**. Your job is to:
+- Track overall progress through the implementation plan
+- Spawn builder teammates for each task (one at a time, fresh context)
+- Monitor builder progress and relay status to the user
+- Handle failures and blocked tasks
+- Squash commits when a stage completes
+- Keep the user informed so they can intervene if needed
 
-### 1. Orient
-- Read the current .golem/IMPLEMENTATION_PLAN.md
-- Identify current stage and task
-- Review relevant specs for context
+You do NOT implement tasks yourself. You delegate to builders.
 
-### 2. Select Task
-- Pick the **first** incomplete task in the current stage
-- Skip only if it has unmet dependencies
-- Never cherry-pick based on preference
+## The Build Loop
 
-### 3. Investigate
-- Search relevant source code
-- Understand existing patterns
-- Identify files to modify
+For each task in the current stage:
 
-### 4. Implement
-- Make changes required for this task ONLY
-- Follow existing code patterns and conventions
-- Write tests alongside implementation
-- Keep changes minimal and focused
+### 1. Identify Next Task
 
-### 5. Validate (Backpressure)
-Run ALL gates from .golem/AGENTS.md. ALL must pass:
+Read .golem/IMPLEMENTATION_PLAN.md and find the first incomplete task (`- [ ]`).
 
-```bash
-# Run test command
-{test_command from .golem/AGENTS.md}
+Announce to the user:
+```
+=== Task {N.M}: {task title} ===
+Files: {expected files}
+Spawning builder...
+```
 
-# Run typecheck if configured
-{typecheck_command from .golem/AGENTS.md}
+### 2. Spawn Builder Teammate
+
+Create a builder teammate for this specific task:
 
-# Run lint if configured
-{lint_command from .golem/AGENTS.md}
 ```
+Spawn a builder teammate with this prompt:
 
-If any gate fails:
-- Read the error carefully
-- Fix the issue
-- Re-run ALL gates from start
-- Repeat until all pass
+"You are a builder. Complete this ONE task, then shut down.
 
-### 6. Simplify
-After tests pass, simplify modified files:
+TASK: {task title}
+FILES: {expected files}
+NOTES: {implementation hints from plan}
+TESTS: {what tests verify this}
 
-Use the code-simplifier agent principles:
-- Remove unnecessary comments
-- Flatten nested conditionals
-- Improve variable/function names
-- Remove dead code
-- **Preserve ALL behavior**
+WORKFLOW:
+1. Write tests first (red phase)
+2. Implement minimum code to pass tests (green phase)
+3. Run validation gates from .golem/AGENTS.md
+4. If gates fail: fix and retry (up to 3 attempts)
+5. Simplify code (remove comments, flatten logic, improve names)
+6. Re-run validation after simplification
+7. Report back: SUCCESS or BLOCKED with reason
 
-Re-run tests after simplification.
+DO NOT commit. The lead handles commits.
+DO NOT modify the implementation plan. The lead handles that.
 
-### 7. Update Plan & Commit
-Edit `.golem/IMPLEMENTATION_PLAN.md`:
-- Change `[ ]` to `[x]` for completed task
+If you get stuck (DB not running, missing dependency, unclear requirement),
+report BLOCKED immediately with a clear explanation. Do not retry forever."
 
-Create task commit:
-```bash
-git add -A
-git commit -m "wip: {task description} [{TICKET_ID}]"
+Require plan approval before implementation.
 ```
 
-### 8. Check Stage Completion
+### 3. Monitor Builder
+
+Watch the builder's progress. The user can see this too.
+
+**If builder reports SUCCESS:**
+- Mark task complete in .golem/IMPLEMENTATION_PLAN.md
+- Create atomic commit:
+  ```bash
+  git add -A
+  git commit -m "wip: {brief task description}"
+  ```
+- Announce: `✓ Task {N.M} complete`
+- Shut down the builder
+- Continue to next task
+
+**If builder reports BLOCKED:**
+- Announce to user:
+  ```
+  ⚠ Task {N.M} BLOCKED
+  Reason: {builder's explanation}
+
+  Options:
+  1. I can skip this task and continue
+  2. You can provide guidance and I'll retry
+  3. You can fix the issue and tell me to retry
+  ```
+- Wait for user input before proceeding
+- Do NOT auto-retry blocked tasks
+
+**If builder is struggling (3+ failed attempts):**
+- Message the builder: "What's blocking you?"
+- Relay the answer to the user
+- Ask user how to proceed
+
+### 4. Stage Completion
 
-If current stage is complete (all tasks marked `[x]`):
+When all tasks in a stage are marked `[x]`:
 
-1. **Squash stage commits** into one clean commit:
+1. Announce: `=== Stage {N} Complete ===`
+
+2. Squash all wip commits:
    ```bash
-   golem-api git:squash $TICKET_ID -m "{stage commit message from plan} [{TICKET_ID}]"
+   golem-api git:squash "{TICKET_ID}" -m "{stage commit message from plan}"
    ```
 
-2. **Update ticket status** with progress:
+3. Update ticket status:
    ```bash
-   golem-api ticket:status $TICKET_ID in-progress --note "Stage N complete: {stage name}"
+   golem-api ticket:status "{TICKET_ID}" in-progress --note "Stage {N} complete: {stage name}"
    ```
 
-3. **Update plan** to mark stage complete
+4. If more stages remain: announce and continue
+5. If all stages complete: proceed to completion
+
+### 5. Overall Completion
 
-4. Continue to next stage
+When all stages are complete:
+```
+=== BUILD COMPLETE ===
 
-### 9. Check Overall Completion
+All {N} stages complete.
+Ticket: {TICKET_ID}
+
+Next steps:
+1. Run /golem:review for code review
+2. Run golem pr to create pull request
+```
 
-- If remaining tasks > 0: continue to next iteration
-- If all stages complete:
-  - Update ticket status to "review"
-  - Announce completion
-  - Suggest creating PR
-- If stuck for 3+ attempts on same task: mark blocked and move on
+Update ticket status to "review".
 
 </process>
 
+<user_controls>
+
+The user can intervene at any time:
+
+- **"skip"** - Skip the current blocked task, continue to next
+- **"retry"** - Tell the current builder to try again
+- **"stop"** - Stop the build loop, keep progress
+- **"status"** - Show current progress summary
+- **Message the builder directly** - Use Shift+Up/Down to select and message
+
+As lead, relay these commands appropriately and keep the user informed.
+
+</user_controls>
+
 <success_criteria>
-- [ ] Task selected from plan
+For each task:
+- [ ] Builder spawned with fresh context
+- [ ] Tests written first
 - [ ] Implementation complete
-- [ ] All tests passing
+- [ ] All gates passing
 - [ ] Code simplified
-- [ ] Plan updated
-- [ ] Task committed
-- [ ] Stage squashed when complete
-- [ ] Ticket status synced
+- [ ] Atomic commit created
+- [ ] Builder shut down
+
+For each stage:
+- [ ] All tasks complete
+- [ ] Commits squashed
+- [ ] Ticket status updated
+
+Overall:
+- [ ] User can observe progress
+- [ ] User can intervene when needed
+- [ ] Blocked tasks surfaced immediately
 </success_criteria>
 
 <important>
-- Complete ONE task per message, then check if user wants to continue
-- Fresh context helps - don't accumulate too much in one session
-- Trust the tests - if they pass, implementation is correct
-- Each task gets a wip commit, each stage gets squashed
-- Keep ticket status updated throughout
+- You are the LEAD, not the implementer - delegate to builders
+- Each builder gets ONE task, then shuts down (fresh context)
+- Surface blockers immediately - don't let builders spin
+- Keep the user informed at every step
+- The user can always intervene - that's the point
+- Builders should NOT commit or modify the plan
+- YOU handle commits, plan updates, and squashing
 </important>

package/commands/golem/help.md

@@ -11,62 +11,202 @@ Display help information for all golem commands.
 <response>
 # Golem - Personal Workflow Manager
 
-Golem integrates Freshworks tickets, Gitea issues, and local development into a unified workflow.
+Golem integrates Freshworks tickets, Gitea issues, and local development into a unified workflow. Uses Claude Code agent teams for collaborative spec/plan/review phases.
 
-## Claude Code Commands (inside Claude)
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/golem:spec` | Define specs through guided conversation |
-| `/golem:plan` | Create implementation plan from specs |
-| `/golem:build` | Run build loop (implement → test → simplify → commit) |
+| `/golem:spec` | Define specs with agent team (UX, Architect, Devil's Advocate) |
+| `/golem:plan` | Create implementation plan with agent team (per-layer + Devil's Advocate) |
+| `/golem:build` | Build lead + sequential builders (observable, interruptible) |
+| `/golem:security` | Run automated security scans (gitleaks, semgrep, pnpm audit, trivy) |
+| `/golem:review` | Security scans + code review agent team |
 | `/golem:simplify` | Run code simplifier on files |
 | `/golem:status` | Show current ticket/project status |
 | `/golem:help` | Show this help |
 
-## CLI Commands (terminal)
+---
+
+## Default Workflow
+
+### 1. Setup (CLI)
+```bash
+golem import INC-1234        # Import ticket from Freshservice
+golem worktree               # Create isolated worktree for this ticket
+cd .golem/worktrees/INC-1234 # Enter the worktree
+claude                       # Start Claude Code
+```
+
+### 2. Spec Phase (`/golem:spec`)
+
+Agent team explores requirements from multiple angles:
+
+```
+You: /golem:spec
+
+[Agent team spawns]
+├── UX Advocate: "Who are the users? What's the simplest solution?"
+├── Architect: "What's the technical approach? What patterns fit?"
+└── Devil's Advocate: "Do we need this? What's the simpler alternative?"
+
+[Team debates and synthesizes]
+
+Output:
+├── .golem/specs/authentication.md
+├── .golem/specs/validation.md
+└── .golem/AGENTS.md (test/build/lint commands)
+```
+
+### 3. Plan Phase (`/golem:plan`)
+
+Agent team creates staged implementation plan:
+
+```
+You: /golem:plan
+
+[Agent team spawns based on project layers]
+├── Frontend Planner: "Component structure, state management"
+├── Backend Planner: "API design, business logic"
+├── Data Planner: "Schema, migrations, queries"
+└── Devil's Advocate: "Too complex? Better patterns?"
+
+[Team maps requirements to tasks]
+
+Output:
+└── .golem/IMPLEMENTATION_PLAN.md
+    ├── Stage 1: Setup (3 tasks) → "feat(auth): add login endpoint"
+    ├── Stage 2: Core Logic (5 tasks) → "feat(auth): implement validation"
+    └── Stage 3: Integration (2 tasks) → "feat(auth): wire up frontend"
+```
+
+### 4. Build Phase (`/golem:build`)
+
+Lead orchestrates builders, you observe and intervene:
+
+```
+You: /golem:build
+
+[Build lead starts]
+=== Task 1.1: Create auth service ===
+Spawning builder...
+
+[Builder works - you can watch]
+├── Writing tests (red phase)
+├── Implementing (green phase)
+├── Running validation gates
+├── Simplifying code
+└── Reporting: SUCCESS
 
+✓ Task 1.1 complete
+=== Task 1.2: Add password validation ===
+Spawning builder...
+
+[If something breaks]
+⚠ Task 1.3 BLOCKED
+Reason: Cannot connect to database
+
+Options:
+1. Skip and continue
+2. Provide guidance
+3. Fix and retry
+
+You: The DB is on port 5433, not 5432
+[Lead relays to builder, continues]
+
+[Stage complete]
+=== Stage 1 Complete ===
+Squashing commits...
+```
+
+**Build controls:**
+- `skip` - Skip blocked task
+- `retry` - Retry current task
+- `stop` - Pause build
+- `status` - Show progress
+- `Shift+Up/Down` - Message builder directly
+
+### 5. Review Phase (`/golem:review`)
+
+Security scans first, then agent team review:
+
+```
+You: /golem:review
+
+[Security gate - automated tools]
+=== SECRETS SCAN (gitleaks) ===
+✓ No secrets detected
+
+=== SAST SCAN (semgrep) ===
+✓ 0 findings
+
+=== DEPENDENCY SCAN (pnpm audit) ===
+✓ 0 high, 0 critical
+
+[Agent team spawns for code review]
+├── Security Patterns: Auth logic, input validation
+├── Performance: Query patterns, algorithms
+├── Correctness: Spec match, edge cases
+├── Tests: Coverage, quality
+└── Devil's Advocate: Overengineered? Maintainable?
+
+[Team reports findings]
+
+Output:
+└── .golem/REVIEW_REPORT.md
+    ├── Verdict: APPROVED (or BLOCKED)
+    ├── 0 critical, 1 major, 3 minor issues
+    └── Recommendations for future work
+```
+
+### 6. Ship (CLI)
 ```bash
-# Ticket Management
-golem new "description"           # Create new ticket + issue
-golem import INC-1234             # Import existing Fresh ticket
-golem list                        # List all tickets
-golem status                      # Show current ticket status
-
-# Worktree Management
-golem worktree                    # Create worktree for current ticket
-golem worktree INC-1234           # Create worktree for specific ticket
-golem worktrees                   # List all worktrees
-
-# Build Loop
-golem build                       # Run build loop (spawns Claude)
-golem plan                        # Generate plan (spawns Claude)
-
-# Utilities
-golem simplify [files]            # Run simplifier
-golem sync                        # Sync ticket status to Fresh/Gitea
+golem pr                     # Create pull request
+# Review, merge, done
 ```
 
-## Typical Workflow
+---
+
+## Files Generated
 
-1. **Get a ticket**: `golem import INC-1234` or `golem new "fix api timeout"`
-2. **Create worktree**: `golem worktree`
-3. **Define specs**: `/golem:spec` (in Claude)
-4. **Create plan**: `/golem:plan` (in Claude)
-5. **Build**: `/golem:build` (in Claude) or `golem build` (CLI loop)
-6. **Review**: Create PR, sync status
-7. **Done**: Merge, close ticket
+| File | Created By | Purpose |
+|------|------------|---------|
+| `.golem/specs/*.md` | /golem:spec | Requirements for each topic |
+| `.golem/AGENTS.md` | /golem:spec | Test/build/lint commands |
+| `.golem/IMPLEMENTATION_PLAN.md` | /golem:plan | Staged task list |
+| `.golem/SECURITY_REPORT.md` | /golem:security | Scan results |
+| `.golem/REVIEW_REPORT.md` | /golem:review | Code review findings |
 
-## Environment Variables
+---
 
-Set in `~/.golem/.env`:
+## Agent Teams
+
+All phases use a **Devil's Advocate** who:
+- Must articulate WHY something is problematic
+- Must propose a concrete alternative
+- Must back down when concern is addressed
+- Goal: better thinking, not blocking progress
+
+---
+
+## Environment Setup
 
 ```bash
+# ~/.golem/.env
 FRESH_DOMAIN=yourcompany.freshservice.com
 FRESH_API_KEY=your_api_key
-GITEA_URL=https://dev.pearlriverresort.com
+GITEA_URL=https://gitea.example.com
 GITEA_TOKEN=your_token
-GITEA_ORG=CRDE
-GITEA_REPO=default-repo
+GITEA_ORG=your-org
+GITEA_REPO=your-repo
+```
+
+```json
+// Claude Code settings.json - enable agent teams
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
 ```
 </response>