--- title: The pipeline description: How Foreman moves a work item through four stations, from classification to a reviewed draft pull request. type: overview summary: The four stations, the clarification gate, the review loop, and the invariants that hold the line together. related: - /docs/stations - /docs/intake - /docs/trust-model --- # The pipeline Every work item, however it [arrives](/docs/intake), moves through the same line: Classifier, then Analyst, then Implementer, then Reviewer. The orchestrator routes between them, verifies each handoff, and assembles the result into a draft pull request. It never skips a station and never does a station's job itself. This page is the narrative. For each station's model, tools, and exact output contract, see the [stations reference](/docs/stations). ## Opening moves Before touching the work item, the orchestrator loads what it already knows. It calls `get_user_preferences` for the requester's standing notes, such as a default base branch or how they like pull request descriptions structured. It calls `read_factory_brain` for durable facts about the target repository: build quirks, verification gotchas, recurring review findings. Because stations cannot read the brain themselves, the orchestrator has to weave the facts that matter into the messages it sends them. It also loads the `writing-quality` skill before drafting anything meant for a person, whether that is a pull request description, an issue comment, or a Linear reply. ## Grounding the work item The orchestrator reads before it routes. It fetches the actual GitHub issue, pull request, or Linear issue in full, and it never invents issue numbers, titles, states, or links. For items that arrived from a GitHub issue or mention, the `triaging-issues` skill runs first. That covers checking for duplicates, learning the repository's own label vocabulary, and deciding whether to ask a question or proceed. When an item spans both trackers, `github-linear-bridging` governs how the two get linked. ## Station 1: the Classifier The Classifier is pure triage on a fast, cheap model. It works from the message alone, with no repository checkout to consult, and returns a structured classification covering type, priority, complexity, affected area, and whether the item is actionable. The orchestrator's rule here is explicit: never skip a station, even for work that looks trivial. The Classifier decides what is trivial, not the orchestrator. When the work item is a GitHub issue, the orchestrator mirrors the classification onto it as labels, using the fewest existing labels from the repository's own vocabulary and never inventing one. ## The clarification gate `needs_clarification` is the pipeline's stop signal, and what happens next depends on if anyone is watching. On an attended run, meaning a mention, a Linear session, or the dev TUI, the orchestrator asks the Classifier's questions and waits for an answer. On an unattended run from a labeled issue, it posts the questions as its reply and stops. An unattended run is never left waiting on input. Someone re-labels the issue once they have answered, which starts a fresh run. ## Optional: the Researcher When a work item turns on a fact the repository and its trackers do not hold, such as an upstream bug, a library version, or a claim to verify, the orchestrator delegates to the Researcher before the Analyst runs. Every claim the Researcher returns carries at least one real, fetched source URL and a confidence level. Anything it could not verify goes into `gaps` rather than being passed along as a finding, and only cited findings feed the Analyst's message. ## Station 2: the Analyst The Analyst plans and never writes the implementation. It works from a live checkout of `FACTORY_REPO`, so the plan names real files and the repository's actual conventions instead of guesses. It reads files before naming them, discovers the package manager and the lint, typecheck, and test commands, and traces the code path the item touches. Its most important output is the acceptance criteria. Those travel unchanged from the Analyst to the Reviewer, which is what turns the review into a judgment against a fixed contract rather than a vibe check. ## Station 3: the Implementer The Implementer executes the plan in its own checkout, on the strongest coding model in the factory. It branches from the default branch as `factory/-`, writes complete runnable code with no stubs, keeps the change minimal, and verifies with the repository's own checks, recording exactly what it ran and what each command produced. It commits and delivers by calling `push_branch`, its only side effect. That tool is inert by construction: `validateBranch` refuses `main` and `master` in code, the credential is brokered at the sandbox firewall, and a feature branch on its own ships nothing. The Implementer cannot ask questions mid-run. When the plan leaves something genuinely open, it makes the narrowest reasonable choice and records it as a deviation. When no reasonable choice exists, it stops without pushing and explains why. ## Station 4: the Reviewer The Reviewer is the quality gate, and it is built to be independent. It runs on a different model vendor than the Implementer, works in its own separate checkout, and never sees the Implementer's reasoning or working state. It fetches the branch and reads the real diff rather than trusting the change summary, because summaries describe intent and diffs describe reality. Where a claim is cheap to check, it re-runs the fastest of the Implementer's verification commands. It reviews in a fixed order: correctness first, then each acceptance criterion judged individually with evidence, then safety, scope, verification adequacy, and quality. It returns one of three verdicts. `approve` ships as-is. `request_changes` means fixable problems, each finding specific and actionable. `reject` means the approach itself is wrong and iteration will not fix it. ## The review loop On `request_changes`, the orchestrator sends the work back to the Implementer with the original context, the branch name, the previous implementation summary, and every finding. Then it re-runs the Reviewer on the updated branch. If the work still does not pass after the second cycle, or the Reviewer returns `reject`, the line stops. The orchestrator reports the unresolved findings on the originating thread and does not open a pull request. ## Delivery When the Reviewer approves, the orchestrator opens a draft pull request with the head set to the pushed branch and the base set to the repository's default branch. The body is assembled from the pipeline's own outputs: * The problem statement * The approach, and why it was chosen * The acceptance criteria as a checklist, with the Reviewer's pass or fail against each * The verification commands and their results * Any deviations from the plan * `Closes #N` when the work item is a GitHub issue It then reports back on the originating surface with the pull request link and a one-paragraph summary: what was built, the review verdict, and anything a person should look at before marking it ready. Marking ready and merging are decisions for a person. Foreman never marks its own pull request ready unprompted, and merge tools are not mounted at all. ## Learning If the run surfaced a durable fact about the repository that would save a future run time, the orchestrator records it. The flow is read the brain, merge the note into what is already there, then save the document. The brain stays curated and short, holds only durable repository-level facts, and never takes an unverified claim from an issue or comment body. Writes are gated so unattended runs cannot poison it, which [factory memory](/docs/memory) covers in full. ## Structural invariants Some properties of this pipeline hold because of how the stations are wired, not because a prompt asks nicely. Stations inherit nothing. Each runs in a fresh child session with none of the root's instructions, skills, connections, tools, or sandbox, and never sees the orchestrator's conversation history. Every delegation message therefore has to be self-contained. Every station declares an `outputSchema`, which puts it in task mode: structured output, and no ability to stop for approval or input. That is why no station holds an approvable tool. A station that parked would strand the run. The built-in `agent` tool is disabled, so the orchestrator cannot delegate to an undifferentiated clone of itself and bypass the stations. The Reviewer's independence is architectural rather than instructed: a different model vendor, a separate checkout, and visibility into nothing but the pushed branch and the structured reports. If a station fails or returns something that does not match its schema, the orchestrator retries it once with a clarified message before surfacing the failure. ## Next steps --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)