autonomous-coding-toolkit 1.0.0

package/scripts/prior-art-search.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# prior-art-search.sh — Search GitHub and local codebase for prior art
+#
+# Usage: prior-art-search.sh [--dry-run] [--local-only] [--github-only] <query>
+#
+# Searches:
+#   1. GitHub repos (gh search repos)
+#   2. GitHub code (gh search code)
+#   3. Local ~/Documents/projects/ (grep -r)
+#
+# Output: Ranked results with source, relevance, and URL/path
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+
+DRY_RUN=false
+LOCAL_ONLY=false
+GITHUB_ONLY=false
+QUERY=""
+MAX_RESULTS=10
+PROJECTS_DIR="${PROJECTS_DIR:-$HOME/Documents/projects}"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --dry-run) DRY_RUN=true; shift ;;
+        --local-only) LOCAL_ONLY=true; shift ;;
+        --github-only) GITHUB_ONLY=true; shift ;;
+        --max-results) MAX_RESULTS="$2"; shift 2 ;;
+        --projects-dir) PROJECTS_DIR="$2"; shift 2 ;;
+        -h|--help)
+            cat <<'USAGE'
+prior-art-search.sh — Search for prior art before building
+
+Usage: prior-art-search.sh [OPTIONS] <query>
+
+Options:
+  --dry-run          Show what would be searched without executing
+  --local-only       Only search local projects
+  --github-only      Only search GitHub
+  --max-results N    Max results per source (default: 10)
+  --projects-dir P   Local projects directory
+
+Output: Results ranked by relevance with source attribution
+USAGE
+            exit 0
+            ;;
+        -*) echo "Unknown option: $1" >&2; exit 1 ;;
+        *) QUERY="$1"; shift ;;
+    esac
+done
+
+if [[ -z "$QUERY" ]]; then
+    echo "Error: Query required" >&2
+    echo "Usage: prior-art-search.sh <query>" >&2
+    exit 1
+fi
+
+echo "=== Prior Art Search ==="
+echo "Search query: $QUERY"
+echo ""
+
+if [[ "$DRY_RUN" == true ]]; then
+    echo "[dry-run] Would search:"
+    [[ "$LOCAL_ONLY" != true ]] && echo "  - GitHub repos: gh search repos '$QUERY' --limit $MAX_RESULTS"
+    [[ "$LOCAL_ONLY" != true ]] && echo "  - GitHub code: gh search code '$QUERY' --limit $MAX_RESULTS"
+    [[ "$GITHUB_ONLY" != true ]] && echo "  - Local projects: grep -rl in $PROJECTS_DIR"
+    if command -v ast-grep >/dev/null 2>&1; then
+        echo "  - Structural code search (ast-grep): scan with built-in patterns"
+    else
+        echo "  - Structural code search (ast-grep): not installed — would skip"
+    fi
+    exit 0
+fi
+
+# Search 1: GitHub repos
+if [[ "$LOCAL_ONLY" != true ]]; then
+    echo "--- GitHub Repos ---"
+    if command -v gh >/dev/null 2>&1; then
+        gh search repos "$QUERY" --limit "$MAX_RESULTS" --json name,url,description,stargazersCount \
+            --jq '.[] | "★ \(.stargazersCount) | \(.name) — \(.description // "no description") | \(.url)"' \
+            2>/dev/null || echo "  (GitHub search unavailable)"
+    else
+        echo "  gh CLI not installed — skipping"
+    fi
+    echo ""
+
+    echo "--- GitHub Code ---"
+    if command -v gh >/dev/null 2>&1; then
+        gh search code "$QUERY" --limit "$MAX_RESULTS" --json repository,path \
+            --jq '.[] | "\(.repository.nameWithOwner)/\(.path)"' \
+            2>/dev/null || echo "  (GitHub code search unavailable)"
+    else
+        echo "  gh CLI not installed — skipping"
+    fi
+    echo ""
+fi
+
+# Search 2: Local projects
+if [[ "$GITHUB_ONLY" != true ]]; then
+    echo "--- Local Projects ---"
+    if [[ -d "$PROJECTS_DIR" ]]; then
+        grep -rl --include='*.py' --include='*.sh' --include='*.ts' --include='*.js' \
+            "$QUERY" "$PROJECTS_DIR" 2>/dev/null | head -"$MAX_RESULTS" || echo "  No local matches"
+    else
+        echo "  Projects directory not found: $PROJECTS_DIR"
+    fi
+    echo ""
+fi
+
+# Search 3: Structural code search (ast-grep)
+if command -v ast-grep >/dev/null 2>&1; then
+    echo "--- Structural Code Search (ast-grep) ---"
+    PATTERNS_DIR="$SCRIPT_DIR/patterns"
+    if [[ -d "$PATTERNS_DIR" ]]; then
+        for pattern_file in "$PATTERNS_DIR"/*.yml; do
+            [[ -f "$pattern_file" ]] || continue
+            pattern_name=$(basename "$pattern_file" .yml)
+            matches=$(ast-grep scan --rule "$pattern_file" . 2>/dev/null | head -5 || true)
+            if [[ -n "$matches" ]]; then
+                echo "  Pattern '$pattern_name': $(echo "$matches" | wc -l) matches"
+            fi
+        done
+    fi
+    echo ""
+else
+    echo "--- Structural Code Search ---"
+    echo "  ast-grep not installed — skipping structural analysis"
+    echo "  Install: npm i -g @ast-grep/cli"
+    echo ""
+fi
+
+echo "=== Search Complete ==="

package/scripts/promote-mab-lessons.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# promote-mab-lessons.sh — Auto-promote MAB patterns with sufficient occurrences to docs/lessons/
+#
+# Usage: promote-mab-lessons.sh [--worktree <dir>] [--min-occurrences N] [--dry-run] [--help]
+set -euo pipefail
+
+WORKTREE="."
+MIN_OCCURRENCES=3
+DRY_RUN=false
+
+usage() {
+    cat <<'USAGE'
+promote-mab-lessons.sh — Promote recurring MAB patterns to lesson files
+
+Usage: promote-mab-lessons.sh [--worktree <dir>] [--min-occurrences N] [--dry-run] [--help]
+
+Options:
+  --worktree <dir>       Project root (default: .)
+  --min-occurrences N    Minimum occurrences to promote (default: 3)
+  --dry-run              Show what would be promoted without creating files
+  -h, --help             Show this help
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help) usage; exit 0 ;;
+        --worktree) WORKTREE="$2"; shift 2 ;;
+        --min-occurrences) MIN_OCCURRENCES="$2"; shift 2 ;;
+        --dry-run) DRY_RUN=true; shift ;;
+        *) echo "ERROR: Unknown option: $1" >&2; exit 1 ;;
+    esac
+done
+
+LESSONS_FILE="$WORKTREE/logs/mab-lessons.json"
+LESSONS_DIR="$WORKTREE/docs/lessons"
+
+if [[ ! -f "$LESSONS_FILE" ]]; then
+    echo "No mab-lessons.json found at $LESSONS_FILE"
+    exit 0
+fi
+
+# Find next lesson number
+next_num() {
+    local existing
+    existing=$(find "$LESSONS_DIR" -maxdepth 1 -name '*.md' 2>/dev/null \
+        | sed 's/.*\///; s/-.*//' \
+        | grep -E '^[0-9]+$' \
+        | sort -n \
+        | tail -1 || echo "0")
+    echo $((existing + 1))
+}
+
+# Slugify a pattern string
+slugify() {
+    echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//' | cut -c1-50
+}
+
+promoted=0
+
+# Read eligible patterns (not yet promoted, >= threshold)
+while IFS= read -r line; do
+    pattern=$(echo "$line" | jq -r '.pattern')
+    context=$(echo "$line" | jq -r '.context // "general"')
+    winner=$(echo "$line" | jq -r '.winner // "unknown"')
+    occurrences=$(echo "$line" | jq -r '.occurrences // 0')
+
+    if [[ "$DRY_RUN" == true ]]; then
+        echo "  Would promote: \"$pattern\" ($occurrences occurrences, context=$context)"
+        promoted=$((promoted + 1))
+        continue
+    fi
+
+    # Create lesson file
+    mkdir -p "$LESSONS_DIR"
+    num=$(next_num)
+    slug=$(slugify "$pattern")
+    filename=$(printf "%04d-%s.md" "$num" "$slug")
+
+    promoted_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    # Use printf to avoid shell expansion of LLM-sourced variables (security)
+    printf '%s\n' \
+        "---" \
+        "pattern: \"$pattern\"" \
+        "context: $context" \
+        "winning_strategy: $winner" \
+        "occurrences: $occurrences" \
+        "source: mab-auto-promoted" \
+        "promoted_at: $promoted_at" \
+        "---" \
+        "" \
+        "# $pattern" \
+        "" \
+        "**Context:** $context batch type" \
+        "**Winning strategy:** $winner" \
+        "**Occurrences:** $occurrences competing runs" \
+        "" \
+        "## Description" \
+        "" \
+        "This pattern was automatically promoted from MAB competing agent runs." \
+        "The $winner strategy consistently produced better results when this" \
+        "pattern was followed." \
+        "" \
+        "## Recommendation" \
+        "" \
+        "Apply this pattern when working on $context batches." \
+        > "$LESSONS_DIR/$filename"
+
+    echo "  Promoted: $filename"
+    promoted=$((promoted + 1))
+
+    # Mark as promoted in JSON
+    tmp=$(mktemp)
+    jq --arg p "$pattern" \
+        '[.[] | if .pattern == $p then .promoted = true else . end]' \
+        "$LESSONS_FILE" > "$tmp" && mv "$tmp" "$LESSONS_FILE"
+
+done < <(jq -c --argjson min "$MIN_OCCURRENCES" \
+    '.[] | select(.promoted != true and .occurrences >= $min)' \
+    "$LESSONS_FILE" 2>/dev/null)
+
+echo ""
+echo "Promoted $promoted patterns"
+if [[ "$DRY_RUN" == true ]]; then
+    echo "(dry run — no files created)"
+fi

