Foreman: a four-station agent pipeline that turns labelled issues into draft pull requests
Meet Foreman, an eve Software Factory.
At a glance
- What is it?
- The eve Software Factory template wires four separate agents (Classifier, Analyst, Implementer, Reviewer) to GitHub and Linear, and stops at a draft PR so a human keeps the merge. Here is what the README and .env.example actually commit to, and where the design leaves gaps.
- Who is it for?
- Adopt this if your team already lives in GitHub or Linear, wants a labelled issue to come back as a draft PR rather than a merged commit, and is willing to run the Vercel deploy flow with a GitHub App installed on the target repository. Do not adopt it if you need a self-hosted pipeline with no Vercel dependency, or if your issues rarely carry enough context for a Classifier to decide they are actionable.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Foreman is aimed at, and the queue it assumes you already have
Most agent coding demos start from a prompt box. Foreman starts from a backlog. The README describes it as an eve software factory that takes tasks from GitHub and Linear, moves each one through four stations, and delivers a reviewed draft pull request on your repository. The human step is explicit: you review, mark ready, and merge. So the target user is a team that already runs issue triage somewhere, already has a repository with its own checks, and wants the mechanical part of the loop handled without giving up the merge button. That is a narrower audience than it first appears. If your work does not arrive as an issue or a Linear task, the entry points listed in the README (label an issue factory, @mention the bot, delegate in Linear, or hand it a task in the local TUI) all assume a ticket-shaped unit of work. A team that works from long-lived branches or design documents has no obvious door into this pipeline. The label itself is the gate: FACTORY_LABEL defaults to factory, and only issues carrying it are handed over. That is a sensible throttle, and it also means the factory does nothing until someone decides an issue is ready for it.
Four stations, four instruction sets, and one deliberate information barrier
The pipeline is not a single agent with a long prompt. Each station is its own agent with its own instructions, sandbox, and tools, according to the README. Classifier triages type, priority, complexity, and whether the task is actionable at all. When it is not actionable, Foreman asks the requester instead of building the wrong thing, which is the cheapest possible failure mode and worth noting as a design choice. Analyst produces a plan with acceptance criteria and works from a live checkout of the repository rather than a description of it. Implementer executes that plan in its own sandbox, verifies with the repository's own checks, and pushes a branch. Reviewer then judges the result against the real diff, with evidence for each verdict. The isolation rule is the most interesting part: the Reviewer sees only the pushed branch, never the Implementer's reasoning. That prevents the reviewer from being talked into a conclusion by the implementer's justifications, and it also means the Reviewer cannot know why a strange-looking change was made. The README does not say how a Reviewer verdict feeds back into a re-run, or whether a rejected branch is discarded or amended. Those are the questions I would want answered before trusting the loop on anything beyond small changes.
How work arrives, and the one path that is treated as untrusted
Five entry points are documented. Labelling an issue runs the pipeline on its own, posts progress as stations complete, and ends with a draft PR linked to the issue. An @mention on an issue or PR starts an interactive session, but only from repo owners, members, and collaborators. Linear Agent Sessions run the same pipeline and report progress back in Linear. The dev TUI takes a task locally. The last two are the interesting ones for anyone evaluating risk. The README states that local runs are treated as untrusted, so changes to GitHub wait for approval. That is a meaningful asymmetry: the same pipeline behaves differently depending on where it was triggered, and the TUI path is the conservative one. There is also a CI repair loop. When CI goes red on a factory PR, Foreman diagnoses the failure and pushes a fix, but only to its own branches, which are identified by FACTORY_BRANCH_PREFIX (default factory/). The README is explicit that the prefix marks the only branches automated CI fixes touch. If you change that prefix to something broad, you are widening what the repair loop can write to. Finally, when a human opens a pull request, Foreman posts one orienting comment for reviewers, described as a summary rather than a review. That distinction matters for anyone worried about an agent's opinion being mistaken for a reviewer's sign-off.
Getting it running: the Vercel deploy path and the environment variables that matter
The intended install is the Deploy with Vercel button, which the README says sets up the GitHub connector, the Linear connector, a Vercel Blob store, and prompts for FACTORY_REPO and FACTORY_LABEL. Two preconditions are stated plainly. FACTORY_REPO must name a real repository in owner/repo format, and the GitHub App behind the connector you select must be installed with access to that repository. The deploy clones FACTORY_REPO up front to prewarm the station sandboxes, so an unreachable repository fails the deploy with a Cannot access <owner/repo> error. Fix the app installation or the value, then redeploy. The rest of the configuration lives in .env.example. FACTORY_SETUP_COMMAND is optional and runs once inside the sandbox checkout at build time, with pnpm install given as the example, so every run starts with dependencies already installed. FACTORY_LABEL defaults to factory. FACTORY_BRANCH_PREFIX defaults to factory/. FACTORY_BOT_NAME defaults to the GitHub App's slug and is resolved from the connector automatically when unset. GITHUB_CONNECTOR and LINEAR_CONNECTOR are required but set automatically from Vercel Connect connector UIDs. For local work the README gives three commands: vercel link, vercel env pull, then pnpm dev. The example task it suggests is a bug report about a password reset email arriving twice, and the expected result is the four stations firing in order and ending in a draft PR on FACTORY_REPO.
The factory brain is the part with the least specification
Between runs, Foreman keeps what the README calls a factory brain: notes about your repository that every run starts from. The documentation link points at ask-foreman.dev/docs/memory for the full picture, and the README itself says nothing about how those notes are written, who can edit them, whether they are versioned, or how they are scoped. That is the largest unquantified surface in the template. A shared memory that every run reads is also a shared failure mode: a wrong note about how your build works propagates into every subsequent run until someone corrects it. Nothing in the supplied material describes a review step for memory writes, a diff of what changed between runs, or a way to reset the brain. If you adopt this, treat the memory store as production configuration rather than an implementation detail, and find out where it lives before the first run, not after the tenth. The README also does not state where the memory is persisted, though the deploy flow provisions a Vercel Blob store, so that is the likely candidate. I cannot confirm that from the material.
Where this is the wrong tool, and what to weigh against it
The README does not discuss cost, model choice, run duration, or concurrency limits. There are no releases retrieved for this repository, so there is no changelog to read for breaking changes, and no versioned upgrade path is described. The template is a template: you clone it, deploy it, and own the result. Upgrades are manual merges from upstream, and any local edits to station instructions or environment handling become conflicts you resolve yourself. The dependency on Vercel is structural rather than incidental. The deploy button provisions connectors and a Blob store, the connectors supply GITHUB_CONNECTOR and LINEAR_CONNECTOR, and the sandbox prewarming happens during the Vercel build. A team that needs the pipeline to run inside its own infrastructure, or that has no appetite for a hosted connector layer, is not the audience for this template. For a different approach, consider a plain CI-driven agent: a GitHub Actions workflow that fires on an issue label, runs a coding agent in the runner's own container, and opens a PR with the runner's credentials. That trades the four-station separation and the factory brain for something you can read in a single YAML file, debug with the runner's logs, and host wherever your CI already lives. The difference is not quality, it is where the state lives. Foreman keeps memory and station separation outside your repository; a CI workflow keeps everything inside it.
Licence and the maintenance arithmetic
The repository is MIT licensed, and the README carries an MIT badge linking to the LICENSE file. MIT permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a permissive baseline and, as always, not legal advice; if you are embedding this into a product, have counsel read the licence text rather than this paragraph. The maintenance cost is the part the template cannot hide. You are responsible for the GitHub App installation and its repository scope, for keeping FACTORY_SETUP_COMMAND aligned with your package manager and lockfile, for the branch prefix that bounds the automated CI fix loop, and for whatever accumulates in the factory brain. Every one of those is a thing that can drift silently. The setup command is the clearest example: it runs once at build time, so a stale lockfile or a switched package manager leaves the sandbox verifying against an environment that no longer matches your repository, and the Implementer's own checks would be the first place that shows up. Nothing in the supplied material describes a health check for the factory itself.
Editorial conclusion
Adopt this if your team already lives in GitHub or Linear, wants a labelled issue to come back as a draft PR rather than a merged commit, and is willing to run the Vercel deploy flow with a GitHub App installed on the target repository. Do not adopt it if you need a self-hosted pipeline with no Vercel dependency, or if your issues rarely carry enough context for a Classifier to decide they are actionable. Before the first deploy, verify three things: that FACTORY_REPO names a repository the selected GitHub App can actually reach, since the README states the deploy clones it up front and fails with Cannot access <owner/repo> otherwise; that FACTORY_SETUP_COMMAND matches your package manager so the sandbox checkout is not starting from zero dependencies; and that your CI passes on the factory branch prefix before you let the automated fix loop push to it.
Community notes