Getting started

Install, then prove one slice.

Software Factory works best when the first run is narrow, explicit, and tied to proof the next thread can inspect.

Codex install

npx skills add jddelia/software-factory \
  --agent codex \
  --global \
  --yes

The first run should create control, not ceremony.

These steps keep the factory grounded in the repo and prevent the first session from expanding before the evidence standard is clear.

Install the skill

Install globally for Codex so the skill is available from any project thread.

Use the primary Codex install command and restart Codex after installation.

Open a project thread

Start from the repo where the factory records should live.

The skill is most useful when the docs sit beside the code they govern.

Choose a mode

Pick Safe MVP, Velocity, Strict, Release, or Recovery based on risk.

Start smaller than you think. You can raise the verification posture later.

Set scope and proof

Tell Codex what it may edit, what is out of scope, and how done will be proven.

This prevents a confident status update from replacing actual evidence.

Review the record

Use the seeded files to inspect ownership, checks, blockers, and next action.

A restarted thread should be able to recover without transcript archaeology.

A good first prompt is boring in the right ways.

It names the mode, objective, write scope, non-goals, and proof. That is enough to let Codex plan without guessing at your tolerance for risk.

Use the software-factory skill in Safe MVP mode.

Objective: build the smallest real slice of <feature or workflow>.
Write scope: <files or directories Codex may edit>.
Non-goals: <what should not change>.
Proof required: <typecheck/build/tests/browser QA>.

Before editing, create or update the factory project records and confirm the plan.

Install options.

The primary path is the global Codex install. Preview detection and telemetry opt-out commands are available when you want extra control.

Codex install

npx skills add jddelia/software-factory \
  --agent codex \
  --global \
  --yes

Codex install

npx skills add jddelia/software-factory \
  --list

Codex install

DISABLE_TELEMETRY=1 npx skills add jddelia/software-factory \
  --agent codex \
  --global \
  --yes

Codex install

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/jddelia/software-factory.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/software-factory"

Expect project records.

The first useful sign is not a flurry of edits. It is a repo-local record that explains ownership, scope, checks, blockers, and next action.

Accept evidence, not confidence.

A factory run is complete when its proof is inspectable. The status update should point at commands, screenshots, logs, or review notes.