Factory: a reference software factory

A software factory is a repeatable loop around software delivery. Instead of opening a new agent session for every issue and steering it by hand, you define what work may be attempted, how work starts, what evidence must be produced, and where a human must make the decision.

This repository installs that operating model into an existing GitHub project using stock Claude Code. A thin Codex adapter uses the same policy, queue, gates, and evidence files. There is no custom orchestrator or queue service to run.

In practical terms: GitHub Issues become a work queue. Scheduled agents triage the queue, implement bounded tasks, run your real tests, obtain an independent review, and open draft pull requests. Humans remain responsible for ambiguous requirements, system design, load-bearing changes, and every merge.

What this gives you

Once configured, the factory can:

• inspect new GitHub issues and route each one to implementation, specification, a named question, or a known blocker

• pick up small work that your charter explicitly allows, claim it without racing another run, implement it on a branch, and open a draft pull request

• run deterministic type, lint, test, build, audit, and architecture checks, failing closed when a required check is missing

• ask a fresh verifier to read the diff cold and prove that the new test fails without the implementation

• verify pull requests when they open, keep a visible review queue, and stop producing when that queue reaches your limit

• monitor the default branch and factory health, then feed findings back into GitHub as new issues

The value begins after code generation. This is a version-controlled method for deciding what an agent may pick up unattended, how independent runs hand work to one another, and what proof a human receives before making the final call.

The mental model

There is no background factory process in this repository. The repository supplies the rules and procedures. Claude Code cloud routines provide the default clock and compute. GitHub carries the durable queue and pull requests. Each run starts fresh, handles one stage, records evidence, and stops.

Factory concept Concrete mechanism

Intent and risk budget A human-owned docs/factory/CHARTER.md

Work queue GitHub Issues with factory:* labels

Handoff between stages A structured factory-handoff:v1 issue comment

Standard operating procedures Version-controlled Claude and Codex skills

Clock and triggers Claude routines, schedules, GitHub events, or the optional API-trigger Action

Worker A fresh Claude Code or Codex session

Quality control Your test commands, gates.sh, and an independent verifier

Control room /factory, backed by live issues, PRs, and run records

Release authority A human reviewing and merging the pull request

Each loop is short and restartable. Broad goals are decomposed into queue items that one run can claim and finish. GitHub labels and committed files survive when sessions end, making a failed run inspectable and allowing the next run, or a different harness, to continue without relying on conversation history.

How an issue becomes a reviewed pull request

flowchart LR
    I["GitHub issue"] --> T["Scheduled triage"]
    T -->|"small and allowed"| R["ready-to-implement"]
    T -->|"needs decisions"| S["ready-to-spec"]
    T -->|"blocked or unclear"| P["needs-info / wait"]
    S --> H["Human-guided spec"]
    H --> R
    R --> B["Implementation run"]
    B --> G["Gates + fresh verifier"]
    G --> D["Draft pull request"]
    D --> V["PR verification"]
    V --> C["/factory control room"]
    C --> M{"Human decision"}
    M -->|"merge"| X["Ship"]
    M -->|"revise or close"| D
    X --> W["Weekly monitor"]
    W --> I

For example, suppose issue #142 reports that expired tokens return 500 instead of 401:

• The scheduled triage routine reads the issue, checks the charter, and decides whether it is small and permitted. It applies one queue label and writes a handoff containing the expected files, completion condition, gate level, and confidence.

• If the issue is factory:ready-to-implement, a later implementation run claims the deterministic branch claude/fq-142. Only the first push wins, so two scheduled sessions cannot both own the issue.

• The implementation run writes a failing test, makes the scoped change, runs the required gates, and delegates to a fresh verifier. It opens a draft PR only if those checks agree.

• Opening the PR can trigger a separate verification routine. That routine reruns the gates, checks scope, and leaves a verdict on the PR.

• /factory shows the PR in the human review queue. A person reads the evidence and decides whether to request changes, close it, or merge it. No routine merges.

If triage cannot infer product intent, the issue goes to factory:ready-to-spec and the spec workflow pauses at four explicit human approval gates. If it needs a missing fact, the issue is parked with the question rather than converted into speculative code.

Where the human stays in the loop

The factory automates repeated mechanical steering while keeping engineering judgment with a person. That person still:

• writes the charter that defines risk, scope, protected paths, and the review-queue limit

• approves product intent, observable behavior, technical design, and implementation slices for work that needs a spec

• reads changes to load-bearing code and any change to an existing test

• decides whether every pull request should merge

• accepts or rejects proposed changes to the factory's own constraints

Agents may classify issues, move queue labels, implement permitted work, run checks, and open draft PRs. They may not quietly widen their scope, rewrite the charter, approve their own work, or merge. GitHub branch protection is the final enforcement boundary.

How work starts from GitHub

One current product limit matters to the first arrow in the diagram: Claude routines have native GitHub triggers for pull requests and releases, but not for newly created issues. This reference uses an hourly scheduled triage routine to poll for untriaged issues. That is the simplest reliable default and means an issue may wait until the next run.

If you need immediate triage, install the optional GitHub Action. It reacts to the issue event and calls the triage routine's API endpoint. Pull-request verification can use the native pull_request.opened trigger. LIMITS.md documents the trigger boundary and the tradeoff in detail.

Where Claude Code and Codex fit

The factory method is shared; the unattended automation is Claude-first in this reference.

Capability Claude Code Codex

Project policy CLAUDE.md plus the shared charter and contract AGENTS.md plus the same charter and contract

Repeatable stages Canonical skills under .claude/skills/ Thin adapters under .agents/skills/

Interactive triage, spec, implementation, and status Yes Yes

Deterministic gates and GitHub queue Shared Shared

Unattended schedule supplied by this repository Five prompts for Claude cloud routines Not provisioned automatically

Native GitHub trigger used here Pull-request verification Not packaged by this reference

Codex can run the same stages interactively, or you can map them to Codex goals and automation surfaces available to you. The repository does not create those schedules or claim that their lifecycle matches Claude routines. Whichever harness starts a run, GitHub labels remain the queue and the shared contract remains the policy.

Codex reads AGENTS.md, discovers repository skills, and can load the committed repository hook. The adapters point back to the canonical Claude workflows rather than maintaining a second implementation.

Start here

This repository is an installer for another project. Clone it, run install.sh against the repository you want to automate, then open that target repository in your coding agent.

• Deciding how much machinery you need? Read ADVICE.md for a pragmatic guide to starting with stock Claude Code or Codex, budgeting verification, and knowing when this Factory reference earns its additional structure.

• Want to see the full loop first? Explore the Reel Good demo, then follow its step-by-step workshop to apply Factory to a small TMDB movie app with Claude Code Desktop or Codex.

• Starting from a desktop app? Follow GETTING_STARTED.md. It has separate Claude Code Desktop and Codex/ChatGPT Desktop walkthroughs, including the first prompts to paste and the checks to run before enabling writes.

• Ready for Claude cloud sessions and routines? Follow QUICKSTART.md after the local desktop dry run is predictable.

• Evaluating the design first? Read ARCHITECTURE.md and the honest product constraints in LIMITS.md.

factory/
├── README.md            <- you are here
├── ADVICE.md            when the harness is enough, and when Factory helps
├── GETTING_STARTED.md   desktop-first local setup
├── QUICKSTART.md        Claude cloud sessions and routines
├── ARCHITECTURE.md      why it is shaped this way
├── ROUTINES.md          the five routine prompts, copy verbatim
├── LIMITS.md            honest constraints + corrections to the common plan
├── CONTRIBUTING.md      change map and validation expectations
├── CLAUDE.md            Claude Code contributo