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 this package differs

This is not a different kind of software factory. It is an extended fork of the same generic engine published as @swamp/software-factory and @adam/software-factory.

The current published packages compare as follows:

This package is closest to @swamp/software-factory: both include dispatch recording, schema-validated artifacts and evidence, materialized status and validation records, a static work-item summary report, and a driver skill. Those shared capabilities are not unique to this package.

Compared with the currently published @swamp and @adam packages, this package additionally provides:

• explicit, compatibility-checked migration of active runs to an edited factory definition without discarding their recorded history;
• explicit recovery of a terminal run at a named non-terminal stage;
• optional approval and rejection binding to exact artifact/evidence versions and canonical payload digests, plus immutable, non-authorizing authority challenges for those exact subjects; and
• provider-neutral attempt leases, heartbeats, bounded retry outcomes, and orphan-attempt claims for workflow execution.

Use @swamp/software-factory as the simpler official default when those additions are unnecessary. Use this package for longer-lived runs that need definition migration, failure recovery, exact-subject approvals, or durable workflow-attempt tracking. @adam/software-factory is an earlier, smaller variant without the newer operational features shown above.

This is an engine, not a turnkey SDLC or an agent runtime. It does not ship a prescribed lifecycle, coding-agent provider, repository integration, issue tracker, CI system, or release implementation. Consumers supply those in factory definitions, workflows, and companion extensions.

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 @mgreten/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 persists a self-describing packet (current stage, work spec with run-data bindings resolved, per-gate transition readiness, context manifest) as a queryable status-<workItem> record, and the driver reads exactly the fields it needs with swamp data query --select rather than re-parsing a whole blob; it then 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)
• begin_attempt / heartbeat_attempt / complete_attempt / claim_orphan_attempt — provider-neutral workflow-attempt leases and bounded terminal decisions
• migrate — explicitly adopt a compatible definition change for an active run without discarding its state, artifacts, or approvals
• resume — recover a terminal run at an explicitly named non-terminal stage without destructive reset
• status — the driver's entrypoint: what a work item requires right now, or a factory-wide overview of all runs
• record_dispatch — record that a stage's work ran (before it runs); proves execution so a stage can't be skipped, and drives the runaway-loop guard (third dispatch of an entry hard-fails as runaway-loop-suspected)
• record_artifact / record_evidence — versioned, schema-validated work products and external facts (every artifact and evidence carries a declared schema, validated on record; strict objects by default)
• resolve_findings — resolution notes on kind: findings artifacts
• mint_authority_challenge — mint an immutable engine-bound challenge for the current exact approval subject. This first legacy-subject increment is explicitly non-authorizing: it cannot approve, dispatch, or advance and does not claim trusted human approval.
• approve / reject — human gate decisions, cycle-scoped; gates may bind decisions to exact artifact/evidence versions and canonical payload digests
• 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 @mgreten/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 (optionally subject-bound), 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>, authority-challenge-<eventDigest> (content-addressed, non-authorizing prerequisite events), validation-<workItem>-<target> (recorded payload-validation failures, bindable as retry feedback), an append-only journal-<workItem>, and a status-<workItem> materialized view (refreshed on every status call; status-_factory holds the fleet overview) that the driver queries instead of scraping a log line.