For AI agents: the complete documentation index is available at https://jig.md/llms.txt, the full documentation bundle is available at https://jig.md/llms-full.txt, and this page is available as Markdown at https://jig.md/guide/software-factory.md.
jig
DocumentationGuidePrerelease

#Run a small software factory

View Markdown

Turn a fixed set of one or two authorized issues into separate tested patch packets. Explicit method IDs select reviewed repair budgets; an optional Semantic Router can choose from issue text when the choice is unknown, or abstain. Each factory-owned worker reproduces the defect, requests bounded source replacements, executes reviewed commands, and checks unchanged acceptance cases. You still decide whether any patch should be combined, merged, or released.

Use the small software factory source. This is an implemented, self-contained source application. Its local repair Flow and Semantic Router use ordinary workspace dependencies. Its external Agent and FLOW dependencies are published alphas. Independent installed-package adoption and maintainer-authored source comparisons are distinct evidence, summarized below. Neither establishes general repair reliability or comparative advantage.

#Run the supplied batch

In a copy of the example, inspect batch.json, the Agent, single-pass and checked-correction Bindings, and the two named case files. Configure a supported client through Choose an Agent. The inline policy in bindings/agent.ts selects native Codex through ACP as an example choice. Edit that Binding for a lasting choice, or explicitly propose another client during review. A selected ACP prerequisite failure stops review before new approval; review never rewrites policy. Review prepares the ordinary declared dependencies. To use an HTTP Agent method instead, follow the package and Binding setup in Reuse the Agent method, including its optional OpenAI-compatible gateway route. Then authenticate the selected Agent:

jig review --allow-resolution-network
jig run

The reviewed entrypoint in jig.ts selects the factory, batch.json, the fixtures source tree and an eight-minute deadline. Jig chooses a fresh packet directory in operating-system temporary storage for its writable deliverables and reports it on stderr. Repeating jig run leaves earlier packets intact, but the operating system may clear temporary storage. Use jig run --out ./factory-result to choose a retained location that does not already exist. For another batch, override its input:

jig run --input @another-batch.json

Existing results are never overwritten. Explicitly naming a target bypasses entrypoint defaults; supply that invocation's arguments in full.

The standard reporting contract supplies three factory views: Jobs shows requested goals, source scope, reviewed approach and outcomes; Checks shows repository tests and independent acceptance cases; Patches shows independently checked patch packets and evidence links. Activity follows current work and check reports. Execution shows the actual call tree, distinguishing baseline checks from checks of each proposed repair. Jobs pairs concise outcomes, verified checks and patch references with each job's goal and evidence. Wide terminals show the selected job's details beside the list. Blocking causes remain in the attention bar; press ! to read the complete cause. Use jig run --display tui to switch views, select a job, inspect its details, and use r to select a verified file preview after packet delivery. Use jig run --display web to open the same Jobs, Checks and Patches views in a browser through the private link printed after execution starts. Delivered files lets you read each checked patch and its evidence once delivery is verified. A job with several evidence references offers an explicit choice; the display does not guess which file you meant. No Flow changes are required. Jobs includes the exact original request file; long displayed goals explicitly identify excerpts. Complete requests also remain in the supplied input and result.json. The completed inspector selects Jobs unless you already chose a view. It stays read-only until you leave, subject to any explicit enclosing command deadline. Execution, cleanup and delivery have already settled. Press q to ask before leaving the TUI, with Stay selected; during work, confirmed exit continues in the ordinary transcript. Escape returns within the TUI. Ordinary jig run selects TUI in suitable interactive terminals; otherwise it shows ordinary output and exits with the final report. --display plain emits a simple transcript. The final application output gives a brief report of each job and public failure causes, while full evidence remains in result.json. Reopen the saved evidence later without starting work:

jig inspect --result DESTINATION --display tui
jig inspect --result DESTINATION --display web

Replace DESTINATION with the packet directory reported by Jig. This shows the recorded result, verified saved files and diagnostics. Current packets do not retain the live factory tabs or call graph. Add --receive progress --json for explicit machine records, or --updates off to disable automatic observation. Rapid phase replacements and slow observers may omit intermediate activity. A checkpoint notice follows durable storage; counts measure saved jobs, including failures. If live updates stop early, check the final report and saved evidence. These views report application observations; the final result and retained evidence determine whether a patch is review-ready. The factory's checkpoint slot separately retains settled job evidence and original request files across interruption.

