# Set up the Factory

What a project needs before the Factory can carry its work, how to file your first idea, and how to pull work in from GitHub, Linear and Jira.

The Factory works with the system pipeline the moment you open it. You only need to change the pipeline when you want something different. This page covers what a project needs, filing work, pulling work in from trackers, and customising the pipeline for one project.

## Before you start

| You need | Why |
|---|---|
| **A git repository** with at least one commit | Every build runs in its own git worktree. Without git, every Factory action stops with *Not a git repository.* |
| **A default branch** | Warden uses the target of `origin/HEAD`, else `main`, else `master`. |
| **Your work committed** | Builds start from committed code. Uncommitted changes are never included. |
| **A connected model** | Triage and drafting need one. Without it you see *No model to triage with: connect a provider or pick a model.* See [Connect your models](models). |
| **GitHub CLI** (`gh`), signed in | Only for GitHub issues, pull requests and GitHub-deployment environments. Local merges don't need it. Run `gh auth login` once. |
| **git 2.38 or later** | To predict merge conflicts before a merge. |

```bash
gh auth login
git --version   # 2.38 or later
```

## File your first idea

:::steps
1. Open **Mission Control** and pick the **Factory** tab. Choose your project in the **Project** picker (or leave **All projects** to see everything).
2. Click **+ New idea** (or {{kbd:⌘+K}} → **New idea (Software Factory)**) and describe the work in plain words, the way you would write a ticket.
3. Triage runs by itself (**Triage new ideas automatically** is on by default). Within a minute the item shows the planner's verdict, size, lane and any questions.
4. If triage was confident, the item moves on by itself. If not, it waits in **Needs you**: open it, check the lane, and press **Accept as Standard** (or the lane you want), **Needs info** or **Reject**.
5. Follow the item along the line. Each stage tells you what it is doing and when it needs you.
:::

> [!TIP] Already have a plan, spec or pull request?
> You don't have to start from an idea. **Send to Factory** from a plan or spec, **Take over in Factory** from a pull request, or **Track in Factory** from a worktree. The Factory also shows plans and specs it isn't tracking yet, each with a **Track** button.

## Pull work in from your tracker

The Ideas stage takes work from more than one place. Open **Customize → Flow**, select **Ideas**, and look at **Ideas come from**:

- **The Warden inbox**: ideas you file by hand. Always on.
- **GitHub issues**: optionally filtered by a label, synced every 1, 6 or 24 hours. Only issues opened after you turn this on are filed.
- **Pick Linear / Jira tickets**: choose tickets to import from a connected Linear or Jira.
- **Add a source**: pull from any connected integration (Sentry, Datadog, PostHog and others), by running a skill, or by asking an agent with the project's integrations. Name the source, say whether it files bugs, features or chores, and describe what to pull.

Connect the integration first in the project's **Integrations** tab. Until you do, a source shows *No integrations are enabled for this project yet*. Pulls are read-only, take at most 20 items at a time, and file each item once.

Automations can also file work: the automation action **File ideas into the Software Factory** turns, for example, a nightly error report into ideas. See [Automations](automations).

## Customise the pipeline

The header shows which pipeline is in force: **System pipeline**, or **‹project› pipeline · Customize** once you have changed it. Pick a single project, then press the pipeline button to open the pipeline studio. The first change you make gives the project its own copy; **Reset to system** goes back.

**Start from a template…** gives you a sensible base:

| Template | What it sets up |
|---|---|
| **Team default** | Express for trivial changes, a plan for most work, a spec for risky work. A person decides at triage, reviews and merges. |
| **Solo, fast** | Confident trivial ideas go straight to Express. Planned work builds by itself and ships when policy allows; specs still need a person. |
| **Triage decides** | Triage proposes plan or spec and the assurance level for each idea; you confirm. Specs always get a person. |
| **Regulated** | No unattended lane. Everything is proven by a test, large work to L2, and a person reviews and merges every change. |

The studio has four tabs, and **Try an idea** under every tab shows how a sample idea would travel through your pipeline before you commit to it.

### Flow

The stages, left to right. Select a stage to edit it:

- **Triage, Shape and Build** each take a **Model** (Auto uses your Model policy: *Planning & architecture* for triage and shape, *Code generation* for build, *Bug fixing* for bugs), a **Skill**, and free-text instructions.
- **Build** sets **New builds start from**: *Latest default branch on origin (recommended)*, *Your current checkout*, or *Ask each time*. It also has **Agents never commit**, for when you want to review and commit by hand.
- **+ Add a step** inserts a custom stage: a skill, a workflow, a command, *Ask an agent*, or an *Adversarial review*. A step runs by itself or waits for a person, is required or advisory, can apply to some lanes only, and has a time limit (5 minutes for a command and 10 otherwise, up to 240).
- **+ Add an environment** adds a stage after Main. Define **Shipped when**: a branch contains it, a matching tag contains it, or a GitHub deployment succeeded. See [stages](factory-stages#staging-and-production).

### Lanes

What each lane does: its shape (none, plan, spec, or triage decides), its assurance level, how it builds, who reviews, whether it is checked against the original ask, whether it merges here or opens a pull request, and whether triage may auto-accept into it. See [Lanes and gates](factory-lanes).

### Who decides

Rules that change review, merge, auto-start or the minimum level for some items, applied in order after the lane's defaults and triage's choice. Use **Always needs a person** to list paths (for example `*/migrations/*` or `*/.github/workflows/*`) where an unattended run must stop for a person.

### Lifecycle rules

Ready-made rules for the moves themselves (*Migrations need a person*, *No unattended merge after hours or on Fridays*, *Large changes need a person*, *Link a ticket before merge* and more), plus **Parallel builds**: what happens when two builds touch the same files (*Off*, *Warn*, *Queue* or *Strict*).

## Parallel builds and worktrees

Each chat build gets a fresh git worktree, so builds never trip over each other or over your own checkout.

- **Ready to work.** New worktrees clone the checkout's dependencies (`node_modules`, `.venv`) as copy-on-write clones, so a build starts in seconds. Secrets and `.env*` files are never copied.
- **Services per worktree.** Set up `.warden/services.json` under **Assurance → Services** (Warden detects most of it). Each worktree then gets its own ports, and a Factory build starts its own services and stops them when the worktree goes.
- **Overlaps.** With **Parallel builds** on *Warn* (the default), the Factory shows when two builds touch the same files but starts them anyway. *Queue* holds a build that shares more than a set number of files; *Strict* holds any overlap and makes edits outside the build's claimed files ask.

Up to two sandboxed builds run at once. Triage, drafting and reviews run one at a time.

## Where things are stored

| What | Where |
|---|---|
| Plans | `.warden/plans/<slug>/` in the repo: `meta.json` plus `v1.md`, `v2.md`… |
| Specs | `.warden/specs/<slug>/` in the repo: `requirements.md`, `design.md`, `tasks.md`, `invariants.json`, `meta.json` |
| Worktree services | `.warden/services.json` in the repo |
| Pipeline and items | In Warden on your Mac, per project |
| Factory rules | Your policy files, edited under **Policies** |

> [!LIMIT] One machine
> The pipeline and the Factory's items live in Warden on your Mac. They don't sync to teammates yet, and nothing moves while Warden is closed.