factory

Factory is an autonomous ticket pipeline that automates the journey from GitHub issue to merged PR. Issues labeled `ready-for-agent` are claimed by a coding agent working in an isolated git worktree, gated by your own deterministic checks (test/lint commands), reviewed by a second LLM, opened as a PR, and merged to `main` only when the gate, reviewer, GitHub CI, and freshness against `main` all agree. Anything the pipeline cannot resolve is handed back with a `ready-for-human` label and attached evidence. It runs locally on your machine via a systemd timer (default every 10 minutes) using agent CLIs you already have — `omp`, `droid`, `codex exec`, `claude -p`, and similar. State lives in GitHub (labels, comments, PRs) plus a gitignored `.factory/` directory; the dispatcher is stateless and safe to re-run. Key commands and capabilities: - **Triage**: A local model (Ollama, vLLM, llama.cpp, LM Studio) labels `needs-triage` issues as `ready-for-agent`, `needs-info`, `ready-for-human`, or proposes `wontfix`. - **Dispatch**: One stateless pass that syncs upstream, runs the merge stage, claims tickets, invokes workers, runs gates, opens PRs, and handles review bounces up to a configured round limit. - **Manage**: A manager agent recommends directions for PRs needing review, resolves escalation packets, and can RETRY, REWRITE, SPLIT, ROUTE, FIX, or hand off to HUMAN. Split children re-enter triage; rewrites must preserve accepted initiative baselines. - **Gate**: Runs your deterministic checks in the worktree and produces a Markdown report. - **Learn**: Reads recent finished tickets' event trails and reviewer findings, asks the local model for repo-specific lessons, and writes a `.factory-lessons.md` file carried into every worker prompt. - **Dashboard**: A local ops UI showing ticket stages, in-flight phases, gate reports, worker logs, journal heartbeat, upstream drift, a read-only Factory Manager Chat, and a Roadmap view for shared initiatives. - **Plan**: Read-only commands for listing and inspecting initiative issues, routing decision ownership, proposing immutable initiative baselines, and detecting drift between a ticket's accepted baseline and the live initiative source. Factory supports immutable initiative bindings: an implementation ticket can declare `Initiative: #N` with a fenced JSON baseline (SHA-256 hashed, schema version 1). Once admitted, the complete ticket snapshot becomes the human-approved execution contract; retries reuse it and cannot adopt later revisions. Drift detection compares the accepted baseline against the live initiative, reporting changed sections without guessing attribution. Installation is via `uv tool install` (or pipx/pip) from the GitHub repository, with a `@stable` channel for releases. Setup involves `factory init` (creates `.factory.toml`, issue templates, labels), editing gate checks, `factory doctor` (validates tools, auth, remotes, model endpoint, dashboard port), and `factory install --dashboard` (writes systemd user units). The tool requires Python ≥ 3.11, `git`, and authenticated `gh` with push access. For forks tracking an upstream, the dispatcher merges new upstream commits into `main` (gated) before each merge stage. Worker and manager commands receive prompt-file paths and working directories; reviewers receive inline prompts. The manager CLI should be configured in read-only/no-tools mode.