The factory accepts at most two jobs. It validates and captures every selected project and case set before starting paid work, then routes and repairs each job independently. One configuration allows a single checked proposal; the other allows one correction using check feedback. Both require the same evidence. Original projects are read-only; only a new result packet is writable. Source reads use explicit file offsets and must match their observed sizes; an incomplete or wholly empty materialization stops before worker dispatch.

#Review the packet

Start with <reported destination>/files/summary.txt, then inspect each job directory and the host-owned result.json.

  • review.patch means that job reproduced its defect and the final candidate passed its repository test command and every independent case.
  • proposal-N.patch preserves a valid unsuccessful proposal without calling it review-ready.
  • A failed or cancelled peer stays explicit. It does not erase a healthy job's patch or manufacture a verdict for unfinished work.
  • Checkpoint evidence contains only settled jobs. After interruption, the host can deliver that accepted checkpoint with the unsuccessful Run status.

Patches are checked separately. The factory reports overlap and blocks conflicting replacements, but it does not claim that two individually passing patches pass when combined. Apply selected patches to a disposable copy, run combined checks, and review the changes before a human merge decision.

#Adapt the issue set

Place each small project beneath the directory supplied as source. The included specialist runs the same test/project.test.ts and src/cli.ts paths for both projects; change its Binding only when your bounded application needs a different common command shape.

