software-factory

作者: mattpocock

Shared language for designing a software factory: the tasks it runs and the services it plugs into.

npx skills add https://github.com/mattpocock/skills --skill software-factory

A software factory is a system of agents that turns tickets, PRs and schedules into merged code, deployed on remote infrastructure the user chooses. This skill is the language for designing one. Use these terms, and only these, when discussing or whiteboarding a factory; when the user reaches for a word under Avoid, name the canonical term.

Tasks and runs

Task: A kind of work the factory performs, defined once and run many times: review, explore, implement, ratchet. A task may work on a ticket, a PR, or the codebase as a whole. Avoid: job, workflow, action, as names for the task. A CI vendor's workflow file and its jobs are where a task is wired up, not the task.

Trigger: The event that starts a run: a change in the ticket tracker or git host, a clock in the orchestrator, or another run.

Run: One execution of a task on one runner, from its trigger to its finish, treated as a black box. A run triggers further runs either directly, through logic in the orchestrator, or by changing the ticket tracker or git host. A run never waits for a human: it ends, and the human's later change to the ticket tracker or git host triggers a new run. Avoid: session

Runner: The disposable machine a run executes on. Nothing on it survives the run, even when the machine itself is long-lived: a run's only memory of earlier runs is the ticket tracker, the git host and the orchestrator. Avoid: server, host, box, compute, sandbox

Services

Ticket tracker: Where tickets live, and the factory's human interface: humans schedule work by filing tickets, talk to agents in their comments, and their changes to tickets trigger runs. Avoid: issue tracker, ticket manager, project board

Ticket source: Anything outside the factory that creates tickets in the ticket tracker: a feedback button, a monitor, an error tracker, an inbox. Avoid: data source, trigger source, intake

Git host: Where branches, PRs and reviews live. Avoid: code host, forge, repo

Orchestrator: The component that receives triggers, starts runs on runners, and records which runs are queued, in flight or finished. Avoid: dispatcher, scheduler, control plane

Observability platform: Where runners send logs, traces and status, so a human can see what happened inside each run. Optional: the product filling the runner or orchestrator slot often shows enough on its own. A run never decides on it until something writes it into the ticket tracker or git host. Avoid: observability, logs, monitoring, dashboard

Designing a factory

A design has two halves: the services, each a slot filled with a product, and the tasks whose runs move work through them.

Start from the user's problem, not the factory: untriaged tickets, PRs waiting for automated review, a stricter automated check to migrate to, bugs nobody reads. When the user names a problem or doesn't know what to build, read EXAMPLE-TASKS.md for the tasks that solve common ones.

Start slow

Every trigger is an accelerator. Accelerators without brakes make a slop cannon. There are three brakes:

  • Automated checks: deterministic gates (types, lint, tests) that every run must pass.
  • Automated review: a separate run that reads the diff cold against the codebase's standards and the ticket, when there is one.
  • Human review: a human reads the PR before it merges; what it catches becomes new automated checks and sharper automated review.

Add one automated trigger at a time, throttled at first (one bug report in ten, a clock once a day), with human review on every PR. Open the throttle as the brakes earn trust, and cap every loop of runs at a few tries before a human.

Fill every slot

Each service is a slot. One product can fill several slots, and one server can host several services. Three designs, side by side:

ServiceAll on GitHubLinear ticketsOwn tracker
Ticket trackerGitHub IssuesLinearown app
Ticket sourcefeedback buttonfeedback button, monitorfeedback button, monitor
Git hostGitHubGitHubGitHub
OrchestratorGitHub Actionsown server + databaseown app
RunnerActions runnerActions, E2B, Daytona or a VPSown app, or sandboxes
Observability platformnone: Actions run pages sufficean LLM tracing platformown app

When the user is choosing a product for a slot, read that slot's survey to get oriented, then research the current options yourself; each survey groups the options by type and lists the questions that decide the slot:

Buy the services and build the tasks: the tasks carry the user's design, the services are generic. Favour an off-the-shelf ticket tracker: it is robust, people already know it, and outside users are easy to let in.

Question every task

For each task, answer:

  1. What triggers it?
  2. What does it do, and which services does it read and write?
  3. What does it trigger next?
  4. Where does a human re-enter?
  5. What stops two runs doing the same work?

For each ticket source, answer: what stops it filing the same ticket twice?

A design is finished when every slot names a product (or, for the observability platform, a deliberate none) and every task and ticket source has an answer to every question.

來自 mattpocock 的更多技能

ask-matt
mattpocock
詢問哪個技能或流程適合你的情況。此儲存庫中使用者呼叫技能的導航器。
communicationresearchproductivity
chief-of-staff
mattpocock
Pursue a long-running goal in a single session by co-ordinating subagents.
productivityproject-managementcommunication
claude-handoff
mattpocock
將當前對話移交給一個全新的背景代理,該代理會立即接手處理工作。
codebase-design
mattpocock
設計深度模組的共享詞彙。當使用者想要設計或改善模組介面、尋找深化機會、決定接縫位置、讓程式碼更易於測試或AI導航,或其他技能需要深度模組詞彙時使用。
designdevelopmentcode-review
code-review
mattpocock
從固定點(提交、分支、標籤或合併基礎)開始,沿兩個軸審查變更——標準(程式碼是否遵循此儲存庫記錄的編碼標準?)與規格(程式碼是否符合原始問題/PRD 的要求?)。透過平行子代理執行兩項審查,並並排報告結果。當使用者想要審查分支、PR、進行中的變更,或要求「從 X 開始審查」時使用。
testingdevelopmentcode-review
design-an-interface
mattpocock
使用平行子代理為一個模組生成多個截然不同的介面設計。適用於使用者想要設計API、探索介面選項、比較模組形狀,或提到「設計兩次」的情況。
developmentdesignapi
diagnosing-bugs
mattpocock
針對難以解決的錯誤與效能回歸的診斷循環。當使用者說「診斷/除錯這個」,或回報某個東西損壞、拋出錯誤、失敗、緩慢時使用。
testingdevelopmentcode-review
domain-modeling
mattpocock
建立並精煉專案的領域模型。當使用者想要確定領域術語或通用語言、記錄架構決策,或其他技能需要維護領域模型時使用。
designdevelopmentdocument