builder

CLI builder for AI-driven development at scale.

One builder. Many projects. AI agents do the work — you make the decisions.

How It Works

1. Add intent — describe what you want built in plain language
2. Agents analyze — PM, validation, planning, testing, build, review, and conflict resolution agents handle each stage
3. You act — approve, decline, skip, or nix at each gate (or let AI decide with --yolo)
4. Code ships — approved work is merged automatically

The system uses a marshaler agent to always present you with the highest-priority decision across all your projects. You never have to figure out what to look at next.

Workflow

You: "Build user authentication with OAuth2"
  ↓
PM Agent suggests project assignment → you approve
  ↓
PM Agent refines requirements (reads codebase) → you approve
  ↓
Validation Agent checks feasibility (reads codebase) → you approve
  ↓
Planning Agent creates implementation plan (reads codebase) → you approve
  ↓
Tester Agent writes tests (in worktree, autonomous — no gate)
  ↓
Builder Agent implements (autonomous — no gate)
  ↓
Acceptor Agent reviews the PR → you approve
  ↓ (if changes needed)
  ↓ Tester adds tests → Builder fixes → Acceptor re-reviews (up to 3 cycles, no gates)
  ↓
Merge to main → Done (worktrees cleaned up)
  ↓ (if merge conflict)
Resolver Agent resolves async → Acceptor re-evaluates → you re-approve → Merge

At any gate: (a)pprove · (d)ecline with feedback · (r)efine (send instructions, re-run) · (s)kip · (n)ix (will not do) · (q)uit

Prerequisites

• Node.js ≥ 20
• GitHub CLI (gh) — authenticated
• Claude Code CLI (claude) — for agent execution

# Add required GitHub scope
gh auth refresh -s project

Setup

npm install
npm link

# Initialize (creates GitHub Project board for main queue)
builder init --owner <your-org>

# Create a project
builder project create my-app --description "My application"

Usage

# Add a requirement
builder add "Build user authentication with OAuth2"

# Add in yolo mode (AI makes all decisions)
builder add --yolo "Add a health check endpoint"

# Add in freak mode (review at every stage including build)
builder add --freak "Critical auth feature"

# Add multiple requirements (continuous mode)
builder add

# Run agents on items that need work
builder process

# Enter action flow — system presents highest-priority items
builder act

# View status across all projects
builder status

# View status for a specific project
builder status --project my-app

# View roadmap (all work in progress and upcoming)
builder roadmap
builder roadmap --project my-app

# View delivered items (completed work with artifacts)
builder delivered
builder delivered --project my-app

# Generate AI-researched product ideas
builder dream
builder dream --project my-app

# View usage and quota information (last 7 days)
builder quota

# View usage for a specific period
builder quota --days 30

# View pipeline metrics (cycle time, velocity, bottlenecks)
builder metrics
builder metrics --project my-app --days 14

# Deep-dive into a specific issue's pipeline history
builder metrics --issue my-app#42

Commands

Command	Description
builder init --owner <org>	Setup main queue (owner is required)
builder project create <name> [--description] [--public]	Create project repo + board
builder project list	List managed projects
builder project update [name]	Refresh project metadata (description, README summary) from GitHub
builder add [intent...] [--yolo] [--freak]	Add requirement (--yolo for autonomous, --freak for max control)
builder connect <repo> [type]	Connect existing project board (or main queue with type="main")
builder disconnect <name> [--clean-github] [--clean-labels] [--force]	Disconnect a project (--clean-github deletes Project, --clean-labels removes labels, --force skips prompts)
builder process [--project <name>] [--status]	Trigger agents (or check status)
builder act	Enter action flow
builder status [--project <name>]	Dashboard
builder roadmap [--project <name>]	Work in progress and upcoming across projects
builder delivered [--project <name>]	Completed items from builder artifact directories
builder dream [--project <name>]	AI-researched product ideas for a project
builder clear <issue>	Delete item (close issue, clean branches)
builder config	Show configuration
builder quota [--days <n>]	Usage and quota dashboard (default: 7 days)
builder metrics [--project] [--days <n>] [--issue]	Pipeline metrics: cycle time, velocity, bottlenecks (default: 30 days)
builder recover [--project] [--issue]	Clean up orphaned worktrees

