fagan

# Fagan

[![CI](https://github.com/motock/fagan/actions/workflows/ci.yml/badge.svg)](https://github.com/motock/fagan/actions/workflows/ci.yml)
[![Fagan MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/motock/fagan/badges/card.svg)](https://glama.ai/mcp/servers/motock/fagan)

**Spend tokens on judgment, not typing.**

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](https://www.semanticscholar.org/paper/Design-and-Code-Inspections-to-Reduce-Errors-in-Fagan/fe02f66911c6331a81d01f9cf4fdce05b6b2aca3),
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](./REFERENCE.md).

**Before you start:** read [Reliability & limitations](#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 Linux, run the same entry points directly
  (e.g. `python3 -m pipeline.scheduler_daemon`) under your init system or
  supervisor of choice, or 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

```bash
curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash
```

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:

```bash
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.sh
```

Either way, `cd` into the install directory it reports (`~/.fagan` by
default) and continue from step 2 below. 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.

```bash
# 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. Restart Claude Code (or start a new session) so it picks up the MCP server
```

`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–4 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](REFERENCE.md#plan--story-schema).
2. `mcp__pipeline__save_plan` (or `ingest_plan`) with that plan and a
   `repo_root` pointing at the target project — **not** this pipeline repo.
3. `mcp__pipeline__list_ready_stories` to see what's unblocked, then
   `mcp__pipeline__dispatch_story` to claim and start one.
4. Watch progress with the dashboard: `scripts/dashboard.sh start`, then open
   `http://localhost:8000`.
5. For unattended operation, run the scheduler so ready stories advance
   without you calling `advance_pipeline` by hand:
   `.venv/bin/python3 -m pipeline.scheduler_daemon` (foreground, or under
   launchd/systemd/tmux — see [Scheduler](#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](REFERENCE.md#configuration-environment-variables).

**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](REFERENCE.md#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`:

1. **Plan role config** — a plan's per-role `provider`/`model` beats
   everything below.
2. **A `roles` block in a registry file** — the single source of truth for
   role routing; see below.
3. **`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=ollama` opts the
   dispatch role into Ollama.
4. **The caller's own fallback** — for dispatch/review this is the `claude`
   backend.

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_PATH`** points 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. Point `PIPELINE_MODEL_REGISTRY_PATH` at it, or copy it over
  `model_registry.json` locally 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 |
| --- | --- | --- |
| `git` / `gh` | GitHub auth (the pipel