Software FactoryInstall

Examples

Codex factory topologies.

Start with one clear owner. Add reviewers, advisors, variants, or release gates only when the work benefits from the extra structure.

ExploreStart a factory

Choose the shape before you start adding threads.

The examples below turn abstract coordination into concrete roles, worktree strategies, proof expectations, and starter prompts.

Low risk

Solo Factory

One Codex thread, one scoped slice, one evidence trail. The right starting point for small but real work.

Runtime fitCodex app or docs-only
User

Sets the objective, reviews the result, and approves external effects.

Codex

Plans, edits, verifies, and records the evidence in the project docs.

01Scope
02Edit
03Check
04Record

Worktree strategy

Main worktree is fine when scope is narrow and ownership is clear.

Verification

Focused checks, build or typecheck when applicable, and honest skipped-test notes.

Handoff

A compact status with files changed, proof commands, residual risks, and next action.

Starter prompt

Use Software Factory in Safe MVP mode for one focused slice.

Objective: <describe the smallest real outcome>
Write scope: <files or surfaces Codex may edit>
Non-goals: <what should stay untouched>
Proof required: <checks, screenshots, or review evidence>

Project record excerpt

status: running
active_owner: current_thread
current_slice: focused install-doc cleanup
accepted_evidence:
- npm run check
next_action: user review

Watch for

  • Letting a small task expand into an unreviewed refactor.
  • Declaring done without a command or screenshot behind it.
Medium risk

Principal + Builder + Reviewer

A principal keeps direction, a builder edits, and a reviewer challenges the result before acceptance.

Runtime fitBest in Codex app
Principal

Owns the plan, constraints, acceptance standard, and final integration call.

Builder

Implements the assigned slice and leaves proof in a handoff.

Reviewer

Looks for regressions, missing tests, unclear risk, and weak evidence.

01Plan
02Build
03Review
04Accept

Worktree strategy

Prefer one writer in the main worktree. Reviewer stays read-only unless explicitly assigned a fix.

Verification

Focused checks from the builder, then reviewer-requested checks for changed risk.

Handoff

Builder handoff includes objective, scope, files changed, proof, known risks, and open questions.

Starter prompt

Run a principal-builder-reviewer factory.

Principal: maintain the plan and acceptance criteria.
Builder: implement only <slice>.
Reviewer: stay read-only and return findings first.
Acceptance requires: <proof commands and browser evidence>.

Project record excerpt

active_owner: builder-thread
reviewer_policy: risk_triggered
accepted_evidence:
- npm run typecheck
- browser smoke: desktop and mobile
review_state: pending

Watch for

  • Reviewer starts rewriting instead of reviewing.
  • Principal accepts work without reconciling skipped verification.
Medium risk

Single Writer With Advisory Threads

One thread edits. Other threads research, design, or review without touching the worktree.

Runtime fitCodex app
Writer

Owns filesystem edits and final synthesis.

Researcher

Investigates options, docs, APIs, or examples and reports evidence.

Reviewer

Reviews diffs and proof without changing files.

01Assign
02Research
03Write
04Review

Worktree strategy

Only the writer has write permission. Advisors operate from read-only context or separate scratch.

Verification

Writer runs acceptance checks; advisors can recommend extra checks but do not mutate state.

Handoff

Advisor notes must separate verified facts from recommendations and open uncertainty.

Starter prompt

Use a single-writer topology.

Writer owns all edits in this worktree.
Advisory threads may research and review only.
Each advisory response must include evidence, recommendation, and uncertainty.

Project record excerpt

concurrency_policy: single_writer
advisory_threads:
- research: package/runtime docs
- review: diff and proof review
writer_owner: implementation-thread

Watch for

  • Advisors provide vague advice that the writer cannot act on.
  • A read-only thread starts applying patches and creates hidden collisions.
Medium risk

Parallel Worktree Variants

Separate branches explore competing directions. A principal compares outputs and integrates one deliberately.

Runtime fitCodex app with worktrees
Principal

Writes variant specs, monitors drift, and decides what enters the main branch.

Variant A

Explores one bounded direction in its own branch and port.

Variant B

Explores a competing bounded direction in a separate branch and port.

Integrator

Ports the selected work into the current branch without merging accidental debris.

