motock/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:
Frontier 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.12–3.14 on every push. 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
with scripts/generate_systemd_units.sh (see Scheduler below)
instead of hand-rolling init files, or run the entry points directly in a
foreground terminal/tmux session.
- **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.
Quickstart
One-line install
This 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:
Either 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.
scripts/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:
1. Ask the product-analyst subagent to turn a goal into epics/stories, or
hand-write a plan per the schema.
2. mcp__pipeline__save_plan (or ingest_plan) with that plan and a