Skip to content

About

A small set of skills for running a budget-aware factory

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Factory Skills

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.

Commands

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.

  • approve marks the task done and starts the next dependency-ready task. After the last task, the controller launches wrap-up.
  • changes_requested resumes 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 and reply resumes the reviewer with your decision.
  • blocked pauses the ticket. reply resumes 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 retry validates 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 and reply resumes the QA agent;
  • after the QA commands, the controller runs every validation.work.commands again, then any validation.qa.commands work 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 checklist has one line per open checklist item of the ticket's issue, B1..Bn: met cites 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_met gives a reason. ## Decisions is none or bullet points;
  • every heading is present; ## Files lists every changed path and no other; ## Tests names the validation.work.commands; ## Merge commands holds 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, and learnings/ may change; no wrapup.md or visuals/. Other tickets' directories, the controller's own files (db/, runtime/, local.token, …), and validators' artifacts in validation-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.pullRequests off, nothing was committed or pushed, and ## Merge commands prints 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 ## Files lists. 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 title codeHost.pullRequestTitle gives. 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.

Feedback rounds

/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 graphql call: 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 in codeHost.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: r2841017733 for a review thread, p… for a review, c… for a conversation comment. /factory feedback <ticket> --list (or GET /v1/tickets/{key}/feedback) lists them, with what was skipped, and changes nothing. In Pi's terminal, --list opens a picker instead: every pending comment ticked in a scrolling list, the selected one in full with its link below; space ticks, a ticks all or none, enter starts the round on the ticked ones (as --only unless all are ticked, with the command's note), and q closes without starting anything. A round takes every pending comment by default; --only r2841017733,c6799058255 takes just those and leaves the rest pending; --skip r2841017733 takes 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 at tickets/<slug>/feedback/<n>/task.md. Its acceptance criteria are the items F1..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 changed or - 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, verified with the lines that address it or not_verified with why it is left as is. It uses the worker's ## Feedback responses when 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, addressed or left as is: <reason>, from review's Verification line for it. At full verbosity 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 the developer voice, "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's trackerWarnings, 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 reads F1 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 runs F1. Through the API, the round's task carries feedback: { round, pullRequestUrl, items: [{ id, kind, author, location, summary, url }], skipped }, with each item's first line (160 characters at most) and its link; it is null on 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 own handoff:<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 as node_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 retry may 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.

Factory server

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 serve

On 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 serve

npm 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 to extensions/factory/index.js in 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_ID and HERDR_SOCKET_PATH, plus herdr (0.8.2 or newer) and pi on PATH; FACTORY_PI_BIN overrides the path to pi.
  • 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 runs herdr plugin link on 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 its BASH_ENV when 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 start factory serve from a shell where the project's toolchain (pnpm, bun, ...) is on PATH.
  • Each agent's launch script also exports FACTORY_WORKTREE, its worktree, and FACTORY_RUN_ID, which every process it starts inherits. Handoff panes export FACTORY_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 a stray_process_stopped or stray_process_stop_failed event 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.host and server.port from FACTORY.json, 127.0.0.1:7731 by default. Bind 0.0.0.0 to 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 gh call 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 other gh error: a tracker update or pull request write retries, a pull request sync tries again next time, and a feedback command is refused with code_host_unavailable. FACTORY_GH_BIN names another gh binary.
  • 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, replace state.sqlite with the copy, and delete state.sqlite-wal and state.sqlite-shm. Anything recorded after the upgrade is lost.