01Fork
02Explore
03Compare
04Integrate

Worktree strategy

Each variant gets a nested git worktree, distinct branch, distinct server port, and explicit cleanup plan.

Verification

Each variant runs local checks. Integration branch reruns the full acceptance set.

Handoff

Variant handoff must include URL, screenshot evidence, diff summary, checks, and rejected tradeoffs.

Starter prompt

Create two bounded visual variants in separate worktrees.

Variant A: <direction>
Variant B: <direction>
Each must use a unique branch, unique port, local checks, browser QA, and a concise handoff.
Do not merge either variant directly into the main branch.

Project record excerpt

variant_matrix:
- A: transparent asset system, port 3011
- B: transparent big images, port 3012
integration_decision: select B direction, preserve A assets separately

Watch for

  • Integrating both variants because both contain something useful.
  • Using generated assets from one branch without preserving their provenance or quality bar.
High risk

Strict Review Gate

Small work packages move through deeper review before they are accepted.

Runtime fitCodex app or Agentic Factory
Builder

Implements one narrow slice and records exact proof.

Reviewer

Challenges behavior, compatibility, and missing coverage.

Verifier

Runs the agreed gate and captures failures or residual risk.

Principal

Accepts, revises, or stops based on evidence.

01Slice
02Build
03Review
04Gate
05Accept

Worktree strategy

Keep one writer unless isolated worktrees are required. Gate output belongs in the record.

Verification

Full relevant test gate, diff hygiene, generated-file guards, and explicit skipped checks.

Handoff

Acceptance requires proof commands, reviewer disposition, and any unresolved risk.

Starter prompt

Use Strict mode.

Risk area: <contract/security/data/provider path>
Keep slices small.
Do not weaken validation to pass checks.
Acceptance requires reviewer findings, proof commands, and residual-risk notes.

Project record excerpt

work_mode: strict
verification_level: full_relevant_gate
reviewer_policy: required
external_effect_policy: explicit_operator
acceptance_state: blocked_until_review

Watch for

  • Weakening validation to make the gate pass.
  • Confusing a successful build with behavioral verification.
Recovery risk

Recovery Control

Stop adding work, inspect state, preserve useful changes, and reassign ownership before building resumes.

Runtime fitCodex app or Agentic Factory
Inspector

Reads status, diffs, processes, ports, and failing evidence without reverting blindly.

Principal

Decides what to keep, adapt, remove, or hand back.

New Owner

Resumes only after the state and scope are explicit.

01Stop
02Inspect
03Preserve
04Assign
05Resume

Worktree strategy

Do not reset blindly. Inspect unknown changes first, then remove only what the user or principal approves.

Verification

Targeted checks around the recovered state, then full gates if shared behavior was touched.

Handoff

Recovery handoff states ready/blocked, exact proof, exact next action, and who owns it.

Starter prompt

Use Recovery mode.

Do not edit yet.
Inspect git status, active processes, worktree registrations, and recent proof.
Report keep/adapt/remove decisions before resuming implementation.

Project record excerpt

status: recovery
dirty_state_reviewed: true
preserve:
- selected generated assets
remove:
- abandoned variant worktrees
next_owner: principal-thread

Watch for

  • Treating recovery like cleanup and deleting useful work.
  • Letting the stale writer continue after ownership has moved.
High risk

Release Readiness

Freeze scope, verify the ship criteria, package evidence, and make residual risk visible.

Runtime fitCodex app or Agentic Factory
Release Owner

Owns the final criteria and stops new scope from sneaking in.

Verifier

Runs build, audit, browser QA, and deployment-specific checks.

Reviewer

Reviews release notes, residual risk, and acceptance evidence.

01Freeze
02Verify
03Package
04Ship

Worktree strategy

Use the integration branch only. Variant or scratch worktrees should already be removed or isolated.

Verification

Build, audit, diff hygiene, browser QA, deployment preview, and generated-file guards where relevant.

Handoff

Release packet includes what shipped, proof, deploy target, known risk, rollback or follow-up path.

Starter prompt

Use Release mode.

Freeze scope.
Verify Cloudflare static export readiness.
Run checks, browser QA, audit, and diff hygiene.
Report residual risk before commit or deploy.

Project record excerpt