Modes

Each intent runs in a mode that controls how many gates require human approval. Mode is per-intent, stored as a GitHub label.

Stage	Normal (default)	Freak (--freak)	Yolo (--yolo)
assign	gate	gate	auto
refine	gate	gate	auto
validate	gate	gate	auto
plan	gate	gate	auto
test	auto	gate	auto
build	auto	gate	auto
accept	gate	gate	auto

Normal Mode (default)

No flags needed. Builder approves at assign, refine, validate, plan, and accept. Test and build auto-advance without review.

Freak Mode

builder add --freak "Critical auth feature"

Maximum control. Builder must approve at every stage, including test plan review and build/PR review before the acceptor runs. Use for high-stakes work where you want to inspect every step.

Yolo Mode

builder add --yolo "Add a health check endpoint"

Full automation. AI makes all decisions, answers open questions, and auto-merges. Artifacts are still created for audit trail.

Graceful degradation:

• If the PM agent's project recommendation can't be parsed, the item falls back to manual triage
• If the acceptor finds issues ("Changes Needed"), the item enters the normal rework cycle (test → build → accept) instead of auto-approving
• If the acceptor exhausts 3 auto-fix cycles, the yolo label is removed and the item falls back to manual review
• You can manually remove the yolo or freak label from any issue to change its mode

Documentation

The builder process automatically keeps project documentation up to date:

• Builder agent updates README.md and CLAUDE.md as part of every implementation — new features, commands, config options, architectural changes, and conventions are documented alongside the code
• Acceptor agent verifies documentation was updated during review — missing or stale docs are flagged as "Changes Needed" and fixed automatically in the accept rework cycle (sent back to test→build→accept without builder gates)
• Builder artifacts (builder/<issueNumber>/1-INTENT.md through 6-ACCEPT.md) serve as a per-feature changelog and decision log, preserved on main after merge

Architecture

• Main queue — GitHub Project with states: icebox, intent, triage
• Project boards — GitHub Projects with states: icebox, refine, validate, plan, test, build, accept, done
• Agents — Claude Code CLI subprocesses with role-specific prompts and escalating timeout (SIGTERM → SIGKILL)
• Multi-pass processing — builder process re-checks for new work after each agent completes, so auto-advanced stages (e.g., build → accept) are picked up immediately
• Error recovery — Agent failures are retried automatically on the next processing run; stale locks are recovered after 30 minutes
• Context-aware assignment — PM assignment agent sees project descriptions, AI-synthesized README summaries, and recent issue titles to make informed project recommendations
• Codebase-aware agents — PM, Validator, and Planner agents have read-only access to the project repo, so they can inspect tech stack, structure, and patterns without asking the builder
• Git worktrees — Tester and Builder agents work in isolated worktrees; merged on review approval
• Async merge conflict resolution — When a merge fails, the issue is flagged for async resolution. On the next builder process run, the Resolver agent rebases and resolves conflicts, the Acceptor re-evaluates, and the builder re-approves before merge. Resolution never blocks the interactive session

Configuration

Stored at ~/.builder/config.json. Contains GitHub Project IDs and field mappings. Generated automatically by builder init and builder project create.

Agent usage data (cost, tokens, duration per run) is tracked in ~/.builder/usage.jsonl and surfaced via builder quota.

Pipeline state transitions are tracked in ~/.builder/transitions.jsonl and surfaced via builder metrics. Each entry records when an issue moves between states, what triggered the transition (builder approval, auto-advance, yolo, rework), and the project. The Validation Agent also assigns Fibonacci story points (1–13) as sp:N labels for velocity tracking.