---
title: Customizing
description: Where each Foreman behavior lives, how to extend the factory with new capabilities, and the eve conventions a contributor must know.
type: guide
summary: Customizing the pipeline, models, policies, and intake; extending with schedules, merge, and station tooling.
related:
  - /docs/tools
  - /docs/configuration
  - /docs/evals
---

# Customizing



Foreman is a template, and the expectation is that you change it. Every behavior has one home, so a change is usually one file.

| Behavior                                                                          | Where it lives                                                                     |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Orchestrator routing: when to run which station, the clarification gate, delivery | `agent/instructions.ts`                                                            |
| A station's procedure                                                             | `agent/subagents/<station>/instructions.md`                                        |
| A station's model and output contract                                             | that station's `agent.ts`                                                          |
| Model assignments                                                                 | `agent/lib/models.ts`                                                              |
| Approval policy                                                                   | `agent/lib/github/approval.ts`, mapped onto tools by `agent/extensions/github.ts`  |
| The intake label                                                                  | `FACTORY_LABEL` in `agent/lib/constants.ts`                                        |
| PR summary comments                                                               | the `onPullRequest` hook in `agent/channels/github.ts`; remove it to turn them off |

### The pipeline

The orchestrator prompt decides routing; each [station's](/docs/stations) `instructions.md` decides how that station does its job. For example, to change what the Reviewer checks, edit `agent/subagents/reviewer/instructions.md` rather than the orchestrator.

The station's `agent.ts` holds its `outputSchema`, which is the contract the orchestrator reads back. A new output field therefore means touching both the schema and whatever consumes it in the orchestrator prompt.

### Models

`agent/lib/models.ts` holds the one `MODELS` map every `agent.ts` reads from, so a model swap is a one-line edit.

One split is deliberate: the Implementer and the Reviewer run on different vendors, because a different vendor does not share the Implementer's idiom or blind spots. Whatever you swap in, keep those two different.

### The approval policy

`agent/lib/github/approval.ts` is the whole policy in a handful of small functions, and `agent/extensions/github.ts` maps GitHub tools onto it. To tighten or loosen a gate, change the mapping or the policy function.

Never hardcode `"never"` on a tool or invent a new caller check. `agent/lib/trust.ts` is the single trust authority, and the [trust model](/docs/trust-model) explains what each policy returns and why.

## Extending the factory

The design leaves room for four extensions in particular.

<Accordions type="single">
  <Accordion title="Continuous operation with a schedule">
    Add a schedule that sweeps for queued work on a cron.

    The approval policies already recognize schedule turns through `isScheduleAppAuth` and treat them as trusted callers, so no policy work is needed. The template ships without a schedule.
  </Accordion>

  <Accordion title="Merge behind approval">
    The template mounts no merge tool, so a draft pull request is the ceiling for unattended runs.

    To let Foreman merge after a person approves, add `mergePullRequest` to the extension's `include` allowlist and map it to `shipPolicy` in `requireApproval`. The ship policy parks no matter who asks and is denied unattended, so merging stays behind an approval card.

    <Callout type="warn" title="Keep the evals in sync">
      Add any new write tool to `GITHUB_WRITE_TOOLS` in `evals/helpers.ts` so the read-only [evals](/docs/evals) keep guarding it.
    </Callout>
  </Accordion>

  <Accordion title="More intake surfaces">
    The GitHub channel also exposes `onCheckRun` and `onWorkflowRun` hooks for finer-grained CI intake, and eve ships Slack, Teams, and other channels if you want work to arrive from chat.

    New intake hooks should stamp trust the way the existing ones do. Trust is decided at dispatch, never re-derived from content the model can read.
  </Accordion>

  <Accordion title="Deeper station tooling">
    Stations are ordinary eve agents that inherit nothing from the root, so a new capability goes in the station's own directory: its `tools/`, its `connections/`, its `sandbox.ts`.

    Give the Analyst a Sentry MCP connection so plans can cite production errors, or give the Reviewer a browser extension so it can exercise a UI change.

    One hard rule applies. A station's `outputSchema` puts it in task mode, which cannot park, so nothing approval-gated may live in a station. A station side effect must be inert by construction, the way `push_branch` is: validated branch names, feature branches only, and a credential brokered outside the sandbox.
  </Accordion>
</Accordions>

## eve conventions to know

Four framework rules save the most debugging time.

Identity comes from the filesystem, never a `name` field. `agent/tools/agent.ts` is the tool `agent`, `agent/connections/linear.ts` registers as `linear`, and the directory `agent/subagents/classifier/` lowers into the tool `classifier`. Renaming means moving the file.

Approval-gated tools must not live in task-mode children. A task-mode session cannot park, so a tool that returned `user-approval` inside a station would strand the run. Gated tools belong on the root.

Read the relevant guide in `node_modules/eve/docs/` before writing code against the framework, and confirm APIs there rather than inventing them. The same docs are published at [eve.dev](https://eve.dev/docs/introduction).

Run `pnpm validate` before shipping. It runs the lint check, `tsc`, and eve discovery diagnostics, and all three must report zero errors and zero warnings. Then exercise the change in the `pnpm dev` TUI, and run `pnpm eval --tag fast` if you touched routing or policy.

Working in the template repository with a coding agent? This prompt adds a fifth station end to end, and adapts easily to swapping a model or adding a tool.

<CopyPrompt
  text={`Add a new station to the factory pipeline: a docs writer that runs after the Reviewer approves and drafts documentation for the change in its own repo checkout.

Ground truth: read AGENTS.md and ARCHITECTURE.md in this repo first, and follow the existing station layout under agent/subagents/.

1. Create the station directory with a description, an outputSchema, and instructions.md.
2. Give it its own repo checkout via agent/lib/github/repo-sandbox.ts.
3. Wire it into the orchestrator routing in agent/instructions.ts.
4. Pick its model in agent/lib/models.ts.
5. Finish with pnpm validate reporting 0 errors and 0 warnings.`}
>
  Add a new station to the factory pipeline: a docs writer that runs after the Reviewer approves and drafts documentation for the change in its own repo checkout.

  Ground truth: read `AGENTS.md` and `ARCHITECTURE.md` in this repo first, and follow the existing station layout under `agent/subagents/`.

  1. Create the station directory with a `description`, an `outputSchema`, and `instructions.md`.
  2. Give it its own repo checkout via `agent/lib/github/repo-sandbox.ts`.
  3. Wire it into the orchestrator routing in `agent/instructions.ts`.
  4. Pick its model in `agent/lib/models.ts`.
  5. Finish with `pnpm validate` reporting 0 errors and 0 warnings.
</CopyPrompt>

## Learn more

* [eve documentation](https://eve.dev/docs/introduction), also at `node_modules/eve/docs`
* [GitHub Tools eve extension](https://github-tools.com/frameworks/eve-extension)
* [Vercel Connect](https://vercel.com/docs/connect), [Vercel Sandbox](https://vercel.com/docs/sandbox), and [Vercel Blob](https://vercel.com/docs/vercel-blob)
* Related templates: [eve Content Agent](https://github.com/vercel-labs/eve-content-agent-template) and [eve Personal Agent](https://vercel.com/templates/nuxt/eve-personal-agent)

## Next steps

<Cards>
  <Card href="/docs/tools" title="Tool surface" description="The reference for what is mounted today and where." />

  <Card href="/docs/stations" title="Stations reference" description="Each station's model, tools, sandbox, and output contract." />

  <Card href="/docs/evals" title="Evals" description="How you prove a customization did not loosen a gate." />
</Cards>


---

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)