roga

Point rogadev at your repo, run rogadev go, and walk away. It picks issues off your GitHub backlog, analyzes the codebase, writes an implementation plan, codes the solution, writes tests, runs six QA gates (lint, tests, build, accessibility, responsive, security), curates clean commits, and opens a PR — all without a human touching the keyboard. When something truly needs a person, it stops, labels the issue needs-human, and moves on. It's not AI pair programming — it's an AI assembly line for your entire backlog.

How It Works

Most AI coding tools give you a chatbot with tools. roga gives you a factory floor.

18 specialized agents run in sequence, each with a single job. A deterministic state machine — not an AI — controls all routing. Every agent is a fresh Claude CLI invocation with only the context files it needs, which means:

• No context pollution. The agent that just debugged a lint error doesn't carry that baggage into the security review. Each agent starts sharp and focused.
• Bounded failure. If an agent hallucinates, the damage is contained to one step. A structured JSON "gate" at the end of every agent catches bad outputs before they propagate.
• Right-sized models. Each agent can use a different model. Your issue selector doesn't need Opus. Your security reviewer might. Configure per-agent, saving cost without sacrificing quality where it matters.
• Inspectable state. Agents communicate through .roga/context/ files — structured artifacts like plan.md, analysis.json, test-results.md. No "remember what I said 47 messages ago" fragility.

Issue → Scope → Analyze → Investigate → Plan → Review →
Implement → Test → Lint → Test Run → Build → A11y →
Responsive → Security → Diff Review → Commits → PR → Close

QA failures route back to the implementer with a diagnosis. Fix, re-run the gauntlet. If loop limits are exceeded, the workflow aborts gracefully — a draft PR is created with findings, the issue is labeled, and roga moves on to the next one.

Quick Start

Prerequisites

• Node.js >= 20
• GitHub CLI (gh) — authenticated
• Claude CLI (claude)
• A Git repository with a remote

Install

npm install -g rogadev

Initialize

cd your-project
rogadev init

This creates roga.config.ts with your GitHub repo details and default settings. The init wizard automatically detects your GitHub owner and repo from gh or the git remote, prompts you to choose a completion action, and optionally sets maxIssues for per-issue review workflows.

Configure

Edit roga.config.ts:

import { defineConfig } from 'rogadev';

export default defineConfig({
  github: {
    owner: 'your-org',
    repo: 'your-repo',
    defaultBranch: 'main',
  },
});

Run

# Process next available issue
rogadev go

# Process a specific issue
rogadev go --issue 42

# Dry run (no git/GitHub changes)
rogadev go --dry-run

# Process up to 5 issues in a row
rogadev go --max 5

# Resume from last checkpoint
rogadev go --resume

# Show full agent output
rogadev go --verbose

CLI Commands

| Command | Description | | ------------------- | -------------------------------------- | | rogadev go | Start the agent workflow | | rogadev init | Create config file (auto-detects repo) | | rogadev status | Show current workflow state | | rogadev reset | Clear all state (with confirmation) | | rogadev validate | Check prerequisites and config | | rogadev diagnose | View and manage incident reports | | rogadev issue | Create a GitHub issue from plain text | | rogadev dashboard | Open a live browser dashboard | | rogadev update | Update rogadev to the latest version |

Global Flags

| Flag | Description | | --------------------- | ----------------------------------------- | | --config <path> | Path to config file | | --log-level <level> | Log level: debug | info | warn | error | | --no-color | Disable colored output | | -v, --version | Show version |

Command-Specific Flags

go

| Flag | Description | | ------------- | ------------------------------------ | | --max <n> | Process up to N issues, then stop | | --issue <n> | Work on a specific issue by number | | --dry-run | Analysis + planning only, no changes | | --resume | Resume from last checkpoint | | --verbose | Show full agent output |

init

| Flag | Description | | --------- | ------------------------------ | | --force | Overwrite existing config file |

reset

| Flag | Description | | ------------------ | --------------------------------------- | | --force | Clear without confirmation | | --keep-incidents | Keep incident logs when resetting | | --soft | Reset only current issue, keep archives |

diagnose

| Flag | Description | | ------------------ | ----------------------------------------------------- | | --severity <lvl> | Filter by severity: info | warning | error | fatal | | --type <type> | Filter by failure type (e.g., TOKEN_EXHAUSTION) | | --patterns | Analyze recurring failure patterns | | --report | Generate a full diagnostic report | | --submit <id> | Submit an incident as a GitHub issue | | --submit-all | Submit all unsubmitted incidents | | --target <repo> | Target repo for submission (owner/repo) |

Configuration

Full configuration reference:

import { defineConfig } from 'rogadev';

export default defineConfig({
  // Required
  github: {
    owner: 'your-org',
    repo: 'your-repo',
    defaultBranch: 'main', // Default: 'main'
    projectBoard: 'PVT_xxx', // GitHub Projects board ID
    issueLabels: {
      blocked: 'blocked',
      needsHuman: 'needs-human',
      needsTriage: 'needs-triage',
      inProgress: 'in-progress',
    },
  },

  // What happens after an issue is resolved
  completionAction: 'commit-push-and-pr',
  // 'commit'             — commit only (default)
  // 'commit-and-push'    — commit + push, comment on issue
  // 'commit-push-and-pr' — commit + push + open PR, comment on issue
  // 'none'               — do nothing (manual handling)

  // Max issues to process per run (0 = unlimited)
  maxIssues: 0,

  // Merge strategy
  merge: {
    strategy: 'squash', // 'squash' | 'merge' | 'rebase'
    deleteBranch: true,
  },

  // Branch prefix mapping
  branches: {
    prefix: {
      feature: 'feat',
      bugfix: 'fix',
      refactor: 'refactor',
      chore: 'chore',
    },
  },

  // Model overrides per agent
  models: {
    implementer: 'claude-opus-4-6',
    'lint-fixer': 'claude-haiku-4-5',
  },

  // Loop limits
  limits: {
    planReviewMax: 2, // Max plan review cycles
    qaCycleMax: 3, // Max QA → implement loops
    lintFixMax: 5, // Max lint fix attempts
    diffReviewMax: 2, // Max diff review cycles
    ciRetryMax: 2, // Max CI retry attempts
    agentTimeoutSeconds: 600, // Per-agent timeout
    circuitBreakerMax: 3, // Consecutive aborts before exit
  },

  // Quality thresholds
  quality: {
    coverageMinPercent: 80,
    bundleSizeIncreaseMaxKb: 5,
    maxFilesChangedPerPr: 15,
    skipStages: [], // QA stages to skip (e.g., ['QA_UI'])
  },

  // Incident log retention
  incidents: {
    maxFiles: 1000,
    maxAgeDays: 30,
    maxTotalSizeMb: 50,
  },

  // Lifecycle hooks
  hooks: {
    beforeImplement: 'npm run generate',
    afterImplement: 'npm run format',
    beforeTest: 'npm run setup:test',
    beforeBuild: 'npm run prebuild',
  },

  // Custom agent instructions directory
  agentsDir: '.roga/agents',
});

The 18 Agents

| # | Agent | Model | Purpose | | --- | ------------------------ | ------ | -------------------------------- | | 01 | Issue Selector | Haiku | Picks the next issue from GitHub | | 02 | Issue Scoper | Sonnet | Checks scope, splits epics | | 03 | Issue Analyzer | Opus | Deep requirements analysis | | 04 | Codebase Investigator | Opus | Maps patterns and blast radius | | 05 | Solution Architect | Opus | Designs the implementation plan | | 06 | Plan Reviewer | Opus | Reviews the plan for gaps | | 07 | Implementer | Opus | Writes the code | | 08 | Test Writer | Sonnet | Writes tests | | 09 | QA Lint Fixer | Haiku | Fixes lint/format/type errors | | 10 | QA Test Runner | Sonnet | Runs tests, fixes failures | | 11 | QA Build Verifier | Haiku | Verifies build succeeds | | 12 | QA Accessibility Auditor | Sonnet | WCAG 2.1 AA compliance | | 13 | QA Responsive Checker | Sonnet | Responsive design verification | | 14 | QA Security Reviewer | Opus | Security vulnerability check | | 15 | Diff Reviewer | Opus | Final code review | | 16 | PR Writer | Sonnet | Creates the pull request | | 17 | Commit Curator | Haiku | Organizes clean commits | | 18 | Issue Closer | Haiku | Closes the issue |

Custom Agent Overrides

You can override any agent's instructions by placing a file with the same name in your configured agentsDir (default: .roga/agents/).

.roga/agents/
  07-implementer.md     ← Your custom instructions override the default

See examples/custom-agent-override/ for a sample.

State & Context

All workflow state is stored in .roga/:

.roga/
  state.json            # Current workflow snapshot
  wal.jsonl             # Write-ahead log for checkpointing
  context/              # Agent context files (issue.json, analysis.md, etc.)
  logs/                 # Full agent output logs
  incidents/            # Incident reports from failures
  archive/              # Archived contexts from completed issues

Add .roga/ to your .gitignore.

Runtime Controls

While running in an interactive terminal:

• f — Finish current issue cycle, then stop
• x — Stop immediately after current agent finishes
• Ctrl+C — Abort (double-tap within 2s to force quit)

Abort & Recovery

If the workflow exceeds loop limits or encounters an unrecoverable error:

1. All work-in-progress is committed to the branch
2. A draft PR is created with an abort report
3. The issue is labeled needs-human
4. Use rogadev go --resume to continue from the last checkpoint

State is checkpointed to a write-ahead log (.roga/wal.jsonl), so crashes and interrupts can be recovered from gracefully.

If the same issue aborts consecutively and hits the circuit breaker limit (default: 3), roga will exit rather than loop indefinitely.

Incident Diagnostics

roga logs incidents (agent failures, token exhaustion, timeouts) to .roga/incidents/. Use rogadev diagnose to inspect them:

# View all incidents
rogadev diagnose

# Filter by severity or type
rogadev diagnose --severity error
rogadev diagnose --type TOKEN_EXHAUSTION

# Analyze recurring failure patterns
rogadev diagnose --patterns

# Generate a full diagnostic report
rogadev diagnose --report

# Submit an incident as a GitHub issue
rogadev diagnose --submit <id> --target owner/repo

Incident retention is configurable via the incidents config section.

Live Dashboard

rogadev dashboard

Opens a browser dashboard on port 3000 that polls workflow state in real time. Displays current phase progress, loop counters, session metrics (cost, tokens, agent count), and an event stream.

Programmatic API

import { Orchestrator, loadConfig } from 'rogadev';

const config = await loadConfig();
const orchestrator = new Orchestrator({ config, maxIssues: 1 });
await orchestrator.run();

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Type check
pnpm typecheck

# Lint
pnpm lint

# Test
pnpm test

# Dev mode (watch)
pnpm dev

Loop Limits

| Loop | Max | On Exceed | | ----------------------- | --- | ----------------------------------- | | Plan ↔ Review | 2 | Abort: draft PR + needs-human label | | Full QA cycle | 3 | Abort: draft PR with findings | | Lint fix | 5 | Abort: structural issue | | Diff Review ↔ Implement | 2 | Abort: draft PR with review notes | | CI retry | 2 | Abort: PR comment with failure log | | Circuit breaker | 3 | Exit: stop retrying same issue |

Model Selection Rationale

• Opus — Where mistakes are expensive: planning, implementation, security, code review
• Sonnet — Where domain knowledge matters: testing, accessibility, responsiveness
• Haiku — Where the task is mechanical: git ops, lint fixes, build verification

Support the Project

If roga saves you time or you just want to help a fellow developer keep the lights on, consider buying me a coffee:

• PayPal: [email protected]
• Interac e-Transfer (Canada): [email protected]

Every bit helps — thank you!

Early Access Passes

rogadev requires Claude Code to run. If you don't have access yet, here are 3 early-bird passes to get you started:

Claim a pass

Each pass grants access to Claude Code so you can try rogadev in your own projects. Only 3 passes are available — once they're claimed, they're gone for good. No more will be added, so grab one while you can.

License

MIT