How the Factory works

The Factory runs coding agents on your machine against a plan you approve. You describe the outcome, review the Tasks, and come back when a Task or pull request needs a decision.

The pieces

Piece	What it is	Where it runs
Task	One unit of work: an objective, acceptance criteria, verification steps and its dependencies. Tasks that share an `epic` label form a plan.	ArchDev (shared with your organization)
Overseer	The agent you talk to in `archdev agents factory run`. It turns your goal into Tasks, assigns them to workers and asks you only when a decision needs a person. It hands implementation to workers.	Your terminal
Workers	Coding agents (3 by default) that each take one ready Task, implement it in their own worktree and call `done`.	Subprocesses of the overseer
Daemon	A per-user background service. It verifies each worker's exact commit, runs the review pipeline, opens the pull request and follows up on CI and review feedback.	launchd / systemd / Task Scheduler
Model provider	The models behind the overseer and workers: the ArchDev Model Router (paid from ArchDev credit), your ChatGPT or SuperGrok subscription, an API key, or your Claude Code login.	—

What happens to one Task

you ── goal ──▶ overseer ── plan ──▶ review in browser ── approve ──▶ Tasks (ready)
                                                                       │
            ┌──────────────────────────────────────────────────────────┘
            ▼
   worker claims Task ─▶ worktree from origin/main ─▶ implements + tests ─▶ done
            │
            ▼
   host commits "factory: <task>" ─▶ archdev push ─▶ daemon branch_update job
            │                                         (review → fix → publish)
            ▼
   pull request opened ─▶ Task: in_review ─▶ CI / review feedback handled by daemon
            │
            ▼
   PR merged ─▶ Task: done ─▶ dependent Tasks become ready

Plan. The overseer (or your own coding agent with the tasks skill) drafts a Task graph. You review it in the browser and approve it. Approval creates the Tasks in ArchDev.
Claim. An idle worker claims a ready Task. A Task is ready when it is open, assigned to you, has no open blockers and belongs to this repository.
Build. The worker gets a fresh worktree under ~/.archdev/factory-worktrees/ on branch factory/<task-id>, starting from origin/main. It may make its own commits; it never pushes.
Commit. When the worker calls done, the Factory commits any remaining changes as factory: <task name>. Your repository's pre-commit hook runs. If it fails, the worker receives the output and fixes it, for up to 3 rounds.
Verify and publish. The Factory pushes the branch to your private ArchDev remote. The daemon runs the branch_update pipeline on that exact commit: by default it reviews the commits, fixes supported findings and opens the pull request. The PR body links the epic and Task.
Follow up. The daemon watches the pull request. CI failures, review comments and rebase conflicts start remediation jobs. When the PR merges, the Task closes and the Tasks that depend on it become ready.

The Factory pauses a Task and asks you only for decisions a worker should not make alone: credentials, spending, live infrastructure (including merging), irreversible actions, product decisions, or a sign-off the Task names. Each question comes with a recommended answer.

You answer in the overseer's Needs you tab, at archdev.ai/tasks (Needs you view), or with archdev tasks answer. See Run the Factory.

Set up the Factory: install the CLI, connect models and install the daemon (about 15 minutes, once per machine).
Plan work as Tasks: write and approve a plan.
Run the Factory: start it, watch it and answer its questions.

The pieces

What happens to one Task

When you are needed

Next