Loose agent run
Work splits faster than ownership
Codex app skill
Run Codex like a delivery system.
Plan large work, split it safely, verify progress, and resume without losing context.
Codex install
npx skills add jddelia/software-factory \
--agent codex \
--global \
--yes
Clear ownership
Keep one active writer by default, then route review and feedback without collisions.
Recoverable work
Leave project records that explain what changed, what passed, and what still needs attention.
Evidence before done
Treat checks, screenshots, logs, and review notes as part of delivery, not cleanup.
Safe pauses
Stop, resume, or recover long-running work without asking the next thread to guess.
Big agent projects fail in ordinary ways.
Software Factory handles the boring project-control problems that show up when Codex work becomes larger than a single edit.
Factory-controlled work
Software Factory keeps each slice scoped, assigned, and reviewable.
Control move
Assign one clear work owner before edits begin.
Visible result
The next person can see who owns the change and what is out of scope.
Loose agent run
Threads lose the reason behind a change
Factory-controlled work
The project record captures decisions, proof, blockers, and next actions.
Control move
Keep decisions and proof in the repo, not only in the transcript.
Visible result
A restarted thread can recover the why, not just the diff.
Loose agent run
Progress looks complete before it is verified
Factory-controlled work
Acceptance depends on focused evidence, not a confident status update.
Control move
Make checks, screenshots, and known risks part of acceptance.
Visible result
Green status means there is evidence behind it.
Loose agent run
Interrupted work is hard to restart
Factory-controlled work
Stop and resume packets preserve enough state to continue safely.
Control move
Pause with current state, blockers, proof, and the next safe action.
Visible result
Work can restart without asking the next thread to infer the plan.
How the workflow stays recoverable.
The skill turns large work into a visible sequence: choose the posture, write down the state, verify the result, then continue with evidence.
Choose the operating mode
Pick the delivery posture: faster slices, stricter checks, release readiness, or recovery.
Create the project record
Seed the repo with durable docs that explain ownership, checks, handoffs, and stop rules.
Assign focused work
Give Codex a clear objective, write scope, non-goals, and proof requirements.
Verify the evidence
Run the right checks for the risk level and record skipped work or residual risk honestly.
Review and continue
Accept, revise, pause, or hand off with enough context for the next thread to continue.
Built for the Codex app first.
Software Factory is designed around Codex app primitives: delegated threads, permissions, browser QA, checkpoints, and long-running handoffs. In smaller runtimes, the same docs become a manual or single-thread operating protocol.
Delegated worker threads
Tool permissions and blockers
Browser QA and screenshots
Goals, checkpoints, and handoffs
Pick the mode that matches the risk.
The same protocol can move quickly, slow down for critical work, or recover a messy project before another edit starts.
Safe MVP
Ship the thinnest real product slice.
Best when the team needs momentum now, but still wants a real vertical slice that can survive review.
- Operating posture
- Cut breadth and polish. Keep real behavior, explicit effects, and focused proof.
- Proof shape
- Focused tests, targeted browser QA, and a hardening backlog.
Velocity
Move larger slices through review.
Best when the direction is clear and the repo can absorb faster coordinated implementation.
- Operating posture
- Use bigger work packages, focused checks, and periodic full gates.
- Proof shape
- Focused tests plus build checks at the right cadence.
Strict
Add gates for high-risk work.
Best when the cost of a wrong change is higher than the cost of moving carefully.
- Operating posture
- Use smaller work packages, deeper review, and full verification gates.
- Proof shape
- Full gates, fuller review, and explicit acceptance evidence.
Release
Prepare the repo to ship.
Best when the question is no longer what to build, but whether the work is ready to declare done.
- Operating posture
- Freeze scope, verify release criteria, archive evidence, and surface residual risk.
- Proof shape
- Release gate, adversarial review, and complete ship-readiness record.
Recovery
Reconcile messy state safely.
Best when the project needs control restored before another agent starts editing.
- Operating posture
- Stop the confusion first. Inspect, preserve, route, and resume only when state is clear.
- Proof shape
- Targeted/full checks as needed, plus a precise recovery handoff.
The skill seeds project records, not ceremony.
The generated files explain ownership, checks, handoff shape, review status, and stop/resume behavior. They are readable in the repo and useful even outside the Codex app.
AGENTS.mdseeded by software-factory
The repo-level operating contract.
Shared rules for every agent that enters the project.
# Project Agent Rules
- Preserve user changes. Never revert unknown work.
- Keep one active writer in the main worktree by default.
- Treat external effects as explicit operator actions.
- Record proof commands and residual risk before declaring done.
- Use the factory docs as the routing source of truth.factory_config.mdseeded by software-factory
Editable factory settings.
Mode, review posture, permissions, stop rules, and verification cadence.
work_mode: balanced
user_involvement: principal_partner
concurrency_policy: single_writer
verification_level: focused_plus_build
reviewer_policy: risk_triggered
default_stop_mode: drain_to_checkpoint
external_effect_policy: explicit_operatorbuild_ledger.mdseeded by software-factory
The durable project record.
What changed, what passed, who owns the next step, and what remains risky.
## Current State
status: running
active_owner: builder-thread
current_slice: install flow and landing shell
accepted_evidence:
- npm run typecheck
- npm run build
- browser smoke on desktop and mobile
next_action: review generated asset integrationhandoff_protocol.mdseeded by software-factory
A reliable handoff shape.
A scoped work package with enough evidence for review or resume.
## Handoff Bundle
objective:
write_scope:
non_goals:
files_changed:
proof_commands:
known_risks:
recommended_next_action:
stop_or_resume_notes:review_index.mdseeded by software-factory
Review state without transcript archaeology.
A small index of what was reviewed, accepted, deferred, or blocked.
## Review Index
| Slice | Reviewer | Result | Evidence |
| --- | --- | --- | --- |
| landing shell | reviewer-thread | accepted | build, browser smoke |
| install copy | reviewer-thread | accepted | source readback |
| mode graphics | pending | needs visual QA | desktop/mobile screenshots |Docs-first when you want portability.
Use Software Factory when you want a lightweight protocol that lives with the codebase. Use Agentic Factory when you want SQLite-backed state, CLI controls, durable event history, verification records, and a larger control plane.
Software Factory
Portable skill, seeded docs, mode presets, handoff templates.
Agentic Factory
DB-backed plugin, CLI control plane, event and review records.
Install globally for Codex.
Add the skill, restart Codex, then invoke it directly from your project thread.
Codex install
npx skills add jddelia/software-factory \
--agent codex \
--global \
--yesPreview, telemetry-off, and manual install options
Codex install
npx skills add jddelia/software-factory \
--listCodex install
DISABLE_TELEMETRY=1 npx skills add jddelia/software-factory \
--agent codex \
--global \
--yesCodex install
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/jddelia/software-factory.git \
"${CODEX_HOME:-$HOME/.codex}/skills/software-factory"