For each job:

  1. add a named *-cases.json beside flows/factory/FLOW.ts;
  2. add its id, relative directory, case-set name, issue text, and existing editable src/*.ts or src/*.js paths to batch.json;
  3. reproduce the failure yourself; and
  4. review again before starting the batch.

Do not move acceptance policy into candidate source or relax it after seeing a proposal. Optional cancelAfterMs covers the entire routing-and-repair interval of one job while its peer may finish; root cancellation still stops all owned work.

#Choose a method without changing its authority

The supplied issues express different work preferences: the log repair gets one proposal, while the timesheet repair can use check feedback for a correction. The supplied batch.json selects "method": "p1" for logs and "method": "p2" for timesheet, so an ordinary jig run spends no Agent calls on selection. Inspect routing in the result packet to see the exact chosen configuration. flows/factory/methods.ts supplies opaque IDs and descriptions and maps them to reviewed slots. A second proposal is a work budget choice, not weaker acceptance. When semantic selection is requested with no preference, candidate data describes checked correction as the default; the router prompt asks the Agent to apply that default only when the method suits the stated requirements. This remains model judgment, not a deterministic guarantee. When the operator already knows which configuration to select, set that job's method to p1 or p2; this exact reviewed choice bypasses the router. Omit method to ask the router to judge from the issue and preferences. Both paths still use the same worker and acceptance checks. The router is useful when the preference is expressed in the task text; it is not a cheaper or more reliable replacement for an explicit choice.

For example, a job may include "method": "p1" to require one proposal, or "method": "p2" to allow a checked correction. Unknown method IDs fail input validation before any Agent call. The final and checkpoint evidence records whether the choice was explicit or automatic and the exact selected slot.

The standalone repair also publishes Repair and Checks on its optional updates channel; their reports remain provisional for a caller. The router publishes Selection on progress, showing task, eligible candidates and a validated choice or abstention. Both use the same portable profile as the factory’s views.

The Semantic Router source package is independently reusable. It accepts only task text and a bounded candidate list, uses the ordinary Agent contract, and returns a supplied ID with a reason or null for abstention. Candidate IDs and descriptions are data, not executable selectors. It has no host registry, provider configuration, or factory-specific prompt. Candidate descriptions are still natural-language model input: use reviewed application-owned descriptions, and do not treat membership validation as protection against instruction-like text or as an authority check.

The factory validates even a replacement router's complete result and membership before calling the mapped slot. Abstention, Agent blocked/limit, malformed output and operational failure produce no worker dispatch or patch for that job. They remain visible alongside healthy peers. Job evidence retains the exact routing input, validated decision and selected slot; checkpoint and final summaries show the routing outcome. The router returns before the worker starts, keeping each concurrent branch within the ordinary host budget.

Adding an eligible method changes candidate data and the factory's declared slot and Binding. Keep any input/result adaptation in application code and preserve independent patch inspection. Reusing the router for a different domain changes only candidate data and project wiring. This is bounded semantic dispatch, not catalogue discovery or installation. Membership checks enforce the finite set; they cannot guarantee an appropriate choice within it.

#Bounded live source evidence

On 2026-09-24, the current router instructions were evaluated on eleven frozen, synthetic held-out cases through an ordinary Jig Run in a fresh consumer project, using mistralai/mistral-small-2603. Seven choices matched the pre-recorded expectations. Four did not: the Agent selected a sole candidate despite an explicit mismatch, selected the default when task context was missing, treated contradictory mandatory budgets as conditional, and followed instruction-like text embedded in one candidate description over the task. All eleven Runs completed successfully at the protocol level; that does not make the four judgments correct. The result is not evidence of improved suitability or abstention, and it exposes that candidate text can steer the Agent. The router therefore remains a bounded choice mechanism, not a suitability, injection resistance, permission, or policy boundary. Supply reviewed application-owned candidate descriptions and independently validate dispatch policy.

This is a small maintainer-authored synthetic set, not a general accuracy estimate. Cases, prompt and host hashes, per-Run outputs, and the full method are retained in the repository's transient .tmp/semantic-router/revised-holdout/ record; do not tune against this set and then reuse it as held-out evidence.

An earlier evaluation of the previous router instructions used a different frozen set, so its outcomes below are not directly comparable to the current run.

In a fresh copy with an operator-selected OpenRouter Mistral BYOK Agent, twelve frozen direct router Runs tested repair preferences, abstention, adversarial text, and an unrelated prose-method set. With mistralai/mistral-small-2603, ten of twelve choices matched the expected sets. It selected a repair method instead of abstaining on an underspecified request and on contradictory mandatory preferences. A lighter mistralai/ministral-8b-2512 run matched nine of twelve, also missing the no-preference default. All twenty-four Runs settled; this small synthetic set is evidence of behavior, not a general accuracy estimate.

The same source factory then routed the supplied two issues to different reviewed configurations. Both workers reproduced their defects, passed their fixed Bun tests and every independent case after one proposal, and delivered separate review patches. A fixed two-proposal baseline on the same inputs also completed both patches. Approximate command wall time was 128 seconds routed versus 96 seconds fixed; this trial demonstrates method selection and evidence retention, not a completion or speed advantage. Original fixture bytes were unchanged, and both root Runs retained confirmed fencing and release. The provider did not expose per-call cost through these Jig results, so no factory cost comparison is claimed.

#Earlier factory evidence

The following comparison predates semantic dispatch and does not measure routing.

On the supplied two-project candidate run, one native Agent request failed while the other worker produced a patch passing two repository tests and four independent cases. The batch returned blocked, exported only the healthy patch, retained both outcomes and a checkpoint, and left all source bytes unchanged.

A frozen comparison used Codex 0.154.0 with its default model selection. The factory needed one batch command but accepted one of two issues in about 75 seconds. A direct Codex coding session edited disposable copies and accepted both issues in about 169 seconds; it also had to construct its evidence harness, whose first invocation failed before being corrected. Counting the operator's mistyped CLI submission gives one action versus two, but excluding that unrelated mistake makes the primary action metric a tie. This run therefore does not prove a coordination advantage or superior patch quality. It does demonstrate the factory's predefined evidence shape and healthy-peer retention under a real failure. The earlier two-fixture controller comparison also remains a tie.

An independent builder then replaced the issue set with invoice-total and word-frequency projects without changing the Bindings. It reproduced both defects, reviewed three exact grants, and completed one bounded batch in 121 seconds. The invoice Agent failed before proposing a patch. More importantly, the word-frequency child saw empty files even though the host's captured input manifest retained all 24 nonempty source identities. No patch was called ready, all originals remained byte-identical, and nothing was merged.

At that stage, the source correction verified every projected attachment's byte count and digest in Jig's trusted inner launcher before Flow code started; the repair input layer also rejected incomplete and wholly empty reads. Replaying the same adapted input failed before any worker or Agent call. A separate 24-file nested host projection check passed, so that evidence alone did not establish the cause of the projection mismatch.

#Published package evidence and adoption limits

This example remains limited to small Bun projects and one or two preselected issues with a human merge gate. An independent builder used published packages and this guide to adapt it to pantry and receipts projects: both patches passed their repository commands and all seven unchanged independent acceptance cases. No patch was applied or combined. This establishes that particular adaptation, not general repair reliability or comparative superiority.

A later same-project, two-issue attempt reproduced both defects, but the configured Agent endpoint rejected both calls before proposals, so no patch or repair-quality evidence resulted. That narrower adoption criterion remains unproved until an independent builder produces a review-ready patch with passing repository and independent checks, retains inspectable outcomes for the other issue, and can explain how to review the results. These runs were not technically isolated clean-room tests and establish neither general model reliability nor an advantage over a capable coding Agent.

Immediate follow-up interruption also remains unqualified with a supported native client on Ubuntu using published packages. Deterministic tests and the documented requirement to await the same turn's result do not replace that live qualification.