autonomous-coding-toolkit 1.0.0

package/benchmarks/runner.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# runner.sh — Benchmark orchestrator for the Autonomous Coding Toolkit
+#
+# Usage:
+#   runner.sh run [task-name]      Run all or one benchmark
+#   runner.sh compare <a> <b>      Compare two result files
+#   runner.sh list                 List available benchmarks
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+TASKS_DIR="$SCRIPT_DIR/tasks"
+RESULTS_DIR="${BENCHMARK_RESULTS_DIR:-$SCRIPT_DIR/results}"
+
+usage() {
+    cat <<'USAGE'
+Usage: runner.sh <run|compare|list> [options]
+
+Commands:
+  run [name]        Run all benchmarks, or a specific one by directory name
+  compare <a> <b>   Compare two result JSON files
+  list              List available benchmark tasks
+
+Options:
+  --help, -h        Show this help
+
+Results are saved to benchmarks/results/ (gitignored).
+USAGE
+    exit 0
+}
+
+SUBCOMMAND="${1:-}"
+shift || true
+
+case "$SUBCOMMAND" in
+    list)
+        echo "Available benchmarks:"
+        for task_dir in "$TASKS_DIR"/*/; do
+            [[ -d "$task_dir" ]] || continue
+            name=$(basename "$task_dir")
+            desc=""
+            if [[ -f "$task_dir/task.md" ]]; then
+                desc=$(head -1 "$task_dir/task.md" | sed 's/^# //')
+            fi
+            echo "  $name — $desc"
+        done
+        ;;
+
+    run)
+        TARGET="${1:-all}"
+        mkdir -p "$RESULTS_DIR"
+        timestamp=$(date -u +%Y%m%dT%H%M%SZ)
+
+        run_benchmark() {
+            local task_dir="$1"
+            local name=$(basename "$task_dir")
+            echo "=== Benchmark: $name ==="
+
+            if [[ ! -f "$task_dir/rubric.sh" ]]; then
+                echo "  SKIP: no rubric.sh found"
+                return
+            fi
+
+            local score=0
+            local total=0
+            local pass=0
+
+            # Run rubric — each line of output is "PASS: desc" or "FAIL: desc"
+            while IFS= read -r line; do
+                total=$((total + 1))
+                if [[ "$line" == PASS:* ]]; then
+                    pass=$((pass + 1))
+                fi
+                echo "  $line"
+            done < <(bash "$task_dir/rubric.sh" 2>&1 || true)
+
+            if [[ $total -gt 0 ]]; then
+                score=$((pass * 100 / total))
+            fi
+            echo "  Score: ${score}% ($pass/$total)"
+            echo ""
+
+            # Write result
+            jq -n --arg name "$name" --argjson score "$score" \
+                --argjson pass "$pass" --argjson total "$total" \
+                --arg ts "$timestamp" \
+                '{name: $name, score: $score, passed: $pass, total: $total, timestamp: $ts}' \
+                >> "$RESULTS_DIR/$timestamp.jsonl"
+        }
+
+        if [[ "$TARGET" == "all" ]]; then
+            for task_dir in "$TASKS_DIR"/*/; do
+                [[ -d "$task_dir" ]] || continue
+                run_benchmark "$task_dir"
+            done
+        else
+            if [[ -d "$TASKS_DIR/$TARGET" ]]; then
+                run_benchmark "$TASKS_DIR/$TARGET"
+            else
+                echo "Benchmark not found: $TARGET" >&2
+                echo "Run 'runner.sh list' to see available benchmarks." >&2
+                exit 1
+            fi
+        fi
+
+        echo "Results saved to: $RESULTS_DIR/$timestamp.jsonl"
+        ;;
+
+    compare)
+        FILE_A="${1:-}"
+        FILE_B="${2:-}"
+        if [[ -z "$FILE_A" || -z "$FILE_B" ]]; then
+            echo "Usage: runner.sh compare <result-a.jsonl> <result-b.jsonl>" >&2
+            exit 1
+        fi
+        if [[ ! -f "$FILE_A" || ! -f "$FILE_B" ]]; then
+            echo "One or both files not found." >&2
+            exit 1
+        fi
+
+        echo "Benchmark Comparison"
+        echo "═════════════════════════════════════"
+        printf "%-25s %8s %8s %8s\n" "Task" "Before" "After" "Delta"
+        echo "─────────────────────────────────────────────"
+
+        jq -s '
+            [.[0], .[1]] | transpose | .[] |
+            select(.[0] != null and .[1] != null) |
+            "\(.[0].name)|\(.[0].score)|\(.[1].score)|\(.[1].score - .[0].score)"
+        ' <(jq -s '.' "$FILE_A") <(jq -s '.' "$FILE_B") 2>/dev/null | \
+        while IFS='|' read -r name before after delta; do
+            sign=""
+            [[ "$delta" -gt 0 ]] && sign="+"
+            printf "%-25s %7s%% %7s%% %7s%%\n" "$name" "$before" "$after" "${sign}${delta}"
+        done
+
+        echo "═════════════════════════════════════"
+        ;;
+
+    help|--help|-h|"")
+        usage
+        ;;
+
+    *)
+        echo "Unknown command: $SUBCOMMAND" >&2
+        usage
+        ;;
+esac

