How phax works#

#Concepts

Spec and plan. A spec says what to build and why: requirements, acceptance criteria, and the questions still open. A plan says how: an ordered list of phases, each with its instructions, the files it will create and edit, the gate it must pass and its commit message. Both are Markdown files with a status in their frontmatter, under docs/specs/ and docs/plans/. phax calls them artifacts.

Lifecycle. An artifact moves through statuses: Draft → Approved → Completed, or Abandoned if the work is dropped. A plan can also be marked Stale when the ground it was approved on has changed (phax plans status tells you). phax artifact makes every transition and commits it; an approval records what the artifact was approved against, so phax can tell later whether it still holds. A run completes its plan, and its spec where it can, on the run's own branch, so the merge lands the code and the completion together.

Run and phase. phax run turns an approved plan into a run, named from the plan's title as <namespace>.<name>, where the namespace is your project's name in phax.json. Each phase runs in its own Git worktree on its own branch, phax/<name>--phase-NN, branched from the previous phase, so the last phase's branch carries the whole change.

Gate. Your project's checks, declared once in phax.json as a gate profile. A step runs at every phase (every-phase) or only at the last one (terminal), and records what it verifies (local, structural or product). When a gate fails, the same agent session gets the failure and tries to fix it before the phase gives up.

Handoff and reconciliation. After its gate passes, each phase writes a handoff for the next one: what it did, what it decided, what is left. phax compares the files the phase actually changed with the files it planned, and every gap goes into the next phase's prompt and into the final review.

Review. The last phase does not land anything. The run stops at review_open, with a review handoff, an optional compliance review of the work against the plan, and optionally a pull request. You take it from there.

Records. If you turn them on (phax records init), every phase leaves a record on the phax/records/v1 branch — its manifest, gate results, reconciliation, diff, handoff and, optionally, the agent's transcript — so a run's history outlives its worktrees.

State. phax keeps its own state outside your repository, under ~/.phax/: the registry of runs, each run's folder, the worktrees, the locks. Your repository only holds the artifacts, and the records branch if you use one.