forge-pipeline 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# Forge
+
+Autonomous multi-agent coding pipeline. Give it a task, walk away, come back to finished code.
+
+## Quick Start
+
+```bash
+# Clone and set up
+git clone <repo-url> ~/forge
+chmod +x ~/forge/forge
+export PATH="$HOME/forge:$PATH"  # Add to your shell profile
+
+# Initialize a new project
+forge init my-project
+cd my-project
+forge start "Build a REST API with user authentication"
+
+# Or use with an existing project
+cd my-existing-project
+forge init
+forge start "Add rate limiting to all API endpoints"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `forge init [name]` | Initialize a project (creates git repo if needed) |
+| `forge start "task"` | Run the full autonomous pipeline |
+| `forge run "task"` | Alias for start |
+| `forge status` | Show current phase and active agents |
+| `forge logs [agent]` | View agent logs |
+| `forge abort` | Kill all running agents |
+| `forge clean` | Remove .forge/ directory and temp branches |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--max-workers N` | 4 | Max parallel workers per lead |
+| `--max-leads N` | 4 | Max parallel leads |
+| `--audit-rounds N` | 2 | Max audit-fix cycles |
+| `--timeout N` | 60 | Timeout in minutes |
+| `--dry-run` | - | Only run spec + planning phases |
+| `--verbose` | - | Show real-time output |
+
+## How It Works
+
+Forge runs 7 phases automatically:
+
+0. **Spec** — Architect writes spec, Challenger reviews it (up to 3 rounds)
+1. **Plan** — Coordinator decomposes spec into parallel work units
+2. **Implement** — Lead agents spawn Worker agents in isolated git worktrees
+3. **Integrate** — All branches merged, conflicts resolved, tests run
+4. **Audit** — Senior auditor spawns junior auditors for security, quality, testing review
+5. **Fix** — Audit findings routed back for fixes (up to 2 rounds)
+6. **Finalize** — Merge to main, generate summary report
+
+## Requirements
+
+- `git` — version control
+- `tmux` — session management for parallel agents
+- `claude` — [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- `jq` — JSON processing
+
+## Optional
+
+- **Augment codebase-retrieval** — Semantic code search for better results. Auto-detected if configured.

package/forge

@@ -0,0 +1,593 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+###############################################################################
+# FORGE — Autonomous Coding Pipeline
+# Main CLI entry point
+###############################################################################
+
+# Determine installation directory (resolve symlinks for npm global installs)
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+FORGE_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+
+# Source all libraries
+source "$FORGE_DIR/lib/utils.sh"
+source "$FORGE_DIR/lib/agent.sh"
+source "$FORGE_DIR/lib/worktree.sh"
+source "$FORGE_DIR/lib/prompts.sh"
+source "$FORGE_DIR/lib/phases/00_spec.sh"
+source "$FORGE_DIR/lib/phases/01_plan.sh"
+source "$FORGE_DIR/lib/phases/02_implement.sh"
+source "$FORGE_DIR/lib/phases/03_integrate.sh"
+source "$FORGE_DIR/lib/phases/04_audit.sh"
+source "$FORGE_DIR/lib/phases/05_fix.sh"
+source "$FORGE_DIR/lib/phases/06_finalize.sh"
+
+###############################################################################
+# Default configuration
+###############################################################################
+MAX_WORKERS=4
+MAX_LEADS=4
+AUDIT_ROUNDS=2
+TIMEOUT_MINUTES=60
+DRY_RUN=false
+VERBOSE=false
+AUTO_APPROVE=false
+FORGE_TIMEOUT=$((TIMEOUT_MINUTES * 60))
+FORGE_START=$(date +%s)
+AGENT_COUNT=0
+MAX_TOTAL_AGENTS=30
+
+export MAX_WORKERS MAX_LEADS AUDIT_ROUNDS TIMEOUT_MINUTES DRY_RUN VERBOSE
+export FORGE_TIMEOUT FORGE_START AGENT_COUNT MAX_TOTAL_AGENTS FORGE_DIR
+
+###############################################################################
+# Usage
+###############################################################################
+show_usage() {
+  cat <<'EOF'
+Usage:
+  forge init [project-name]        Initialize a project for forge
+  forge start <task description>   Run the full pipeline
+  forge run <task description>     Alias for start
+  forge status                     Show current phase and active agents
+  forge logs [agent-name]          Tail an agent's log
+  forge abort                      Kill all agents and cleanup
+  forge clean                      Remove .forge/ directory and branches
+
+Options:
+  --auto                   Skip approval gate, fully autonomous
+  --max-workers N          Max parallel workers per lead (default: 4)
+  --max-leads N            Max parallel leads (default: 4)
+  --audit-rounds N         Max audit-fix cycles (default: 2)
+  --timeout MINUTES        Kill everything after this long (default: 60)
+  --dry-run                Only run spec + planning phases
+  --verbose                Show real-time agent output
+  --help, -h               Show this help
+
+Examples:
+  forge init my-app
+  forge start Add user authentication with JWT
+  forge start Refactor the payment module to use Stripe
+  forge --auto start Build a REST API with CRUD endpoints
+EOF
+}
+
+###############################################################################
+# Preflight check
+###############################################################################
+preflight_check() {
+  local skip_git_check="${1:-false}"
+  local missing=()
+
+  # Check required tools
+  command -v git   >/dev/null 2>&1 || missing+=("git")
+  command -v tmux  >/dev/null 2>&1 || missing+=("tmux")
+  command -v claude >/dev/null 2>&1 || missing+=("claude")
+  command -v jq   >/dev/null 2>&1 || missing+=("jq")
+
+  if [ ${#missing[@]} -gt 0 ]; then
+    log_error "Missing required tools: ${missing[*]}"
+    log_error "Please install them before running forge."
+    exit 1
+  fi
+
+  # Check we're in a git repo (unless caller says to skip)
+  if [ "$skip_git_check" != "true" ]; then
+    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      log_error "Not inside a git repository. Run 'forge init' first."
+      exit 1
+    fi
+  fi
+
+  # Detect Augment MCP tool
+  AUGMENT_AVAILABLE=false
+  AUGMENT_TOOL_NAME=""
+
+  local augment_line
+  augment_line="$(claude mcp list 2>/dev/null | grep -i "augment\|auggie\|codebase-retrieval" | head -1 || true)"
+
+  if [ -n "$augment_line" ]; then
+    AUGMENT_AVAILABLE=true
+    AUGMENT_TOOL_NAME="$(echo "$augment_line" | awk '{print $1}')"
+  fi
+
+  export AUGMENT_AVAILABLE AUGMENT_TOOL_NAME
+
+  # Ensure .forge directory exists
+  local forge_root
+  forge_root="$(get_forge_root)"
+  mkdir -p "$forge_root/.forge"
+
+  # Save config
+  cat > "$forge_root/.forge/config.json" <<CONF
+{
+  "max_workers": $MAX_WORKERS,
+  "max_leads": $MAX_LEADS,
+  "audit_rounds": $AUDIT_ROUNDS,
+  "timeout_minutes": $TIMEOUT_MINUTES,
+  "dry_run": $DRY_RUN,
+  "verbose": $VERBOSE,
+  "auto_approve": $AUTO_APPROVE,
+  "augment_available": $AUGMENT_AVAILABLE,
+  "augment_tool_name": "$AUGMENT_TOOL_NAME",
+  "max_total_agents": $MAX_TOTAL_AGENTS,
+  "started_at": $FORGE_START
+}
+CONF
+
+  log_info "Preflight check passed."
+}
+
+###############################################################################
+# Global timeout checker
+###############################################################################
+check_global_timeout() {
+  local now elapsed_minutes
+  now=$(date +%s)
+  elapsed_minutes=$(( (now - FORGE_START) / 60 ))
+
+  if [ "$elapsed_minutes" -ge "$TIMEOUT_MINUTES" ]; then
+    log_error "Global timeout reached (${TIMEOUT_MINUTES} minutes). Aborting all agents."
+    forge_abort
+    exit 1
+  fi
+}
+
+###############################################################################
+# Init command (idempotent)
+###############################################################################
+forge_init() {
+  local project_name="${1:-}"
+
+  # If project name given, create directory and cd into it
+  if [ -n "$project_name" ]; then
+    mkdir -p "$project_name"
+    cd "$project_name"
+  fi
+
+  # If not already a git repo, initialize one
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git init
+    git commit --allow-empty -m "Initial commit"
+    log_info "Initialized git repository."
+  else
+    log_info "Git repository already exists."
+  fi
+
+  # Add .forge/ to .gitignore (idempotent — skip if already present)
+  if [ -f .gitignore ] && grep -qxF '.forge/' .gitignore 2>/dev/null; then
+    log_info ".forge/ already in .gitignore."
+  else
+    echo '.forge/' >> .gitignore
+    git add .gitignore
+    if ! git diff --cached --quiet 2>/dev/null; then
+      git commit -m "Update gitignore"
+    fi
+    log_info "Added .forge/ to .gitignore."
+  fi
+
+  # Run preflight (skip git check since we just ensured it)
+  preflight_check "true"
+
+  log_success "Forge initialized. Run: forge start <your task>"
+}
+
+###############################################################################
+# Approval gate — shows plan summary and asks user to confirm
+###############################################################################
+show_plan_summary() {
+  local forge_root="$1"
+
+  echo ""
+  printf "${BOLD}${CYAN}═══════════════════════════════════════${RESET}\n"
+  printf "${BOLD}${CYAN}  PLAN REVIEW${RESET}\n"
+  printf "${BOLD}${CYAN}═══════════════════════════════════════${RESET}\n"
+  echo ""
+
+  # Show leads and workers summary from plan.json
+  local plan_file="$forge_root/.forge/plan.json"
+  local total_leads
+  total_leads="$(jq -r '.leads | length' "$plan_file" 2>/dev/null || echo 0)"
+
+  echo "Leads: $total_leads"
+  echo ""
+
+  local i=0
+  while [ "$i" -lt "$total_leads" ]; do
+    local lead_name lead_module workers_count
+    lead_name="$(jq -r ".leads[$i].name" "$plan_file")"
+    lead_module="$(jq -r ".leads[$i].module // .leads[$i].name" "$plan_file")"
+    workers_count="$(jq -r ".leads[$i].workers | length" "$plan_file")"
+
+    printf "  ${BOLD}%s${RESET} (%s workers)\n" "$lead_module" "$workers_count"
+
+    local j=0
+    while [ "$j" -lt "$workers_count" ]; do
+      local worker_name worker_task
+      worker_name="$(jq -r ".leads[$i].workers[$j].name // .leads[$i].workers[$j].id" "$plan_file")"
+      worker_task="$(jq -r ".leads[$i].workers[$j].task // .leads[$i].workers[$j].task_description" "$plan_file" | head -c 80)"
+      printf "    - %s: %s\n" "$worker_name" "$worker_task"
+      j=$((j + 1))
+    done
+    echo ""
+    i=$((i + 1))
+  done
+
+  echo "Full spec:  .forge/spec/spec.md"
+  echo "Full plan:  .forge/plan.json"
+  echo ""
+}
+
+wait_for_approval() {
+  printf "${BOLD}${YELLOW}Approve this plan and start implementation? [Y/n] ${RESET}"
+  local answer
+  read -r answer </dev/tty
+  case "$answer" in
+    n|N|no|No|NO)
+      log_info "Aborted. Edit .forge/spec/spec.md or .forge/plan.json, then run 'forge start' again."
+      exit 0
+      ;;
+    *)
+      log_success "Plan approved. Starting autonomous execution..."
+      echo ""
+      ;;
+  esac
+}
+
+###############################################################################
+# Status command
+###############################################################################
+forge_status() {
+  local forge_root
+  forge_root="$(get_forge_root)"
+
+  echo ""
+  echo "=== Forge Status ==="
+  echo ""
+
+  # Determine current phase
+  if [ -f "$forge_root/.forge/status/finalize.done" ]; then
+    echo "Phase: COMPLETE"
+  elif [ -f "$forge_root/.forge/status/fix.done" ]; then
+    echo "Phase: Post-fix (audit/fix cycles)"
+  elif [ -f "$forge_root/.forge/status/audit.done" ]; then
+    echo "Phase: Audit complete"
+  elif [ -f "$forge_root/.forge/status/integrate.done" ]; then
+    echo "Phase: Integration complete"
+  elif [ -f "$forge_root/.forge/status/implement.done" ]; then
+    echo "Phase: Implementation complete"
+  elif [ -f "$forge_root/.forge/status/plan.done" ]; then
+    echo "Phase: Planning complete"
+  elif [ -f "$forge_root/.forge/status/spec.done" ]; then
+    echo "Phase: Spec complete"
+  else
+    echo "Phase: Not started or in progress"
+  fi
+
+  echo ""
+
+  # List active tmux sessions
+  echo "Active forge sessions:"
+  local sessions
+  sessions="$(tmux list-sessions 2>/dev/null | grep "^forge-" || true)"
+  if [ -n "$sessions" ]; then
+    echo "$sessions"
+  else
+    echo "  (none)"
+  fi
+
+  echo ""
+
+  # Show agent counts
+  local expected=0 done=0
+  if [ -d "$forge_root/.forge/status" ]; then
+    expected=$(find "$forge_root/.forge/status" -name "*.expected" 2>/dev/null | wc -l | tr -d ' ')
+    done=$(find "$forge_root/.forge/status" -name "*.done" 2>/dev/null | wc -l | tr -d ' ')
+  fi
+  echo "Agents: $done / $expected completed"
+  echo ""
+}
+
+###############################################################################
+# Logs command
+###############################################################################
+forge_logs() {
+  local agent_name="${1:-}"
+  local forge_root
+  forge_root="$(get_forge_root)"
+  local log_dir="$forge_root/.forge/logs"
+
+  if [ ! -d "$log_dir" ]; then
+    log_warn "No log directory found at $log_dir"
+    return 0
+  fi
+
+  if [ -n "$agent_name" ]; then
+    local log_file="$log_dir/${agent_name}.log"
+    if [ -f "$log_file" ]; then
+      tail -f "$log_file"
+    else
+      log_error "Log file not found: $log_file"
+      echo "Available logs:"
+      ls -1 "$log_dir"/*.log 2>/dev/null || echo "  (none)"
+    fi
+  else
+    echo "Available log files:"
+    ls -1 "$log_dir"/*.log 2>/dev/null || echo "  (none)"
+  fi
+}
+
+###############################################################################
+# Abort command
+###############################################################################
+forge_abort() {
+  log_warn "Aborting all forge agents..."
+
+  local sessions
+  sessions="$(tmux list-sessions 2>/dev/null | grep "^forge-" | cut -d: -f1 || true)"
+  if [ -n "$sessions" ]; then
+    while IFS= read -r session; do
+      tmux kill-session -t "$session" 2>/dev/null || true
+      log_info "Killed session: $session"
+    done <<< "$sessions"
+  else
+    log_info "No active forge sessions found."
+  fi
+
+  log_warn "All forge agents aborted."
+}
+
+###############################################################################
+# Clean command
+###############################################################################
+forge_clean() {
+  local forge_root
+  forge_root="$(get_forge_root)"
+
+  forge_abort
+
+  if [ -d "$forge_root/.forge" ]; then
+    rm -rf "$forge_root/.forge"
+    log_info "Removed .forge directory."
+  fi
+
+  local worktrees
+  worktrees="$(git worktree list --porcelain 2>/dev/null | grep "^worktree " | grep "forge" | sed 's/^worktree //' || true)"
+  if [ -n "$worktrees" ]; then
+    while IFS= read -r wt; do
+      git worktree remove --force "$wt" 2>/dev/null || true
+    done <<< "$worktrees"
+  fi
+
+  git worktree prune 2>/dev/null || true
+  log_success "Forge workspace cleaned."
+}
+
+###############################################################################
+# Argument parsing
+#
+# Handles three styles:
+#   forge start Add user auth with JWT      (all args after "start" = prompt)
+#   forge Add user auth with JWT            (all non-option args = prompt)
+#   forge --auto start Build me an app      (options before subcommand)
+###############################################################################
+USER_PROMPT=""
+SUBCOMMAND=""
+INIT_PROJECT=""
+LOGS_AGENT=""
+PROMPT_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --max-workers)
+      MAX_WORKERS="$2"; shift 2 ;;
+    --max-leads)
+      MAX_LEADS="$2"; shift 2 ;;
+    --audit-rounds)
+      AUDIT_ROUNDS="$2"; shift 2 ;;
+    --timeout)
+      TIMEOUT_MINUTES="$2"
+      FORGE_TIMEOUT=$((TIMEOUT_MINUTES * 60))
+      shift 2 ;;
+    --dry-run)
+      DRY_RUN=true; shift ;;
+    --verbose)
+      VERBOSE=true; shift ;;
+    --auto)
+      AUTO_APPROVE=true; shift ;;
+    --help|-h)
+      show_usage; exit 0 ;;
+    init)
+      SUBCOMMAND="init"
+      shift
+      # Everything after init is the project name (just first arg)
+      INIT_PROJECT="${1:-}"
+      [ -n "$INIT_PROJECT" ] && shift
+      break
+      ;;
+    start|run)
+      SUBCOMMAND="$1"
+      shift
+      # Everything remaining is the prompt
+      PROMPT_ARGS+=("$@")
+      break
+      ;;
+    status)
+      SUBCOMMAND="status"; shift; break ;;
+    logs)
+      SUBCOMMAND="logs"; shift
+      LOGS_AGENT="${1:-}"
+      [ -n "$LOGS_AGENT" ] && shift
+      break
+      ;;
+    abort)
+      SUBCOMMAND="abort"; shift; break ;;
+    clean)
+      SUBCOMMAND="clean"; shift; break ;;
+    -*)
+      log_error "Unknown option: $1"
+      show_usage; exit 1 ;;
+    *)
+      # No subcommand — collect everything as prompt args
+      PROMPT_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Join prompt args into a single string
+if [ ${#PROMPT_ARGS[@]} -gt 0 ]; then
+  USER_PROMPT="${PROMPT_ARGS[*]}"
+fi
+
+# Re-export updated values after argument parsing
+export MAX_WORKERS MAX_LEADS AUDIT_ROUNDS TIMEOUT_MINUTES DRY_RUN VERBOSE
+export FORGE_TIMEOUT AUTO_APPROVE
+
+###############################################################################
+# Main pipeline
+###############################################################################
+run_pipeline() {
+  local user_prompt="$1"
+  local truncated_prompt="${user_prompt:0:72}"
+
+  echo ""
+  printf "${BOLD}═══════════════════════════════════════${RESET}\n"
+  printf "${BOLD}  FORGE${RESET}\n"
+  printf "  ${truncated_prompt}\n"
+  printf "${BOLD}═══════════════════════════════════════${RESET}\n"
+  echo ""
+
+  # Initialize
+  FORGE_ROOT="$(get_forge_root)"
+  export FORGE_ROOT
+
+  mkdir -p "$FORGE_ROOT/.forge/status"
+  mkdir -p "$FORGE_ROOT/.forge/logs"
+
+  # Preflight
+  preflight_check
+
+  # Phase 0: Spec Creation
+  run_phase_spec "$user_prompt" || { log_error "Phase 0 failed"; exit 1; }
+  check_global_timeout
+
+  # Phase 1: Planning
+  run_phase_plan || { log_error "Phase 1 failed"; exit 1; }
+  check_global_timeout
+
+  # Dry run stops here
+  if [ "$DRY_RUN" = true ]; then
+    log_success "Dry run complete. Check .forge/spec/spec.md and .forge/plan.json"
+    exit 0
+  fi
+
+  # ── Approval gate ─────────────────────────────────────────────
+  if [ "$AUTO_APPROVE" = true ]; then
+    log_info "Auto-approve enabled, skipping review."
+  else
+    show_plan_summary "$FORGE_ROOT"
+    wait_for_approval
+  fi
+
+  # ── From here on, fully autonomous ────────────────────────────
+
+  # Phase 2: Implementation
+  run_phase_implement || { log_error "Phase 2 failed"; exit 1; }
+  check_global_timeout
+
+  # Phase 3: Integration
+  run_phase_integrate || { log_error "Phase 3 failed"; exit 1; }
+  check_global_timeout
+
+  # Phase 4-5: Audit + Fix cycles
+  for round in $(seq 1 "$AUDIT_ROUNDS"); do
+    run_phase_audit "$round" || { log_warn "Audit round $round had issues"; }
+    check_global_timeout
+
+    local critical_count warning_count
+    critical_count=$(jq '[.findings[] | select(.severity == "critical")] | length' \
+      "$FORGE_ROOT/.forge/audit/consolidated-audit.json" 2>/dev/null || echo "0")
+    warning_count=$(jq '[.findings[] | select(.severity == "warning")] | length' \
+      "$FORGE_ROOT/.forge/audit/consolidated-audit.json" 2>/dev/null || echo "0")
+
+    if [ "$critical_count" -eq 0 ] && [ "$warning_count" -eq 0 ]; then
+      log_success "Clean audit in round $round"
+      break
+    fi
+
+    run_phase_fix "$round" || { log_warn "Fix round $round had issues"; }
+    check_global_timeout
+  done
+
+  # Phase 6: Finalize
+  run_phase_finalize "$user_prompt" || { log_error "Phase 6 failed"; exit 1; }
+
+  log_success "Done. Read .forge/DONE.md"
+}
+
+###############################################################################
+# Entry point
+###############################################################################
+
+# No arguments at all → show help
+if [ -z "${SUBCOMMAND:-}" ] && [ -z "${USER_PROMPT:-}" ]; then
+  show_usage
+  exit 0
+fi
+
+# Dispatch subcommands
+case "${SUBCOMMAND:-}" in
+  init)
+    forge_init "${INIT_PROJECT:-}"
+    ;;
+  status)
+    forge_status
+    ;;
+  logs)
+    forge_logs "${LOGS_AGENT:-}"
+    ;;
+  abort)
+    forge_abort
+    ;;
+  clean)
+    forge_clean
+    ;;
+  start|run)
+    if [ -z "${USER_PROMPT:-}" ]; then
+      log_error "No task provided. Usage: forge start <your task description>"
+      exit 1
+    fi
+    run_pipeline "$USER_PROMPT"
+    ;;
+  "")
+    # No subcommand — bare prompt
+    run_pipeline "$USER_PROMPT"
+    ;;
+esac