package/benchmarks/tasks/01-rest-endpoint/rubric.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Rubric for 01-rest-endpoint benchmark
+set -euo pipefail
+
+PROJECT_ROOT="${BENCHMARK_PROJECT_ROOT:-.}"
+
+# Criterion 1: Health endpoint file exists
+if compgen -G "$PROJECT_ROOT/src/*health*" >/dev/null 2>&1 || \
+   compgen -G "$PROJECT_ROOT/app/*health*" >/dev/null 2>&1 || \
+   grep -rl "health" "$PROJECT_ROOT/src/" "$PROJECT_ROOT/app/" 2>/dev/null | head -1 >/dev/null 2>&1; then
+    echo "PASS: Health endpoint file exists"
+else
+    echo "FAIL: Health endpoint file not found"
+fi
+
+# Criterion 2: Test file exists
+if compgen -G "$PROJECT_ROOT/tests/*health*" >/dev/null 2>&1 || \
+   compgen -G "$PROJECT_ROOT/test/*health*" >/dev/null 2>&1; then
+    echo "PASS: Health endpoint test file exists"
+else
+    echo "FAIL: Health endpoint test file not found"
+fi
+
+# Criterion 3: Test passes
+if cd "$PROJECT_ROOT" && (npm test 2>/dev/null || pytest 2>/dev/null || make test 2>/dev/null); then
+    echo "PASS: Tests pass"
+else
+    echo "FAIL: Tests do not pass"
+fi

package/benchmarks/tasks/01-rest-endpoint/task.md

@@ -0,0 +1,17 @@
+# Add a REST Endpoint with Tests
+
+**Complexity:** Simple (1 batch)
+**Measures:** Basic execution, TDD compliance
+
+## Task
+
+Add a `/health` endpoint to the project that:
+1. Returns HTTP 200 with JSON body `{"status": "ok", "timestamp": "<ISO8601>"}`
+2. Has a test that verifies the response status and body structure
+3. All tests pass
+
+## Constraints
+
+- Use the project's existing web framework (or add minimal one if none exists)
+- Follow existing code style and patterns
+- Test must be automated (no manual verification)

package/benchmarks/tasks/02-refactor-module/task.md

@@ -0,0 +1,8 @@
+# Refactor a Module into Two
+
+**Complexity:** Medium (2 batches)
+**Measures:** Refactoring quality, test preservation
+
+## Task
+
+Split `src/utils.sh` into `src/string-utils.sh` and `src/file-utils.sh`, preserving all existing tests.

package/benchmarks/tasks/03-fix-integration-bug/task.md

@@ -0,0 +1,8 @@
+# Fix an Integration Bug
+
+**Complexity:** Medium (2 batches)
+**Measures:** Debugging, root cause analysis
+
+## Task
+
+The `/api/users` endpoint returns 500 when the database connection pool is exhausted. Find and fix the root cause.

package/benchmarks/tasks/04-add-test-coverage/task.md

@@ -0,0 +1,8 @@
+# Add Test Coverage to Untested Module
+
+**Complexity:** Medium (2 batches)
+**Measures:** Test quality, edge case discovery
+
+## Task
+
+Add comprehensive tests to `src/parser.sh` which currently has 0% coverage. Cover happy path, edge cases, and error conditions.

package/benchmarks/tasks/05-multi-file-feature/task.md

