Fagan
Fagan's MCP server lets you orchestrate, inspect, and gate autonomous coding work across plans and stories.
Probe and persist subscription usage.
Inspect effective role/model and env-var configuration with provenance.
Decompose goals into epics/stories; save, list, and ingest plans, optionally mirroring them to Plane.
Find ready stories; dispatch, interrupt, resume, checkpoint, and status-manage story agents.
Patch story/plan fields and set sanctioned story statuses without hand-editing manifests.
Request and list overlord rulings for blocked decisions.
Review branches, open PRs, approve gated merges, and run scheduler-like pipeline ticks.
Pause/resume individual plans or advance all ingested plans.
Inspect in-flight story worktree diffs.
Approve/reject plans and record/verify security-audit chains.
Fagan
Spend tokens on judgment, not typing.

A real story (STE-1, PR #986) crossing the board: implemented by an open-weight model, sent back once by review, merged. 14 minutes, time-lapsed.
Try it (macOS; Linux via Ollama or LM Studio), then see the Quickstart:
curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bashFrontier models cost money per token and are excellent at judgment. Local models run free and are adequate at typing. This pipeline splits software engineering along exactly that line: a frontier model decomposes the work, plans it, reviews the diff, and adjudicates anything risky — while a local model writes the implementation at no marginal cost.
What makes the cheap half trustworthy is inspection. In Michael Fagan's 1976 IBM study, formal inspection found 82% of the defects in the released product — 38 per KLOC, against 8 per KLOC for unit testing. Quality lives in the gate, not in the author. So this project spends its budget on gates: TDD enforced before implementation, an independent review pass, acceptance-oracle grading, a risk-tiered overlord that stops for a human on anything irreversible, and a merge gate that re-runs the suite against the rebased branch before anything lands.
The goal is narrow and specific: enterprise-grade engineering discipline — decomposition, TDD, code review, dependency-ordered delivery — on a $20/month budget.
For detailed reference material, see REFERENCE.md.
Before you start: read Reliability & limitations below. This is an autonomous coding pipeline with real, documented failure modes — it is not a hands-off "describe a feature, get a PR" tool yet.
Platform support
Developed and run day-to-day on macOS. The core (MCP server, dashboard, Claude-backend dispatch/review, the full test suite) is plain Python and CI tests it on Ubuntu across Python 3.11–3.14 on every pull request and push, plus macOS on 3.14 on every push to master and nightly. Two pieces are macOS-only:
launchd/*.plist— the scheduler/MLX-supervisor/usage-poller are packaged as launchd jobs on macOS. On Linux, render the systemd equivalent withscripts/generate_systemd_units.sh(see Scheduler below) instead of hand-rolling init files, or run the entry points directly in a foreground terminal/tmuxsession.MLX (
PIPELINE_LOCAL_PROVIDER=mlx) — Apple Silicon only. Local dispatch works fine on Linux via Ollama or LM Studio instead (PIPELINE_LOCAL_PROVIDER=ollama/lmstudio).
Windows is untested.
Related MCP server: Spine
Quickstart
One-line install
curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bashThis clones the repo to ~/.fagan (override the location with
FAGAN_INSTALL_DIR, and the source URL with FAGAN_REPO_URL) and runs
scripts/install.sh inside it -- equivalent to the manual clone-and-run
steps below, minus the typing. Re-running it later updates the existing
checkout (git pull --ff-only) instead of re-cloning.
Piping a remote script into bash means trusting whatever that URL serves
at fetch time. If you'd rather read it first:
curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh -o remote-install.sh
less remote-install.sh # or open it in an editor
bash remote-install.shEither way, cd into the install directory it reports (~/.fagan by
default); it has already done steps 1–3 below, so restart Claude Code (step 5). Prefer a manual clone? Use the
steps below instead.
This gets the MCP server registered and a first plan running end-to-end.
A first run needs no local model at all: with nothing configured, dispatch
and review fall back to the claude backend, which shells out to the Claude
Code CLI. That fallback is the starting configuration, not the intended one
— the cost split described above only happens once you deliberately route
the implementation role to a local model, which is why the shipped registry
ships no roles block of its own: see Provider selection & authorization
below for how to make that choice when you're ready.
# 1. Clone and install the Python environment
git clone https://github.com/motock/fagan.git
cd fagan
scripts/install.sh # creates .venv, installs requirements.txt
# 2. Register the MCP server with Claude Code (adjust the path to where you cloned it)
claude mcp add -s user pipeline "$(pwd)/.venv/bin/python3" "$(pwd)/app/pipeline_mcp_server.py"
# 3. Copy the persona subagents and decision policy into place
# (cp -n skips any file you already have — e.g. a customized code-reviewer.md —
# instead of silently overwriting it; diff before removing -n if you do want the update)
mkdir -p ~/.claude/agents
cp -n agents/*.md ~/.claude/agents/
cp -n overlord-policy.md ~/.claude/overlord-policy.md
# 4. (Optional) Install the global rules bundle for your agent CLIs
# scripts/install_global_rules.py --tools=claude,codex,opencode
# Opt-in: nothing is written unless --tools is passed. It writes the bundle into
# ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md, copies
# the rule files into the sibling fagan-rules/ directory, and backs up an existing
# file as <name>.fagan-bak-<UTC timestamp>. Re-running refreshes only the fenced
# block between the fagan:begin and fagan:end markers.
# 5. Restart Claude Code (or start a new session) so it picks up the MCP serverscripts/install.sh creates the .venv, installs requirements.txt and
requirements-dashboard.txt (the dashboard's fastapi/uvicorn deps, installed
on every run; a --dev install uses requirements-dev.txt, which already
includes the dashboard deps), and reports on the tools the pipeline shells out
to — required: git, gh, and the claude CLI; optional: ollama and
docker — with graceful-degradation messaging, and is safe to re-run. It does not register the MCP server, set environment
variables, or install the persona subagents — steps 2–3 above cover those. With
nothing but the claude backend configured, ollama/docker being absent is
expected, not an error.
From a Claude Code session in the project you want the pipeline to work on:
Ask the
product-analystsubagent to turn a goal into epics/stories, or hand-write a plan per the schema.mcp__pipeline__save_plan(oringest_plan) with that plan and arepo_rootpointing at the target project — not this pipeline repo.mcp__pipeline__list_ready_storiesto see what's unblocked, thenmcp__pipeline__dispatch_storyto claim and start one.Watch progress with the dashboard:
scripts/dashboard.sh start, then openhttp://localhost:8000.For unattended operation, run the scheduler so ready stories advance without you calling
advance_pipelineby hand:.venv/bin/python3 -m pipeline.scheduler_daemon(foreground, or under launchd/systemd/tmux — see Scheduler below).
Start with PIPELINE_AUTONOMY=dry-run (plans and logs only, nothing is
dispatched or merged) until you've watched one plan run and trust the gates —
see Autonomy levels.
Only using the claude backend? The PIPELINE_LOCAL_* and
PIPELINE_BACKEND_*=ollama/lmstudio/mlx variables, and Ollama/MLX/LM Studio
setup, only matter if you opt a role into local-model dispatch — but provider
selection itself is still a required setup step (the shipped registry routes
nothing; see Provider selection & authorization below), and even the
claude path needs two credentials before the first dispatch: gh auth login
(the pipeline opens and merges PRs through the GitHub CLI) and the Claude Code
CLI's own login. See
Minimal configuration for the handful of
variables actually worth setting on day one, versus the ~100 that exist purely
for tuning.
Provider selection & authorization
Provider selection is a required setup step. The shipped
model_registry.json deliberately declares which models exist per provider
but ships no roles routing: this project decouples from any single
provider, so the operator chooses. There are two supported ways to select a
provider per role, checked in this order by resolve_role:
Plan role config — a plan's per-role
provider/modelbeats everything below.A
rolesblock in a registry file — the single source of truth for role routing; see below.PIPELINE_BACKEND_<ROLE>environment variables — consulted only when the registry has no entry for the role (the empty-state path, so a fresh clone still boots); e.g.PIPELINE_BACKEND_DISPATCH=ollamaopts the dispatch role into Ollama.The caller's own fallback — for dispatch/review this is the
claudebackend.
For an interactive alternative to editing registry JSON by hand, run the
picker: .venv/bin/python scripts/choose_providers.py. It walks through all
nine roles one at a time, showing each role's current provider/model and where
that setting came from, and lets you switch it by typing an option number —
each of the nine roles is configured independently, and every change is
validated against the registry before it is written. It is safe to re-run any
time: re-running just re-reads the current routing, and pressing Enter keeps a
role's existing setting.
The same two registry files work for both selection styles:
PIPELINE_MODEL_REGISTRY_PATHpoints the pipeline at any registry JSON you like.model_registry.local.json(repo root) is the convention for a personal registry: it is gitignored, so your per-role routing stays out of the repo. PointPIPELINE_MODEL_REGISTRY_PATHat it, or copy it overmodel_registry.jsonlocally if you prefer not to set the variable.
A roles block names a provider and a friendly model name per role; the
friendly name must exist under that provider's models in the same file, and
the concrete tag is resolved from there. A typo raises an error rather than
silently falling back.
Authorization matrix. Selecting a provider also selects which credentials
you must establish first — scripts/install_checks.py probes these and
reports unauthorized (remedy: a login, not an install) where it can:
Provider / tool | Credential needed | How to establish it |
| GitHub auth (the pipeline opens and merges PRs through |
|
| Claude Code CLI's own login |
|
any | An ollama.com account, signed into the local daemon |
|
| Per-vendor API keys | |
on-device ollama / lmstudio / mlx tag | Nothing extra | — |
On the :cloud rows: those calls are proxied through https://ollama.com by
the local ollama daemon, which sends its own credential — the pipeline sends
no credential of its own. :cloud tags are the only ollama tags that need
a sign-in; purely on-device tags need nothing beyond the daemon running.
Getting-started walkthrough
The walkthrough works with whatever dispatch provider you have configured —
PIPELINE_BACKEND_DISPATCH (set it explicitly, or add a roles block to a
local registry — the shipped registry routes nothing; see Provider selection
& authorization above). With claude configured, dispatch and review shell
out to the Claude Code CLI; with a local provider such as ollama configured,
they run on that local model instead.
Install — one command:
scripts/install.sh(see the quickstart above for what it does and does not do).Register the MCP server and personas — quickstart steps 2–3 above (
claude mcp add ...plus copyingagents/*.mdand the overlord policy), then restart Claude Code.Start the dashboard —
scripts/dashboard.sh start, then openhttp://localhost:8000and pick your target project in the workspace picker.Decompose a tiny goal — ask the
product-analystsubagent (or the dashboard's decompose action) to turn a one-liner goal into epics/stories, thenmcp__pipeline__save_planthe result with itsrepo_rootfield pointing at your target project — not this pipeline repo.Dispatch the first ready story —
mcp__pipeline__list_ready_stories, thenmcp__pipeline__dispatch_storyon the first one, and watch the story advance across the kanban board in the dashboard.Watch it merge — with
PIPELINE_AUTONOMY=gated(the default), a risk-lowstory that passes review merges unattended. Start withPIPELINE_AUTONOMY=dry-runfirst, per the quickstart advice above. SetPIPELINE_AUTO_MERGE=0to keep everything automatic except merging; merges then happen only viaapprove_mergeor by hand.Prefer the scripted path? —
.venv/bin/python scripts/smoke_getting_started.pyruns the same flow end-to-end without the dashboard, in a scratchPLAN_DIRthat never touches your real plans. The smoke is provider-neutral: it runs on your configured dispatch provider (PIPELINE_BACKEND_DISPATCH, defaultclaude) and announces the resolved provider, model and source up front, so you always know which backend it validated. Exit codes:0PASS (the story reachedtests_passed),1the resolved provider isclaudeand theclaudeCLI is missing, exit 2 means the configured provider is empty or unrecognised — a configuration error, not a refusal of a local provider —3the bounded poll timed out,4the story failed. Honest caveat: PASS depends on the configured model actually completing the story, so a failure on a weak local model reflects that model, not a broken pipeline.
For what can still go wrong, see Reliability & limitations.
Companion MCP server (overlord + acceptance-oracle only)
Not ready to adopt the whole orchestrator? pipeline/companion_server.py is a
second, smaller MCP server (pipeline-companion) exposing two ideas that
stand on their own without adopting the rest of the pipeline:
escalate_decision (the overlord decision path) and the acceptance-oracle
helpers classify_oracle_outcome / acceptance_digests. It imports the real pipeline.overlord and
pipeline.oracle_gate modules rather than duplicating them, so it stays in
sync with the main server. Add it alongside the main server as a second
mcpServers entry:
{
"mcpServers": {
"pipeline": {
"command": ".venv/bin/python3",
"args": ["app/pipeline_mcp_server.py"]
},
"pipeline-companion": {
"command": ".venv/bin/python3",
"args": ["-m", "pipeline.companion_server"]
}
}
}The adoptable specs this server exports live in docs/specs/:
OVERLORD_POLICY_SPEC.md (the overlord decision path),
ACCEPTANCE_ORACLE_PATTERN.md (the acceptance-oracle grading pattern), and
DOCKER_SANDBOX.md (the opt-in Docker sandboxing behavior).
Running the Docker server (Keycloak sign-in, TLS, remote MCP)
This is the production-style deployment — Keycloak sign-in, Caddy TLS and the
remote MCP transport — installed on a clean Docker machine with
bash deploy/install.sh. The operator guide is
docs/DEPLOY_STANDALONE.md. Plan approval is ON by
default for this stack (PIPELINE_PLAN_APPROVAL, see §6 and §7 of that guide),
so a newly ingested plan dispatches only after its owner or a delegate runs
approve_plan. This is not the scripts/standalone-setup.sh flow below: that
one starts the dashboard and scheduler directly and never registers an MCP
server.
Running standalone (dashboard + scheduler, no MCP server)
The dashboard exposes the same operations as the MCP tools — save/ingest a plan,
decompose a goal, dispatch a story, advance, review, approve merge — so the
pipeline can run without registering an MCP server at all. That parity lives at
the HTTP API, not in the UI: the dashboard UI directly surfaces chat (including
drafting a plan), browsing plans, stories, journals and logs, the workspace
picker, the worktree-patch review/apply flow, role configuration, and ingesting a
saved plan. Dispatch, advance, review and approve-merge have UI-less API routes
(/api/plans/{plan_name}/stories/{story_key}/dispatch and friends) available for
scripting, and for the standalone flow the scheduler is the intended driver:
draft and ingest a plan from the dashboard, then let the scheduler dispatch,
advance, review and merge ready stories on its own. The
supported path is one command:
scripts/standalone-setup.sh upup provisions a scratch data dir (default ~/pipeline-standalone), writes
the shared operator env file with absolute paths, starts the dashboard and the
scheduler through their existing helper scripts, and then refuses to report
success until GET /api/health answers with an empty config_mismatch and
the intended plan_dir. Main options: --data-dir DIR (default
~/pipeline-standalone), --target-repo DIR (default: a scratch repo under
the data dir), --port PORT (default 8001), --autonomy MODE (default
dry-run), plus --repo-root and --force. down stops both processes and
leaves the scratch data in place; status prints the resolved paths and both
processes' state.
Both long-running processes read the same operator env file:
scripts/dashboard.sh and scripts/scheduler.sh both source
.pipeline.env (gitignored; see .pipeline.env.example) first, then
.dashboard.env (gitignored; see .dashboard.env.example) second, so
existing dashboard-only installs keep their current last-write precedence —
.dashboard.env still works and simply overrides .pipeline.env where they
overlap.
Because the dashboard and the scheduler are separate processes, PLAN_DIR
must match between the two: the scheduler writes a config fingerprint to
<plan_dir>/.scheduler_health.json, and /api/health reports
config_mismatch listing the fields where the dashboard's resolved config
differs from that fingerprint. A non-empty config_mismatch means the UI and
the scheduler are working different plan stores — check that both were
started with the same PLAN_DIR (the standalone script writes one env file
for exactly this reason, and fails hard on a non-empty config_mismatch).
The normal prerequisites still apply in standalone mode: gh auth login for
the PR/merge path (the pipeline opens and merges PRs through the GitHub CLI),
and provider authorization for whichever backend is configured — see
Provider selection & authorization above.
Guided configuration (one command)
scripts/install.sh finishes by running scripts/configure.py, which detects what is already set up and writes .pipeline.env, role routing, and (optionally) background services. It prompts only when both stdin and stdout are TTYs; --yes and piped installs (curl ... | bash) apply secure defaults and never prompt.
Pass --dry-run to print the plan without writing anything. Every flag, key, and default is documented in docs/guided-setup.md.
Components at a glance
Piece | Location | Role |
Persona subagents |
| The SDLC roles agents play |
Decision policy |
| How the overlord decides |
Pipeline MCP server |
| All pipeline tools + orchestration; |
Backend seam |
| Per-role driver routing ( |
Local agent loop |
| Native-tool-calling write loop for local dispatch (subprocess) |
Monitoring dashboard |
| FastAPI status/lifecycle viewer; in standalone mode (see "Running standalone" above) it also drives save/ingest/dispatch/review/merge directly |
Install / deps |
| venv + dependency setup |
Tests |
|
|
Plans / manifests / logs |
| Plan, manifest, decisions, notifications |
Worktrees |
| Isolated per-story branches |
Issue tracker | Plane (external, optional) | Mirror of story state; skipped entirely when unconfigured (manifest is the source of truth) |

The dashboard's Comms view — ask what's blocked, draft a plan, or approve a merge, all routed through the same gated API the kanban board's own buttons call. More screenshots (the live kanban board and the workspace picker) are in docs/DEMO.md.
Beyond the core loop
Not just Python. The test, lint and build gates detect the target repo's ecosystem from its build files, and a committed
.fagan.jsondeclares the commands for anything they can't detect. See Test, lint and build commands.Notifications. Every pipeline event goes to a per-plan notification log. Opt in to e-mail (
PIPELINE_NOTIFY_EMAIL_ENABLED=1) and the scheduler sends plan completions, parked stories, and dispatch, test and agent failures through an outbox that keeps undelivered messages for the next attempt. See Notifications.Review from the dashboard. Each story's modal shows a read-only diff of its worktree against its fork point (also the
get_story_difftool), a stuck story can take a proposed patch through patch review and apply, and the plan list scopes to the active repository. The same diagnosis is reachable over MCP:get_story_log,get_story_journal,get_story_worktreeandget_story_eventsare plan-scoped reads that redact secret values before returning them, and none of them takes a path argument, because the plan name and story key name the story.unblock_storyis the matching mutation, held to the plan's owner or a delegate, and it resets plan approval when it changes the story's brief or files.Cross-plan coordination. A story can wait on a story in another plan (
blocked_by), and the pipeline warns when two plans' in-flight stories edit the same files. See Cross-plan coordination.Human-gated merges.
PIPELINE_AUTO_MERGE=0keeps dispatch and review automatic but parks every reviewed PR for you to merge, withapprove_mergeor by hand.Where agents run. Opt-in Docker sandboxing, remote dispatch or review over SSH, and LiteLLM routing to hosted vendors.
Stuck-story handling. The scheduler flags an in-progress story whose agent has gone quiet (30 minutes by default), and with
PIPELINE_AUTO_TRIAGE=1the overlord rules on a failed or parked story: escalate the model, split the story, patch a broken acceptance fixture, or hold it for you.pause_planstops one plan without touching the others.
Architecture
┌────────────────────────────────────────────────────────────────────────┐
│ Scheduler daemon (or a manual advance_pipeline call) │
│ advance_pipeline(plan) — one idempotent tick │
└────────────────────────────────────────────────────────┬───────────────┘
ready stories (deps satisfied) │
▼
┌───────────────┐ resolve backend + ┌───────────────────────────────┐
│ Plan/Manifest │ persona/model │ Dispatch │
│ (JSON, Plane) │───────────────────────►│ claude -p OR local loop │
└───────────────┘ │ (tech-lead plans for local → │
│ .agent_plan.md) │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ Headless story agent, TDD- │
│ first, in an isolated git │
│ worktree │
└───────────────┬───────────────┘
local fail → escalate │ tests +
to claude (`auto`) │ acceptance oracle
▼
┌───────────────────────────────┐
│ code-reviewer: VERDICT, │
│ opens a PR │
└───────────────┬───────────────┘
▼
low → decide silently ┌───────────────────────────────┐
medium → decide, notify the user │ Overlord adjudicates risk │──► decisions log
high → park, wait for a human │ (blocked decisions, merge, │ (audit trail)
│ scope disputes) │
└───────────────┬───────────────┘
▼ approved
┌───────────────────────────────┐
│ Merge gate: rebase on master, │
│ force-push, poll CI, re-run │
│ the suite on the rebased │
│ branch │
└───────────────┬───────────────┘
▼
masterPersonas (~/.claude/agents/)
Each persona is a Claude Code subagent: a markdown file with YAML frontmatter
(name, description, model, and optionally memory: user) and a
system-prompt body. The pipeline reads the body and dispatches a headless agent
with it as the role.
memory: user injects the user-memory directory into the system prompt on
every Claude call — high-leverage context but expensive in tokens. The
reviewer personas (code-reviewer, security-engineer) deliberately omit
it: their job is a mechanical check (run tests, read diff, emit VERDICT),
the CLAUDE.md rules they need are in the persona body, and skipping the
~132 KB memory injection shaves ~30-40% off every review call's input tokens.
The dispatch and overlord personas keep it because they benefit from project
context and are lower-volume.
Persona | Default model | Responsibility |
| opus | Decompose a goal into epics/stories with acceptance criteria, dependencies, and per-story |
| opus | General system design, tech selection, API design (delegates mobile to |
| sonnet | Default TDD implementer for non-mobile work |
| opus | Threat modeling and security review (OWASP, Secure by Design) |
| sonnet | Build/CI, branch & worktree hygiene, releases |
| sonnet | Reviews a branch, emits a |
| haiku | Docs for externally visible changes |
| sonnet | The decision authority (see below) |
Existing mobile specialists (mobile-architect, mobile-engineer,
ux-mobile-principal, qa-test-engineer) are unchanged and used for mobile work.
To change a persona's behavior or default model, edit its .md file. The
frontmatter model: line is the fallback model when a story does not specify one.
The overlord and the decision policy
The overlord (~/.claude/agents/overlord.md) rules on the user's behalf when
a story agent is blocked, two personas disagree, or a gate needs adjudication. It
follows ~/.claude/overlord-policy.md (plus an optional per-repo
<repo>/.overlord-policy.md override).
Decision tiers:
Routine / reversible → decide silently (naming, internal structure, a library within the approved stack, refactors).
Notify-async (
risk: medium) → decide, proceed, flag the user (new dependency, schema change, additive API change).Park-and-ping (
risk: high) → do not act unattended; hold for human review and notify. Anything irreversible, security/auth, money, production config, or breaking changes. Held for a human in dry-run and gated; infullthe overlord adjudicates it and records the ruling for post-hoc audit. Aproceedruling merges only when the plan's triage mode isexecute; inshadow(the default) the ruling is recorded and the merge is held for a human.
The overlord returns a structured ruling (RULING / TIER / RISK /
RATIONALE / NOTIFY_USER) that is parsed and written to the plan's decisions
log as an audit record.
Reference
See REFERENCE.md for the full MCP tools reference, the plan/story JSON schema, per-role provider/model configuration, guided decomposition and TDD-split details, every PIPELINE_*/LOCAL_AGENT_* environment variable, the end-to-end workflow, safety controls, the usage gate, and development/testing instructions.
For a worked end-to-end example of the pipeline developing this repository itself — the install command, the real pull requests it produced, and an honest account of what it can't do yet — see docs/DEMO.md.
For how a release is cut, see docs/RELEASING.md.
For the one-command guided setup (flags, configuration keys, secure defaults, troubleshooting), see docs/guided-setup.md.
Prerequisites
Python 3.11+ and the project venv. CI tests 3.11–3.14 on Ubuntu and 3.14 on macOS on every push to master and nightly.
git on PATH.
Claude Code CLI (
claude).The active forge's CLI —
PIPELINE_FORGEselects the code host (auto|github|gitlab, defaultauto, resolved from the origin remote's hostname):ghforgithub,glabforgitlab. An unknown value raises.
Scheduler
The advance-scheduler runs as a long-lived daemon rather than a periodic
launchd tick. launchd's role is limited to crash-restarting it via KeepAlive.
Environment Variables
PIPELINE_SCHEDULER_INTERVAL_S – default reconcile sweep interval (default 60 seconds).
PIPELINE_SCHEDULER_HEALTH_PATH – optional path where the daemon writes its health JSON each iteration.
Rendering the launchd files for your machine
The committed launchd/*.plist files and launchd/pipeline-logs.newsyslog.conf
are a reference copy: they carry the maintainer's own absolute paths (a
/Users/<name>/... home directory, a specific model cache path) and will not
work unedited on another machine. On a fresh install, regenerate them yourself
with scripts/generate_launchd_plists.sh (the guided setup renders these for you only when you opt into background
services) — it fills the templates in launchd/
(launchd/com.fagan.pipeline.*.plist.template) from three flags:
--repo-root— the pipeline checkout the rendered files should point at (default: the repo that contains the script).--out-dir— where the rendered files are written (default:<repo-root>/launchd).--mlx-model-path— the local MLX model directory baked into the mlx-supervisor plist. As an alternative to the flag you can set theMLX_MODEL_PATHenvironment variable; the flag wins when both are given. The script fails closed — it exits with an error — when neither is supplied.
The same script also renders launchd/pipeline-logs.newsyslog.conf from
launchd/pipeline-logs.newsyslog.conf.template, substituting only the repo root.
scripts/generate_launchd_plists.sh \
--repo-root "$HOME/.claude/mcp-servers/pipeline" \
--out-dir "$HOME/.claude/mcp-servers/pipeline/launchd" \
--mlx-model-path "$HOME/.cache/qwen2.5_coder_14b_manual"These launchd files are macOS-only - see Platform support.
Rendering the systemd units for Linux
scripts/generate_systemd_units.sh renders the equivalent systemd user-unit
and logrotate files from systemd/*.template, the same way
scripts/generate_launchd_plists.sh does for launchd – minus MLX, which is
Apple Silicon-only:
scripts/generate_systemd_units.sh \
--repo-root "$HOME/fagan" \
--out-dir "$HOME/fagan/systemd"Install as per-user systemd units (no root required):
mkdir -p ~/.config/systemd/user
cp systemd/com.fagan.pipeline.advance-scheduler.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now com.fagan.pipeline.advance-scheduler.service
systemctl --user enable --now com.fagan.pipeline.usage-poller.timer
# Optional: let these run even when you are not logged in
loginctl enable-linger "$USER"Log rotation (needs root, one-time):
sudo cp systemd/pipeline-logs.logrotate.conf /etc/logrotate.d/com.fagan.pipelineReliability & limitations
This pipeline runs real autonomous coding loops, and they fail in specific, documented ways — read this before pointing it at anything you care about.
Local (non-Claude) model dispatch is the weak point. It works well for small, mechanically-scoped stories (one concern, ≤2 production files) and degrades sharply on anything bigger: large-file edits, multi-function stories, and anchored inserts into long existing functions reliably cause step-cap timeouts, stalls, or file corruption from stale line-number edits.
docs/plans/*.mdandretros/*.mdin this repo are the actual incident record this finding comes from, not a marketing claim — read a few before trusting local dispatch on anything non-trivial.PIPELINE_BACKEND_DISPATCH=autoexists specifically to escalate a struggling local attempt to Claude rather than let it loop.The "$20/month" framing is the design goal the gates are built around, not a benchmarked result yet. The one full model-comparison run on record (
tests/benchmark/FINDINGS.md) was contaminated mid-run by rate limits and credit exhaustion, so there is no clean apples-to-apples success-rate/cost comparison across backends published yet. The cleanest number there is narrow —gpt-oss:20bon-device, 2 T1 tasks, 2/2 success with the independent oracle passing on the merged code, one trial each — and is directional, not a quality comparison. Read that file for exactly what is and isn't known before citing a number from it.A green test suite is not proof of a correct or complete change. An executor (local or Claude) converges to the minimum diff that turns its own tests green, and can write a self-consistently wrong test that encodes the same bug as its implementation. See
.claude/rules/code-review.md's "Merge-gate and AI-review lessons" section — every lesson there came from a real merged regression, not a hypothetical.A story marked
doneis not proof its title's full scope shipped. A "migrate everything" or "remove all X" story can pass review and merge having only done part of the job, because review grades the story's own tests, not the title's claim. See.claude/rules/agent-dispatch-story-sizing.md.The overlord's
park-and-pingtier is a real safety floor, not a suggestion — high-risk decisions (irreversible actions, auth/security, money, production config, breaking changes) stop for a human indry-runandgated; infullthe overlord adjudicates the high-risk merge hold and records the ruling for post-hoc audit. Aproceedruling merges only when the plan's triage mode isexecute; inshadow(the default) the ruling is recorded and the merge is held for a human. Start any new deployment atPIPELINE_AUTONOMY=dry-runand read the decisions log before trustinggatedorfull.This is a single-maintainer research project, not a maintained product with an SLA. The test suite and CI are real gates, but expect rough edges, and expect the failure-mode catalog to keep growing as new ones are found.
If you hit a new failure mode, it's worth documenting (see retros/ for the
existing format) rather than working around it silently — the whole value of
this project's design is that failure modes get named and fed back into how
stories are sized and reviewed.
License
Fagan is licensed under the GNU Affero General Public License, Version 3.0
only — see LICENSE and NOTICE. Releases through commit
98550bb were licensed Apache-2.0; LICENSE-APACHE is the
text that governed those releases.
Fagan Enterprise — the standalone server distribution — is offered under separate commercial terms. The AGPL of this repository governs the open-source core; if you run an unmodified build as a network service, AGPL §13 asks that you offer users the source, and pointing here at the exact commit you run suffices for unmodified builds.
Available Tools
40 toolsadvance_all_plansA
Run advance_pipeline on every plan that has been ingested (has a manifest), keyed by plan name. Plans saved but not yet ingested (no manifest) are skipped. Intended for a recurring scheduler (cron/launchd or /loop) so newly ingested plans are picked up automatically with no hardcoded plan name to maintain.
NOTE on zombie reaping: the per-plan advance_pipeline polling phase already handles dead-pid in_progress stories via check_story_status (which falls through to test-running on dead pids). Running an external reap pass BEFORE the polling would clobber that and silently leave stories re-dispatching forever without ever running the test (manifest observation 2026-06-28: 3 e2e stories hit dispatch_attempts= MISSING because the reap ate the polling opportunity). The reap helper _reap_zombie_in_progress_stories is kept for callers that need a one-shot cleanup (e.g. tests, ops CLI) but is NOT wired in here.
Inputs: no named parameters. Returns: object
advance_pipelineA
Run one orchestration tick: dispatch every ready story (deps satisfied), advance finished stories through test -> review -> PR, and adjudicate merges against the risk threshold. Idempotent; designed to be called repeatedly by a scheduler (/loop or cron). In PIPELINE_AUTONOMY=dry-run it plans and logs only, taking no actions.
Honors a per-backend resource gate: dispatch and review are gated independently by their own backend's resource_status() (see _role_resource_ok). If the dispatch backend is gated, in-progress stories are interrupted (checkpointed, resumable) and no new dispatch starts; if the review backend is gated, review is deferred. Each is independent, so a Claude usage pause no longer freezes local-backed dispatch. Merge adjudication always runs (no model usage). "interrupted" stories are dispatch-eligible like "todo" ones, so they resume automatically once the dispatch backend frees up.
Also honors MAX_CONCURRENT_AGENTS: dispatch is capped to the number of free slots remaining (limit minus agents already in_progress across all plans), so a tick never starts more agents than the configured ceiling. Stories left undispatched this tick stay "todo"/"interrupted" and are picked up on a later tick as slots free up.
Skips entirely (returns {"ok": True, "skipped": "locked"}) if another tick for this same plan is already running - see _plan_lock.
Inputs: plan_name (required). Returns: object
approve_mergeA
Merge a reviewed story's PR into the default branch, right now, on the caller's explicit approval — this is the human/overlord merge decision itself, not a status check.
plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan. story_key: the story's key within that plan's manifest. Must currently be "parked" or "pr_open" with review_verdict == "APPROVE" — any other state (not yet reviewed, still in progress, already merged) returns {"ok": False, "error": ...} without changing anything.
On success this: rebases the story's branch onto the current default branch, force-pushes it (--force-with-lease) to origin, polls real CI (gh pr checks) — auto-retrying once on a cancelled run, and failing closed on a fail/cancelled/still-pending result — re-runs the story's acceptance fixtures and a build check against the rebased code, then merges the PR, deletes the branch/worktree, marks the story "done" in the manifest and its ticket, and notifies the user to restart the MCP server if the story touched the pipeline's own source. Any failure at any of those steps aborts the merge and returns the specific reason instead of partially completing it.
This does more than a plain gh pr merge (which skips the rebase,
force-push, and re-verification) — prefer this tool over a manual
merge for exactly that reason. It force-pushes and merges regardless
of any local test run you've done yourself, so only call it once you
actually want this specific story merged now; there is no separate
confirmation step after this call.
Inputs: plan_name (required), story_key (required). Returns: object
approve_planB
Approve a plan.
Fail-closed: when plan approval is disabled the request is skipped and nothing is approved. Self-approval is permitted and recorded.
Inputs: plan_name (required).
checkpointA
Deprecated alias for checkpoint_story — identical behavior and parameters (see checkpoint_story's docstring for the full description of plan_name/story_key/step/summary/next_hint). Kept only for backward compatibility with agents/prompts still calling the old name; prefer checkpoint_story in new code.
Inputs: step (required), summary (required), plan_name (required), story_key (required), +1 more. Returns: object
checkpoint_storyA
Record a durable checkpoint for a dispatched agent's own progress on a story. Commits any uncommitted work in the story's worktree as a WIP commit and appends an entry to the story's journal (<plan_name>.<story_key>.journal.json).
plan_name: the plan's name this story belongs to. story_key: the story's key within that plan's manifest — the same key this agent was dispatched with. step: a short label identifying this step (e.g. "wrote-failing-test", "implemented-fix") — becomes part of the WIP commit message, so keep it terse and distinct from other steps in this story. summary: a sentence describing what was actually done in this step, for whoever (human or resumed agent) reads the journal later. next_hint: optional — what to do next if this run is interrupted right after this checkpoint. Leave empty if there's nothing beyond "continue the story normally."
Call this after completing each idempotent step of a story (not mid- step) so a killed or interrupted agent resumes from the last checkpoint via dispatch_story instead of starting the story over from scratch.
Inputs: step (required), summary (required), plan_name (required), story_key (required), +1 more. Returns: object
check_story_statusA
Check whether a dispatched agent has finished. If complete, runs tests in the worktree and reports pass/fail without auto-merging.
Inputs: plan_name (required), story_key (required).
check_usageA
Probe current subscription usage (current session + current week) via a headless /cost call and persist it to USAGE_STATE_PATH.
Inputs: no named parameters. Returns: object
decompose_planA
Turn a raw goal/feature request into epics/stories JSON via the product-analyst persona, run on whichever provider the "decompose" role is configured for (PIPELINE_BACKEND_DECOMPOSE env var, or a "decompose" entry in model_registry.json - defaults to Claude when neither is set). This is a separate, additional path from the interactive product-analyst subagent (invoked via the Agent tool, which is always Claude) - that path remains available and is still the default choice for Claude-quality decomposition; this tool exists so decomposition can also run on a local provider when desired.
Does NOT call save_plan itself - review the returned plan the same way you would review the interactive subagent's output, then save_plan it yourself.
Returns {"ok": True, "plan": {...}} on success. On failure, returns {"ok": False, "error": ...}, with "raw": included whenever the backend actually returned text that failed to parse (never raises).
Inputs: request (required). Returns: object
dispatch_storyA
Spawn a headless Claude Code agent to work on a single story.
For a fresh story, creates a git worktree on a new branch. For a story left "interrupted" (or whose worktree already exists from a prior run), reuses the existing worktree/branch instead and seeds the agent's prompt with the checkpoint journal so it continues rather than starting over. Transitions the Plane issue to In Progress. Returns the subprocess PID; completion is async.
Acquires _plan_lock so direct MCP tool calls serialize across MCP
server processes - without this guard, two Claude sessions (each with
their own MCP server PID) can both call dispatch_story on the same story
in the same window, and the second one treats the first one's
half-built worktree as resumable and spawns a second agent into the
same directory. That race is what produced the repeated zero-output
agent deaths logged in 2026-06-27's e2e-decentralized-messaging run.
Inputs: plan_name (required), story_key (required). Returns: object
export_planA
Export a plan's document, rendered from its ingested manifest.
Returns the plan document in the same shape save_plan accepts -
{"repo_root", "role_config", "team", ["repo_url", "preflight_override",] "epics": [{"summary", "stories": [...]}]} - with each story's key,
summary, description, agent_instructions, dependencies, persona, model,
acceptance, risk, backend, tdd_split and (when set) files and
blocked_by. Dependencies are the plan's own story keys, not the
ticketing provider's issue ids, so the export can be edited and
re-ingested as a plan.
This is a render, not a stored copy (ADR 0012 decision 5: the document
is rendered from the manifest when an export is wanted). Runtime state -
status, attempts, pr_url, worktree, review verdicts and scores, logs,
approvals, owner, delegates, ingest provenance - is never exported; it
is not part of the plan. A plan that was never ingested answers
{"ok": false, "error": "Plan not found"}, and a plan the caller may
not see gets that same reply from the transport's plan-scoped check, so
the tool is no existence oracle.
plan_name: the plan's name, as passed to save_plan/ingest_plan and as
returned by list_plans.
Use this to review what a plan actually says, to hand it to another tool or person, or as the starting point for a revised plan.
Inputs: plan_name (required). Returns: object
get_effective_configA
Read-only diagnostic snapshot of the pipeline's effective configuration: every role in config_provenance.PIPELINE_ROLES with its resolved (provider, model) and provenance, every cataloged env var's resolved value and provenance, any unrecognized/ignored env vars present, and which config-source files were actually consulted (and whether each exists). Pure read - makes no changes and writes nothing.
"restart_required" on a role/env entry means that entry's winning value came from an env var or the launchd plist/mcp_server_env layer, so a change there only takes effect after the scheduler/MCP server is restarted. By contrast, a plan's role_config and model_registry.json are both read fresh on every call, so edits to either are live immediately with no restart needed.
A role entry carrying a non-None "error" key is misconfigured (e.g. no model configured for it anywhere, or its provider/model pairing isn't declared in model_registry.json) - never raises for this; the bad role just reports its error inline while the rest of the roles resolve normally.
Pass plan_name to additionally layer in that plan's role_config overrides (same effect as get_effective_config's plan_name); a plan_name whose manifest doesn't exist degrades to "no plan overrides" rather than raising.
Inputs: plan_name. Returns: object
get_settingsC
Return the stored record for one layer, or record: None when unset.
Inputs: repo (required), scope (required), scope_id (required).
get_story_diffA
Return the in-flight story's worktree diff summary, or one file's diff
when path is given.
plan_name: the plan's name this story belongs to. story_key: the story's key within that plan's manifest. path: optional repo-relative path; must be one of the files listed in the summary. Over-long values are truncated to MAX_PATH_LENGTH and so will not match any listed file.
A story with no worktree returns {"available": False, "reason": ...} rather than raising. An unknown plan/story returns {"ok": False, "status": 404, "error": ...}.
Inputs: plan_name (required), story_key (required), path. Returns: object
get_story_eventsA
Return the story's event history, newest first, with secret values masked.
plan_name: the plan's name this story belongs to. story_key: the story's key within that plan's manifest. limit: how many of the newest events to return, clamped to 1..200; a non-integer uses the default of 50.
The events come from the plan's notification history in the namespace bound for the request. Each is {"seq", "ts", "event", "message"}. The story's own review_feedback, parked_reason, failure_reason and last_inconclusive_output_excerpt (masked, at most 4000 characters) are returned alongside them when the story carries them.
A story with no events is {"available": True, "events": []}. An unknown plan/story returns {"ok": False, "status": 404, "error": ...}.
Inputs: plan_name (required), story_key (required), limit. Returns: object
get_story_journalB
Return the story's checkpoint journal with secret values masked.
Returns {"available": bool, "entries": [...]}; a story that has not checkpointed is {"available": False, "entries": []}. An unknown plan/story returns {"ok": False, "status": 404, "error": ...}.
Inputs: plan_name (required), story_key (required). Returns: object
get_story_logA
Return the tail of the story's log with secret values masked.
plan_name: the plan's name this story belongs to. story_key: the story's key within that plan's manifest. lines: tail length, clamped to 1..500; a non-integer uses the default.
A story with no readable log returns {"available": False, "lines": []}. An unknown plan/story returns {"ok": False, "status": 404, "error": ...}.
Inputs: plan_name (required), story_key (required), lines. Returns: object
get_story_worktreeA
Return the story's worktree status: branch, head, commits ahead of the default branch (max 10), uncommitted paths (max 200) and the agent's scratchpad with secret values masked (max 20000 characters).
plan_name: the plan's name this story belongs to. story_key: the story's key within that plan's manifest.
The worktree is resolved from the story record and contain-checked under the worktrees root; there is no path argument. A story with no worktree returns {"available": False, "reason": "no_worktree"}, a git failure {"available": False, "reason": "git_failed"}. An unknown plan/story returns {"ok": False, "status": 404, "error": ...}.
Inputs: plan_name (required), story_key (required). Returns: object
ingest_planA
Push a saved plan into Plane. Creates epics first, then issues linked to their parent epic. Optionally restrict to specific epic summaries via only_epics. Returns a manifest mapping local IDs to Plane UUIDs.
Re-ingesting an already-ingested plan merges into the existing manifest rather than replacing it: epics/stories not touched this call (including everything only_epics excludes) are preserved verbatim, a story whose key already exists gets its authored fields (summary, agent_instructions, dependencies, persona, model, acceptance, risk (only while todo), backend, tdd_split, files, blocked_by, test_scope) refreshed while its runtime state (status, pr_url, escalated, ...) is kept, and top-level manifest keys outside epics/stories/repo_root (paused, local_model_fallback, final_rework_escalation, ...) carry over untouched. Pass overwrite=True to restore the old wholesale-replace behavior (drops anything not produced by this call).
Inputs: plan_name (required), overwrite, only_epics. Returns: object
interrupt_storyA
Stop a dispatched agent and leave its story resumable.
Sends SIGTERM to the agent's process (a no-op if it has already exited), commits any uncommitted work in its worktree as a checkpoint, and marks the story "interrupted" rather than "failed" so a later dispatch_story call resumes it instead of starting over. The worktree and branch are left in place.
Acquires _plan_lock for the same reason dispatch_story does - two MCP
servers can race here too, with one calling interrupt while the other
calls dispatch on the same story, producing a manifest write race that
leaves the worktree in an inconsistent state.
Inputs: plan_name (required), story_key (required). Returns: object
list_decisionsA
Return the overlord's decision log for a plan: every ruling ever made by request_decision on this plan, oldest first, as an audit trail. Read-only — makes no changes to the plan or any story.
plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan.
Each entry corresponds one-to-one with a prior request_decision call and carries at least the story_key, question, the ruling made, and a timestamp. Returns an empty list if the plan has no decisions logged yet — this is normal for a plan with no blocked stories, not an error.
Call this to check for precedent before escalating a similar decision with request_decision, or when a human wants to review what the overlord has ruled on so far for a plan.
Inputs: plan_name (required). Returns: result
list_plansA
List plan names found in the plan directory (~/.claude/plans, or $PLAN_DIR). No parameters.
Returns the '.json' stem of every file in that directory, not just fresh, ingestable plan sources — an already-ingested plan's '.manifest.json' surfaces as '.manifest', and a story journal or notification log contributes its own noisy stem too. Treat a returned name as a candidate to inspect, not a guarantee it is a valid target for save_plan/ingest_plan.
Call this to check whether a plan name is already taken before save_plan, or to confirm a plan file actually landed on disk after saving it.
Inputs: no named parameters. Returns: result
list_ready_storiesA
Return the stories in this plan that are unblocked and available to dispatch: status == "todo" and every entry in the story's own dependencies list refers to an already-completed story.
plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan. Returns [] if the plan has no manifest yet (not yet ingested) rather than raising.
Returns a list of {"key": ..., "summary": ...} — just enough to choose a story key for dispatch_story or check_story_status, not the full story record (agent_instructions, acceptance, etc. are omitted; use check_story_status for those). A story already in_progress, parked, or done is never included, and neither is a "todo" story whose dependencies aren't all done yet — call this again after a dependency completes rather than assuming today's list stays valid.
Inputs: plan_name (required). Returns: result
list_settingsA
Return every stored settings record the caller may read, by layer and key.
A remote caller must be allowed config:read on the whole store (decided
on an empty resource), and each record is then kept only if the caller may
read its own layer. The host-only deployment layer is never returned to a
remote caller.
Inputs: no named parameters.
mark_story_doneA
Mark a story finished: sets its ticket (Plane, when enabled) to Done, sets manifest["stories"][story_key]["status"] to "done", and clears any stale parked_reason. If this was the plan's last remaining story, fires the plan-completion notification.
plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan. story_key: the story's key within that plan's manifest, as returned by list_ready_stories, check_story_status, or dispatch_story.
Call this only after the story's PR has actually been reviewed and merged —
approve_merge already calls this internally as its last step, so you normally
only need to call mark_story_done directly for a merge that happened outside
the pipeline (e.g. a manual gh pr merge you've already confirmed passed CI).
It does not merge or verify anything; after recording the work as done it
removes the story's worktree and local branch when the worktree is clean and
inside WORKTREE_ROOT. If another dispatch/ingest/interrupt holds the plan's
lock, this is a no-op that returns {"ok": True, "skipped": "locked", ...}
rather than blocking or raising — retry the call rather than assuming failure.
Inputs: plan_name (required), story_key (required). Returns: object
mark_story_in_progressA
Transition the ticket to In Progress and update the local manifest's story status.
plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan. story_key: the story's key within that plan's manifest, as returned by list_ready_stories or dispatch_story.
Use this before writing any code for a story. Call it once, right after dispatch_story (or after claiming a story for manual work) — it only records status, it does not create a worktree/branch or start an agent itself (dispatch_story does that). Calling it on a story that doesn't exist in the local manifest returns {"ok": False, "error": ...} rather than raising. If another dispatch/ingest/interrupt holds the plan's lock, this is a no-op that returns {"ok": True, "skipped": "locked", ...} — retry rather than assuming the status change happened.
Inputs: plan_name (required), story_key (required). Returns: object
patch_planA
Edit a plan manifest's top-level fields (currently only role_config) without hand-editing the manifest JSON.
Hand-editing the manifest directly races the scheduler's 60s advance_all_plans tick - a read-modify-write on either side can silently clobber the other's write. This tool acquires the same _plan_lock the scheduler and dispatch_story use, so the edit is atomic with respect to it. Only role_config may be set; every other top-level field (repo_root, epics, stories, ...) is rejected fail-closed before the lock is taken, so an unknown field can never reach disk.
Inputs: fields (required), plan_name (required). Returns: object
patch_storyA
Edit a story's plan-authored fields (agent_instructions, model, persona,
risk, dependencies, acceptance, pr_url, summary, tdd_split, backend,
blocked_by: a list of ":<story_key>" strings) without hand-editing
the manifest JSON. files is not patchable: use ingest_plan to re-ingest.
Hand-editing the manifest races the scheduler's 60s advance_all_plans tick - a read-modify-write on either side can clobber the other's write. This tool takes the same _plan_lock the scheduler and dispatch_story use, so the edit is atomic with respect to it. Only the fields above may be set; status transitions go through set_story_status, not this tool.
Inputs: fields (required), plan_name (required), story_key (required). Returns: object
pause_planA
Stop advance_pipeline/advance_all_plans from touching this one plan - no new dispatch, review, or merge - while leaving every other ingested plan's scheduler ticks unaffected. Any story currently in_progress is interrupted (checkpointed and left resumable) so a paused plan isn't quietly burning usage in the background. Resume with resume_plan.
Inputs: plan_name (required). Returns: object
record_decisionA
Record one judgment call in plan_name's hash-chained stream.
Authorizes decision:record on the plan first (a plan the caller may not
see is refused exactly as a plan that does not exist is), then validates the
ruling, the rationale, the evidence, the decision class and the story key,
then applies the per-principal rate limit, then appends one record and
writes one audit record.
Refusals never raise and return {"recorded": false, "error": <code>}
with one of not_authorized, empty_ruling, empty_rationale,
empty_evidence, invalid_decision_class, unknown_story,
rate_limited (plus retry_after_seconds) or record_refused (the
v2 validator refused a record that passed the checks above -- defence in
depth, never expected).
Success returns {"recorded": true, "decision_id": <32 hex>, "seq": <int>}.
The record: tier follows the bound principal (human for a human,
auto for an agent -- the v2 chain refuses tier="human" from a
non-human principal, so "always human" would be misattribution); the
caller's identity is stamped from the bound principal (S2) and never from an
argument, so an actor argument is ignored; rule carries empty layer,
persona and policy shas and PIPELINE_RECORD_DECISION_MODEL (or
"unspecified"); alternatives carries the rationale as its single
element "rationale: <text>" (an alternatives entry is capped at 200
characters, so the text keeps 189 of them -- a dedicated rationale field is a
later S3 revision); outcome is empty. The question is accepted and
not persisted: the v2 record has no field for it.
Rate limiting: PIPELINE_RECORD_DECISION_PER_MINUTE calls per minute per
principal subject, default 30; a malformed or non-positive value means 30.
The window is in-process memory, so it resets when the process restarts and
is not shared between processes.
Attribution under the shared-secret provider: the caller resolves to
LOCAL_OPERATOR, so a record cannot tell an agent session from a human
one. Agent attribution needs the OIDC identity seam (S2).
Inputs: ruling (required), ignored (required), evidence (required), question (required), +5 more. Returns: object
record_security_auditA
Record that a repository was security-audited at a given commit.
Parameters: repo_root: Absolute path to an existing directory containing the git repo. sha: Optional 4-64 hex-character commit id. Defaults to HEAD.
Returns:
On success, {"ok": True, "repo_root": ..., "last_audited_sha": ..., "last_audited_at": ...}. On failure, {"ok": False, "error": ...}.
Inputs: repo_root (required), sha. Returns: object
reject_planB
Reject a plan.
Fail-closed: when plan approval is disabled the request is skipped and nothing is rejected. Self-approval is permitted and recorded.
Inputs: plan_name (required), reason.
request_decisionA
Escalate a blocking decision to the overlord, which rules on the user's behalf per the decision policy. The ruling is appended to the plan's decisions log (audit trail, readable via list_decisions) and returned.
plan_name: the plan's name this story belongs to.
story_key: the story's key within that plan's manifest — the story
that's actually blocked.
question: the specific question you need answered, stated so a ruling
of "pick one of these options" fully resolves it.
options: the mutually exclusive choices the overlord may rule between,
as plain strings (e.g. ["hand-roll a parser", "add a dependency"]).
Not free text — the ruling should select one of these verbatim.
context: optional — anything the overlord needs to rule correctly that
isn't in question itself (constraints, tradeoffs you've already
found, why the choice matters). Defaults to empty; provide it
whenever the bare question is ambiguous without it.
On success returns a dict with at least "ruling" (the chosen option's text), "rationale", "risk", "tier", "action", and "notify_user" — act on "ruling", not on your own preference. Call this from a story agent when you are blocked on a choice the user would normally make; do not guess.
Fails open: if the overlord backend errors, the story is parked for a human and a single-line escalation message (a plain string, not the dict above) is returned instead of raising — check whether the return value is a str before reading dict keys off it.
Inputs: options (required), question (required), plan_name (required), story_key (required), +1 more. Returns: result
resume_planA
Clear a pause set by pause_plan so this plan's stories are eligible for dispatch/review/merge on the next advance_pipeline tick again.
Inputs: plan_name (required). Returns: object
review_storyA
Run the code-reviewer persona over a dispatched story's branch. On APPROVE, open a PR via gh and set status to pr_open; otherwise set status to changes_requested. Does not merge — merge is the overlord's decision.
Only reviewable when story["status"] == "tests_passed" - any other status (a stale/duplicate call, e.g. a second tick racing an already-merged story) is a no-op skip; see README.md's "Review & merge" section.
force (default false) is the explicit, audited way to re-run a review the unchanged-since-last-review skip would otherwise decline: it clears the story's last-reviewed markers (last_reviewed_sha, the reviewing-logic fingerprint and skip_notified_sha) so the review actually runs, and records one story:force_review audit entry. The first review after a force has no last_reviewed_sha and is therefore a first-style full-branch review of HEAD, not a since_sha rework diff. It refuses (changing nothing) while a detached review job holds the story, and for any status but tests_passed; it never merges anything, and it leaves review_verdict, review_feedback and the rework budget alone, so a forced review counts against that budget like any other.
Inputs: plan_name (required), story_key (required), force. Returns: object
save_planA
Save a generated project plan to disk. Plan should be JSON matching the schema: { "epics": [ { "summary", "stories": [...] } ] }. Call this after generating a plan so the user can review before ingestion.
workspace is optional. When supplied, it is validated and (WS-11) the model-authored repo_root in plan_json is OVERWRITTEN with the server-validated resolved path (the server overwrites the model-authored value; this tool never resolves or rewrites plan_json itself). When omitted, the plan's own repo_root is trusted, exactly as before. The tool deliberately does NOT fall back to the dashboard's persisted active workspace: the MCP server and the dashboard are separate processes, and silently coupling them through shared durable state is out of scope (that fallback lives only in the dashboard HTTP route).
Inputs: plan_json (required), plan_name (required), workspace. Returns: object
set_settingB
Write one settings key at one layer, compare-and-set on expected_version.
expected_version is null to create a record and the stored version to
update it. allow_loosen replaces the layer's list of ceiling keys that the
layer below may loosen; null keeps the list already stored.
Returns {"ok": True, "scope", "scope_id", "repo", "key", "value", "new_version"} on success, or a refusal dict. Every outcome is audited.
Inputs: key (required), repo (required), scope (required), value (required), +3 more.
set_story_statusA
Transition a story to an explicit status without hand-editing the manifest JSON (e.g. resetting a "parked" story to "interrupted" so the scheduler retries it).
Acquires _plan_lock for the same reason patch_story does. Only accepts the fixed set of statuses the pipeline itself assigns (todo/in_progress/running/interrupted/failed/tests_passed/pr_open/ changes_requested/parked/done) - this is a sanctioned status change, not a way to invent pipeline state the rest of the code doesn't expect.
Inputs: status (required), plan_name (required), story_key (required). Returns: object
unblock_storyA
Unblock a parked story, recording the manual intervention.
Authorized like set_story_status (the plan's owner or a delegate; anyone
else is refused). Clears the named retry/review fields, optionally sets
status and appends add_files to the story's files, exactly as
python -m pipeline.unpark does, and records the caller as the human
action. All of it happens under the plan lock.
plan_name / story_key: the parked story. clear_fields: names to delete; only the retry counters and review records in pipeline.unpark.UNPARKABLE_FIELDS are accepted. status: one of the statuses the pipeline assigns (default: unchanged). add_files: repo-relative production paths (no leading '/', no backslash, no NUL, no '..') appended to the story's files. note: up to 8000 characters appended to the story's agent_instructions. It is written together with the unblock notice, or not at all.
Changing the brief or files resets the plan's approval exactly as
patch_story does; the result says so with approval_reset. A refused
value is never echoed. If the plan lock is busy the result carries
skipped: "locked" and retry_after_seconds: call again.
Inputs: plan_name (required), story_key (required), clear_fields (required), note, +2 more. Returns: object
verify_auditA
Verify every audit chain and report where each one first breaks.
Read-only: nothing is appended, rewritten or repaired. The answer is
{"ok": True, "plans": {<plan>: None | <bad seq>}, "host": None | <bad seq>}. A plan appears only when the audit log knows the chain; the value
is the seq of its first altered record, or None when it is intact.
The host-scoped chain — events with no plan to belong to, such as a host
config write — is verified the same way and reported under host.
A chain with no externally recorded head cannot prove that trailing records
were not removed, so truncation of the tail verifies intact. When
PIPELINE_AUDIT_ANCHOR names a sink, the answer gains an anchor
mapping from the same chain names to this tool's tamper verdict for each
one, which is what catches a cut tail. If the anchor log itself cannot be
read, that mapping holds a single * entry with an anchor log unreadable verdict: the anchors are unknown, so no chain is reported
clean.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Most tools target a distinct resource+action, but several pairs overlap: `checkpoint` is an exact deprecated alias of `checkpoint_story`, `mark_story_in_progress` vs `set_story_status` both mutate status, and `record_decision` vs `request_decision` differ only by one verb despite very different semantics. The long descriptions do resolve most of these, but an agent has to read carefully to avoid picking the wrong one.
The set follows a near-uniform snake_case verb_noun convention (dispatch_story, patch_plan, get_story_log, approve_merge, list_plans...). The only real deviation is the bare verb `checkpoint` kept as a deprecated alias, plus minor singular/plural drift in set_setting vs get_settings/list_settings.
40 tools is well past the point where a single server's surface stays legible, even for a broad pipeline-orchestration domain spanning plan lifecycle, story lifecycle, settings, audit, decisions, and config. The count is inflated by redundant entries like the deprecated `checkpoint` alias and the advance_pipeline/advance_all_plans split.
Coverage is strong: full plan lifecycle (save/ingest/export/approve/reject/pause/resume/patch/advance), full story lifecycle (dispatch/interrupt/checkpoint/status/review/merge/unblock plus logs, journal, diff, worktree), settings, audit verification, and decision escalation. Gaps are minor — no plan deletion or story removal, and no single plan-overview/status tool, but nothing that blocks core workflows.
Maintenance
Related MCP Connectors
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that spawns autonomous Claude Code agents in GitHub repos, enabling task delegation with persistent state, multi-step workflows, and job monitoring.4729 npm2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes a governed, provenance-grounded autonomous delivery pipeline as an MCP server, enabling AI coding assistants like Claude Code or Codex to initiate requirements-to-PR workflows with human approval gates and full audit.549 PyPI13MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets ChatGPT or any MCP client securely delegate coding tasks to a local Claude Code instance, with git checkpointing, approval gates, and structured results. Supports code review, test running, and rollback via simple tool calls.24 npmMIT
- AlicenseAqualityDmaintenanceAn MCP server and HTTP gateway that dispatches coding tasks to Claude Code, Codex, and Antigravity CLI sessions, keeps track of those sessions, and optionally runs an implement → review → verify loop against a real repository.6MIT