A Pi package that runs one ticket from planning through work, review, and wrap-up to a human handoff. Coordination lives in a TypeScript controller. Skills describe specialist behavior only.
Pi loads src/extension/index.ts and the skills/ directory from this package. The controller runs in the factory server, and Pi is one of its clients: /factory start, reply, retry, and complete go to the server's API with the token in .factory/local.token, while status, the ticket and agents views, the widget, and the status cards read .factory/db/state.sqlite directly. Pi looks for new events about once a second and shows the cards the server posted since. With no server running, a command says how to start one and changes nothing. Any number of Pi sessions can watch the same factory. .factory/FACTORY.json must already exist and name distinct models.work and models.review. models.plan defaults to the work model.
/factory start <github-url | owner/repo#n | #n | local-file>
/factory start --text <id> <ticket text>
/factory reply <ticket> "answer"
/factory retry <ticket>
/factory complete <ticket>
/factory feedback <ticket> [--list] [--only <refs>] [--skip <refs>] ["note"]
/factory stop <ticket>
/factory cancel <ticket> ["reason"]
/factory rerun <ticket>
/factory status <ticket>
/factory update [--check | --later | --when-idle | --rollback [--yes]]
start resolves the ticket, freezes the source, adds the ticket's git worktree at .factory/worktrees/<slug> (see Worktree base), and launches the planning agent in it. Repeating it does not open another child. An issue with sub-issues is an umbrella and is rejected; see Tracker and code host. After plan.md and at least one task file exist, each task file's frontmatter (type, qa, blocked_by) is valid, and .factory/CONTEXT.md has its required sections, the controller registers the task graph and launches the first dependency-ready work agent in the same worktree. The plan is those files; the planner's factory.plan.v3 reply is a suggested summary, not a requirement. When the factory root has no CONTEXT.md, the plan prompt asks the planner to create it with the sections Commands, Environment, Test layers, Servers and ports, Known flakes, Fixtures and fakes, and Vocabulary (see the CONTEXT.md reference); a file over 150 lines passes with a warning.
Linked issues. The planner also gets the ticket's linked issues, one level deep, so a follow-up is planned with the issues it builds on. When the worktree is ready, the controller asks the tracker once for the issue's parent, sub-issues, blocking and other native relations, and the issues its description names (ENG-42 keys and Linear URLs on Linear; #n, owner/repo#n and issue or pull request URLs on GitHub). The plan prompt lists them after the ticket body, one line each: the relation, ref, state, title, attached or closing pull requests, and comment count, with no descriptions or comments. limits.linkedIssues (default 20) bounds the list, and a last line says how many were left out; 0 reads none. The read runs off the controller's dispatch loop, so a slow tracker holds up only that ticket's plan; a server stopped meanwhile prepares the worktree again when it restarts. Refs in the description are looked up only while there is room under the limit. A failed read is retried three times, after 1, 2 and 4 seconds; only a ref the tracker says names nothing is dropped, and any other error counts as a failure. A read that still fails leaves the plan going: the prompt says so and the server log says why. Corrections and resumed sessions do not read them again. Links are read on the ticket's own GitHub host, even when it is not FACTORY.json's. Stage sessions need no tracker key for this; the planner reads a pull request that matters with gh, and the factory-plan skill says how to use each kind of link. A ticket from a file or text, or from a tracker other than the configured one, gets no links.
caller_ping stores the question and waits. reply resumes that same session. A failed resume keeps the answer; retry reuses it. Plan validation may resume the planner three times. Launch failures retry separately and do not spend that budget.
When a worker finishes, the controller inspects the worktree diff and runs the trusted validation.work.commands. A failure resumes the same worker with the exact failures. A pass launches a read-only reviewer on models.review with the diff that was checked.
Validation selection. A selection is optional: it gives the project's validator the tests a worker found, so it can run just those. A worker that found focused regression tests from its own diff lists them under ## Validation selection in its reply, one line each: - `tests/test_filter.py`: checks disabled entries are excluded, with the path relative to the repository root. Without the section, or with none alone under it, FACTORY_VALIDATION_SELECTION is unset and the validator uses its default behavior. The controller passes them to each validation.work.commands command as FACTORY_VALIDATION_SELECTION:
{
"version": 1,
"tests": [{ "path": "tests/test_filter.py", "reason": "checks disabled entries are excluded" }]
}It keeps the configured argv; the project's validator decides how to run the paths. Each command gets an environment of its own, so parallel tickets never see each other's selection, and without a selection the variable is unset. A malformed entry, or a path that is not a file in the worktree, is a work correction that says how to write it, before any command runs: a selection known to be wrong is never passed on, and the commands do not run without it in its place. A selection holds for its round of work: a correction reply that leaves the section out keeps it, and a later round, after review or QA returns the task, starts without one. A retried validation uses the selection of the run it validates, and QA validation's run of the work commands uses the task's latest round's. The worker's ## Tests stays its report of what it ran; the reviewer reads the same round's reply, and its validation summary names the files the commands got.
The reviewer's project rules come from the ticket's base commit, not from its branch, so the work under review cannot change the rules it is judged by. The reviewer starts with Pi's --no-approve, so Pi treats the project as untrusted even when a directory above the worktree is trusted: none of the worktree's .pi settings, extensions, skills, or prompt templates load. It also starts with --no-context-files, and with the factory's factory-review skill by path through --skill, which loads untrusted (an installed factory package's copy wins when there is one; the single executable writes its carried copy under .factory/runtime/skills). The controller reads each AGENTS.md, AGENTS.override.md, or CLAUDE.md that Pi would find inside the code root, following symlinks, with one git ls-tree and one git cat-file --batch at the base commit, and passes them, labelled with the base branch and short SHA, through --append-system-prompt. A directory between the code root and the worktree, such as .factory, gives its tracked file at the base commit, else its file on disk. The base commit's .pi/SYSTEM.md goes through --system-prompt, and its .pi/APPEND_SYSTEM.md through --append-system-prompt in place of the agent directory's. Context files outside the code root, such as Pi's agent directory's and those of the directories above the code root, and the agent directory's APPEND_SYSTEM.md when the base commit has none, are passed as they are on disk. When the diff changes a rule file (one of those context files, .pi/SYSTEM.md, or .pi/APPEND_SYSTEM.md), the review prompt names it, and the reviewer gives it a Verification line: in_scope when the task asks for the change, which is then reviewed as part of the task, or out_of_scope, which needs a Major finding naming the file. Changes stay uncommitted until wrap-up, so a later task's diff still holds an earlier task's rule change: an approving review records each rule file's diff hash in the task's review summary, and a later task's review names that change as accepted, with no Verification line, until the file's diff changes again. A base commit that cannot be read pauses the ticket with project_rules instead of retrying the launch; /factory retry validates the previous stage again, which starts the review again. Review validation records which base commit the rules came from, and the handoff lists the rule files the ticket changes. Plan, work, QA, and wrap-up keep the rules in their worktree, because a ticket may be about changing them.
The reviewer returns the factory.review.v5 template. Its ## Verification section has a line per acceptance criterion, per changed project rule file, and, from round 2, per earlier blocking finding, each citing the code it checked or giving its reason. The controller parses the verdict, findings, and Verification lines; checks that every expected id is there and every cited path:line exists in the worktree; then checks that the reviewer was isolated and that the worktree diff has not changed since the reviewer received it. A problem comes back to the reviewer as a correction.
approvemarks the task done and starts the next dependency-ready task. After the last task, the controller launches wrap-up.changes_requestedresumes the same worker with only the blocking findings. Work validation runs again, then the same reviewer session reviews round 2.limits.reviewRounds(default 3) bounds the rounds; at the limit the ticket pauses andreplyresumes the reviewer with your decision.blockedpauses the ticket.replyresumes the reviewer.- A result the controller cannot parse resumes the reviewer with the parse errors. That does not spend a round.
limits.reviewCorrections(default 3) bounds it per round. - A diff that changed during review is validated again before another review in the same round. The reviewer gets the worktree as it stands after the validation commands. A second change in the same round pauses the ticket, because something keeps writing to the worktree; ignore the generated files, then
retryvalidates the work and reviews it again.
Launch failures and crashes use limits.infrastructureRetries and never spend a correction or a review round.
QA is an optional stage between work and review, on when FACTORY.json sets stages.qa.enabled and lists at least one stages.qa.commands. It reads the task file's ## Acceptance criteria (AC1..ACn) and launches the factory-qa agent on models.work in the worktree. QA owns the task's end-to-end tests, the ones that prove a criterion from outside the code: through a browser, an HTTP API, a job, or a CLI. The work prompt says so, and the worker writes unit and component tests instead. The agent proves each criterion a user can observe at the cheapest layer that runs the real code (a browser end-to-end test for a user path through the running app, a component test or story for a component's look or state, a request through the framework's test client for an API, a synchronous run for a job, a run of the command for a CLI; see the API reference), extending the feature's existing spec rather than a per-task file, lists the others in the ledger with what covers them, and test-plan.md, ledger.md, and screenshots/ under tickets/<slug>/qa/<task>/. The controller checks that every criterion is tested or in the ledger with a reason and that each screenshot exists, then runs the QA commands itself:
- missing or incomplete QA output resumes the QA agent with the failures, up to
limits.qaCorrections(default 2) per round; - a failing QA command returns the task to work with the failure; work's validation runs again, then QA again.
limits.qaRounds(default 3) bounds the rounds; at the limit the ticket pauses andreplyresumes the QA agent; - after the QA commands, the controller runs every
validation.work.commandsagain, then anyvalidation.qa.commandswork does not run, so code QA wrote meets the project's bar: a test QA wrote must pass the type check work had to. A failure whose output names a file QA changed this round resumes the QA agent as a correction, ahead of any other failure; any other failure returns the task to work; - a pass hands review the diff QA left, tests included, and the checks behind it: the work checks as they stand after QA and QA's own, grouped under Work and QA in the review prompt. Wrap-up lists the screenshots for the pull request.
Every stage after work is given the worker's latest reply for the task, in every round. When a later round's reply is empty, the last reply with text stands in, marked as such.
For a service without a browser harness, the QA command is the project's test runner, and the screenshots stay none:
"stages": {
"qa": {
"enabled": true,
"commands": [{ "name": "api", "argv": ["uv", "run", "pytest", "tests/api", "-x"], "timeoutMs": 300000 }]
}
}With QA on, the plan must give every task at least one acceptance criterion. A task file opts out with qa: none in its frontmatter when no criterion is observable in the running product (a data layer change, docs, an ADR): the task goes from work straight to review, and its QA summary reads skipped. With qa: e2e, QA runs, for an API, job or CLI criterion too: e2e means from the outside, not through a browser.
After the last approval, the controller checks the wrap-up input in code: every task is done with an approving review, the plan and task files exist, the worktree is ready on its branch, and no other child runs. It records the worktree, refs, and factory files as a baseline, then launches the factory-wrapup agent on models.work in the worktree. A failed check pauses the ticket; retry checks again.
The wrap-up agent returns the factory.wrapup.v2 handoff. The controller keeps it as written and validates it against the repository:
## Issue checklisthas one line per open checklist item of the ticket's issue,B1..Bn:metcites a task criterion (Task 01 AC2) that review verified or QA's test plan covers, or a worktree file, and is refused while an open review finding, minor included, names that criterion;not_metgives a reason.## Decisionsisnoneor bullet points;- every heading is present;
## Fileslists every changed path and no other;## Testsnames thevalidation.work.commands;## Merge commandsholds a pull-request URL or commands with the real worktree and branch; - wrap-up changed no product code: a change it makes must be documentation, or a generated artifact listed in
validation.wrapup.generated, and must be named in## Files; - in the factory root only
CONTEXT.md,PRD.md, andlearnings/may change; nowrapup.mdorvisuals/. Other tickets' directories, the controller's own files (db/,runtime/,local.token, …), and validators' artifacts invalidation-logs/are not compared, so tickets running beside this one never fail its wrap-up; a wrap-up paused on such a change before completes on its stored baseline. OS metadata (.DS_Store,._*,Thumbs.db,desktop.ini), which a host's file browser can write through a mounted repository, is never compared, here or among the worktree's untracked files, and an untracked one is not part of the work diff; - nothing was merged, the base branch did not move, and the branch still exists;
- with
codeHost.pullRequestsoff, nothing was committed or pushed, and## Merge commandsprints the commands; - with it on, wrap-up commits the approved work on the ticket branch. Its commits sit on top of the commit wrap-up started from, with no merge and no rewritten history, and hold only paths
## Fileslists. Once anything is committed the worktree must be clean, and with a clean worktree the pull request must exist for the branch with the local HEAD as its head and the titlecodeHost.pullRequestTitlegives. If committing fails, the worktree stays uncommitted, nothing is pushed, and the commands are printed instead.
A failed validation resumes the same wrap-up session with the exact failures; wrap-up corrections have no limit. When validation fails with exactly the failures of the latest correction, the agent could not fix them, so the ticket pauses with wrapup_failure_repeated instead: /factory retry validates the latest run again once the cause is fixed, and a reply resumes the agent. A pass sets the ticket to wrapup / ready_for_handoff, opens two panes without a model turn (📦 <ticket> reopens the wrap-up session on its own model, 🔀 <ticket> shows the ticket's diff since its base commit (after a feedback round, only the round's diff, since the commit it started at), in Hunk when hunk is on PATH, else in Fresh; FACTORY_HUNK_BIN and FACTORY_FRESH_BIN name other binaries; in Hunk the diff carries notes from the handoff: what each ## Files line says about its file, each decision on the lines it cites, and each open review finding at its location), and posts a notice with the all-stage usage table. A pane that fails to open retries and never fails the handoff. On a tracker issue, the controller ticks the met items through the tracker and posts one handoff comment with the decisions and the items left open; a rerun replaces that comment. An item someone changed on the issue stays unticked, and the comment and a warning on the ticket say so. None of this can fail the handoff.
/factory feedback <ticket> ["note"] takes the feedback the ticket's pull request got after handoff back through work, review, and wrap-up, on the same worktree and branch, and ends with a new commit pushed to the same pull request. It works only at wrapup / ready_for_handoff, with codeHost.pullRequests on and an open pull request recorded for the ticket whose head is the worktree's; anything else is refused with invalid_state, and nothing changes. A pull request gh cannot read is refused with code_host_unavailable.
- What counts. The server reads the pull request with one
gh api graphqlcall: its unresolved review threads, shown whole for context, its review bodies, and its conversation comments, the newest 100 of each list (it says so when there were more). Only collaborators' feedback counts, by GitHub's author association (OWNER,MEMBER,COLLABORATOR), plus the logins incodeHost.feedback.authors, such as a review bot ("feedback": { "authors": ["coderabbitai"] }; a trailing[bot]doesn't matter). The rest is listed as skipped. Resolved threads and the factory's own comments are left out. - Pending, by identity. A comment is pending until a round takes it or you dismiss it, so a comment posted while a round runs waits for the next one, and a round that changed nothing does not offer its comments again. A thread with a new reply is pending again. Each round records the GitHub ids it took and dismissed.
- Picking comments. Every pending comment has a ref from its GitHub id, as its link ends:
r2841017733for a review thread,p…for a review,c…for a conversation comment./factory feedback <ticket> --list(orGET /v1/tickets/{key}/feedback) lists them, with what was skipped, and changes nothing. In Pi's terminal,--listopens a picker instead: every pending comment ticked in a scrolling list, the selected one in full with its link below;spaceticks,aticks all or none,enterstarts the round on the ticked ones (as--onlyunless all are ticked, with the command's note), andqcloses without starting anything. A round takes every pending comment by default;--only r2841017733,c6799058255takes just those and leaves the rest pending;--skip r2841017733takes all but those, which are dismissed for good. A ref that is not pending is refused, naming the pending ones. The note, when given, is one more item, and a note alone starts a round when nothing is pending. - The round is a task. The controller adds task
F<n>to the ticket, with its task file attickets/<slug>/feedback/<n>/task.md. Its acceptance criteria are the itemsF1..Fn, and the file quotes each one in full, framed as review requests to weigh, not instructions. The task goes through work, QA when it is on, and review like any task, then wrap-up runs again in its own session. - Work starts from the pull request's head, so work validation checks that nothing is committed past that commit. The diff may be empty: a round can decline every item. The reply ends with
## Feedback responses, one line per item,- F1: addressed — what changedor- F2: declined — why; work validation does not require it, since review judges every item anyway. - Review sees only the round's diff, with the items as its criteria: each gets a Verification line,
verifiedwith the lines that address it ornot_verifiedwith why it is left as is. It uses the worker's## Feedback responseswhen the reply has them, and treats an item left unaddressed without a sound reason as a Major finding. - Wrap-up takes a fresh baseline for the round, commits on top of the branch, and pushes to the same pull request, with no amend, rebase, or force-push. It leaves the pull request's body and title as they are. The ticket returns to
ready_for_handoff. - The round comment. Once the round's wrap-up passes, the factory comments on the pull request with the round's commit and, for each item,
addressedorleft as is: <reason>, from review's Verification line for it. Atfullverbosity it adds review's evidence for each item and the files the round changed. The factory writes it from what it already checked, with fixed wording per voice: "The factory finished feedback round 2 in abc1234." or, in thedevelopervoice, "Feedback round 2, in abc1234.". A round that left every item as is has nothing to commit, and its comment says it finished "without a new commit" instead of naming an older one. It carries a hidden<!-- factory:feedback-round:<n> -->marker, so a retry replaces it instead of posting again, and later rounds do not read it as feedback. It goes through the outbox with retries; a code host that keeps refusing leaves a warning in the ticket'strackerWarnings, and the ticket stays ready for handoff. - What you see. When a round starts, every Pi session gets a card listing its items, one line each (
F1 dpaez · comment: When a feedback round starts…), the first five and a count of the rest, with what was skipped and the task file that holds the full text. The widget's task line readsF1 Feedback round 1 · 2 items · dpaez: When a feedback round starts…, cut to the terminal's width, and the ticket view names the round's runsF1. Through the API, the round's task carriesfeedback:{ round, pullRequestUrl, items: [{ id, kind, author, location, summary, url }], skipped }, with each item's first line (160 characters at most) and its link; it isnullon a planned task. - Panes. The round closes the earlier handoff's
📦and🔀panes when its work starts, so the round's wrap-up is the only Pi with the wrap-up session open, and its handoff opens fresh ones. A pane is closed only while a process in it carries its ownhandoff:<action>marker (FACTORY_WORKTREE), so a pane that Herdr gave a closed pane's id to stays open. limits.feedbackRounds(default 3) bounds the rounds per ticket; one past the limit is refused with a message.
The tracker adapter decides what an issue's checklist is: wrap-up's input preparation asks it for the items, numbers the open ones B1..Bn, and keeps each one's key in the wrap-up baseline, so corrections and validation judge the same list. On GitHub the checklist is the Markdown boxes (- [ ], 1. [ ]) in the issue body, outside code fences, each keyed by its text and which box of that text it is; ticking re-reads the body and flips only those marks, leaving every other byte as it was. A tracker without a checklist capability gives wrap-up no boxes, and the factory only comments. A tracker that cannot be read leaves wrap-up without boxes and says why in its prompt. Merge the work yourself, then /factory complete <ticket> moves it to done / complete. Repeating start on a ticket ready for handoff only reports its state. Merging always stays with you. Commit and push do too unless codeHost.pullRequests is on.
Cleanup. A completed ticket's worktree, with the dependencies and build output its runs left, and its local branch take disk space that new tickets need. Once a ticket is complete, by /factory complete or a merged pull request, the server removes them, as far as that is safe:
- The worktree goes only if the factory made it (under
.factory/worktrees/, as git lists it), no change in it is uncommitted or untracked (ignored files, such asnode_modules, do not count), and no process runs in it. - The local branch goes only with its worktree, and only if its commits are on a remote branch, or in the ticket's merged pull request (its remote branch may be deleted), or it has none of its own.
- Remote branches, cancelled tickets (cancelling promises the worktree stays), and failed ones, which
retrymay resume, are never touched.
It runs once the ticket's tab has closed, so the handoff panes have left the worktree, and waits a few seconds for their processes to exit. What stays, and why, is a card on the ticket and a server log line. Cleaning up is idempotent: a request while one runs for the same ticket joins it, a later one finds what is already gone, and the card goes out again only when the outcome changes. factory cleanup applies the same checks to every completed ticket, such as those that completed before, or after you resolved what a cleanup kept; --dry-run says what would go and changes nothing. Running it again finds what is already gone.
The factory server hosts the controller outside Pi, so tickets keep moving with no Pi session open (ADR-003). It dispatches, recovers runs, serves the API below, and creates .factory/db/state.sqlite on its first start. The remaining routes follow in the build tickets.
Prebuilt binaries for Linux arm64 and x64 are published on the Releases page, each with a .sha256 checksum. They need no Node and no checkout of this repository, and run on glibc 2.28 or newer. Download one and run it from the repository root inside a Herdr pane:
arch=$(uname -m | sed 's/aarch64/arm64/; s/x86_64/x64/')
curl -fsSL -o factory "https://github.com/geut/factory-skills/releases/latest/download/factory-linux-$arch"
chmod +x factory
./factory serveOn another platform, or to run unreleased changes, build the single executable yourself:
npm run build # writes dist/factory for this OS and architecture
dist/factory servenpm run build bundles src/cli.ts with esbuild and injects it into a copy of the running node (single executable applications). Build on the platform that runs it. node src/cli.ts serve runs the same server from source.
A release is one artifact: the binary is all a factory needs, with no Pi package to install. It carries:
- the agents' extension, which it writes to
.factory/runtime/child-handshake.ts; - every stage skill, written to
.factory/runtime/skills/and passed to each agent with--skill; - the operator's Pi extension (
/factory, the widget, and the cards). On every start the binary writes it toextensions/factory/index.jsin Pi's agent directory ($PI_CODING_AGENT_DIR, else~/.pi/agent), which Pi loads on its next start or/reload.
The extension file is global to the machine, but whether Pi also loads factory-skills as a package depends on the project. So the binary always writes it (a directory it cannot write only prints a warning), and the installed copy decides each time Pi loads it: where Pi's settings for that session, personal or the project's .pi/settings.json, list a factory-skills package, it registers nothing, and the package's copy is the one Pi uses. A package counts by what it is: a git source by its repository name, an npm source by its package name, a local path by the name in its package.json, so a checkout or worktree under any directory name counts. Pi also keeps the first skill of a name, so an installed package's skills win over the binary's.
A pinned git or npm install keeps Pi on that version, so the server names it once at start with the pi remove command that lets updates reach Pi. Remove an old git install (pi remove git:github.com/geut/factory-skills@v…) once the binary carries the extension; keep a local checkout's package while you develop the factory.
- The server refuses to start outside Herdr. It needs
HERDR_PANE_IDandHERDR_SOCKET_PATH, plusherdr(0.8.2 or newer) andpionPATH;FACTORY_PI_BINoverrides the path topi. - Agent and handoff panes open through the factory's own Herdr plugin,
geut.factory. On every start the server writes its manifest to$XDG_DATA_HOME/factory/herdr-plugin/(~/.local/share/factory/herdr-plugin/by default) and runsherdr plugin linkon it, so there is nothing to install. Its pane runs the launch script directly in non-interactive bash, so shell setup that prints or prompts cannot swallow the launch. A failed link stops the server with the command to run by hand. - Agents see the server's
PATH, and itsBASH_ENVwhen set. Herdr opens panes with its own environment and agents run non-interactive bash, which never reads~/.bashrc, so every pane's launch script exports both. Whatever the server can run, its agents can run too, so startfactory servefrom a shell where the project's toolchain (pnpm,bun, ...) is onPATH. - Each agent's launch script also exports
FACTORY_WORKTREE, its worktree, andFACTORY_RUN_ID, which every process it starts inherits. Handoff panes exportFACTORY_WORKTREE=handoff:<action id>, which names no worktree. Before a work or QA run, the controller stops the user's processes that belong to a worktree under.factory/worktrees/whose execution is complete, cancelled or retired, or whose directory is gone. A marked process belongs to what its marker names; an unmarked one to its working directory. They get SIGTERM, then SIGKILL after 3 seconds. Paused and failed tickets keep theirs, and processes outside the factory are never touched. Each one becomes astray_process_stoppedorstray_process_stop_failedevent on the ticket, with its PID, command and worktree, and a card lists them. A failed sweep is reported and never blocks the run. - It listens on
server.hostandserver.portfromFACTORY.json,127.0.0.1:7731by default. Bind0.0.0.0to publish the port from a sandbox. The server warns when it listens off loopback, because it speaks plain HTTP. - One server owns a factory root. It holds a lease row in SQLite with its URL and a heartbeat, and a second server refuses to start while that lease is live. A lease whose process is gone, or whose heartbeat is older than 15 s, is taken over.
- Each ticket gets its own Herdr tab, named after it, in the server pane's workspace. Every agent, and each handoff pane, opens in its own pane in that tab, and the pane closes when its Pi exits. The tab's starting shell closes once the first pane is open, and a resumed agent's pane opens before the finished one closes, so the tab stays while the ticket runs. The tab closes when the ticket finishes. The panes of each tab are remembered in
.factory/runtime/tabs.json, so a restarted server keeps using them. A tab that cannot be made falls back to splitting the server's pane. - Every
ghcall the server makes runs as a child process it awaits, so a slow or stuck GitHub never blocks the API, webhooks, or other actions. A call that takes longer than five minutes is stopped and fails like any othergherror: a tracker update or pull request write retries, a pull request sync tries again next time, and a feedback command is refused withcode_host_unavailable.FACTORY_GH_BINnames anotherghbinary. - On SIGINT or SIGTERM it stops dispatching, releases the lease, and exits. Agent panes keep running, and the next start adopts them with
recover(). - It upgrades a schema 3 database in place the first time it opens it. It first copies the database to
.factory/db/state.schema-<N>.sqlite, where N is the old schema version, and does not upgrade if the copy fails. An upgraded database refuses older controllers. To go back to one, stop every factory server and Pi session, replacestate.sqlitewith the copy, and deletestate.sqlite-walandstate.sqlite-shm. Anything recorded after the upgrade is lost.
The server checks GitHub for an update, a stable release newer than the one it runs, once a day through gh. The day counts from the last check recorded, so restarting the server does not check again; a server on a new version checks when it starts. Drafts and pre-releases never count. A check that fails stays quiet and the next one tries again. "updates": { "check": false } in FACTORY.json turns checks off. What a check found lives in .factory/runtime/update.json, which only the server writes.
When a check first finds a release, every Pi session running then posts one card. However many releases the factory skipped, the card names only the newest, and its link covers them all: the release's notes, or GitHub's compare page from the running version.
⬆ factory 0.6.0 is available · you run 0.3.0
What's new in 0.6.0
https://github.com/geut/factory-skills/compare/v0.3.0...v0.6.0
→ /factory update · later: /factory update --later
Pi's footer keeps ⬆ factory 0.6.0 until the factory runs it; a session started after the check shows only the footer line. /factory update --later stops the cards for that release and dims the line; a newer release brings both back. /factory update --check checks now; outside Pi, factory update --check asks GitHub directly and needs no server.
Updating installs the newest release and restarts the server on it:
/factory update in Pi
factory update on the command line
POST /v1/factory/update for a client such as the dashboard
- The server downloads this machine's binary (
factory-linux-<arch>) and its.sha256from the release withgh, and checks one against the other. A mismatch, or a failed download, stops with nothing changed. - It copies the running binary to
factory.previousbeside it, then renames the new one into place. - It opens a new Herdr pane, beside its own, running
factory serve --after <its instance>, then stops. The new server waits for it to hand back the lease (up to a minute), takes over, and adopts the running agents, as on any restart. The pane's script carries the old server's environment (PATH, API keys, and the rest), so it is written to.factory/runtime/with mode0700and deletes itself as it starts.
A Pi session keeps the extension it loaded at its start. When the server it talks to restarts on another release, the session posts one card, ⟳ The factory server is on 0.6.0; this Pi runs 0.5.0, and its footer shows ⟳ /reload for factory 0.6.0 until /reload loads the matching extension. Pi asks the server's version (version in GET /v1/factory) when the session starts and whenever the server restarts; builds of one release count as matching, and with no server running Pi says nothing.
If the new pane cannot open, the server keeps running and says so; the binary on disk is already the update, so restarting factory serve runs it, and /factory update tries the restart again without downloading.
--when-idle(/factory update --when-idle,factory update --when-idle, or{ "whenIdle": true }) records the update as pending, and the server runs it once no agent runs and no action is queued. Pi's footer shows· when idlemeanwhile. An update that fails then is not retried.- On the command line,
factory updatehands off to the server running for the repository. With none running, it replaces the binary itself, and the nextfactory serveruns the new version.factory --versionprints the version a binary is. - Factories sharing a binary. Every factory on a machine that runs the same
factoryfile shares its updates. A server looks at its binary on disk every 10 seconds and asks it--versionwhen the file changed; when it holds a newer version than the server runs, Pi posts⬆ factory 0.6.0 is installed · restart to use itand the footer shows· restart./factory updatethere only restarts. - Running from source (
node src/cli.ts serve), updating says to usegit pulland does nothing else. - Rolling back (
/factory update --rollback,factory update --rollback, orPOST /v1/factory/rollback) goes back to the version the last update replaced. An update writesfactory.previous.jsonbesidefactory.previous, naming its version and the database schema it runs. Rollback swaps the two binaries, so rolling back again goes forward, and restarts as updating does, except that the new pane waits for this server's process to exit (an older binary may not knowserve --after). The release rolled back from stays on offer without its cards, as after--later.- When the update's server upgraded the database, the older version cannot open it. Rollback then restores the backup the upgrade made,
.factory/db/state.schema-<N>.sqlite, after this server stops and before the older one starts. It first names the backup and what restoring it loses, the events recorded since and their tickets, and waits for a confirmation: a dialog in Pi,--yeselsewhere,{ "confirm": true }through the API. Without the backup it refuses and says why. - With no
factory.previous, or one that no update put there, it refuses. If the new pane cannot open, the binaries are swapped back and nothing changes. - Factories sharing a binary share its rollback too: one that already upgraded its own database needs its own backup restored before the older binary can open it.
- When the update's server upgraded the database, the older version cannot open it. Rollback then restores the backup the upgrade made,
The server's routes are declared once, in src/api/routes.ts, with Zod schemas. The router validates every request against them, and the OpenAPI 3.1 document is generated from the same list. GET /openapi.json serves it without a token, and openapi.json is the committed copy that clients generate their types from.
- Routes live under
/v1./healthand/openapi.jsonsit outside it. - Errors are RFC 9457
application/problem+jsonwith a stabletypecode, listed insrc/api/problem.ts. Avalidation_errorlists each bad field, such asbody.reforquery.stage. - Source runs and tests also check every response against its schema; the single executable does not.
- A test fails when
openapi.jsonno longer matches the routes. After changing a route, runnpm run openapi:updateand commit the document.
Reads need a read token.
| Route | Returns |
|---|---|
GET /v1/tickets |
Each ticket's current execution: stage, status, progress, whether it needs a person, and who started it. |
GET /v1/tickets/{key} |
The same, plus the source it started from, tasks with dependencies and review state, questions with their replies, usage, and its controllerStep (null when none). |
GET /v1/tickets/{key}/runs |
The ticket's runs, oldest first. |
GET /v1/runs/{id} |
One run: purpose, round, outcome, model setup, latest validation and its checks, review findings, usage, and its latest activity. |
GET /v1/agents |
Runs that are starting or running. |
GET /v1/controller-steps |
Each current ticket's controller step: what the controller runs for it between agents, else the next action queued, with the command a long step is on. |
/v1/ticketsfilters bystatus=open|finished|all(defaultopen),stage,state(the execution status),needsUser=true|false, andref. Filters combine with AND; repeat one for OR, as in?stage=review&stage=qa&needsUser=true.- Finished tickets and runs page: pass the response's
nextCursorascursor, withlimitup to 200. - A ticket's
sourceis the issue or brief as fetched when that execution started, so?execution=nshows what generation n was asked. A brief has no tracker author or url;startedBysays who started it. - A run's activity is the agent's latest assistant message in that run, read from its Pi session file.
GET /v1/backloglists open tracker issues that matchtracker.backlog(labels and milestone on GitHub; team, labels, project, and state types on Linear) and are not tickets yet. Each one carries its description, author, and created and updated times, and says whether another issue blocks it and whether it is an umbrella with sub-issues. The list is cached for about a minute;?refresh=trueasks the tracker again. A started issue drops out at once.
GET /v1/events (read) streams Server-Sent Events, one per row of the events table: commands, runtime results, validations, and the status cards the controller posts. Each event is id: <revision>, event: <kind>, and data: {ticket, task, run, actor, card}. Events only name what changed; a client refetches it through the read routes.
- Resume with
Last-Event-ID: <revision>(EventSource sends it on reconnect) or?since=<revision>. Without either, the stream starts with new events. - A comment line every 15 s keeps proxies from closing the connection.
EventPayloadinopenapi.jsontypesdata. OpenAPI 3.1 cannot type a stream's items, so clients parse events themselves.
/v1/stats/summary, /stages, /configurations, /tickets, and /export (read) report how the factory turns tickets into merged pull requests, by stage and model setup, as defined in docs/stats-v1.md. from and to select tickets by start time. Every response names the factory (factoryId, created with the database), the factory versions its tickets ran on, and definitions: "stats.v1". Set name in FACTORY.json to tell factories apart in an export.
Commands need an act token. Each one returns 202 {ticket, revision, message} once it is committed. ticket is the ticket key used in the other URLs: its factory directory's name, such as proj-123-ab12cd34. revision is the events.revision that recorded the command. Agent launches happen afterwards, so a client that wants the result waits for the event stream to pass that revision.
| Route | Pi equivalent |
|---|---|
POST /v1/tickets {ref} or {id, text} |
/factory start |
POST /v1/tickets/{key}/replies {answer} |
/factory reply |
POST /v1/tickets/{key}/retries |
/factory retry |
POST /v1/tickets/{key}/complete |
/factory complete |
POST /v1/tickets/{key}/feedback-rounds {note?, only?, skip?} |
/factory feedback |
GET /v1/tickets/{key}/feedback |
/factory feedback --list |
POST /v1/tickets/{key}/cancel {reason?} |
/factory cancel |
POST /v1/tickets/{key}/reruns |
/factory rerun |
POST /v1/runs/{id}/stop |
/factory stop |
- Problems found before anything changes come back at once:
validation_errorfor a reference that cannot be resolved,umbrella_issue,tracker_unavailable,code_host_unavailable,ticket_not_found,not_waiting_for_reply, orinvalid_state. - Cancel ends a ticket for good: its agents stop, its tab closes, open questions and tasks are cancelled, and the ticket is
done / cancelled. Its worktree, branch, and pull request stay for you to keep or clean up. A ticket from the tracker gets a comment, and its factory status label is removed. - Rerun runs a complete, cancelled, or failed ticket again as generation N+1: it fetches the issue again and works in
<ticket dir>/r<N>on its own worktree and branch (factory/<key>-r<N>), with the models inFACTORY.json. Earlier generations stay readable throughGET /v1/tickets/{key}/executionsand?execution=<n>on the ticket and run routes. - Stop closes a running agent's pane and pauses the ticket. A reply resumes that agent's session with your instructions; a retry relaunches it.
- Send
Idempotency-Key: <key>to make a command safe to repeat: the same key returns the first result instead of applying the command again.
Every /v1 route needs Authorization: Bearer <token>. A token belongs to a named API client and has a scope: read routes only look, act routes change tickets, and act includes read. Tokens are managed only from the command line, so whoever can reach the factory root decides who gets one:
dist/factory token create dashboard --scope act # prints the token once
dist/factory token list
dist/factory token revoke dashboard- The database keeps only each token's SHA-256. A lost token cannot be shown again; revoke it and create it again.
- To rotate without downtime, create a client with a new name, switch the client over, then revoke the old one.
- The server writes a
localact token to.factory/local.token(mode0600) for Pi on the same machine. It replaces the token when the file is missing or the client was revoked. GET /v1/mereturns the client a token belongs to and its scope (readoract), to check a token and know up front whether commands are allowed.GET /v1/factoryreturns the factory'sfactoryId, its FACTORY.jsonname, itscommunicationsettings, the pull request format a ticket started now would follow, and every stage in flow order, with whether it is optional, enabled, and per task. It reads FACTORY.json when asked; a running ticket keeps the settings it started with.versionis the factory version the server runs, such as0.5.0+1ddf4f6. Itsupdateis the update the last check found,{ current, latest, name, notesUrl, later }, ornull.POST /v1/factory/update-check(act) checks GitHub now and answers{ message, update }. A failed check is502 code_host_unavailable.POST /v1/factory/update-later(act) puts off the update on offer until a newer release, and answers with it; with none on offer it is409 invalid_state.POST /v1/factory/rollback(act) rolls back tofactory.previous. A rollback that restores the database answers200with{ kind: "confirm", message }, naming what it loses, until it is sent with{ "confirm": true }; it then answers202withkind: "restarting". With nothing to roll back to, or no backup, it is409 invalid_state.POST /v1/factory/update(act) updates the factory. It answers202with{ kind, message },kindbeingrestarting(installed; a new server is starting) orpending(with{ "whenIdle": true }, until idle), or200withnonewhen it runs the newest release. A source run, or an update already under way, is409 invalid_state; a download or checksum that fails is502 update_failed, with nothing changed. The update'sinstalledsays the binary on disk already has it, andpendingthat it waits to run once idle.PUT /v1/factory/communication(act) takes the wholecommunicationblock (verbosity,voice,tone), checks it by the same rules as the file, and rewrites that block in FACTORY.json, leaving every other key as it was. It answers with the saved block. A value that breaks the rules is400 validation_errorand changes nothing. FACTORY.json stays the only source: editing it by hand works too, and either way the change applies to tickets started after it.- Commands record the client that sent them. A client can add
X-Factory-On-Behalf-Of: <who>, such as a dashboard user's name. The server stores it as given and never uses it for access. - An unknown or revoked token gets
401 unauthorized; areadtoken on anactroute gets403 insufficient_scope. - Keep tokens off browsers: a web client calls the API from its server.
Every status card names the ticket, the stage, and what the run led to, then the task and round:
✓ dpaez/factory-dashboard#11 · review · approved
03/06 Overview page · r1 · 3/6 done
The overview page meets every acceptance criterion.
Outcomes are planned, ready for review, approved, changes requested, blocked, correcting, retrying, diff changed, paused, waiting for you, failed, and finished. The plan card lists every task with its dependencies. Blocking findings show under the card. A card that waits on you (▲) shows its whole message and the command to run next.
Above the editor, the widget keeps each unfinished ticket's progress on screen between runs, followed by the running agents. Between agents, a line under the ticket shows its controller step: what the controller is doing for it, such as preparing the worktree, preparing a stage's input, validating a run, starting an agent, updating the issue or the pull request, or opening the handoff panes, with a spinner and how long it has run. An action waiting its turn shows dimmed as queued:
● dpaez/factory-dashboard#11 · ■■□□□□ 2/6 · review r1
03/06 Overview page
◜ validating task 03's review · 41.0s
While a step runs commands of the controller's own (worktree.setup, work validation, QA's commands, and QA validation), the line also names the command and its position, as in ◜ validating task 02's work · test (2/3) · 41.0s.
Pi reads the steps from the controller's actions in the database, and checks them every second along with the event revision, since starting or finishing an action records no event. The running command is not in the database: the server keeps it in memory, and Pi asks GET /v1/controller-steps for it once a second, only while such a step runs. A server that does not answer leaves the line without its command.
src/extension/ Pi /factory command
src/server/ factory serve: HTTP server and owner lease
src/api/ routes, router, problem errors, OpenAPI document
src/cli.ts the factory executable's entry point
scripts/ single executable build
src/controller/ commands, pure reducer, SQLite persistence
src/actions/ leased dispatcher, worktree preparation
src/runtime/ FactorySubagentRuntime, fake, pi-herdr adapter, Herdr plugin
src/validation/ plan, work, review, and wrap-up checks
src/stories/ component gallery: fixtures, scenarios, server, snapshots
src/state/ schema and database opener
skills/ specialist procedures and output templates
tests/ recovery tests against real SQLite
Child sessions follow the named skill, return only the versioned template in that skill's references/output.md, then call subagent_done. caller_ping replaces the template when a decision is needed. Skills do not write the controller database. Both calls end the child, but each still gets a tool result in the session ("The session is shutting down…") and stops Pi after the turn. The child publishes its .exit sidecar and exits only at the end of that turn, once Pi has saved every tool result and before any further model request, so a session resumed with a reply or a validation correction never replays a tool call without its result, which providers such as Anthropic's refuse.
| Term | Meaning |
|---|---|
| ticket | External work, from GitHub or a local document. |
| execution | One generation of a ticket. |
| stage | plan, work, review, wrapup, or done. |
| session | One Pi conversation, reused when that agent resumes. |
| run | One pane launch. A resume or retry creates a new run. |
| factory root | Untracked .factory/ in the code repository. |
A ticket starts from the tip of its remote's default branch, not from your checkout. Before planning, the controller asks origin (or the only remote) for its default branch, fetches it into refs/remotes/<remote>/<branch>, and adds the worktree on a new factory/<slug> branch at that commit. Plan, work, QA, review, and wrap-up all run in that worktree, so the planner reads the code the workers change, and pull requests merged since your last git pull are included. Your checkout, its branch, and its local main never move.
- A repository without a remote starts from the code root's
HEAD, as before. - With several remotes and none named
origin, the ticket stops and asks you to name oneorigin. - A remote that cannot be reached, or a fetch that fails, stops the ticket before planning with git's error, as a failed worktree step.
/factory retrytries again. Git never prompts: a password or host-key question fails the fetch. .factory/is untracked, so the worktree has none. Plan files still go to.factory/tickets/<slug>/in the code root, and the planner's prompt names the factory root. They stay there after the worktree is removed.- A ticket started before this change keeps planning in the code root and gets its worktree when its plan is accepted.
Each ticket works in its own git worktree, which starts without installed dependencies. worktree.setup lists commands the controller runs once in each new worktree, in order, before its first agent (the planner), so agents, validation, and QA start from a ready tree. Each command takes a name, an argv, and an optional timeoutMs (10 minutes by default).
- Use a command that reuses a cache, so each ticket links dependencies instead of downloading them:
pnpm install --frozen-lockfile --prefer-offline(pnpm's global store makes it mostly hard links),npm ci --prefer-offline,uv sync --frozen,bundle install --local, orcargo fetch --locked. - Each worktree gets its own dependencies, matching its branch's lockfile, so a ticket that changes them cannot affect another ticket or your checkout.
- A command that fails, times out, or cannot start stops the ticket with its output, as a failed worktree step.
/factory retryruns the setup again in the same worktree. - An execution keeps the setup it started with; a change to
FACTORY.jsonapplies to tickets started after it.
What the factory writes where people other than its owner read it (tracker comments, checklist ticks, the pull request, and commit messages) follows the communication block in FACTORY.json. Pi, the API, and the dashboard always show everything. The design is in ADR-004, and the terms are in GLOSSARY.md.
"communication": { "verbosity": "standard", "voice": "developer", "tone": "terse, lowercase, no emoji" }verbosity:minimal(the pull request only, succinct),standard, orfull(the default, everything the factory has always written). Each level writes everything the level below does.voice:factory(the default) speaks of itself in the third person.developerreads as the factory's owner writing in the first person.tone: how thedevelopervoice should sound, in your words; at most 500 characters. It defaults to "succinct, technical, to the point".
Every field can be left out and takes its default. Any other key, or a value outside these, stops the server at startup with a message naming the field. A ticket keeps the settings it started with, including in its feedback rounds. PUT /v1/factory/communication changes them through the API.
The factory reads issues through a tracker and pull requests through a code host, configured in FACTORY.json as tracker and codeHost. Each is an adapter behind a fixed interface. GitHub is both, through the gh CLI; Linear is a tracker, through its SDK (see Linear), with GitHub as the code host. An operation an adapter cannot do fails with "not supported", and asking for one in FACTORY.json stops the server at startup. The old github and keys blocks are refused with a message saying what replaced them.
-
trackerresolves issue refs: on GitHub an issue URL,owner/repo#n, or#nfor the configured repository; on Linear an issue key such asENG-42or its URL. Local markdown or JSON files and--texttickets bypass it. -
Parent and blocking links must be native. The factory reads GitHub's sub-issues and "blocked by" links, not
## Parentor## Blocked byheadings in an issue body. An issue with sub-issues is an umbrella: start each sub-issue instead. -
Tracker updates. For a ticket that came from the tracker, the factory comments on its issue when it starts, when it pauses for a person (with the question and how to answer), and at handoff (with the pull request link).
tracker.statusmapsin_progressandin_reviewto labels, such as{ "in_progress": { "label": "factory:in-progress" } }; create the labels in the repository first. An unmapped status is not written. Updates go through the outbox and retry; each comment carries a hidden marker, so a retry never posts twice. A tracker that keeps failing leaves a warning in the ticket'strackerWarningsand never pauses or fails the ticket. Atracker.statusthe tracker cannot write stops the server at startup. -
How much it says. The ticket's communication settings decide which comments and ticks go out. Statuses and the pause comment, which asks a person a question, go out at every level:
minimalstandardfull(default)Started, feedback-round started, and cancelled comments no no yes Handoff comment no the pull request link and the items left open adds the decisions and any project rule changes Checklist ticks no yes yes In the
factoryvoice the comments say "The factory …". In thedevelopervoice they read as the factory's owner, with no factory branding: the pause comment is just the question, with no/factory replyhint. Hidden markers stay in both voices. Tone does not change these comments; they are fixed wording. -
Turning updates off.
tracker.updatesturns off comments ("comments": false) or checklist ticks ("checklist": false); both are on by default. A switch only turns a channel off: it never adds one the ticket's verbosity leaves out, and with comments off no pause comment goes out either. With ticks off, the handoff comment lists the met items instead. Status changes need no switch, because only mapped statuses are written. The factory never creates labels or statuses in the tracker; it only uses the ones that already exist. -
Switching trackers. A ticket keeps the tracker it came from. If
tracker.kindchanges while it is open, its tracker updates are skipped with a warning, and rerunning it is refused (invalid_state), because its issue can no longer be fetched. -
codeHost.pullRequestsis on unless it isfalse. When it is on, wrap-up commits the approved work, pushes the branch, and opens or updates the pull request. -
The project's PR format. At the ticket's base commit, the factory looks for the format the project asks pull requests to take, in this order: a section of the repository root's agent instructions (the first of
AGENTS.override.md,AGENTS.md,CLAUDE.mdit has) whose heading names pull requests or PRs; a singlepull_request_template.md, in any letter case, in.github/, the root, ordocs/(aPULL_REQUEST_TEMPLATE/directory is ignored, as GitHub only uses one when a link asks for it). Either way, wrap-up's prompt carries it, and the agent writes the whole body in it at every verbosity, with no other section and no attribution. Files are read as Pi reads them, following symlinks, so anAGENTS.mdlinked toCLAUDE.mdcounts. The first wrap-up's validation checks that the pull request's body has every template heading, in order (a<!-- -->hint on a heading's line is not part of it), and names the missing ones; prose instructions cannot be checked, and a feedback round, which leaves the body alone, is not checked. The factory then leaves the body alone. A format the ticket itself adds or changes does not apply to its own pull request. To see which format applies,GET /v1/factoryreturnspullRequestFormat:{ "source": "agents" | "github" | "default", "path": … }, read at the remote's default branch as last fetched, without fetching; and each ticket's handoff message in Pi says which one its pull request followed, such asPull request format: github (.github/pull_request_template.md).. -
The pull request body. With no project format, wrap-up opens the pull request with its
## PR summary. Once the factory accepts the handoff, it replaces the body with one it builds from the handoff's sections, by the ticket's verbosity:minimal/standardfull(default)Sections ## Summary,## Tests## Summary,## Files,## Tests,## Decisions,## Limitations,## ScreenshotsA section that says
noneis left out. In thefactoryvoice the body ends with "Opened by the factory for ."; thedevelopervoice has no attribution anywhere, and the ticket's tone shapes the summary, the decisions, and the commit summary the agent writes. The body is set once, through the outbox with retries; a feedback round leaves it as it is. A code host that keeps refusing leaves a warning in the ticket'strackerWarnings, and the ticket stays ready for handoff. Commit messages keep their format in both voices. -
codeHost.pullRequestTitlesets the pull request's title, such as"{ref} | {summary}", for a team whose CI, changelog, or bot reads its own format.{ref}is the ticket as its tracker names it (#42, orowner/repo#42for an issue of another repository thancodeHost's;ENG-42on Linear) and{summary}is wrap-up's one-line summary. A local ticket has no ref, so{ref}and the separator next to it are dropped:{ref} | {summary}becomes just the summary. Unset, the title is the summary for a GitHub ticket and{ref}: {summary}for any other tracker. The template must contain{summary}once and no other braces, or the config is refused; it is trimmed, because GitHub trims titles. The controller fills in the ref and passes the title to wrap-up, and a pull request with another title is a wrap-up correction, so a correction or rerun keeps the configured title. -
When wrap-up validation passes, the pull request it checked becomes the ticket's. A ticket with none recorded, such as one you opened by hand, is found later by its branch.
-
The server checks the pull request of every ticket in handoff at startup and then every
codeHost.syncMinutes(10 by default), and stores its reviews and commits. A merged pull request completes the ticket, recorded as done bycode-host; one closed without merging cancels it with reasonpull_request_closed./factory completestill works by hand. -
Webhooks make that faster. Set
codeHost.webhookSecretEnvto the name of an environment variable holding the secret, then point a GitHub webhook for Pull requests and Pull request reviews atPOST /v1/webhooks/githubwith that secret. A delivery needs no token; itsX-Hub-Signature-256must match, or it gets401. Deliveries about pull requests no ticket has are accepted and ignored. The periodic sync stays on as a backstop, because GitHub does not retry a failed delivery.
The factory fits an existing Linear workspace: it uses the teams, labels, projects, and workflow states that are already there, and never creates any.
-
Create a personal API key in Linear (Settings → Security & access) and put it in
LINEAR_API_KEY, or in the variabletracker.apiKeyEnvnames. -
Run
factory tracker inspect(--jsonfor JSON). It lists the teams the key can see, each team's workflow states (name and type, in workflow order) and labels, the workspace's labels, and its projects. It works before the tracker is configured. The server serves the same list atGET /v1/tracker/inventory(read). -
Write the tracker settings from those names:
"tracker": { "kind": "linear", "team": "ENG", "backlog": { "labels": ["factory"], "project": "Catalog", "states": ["backlog", "unstarted"] }, "status": { "in_progress": { "state": "In Progress" }, "in_review": { "state": "In Review" } } }
teamis a team key and sets the backlog.backlog.statestakes workflow state types (triage,backlog,unstarted,started,completed,canceled), so it fits any team's workflow, and defaults tobacklogandunstarted. An issue must carry every listed label.statusmaps to workflow state names.apiKeyEnvdefaults toLINEAR_API_KEY.
The server refuses to start without the key, or when a team, label, project, or state it names does not exist; the message lists the names that do. When Linear cannot be reached at startup, the server warns and starts anyway: local tickets and runs under way do not need it.
- Refs. Start an issue by its key (
ENG-42, any case) or its URL. A bare number is refused with the key to use instead. An issue of another team can be started too. - Statuses only move forward. A status moves the issue to the mapped state of its own team only when that state comes later in the workflow, and never moves a completed or cancelled issue: people and Linear's own automation move issues too. Cancelling a ticket leaves the state as it is; the cancel comment says the factory stopped. When the issue's team has no state of the mapped name, the status is skipped with a warning on the ticket.
- Comments. Each factory comment's id is derived from the issue and the comment's purpose, so a retry finds it instead of posting twice, with no hidden marker in the text. After a person deletes one, the next post makes it again with the same id.
- Checklist. The issue checklist is the Markdown boxes in the description. Sub-issues make an issue an umbrella, as on GitHub; blockers are
blocksrelations whose issue is not finished. - Linked issues. The plan reads the parent, sub-issues,
blocks,relatedandduplicaterelations both ways (Linear'ssimilarreads as related), GitHub pull requests attached to each, up to 50 comments counted, and keys or Linear URLs in the description. A key Linear does not know, such asUTF-8, is dropped. - Pull requests. The ticket branch (
factory/eng-42-…) and the pull request title (ENG-42: …) carry the issue key, so Linear's GitHub integration links the pull request. The factory adds no closing keyword. By default that integration also moves a linked issue to In Progress when a pull request opens and to Done when it merges; mapin_reviewonly if your team's automation does not already cover it. - Unexpected responses. Each Linear response is checked against the shape the factory expects as it arrives. One that does not match, as after a Linear API change, fails with the query and the field, such as
Linear returned an unexpected FactoryBacklog response: issues.nodes[3].identifier: …, and is handled like any other Linear failure. - Checking against a real workspace.
tests/linear-smoke.test.tsruns against Linear whenLINEAR_API_KEYandLINEAR_SMOKE_TEAM(a scratch team's key) are set, in the environment or in a.envfile at the repository root, which git ignores. With that file in place,npm testruns it too. It creates one throwaway issue, checks that description boxes, derived comment ids (including after a deletion), workflow states, and the factory's branch names behave as the adapter expects, then deletes it. CI skips it.tests/linear-smoke-links.test.tsonly reads: withLINEAR_API_KEYandLINEAR_SMOKE_LINKS_ISSUE(an issue key with links), it checks the plan's linked issues against what the Linear SDK reports for that issue, and prints theLinked issuessection the planner would get.
.code-repository/
└── .factory/
├── FACTORY.json
├── CONTEXT.md
├── db/state.sqlite
├── tickets/<slug>/
├── worktrees/<slug>/
├── validation-logs/
└── sessions/
validation-logs/ is where project validators keep their run artifacts: logs, and pointers to the latest one, such as <ticket>.latest. Tickets run in parallel under one factory root, so one ticket's validation may write there while another ticket wraps up. Wrap-up never compares it, only validation-logs/ at the factory root itself: a log anywhere else under .factory/, a ticket's own directory included, is still a change wrap-up must not make. Every validation command (work's, QA's, and QA's run of the work commands) gets the directory's absolute path as FACTORY_VALIDATION_LOGS, and the factory makes the directory before the commands run, private to its owner (0700; one that is already there keeps its mode), so a validator writes there without knowing where the factory root is. The factory writes no files there and never cleans it.
FACTORY.json example:
{
"name": "factory-skills on Sonnet",
"models": { "work": "work-model", "review": "review-model" },
"tracker": {
"kind": "github",
"owner": "geut",
"repo": "factory-skills",
"backlog": { "labels": ["factory"] }
},
"codeHost": { "kind": "github", "owner": "geut", "repo": "factory-skills", "pullRequests": true },
"communication": { "verbosity": "full", "voice": "factory" },
"server": { "host": "127.0.0.1", "port": 7731 },
"limits": { "workCorrections": 3, "reviewRounds": 3, "reviewCorrections": 3 },
"stages": {
"qa": {
"enabled": true,
"commands": [{ "name": "e2e", "argv": ["npx", "playwright", "test"] }]
}
},
"worktree": {
"setup": [
{ "name": "install", "argv": ["pnpm", "install", "--frozen-lockfile", "--prefer-offline"] }
]
},
"validation": {
"work": { "commands": [{ "name": "tests", "argv": ["npm", "test"], "timeoutMs": 300000 }] },
"qa": { "commands": [{ "name": "lint", "argv": ["npm", "run", "lint"] }] },
"wrapup": { "generated": ["docs/api/", "*.snap"] }
}
}The API is the contract for clients outside this package. Only the server and Pi read SQLite; its views, such as current_ticket_executions, ready_task_frontier, and open_attention, are documented in src/state/README.md as internal. The controller does not emit a JSON state file.
node --test
npx oxlint .
npx tsc --noEmitNode.js 24 runs the TypeScript tests directly.
Each TUI component (Status Message, Widget, Ticket View, Agents View) has scenarios next to it in src/extension/*.stories.ts. A scenario is one state of the component, rendered without Pi from plain JSON state. The scenarios cover a ticket's life, from the plan card through review rounds, pauses, questions, retries, and wrap-up.
npm run gallery # live gallery at http://127.0.0.1:5180/
npm run gallery -- --port 5200 --host 0.0.0.0The sidebar lists the components. /component/<id> shows that component's scenarios, each in its own card with a description, rendered with Pi's own theme at the widths you pick (40, 60, 80, 120). The theme selector at the top applies to every page. Edit state opens a scenario's state as JSON; the render updates as you type, the edit is kept in the browser, and Reset restores it. The server runs under node --watch, so a code change restarts it and the open page reloads.
The same scenarios print in the terminal:
npm run stories # every scenario at 40, 60, 80, 120 columns, Pi's dark theme
npm run stories -- --story widget --width 60 # filter by component or scenario name
npm run stories -- --theme light --plain # light theme, or no colournode --test renders every story at every width, fails if a line is wider than its width, and compares the text with src/stories/snapshots/. After an intended UI change, run npm run stories:update and review the snapshot diff.