package/scripts/prompts/agent-a-superpowers.md

@@ -0,0 +1,29 @@
+# Agent A: Superpowers Strategy
+
+You are executing a work unit using the **superpowers methodology** — disciplined skill invocation, TDD, systematic debugging, and verification before completion claims.
+
+## Work Unit
+
+{WORK_UNIT_DESCRIPTION}
+
+## Context
+
+- **PRD:** {PRD_PATH}
+- **Architecture Map:** {ARCH_MAP_PATH}
+- **Quality Gate:** `{QUALITY_GATE_CMD}`
+
+## MAB Lessons (from prior competing runs)
+
+{MAB_LESSONS}
+
+## Instructions
+
+1. **Invoke skills before acting.** Check if brainstorming, TDD, or systematic-debugging applies. Follow skill discipline exactly.
+2. **TDD cycle:** Write failing tests first, then implement to make them pass, then refactor.
+3. **Quality gate:** Run `{QUALITY_GATE_CMD}` after implementation. All tests must pass.
+4. **Commit atomically:** One commit per logical change. Stage specific files only.
+5. **No completion claims without evidence.** Run the quality gate and report its output.
+
+## Strategy Differentiator
+
+This strategy prioritizes **process discipline** — skills, TDD, verification gates. When in doubt, follow the skill chain exactly rather than improvising. The bet is that disciplined execution produces fewer defects even if it takes more steps.