Updates

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
  1. The server downloads this machine's binary (factory-linux-<arch>) and its .sha256 from the release with gh, and checks one against the other. A mismatch, or a failed download, stops with nothing changed.
  2. It copies the running binary to factory.previous beside it, then renames the new one into place.
  3. 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 mode 0700 and 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 idle meanwhile. An update that fails then is not retried.
  • On the command line, factory update hands off to the server running for the repository. With none running, it replaces the binary itself, and the next factory serve runs the new version. factory --version prints the version a binary is.
  • Factories sharing a binary. Every factory on a machine that runs the same factory file shares its updates. A server looks at its binary on disk every 10 seconds and asks it --version when the file changed; when it holds a newer version than the server runs, Pi posts ⬆ factory 0.6.0 is installed · restart to use it and the footer shows · restart. /factory update there only restarts.
  • Running from source (node src/cli.ts serve), updating says to use git pull and does nothing else.
  • Rolling back (/factory update --rollback, factory update --rollback, or POST /v1/factory/rollback) goes back to the version the last update replaced. An update writes factory.previous.json beside factory.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 know serve --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, --yes elsewhere, { "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.

API

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. /health and /openapi.json sit outside it.
  • Errors are RFC 9457 application/problem+json with a stable type code, listed in src/api/problem.ts. A validation_error lists each bad field, such as body.ref or query.stage.
  • Source runs and tests also check every response against its schema; the single executable does not.
  • A test fails when openapi.json no longer matches the routes. After changing a route, run npm run openapi:update and commit the document.

Reads

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/tickets filters by status=open|finished|all (default open), stage, state (the execution status), needsUser=true|false, and ref. 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 nextCursor as cursor, with limit up to 200.
  • A ticket's source is the issue or brief as fetched when that execution started, so ?execution=n shows what generation n was asked. A brief has no tracker author or url; startedBy says 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/backlog lists open tracker issues that match tracker.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=true asks the tracker again. A started issue drops out at once.

Events

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.
  • EventPayload in openapi.json types data. OpenAPI 3.1 cannot type a stream's items, so clients parse events themselves.

Stats

/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

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_error for a reference that cannot be resolved, umbrella_issue, tracker_unavailable, code_host_unavailable, ticket_not_found, not_waiting_for_reply, or invalid_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 in FACTORY.json. Earlier generations stay readable through GET /v1/tickets/{key}/executions and ?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.

Tokens

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 local act token to .factory/local.token (mode 0600) for Pi on the same machine. It replaces the token when the file is missing or the client was revoked.
  • GET /v1/me returns the client a token belongs to and its scope (read or act), to check a token and know up front whether commands are allowed.
  • GET /v1/factory returns the factory's factoryId, its FACTORY.json name, its communication settings, 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. version is the factory version the server runs, such as 0.5.0+1ddf4f6. Its update is the update the last check found, { current, latest, name, notesUrl, later }, or null.
  • POST /v1/factory/update-check (act) checks GitHub now and answers { message, update }. A failed check is 502 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 is 409 invalid_state.
  • POST /v1/factory/rollback (act) rolls back to factory.previous. A rollback that restores the database answers 200 with { kind: "confirm", message }, naming what it loses, until it is sent with { "confirm": true }; it then answers 202 with kind: "restarting". With nothing to roll back to, or no backup, it is 409 invalid_state.
  • POST /v1/factory/update (act) updates the factory. It answers 202 with { kind, message }, kind being restarting (installed; a new server is starting) or pending (with { "whenIdle": true }, until idle), or 200 with none when it runs the newest release. A source run, or an update already under way, is 409 invalid_state; a download or checksum that fails is 502 update_failed, with nothing changed. The update's installed says the binary on disk already has it, and pending that it waits to run once idle.
  • PUT /v1/factory/communication (act) takes the whole communication block (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 is 400 validation_error and 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; a read token on an act route gets 403 insufficient_scope.
  • Keep tokens off browsers: a web client calls the API from its server.

What you see

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.

Layout

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.

Vocabulary

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.

Worktree base

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 one origin.
  • 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 retry tries 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.

Worktree setup

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, or cargo 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 retry runs the setup again in the same worktree.
  • An execution keeps the setup it started with; a change to FACTORY.json applies to tickets started after it.

Communication

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, or full (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. developer reads as the factory's owner writing in the first person.
  • tone: how the developer voice 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.

Tracker and code host

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.

  • tracker resolves issue refs: on GitHub an issue URL, owner/repo#n, or #n for the configured repository; on Linear an issue key such as ENG-42 or its URL. Local markdown or JSON files and --text tickets bypass it.

  • Parent and blocking links must be native. The factory reads GitHub's sub-issues and "blocked by" links, not ## Parent or ## Blocked by headings 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.status maps in_progress and in_review to 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's trackerWarnings and never pauses or fails the ticket. A tracker.status the 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:

    minimal standard full (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 factory voice the comments say "The factory …". In the developer voice they read as the factory's owner, with no factory branding: the pause comment is just the question, with no /factory reply hint. Hidden markers stay in both voices. Tone does not change these comments; they are fixed wording.

  • Turning updates off. tracker.updates turns 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.kind changes 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.pullRequests is on unless it is false. 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.md it has) whose heading names pull requests or PRs; a single pull_request_template.md, in any letter case, in .github/, the root, or docs/ (a PULL_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 an AGENTS.md linked to CLAUDE.md counts. 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/factory returns pullRequestFormat: { "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 as Pull 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 / standard full (default)
    Sections ## Summary, ## Tests ## Summary, ## Files, ## Tests, ## Decisions, ## Limitations, ## Screenshots

    A section that says none is left out. In the factory voice the body ends with "Opened by the factory for ."; the developer voice 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's trackerWarnings, and the ticket stays ready for handoff. Commit messages keep their format in both voices.

  • codeHost.pullRequestTitle sets 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, or owner/repo#42 for an issue of another repository than codeHost's; ENG-42 on 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 by code-host; one closed without merging cancels it with reason pull_request_closed. /factory complete still works by hand.

  • Webhooks make that faster. Set codeHost.webhookSecretEnv to the name of an environment variable holding the secret, then point a GitHub webhook for Pull requests and Pull request reviews at POST /v1/webhooks/github with that secret. A delivery needs no token; its X-Hub-Signature-256 must match, or it gets 401. 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.

Linear

The factory fits an existing Linear workspace: it uses the teams, labels, projects, and workflow states that are already there, and never creates any.

  1. Create a personal API key in Linear (Settings → Security & access) and put it in LINEAR_API_KEY, or in the variable tracker.apiKeyEnv names.

  2. Run factory tracker inspect (--json for 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 at GET /v1/tracker/inventory (read).

  3. 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" } }
    }

    team is a team key and sets the backlog. backlog.states takes workflow state types (triage, backlog, unstarted, started, completed, canceled), so it fits any team's workflow, and defaults to backlog and unstarted. An issue must carry every listed label. status maps to workflow state names. apiKeyEnv defaults to LINEAR_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 blocks relations whose issue is not finished.
  • Linked issues. The plan reads the parent, sub-issues, blocks, related and duplicate relations both ways (Linear's similar reads 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 as UTF-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; map in_review only 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.ts runs against Linear when LINEAR_API_KEY and LINEAR_SMOKE_TEAM (a scratch team's key) are set, in the environment or in a .env file at the repository root, which git ignores. With that file in place, npm test runs 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.ts only reads: with LINEAR_API_KEY and LINEAR_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 the Linked issues section the planner would get.

Factory root

.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.

Checks

node --test
npx oxlint .
npx tsc --noEmit

Node.js 24 runs the TypeScript tests directly.

Component gallery

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.0

The 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 colour

node --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.

About

A small set of skills for running a budget-aware factory

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages