Software Factory

A fully generic, model-driven state machine for guiding agents through a software development lifecycle. The entire machine — stages, transitions, gates, required artifacts, review skills, agent commands, system prompts — lives in the model definition's globalArguments as data. The engine ships no lifecycle concepts: adversarial review, comprehensive testing, release, and UAT stages are expressible (see examples/), never assumed.

How it works

An instance is a factory serving many work items concurrently — every method takes workItem, and all run data is namespaced per work item:

swamp model create @swamp/software-factory my-factory
swamp model edit my-factory      # fill globalArguments: stages
swamp model method run my-factory start --input workItem=ISSUE-42

The driver loop is the same for every factory: status returns a self-describing packet (current stage, work spec with run-data bindings resolved, per-gate transition readiness, context manifest); the driver does the stage's work, records products, and advances. Gates are hard enforcement — evaluated in pre-flight checks and re-validated inside advance.

Methods

• start — validate the graph and start a work item at the initial stage (refuses to restart; resume with status)
• status — the driver's entrypoint: what a work item requires right now, or a factory-wide overview of all runs
• record_artifact / record_evidence — versioned, schema-validated work products; opaque external facts
• resolve_findings — resolution notes on kind: findings artifacts
• approve / reject — human gate decisions, cycle-scoped
• advance — move along a gated transition
• summary — full implementation history of a work item as markdown, rendered statically from the run data (no LLM); also persisted via the @swamp/software-factory/work-item-summary report
• validate / describe — definition lint; Mermaid + tables
• reset — destructive restart, requires confirm=reset

Gates

artifact-exists, artifact-fresh (subject-version + recordedThisCycle), findings-clear, human-approval, evidence-recorded (cycle-scoped, field matching), cooldown, max-cycles (routing), cel (CEL predicates over run data), workflow-succeeded (verified against swamp's own workflow run records, not driver attestation).

Every stage carries maxCycles (default 5): entries past the limit park the run for an explicit human cycle-override approval.

Run data

All resources are versioned, immutable, and namespaced per work item: state-<workItem>, artifact-<workItem>-<name>, evidence-<workItem>-<name>, approval-<workItem>-<gateId>, and an append-only journal-<workItem>.