package/scripts/prompts/agent-b-ralph.md

@@ -0,0 +1,29 @@
+# Agent B: Ralph Wiggum Strategy
+
+You are executing a work unit using the **Ralph Wiggum methodology** — iterative loop with stop-hook verification. Ship fast, verify, fix, repeat.
+
+## Work Unit
+
+{WORK_UNIT_DESCRIPTION}
+
+## Context
+
+- **PRD:** {PRD_PATH}
+- **Architecture Map:** {ARCH_MAP_PATH}
+- **Quality Gate:** `{QUALITY_GATE_CMD}`
+
+## MAB Lessons (from prior competing runs)
+
+{MAB_LESSONS}
+
+## Instructions
+
+1. **Read the work unit carefully.** Understand what "done" looks like before writing code.
+2. **Implement directly.** Write the code, then write the tests. Speed over ceremony.
+3. **Run the quality gate** after each significant change: `{QUALITY_GATE_CMD}`
+4. **If gate fails:** Read the error, fix the root cause, run again. Do not retry blindly.
+5. **Commit when green.** Stage specific files, commit with a descriptive message.
+
+## Strategy Differentiator
+
+This strategy prioritizes **velocity and iteration** — get to a working state quickly, then iterate on failures. The bet is that fast feedback loops and direct implementation outperform ceremony-heavy approaches. When in doubt, ship something testable rather than planning further.

