Software Factory

Understand the roles, records, and loops behind development, maintenance, and improvement.

This factory will not solve your engineering woes. Agents can do substantial work, but this guide keeps a human responsible for scope, engineering judgment, and delivery. Review the code and its evidence. Revisit that level of supervision as models improve and your own evaluations justify it.

The factory floor is the collection of workflows people operate. Start with one repository and an owner who can resolve conflicting findings, stop work, and decide what ships.

Three kinds of work

Category	Purpose	Start here
Development	Implement an accepted request and verify the result.	Take an issue.
Maintenance	Find drift, review ongoing work, and respond to incidents.	Review existing pull requests.
Improvement	Reduce recurring problems in the codebase and the factory itself.	Inspect the factory.

The categories cooperate. Maintenance may find that reviews keep missing a particular defect. An inspector investigates why, then proposes a skill or code change. The accepted change goes through evaluation and review before adoption. Code changes use the development cycle.

The base loop

observe → gather context → assess → act within scope → check → record
                              ↑                         │
                              └── revise or hand off ───┘

An observation can be an issue, PR revision, failed check, changed skill, or scheduled inspection. Record the source and its revision before dispatch. Each stage returns evidence and a next action. Missing context calls for a question; an unsuccessful attempt may need revision or a handoff.

One issue can take several runs. A completed run does not mean the issue is finished. A maintenance run that finds no action necessary is also useful.

Roles and decisions

Role	Responsibility
Triage agent	Establish whether a request is understood and ready to plan.
Implementer	Make the scoped change and explain its decisions and checks.
Reviewer	Assess the exact candidate against its original intent.
Review lead	Reproduce findings, remove duplicates, and record disagreements.
On-call agent	Investigate an incident and hand evidence to its owner.
Inspector	Assess whether the factory’s code, checks, and instructions still serve the project.
Improvement agent	Propose a change based on an accepted inspection finding.
Human owner	Set priorities, resolve disputed judgments, and authorize delivery.

These are roles you author with agents and workflows, not built-in Marbles roles. One person may cover several jobs. Give each agent a specific task, the relevant context, and a stopping condition.

Shared records

The work log preserves the request, implementation history, findings, and decisions. A reviewer needs the original intent as well as the diff. An inspector needs both accepted and rejected findings to assess review quality.

Keep separate records for an issue, a PR review, and an evaluation trial. Link them by issue number, commit SHA, and artifact version ID. A run ID identifies one execution; it is not the identity of the work itself.

Workflows orders the steps, Agents performs model work, and Artifacts retains evidence. Human approvals name the exact candidate they authorize.

Start locally

Prerequisites

Complete the quickstart. Development needs a local Git repository, an authenticated GitHub CLI and agent CLI, and the project’s test commands. The development setup lists the dependencies. Maintenance chapters state which helpers they reuse; improvement needs recorded runs or review findings to inspect.

Choose a category above. Development contains the complete issue walkthrough. Maintenance has separate examples for on-call work, monitoring, and reports. Improvement guides an inspection through a reviewed change.

Start with manual launches. Add schedules after the workflow produces useful results and ownership is clear. These examples use local state and do not coordinate independent machines.

Evaluations supplies reusable methods for comparing models and skills. Design covers product decisions and the implementation handoff.