Deterministic orchestration for autonomous software engineering.
LLMs generate the code. ForgeDock owns everything else — state, scheduling, recovery, review, and memory — as durable, inspectable structure on the GitHub you already have. Issues are the queue. PRs are the ledger. Annotations are the memory. Point it at an issue and get a merged, reviewed PR; point it at a milestone and get parallel pipelines with conflict-aware scheduling.
One /orchestrate runs a whole milestone. Agents pick up issues in parallel, drive each through investigate → build → review, and flip the GitHub labels to merged — live.
This repository builds itself with ForgeDock. In its first 30 days (June 4 → July 4, 2026): 693 issues filed, 605 closed, 603 PRs merged — median 56 minutes from open to merged-and-closed. 57% of those issues were filed by the pipeline itself; 49% are findings its own review agents raised, filed, and then fixed. Every run leaves a public audit trail — click through the receipts, or count them yourself:
gh issue list -R RapierCraftStudios/ForgeDock --state closed --limit 1000 --json number --jq 'length'A single run, up close — a real one, issue #1230:
$ /work-on #1230 "orchestrate: Layer 5 co-change signal is dead code"
✓ investigate CONFIRMED/HIGH — feature shipped 3h earlier (PR #1204) reads a
never-populated variable; the co-change query can never fire
✓ build fix branch, 1 file
✓ review caught a defect in the fix itself: stray backticks in the grep
meant every git-log pathspec silently matched zero commits —
"the fix would not have actually worked." Corrected.
✓ merged 30m 37s → staging
filed by the pipeline's own staging review. fixed before a human read it.npx forgedock demo # spins up a risk-free demo repo and shows you the pipeline end to endReady to use it for real? npx forgedock walks you through one continuous setup: it checks your environment, installs the slash commands, reads your repo, and hands you a single annotated forge.yaml to review — you press Enter once.
⭐ If ForgeDock saves you time, star the repo — it's the whole marketing budget.
Your AI coding agent forgets everything after every session. It re-explores the codebase from scratch, re-makes mistakes that were already fixed, and has no idea why the code it's touching looks the way it does. ForgeDock fixes that by making GitHub itself the memory — every pipeline stage writes structured findings that every later agent reads.
| Without ForgeDock | With ForgeDock |
|---|---|
| Agent starts every session blind — no context from prior work | Agent reads structured investigation, root cause, and history straight from GitHub |
| The same bugs get reintroduced across PRs | Review agents surface known pitfalls from past PRs before you commit |
| A crash or compaction loses the run | State lives on GitHub and in an event-sourced run log — the pipeline resumes where it stopped |
| You write the issue, plan the fix, open the PR, and review it | /work-on #42 → investigated, built, reviewed, merged |
| Review depends on whoever has capacity | 9 domain-specialist agents (security, billing, DB, concurrency…) review every PR |
| One task at a time, serialized by your attention | /orchestrate runs a whole milestone — many issues in parallel, each its own full pipeline |
AI agents have no lookback. They don't know a function was shaped by a bug fix in #347, that an approach was tried and reverted in PR #891, or that three other files need the same change. Context window isn't the bottleneck — memory is. But GitHub already stores everything an agent needs: commits, PRs, issues, blame, cross-references. It's a citation graph; agents just don't use it as one. ForgeDock makes every stage write machine-readable annotations to issues and PRs, and every downstream agent read them. The gh CLI becomes the query interface to institutional memory. The result: agents that follow structured data, not vibes.
┌──────────────────────────────────────────────────────────────────┐
│ GITHUB (Knowledge Graph) │
│ │
│ Issues: FORGE:INVESTIGATOR → FORGE:CONTEXT → FORGE:ARCHITECT │
│ → FORGE:TRAJECTORY (the run's full audit trail) │
│ PRs: FORGE:BUILDER → structured review FINDING blocks │
│ Links: git blame → commit → PR → issue → related issues │
│ │
│ Every agent reads this. Every agent writes to it. │
│ Nothing is lost between conversations. │
└──────────────────────────────────────────────────────────────────┘
Not a staged demo — these are real, public runs on this repository. Open any of them and read the full trail:
- #1230 — the pipeline's staging review caught dead code in a feature the pipeline had shipped three hours earlier; review then caught a bug in the fix itself. Intent to merged: 30 minutes.
- #1172 — review found an
ANTHROPIC_API_KEYexfiltration path in the headless runner (an in-process file read bypassed the env scrub), with exact line evidence. Fixed and merged in 18 minutes, with regression tests. A later re-review found a second-order bypass of the first fix (#1243) — the pipeline red-teams its own fixes. - #952 — the investigator closed the pipeline's own proposal as INVALID with receipts: the deliverable had already shipped weeks earlier. Zero code written, 34 minutes, full explanation.
- #1256 — decomposition that respects the existing graph: it created only the two net-new sub-issues no open issue already claimed, then sequenced three existing issues into the dependency order.
- #1322 — a heavyweight feature (the durable execution engine itself): 9 TDD tasks, whole-branch review caught two Criticals pre-merge, merged in under 2 hours.
And the part that makes it compound — the context phase citing past bugs by number before a line is written (from #1196):
"
commands/orchestrate.mdhas a dense review-finding history from PR #1081/#1107/#1126… associative-array declaration mistakes (#1113), array-element removal via pattern substitution corrupting partial matches (#1108)… the new Layer 5 subsection should not introduce a competing edge-direction convention that could reintroduce a cycle class."
Numbers on this page are point-in-time (2026-07-04), from this repository's first 30 days of dogfooding. A reproducible cost-per-issue benchmark is a hard gate on our own launch plan — #1264: no estimated efficiency claims.
/work-on ships one issue. /orchestrate ships a milestone. It decomposes the milestone into dependency-ordered waves and runs a full /work-on pipeline on each issue in parallel — investigating, building, reviewing, and merging many at once, while GitHub labels track every agent's state live. On this repo's record day, that meant 29 issues taken to merged inside a single hour.
Scheduling is conflict-aware before it is parallel. Five detection layers decide what may run concurrently: same-file overlap, directory proximity, shared-module fan-in, a conservative fallback when file extraction is low-confidence, and historical co-change coupling mined from git log — files that changed together in the past are assumed to conflict now. Database-touching issues are always serialized. The resulting graph is cycle-checked (Kahn's algorithm) and executed in topologically sorted waves; overlapping work is expressed as ordinary Depends on #N edges anyone can read.
/orchestrate milestone/checkout-v2 # decompose → conflict-aware waves → merged PRsEach stage reads the structured output of the stages before it and writes its own findings back:
Issue → Investigate → Context → Architect → Build → Quality Gate → Review → Merge
└──────────── each stage reads & writes GitHub ────────────┘
| Stage | Reads | Writes |
|---|---|---|
| Investigate | Issue body, git blame, related issues/PRs |
FORGE:INVESTIGATOR — verdict, root cause, affected files, severity |
| Context | Historical findings from related PRs, known pitfalls | FORGE:CONTEXT — institutional memory for this module |
| Architect | Investigation + context | FORGE:ARCHITECT — ordered plan, code paths, risks |
| Build | Everything above | FORGE:BUILDER — branch, commits, files changed |
| Quality Gate | Builder output, domain-specific checks | gate results, recorded in the run's trajectory |
| Review | PR diff, contract, gate results | FORGE:REVIEW_STARTED on the issue; per-agent findings as structured FINDING blocks on the PR |
| Close | All of the above | FORGE:TRAJECTORY — the full audit trail of the run |
GitHub as the database. Every annotation is wrapped in an HTML comment (<!-- FORGE:INVESTIGATOR -->) that makes it machine-parseable. When an agent starts — even in a brand-new conversation after compaction — it queries the issue via gh and reconstructs full context from these tags. Workflow labels (workflow:investigating, workflow:in-review, workflow:merged…) track state, and the pipeline resumes from whatever state GitHub reports. The annotation format is an open standard — see the FORGE Annotation Protocol.
Durable by design. Headless runs are backed by a real execution engine, not prompt-hope: every phase transition is appended to an event-sourced, crash-safe run log, mirrored to the issue as a compact FORGE:STATE index, and guarded by leases so two agents can never own the same issue. Kill the process mid-run and restart it — the engine reconciles local state against GitHub (GitHub wins), adopts branches and PRs that already exist instead of re-running the LLM, and escalates to needs-human after bounded retries instead of looping. Phase selection is a pure rule-based state machine: the engine, not the model, decides what happens next. The headless core shipped in PR #1326; wiring the interactive path onto the same engine is in progress (#1323–#1325).
Domain-specialist review. Every PR is reviewed by agents with deep, narrow expertise — Security, Auth & Access Control, Billing Integrity, Database, Concurrency, Frontend, API, Performance, Infrastructure. Findings carry a confidence level, and a reproduction gate keeps them honest: a finding only blocks if the reviewer traced an actual code path or input that triggers it — pattern-match suspicions are downgraded, not merged into noise. Findings above the severity threshold are automatically filed as new issues that enter the same pipeline: on this repo, that loop produced 49% of all issues ever filed.
It measures itself. /pipeline-health correlates every prompt change against review-finding rates, build failures, and manual fix-up commits, then files its own report — including failing grades — as an issue. /autopilot pulls production signals (errors, CI failures, stale issues, analytics), files issues from them, and optionally runs /work-on on the top ones. The pipeline also invalidates its own bad ideas: proposals that turn out to be already-shipped or wrong are closed workflow:invalid with the reasoning attached (example).
Every mechanism above exists because autonomous agents fail in predictable ways. The skeptics are right about the failure modes — the answer is structure, not optimism:
| "We've all seen this go wrong…" | The mechanism |
|---|---|
| Parallel agents just turn typing time into reading time | Review is a pipeline stage: domain specialists with confidence ratings and a reproduction gate — not a pile of raw diffs |
| Agents game their own checks (or delete the tests) | Builders never grade their own work — the quality gate and reviewers are separate agents reading the diff cold |
| Third retry = increasingly creative excuses | Engine-owned state machine: bounded retries, then escalation to needs-human |
| One runaway agent wrecks the codebase | 1 issue = 1 agent, bounded by decomposition; conflict-aware scheduling; isolated worktrees |
| No institutional memory — "it can't read the Slack thread from 2023" | Every run writes citable annotations to GitHub; the context phase quotes past bugs by number |
| No way to tell when an agent drifts | A FORGE:TRAJECTORY receipt on the issue records what every phase actually did |
| Humans rubber-stamp 95%-good output | Specialist review raises the floor before a human looks at the PR |
| The economics are opaque | ForgeDock runs on your existing Claude account — it resells no compute and takes no per-task cut. Cost-per-issue benchmarks are tracked in the open (#1264) |
The core loop:
| Command | What it does |
|---|---|
/work-on |
Full issue lifecycle: investigate → build → quality gate → review → merge |
/orchestrate |
A whole milestone in parallel — conflict-aware waves, one pipeline per issue |
/issue |
Creates pipeline-ready GitHub issues |
/milestone |
Create, manage, and ship milestones |
/review-pr |
Context-aware PR review with domain-specialist agents |
/quality-gate |
Pre-commit checks, gated by the domains your change actually touches |
/test-gate |
Acceptance verification against running code before anything deploys |
Observe & recover — the durable-state story, as commands:
| Command | What it does |
|---|---|
/pipeline-status |
Fleet view of every in-flight issue, straight from workflow labels |
/pipeline-resume |
Resume an interrupted run from whatever state GitHub reports |
/diagnose |
Trace why a run failed, from its annotations |
/explain |
Translate the FORGE annotations on any issue into plain language |
/replay |
Replay a past run's full audit trail |
/changelog |
Release notes assembled from merged PRs and trajectory receipts |
Ops:
| Command | What it does |
|---|---|
/deploy-info |
Staging vs. main diff with risk assessment |
/rollback |
Automated revert PR for production incidents |
/autopilot |
Production signals → triaged issues → fixes |
/security-audit |
Multi-phase security posture audit |
/cleanup |
Sweeps stale issues, branches, worktrees |
More ship today (web-property analytics, browser QA sweeps, self-benchmarking) — see the full command reference. A leaner, tiered install that keeps the core loop front and center is planned in #1257.
Requirements: Claude Code · GitHub CLI (authenticated) · Node.js ≥ 18.
npx forgedock # checks your environment, installs commands into ~/.claude/commands/ (available in every Claude Code session on this machine), detects your repo, and hands you a reviewed forge.yamlInstall is always global, to ~/.claude/commands/. --global is still accepted on the command line for backward compatibility but has no effect — there's no other install location to opt out of.
Want engine-mode dispatch?
npx forgedockis transient — theforgedockbinary isn't persisted in PATH after install./orchestrateand/autopilotuse agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (forgedock run-issue) with its durable phase table and fail-closed review gate, runnpm install -g forgedockinstead.
One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated forge.yaml to review — press Enter to accept. Run npx forgedock init any time afterward to re-generate the config only.
Installing also registers a SessionStart hook, so every Claude Code session
in a forge-managed directory starts already knowing ForgeDock runs it.
Per-directory control: npx forgedock enable / disable / status.
Then just open Claude Code and run /work-on <issue>.
Cost: ForgeDock is free and open-source. It orchestrates sessions on your Claude account — no compute resold, no per-task markup. A typical
/work-onrun on a straightforward bug costs about what a 15–20 minute manual Claude Code session does.
Other install options & commands
Claude Code plugin marketplace (Claude Code v2.1.143+):
/plugin marketplace add RapierCraftStudios/ForgeDock
/plugin install forgedock@forgedock
Commands then appear as /forgedock:work-on, etc. You still run npx forgedock init to generate forge.yaml.
Headless / CI: the pipeline also runs outside Claude Code. npx forgedock run work-on <issue> --dry-run previews the assembled prompt and tool plan. npx forgedock run picks an execution backend automatically (--backend auto, the default): if the Claude Code CLI (claude) is installed and already authenticated (Pro/Max subscription or a CLI-managed key), it drives the command through that — no separate ANTHROPIC_API_KEY required. Otherwise it falls back to the Anthropic API directly (ANTHROPIC_API_KEY required). Force either path explicitly with --backend cli / --backend api (or FORGEDOCK_BACKEND=cli|api) — the API backend is what CI environments without an interactive claude login should use. npx forgedock run-issue <issue> executes the same command specs on the durable engine (event-sourced run log, leases, crash-safe resume).
Explicit install command:
npx forgedock install # installs into ~/.claude/commands/
npx forgedock install --global # same thing — --global is accepted but is a no-opMaintenance:
npx forgedock update # relink commands + refresh the SessionStart hook
npx forgedock enable # turn ForgeDock on for this directory
npx forgedock disable # turn ForgeDock off for this directory
npx forgedock status # show ForgeDock's state for this directory
npx forgedock doctor # installation health check with fix hints
npx forgedock report # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
npx forgedock uninstall # remove commands, the hook, and tracked copies
npx forgedock help # show everythingRunning
npx forgedockfrom inside this repo uses the local working tree. From your own project, usenpx forgedock@latestto pin the published release.
A note on install location
ForgeDock briefly experimented with a project-scoped-by-default install mode. It was backed out after causing a "split-brain" bug (detect assumed project-scoped while the installer still wrote globally — #1589), so every version you'd realistically install today only ever writes to ~/.claude/commands/. --global is still accepted as a flag for old scripts/muscle memory, but it changes nothing.
If you're carrying an older --global habit in scripts or CI, it's harmless to leave it — npx forgedock --global and npx forgedock do exactly the same thing.
The core is AGPL-3.0 and stays that way: engineers run the full pipeline on their own Claude account, forever free.
Two things are for sale:
- A commercial license — for organizations that need ForgeDock inside proprietary workflows or products without AGPL copyleft obligations. Contact support@rapiercraftstudios.com.
- The fleet layer (in development) — org-wide observability over every pipeline run: the receipts on this page, live, across all your repos, plus policy controls and audit-grade provenance for autonomous merges. We're onboarding a small group of design partners — see ForgeDock for Companies for details and intake.
Month one built the execution layer. The open roadmap — tracked in the five-foundations epic (#1320) — is about earning trust while unattended:
- Durability — engine-owned state instead of prose-owned state. Headless core shipped (PR #1326); interactive wiring in progress.
- Verification — an outcome-based acceptance gate and a graded eval corpus, so "done" is machine-checkable before anything claims success. Per-release pipeline scorecards are published in
docs/eval/; model upgrades follow the model-release playbook. - Learning — per-codebase memory that compounds across runs.
- Economics — per-run cost accounting and risk×cost dispatch decisions.
- Provenance — signed, replayable records of every autonomous change.
Marketing is held to the same standard: #1264 gates our own launch on measured cost-per-issue benchmarks — no estimated claims.
Using ForgeDock in your pipeline? Add the badge — each one is a backlink and a signal to other developers:
[](https://github.com/RapierCraftStudios/ForgeDock)
- GitHub Is Already Your Agents' Memory — the canonical argument: why GitHub is the right place for agent memory, how FORGE annotations make it machine-readable, and how to adopt the protocol without ForgeDock
- Getting Started in 5 Minutes
- How the Knowledge Graph Works
- What Are Those FORGE Comments? — 2-minute explainer for annotations you meet in the wild
- FORGE Annotation Protocol — the open standard for AI context passing (CC-BY-4.0)
- ForgeDock vs. Manual Claude Code Workflows
- ForgeDock vs. DeepWiki, AGENTS.md, and Cursor Memories
- Command Learning Path — which commands to learn first
- Complete Command Reference
- Troubleshooting & Recovery
- Pipeline Eval Scorecards — per-release published results for every model/Claude Code upgrade
- Model-Release Upgrade Playbook — how to validate a new model before adopting it
Contributing: PRs welcome — every change goes through a PR, tested against 3+ scenarios, using conventional commits (fix(command):, feat(command):). License: AGPL-3.0 — free to use, modify, and distribute; network use of modifications must be open-sourced under the same license. Commercial licenses are available for proprietary use — see COMMERCIAL-LICENSE.md.
Built and dogfooded in production by RapierCraft Studios.