@samahlstrom/forge-cli 0.1.0

package/templates/core/pipeline/decompose.md.hbs

@@ -0,0 +1,100 @@
+# Architect Agent: Task Decomposition
+
+You are the **architect agent** for Forge. Your job is to break a work item into parallel-safe subtasks organized into execution waves.
+
+## Input
+
+**Task ID:** `{{bead_id}}`
+**Title:** {{title}}
+**Description:**
+{{description}}
+
+**Risk Tier:** {{tier}}
+**Mode:** {{mode}}
+
+### Project Context
+Read these files for architectural understanding:
+{{#each context_files}}
+- `{{this}}`
+{{/each}}
+
+## Your Task
+
+Analyze the work description and produce a decomposition plan. You must output **valid JSON** matching the schema below.
+
+## Constraints
+
+1. **Max subtasks:** 8 (prefer fewer; most work needs 2-4)
+2. **Max waves:** 4 (prefer fewer)
+3. **No circular dependencies:** If A depends on B, B cannot depend on A
+4. **No file conflicts within a wave:** Two subtasks in the same wave CANNOT modify the same file
+5. **Each subtask must be independently verifiable:** It should compile/typecheck on its own after the wave completes
+6. **Respect the risk tier:**
+   - T1: Minimal decomposition needed; 1-2 subtasks is fine
+   - T2: Break along service/module boundaries
+   - T3: Isolate security-critical changes into their own subtask with explicit verification
+7. **Agent assignment:** Each subtask gets an agent type:
+   - `code` — writes implementation code
+   - `test` — writes tests
+   - `docs` — writes documentation
+   - `config` — modifies configuration files
+
+## Analysis Steps
+
+Before producing output, think through:
+
+1. **What files will be touched?** List every file that needs to change.
+2. **What are the dependency relationships?** Which changes must happen before others?
+3. **Where are the file conflicts?** Group non-conflicting changes into waves.
+4. **What is the verification for each subtask?** How do you know it worked?
+
+## Output Schema
+
+```json
+{
+  "analysis": {
+    "files_affected": ["src/lib/foo.ts", "src/routes/bar/+page.svelte"],
+    "dependency_graph": "A -> B means B depends on A",
+    "risk_notes": "Any special concerns for this tier"
+  },
+  "subtasks": [
+    {
+      "id": "sub-1",
+      "title": "Short description of the subtask",
+      "agent": "code",
+      "files": ["src/lib/foo.ts", "src/lib/foo.test.ts"],
+      "dependsOn": [],
+      "verification": "npm run check passes; foo.test.ts passes",
+      "instructions": "Detailed instructions for what the agent should do. Be specific about function signatures, data shapes, and integration points."
+    }
+  ],
+  "waves": [
+    {
+      "id": "wave-1",
+      "subtasks": ["sub-1", "sub-2"],
+      "gate": "typecheck"
+    },
+    {
+      "id": "wave-2",
+      "subtasks": ["sub-3"],
+      "gate": "typecheck + test"
+    }
+  ],
+  "verification_plan": {
+    "after_all_waves": "Full test suite, lint, typecheck",
+    "manual_checks": ["Describe any checks that need human verification"]
+  }
+}
+```
+
+## Rules for Good Decomposition
+
+- **Prefer wide waves over deep chains.** 3 subtasks in wave-1 is better than 3 sequential waves of 1 subtask each.
+- **Tests go in the same wave as the code they test** (same subtask if the file set is small, separate subtask if large).
+- **Type definitions and interfaces go in wave-1.** Downstream code depends on them.
+- **Database migrations go in their own subtask** in wave-1, before any code that uses the new schema.
+- **Each subtask's `instructions` field should be detailed enough** that an agent with no prior context can execute it. Include: what to create/modify, expected function signatures, data flow, and how it integrates with existing code.
+
+## Output
+
+Respond with **only** the JSON object. No markdown fences, no explanation, no commentary. Just the JSON.

package/templates/core/pipeline/deliver.sh.hbs

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# forge pipeline — deliver: branch, commit, push, PR
+# Generated by: forge init
+# Uses bd (steveyegge/beads) for task tracking
+set -euo pipefail
+
+FORGE_DIR=".forge"
+PROMPTS_DIR="${FORGE_DIR}/pipeline"
+
+TASK_ID="${1:-}"
+PR_BODY_FILE="${2:-}"
+
+if [[ -z "$TASK_ID" ]]; then
+  echo '{"error":"Usage: deliver.sh <task-id> [pr-body-file]"}' >&2
+  exit 1
+fi
+
+# --- Read task state from bd ---
+
+TASK_JSON=$(bd show "$TASK_ID" --json 2>/dev/null)
+TITLE=$(echo "$TASK_JSON" | jq -r '.title // "untitled"')
+DESCRIPTION=$(echo "$TASK_JSON" | jq -r '.description // ""')
+
+# Extract tier and mode from labels
+TIER=$(echo "$TASK_JSON" | jq -r '.labels[]? // empty' | grep "^tier:" | head -1 | sed 's/^tier://')
+TIER="${TIER:-T1}"
+MODE=$(echo "$TASK_JSON" | jq -r '.labels[]? // empty' | grep "^mode:" | head -1 | sed 's/^mode://')
+MODE="${MODE:-normal}"
+
+# Detect modified files from git
+MODIFIED_FILES=$(git diff --name-only HEAD 2>/dev/null || true)
+if [[ -z "$MODIFIED_FILES" ]]; then
+  MODIFIED_FILES=$(git diff --cached --name-only 2>/dev/null || true)
+fi
+if [[ -z "$MODIFIED_FILES" ]]; then
+  MODIFIED_FILES=$(git status --porcelain | grep -v '^\?' | awk '{print $2}')
+fi
+
+if [[ -z "$MODIFIED_FILES" ]]; then
+  echo '{"error":"No modified files found to deliver"}' >&2
+  exit 1
+fi
+
+# --- Generate slug from title ---
+
+slugify() {
+  echo "$1" | tr '[:upper:]' '[:lower:]' | \
+    sed 's/[^a-z0-9]/-/g' | \
+    sed 's/--*/-/g' | \
+    sed 's/^-//' | \
+    sed 's/-$//' | \
+    cut -c1-40
+}
+
+SLUG=$(slugify "$TITLE")
+BRANCH="feature/${TASK_ID}-${SLUG}"
+
+# --- Phase 1: Branch + commit + push ---
+
+if [[ -z "$PR_BODY_FILE" ]]; then
+  # Create branch
+  CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+  if [[ "$CURRENT_BRANCH" != "$BRANCH" ]]; then
+    git checkout -b "$BRANCH" 2>/dev/null || git checkout "$BRANCH" 2>/dev/null || {
+      echo "{\"error\":\"Failed to create or switch to branch ${BRANCH}\"}" >&2
+      exit 1
+    }
+  fi
+
+  # Stage files explicitly
+  while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+    if [[ -f "$file" ]]; then
+      git add "$file"
+    fi
+  done <<< "$MODIFIED_FILES"
+
+  # Build commit message
+  local_type="feat"
+  if echo "$TITLE" | grep -qiE '(fix|bug|patch|repair|correct)'; then
+    local_type="fix"
+  elif echo "$TITLE" | grep -qiE '(refactor|cleanup|reorganize)'; then
+    local_type="refactor"
+  elif echo "$TITLE" | grep -qiE '(doc|readme|comment)'; then
+    local_type="docs"
+  elif echo "$TITLE" | grep -qiE '(test|spec)'; then
+    local_type="test"
+  fi
+
+  COMMIT_MSG="${local_type}(${SLUG}): ${TITLE}
+
+Task: ${TASK_ID}
+Risk: ${TIER}"
+
+  git commit -m "$COMMIT_MSG" || {
+    echo "{\"error\":\"Commit failed\"}" >&2
+    exit 1
+  }
+
+  # Push branch
+  git push -u origin "$BRANCH" 2>/dev/null || {
+    echo "{\"error\":\"Push failed. You may need to set up remote.\"}" >&2
+    exit 1
+  }
+
+  # PAUSE: ask LLM to write PR body
+  local task_dir="${FORGE_DIR}/pipeline/runs/${TASK_ID}"
+  mkdir -p "$task_dir"
+  PR_BODY_OUTPUT="${task_dir}/pr-body.md"
+
+  jq -n \
+    --arg status "PAUSE" \
+    --arg task "write-pr-body" \
+    --arg prompt_file "${PROMPTS_DIR}/pr-body-prompt.md" \
+    --arg output_file "$PR_BODY_OUTPUT" \
+    --arg branch "$BRANCH" \
+    --arg resume "bash ${FORGE_DIR}/pipeline/deliver.sh ${TASK_ID} ${PR_BODY_OUTPUT}" \
+    --argjson context '["{{stackFile}}","{{projectFile}}"]' \
+    '{status:$status, task:$task, prompt_file:$prompt_file, output_file:$output_file, branch:$branch, context:$context, resume:$resume}'
+  exit 0
+fi
+
+# --- Phase 2: Create PR with body ---
+
+if [[ ! -f "$PR_BODY_FILE" ]]; then
+  echo "{\"error\":\"PR body file not found: ${PR_BODY_FILE}\"}" >&2
+  exit 1
+fi
+
+PR_BODY=$(cat "$PR_BODY_FILE")
+
+PR_TITLE="${TITLE}"
+if [[ ${#PR_TITLE} -gt 70 ]]; then
+  PR_TITLE=$(echo "$PR_TITLE" | cut -c1-67)"..."
+fi
+
+# Add risk badge
+RISK_BADGE=""
+case "$TIER" in
+  T1) RISK_BADGE="<!-- risk:T1 --> **Risk: T1** (Low)" ;;
+  T2) RISK_BADGE="<!-- risk:T2 --> **Risk: T2** (Moderate)" ;;
+  T3) RISK_BADGE="<!-- risk:T3 --> **Risk: T3** (Critical)" ;;
+esac
+
+FULL_BODY="${RISK_BADGE}
+
+${PR_BODY}
+
+---
+Task: \`${TASK_ID}\`"
+
+PR_URL=$(gh pr create \
+  --title "$PR_TITLE" \
+  --body "$FULL_BODY" \
+  --head "$BRANCH" 2>/dev/null) || {
+  echo "{\"error\":\"gh pr create failed. Is gh authenticated?\"}" >&2
+  exit 1
+}
+
+# Add labels based on tier
+case "$TIER" in
+  T3) gh pr edit "$PR_URL" --add-label "critical,security-review" 2>/dev/null || true ;;
+  T2) gh pr edit "$PR_URL" --add-label "needs-review" 2>/dev/null || true ;;
+esac
+
+jq -n \
+  --arg pr_url "$PR_URL" \
+  --arg branch "$BRANCH" \
+  --arg task_id "$TASK_ID" \
+  --arg tier "$TIER" \
+  '{pr_url:$pr_url, branch:$branch, task_id:$task_id, tier:$tier}'

package/templates/core/pipeline/execute.md.hbs

@@ -0,0 +1,138 @@
+# Execution Dispatcher: Wave-by-Wave Agent Orchestration
+
+You are the **execution dispatcher** for Forge. Your job is to execute a decomposition plan by launching agents wave-by-wave, verifying between waves, and tracking progress via `bd`.
+
+## Input
+
+**Task ID:** `{{bead_id}}`
+**Title:** {{title}}
+**Risk Tier:** {{tier}}
+
+### Decomposition Plan
+The decomposition is at: `{{decomposition_file}}`
+
+Read it now. It contains `subtasks[]` and `waves[]`.
+
+### Project Context
+{{#each context_files}}
+- `{{this}}`
+{{/each}}
+
+## Execution Protocol
+
+For each wave in order:
+
+### 1. Pre-Wave Setup
+
+- Read the wave definition to get the list of subtask IDs
+- For each subtask in this wave, read its `files[]`, `instructions`, and `verification`
+
+### 2. Execute Subtasks in Parallel
+
+For each subtask in the wave, launch a subagent with this context:
+
+**Subagent prompt template:**
+```
+You are a {{subtask.agent}} agent. Your task:
+
+Title: {{subtask.title}}
+
+Instructions:
+{{subtask.instructions}}
+
+Files to modify:
+{{#each subtask.files}}
+- {{this}}
+{{/each}}
+
+Verification: {{subtask.verification}}
+
+Rules:
+- Only modify the files listed above
+- Follow the project conventions in the context files
+- After making changes, verify: {{subtask.verification}}
+- If you encounter an error you cannot resolve, output:
+  {"status": "blocked", "subtask": "{{subtask.id}}", "error": "<description>"}
+```
+
+Each subagent receives:
+1. The subagent prompt above
+2. The project context files (stack.md, project.md)
+3. The agent.md file matching its agent type (if it exists)
+
+### 3. Post-Wave Verification Gate
+
+After ALL subtasks in a wave complete:
+
+1. **Run typecheck:** `{{commands.typecheck}}`
+2. **If the wave definition has `gate: "typecheck + test"`**, also run: `{{commands.test}}`
+
+### 4. Handle Failures
+
+If the verification gate fails after a wave:
+
+1. **Identify the breaking subtask:**
+   - Check which files were modified in this wave
+   - Run typecheck/test with verbose output
+   - Match errors to specific files and subtasks
+
+2. **Retry the breaking subtask:**
+   - Provide the subagent with the error output as additional context
+   - Include the failing test output or typecheck errors
+   - Limit to 2 retries per subtask
+
+3. **If retry fails after 2 attempts:**
+   - Revert the breaking subtask's file changes: `git checkout -- <files>`
+   - Continue to the next wave (the breaking subtask becomes a "deferred" item)
+   - Track deferred subtasks for the PR summary
+
+## Progress Reporting
+
+After each wave, output a progress update:
+
+```json
+{
+  "wave": "wave-1",
+  "status": "complete",
+  "subtasks_completed": ["sub-1", "sub-2"],
+  "subtasks_failed": [],
+  "subtasks_deferred": [],
+  "verification": "passed",
+  "files_modified": ["src/lib/foo.ts", "src/lib/bar.ts"]
+}
+```
+
+## Completion
+
+After all waves are done:
+
+1. Run the full verification suite:
+   - `{{commands.typecheck}}`
+   - `{{commands.lint}}`
+   - `{{commands.test}}`
+
+2. Compile the execution summary:
+
+```json
+{
+  "status": "complete",
+  "waves_executed": 2,
+  "subtasks_completed": ["sub-1", "sub-2", "sub-3"],
+  "subtasks_deferred": [],
+  "files_modified": ["list", "of", "all", "files"],
+  "verification": {
+    "typecheck": "passed",
+    "lint": "passed",
+    "test": "passed"
+  }
+}
+```
+
+3. Write the summary to: `.forge/pipeline/runs/{{bead_id}}/execution.json`
+
+## Rules
+
+- **Never skip a wave.** Execute them in order.
+- **Never modify files not listed in a subtask's `files[]` array.**
+- **If a subtask has `dependsOn` entries not in its wave, those were already completed in prior waves.** You can assume their output exists.
+- **Keep each subagent focused.** It gets only its subtask, not the full decomposition.

package/templates/core/pipeline/intake.sh.hbs

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# forge pipeline — intake: parse input and score quality
+# Generated by: forge init
+set -euo pipefail
+
+# --- Quality Scoring ---
+# Scores a work description from 0.0 to 1.0 based on:
+#   What (25%)  — Does it describe what to build/fix?
+#   Why (15%)   — Does it explain why this is needed?
+#   Where (15%) — Does it mention files, components, or areas?
+#   Scope (15%) — Is the scope bounded (not "refactor everything")?
+#   Layers (20%)— Does it mention affected layers (UI, API, DB, etc.)?
+#   Criteria (10%) — Does it include acceptance criteria or done conditions?
+
+score_quality() {
+  local desc="$1"
+  local desc_lower
+  desc_lower=$(echo "$desc" | tr '[:upper:]' '[:lower:]')
+  local total=0
+
+  # What (25 pts): presence of action verbs and object nouns
+  local what_score=0
+  if echo "$desc_lower" | grep -qE '(add|create|build|implement|fix|update|remove|delete|refactor|migrate|change|replace|move|rename|extract|split|merge)'; then
+    what_score=$((what_score + 15))
+  fi
+  if echo "$desc_lower" | grep -qE '(component|page|endpoint|api|function|service|hook|store|model|schema|table|route|handler|middleware|view|controller|module)'; then
+    what_score=$((what_score + 10))
+  fi
+  total=$((total + what_score))
+
+  # Why (15 pts): rationale keywords
+  local why_score=0
+  if echo "$desc_lower" | grep -qE '(because|so that|in order to|to enable|to fix|to prevent|to improve|to support|to allow|currently|problem|issue|bug|broken|incorrect|missing|needed)'; then
+    why_score=15
+  fi
+  total=$((total + why_score))
+
+  # Where (15 pts): file paths, component names, or area references
+  local where_score=0
+  if echo "$desc_lower" | grep -qE '(\.[a-z]{1,4}$|/[a-z]|src/|lib/|components/|pages/|routes/|api/|server/|client/|services/)'; then
+    where_score=$((where_score + 10))
+  fi
+  if echo "$desc_lower" | grep -qE '(in the|on the|at the|within|inside|under|header|footer|sidebar|navbar|modal|form|table|list|card|dashboard|settings|profile|login|signup)'; then
+    where_score=$((where_score + 5))
+  fi
+  total=$((total + where_score))
+
+  # Scope (15 pts): bounded descriptions score higher
+  local scope_score=10  # default: assume moderate scope
+  if echo "$desc_lower" | grep -qE '(all|every|entire|whole|everything|refactor the entire|rewrite)'; then
+    scope_score=0  # unbounded = bad
+  fi
+  if echo "$desc_lower" | grep -qE '(only|just|single|specific|one|the [a-z]+ (component|page|endpoint|function))'; then
+    scope_score=15  # well-bounded = good
+  fi
+  total=$((total + scope_score))
+
+  # Layers (20 pts): mentions of architectural layers
+  local layers_score=0
+  local layer_count=0
+  for layer in "ui" "frontend" "client" "backend" "server" "api" "database" "db" "schema" "migration" "state" "store" "style" "css" "test" "auth" "middleware"; do
+    if echo "$desc_lower" | grep -qw "$layer"; then
+      layer_count=$((layer_count + 1))
+    fi
+  done
+  if [[ $layer_count -ge 3 ]]; then
+    layers_score=20
+  elif [[ $layer_count -ge 2 ]]; then
+    layers_score=15
+  elif [[ $layer_count -ge 1 ]]; then
+    layers_score=10
+  fi
+  total=$((total + layers_score))
+
+  # Criteria (10 pts): acceptance criteria or done conditions
+  local criteria_score=0
+  if echo "$desc_lower" | grep -qE '(should|must|expect|when .* then|given .* when|acceptance|criteria|done when|verify that|ensure that|assert)'; then
+    criteria_score=10
+  fi
+  total=$((total + criteria_score))
+
+  # Normalize to 0.0-1.0
+  echo "scale=2; $total / 100" | bc | sed 's/^\./0./'
+}
+
+# --- Input Parsing ---
+
+MODE="normal"
+SOURCE="text"
+ISSUE_NUMBER=""
+DESCRIPTION=""
+TITLE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --quick)
+      MODE="quick"; shift ;;
+    --hotfix)
+      MODE="hotfix"; shift ;;
+    --issue)
+      ISSUE_NUMBER="$2"; SOURCE="issue"; shift 2 ;;
+    *)
+      if [[ -z "$DESCRIPTION" ]]; then
+        DESCRIPTION="$1"
+      else
+        DESCRIPTION="${DESCRIPTION} $1"
+      fi
+      shift ;;
+  esac
+done
+
+# Fetch from GitHub issue if --issue
+if [[ "$SOURCE" == "issue" && -n "$ISSUE_NUMBER" ]]; then
+  if ! command -v gh &>/dev/null; then
+    echo '{"error":"gh CLI not installed, cannot fetch issue"}' >&2
+    exit 1
+  fi
+
+  issue_json=$(gh issue view "$ISSUE_NUMBER" --json title,body 2>/dev/null) || {
+    echo '{"error":"Failed to fetch issue '"$ISSUE_NUMBER"'"}' >&2
+    exit 1
+  }
+
+  TITLE=$(echo "$issue_json" | jq -r '.title // ""')
+  issue_body=$(echo "$issue_json" | jq -r '.body // ""')
+  DESCRIPTION="${TITLE}. ${issue_body}"
+fi
+
+if [[ -z "$DESCRIPTION" ]]; then
+  echo '{"error":"No work description provided. Usage: forge work \"<description>\" | --issue N"}' >&2
+  exit 1
+fi
+
+# Generate title from description if not set
+if [[ -z "$TITLE" ]]; then
+  # Take first sentence or first 80 chars
+  TITLE=$(echo "$DESCRIPTION" | head -1 | cut -c1-80)
+  # Remove trailing period if present
+  TITLE="${TITLE%.}"
+fi
+
+# Score quality
+QUALITY_SCORE=$(score_quality "$DESCRIPTION")
+
+# Output JSON result
+jq -n \
+  --arg title "$TITLE" \
+  --arg description "$DESCRIPTION" \
+  --arg source "$SOURCE" \
+  --arg mode "$MODE" \
+  --arg quality_score "$QUALITY_SCORE" \
+  '{title:$title, description:$description, source:$source, mode:$mode, quality_score:($quality_score | tonumber)}'