@@ -0,0 +1,8 @@
+# Multi-File Feature with API + DB + Tests
+
+**Complexity:** Complex (4 batches)
+**Measures:** Full pipeline, cross-file coordination
+
+## Task
+
+Add a "bookmarks" feature: API endpoints (CRUD), database migration, and integration tests.

package/bin/act.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Toolkit root: works for npm global, npx, and local clone
+// ---------------------------------------------------------------------------
+const TOOLKIT_ROOT = path.resolve(__dirname, '..');
+let VERSION;
+try {
+  const pkg = JSON.parse(fs.readFileSync(path.join(TOOLKIT_ROOT, 'package.json'), 'utf8'));
+  VERSION = pkg.version;
+} catch (err) {
+  console.error('Error: Could not read package.json');
+  console.error(`  ${err.message}`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Platform check — bash required
+// ---------------------------------------------------------------------------
+function checkPlatform() {
+  if (process.platform === 'win32') {
+    let inWsl = false;
+    try {
+      inWsl = fs.existsSync('/proc/version') &&
+        fs.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
+    } catch (_) {
+      // If /proc/version is unreadable, assume not WSL
+    }
+    if (!inWsl) {
+      console.error(
+        'Error: act requires bash, which is not available on native Windows.\n' +
+        'Hint: Install WSL2 (https://aka.ms/wsl) and run act from a WSL terminal.'
+      );
+      process.exit(1);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dependency check
+// ---------------------------------------------------------------------------
+function checkDep(cmd) {
+  try {
+    execFileSync('which', [cmd], { stdio: 'pipe' });
+  } catch (_) {
+    console.error(`Error: Required dependency "${cmd}" not found on PATH.`);
+    console.error(`Install it and try again.`);
+    process.exit(1);
+  }
+}
+
+function checkDependencies() {
+  checkDep('bash');
+  checkDep('git');
+  checkDep('jq');
+}
+
+// ---------------------------------------------------------------------------
+// Script runner
+// ---------------------------------------------------------------------------
+function scripts(name) {
+  return path.join(TOOLKIT_ROOT, 'scripts', name);
+}
+
+function runScript(scriptPath, args) {
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`Error: Script not found: ${scriptPath}`);
+    console.error('This script may not be included in the current installation.');
+    console.error('Try reinstalling: npm install -g autonomous-coding-toolkit');
+    process.exit(1);
+  }
+  try {
+    execFileSync('bash', [scriptPath, ...args], { stdio: 'inherit' });
+  } catch (err) {
+    process.exit(err.status != null ? err.status : 1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+function printHelp() {
+  console.log(`Autonomous Coding Toolkit v${VERSION}
+
+Usage: act <command> [options]
+
+Execution:
+  plan <file> [flags]          Headless/team/MAB batch execution
+  plan --resume                Resume interrupted execution
+  compound [dir]               Full pipeline: report→PRD→execute→PR
+  mab <flags>                  Multi-Armed Bandit competing agents
+
+Quality:
+  gate [flags]                 Composite quality gate (lesson-check + tests + memory)
+  check [files...]             Syntactic anti-pattern scan from lesson files
+  policy [files...]            Advisory positive-pattern checker
+  research-gate [flags]        Block PRD if unresolved research issues
+  validate                     Run all validators
+  validate-plan <file>         Validate plan quality score
+  validate-prd [file]          Validate PRD shell-command criteria
+
+Lessons:
+  lessons pull                 Pull community lessons from upstream
+  lessons check                List active lesson checks
+  lessons promote              Promote MAB-discovered lessons
+  lessons infer                Infer scope metadata for lesson files
+
+Analysis:
+  audit [flags]                Entropy audit: doc drift, naming violations
+  batch-audit [flags]          Cross-project audit runner
+  batch-test [flags]           Memory-aware cross-project test runner
+  analyze [report]             Analyze audit/test report
+  digest [flags]               Failure digest from run logs
+  status [flags]               Pipeline status summary
+  architecture [flags]         Generate architecture map
+
+Telemetry:
+  telemetry [flags]            Telemetry reporting
+
+Benchmarks:
+  benchmark [flags]            Run benchmark suite
+
+Setup:
+  init [flags]                 Initialize toolkit in current project
+  license-check [flags]        Check dependency licenses
+  module-size [flags]          Check module sizes against budget
+
+Meta:
+  version                      Print version
+  help                         Show this help text
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Command map
+// ---------------------------------------------------------------------------
+const COMMANDS = {
+  // Execution
+  plan:            { script: scripts('run-plan.sh') },
+  compound:        { script: scripts('auto-compound.sh') },
+  mab:             { script: scripts('mab-run.sh') },
+
+  // Quality
+  gate:            { script: scripts('quality-gate.sh') },
+  check:           { script: scripts('lesson-check.sh') },
+  policy:          { script: scripts('policy-check.sh') },
+  'research-gate': { script: scripts('research-gate.sh') },
+  validate:        { script: scripts('validate-all.sh') },
+  'validate-plan': { script: scripts('validate-plan-quality.sh') },
+  'validate-prd':  { script: scripts('validate-prd.sh') },
+
+  // Analysis
+  audit:           { script: scripts('entropy-audit.sh') },
+  'batch-audit':   { script: scripts('batch-audit.sh') },
+  'batch-test':    { script: scripts('batch-test.sh') },
+  analyze:         { script: scripts('analyze-report.sh') },
+  digest:          { script: scripts('failure-digest.sh') },
+  status:          { script: scripts('pipeline-status.sh') },
+  architecture:    { script: scripts('architecture-map.sh') },
+
+  // Setup
+  init:            { script: scripts('init.sh') },
+  'license-check': { script: scripts('license-check.sh') },
+  'module-size':   { script: scripts('module-size-check.sh') },
+
+  // Telemetry
+  telemetry:       { script: scripts('telemetry.sh') },
+
+  // Benchmarks (note: under benchmarks/, not scripts/)
+  benchmark:       { script: path.join(TOOLKIT_ROOT, 'benchmarks', 'runner.sh') },
+};
+
+// Lessons sub-dispatch
+const LESSONS_COMMANDS = {
+  pull:    { script: scripts('pull-community-lessons.sh'), args: [] },
+  check:   { script: scripts('lesson-check.sh'),          args: ['--list'] },
+  promote: { script: scripts('promote-mab-lessons.sh'),   args: [] },
+  infer:   { script: scripts('scope-infer.sh'),           args: [] },
+};
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const rest = args.slice(1);
+
+  // Built-in meta commands (no bash needed)
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+    console.log(`act v${VERSION}`);
+    process.exit(0);
+  }
+
+  // Platform + dependency checks for all other commands
+  checkPlatform();
+  checkDependencies();
+
+  // Lessons sub-dispatch
+  if (cmd === 'lessons') {
+    const sub = rest[0];
+    const subArgs = rest.slice(1);
+    if (!sub) {
+      console.error('Error: "lessons" requires a subcommand: pull, check, promote, infer');
+      process.exit(1);
+    }
+    const lessonCmd = LESSONS_COMMANDS[sub];
+    if (!lessonCmd) {
+      console.error(`Error: Unknown lessons subcommand: ${sub}`);
+      console.error('Available: pull, check, promote, infer');
+      process.exit(1);
+    }
+    runScript(lessonCmd.script, [...lessonCmd.args, ...subArgs]);
+    return;
+  }
+
+  // Standard command routing
+  const entry = COMMANDS[cmd];
+  if (!entry) {
+    console.error(`Error: Unknown command: ${cmd}`);
+    console.error(`Run "act help" to see available commands.`);
+    process.exit(1);
+  }
+
+  runScript(entry.script, rest);
+}
+
+main();

package/commands/autocode.md

@@ -0,0 +1,6 @@
+---
+description: "Run the full autonomous coding pipeline — brainstorm → PRD → plan → execute → verify → finish"
+argument-hint: "<feature description, report path, or issue #>"
+---
+
+Invoke the `autonomous-coding-toolkit:autocode` skill to run the full pipeline for: $ARGUMENTS

package/commands/cancel-ralph.md

@@ -0,0 +1,18 @@
+---
+description: "Cancel active Ralph Loop"
+allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/commands/code-factory.md

@@ -0,0 +1,53 @@
+---
+description: "Run the full Code Factory pipeline — brainstorm → PRD → plan → execute → verify"
+argument-hint: "<feature description or report path>"
+---
+
+# Code Factory
+
+Run the full agent-driven development pipeline for: $ARGUMENTS
+
+## Pipeline
+
+This command orchestrates the superpowers skill chain with Code Factory enhancements integrated at each stage. Follow each step in order — do not skip stages.
+
+### Stage 1: Brainstorming
+Invoke `superpowers:brainstorming` to explore the idea, ask questions, propose approaches, and produce an approved design doc at `docs/plans/YYYY-MM-DD-<topic>-design.md`.
+
+### Stage 2: PRD Generation
+After the design is approved, generate `tasks/prd.json` using the `/create-prd` format:
+- 8-15 granular tasks with machine-verifiable acceptance criteria (shell commands)
+- Separate investigation tasks from implementation tasks
+- Order by dependency
+- Save both `tasks/prd.json` and `tasks/prd-<feature>.md`
+
+### Stage 3: Writing Plans
+Invoke `superpowers:writing-plans` to create the implementation plan. Enhance the plan with:
+- A `## Quality Gates` section listing project checks (auto-detect: pytest, npm test, npm run lint, make test)
+- Cross-references to `tasks/prd.json` task IDs
+- `progress.txt` initialization as the first step
+
+### Stage 4: Execution
+Invoke `superpowers:executing-plans` to execute in batches. Between each batch:
+- Run quality gate commands and report results
+- Update `tasks/prd.json` — mark passing tasks
+- Append batch summary to `progress.txt`
+- Fix any failures before proceeding
+
+### Stage 5: Verification
+Invoke `superpowers:verification-before-completion`:
+- Run ALL `tasks/prd.json` acceptance criteria
+- Confirm every task has `"passes": true`
+- Show quality gate evidence
+- Only claim completion with full evidence
+
+### Stage 6: Finish
+Invoke `superpowers:finishing-a-development-branch` to handle commit, PR, or merge.
+
+## Rules
+
+- Never skip a stage. The design must be approved before PRD generation.
+- Every acceptance criterion is a shell command. No vague criteria.
+- Quality gates run between EVERY batch, not just at the end.
+- Progress.txt is append-only during execution — never truncate it.
+- If the input is a report file path, run `scripts/analyze-report.sh` first to identify the top priority, then use that as the feature description for brainstorming.

package/commands/create-prd.md

@@ -0,0 +1,55 @@
+---
+description: "Generate a PRD with machine-verifiable acceptance criteria from a feature description"
+argument-hint: "<feature description>"
+---
+
+# Create PRD
+
+Generate a Product Requirements Document for the given feature.
+
+## Input
+
+The user provides a feature description: $ARGUMENTS
+
+## Process
+
+1. **Understand the feature** — Ask clarifying questions if the description is ambiguous
+2. **Break into tasks** — Generate 8-15 small, granular tasks (not 3-5 large ones)
+3. **Machine-verifiable criteria** — Every acceptance criterion must be a command that returns pass/fail:
+   - Test commands: `pytest tests/test_feature.py -x`
+   - Lint commands: `python3 -m py_compile file.py`
+   - Endpoint checks: `curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/endpoint`
+   - File existence: `test -f path/to/file`
+   - Pattern checks: `grep -q 'expected_pattern' file`
+4. **Separate investigation from implementation** — "Research X" and "Implement X" are different tasks
+5. **Order by dependency** — Tasks should be ordered so each builds on the previous
+
+## Output Format
+
+Save to `tasks/prd.json` (create `tasks/` directory if needed):
+
+```json
+[
+  {
+    "id": 1,
+    "title": "Short imperative title",
+    "description": "What needs to be done and why",
+    "acceptance_criteria": [
+      "pytest tests/test_auth.py::test_login -x",
+      "test -f src/auth/handler.py"
+    ],
+    "passes": false,
+    "blocked_by": []
+  }
+]
+```
+
+Also save a human-readable version to `tasks/prd-<feature-slug>.md` with full descriptions.
+
+## Rules
+
+- Each task should take 1-3 iterations of a Ralph loop to complete
+- Acceptance criteria MUST be shell commands that exit 0 on success, non-zero on failure
+- No vague criteria like "code is clean" or "well-tested" — everything is boolean
+- Include setup tasks (create directories, install deps) as separate tasks
+- Final task should always be "Run full quality gate" with all checks combined

package/commands/ralph-loop.md

@@ -0,0 +1,18 @@
+---
+description: "Start Ralph Loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.