Three-Body Agent

An autonomous development pipeline powered by GitHub Actions and Claude Code CLI. Five workflows pick issues from a project board, implement them, fix their own CI failures, merge green PRs, and keep the board updated — all without human intervention.

┌─────────────────────────────────────────────────────┐
│                  GitHub Actions                     │
│              (Autonomous Brain)                     │
│                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │ Implementer │  │    Fixer    │  │   Merger    │  │
│  │  (hourly)   │  │ (every 30m) │  │ (every 2h)  │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
│                                                     │
│  ┌─────────────┐  ┌─────────────┐                   │
│  │ Board Sync  │  │  Rollover   │                   │
│  │ (PR events) │  │  (weekly)   │                   │
│  └─────────────┘  └─────────────┘                   │
│                                                     │
│              Claude Code CLI                        │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────┐
│              GitHub Projects V2                     │
│            (State Management)                       │
│                                                     │
│   Board: Todo → In Progress → Ready for QA → Done   │
│   Milestones: "26 CW 14", "26 CW 15", ...           │
│   Labels: p0 (critical) through p5 (backlog)        │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────┐
│              Telegram Notifications                 │
│         (Visibility at every stage)                 │
└─────────────────────────────────────────────────────┘

Three systems in constant gravitational pull, each with its own orbit, producing stable results. Shell scripts and GraphQL — no framework, no SDK, no dependencies beyond gh, jq, and curl. The intelligence comes from the model.

60-second quickstart

Copy .github/workflows/ and .github/prompts/ into your repository.
Add three secrets (Settings → Secrets and variables → Actions):
- ANTHROPIC_API_KEY — Claude Code CLI is installed automatically by the workflows.
- AGENT_PAT — a PAT with repo, project, workflow scopes (org-level Projects V2 needs this; GITHUB_TOKEN can't reach it).
- TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID — optional. Swap for Slack / Discord / email by editing the curl call in telegram.yml.
Create a Projects V2 board with the columns Todo, In Progress, Ready For QA, Done. Add priority labels p0 (critical) through p5 (backlog). Optional: milestones in "YY CW WW" format for sprint scoping.
Search every workflow file for TODO comments and fill in your org, repo, project number, runner labels, dependency-install command, and merge method.
Open an issue with clear acceptance criteria, drop it in Todo with a priority label, and the next hourly Implementer run picks it up.

The deeper rationale — and the comparison to Anthropic's Managed Agents — lives in ARCHITECTURE.md.

The five workflows

Workflow	Schedule	Job
Implementer (`autoagent-implementer.yml`)	Hourly	Picks the highest-priority `Todo` issue in the current milestone, branches, implements, opens PR.
Fixer (`autoagent-fixer.yml`)	Every 30 min + on CI failure	Handles CI failures, review comments, and merge conflicts on `autoagent/*` branches.
Merger (`autoagent-merger.yml`)	Every 2 hours	Sequentially merges fully-green autoagent PRs; uses Claude to weigh review comments before merging.
Board Sync (`autoagent-board-sync.yml`)	PR events	Moves issues between `Todo` ↔ `In Progress` ↔ `Ready for QA` ↔ `Done`.
Week Rollover (`auto-week-rollover.yml`)	Mondays 06:00 UTC	Rolls open issues into next week's milestone.

telegram.yml is a reusable notification workflow each of the others calls — pluggable, swap the curl body for any messaging service.

Writing good issues

The number-one predictor of autonomous success is issue quality:

Clear acceptance criteria — what does "done" look like?
Example inputs/outputs — concrete, not abstract.
References — see src/services/auth.ts for the pattern.
Dependencies — Depends on: #123 to chain branches.

Branch naming

autoagent/<issue-number>-<slug> (e.g. autoagent/123-add-user-auth). The issue-number prefix is required — Board Sync uses it to map branches back to issues.