golem-cc 0.2.2 → 0.2.5

package/README.md

@@ -52,7 +52,7 @@ Golem is an autonomous coding loop that implements features while you watch (or
 │                  └────────────────────┘                         │
 │                              │                                  │
 │                              ▼                                  │
-│                        specs/*.md                               │
+│                      .golem/specs/*.md                          │
 │                              │                                  │
 ├──────────────────────────────┼──────────────────────────────────┤
 │                         GOLEM                                   │
@@ -63,7 +63,7 @@ Golem is an autonomous coding loop that implements features while you watch (or
 │                    └────────────────┘    vs. codebase           │
 │                              │                                  │
 │                              ▼                                  │
-│                   IMPLEMENTATION_PLAN.md                        │
+│               .golem/IMPLEMENTATION_PLAN.md                     │
 │                              │                                  │
 │                              ▼                                  │
 │                   ┌─────────────────┐                           │
@@ -126,7 +126,7 @@ golem run build
 Each iteration runs two separate sessions with fresh context:
 
 **Step 1: Implement**
-- Picks the next task from `IMPLEMENTATION_PLAN.md`
+- Picks the next task from `.golem/IMPLEMENTATION_PLAN.md`
 - Implements the feature/fix
 - Runs tests until they pass
 - Updates the plan
@@ -176,18 +176,18 @@ After running `golem --init`:
 
 ```
 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
+└── .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
@@ -223,7 +223,7 @@ User authentication for the API.
 
 ## Backpressure
 
-The loop uses your test suite as a quality gate. Configure in `AGENTS.md`:
+The loop uses your test suite as a quality gate. Configure in `.golem/AGENTS.md`:
 
 ```markdown
 # Operational Guide
@@ -256,7 +256,7 @@ If tests fail, it fixes and retries. If they pass, it moves on. Your tests are t
 
 **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.
+**You steer via specs, not prompts.** Change what you want by editing `.golem/specs/*.md`, not by micromanaging the AI.
 
 ## Based On
 

package/bin/golem

@@ -11,6 +11,7 @@
 #   golem run build          Run autonomous build loop
 #   golem simplify [path]    Run code simplifier
 #   golem status             Show project status
+#   golem doctor             Check installation health
 #
 set -euo pipefail
 
@@ -115,6 +116,119 @@ get_version() {
     fi
 }
 
+# Update checker - checks npm registry for newer version with caching
+# Cache file: ~/.golem/.update-check (JSON format)
+# Returns: latest version if update available, empty string otherwise
+check_for_update() {
+    local current_version="$1"
+    local cache_file="$HOME/.golem/.update-check"
+    local cache_max_age=86400  # 24 hours in seconds
+    local timeout_secs=3
+    local npm_registry="https://registry.npmjs.org/golem-cc/latest"
+
+    # Skip if current version is unknown
+    [[ "$current_version" == "unknown" ]] && return
+
+    # Check cache first
+    if [[ -f "$cache_file" ]]; then
+        local cache_time=""
+        local cached_version=""
+
+        if command -v jq &>/dev/null; then
+            cache_time=$(jq -r '.checked // 0' "$cache_file" 2>/dev/null)
+            cached_version=$(jq -r '.version // ""' "$cache_file" 2>/dev/null)
+        else
+            # Parse JSON without jq
+            cache_time=$(grep -o '"checked"[[:space:]]*:[[:space:]]*[0-9]*' "$cache_file" 2>/dev/null | grep -o '[0-9]*$')
+            cached_version=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$cache_file" 2>/dev/null | sed 's/.*"\([^"]*\)"$/\1/')
+        fi
+
+        local now
+        now=$(date +%s)
+        local age=$((now - ${cache_time:-0}))
+
+        # Use cached result if still fresh
+        if [[ $age -lt $cache_max_age ]] && [[ -n "$cached_version" ]]; then
+            # Compare versions - only output if update available
+            if version_gt "$cached_version" "$current_version"; then
+                echo "$cached_version"
+            fi
+            return
+        fi
+    fi
+
+    # Fetch latest version from npm registry (with timeout, background-friendly)
+    local latest_version=""
+    local response=""
+
+    # Use curl with timeout (available on all Unix systems)
+    if command -v curl &>/dev/null; then
+        response=$(curl -s --max-time "$timeout_secs" "$npm_registry" 2>/dev/null) || return
+    elif command -v wget &>/dev/null; then
+        response=$(wget -q -O - --timeout="$timeout_secs" "$npm_registry" 2>/dev/null) || return
+    else
+        # No curl or wget available
+        return
+    fi
+
+    # Parse version from response
+    if [[ -n "$response" ]]; then
+        if command -v jq &>/dev/null; then
+            latest_version=$(echo "$response" | jq -r '.version // ""' 2>/dev/null)
+        else
+            latest_version=$(echo "$response" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+        fi
+    fi
+
+    # Update cache (create directory if needed)
+    if [[ -n "$latest_version" ]]; then
+        mkdir -p "$(dirname "$cache_file")"
+        local now
+        now=$(date +%s)
+        cat > "$cache_file" << EOF
+{"version":"$latest_version","checked":$now}
+EOF
+
+        # Compare versions and output if update available
+        if version_gt "$latest_version" "$current_version"; then
+            echo "$latest_version"
+        fi
+    fi
+}
+
+# Compare two semver versions - returns 0 if v1 > v2
+version_gt() {
+    local v1="$1"
+    local v2="$2"
+
+    # Use sort -V if available (GNU coreutils)
+    if printf '%s\n' "$v1" "$v2" | sort -V &>/dev/null; then
+        local highest
+        highest=$(printf '%s\n' "$v1" "$v2" | sort -V | tail -1)
+        [[ "$highest" == "$v1" ]] && [[ "$v1" != "$v2" ]]
+        return $?
+    fi
+
+    # Fallback: simple numeric comparison for x.y.z format
+    local v1_major v1_minor v1_patch
+    local v2_major v2_minor v2_patch
+
+    IFS='.' read -r v1_major v1_minor v1_patch <<< "$v1"
+    IFS='.' read -r v2_major v2_minor v2_patch <<< "$v2"
+
+    # Default to 0 if empty
+    v1_major=${v1_major:-0}; v1_minor=${v1_minor:-0}; v1_patch=${v1_patch:-0}
+    v2_major=${v2_major:-0}; v2_minor=${v2_minor:-0}; v2_patch=${v2_patch:-0}
+
+    # Compare major.minor.patch
+    if [[ $v1_major -gt $v2_major ]]; then return 0; fi
+    if [[ $v1_major -lt $v2_major ]]; then return 1; fi
+    if [[ $v1_minor -gt $v2_minor ]]; then return 0; fi
+    if [[ $v1_minor -lt $v2_minor ]]; then return 1; fi
+    if [[ $v1_patch -gt $v2_patch ]]; then return 0; fi
+    return 1
+}
+
 # Audit logging
 log_event() {
     local event="$1"
@@ -192,6 +306,10 @@ print_usage() {
     echo "  simplify [path]   Run code simplifier"
     echo "  status            Show project status"
     echo "  status --check    Exit 0 if complete, 1 if incomplete, 2 if no plan"
+    echo "  status --skip-update-check  Skip checking for updates"
+    echo "  doctor            Check installation health"
+    echo "  doctor --fix      Auto-fix detected issues"
+    echo "  doctor --json     Output results as JSON (for CI/scripting)"
     echo ""
     echo -e "${BLUE}Options:${NC}"
     echo "  --init            Initialize golem in current project"
@@ -681,8 +799,376 @@ cmd_simplify() {
     fi
 }
 
+# Doctor command - verify installation health
+cmd_doctor() {
+    local all_passed=true
+    local fix_mode=false
+    local json_mode=false
+    local fixes_applied=0
+    local fixes_available=0
+
+    # JSON output accumulator (array of check results)
+    local json_checks=()
+
+    # Parse options
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --fix)
+                fix_mode=true
+                shift
+                ;;
+            --json)
+                json_mode=true
+                shift
+                ;;
+            *)
+                shift
+                ;;
+        esac
+    done
+
+    if [[ "$json_mode" == "false" ]]; then
+        print_banner
+        header_box "DOCTOR" "$BLUE"
+        echo ""
+        if [[ "$fix_mode" == "true" ]]; then
+            echo -e "  ${DIM}Checking installation health (auto-fix enabled)...${NC}"
+        else
+            echo -e "  ${DIM}Checking golem installation health...${NC}"
+        fi
+        echo ""
+    fi
+
+    # Track check results for summary
+    local checks_passed=0
+    local checks_failed=0
+
+    # Helper: prompt user to apply a fix (or auto-apply in fix mode)
+    # Always returns 0 to avoid triggering set -e
+    apply_fix() {
+        local description="$1"
+        local fix_cmd="$2"
+
+        fixes_available=$((fixes_available + 1))
+
+        if [[ "$fix_mode" == "true" ]]; then
+            # Auto-fix mode: apply without prompting
+            [[ "$json_mode" == "false" ]] && echo -e "       ${CYAN}→ Applying fix: $description${NC}"
+            if eval "$fix_cmd" 2>/dev/null; then
+                [[ "$json_mode" == "false" ]] && echo -e "       ${GREEN}✓ Fixed${NC}"
+                fixes_applied=$((fixes_applied + 1))
+            else
+                [[ "$json_mode" == "false" ]] && echo -e "       ${RED}✗ Fix failed${NC}"
+            fi
+        else
+            # Interactive mode: prompt user (only if stdin is a terminal and not json mode)
+            if [[ -t 0 ]] && [[ "$json_mode" == "false" ]]; then
+                echo -ne "       ${YELLOW}Fix this? [y/N]${NC} "
+                local response=""
+                read -r response
+                if [[ "$response" =~ ^[Yy]$ ]]; then
+                    echo -e "       ${CYAN}→ Applying fix: $description${NC}"
+                    if eval "$fix_cmd" 2>/dev/null; then
+                        echo -e "       ${GREEN}✓ Fixed${NC}"
+                        fixes_applied=$((fixes_applied + 1))
+                    else
+                        echo -e "       ${RED}✗ Fix failed${NC}"
+                    fi
+                else
+                    echo -e "       ${DIM}Skipped${NC}"
+                fi
+            elif [[ "$json_mode" == "false" ]]; then
+                # Non-interactive: just show the hint
+                echo -e "       ${DIM}Fix: $description${NC}"
+            fi
+        fi
+        return 0  # Always return 0 to continue script execution
+    }
+
+    # Helper function to run a check with optional auto-fix
+    # Always returns 0 to avoid triggering set -e; tracks failures internally
+    run_check() {
+        local name="$1"
+        local check_cmd="$2"
+        local fix_hint="$3"
+        local fix_cmd="${4:-}"
+        local check_status="pass"
+        local fixed=false
+
+        if eval "$check_cmd" 2>/dev/null; then
+            [[ "$json_mode" == "false" ]] && status_line "✓" "$GREEN" "$name"
+            checks_passed=$((checks_passed + 1))
+            check_status="pass"
+        else
+            [[ "$json_mode" == "false" ]] && status_line "✗" "$RED" "$name"
+            checks_failed=$((checks_failed + 1))
+            all_passed=false
+            check_status="fail"
+
+            # Attempt to fix if fix_cmd is provided
+            if [[ -n "$fix_cmd" ]]; then
+                apply_fix "$fix_hint" "$fix_cmd"
+                # Re-check after fix attempt
+                if eval "$check_cmd" 2>/dev/null; then
+                    checks_passed=$((checks_passed + 1))
+                    checks_failed=$((checks_failed - 1))
+                    check_status="fixed"
+                    fixed=true
+                fi
+            elif [[ -n "$fix_hint" ]] && [[ "$json_mode" == "false" ]]; then
+                echo -e "       ${DIM}Fix: $fix_hint${NC}"
+            fi
+        fi
+
+        # Add to JSON checks array
+        local fix_available="false"
+        [[ -n "$fix_cmd" ]] && fix_available="true"
+        local escaped_name="${name//\"/\\\"}"
+        local escaped_hint="${fix_hint//\"/\\\"}"
+        json_checks+=("{\"name\":\"$escaped_name\",\"status\":\"$check_status\",\"fixable\":$fix_available,\"fix_hint\":\"$escaped_hint\"}")
+
+        return 0  # Always return 0 to continue script execution
+    }
+
+    # === Global Installation Checks ===
+    [[ "$json_mode" == "false" ]] && echo -e "  ${BOLD}Global Installation (~/.golem/)${NC}"
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # Check ~/.golem directory exists
+    run_check "~/.golem/ directory exists" \
+        "[[ -d \"$HOME/.golem\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.golem\""
+
+    # Check ~/.golem/bin/golem exists and is executable
+    run_check "~/.golem/bin/golem is executable" \
+        "[[ -x \"$HOME/.golem/bin/golem\" ]]" \
+        "Fix permissions" \
+        "[[ -f \"$HOME/.golem/bin/golem\" ]] && chmod +x \"$HOME/.golem/bin/golem\""
+
+    # Check ~/.golem/bin/render-md.cjs exists
+    run_check "~/.golem/bin/render-md.cjs exists" \
+        "[[ -f \"$HOME/.golem/bin/render-md.cjs\" ]]" \
+        "npx golem-cc (reinstall)" \
+        ""
+
+    # Check ~/.golem/golem/prompts directory
+    run_check "~/.golem/golem/prompts/ exists" \
+        "[[ -d \"$HOME/.golem/golem/prompts\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.golem/golem/prompts\""
+
+    # Check ~/.golem/golem/agents directory
+    run_check "~/.golem/golem/agents/ exists" \
+        "[[ -d \"$HOME/.golem/golem/agents\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.golem/golem/agents\""
+
+    # Check VERSION file
+    run_check "~/.golem/VERSION file exists" \
+        "[[ -f \"$HOME/.golem/VERSION\" ]]" \
+        "npx golem-cc (reinstall)" \
+        ""
+
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # === Claude Code Integration Checks ===
+    [[ "$json_mode" == "false" ]] && echo -e "  ${BOLD}Claude Code Integration (~/.claude/)${NC}"
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # Check ~/.claude/golem directory
+    run_check "~/.claude/golem/ directory exists" \
+        "[[ -d \"$HOME/.claude/golem\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.claude/golem\""
+
+    # Check ~/.claude/commands/golem directory with slash commands
+    run_check "~/.claude/commands/golem/ exists" \
+        "[[ -d \"$HOME/.claude/commands/golem\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.claude/commands/golem\""
+
+    # Check for key slash command files
+    run_check "Slash commands installed (build.md)" \
+        "[[ -f \"$HOME/.claude/commands/golem/build.md\" ]]" \
+        "npx golem-cc (reinstall)" \
+        ""
+
+    # Check ~/.claude/golem/prompts directory
+    run_check "~/.claude/golem/prompts/ exists" \
+        "[[ -d \"$HOME/.claude/golem/prompts\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.claude/golem/prompts\""
+
+    # Check ~/.claude/golem/agents directory
+    run_check "~/.claude/golem/agents/ exists" \
+        "[[ -d \"$HOME/.claude/golem/agents\" ]]" \
+        "Create directory" \
+        "mkdir -p \"$HOME/.claude/golem/agents\""
+
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # === Shell Integration Checks ===
+    [[ "$json_mode" == "false" ]] && echo -e "  ${BOLD}Shell Integration${NC}"
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # Determine user's shell and config file
+    local user_shell
+    user_shell=$(basename "${SHELL:-/bin/bash}")
+    local shell_config=""
+    case "$user_shell" in
+        zsh)  shell_config="$HOME/.zshrc" ;;
+        bash)
+            if [[ -f "$HOME/.bash_profile" ]]; then
+                shell_config="$HOME/.bash_profile"
+            else
+                shell_config="$HOME/.bashrc"
+            fi
+            ;;
+        *)    shell_config="$HOME/.profile" ;;
+    esac
+
+    # Check if golem is in PATH (the function/alias should work)
+    run_check "golem command available in PATH" \
+        "command -v golem &>/dev/null" \
+        "Add PATH to $shell_config" \
+        "grep -q '.golem/bin' \"$shell_config\" 2>/dev/null || echo 'export PATH=\"\$HOME/.golem/bin:\$PATH\"' >> \"$shell_config\""
+
+    # Check shell config files for golem setup
+    local shell_config_found=false
+    local shell_configs=("$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.profile")
+    for config in "${shell_configs[@]}"; do
+        if [[ -f "$config" ]] && grep -q "golem" "$config" 2>/dev/null; then
+            shell_config_found=true
+            break
+        fi
+    done
+    run_check "Shell config contains golem setup" \
+        "$shell_config_found" \
+        "Add PATH to $shell_config" \
+        "grep -q '.golem/bin' \"$shell_config\" 2>/dev/null || echo 'export PATH=\"\$HOME/.golem/bin:\$PATH\"' >> \"$shell_config\""
+
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # === Optional Checks ===
+    [[ "$json_mode" == "false" ]] && echo -e "  ${BOLD}Optional Dependencies${NC}"
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # Check if Claude Code CLI is installed
+    if command -v claude &>/dev/null; then
+        local claude_version
+        claude_version=$(claude --version 2>/dev/null | head -1 || echo "unknown")
+        [[ "$json_mode" == "false" ]] && status_line "✓" "$GREEN" "Claude Code CLI installed ($claude_version)"
+        checks_passed=$((checks_passed + 1))
+        json_checks+=("{\"name\":\"Claude Code CLI installed\",\"status\":\"pass\",\"fixable\":false,\"fix_hint\":\"npm install -g @anthropic-ai/claude-code\",\"version\":\"$claude_version\"}")
+    else
+        [[ "$json_mode" == "false" ]] && status_line "◦" "$YELLOW" "Claude Code CLI not found (required for golem)"
+        [[ "$json_mode" == "false" ]] && echo -e "       ${DIM}Install: npm install -g @anthropic-ai/claude-code${NC}"
+        # This is critical, so count as failure
+        checks_failed=$((checks_failed + 1))
+        all_passed=false
+        json_checks+=("{\"name\":\"Claude Code CLI installed\",\"status\":\"fail\",\"fixable\":false,\"fix_hint\":\"npm install -g @anthropic-ai/claude-code\"}")
+    fi
+
+    [[ "$json_mode" == "false" ]] && echo ""
+
+    # === Project-Level Checks (if in a golem project) ===
+    if [[ -d ".golem" ]]; then
+        [[ "$json_mode" == "false" ]] && echo -e "  ${BOLD}Project-Level (.golem/)${NC}"
+        [[ "$json_mode" == "false" ]] && echo ""
+
+        run_check ".golem/ directory exists" \
+            "[[ -d \".golem\" ]]" \
+            "Create directory" \
+            "mkdir -p .golem"
+
+        run_check ".golem/AGENTS.md exists" \
+            "[[ -f \".golem/AGENTS.md\" ]]" \
+            "Run golem --init" \
+            ""
+
+        run_check ".golem/specs/ directory exists" \
+            "[[ -d \".golem/specs\" ]]" \
+            "Create directory" \
+            "mkdir -p .golem/specs"
+
+        run_check ".golem/prompts/ directory exists" \
+            "[[ -d \".golem/prompts\" ]]" \
+            "Create directory" \
+            "mkdir -p .golem/prompts"
+
+        run_check ".golem/agents/ directory exists" \
+            "[[ -d \".golem/agents\" ]]" \
+            "Create directory" \
+            "mkdir -p .golem/agents"
+
+        [[ "$json_mode" == "false" ]] && echo ""
+    fi
+
+    # === Summary ===
+    local total=$((checks_passed + checks_failed))
+    local version
+    version=$(get_version)
+
+    # JSON output mode
+    if [[ "$json_mode" == "true" ]]; then
+        local json_checks_str
+        json_checks_str=$(IFS=,; echo "${json_checks[*]}")
+        local success="true"
+        [[ $checks_failed -gt 0 ]] && success="false"
+
+        cat <<EOF
+{
+  "success": $success,
+  "version": "$version",
+  "checks_passed": $checks_passed,
+  "checks_failed": $checks_failed,
+  "checks_total": $total,
+  "fixes_applied": $fixes_applied,
+  "fixes_available": $fixes_available,
+  "checks": [$json_checks_str]
+}
+EOF
+        if [[ $checks_failed -eq 0 ]]; then
+            exit 0
+        else
+            exit 1
+        fi
+    fi
+
+    hr "━" "$CYAN"
+    echo ""
+
+    # Show fixes applied if any
+    if [[ $fixes_applied -gt 0 ]]; then
+        status_line "⚡" "$CYAN" "$fixes_applied fix(es) applied"
+    fi
+
+    # Recalculate pass status (fixes may have resolved issues)
+    if [[ $checks_failed -eq 0 ]]; then
+        status_line "✓" "$GREEN" "All checks passed ($checks_passed/$total)"
+        echo ""
+        if [[ $fixes_applied -gt 0 ]]; then
+            echo -e "  ${DIM}Note: You may need to restart your shell for PATH changes${NC}"
+            echo ""
+        fi
+        exit 0
+    else
+        status_line "✗" "$RED" "$checks_failed check(s) failed ($checks_passed/$total passed)"
+        echo ""
+        if [[ "$fix_mode" == "false" ]] && [[ $fixes_available -gt 0 ]]; then
+            echo -e "  ${DIM}Run 'golem doctor --fix' to auto-fix issues${NC}"
+        else
+            echo -e "  ${DIM}Run 'npx golem-cc' to reinstall golem${NC}"
+        fi
+        echo ""
+        exit 1
+    fi
+}
+
 cmd_status() {
     local check_only=false
+    local skip_update_check=false
 
     # Parse options
     while [[ $# -gt 0 ]]; do
@@ -691,6 +1177,10 @@ cmd_status() {
                 check_only=true
                 shift
                 ;;
+            --skip-update-check)
+                skip_update_check=true
+                shift
+                ;;
             *)
                 shift
                 ;;
@@ -750,6 +1240,19 @@ cmd_status() {
         done || echo -e "    ${DIM}No commits yet${NC}"
     fi
     echo ""
+
+    # Check for updates (non-blocking, cached)
+    if [[ "$skip_update_check" == "false" ]]; then
+        local current_version
+        current_version=$(get_version)
+        local latest_version
+        latest_version=$(check_for_update "$current_version")
+
+        if [[ -n "$latest_version" ]]; then
+            echo -e "  ${YELLOW}Update available:${NC} ${DIM}$current_version${NC} → ${GREEN}$latest_version${NC} ${DIM}(run: npx golem-cc)${NC}"
+            echo ""
+        fi
+    fi
 }
 
 # Main entry point
@@ -783,6 +1286,10 @@ main() {
             shift
             cmd_status "$@"
             ;;
+        doctor)
+            shift
+            cmd_doctor "$@"
+            ;;
         "")
             # No command - just launch claude
             claude

package/commands/golem/build.md

@@ -16,22 +16,22 @@ Execute the autonomous build loop: select a task, implement it, validate with te
 <context>
 Load specs:
 ```bash
-for f in specs/*.md; do echo "=== $f ==="; cat "$f"; echo; done 2>/dev/null
+for f in .golem/specs/*.md; do echo "=== $f ==="; cat "$f"; echo; done 2>/dev/null
 ```
 
 Load operational guide:
 ```bash
-cat AGENTS.md 2>/dev/null || echo "No AGENTS.md - run /golem:spec first"
+cat .golem/AGENTS.md 2>/dev/null || echo "No AGENTS.md - run /golem:spec first"
 ```
 
 Load implementation plan:
 ```bash
-cat IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No plan - run /golem:plan first"
+cat .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No plan - run /golem:plan first"
 ```
 
 Check remaining tasks:
 ```bash
-grep -c '^\- \[ \]' IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
+grep -c '^\- \[ \]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
 ```
 </context>
 
@@ -39,9 +39,9 @@ grep -c '^\- \[ \]' IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0"
 
 ## Pre-flight Checks
 
-1. Verify IMPLEMENTATION_PLAN.md exists
-2. Verify specs/ directory has files
-3. Verify AGENTS.md has test commands
+1. Verify .golem/IMPLEMENTATION_PLAN.md exists
+2. Verify .golem/specs/ directory has files
+3. Verify .golem/AGENTS.md has test commands
 4. Check for remaining tasks
 
 If missing prerequisites, instruct user to run appropriate command first.
@@ -51,7 +51,7 @@ If missing prerequisites, instruct user to run appropriate command first.
 For each iteration:
 
 ### 1. Orient
-- Read the current IMPLEMENTATION_PLAN.md
+- Read the current .golem/IMPLEMENTATION_PLAN.md
 - Review relevant specs for context
 
 ### 2. Select Task
@@ -71,17 +71,17 @@ For each iteration:
 - Keep changes minimal and focused
 
 ### 5. Validate (Backpressure)
-Run ALL gates from AGENTS.md. ALL must pass:
+Run ALL gates from .golem/AGENTS.md. ALL must pass:
 
 ```bash
 # Run test command
-{test_command from AGENTS.md}
+{test_command from .golem/AGENTS.md}
 
 # Run typecheck if configured
-{typecheck_command from AGENTS.md}
+{typecheck_command from .golem/AGENTS.md}
 
 # Run lint if configured
-{lint_command from AGENTS.md}
+{lint_command from .golem/AGENTS.md}
 ```
 
 If any gate fails:
@@ -103,7 +103,7 @@ Use the code-simplifier agent principles:
 Then re-run tests to confirm no regressions.
 
 ### 7. Update Plan
-Edit `IMPLEMENTATION_PLAN.md`:
+Edit `.golem/IMPLEMENTATION_PLAN.md`:
 - Change `[ ]` to `[x]` for completed task
 - Update status counts
 - Add notes about discoveries

package/commands/golem/help.md

@@ -33,7 +33,7 @@ WORKFLOW
 
   1. /golem:spec           Define requirements through conversation
   2. exit claude
-  3. golem run plan        Generate IMPLEMENTATION_PLAN.md (headless)
+  3. golem run plan        Generate .golem/IMPLEMENTATION_PLAN.md (headless)
   4. golem run build       Start autonomous coding loop (headless)
 
 Each build iteration:
@@ -43,12 +43,12 @@ Each build iteration:
   • Simplifies code
   • Commits and loops
 
-FILES
+FILES (all in .golem/ directory)
 
-  specs/                   Requirement files (one per topic)
-  AGENTS.md               Operational commands (test, build, lint)
-  IMPLEMENTATION_PLAN.md   Task list with priorities
-  .golem/                  Configuration and prompts
+  .golem/specs/                   Requirement files (one per topic)
+  .golem/AGENTS.md               Operational commands (test, build, lint)
+  .golem/IMPLEMENTATION_PLAN.md   Task list with priorities
+  .golem/prompts/                 Configuration and prompts
 
 CLI USAGE (outside Claude)
 

package/commands/golem/plan.md

@@ -5,7 +5,7 @@ allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
 <objective>
-Analyze specs versus existing code and create/update IMPLEMENTATION_PLAN.md with prioritized tasks.
+Analyze specs versus existing code and create/update .golem/IMPLEMENTATION_PLAN.md with prioritized tasks.
 </objective>
 
 <execution_context>
@@ -15,17 +15,17 @@ Analyze specs versus existing code and create/update IMPLEMENTATION_PLAN.md with
 <context>
 Load all specs:
 ```bash
-for f in specs/*.md; do echo "=== $f ==="; cat "$f"; echo; done 2>/dev/null || echo "No specs found - run /golem:spec first"
+for f in .golem/specs/*.md; do echo "=== $f ==="; cat "$f"; echo; done 2>/dev/null || echo "No specs found - run /golem:spec first"
 ```
 
 Load operational guide:
 ```bash
-cat AGENTS.md 2>/dev/null || echo "No AGENTS.md found"
+cat .golem/AGENTS.md 2>/dev/null || echo "No AGENTS.md found"
 ```
 
 Existing plan (if any):
 ```bash
-cat IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No existing plan"
+cat .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No existing plan"
 ```
 </context>
 
@@ -33,7 +33,7 @@ cat IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No existing plan"
 
 ## 1. Read All Specs
 
-Read each file in `specs/` completely. Extract:
+Read each file in `.golem/specs/` completely. Extract:
 - Concrete requirements (must have, should have)
 - Acceptance criteria
 - Technical constraints
@@ -76,13 +76,13 @@ Order tasks by:
 
 ## 6. Write Plan
 
-Create or update `IMPLEMENTATION_PLAN.md`:
+Create or update `.golem/IMPLEMENTATION_PLAN.md`:
 
 ```markdown
 # Implementation Plan
 
 Generated: {ISO timestamp}
-Based on: specs/*.md
+Based on: .golem/specs/*.md
 
 ## Status
 - Total tasks: N
@@ -112,14 +112,14 @@ Notes: {notes}
 - [ ] Gap analysis completed
 - [ ] Tasks are atomic and testable
 - [ ] Dependencies mapped correctly
-- [ ] IMPLEMENTATION_PLAN.md written
+- [ ] .golem/IMPLEMENTATION_PLAN.md written
 - [ ] No code changes made (planning only)
 </success_criteria>
 
 <important>
 - Do NOT implement anything in planning mode
 - Do NOT modify source code
-- ONLY create/update IMPLEMENTATION_PLAN.md
+- ONLY create/update .golem/IMPLEMENTATION_PLAN.md
 - Be thorough - missing tasks cause problems later
 - Tasks should be achievable in one iteration
 </important>

package/commands/golem/status.md

@@ -21,23 +21,23 @@ echo ""
 # Specs
 echo "SPECS"
 echo "─────"
-if [ -d "specs" ]; then
-  count=$(ls -1 specs/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ -d ".golem/specs" ]; then
+  count=$(ls -1 .golem/specs/*.md 2>/dev/null | wc -l | tr -d ' ')
   echo "  Files: $count"
-  for f in specs/*.md; do
+  for f in .golem/specs/*.md; do
     [ -f "$f" ] && echo "    • $(basename "$f" .md)"
   done
 else
-  echo "  No specs/ directory - run /golem:spec"
+  echo "  No .golem/specs/ directory - run /golem:spec"
 fi
 echo ""
 
 # Plan
 echo "IMPLEMENTATION PLAN"
 echo "───────────────────"
-if [ -f "IMPLEMENTATION_PLAN.md" ]; then
-  total=$(grep -c '^\- \[' IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0")
-  done=$(grep -c '^\- \[x\]' IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0")
+if [ -f ".golem/IMPLEMENTATION_PLAN.md" ]; then
+  total=$(grep -c '^\- \[' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0")
+  done=$(grep -c '^\- \[x\]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null || echo "0")
   remaining=$((total - done))
   pct=$((done * 100 / (total > 0 ? total : 1)))
 
@@ -49,7 +49,7 @@ if [ -f "IMPLEMENTATION_PLAN.md" ]; then
 
   # Show next few tasks
   echo "  Next tasks:"
-  grep '^\- \[ \]' IMPLEMENTATION_PLAN.md 2>/dev/null | head -3 | while read line; do
+  grep '^\- \[ \]' .golem/IMPLEMENTATION_PLAN.md 2>/dev/null | head -3 | while read line; do
     echo "    $line"
   done
 else
@@ -60,12 +60,12 @@ echo ""
 # AGENTS.md
 echo "OPERATIONAL GUIDE"
 echo "─────────────────"
-if [ -f "AGENTS.md" ]; then
-  echo "  ✓ AGENTS.md exists"
-  test_cmd=$(grep -A1 '### Testing' AGENTS.md 2>/dev/null | tail -1 | tr -d '`')
+if [ -f ".golem/AGENTS.md" ]; then
+  echo "  ✓ .golem/AGENTS.md exists"
+  test_cmd=$(grep -A1 '### Testing' .golem/AGENTS.md 2>/dev/null | tail -1 | tr -d '`')
   [ -n "$test_cmd" ] && echo "  Test: $test_cmd"
 else
-  echo "  No AGENTS.md - run /golem:spec"
+  echo "  No .golem/AGENTS.md - run /golem:spec"
 fi
 echo ""
 

package/golem/agents/code-simplifier.md

@@ -41,7 +41,7 @@ You simplify code and create a single, well-documented commit that covers both t
 - `*.test.ts`, `*.spec.ts` - test files
 - `*.d.ts` - type definitions
 - `*.config.*` - configuration
-- `IMPLEMENTATION_PLAN.md` - just stage it, don't simplify
+- `.golem/IMPLEMENTATION_PLAN.md` - just stage it, don't simplify
 
 ## Commit Message Format
 
@@ -95,7 +95,7 @@ Simplified:
 
 3. Run tests to verify:
    ```bash
-   {test_command from AGENTS.md}
+   {test_command from .golem/AGENTS.md}
    ```
 
 4. Stage any simplification changes:

package/golem/prompts/PROMPT_build.md

@@ -5,13 +5,13 @@ You are in BUILD MODE. Implement ONE task from the plan, then exit.
 ## Phase 0: Orient
 
 Study these files to understand context:
-- @specs/* - All specification files
-- @AGENTS.md - Operational commands (test/build/lint)
-- @IMPLEMENTATION_PLAN.md - Current task list
+- @.golem/specs/* - All specification files
+- @.golem/AGENTS.md - Operational commands (test/build/lint)
+- @.golem/IMPLEMENTATION_PLAN.md - Current task list
 
 ## Phase 1: Select Task
 
-1. Read IMPLEMENTATION_PLAN.md
+1. Read .golem/IMPLEMENTATION_PLAN.md
 2. Pick the first incomplete task (marked `- [ ]`)
 3. Do NOT assume something is not implemented - search first
 
@@ -24,7 +24,7 @@ Study these files to understand context:
 
 ## Phase 3: Validate (Backpressure)
 
-Run commands from AGENTS.md in order. ALL must pass:
+Run commands from .golem/AGENTS.md in order. ALL must pass:
 1. Tests
 2. Type check (if configured)
 3. Lint (if configured)
@@ -33,8 +33,8 @@ If ANY fails: fix the issue, then re-run ALL validation from the beginning.
 
 ## Phase 4: Complete
 
-1. Update IMPLEMENTATION_PLAN.md - mark task `- [x]`
-2. Update AGENTS.md learnings if you discovered something useful
+1. Update .golem/IMPLEMENTATION_PLAN.md - mark task `- [x]`
+2. Update .golem/AGENTS.md learnings if you discovered something useful
 3. Commit changes with descriptive message
 4. Exit
 

package/golem/prompts/PROMPT_plan.md

@@ -1,13 +1,13 @@
 # Planning Mode
 
-You are in PLANNING MODE. Analyze specs vs existing code and create IMPLEMENTATION_PLAN.md.
+You are in PLANNING MODE. Analyze specs vs existing code and create .golem/IMPLEMENTATION_PLAN.md.
 
 ## Phase 0: Orient
 
 Study these files first:
-- @specs/* - All specification files
-- @AGENTS.md - Operational commands
-- @IMPLEMENTATION_PLAN.md - Current plan (if exists)
+- @.golem/specs/* - All specification files
+- @.golem/AGENTS.md - Operational commands
+- @.golem/IMPLEMENTATION_PLAN.md - Current plan (if exists)
 
 ## Phase 1: Gap Analysis
 
@@ -19,7 +19,7 @@ Study these files first:
 
 ## Phase 2: Create Plan
 
-Write `IMPLEMENTATION_PLAN.md` with prioritized tasks:
+Write `.golem/IMPLEMENTATION_PLAN.md` with prioritized tasks:
 
 ```markdown
 # Implementation Plan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golem-cc",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Autonomous coding loop with Claude - structured specs, ralph loop execution, code simplification",
   "bin": {
     "golem-cc": "bin/install.cjs"