The AI Software Factory repository 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 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 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:

Terminal
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. 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 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 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:

Terminal
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:

Terminal
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:

Terminal
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 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 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