package/scripts/prompts/judge-agent.md

@@ -0,0 +1,61 @@
+# Judge Agent: MAB Evaluation
+
+You are evaluating two competing implementations of the same work unit. Your job is to pick the winner based on objective quality criteria.
+
+## Work Unit
+
+{WORK_UNIT_DESCRIPTION}
+
+## Design Document
+
+{DESIGN_DOC}
+
+## Agent A (Superpowers) Results
+
+### Diff
+```
+{DIFF_A}
+```
+
+### Quality Gate Output
+```
+{GATE_A}
+```
+
+## Agent B (Ralph Wiggum) Results
+
+### Diff
+```
+{DIFF_B}
+```
+
+### Quality Gate Output
+```
+{GATE_B}
+```
+
+## Evaluation Criteria
+
+Score each agent 1-5 on these dimensions:
+
+1. **Correctness** — Does the implementation match the work unit spec? Are tests passing?
+2. **Completeness** — Are all specified deliverables present? Nothing missing?
+3. **Code Quality** — Clean, readable, maintainable? Follows project conventions?
+4. **Test Quality** — Meaningful assertions? Edge cases covered? No hardcoded counts?
+5. **Minimalism** — Smallest diff that solves the problem? No unnecessary changes?
+
+## Output Format
+
+Respond with EXACTLY this format (parseable by the orchestrator):
+
+```
+SCORES:
+agent-a: correctness=N completeness=N quality=N tests=N minimalism=N total=N
+agent-b: correctness=N completeness=N quality=N tests=N minimalism=N total=N
+
+WINNER: agent-a|agent-b|tie
+
+LESSON: <one-sentence pattern observation for future runs>
+```
+
+Be decisive. Ties should be rare — only when scores are genuinely equal across all dimensions.

package/scripts/prompts/planner-agent.md

@@ -0,0 +1,44 @@
+# Planner Agent: Routing Reference
+
+> **NOTE:** This file is reference documentation only. The actual routing logic is
+> implemented in `scripts/lib/thompson-sampling.sh` using Thompson Sampling —
+> not an LLM planner.
+
+## How Routing Works
+
+The MAB system uses **Thompson Sampling** (a Bayesian multi-armed bandit algorithm)
+to decide whether each batch runs in competing mode (both strategies) or uses a
+known winner (single strategy).
+
+### Decision Flow
+
+1. **Check data sufficiency:** If fewer than 5 data points per strategy for this
+   batch type, always run competing (`"mab"`).
+2. **Check batch type:** `integration` batches always run competing (too variable
+   for confident routing).
+3. **Check win rate spread:** If the gap between strategies is < 15%, run competing
+   (too close to call).
+4. **Check for clear winner:** If one strategy has ≥ 70% win rate with 10+ data
+   points, route directly to that strategy.
+5. **Thompson Sample:** Draw from Beta(wins+1, losses+1) for each strategy.
+   Higher sample wins the route.
+
+### Batch Types
+
+| Type | Description | Routing Behavior |
+|------|-------------|-----------------|
+| `new-file` | Creating new files from scratch | Normal Thompson routing |
+| `refactoring` | Modifying existing code | Normal Thompson routing |
+| `integration` | Connecting components | Always competing (high variance) |
+| `test-only` | Only running/adding tests | Normal Thompson routing |
+
+### Data Storage
+
+- `logs/strategy-perf.json` — Win/loss counters per strategy per batch type
+- `logs/mab-lessons.json` — Patterns observed by the judge agent
+
+### Human Calibration
+
+The first 10 competing runs prompt for human override (if stdin is a tty).
+This calibrates the system before it runs fully autonomously.
+After `calibration_complete: true`, the system trusts its own routing.

