{"id":48908701,"url":"https://github.com/aojdevstudio/rbp-stack","last_synced_at":"2026-04-16T22:03:57.625Z","repository":{"id":331528442,"uuid":"1131402241","full_name":"AojdevStudio/rbp-stack","owner":"AojdevStudio","description":"Autonomous Epic implementation system with test-gated verification. Stop trusting AI agents. Start verifying them.","archived":false,"fork":false,"pushed_at":"2026-01-21T03:55:08.000Z","size":11647,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-21T03:57:03.961Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AojdevStudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-10T00:18:22.000Z","updated_at":"2026-01-21T03:55:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AojdevStudio/rbp-stack","commit_stats":null,"previous_names":["aojdevstudio/rbp-stack"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AojdevStudio/rbp-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Frbp-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Frbp-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Frbp-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Frbp-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AojdevStudio","download_url":"https://codeload.github.com/AojdevStudio/rbp-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Frbp-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31905896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-16T22:03:37.936Z","updated_at":"2026-04-16T22:03:57.602Z","avatar_url":"https://github.com/AojdevStudio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/rbp-hero-banner.jpg\" alt=\"RBP Stack - Stop trusting. Start verifying.\" width=\"800\"/\u003e\n\n# RBP Stack\n\n### **Stop trusting AI agents. Start verifying them.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\u003c!-- [![GitHub stars](https://img.shields.io/github/stars/AojdevStudio/rbp-stack?style=social)](https://github.com/AojdevStudio/rbp-stack/stargazers) --\u003e\n\n*The first autonomous Epic implementation system that prevents AI agents from lying about task completion.*\n\n\u003cbr /\u003e\n\n[**View Demo**](#demo) · [**Quick Start**](#quick-start) · [**How It Works**](#how-it-works) · [**Documentation**](docs/rbp-stack-specification.md)\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## The Problem Everyone Ignores\n\nYou give an AI agent an Epic. It returns \"done\" with all checkboxes marked complete.\n\nThen you look at the code.\n\n- Tests were never run\n- The UI doesn't render\n- Half the subtasks were skipped\n- There's no audit trail\n\n**Sound familiar?**\n\nYou trusted the agent. The agent lied.\n\n\u003cbr /\u003e\n\n\u003e *\"We spent 3 months building an AI-powered development workflow. 76 stories later, we discovered a painful truth: agents mark tasks 'complete' without doing the work. Checkboxes are just booleans. There's no proof.\"*\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## The Insight That Changed Everything\n\nAfter months of frustration, we discovered something simple:\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n### **Agents can lie to checkboxes.**\n### **They cannot lie to tests.**\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\nA checkbox is self-reported. A test is objective verification.\n\nIf `bun test` fails, the lie is exposed. Period.\n\nSo we built a system around one unbreakable rule:\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n## **No task closes without proof.**\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Introducing the RBP Stack\n\n**R**alph + **B**eads + **P**AI\n\nA verification-first autonomous development system.\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n| Component | Role |\n|:----------|:-----|\n| **Ralph** | Autonomous execution loop that never stops until done |\n| **Beads** | Git-backed task graph — the single source of truth |\n| **Tests** | The gatekeeper that agents cannot bypass |\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n```\nWorkflow A (BMAD):\nEpic  →  BMAD Story  →  Beads  →  Ralph Loop  →  Verified Code\n\nWorkflow B (Quick-Plan):\nFeature Idea  →  /quick-plan  →  Spec  →  Codex Review  →  Beads  →  Ralph Loop  →  Verified Code\n\nBoth workflows use the same gatekeeper:\n                              close-with-proof.sh\n                                       ↓\n                              Tests pass? → Close task\n                              Tests fail? → Keep trying\n```\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/rbp-2-workflow-flow.jpg\" alt=\"RBP Workflow\" width=\"700\"/\u003e\n\n*From requirements to verified code. No human intervention required.*\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## See It In Action\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📺 Demo: Watch Ralph implement a feature autonomously\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n\u003c!-- Replace with actual GIF/video when available --\u003e\n```bash\n# 1. Convert your story to beads\n./scripts/rbp/parse-story-to-beads.sh docs/stories/story-001.md\n\n# 2. Launch Ralph\n./scripts/rbp/ralph.sh\n\n# 3. Watch the magic happen\n# Ralph queries Beads → Implements task → Runs tests → Only closes if tests pass\n# Repeats until all tasks complete\n```\n\n*GIF coming soon — star the repo to get notified!*\n\n\u003c/details\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Defense in Depth\n\nWe don't trust agents. We verify them at every layer.\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/rbp-3-verification-system.jpg\" alt=\"Verification System\" width=\"600\"/\u003e\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n| Layer | Mechanism | What It Prevents |\n|:------|:----------|:-----------------|\n| **1** | Objective Acceptance Criteria | Vague \"it works\" claims |\n| **2** | Protocol Mandate | Skipping verification steps |\n| **3** | Failure State Injection | \"I don't remember what went wrong\" |\n| **4** | Test Gating (`bun test`) | Claims without passing tests |\n| **5** | Playwright Verification | UI lies (\"looks correct\") |\n| **6** | Human Code Review | Subtle implementation issues |\n| **7** | Beads Audit Trail | Retroactive tampering |\n\n\u003cbr /\u003e\n\nAn agent **cannot** game this system. Either the tests pass or they don't.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Quick Start\n\n### Prerequisites\n\n```bash\n# Beads - Git-backed task tracker (one-time global install, pick one)\nbrew install steveyegge/beads/bd                # Homebrew (recommended)\n# or: curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash\n# or: npm install -g @beads/bd\n# or: go install github.com/steveyegge/beads/cmd/bd@latest\n\n# Bun - JavaScript runtime (one-time global install)\ncurl -fsSL https://bun.sh/install | bash\n\n# Claude Code CLI (one-time global install)\n# https://claude.ai/download\n\n# PAI Observability (optional, for real-time monitoring dashboard)\n# https://github.com/danielmiessler/Personal_AI_Infrastructure.git\n```\n\n### Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/AojdevStudio/rbp-stack.git\n\n# Install into your project\n./rbp/install.sh /path/to/your/project\n\n# Validate installation\n/path/to/your/project/scripts/rbp/validate.sh\n```\n\n### Run (Two Workflows)\n\n**Workflow A: BMAD Stories** (structured story-driven)\n\n```bash\n# Create a story with BMAD\n/bmad:bmm:workflows:create-story\n\n# Convert to beads\n./scripts/rbp/parse-story-to-beads.sh docs/stories/story-001.md\n\n# Launch autonomous execution\n./scripts/rbp/ralph.sh\n```\n\n**Workflow B: Quick-Plan Specs** (interview-driven)\n\n```bash\n# Create a spec through codebase analysis + interview\n/quick-plan \"add user authentication with JWT\"\n\n# Execute with optional Codex pre-flight review\n./scripts/rbp/ralph-execute.sh specs/add-user-authentication.md\n\n# Or skip the Codex review\n./scripts/rbp/ralph-execute.sh specs/add-user-authentication.md --skip-review\n```\n\n**Monitor Progress**\n\n```bash\nbd status        # Task status\nbd list --open   # Open tasks\nbd tree          # Task hierarchy\n```\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Ralph CLI Reference\n\nRalph is the autonomous execution engine for RBP. It's written in TypeScript and runs on Bun.\n\n### Global Options\n\nAvailable on all commands:\n\n```bash\nralph --config \u003cpath\u003e        # Custom config file path\nralph --verbose              # Increase output verbosity (debug level)\nralph --quiet                # Decrease output verbosity (warn level)\nralph --json-errors          # Output errors as JSON (default: true)\nralph --no-json-errors       # Output errors as human-readable text\n```\n\n**Error Format:** By default, errors are output as JSON for programmatic processing. Use `--no-json-errors` to get human-readable text output. The `--json-errors` and `--no-json-errors` flags are mutually exclusive.\n\n### Commands\n\n**run** (default command)\n\n```bash\nralph run                              # Run the execution loop\nralph run --bmad                       # Use BMAD workflow explicitly\nralph run --beads                      # Use Beads workflow explicitly\nralph run --max-iterations \u003cn\u003e         # Max iterations (positive integer \u003e= 1)\nralph run --dry-run                    # Dry run mode (no changes)\n```\n\n**Validation Rules:**\n- `--max-iterations` must be a positive integer \u003e= 1 (prevents NaN)\n- `--bmad` and `--beads` flags cannot be used together\n- The CLI auto-detects workflow if not specified\n\n**status**\n\n```bash\nralph status                           # Show current execution state\n```\n\n**close**\n\n```bash\nralph close \u003cid\u003e                       # Close a task with test verification\nralph close \u003cid\u003e --force               # Force close without tests (-f)\nralph close \u003cid\u003e --dry-run             # Dry run mode\n```\n\n**exec-spec**\n\n```bash\nralph exec-spec \u003cfile\u003e                 # Execute a spec file\nralph exec-spec \u003cfile\u003e --skip-review   # Skip Codex review\nralph exec-spec \u003cfile\u003e --max-iterations \u003cn\u003e  # Max iterations\nralph exec-spec \u003cfile\u003e --dry-run       # Dry run mode\n```\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## How It Works\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/rbp-1-layer-architecture.jpg\" alt=\"Architecture\" width=\"700\"/\u003e\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n### The Core Loop\n\n```bash\nwhile tasks_remain:\n    task = bd ready           # Query Beads for next unblocked task\n    implement(task)           # Agent implements the task\n    close-with-proof.sh       # THE GATEKEEPER\n        ├── bun test          # Unit tests must pass\n        ├── playwright test   # UI tests must pass (if UI task)\n        └── bd close          # Only now can the task close\n```\n\n### The Gatekeeper Script\n\n```bash\n#!/usr/bin/env bash\n# close-with-proof.sh - The agent cannot bypass this\n\n# Run tests\nbun run test || exit 1\n\n# Run Playwright for UI tasks (auto-detected)\nif [[ \"$TASK_TYPE\" == \"ui\" ]]; then\n    bunx playwright test || exit 1\nfi\n\n# Only close if all tests pass\nbd close \"$BEAD_ID\"\necho \"✅ Task verified and closed\"\n```\n\n**This is script-level enforcement.** The agent has no way around it.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Failure State Injection\n\nWhen a task fails its test verification, Ralph automatically injects the failure context into the next attempt:\n\n```\nTask Iteration 1:\n  ├── Run tests\n  ├── Tests fail → Append failure notes to bead\n  └── Ralph continues to next task\n\nTask Iteration 2 (when task becomes ready again):\n  ├── Read previous failure notes from bead\n  ├── Inject \"Previous Attempt Failed\" section into prompt\n  ├── Agent sees exactly what went wrong\n  ├── Agent fixes the issues\n  ├── Run tests again\n  └── If pass → Close with proof\n```\n\nThis prevents the agent from making the same mistake twice.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Atomic Subtasks\n\nWhen a task contains subtasks, the parser creates them as **separate child beads with explicit dependencies**:\n\n```\nTask: \"Create admin dashboard\"\n├── Subtask 1.1: Build layout structure (no dependencies)\n│   └── Bead ID: bd-123.1.1\n├── Subtask 1.2: Add sidebar (depends on 1.1)\n│   └── Bead ID: bd-123.1.2\n├── Subtask 1.3: Implement navigation (depends on 1.2)\n│   └── Bead ID: bd-123.1.3\n└── Task depends on final subtask (1.3)\n```\n\nBenefits:\n- **Clear sequencing**: Each subtask has explicit dependencies\n- **Granular tracking**: Each subtask is independently verifiable\n- **Failure recovery**: If subtask 2 fails, only that subtask retries (not 1.1)\n- **Optimal context**: Ralph executes one subtask per iteration\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Quick-Plan Workflow\n\nDon't have BMAD? Use the Quick-Plan workflow instead.\n\n### How It Works\n\n```\n/quick-plan \"feature description\"\n         ↓\n    Codebase Analysis (scans your project)\n         ↓\n    Interview (asks clarifying questions until ZERO gaps remain)\n         ↓\n    specs/feature-name.md (with mandatory Testing Strategy + Implementation Tasks)\n         ↓\n./ralph-execute.sh specs/feature-name.md\n         ↓\n    [Optional] Codex Pre-Flight Review (GPT-5-Codex analyzes spec)\n         ↓\n    Parse Spec → Beads (creates task graph with dependencies)\n         ↓\n    Ralph Loop (bd ready → implement → test → close, repeat)\n         ↓\n    Verified Code\n```\n\n### The Spec Format\n\nQuick-plan generates specs with two mandatory RBP sections:\n\n```markdown\n## Testing Strategy\n\n### Test Framework\nbun test (detected from package.json)\n\n### Test Command\n`bun test`\n\n### Unit Tests\n- [ ] Test: User model validation → File: `tests/user.test.ts`\n- [ ] Test: JWT token generation → File: `tests/auth.test.ts`\n\n## Implementation Tasks\n\n\u003c!-- RBP-TASKS-START --\u003e\n### Task 1: Create user model\n- **ID:** task-001\n- **Dependencies:** none\n- **Files:** `src/models/user.ts`\n- **Acceptance:** User model with email, password hash, timestamps\n- **Tests:** `tests/user.test.ts`\n- **Subtasks:**\n  - [ ] Define TypeScript interfaces\n  - [ ] Implement validation logic\n  - [ ] Add timestamp fields\n\n### Task 2: Add JWT authentication [UI]\n- **ID:** task-002\n- **Dependencies:** task-001\n- **Files:** `src/auth/jwt.ts`, `src/components/LoginForm.tsx`\n- **Acceptance:** Login returns valid JWT, stored in httpOnly cookie\n- **Tests:** `tests/auth.test.ts`\n\u003c!-- RBP-TASKS-END --\u003e\n```\n\n### Codex Pre-Flight Review\n\nBefore executing, `ralph-execute.sh` optionally runs GPT-5-Codex to review the spec:\n\n```bash\n# With Codex review (default)\n./scripts/rbp/ralph-execute.sh specs/feature.md\n\n# Skip review\n./scripts/rbp/ralph-execute.sh specs/feature.md --skip-review\n```\n\nCodex checks for:\n- Missing edge cases\n- Wrong technical approaches\n- Missing task dependencies\n- Incomplete testing strategy\n- Security concerns\n\n### UI Auto-Detection\n\nTasks tagged with `[UI]` or containing UI keywords automatically get the `requires-playwright` flag. The gatekeeper runs Playwright tests for these tasks.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Key Decisions\n\n### Why Beads as Source of Truth?\n\nThe agent queries `bd ready` instead of reading JSON files.\n\n- **No stale state** — Beads is always current\n- **No sync issues** — Single source of truth\n- **Git-backed** — Full audit trail\n\n### Why No Story Atomization?\n\nWe analyzed 76 real BMAD stories:\n\n| Metric | Value |\n|:-------|:------|\n| Average story size | 3,914 tokens |\n| Largest story | 12,962 tokens |\n| Context budget used | 12.9% of 100k |\n\n**All stories fit in a single context window.** For larger stories, our Execution Sequencer groups subtasks into phases of 3-5.\n\n### Why Test-Gating at Script Level?\n\nAgents can be told \"run tests before closing.\" They can ignore the instruction.\n\nScripts cannot be ignored. `close-with-proof.sh` **runs** the tests. Either they pass or the task stays open.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## What's Included\n\n```\nrbp/\n├── scripts/\n│   ├── ralph.sh              # Main execution loop\n│   ├── ralph-execute.sh      # Quick-plan execution (with Codex review)\n│   ├── close-with-proof.sh   # Test-gated closure (THE GATEKEEPER)\n│   ├── emit-event.sh         # PAI Observability event emitter\n│   ├── parse-story-to-beads.sh  # BMAD Story → Beads conversion\n│   ├── parse-spec-to-beads.sh   # Quick-plan Spec → Beads conversion (with atomic subtasks)\n│   ├── sequencer.sh          # Phase grouping for large stories\n│   ├── show-active-task.sh   # Display current task\n│   └── save-progress-to-beads.sh  # Sync progress to bead notes\n├── commands/rbp/\n│   ├── start.md              # /rbp:start command (with dashboard auto-launch)\n│   ├── status.md             # /rbp:status command\n│   └── validate.md           # /rbp:validate command\n├── lib/src/\n│   ├── cli.ts                # TypeScript CLI entry point (Commander.js)\n│   ├── commands/             # CLI command implementations\n│   ├── workflows/            # BMAD and Beads workflow handlers\n│   ├── config/               # Configuration loading and validation\n│   └── utils/                # Shared utilities and error handling\n├── templates/\n│   ├── rbp-config.yaml         # Base configuration\n│   ├── rbp-config.example.yaml # Documented config with comments\n│   └── spec-template.md        # Quick-plan spec format template\n├── install.sh                # One-line installation\n├── validate.sh               # Installation checker\n└── README.md                 # Package documentation\n```\n\nKey features of included scripts:\n- **ralph.sh**: Failure state injection, completion signal detection\n- **close-with-proof.sh**: Failure note appending, multi-layer verification\n- **parse-spec-to-beads.sh**: Atomic subtask creation with dependency chaining\n- **cli.ts**: TypeScript CLI with validation rules for arguments and options\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Tech Stack\n\n- **Execution:** Claude Code CLI\n- **CLI Engine:** TypeScript + Commander.js (bun runtime)\n- **State:** Beads (git-backed) — query `bd ready`, never mirror to JSON\n- **Testing:** bun test + Playwright\n- **Scripts:** Bash\n- **Runtime:** bun\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Configuration\n\n```yaml\n# rbp-config.yaml\nproject:\n  name: \"your-project\"\n\npaths:\n  stories: \"docs/stories\"      # BMAD stories\n  specs: \"specs\"               # Quick-plan specs\n\nexecution:\n  max_iterations: 10\n  phase_size: 5\n\nverification:\n  require_tests: true\n  require_playwright_for_ui: true\n  test_command: \"bun run test\"\n\nquick_plan:\n  command: \"/quick-plan\"\n  spec_template: \"templates/spec-template.md\"\n\ncodex:\n  enabled: true                # Set false if Codex not installed\n  model: \"gpt-5-codex\"\n  reasoning_effort: \"high\"\n  skip_by_default: false       # Set true to skip review by default\n\nobservability:\n  enabled: true                # Emit events to PAI dashboard\n  auto_launch: true            # Auto-start dashboard with /rbp:start\n```\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Observability\n\nRBP integrates with [PAI (Personal AI Infrastructure)](https://github.com/danielmiessler/Personal_AI_Infrastructure.git) for real-time observability of task execution.\n\n### What You Get\n\n| Feature | Description |\n|:--------|:------------|\n| **Real-time Dashboard** | Watch task progress in your browser |\n| **Event Stream** | See RBP:TaskStart, RBP:TestRun, RBP:TestResult events live |\n| **Debug Visibility** | Trace through test failures and errors |\n| **Multi-Session Support** | Run multiple RBP sessions with distinct session IDs |\n\n### Setup\n\n```bash\n# 1. Install PAI (if not already installed)\ngit clone https://github.com/danielmiessler/Personal_AI_Infrastructure.git ~/PAI\ncd ~/PAI \u0026\u0026 ./install.sh\n\n# 2. RBP auto-detects PAI and emits events automatically\n# Events are written to: ~/.claude/history/raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl\n\n# 3. Launch dashboard with /rbp:start or manually:\n~/.claude/observability/manage.sh start\n# Dashboard: http://localhost:5172\n```\n\n### Event Types\n\n| Event | Emitted When |\n|:------|:-------------|\n| `RBP:LoopStart` | Ralph begins execution |\n| `RBP:TaskStart` | A task is picked from `bd ready` |\n| `RBP:TaskProgress` | Task status changes (executing, iteration_complete) |\n| `RBP:TaskComplete` | Task closed with proof |\n| `RBP:TestRun` | Tests are about to run |\n| `RBP:TestResult` | Tests complete (includes exit code, output) |\n| `RBP:Error` | An error occurred |\n| `RBP:CodexReview` | Codex pre-flight review starts/completes |\n| `RBP:SpecParsed` | Spec parsed to Beads |\n| `RBP:LoopEnd` | Ralph loop completes |\n\n### Without PAI\n\nRBP works without PAI — observability events are simply not emitted. You can still monitor progress via:\n\n```bash\n# File-based logs\ntail -f scripts/rbp/progress.txt\n\n# Beads activity\nbd activity --follow\n\n# Task status\nbd status\n```\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## The Story Behind RBP\n\nI've been using the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) for a while now. It's probably the best tool I've found for building software projects with AI — structured stories, clear acceptance criteria, the whole workflow. I'm also an avid [Claude Code](https://claude.ai) user. These tools changed how I build.\n\nBut something was missing.\n\nEvery time I kicked off a BMAD story, I'd watch the AI work... then it would stop. Ask a question. Wait for me. I'd answer, it would continue... then stop again. The constant back-and-forth was killing my productivity. I wanted to give it an Epic and walk away. Come back to working code.\n\n**I wanted long-running autonomous processes.**\n\nThen I discovered [Ralph](https://ghuntley.com/ralph/) — Geoffrey Huntley's pattern for relentless AI execution loops. And [Beads](https://github.com/steveyegge/beads) — Steve Yegge's git-backed task graph. Something clicked.\n\n*What if I could combine BMAD's structured stories with Ralph's autonomous loops and Beads' persistent memory?*\n\nI started building. 76 stories later, I had a working system. But I also discovered something uncomfortable: AI agents lie. They mark tasks \"complete\" without running tests. They check boxes without doing the work.\n\nThe realization hit me: **Checkboxes are self-reported. Tests are objective.**\n\nAn agent can flip a boolean. It cannot fake a passing test.\n\nSo I added test-gated closure. No task closes without proof. The script runs the tests — either they pass or the task stays open. The agent has no say in the matter.\n\nThen I realized: when a task fails, the agent needs to see what went wrong. So I added failure state injection. The previous attempt's notes are automatically injected into the retry prompt. Now agents can learn from their mistakes without human guidance.\n\nFinally, I made subtasks atomic. Each subtask is a separate bead with explicit dependencies, not just checklist items. This lets Ralph execute them sequentially with test verification after each one.\n\n**The RBP Stack is the result.**\n\nWhat started as a productivity hack became a verification-first autonomous development system. BMAD creates the stories. Beads tracks the state. Ralph drives the execution. Tests guard the gates. Failure notes teach the next attempt.\n\nNow I give it an Epic and walk away. Come back to verified, working code.\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n### I wanted to stop babysitting AI. This is how I did it.\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Roadmap\n\n- [x] Core execution loop (Ralph)\n- [x] Test-gated closure\n- [x] Story → Beads conversion (BMAD workflow)\n- [x] Spec → Beads conversion (Quick-Plan workflow)\n- [x] Codex pre-flight review integration\n- [x] UI auto-detection (Playwright)\n- [x] Execution sequencer for large stories\n- [x] Real-time progress dashboard (PAI Observability integration)\n- [x] Failure state injection (previous attempt context)\n- [x] Atomic subtask creation with dependencies\n- [ ] Parallel task execution\n- [ ] Integration with more test frameworks\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Contributing\n\nContributions welcome! Please ensure:\n\n1. All scripts have tests\n2. Documentation is updated\n3. **The verification system is never bypassed**\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## Acknowledgments\n\n- **[Beads](https://github.com/steveyegge/beads)** — Git-backed issue tracking by Steve Yegge\n- **[BMAD](https://github.com/bmad-code-org/BMAD-METHOD)** — Structured story creation framework\n- **[Claude Code](https://claude.ai)** — Execution environment\n- **[Ralph Pattern](https://ghuntley.com/ralph/)** — The original autonomous loop concept by Geoffrey Huntley\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n\u003cbr /\u003e\n\n---\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with frustration. Verified with tests.**\n\n\u003cbr /\u003e\n\nIf this helped you, [⭐ star the repo](https://github.com/AojdevStudio/rbp-stack) — it helps others find it.\n\n\u003cbr /\u003e\n\n[![Star History Chart](https://api.star-history.com/svg?repos=AojdevStudio/rbp-stack\u0026type=Date)](https://star-history.com/#AojdevStudio/rbp-stack\u0026Date)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Frbp-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faojdevstudio%2Frbp-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Frbp-stack/lists"}