THE WORLD IS NOT STANDING STILL.RSS
BIG CHANGE.

Markdown edition

# Set up an Archon-backed software factory and review one issue

> A pinned maintainer guide to planning and reviewing one Archon-backed coding issue, from product mission and runtime checks to a human merge decision. BIG CHANGE has not run the factory.

By BIG CHANGE Editorial

Published: 2026-10-19T14:43:34.857Z
Updated: 2026-10-19T14:43:34.857Z
Canonical: https://bigchange.ai/blog/archon-software-factory-reviewed-issue

![Conceptual charcoal illustration of one reviewer studying an unbranded two-column code change printout clipped to a wall rail.](https://bigchange.ai/api/media/file/archon-reviewed-code-change-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no factory installation, issue delivery, code review outcome or product interface is depicted.

The [AI Software Factory repository](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md) describes a route from a product mission and issue to an Archon-built pull request. Its installer and workflow checks are only the start. The maintainer's [first-hour guide](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) says live end-to-end validation remains to be done. This guide follows factory commit `9e2d85298b45497031009597a6ae0811b66fe6d6` and its pinned Archon revision `fad09169ea1b43512bc7ee88470d47f960a3e0f8`. It is a reading of the documentation and code, not a report of a BIG CHANGE installation or run.

The route below is for a team that controls an application repository or a PRD, its GitHub permissions, and its model-provider account. The maintainer explicitly documents cloning and installing the factory into your own repository. The pinned factory tree has no license or notice file; this guide does not establish broader reuse or redistribution rights. Archon's MIT license applies to the separate Archon source. Keep any provider secret out of issue text, prompts, logs and review receipts.

## The big change

- **What changed:** This implementation joins product scope, issue planning, coding, independent review and runtime checks through one pinned Archon workflow pack. The factory supplies the project inputs and launcher; the shared pack owns the AI steps.
- **Why it matters:** A team can trace one proposed change from an issue to a particular diff, CI result and running candidate before deciding whether to merge. Installation checks alone leave that trace incomplete, and the maintainer says the live integration still needs validation.
- **What to watch:** The first useful proof is a real issue whose delivered revision passes meaningful journeys and an independent holdout, with its costs and review record visible to the team. Scheduling and deployment remain separate decisions after that review.

## 1. Check the repository, permissions and pinned source

The [maintainer's setup instructions](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent) name Git, Python 3.10 or later, `gh` authenticated with `workflow` scope, a GitHub remote, a coding agent, Bun and uv. Git must also be able to push workflow files (`gh auth setup-git`). Check the application's existing test, start and CI commands, branch protection, GitHub access, provider authentication and model billing before starting an agent run. Only grant the repository and workflow authority the run needs.

Clone the factory outside the application repository and check out the specified factory commit. From the *application* root, the documented installer command is:

```bash
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init
```

Use `python3` if necessary. The installer copies factory and project templates and installs the Archon source named in [`pack.json`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json). The README and pack at this commit both specify `fad09169ea1b43512bc7ee88470d47f960a3e0f8`. The installer does not authenticate a provider, select model tiers or start a schedule. Inspect the resulting file changes before accepting them in your repository.

Configure your chosen provider and supported model identifiers using the installed Archon configuration guidance. Set the project's real static and unit commands in `harness/harness.config.json`. Name the CI jobs needed for merge in `required_checks` when GitHub cannot report branch protection, and review `protected_paths` so changes to mission, harness and factory policy require a human. The template leaves ordinary check commands and `required_checks` empty; copying it alone does not establish a usable acceptance gate.

## 2. Write the mission and checks for the product you have

Write `MISSION.md` with the product's purpose, hard limits and plausible requests that are out of scope. In `harness/END-TO-END.md`, describe two to five journeys that the current application actually completes, including the value a user sees. A journey that requires an unbuilt feature would block the first delivery. Write separate cases in `.factory/holdout/HOLDOUT.md` that combine behaviors or probe edge cases. That directory name does not hide the cases from a builder with access to the same checkout; put genuinely private cases outside that checkout and provide them only to verification.

For a repository containing only a PRD, the [README](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent) instead calls for the mission, intended journeys and harness commands from the document. Its first proposed issue must make the product runnable and name the start command, health and build-identity paths, tests and CI. Review that proposal before allowing issue publication.

Turn the journeys into the scenario inputs expected by Archon's runtime workflows. Follow the installed [`factory/RUNTIME_HOST.md`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md) for an app snapshot prepared from the delivered commit, fresh state, health and build-identity checks, and the allowed Python or Node launch commands. The documented host does not support remote databases, containers or cloud resources as owned runtime resources. An app using them needs a separately justified verification arrangement; a successful local host check would not establish their isolation.

Before relying on the evaluator, establish a passing baseline that exercises real user value, show that a relevant deliberate fault fails, and check that a wrong candidate identity returns an inconclusive verdict. The host guide gives the suite inputs and exact expected fields, including `expectations_passed: true` and `baseline_verified: true`. Keep the actual native return and candidate identity as evidence. An assertion that only sees a page load, or a test that directly seeds the final state, is too weak for this purpose.

## 3. Check installation, then choose one work item

Run these from the application root:

```bash
python factory/consumer.py doctor
python factory/consumer.py list
```

`doctor` checks the pinned source, command capabilities and available workflows. `list` shows discovered workflows. Neither proves that a provider can complete an issue, CI will pass or the application will run. Resolve their reported failures before delivery; keep the schedule off.

For an existing codebase, write one small issue with a clear outcome and acceptance checks. The README documents this command to take an issue through triage, delivery and review to a PR:

```bash
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json
```

Replace the issue URL with one you own. The explicit `discovery_publication=preview` keeps adjacent findings from the review unfiled; the pinned `archon-ship` workflow otherwise defaults that input to `auto`. Use `archon-lifecycle` only after its runtime scenario and holdout inputs are ready. Pass the issue as `target`, those input paths as `scenario` and `holdout`, `merge_mode=approve`, and `discovery_publication=preview`. Also supply a project-approved `merge_method`: `merge`, `squash` or `rebase`. For example, use `merge_method=squash` only when your repository permits it. That workflow includes runtime and holdout verification, repair and a merge gate. Approval mode retains a human decision before merge; do not treat a workflow's ready label as that decision. If you use the factory runtime host, its documented `--runtime-host` option is foreground only and cannot accompany `--detach` or `--resume`.

For a PRD, the documented backlog command is:

```bash
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve
```

Replace the quoted `docs/PRD.md` with your PRD's actual path relative to the application checkout. Review the proposed ordered issues before publication. Wire the runtime host from the first issue's declared app start and identity contract, then take that issue through `archon-lifecycle` with the prepared journeys and holdout. The first ticket must be checked as carefully as later work.

## 4. Judge the diff and running result before approval

Keep the returned run ID. The consumer exposes `get <run-id> --json --events` and `status --all --json` for progress and evidence. Inspect the issue and plan against `MISSION.md`; read the actual PR diff and independent current-head review; check the required CI results and protected-path report. Run the product journeys against the delivered revision and inspect the native runtime and holdout results, including candidate identity. Compare the observed user result with the issue's acceptance checks. A reviewer should send a deficient PR back for repair; the README describes `archon-deliver --adopt <run id>` for a delivery run held by the merge queue.

Only a human with repository authority should approve a merge after those checks pass. Deployment needs its own project-specific deploy, health and identity commands, plus a post-deploy revision readback; a merged PR by itself proves no deployment. Keep scheduling off through this first issue and decide separately whether any recurring run should be enabled.

The [maintainer's cost guidance](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#cost) gives no fixed price for a run. It advises measuring tokens from day one and watching model calls on one small issue before enabling a loop. Charges depend on the chosen provider, models and account terms. BIG CHANGE has not measured this factory's spend.

An active run also needs an explicit stop decision. The [consumer code](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py) makes `halt` block new launches and continuations, while `cancel <run-id>` targets active work. `pause` stops timer launches but permits wakes of work already in flight. None of those commands is a substitute for checking the current run state and remote repository changes.

## Sources & further reading

- [Pinned factory README](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md): setup steps, commands, product inputs, workflow choices and stated limits. This is the maintainer's description, not evidence of a BIG CHANGE run.
- [Pinned pack manifest](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json) and [consumer code](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py): Archon revision, exposed workflows and the distinctions among status, halt, cancel and pause.
- [First-hour guide](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) and [runtime host guide](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md): the maintainer's validation caveat and requirements for a candidate-bound runtime check.
- [Related BIG CHANGE report on coding agents and completed work](https://bigchange.ai/articles/ai-coding-agents-review-output-study): context for checking finished outcomes. It covers a separate study, not a dated continuation of this factory implementation.

## Sources

- [AI Software Factory README, pinned commit](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md) — Maintainer setup, project files, workflows, issue and PRD paths, merge policy and operating limits.
- [Pinned factory pack manifest](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json) — Declares the exact Archon revision, workflow entries and CLI capabilities; matches the pinned README.
- [Factory first-hour guide, pinned commit](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) — Setup sequence and explicit statement that live end-to-end validation remains necessary.
- [Factory consumer implementation, pinned commit](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py) — Implementation of doctor/list, workflow invocation, status, halt, pause and cancel.
- [Factory runtime host guide, pinned commit](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md) — Candidate binding, baseline and deliberate-fault calibration, supported app shapes and limitations.
- [Factory harness configuration template, pinned commit](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/harness/harness.config.json) — Shows blank project check commands and required-check setting and default protected paths.
- [Pinned Archon MIT license](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/LICENSE) — Archon's license terms; does not establish a grant for the separate factory repository.
- [Pinned Archon ship workflow](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/ship/archon-ship.yaml) — Confirms discovery publication defaults to auto and preview keeps adjacent findings unfiled.
- [Pinned Archon lifecycle workflow](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/lifecycle/archon-lifecycle.yaml) — Requires an explicit merge method from merge, squash or rebase.
- [Pinned Archon backlog workflow](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/backlog/archon-backlog.yaml) — Describes the PRD as a path inside the checkout.
- [BIG CHANGE coding-agent study report](https://bigchange.ai/articles/ai-coding-agents-review-output-study) — Related but distinct context for checking completed outcomes.