release_state: verifying
scope_frozen: true
proof_required:
- npm run check
- npm audit --omit=dev
- browser QA desktop/mobile
deployment_target: cloudflare_pages

Watch for

  • Adding polish during release verification.
  • Reporting readiness without deployment-specific evidence.
High risk

Agentic Control Plane

Use Software Factory for the docs-first protocol, then Agentic Factory when durable state and CLI controls matter.

Runtime fitAgentic Factory companion
Software Factory

Defines the operating policy, docs, modes, and handoff shape.

Agentic Factory

Stores events, baton state, reviews, verification records, and dashboard status.

Operator

Uses CLI controls to pause, resume, inspect, or render state.

01Policy
02Events
03Controls
04Record

Worktree strategy

Keep the same write-discipline rules. The control plane improves state durability, not merge physics.

Verification

Use both repo checks and control-plane health or doctor checks before declaring the factory healthy.

Handoff

Handoff can reference durable event IDs, review records, and verification history.

Starter prompt

Use Software Factory with the Agentic Factory companion.

Keep Codex app orchestration as the primary runtime.
Record events, reviews, verification, and pause/resume checkpoints.
Render a clear markdown ledger before handoff.

Project record excerpt

protocol: software_factory
control_plane: agentic_factory
state_backend: sqlite
records:
- events
- reviews
- verification
- pause_resume_checkpoints

Watch for

  • Assuming a database makes unclear ownership safe.
  • Using the control plane before the team understands the docs-first protocol.

A field guide for when each shape earns its complexity.

The factory should make work clearer. If a topology adds ceremony without improving ownership, proof, or recovery, choose a smaller one.

Low

Solo Factory

One Codex thread, one scoped slice, one evidence trail. The right starting point for small but real work.

Best for
Docs, focused features, repo cleanup, packaging, and first factory adoption.
Avoid when
Avoid it when the work touches several risky contracts or needs parallel exploration.
Medium

Principal + Builder + Reviewer

A principal keeps direction, a builder edits, and a reviewer challenges the result before acceptance.

Best for
Meaningful product work where quality matters but the scope is still understandable.
Avoid when
Avoid it for trivial edits; the review lane should earn its keep.
Medium

Single Writer With Advisory Threads

One thread edits. Other threads research, design, or review without touching the worktree.

Best for
Complex decisions where you need more thinking but cannot afford write collisions.
Avoid when
Avoid it when the advisors do not have a crisp question or evidence request.
Medium

Parallel Worktree Variants

Separate branches explore competing directions. A principal compares outputs and integrates one deliberately.

Best for
Visual directions, architecture choices, or prototypes where comparison beats debate.
Avoid when
Avoid it when variants are likely to edit the same core contracts without an integration owner.
High

Strict Review Gate

Small work packages move through deeper review before they are accepted.

Best for
Shared contracts, auth, data writes, provider calls, security-sensitive paths, and business-critical logic.
Avoid when
Avoid it when the extra ceremony would only slow a low-risk copy or styling change.
Recovery

Recovery Control

Stop adding work, inspect state, preserve useful changes, and reassign ownership before building resumes.

Best for
Dirty worktrees, stale threads, failed gates, conflicting edits, and unclear next action.
Avoid when
Avoid it when the state is already clear and a normal review would answer the question.
High

Release Readiness

Freeze scope, verify the ship criteria, package evidence, and make residual risk visible.

Best for
Cloudflare deploys, open-source publishing, PR merge readiness, and final acceptance.
Avoid when
Avoid it while product direction is still changing; release mode should not discover the feature.
High

Agentic Control Plane

Use Software Factory for the docs-first protocol, then Agentic Factory when durable state and CLI controls matter.

Best for
Long-running factories, durable event history, SQLite-backed records, dashboards, and repeated handoffs.
Avoid when
Avoid it for a first small task where seeded docs are enough.

Default smaller.

Start with Solo Factory or Principal + Builder + Reviewer. Escalate only when risk, ambiguity, or comparison pressure justifies it.

Separate exploration from integration.

Variant worktrees are useful because they isolate experiments. Integration should still be a deliberate, reviewed edit.

Proof changes with risk.

A copy edit and a provider call do not need the same gate. The topology should make that difference visible before work begins.