package/scripts/pull-community-lessons.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# pull-community-lessons.sh — Fetch lessons + strategy data from upstream remote
+#
+# Usage: pull-community-lessons.sh [--remote <name>] [--dry-run] [--help]
+set -euo pipefail
+
+REMOTE="upstream"
+DRY_RUN=false
+
+usage() {
+    cat <<'USAGE'
+pull-community-lessons.sh — Fetch community lessons and strategy data from upstream
+
+Usage: pull-community-lessons.sh [--remote <name>] [--dry-run] [--help]
+
+Options:
+  --remote <name>   Git remote name (default: upstream)
+  --dry-run         Show what would be fetched without changing anything
+  -h, --help        Show this help
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help) usage; exit 0 ;;
+        --remote) REMOTE="$2"; shift 2 ;;
+        --dry-run) DRY_RUN=true; shift ;;
+        *) echo "ERROR: Unknown option: $1" >&2; exit 1 ;;
+    esac
+done
+
+# Verify remote exists
+if ! git remote get-url "$REMOTE" > /dev/null 2>&1; then
+    echo "ERROR: Remote '$REMOTE' not found." >&2
+    echo "Add it with: git remote add $REMOTE <url>" >&2
+    exit 1
+fi
+
+echo "Fetching from $REMOTE..."
+git fetch "$REMOTE" main 2>/dev/null || {
+    echo "ERROR: Failed to fetch from $REMOTE" >&2
+    exit 1
+}
+
+# Count new lessons
+new_count=0
+while IFS= read -r remote_lesson; do
+    local_path="docs/lessons/$(basename "$remote_lesson")"
+    if [[ ! -f "$local_path" ]]; then
+        new_count=$((new_count + 1))
+        if [[ "$DRY_RUN" == true ]]; then
+            echo "  Would copy: $(basename "$remote_lesson")"
+        else
+            git show "$REMOTE/main:$remote_lesson" > "$local_path" 2>/dev/null || true
+        fi
+    fi
+done < <(git ls-tree -r --name-only "$REMOTE/main" -- docs/lessons/ 2>/dev/null | grep '\.md$' || true)
+
+# Merge strategy-perf.json additively
+local_perf="logs/strategy-perf.json"
+if git show "$REMOTE/main:logs/strategy-perf.json" > /dev/null 2>&1; then
+    if [[ -f "$local_perf" ]]; then
+        if [[ "$DRY_RUN" == true ]]; then
+            echo "  Would merge strategy-perf.json (local wins + upstream wins)"
+        else
+            local_data=$(cat "$local_perf")
+            remote_data=$(git show "$REMOTE/main:logs/strategy-perf.json" 2>/dev/null)
+
+            # Merge: take max(local, upstream) per counter — idempotent on repeated pulls
+            tmp=$(mktemp)
+            echo "$local_data" | jq --argjson remote "$remote_data" '
+                def max(a; b): if a > b then a else b end;
+                . as $local |
+                ["new-file", "refactoring", "integration", "test-only"] | reduce .[] as $bt ($local;
+                    .[$bt].superpowers.wins = max(.[$bt].superpowers.wins; $remote[$bt].superpowers.wins // 0) |
+                    .[$bt].superpowers.losses = max(.[$bt].superpowers.losses; $remote[$bt].superpowers.losses // 0) |
+                    .[$bt].ralph.wins = max(.[$bt].ralph.wins; $remote[$bt].ralph.wins // 0) |
+                    .[$bt].ralph.losses = max(.[$bt].ralph.losses; $remote[$bt].ralph.losses // 0)
+                )
+            ' > "$tmp" && mv "$tmp" "$local_perf"
+            echo "  Merged strategy-perf.json"
+        fi
+    fi
+fi
+
+echo ""
+echo "Pull complete: $new_count new lessons"
+if [[ "$DRY_RUN" == true ]]; then
+    echo "(dry run — no changes made)"
+fi