#phax

• version: 0.18.0

Drive AI Coding agent through isolated, gated phases

• Usage: phax [FLAGS] <SUBCOMMAND>

#Global Flags

#--verbose

Print human-readable progress and system events

#--trace

Write structured JSONL trace events to the run folder

#--usage

Print the phax.usage.kdl CLI spec and exit

#--usage-format <format>

Format for --usage output: kdl (default, no external dependency) or json (requires the usage CLI)

Default: kdl

#phax validate

• Usage: phax validate [--plan <path>]

Validate phax.json and its user overlays without any side effects; pass --plan to also validate a phax-plan.json

#Flags

#--plan <path>

Also validate a phax-plan.json at this path

#phax unlock

• Usage: phax unlock [--force] <short-name>

Remove a stale run lock; use --force to remove any lock

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#--force

Remove the lock regardless of staleness

#phax enter

• Usage: phax enter <short-name>

Attaches to the kept-open agent session in the final worktree, so you can review the agent's work, ask follow-up questions, or apply manual fixes interactively.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax enter usage-cli

#phax enter-phase

• Usage: phax enter-phase <short-name> <phase-id>

Attaches to the agent session for a specific phase worktree. Useful for inspecting intermediate state or debugging a phase that has not yet been committed to main.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#<phase-id>

Phase identifier, e.g. phase-02

#Examples

phax enter-phase usage-cli phase-02

#phax session-info

• Usage: phax session-info [--debug] <short-name>

Prints diagnostic information about a run: its current state, active phase, worktree path, and agent session id. Read-only — no side effects.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#--debug

Dump raw binding and model-resolution metadata

#Examples

phax session-info usage-cli

phax session-info usage-cli --debug

#phax shell

• Usage: phax shell <short-name>

Opens an interactive shell in the final worktree. Useful for manually inspecting files, running tests, or executing commands outside the agent session.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax shell usage-cli

#phax path

• Usage: phax path <short-name>

Prints the absolute path to the final worktree on a single line. Useful in scripts: cd $(phax path my-run) or for piping to other tools.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax path usage-cli

cd $(phax path usage-cli)

#phax open

• Usage: phax open <short-name>

Opens the final worktree in the editor configured in phax.json (or the EDITOR environment variable). Equivalent to running your editor with the worktree path as an argument.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax open usage-cli

#phax ls

• Usage: phax ls [FLAGS]

Lists runs from the local registry (~/.phax/runs/). With no filter flags, shows all runs. Use status filters to narrow output: --active (created or running), --failed, --review-open (awaiting human review), or --archived. Use --json for machine-readable output.

#Flags

#--active

Show only active runs (created or running)

#--failed

Show only failed runs

#--review-open

Show only review_open runs

#--archived

Show only archived runs

#--json

Output as JSON

#--complete

Print run short-names for shell completion

#Examples

phax ls

phax ls --review-open

phax ls --failed --json

#phax archive

• Usage: phax archive [--force] <short-name>

Archives a run by moving its worktrees under ~/.phax/archive/<namespace>.<short-name>/ and marking it archived in the registry. Nothing is destructively deleted — every phase's working state is preserved.

Finished runs (review_open, completed) archive by default. Unfinished runs (created, failed, interrupted, rate_limited, stopped) are refused unless --force is set; the refusal message names the run's current state and the flag. Running, locked, and already-archived runs are never archivable regardless of --force.

The run's stoppedReason and lastError survive archival intact.

Without --force on a finished run, the final worktree must be clean. With --force, no cleanliness check runs.

Side effects: moves worktrees on the filesystem, updates ~/.phax/runs/.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#--force

Archive even if the run is unfinished or a worktree has uncommitted changes

#Examples

phax archive usage-cli

phax archive usage-cli --force

phax archive plan-27 --force  # give up an interrupted run

#phax prune

• Usage: phax prune [FLAGS] [short-name]…

Deletes each selected archived run of the current namespace for real: its archive folder under ~/.phax/archive/<namespace>.<short-name>/, its worktree metadata in the current repository, its local branches (<branch> and <branch>--phase-NN) and, last, its registry entry — so its name and disk space come back. Select runs by name (short or <namespace>.<short-name>) or with --all; only archived runs of the current namespace can be pruned, and an unknown, non-archived or other-namespace name refuses the whole command. Never touches records on phax/records/v1, remote branches, remote-tracking refs or pull requests, and never contacts a remote.

A run whose local branches hold commits that no other branch, tag or remote-tracking ref keeps is kept whole unless --force is set, which discards those commits. A branch checked out in a worktree keeps the run even with --force. A locked run refuses the whole command (exit 7).

Always prints a preview first, then asks for confirmation on a TTY; --yes proceeds without asking, --dry-run deletes nothing, and without a TTY the command refuses unless --yes or --dry-run is set. --json prints one JSON document and never prompts. Exits 0 when every selected run was pruned, 1 when nothing was deleted, 3 when at least one run was kept.

Side effects: deletes under ~/.phax/archive/, deletes local branches and stale worktree metadata, updates ~/.phax/registry.json.

#Arguments

#[short-name]…

Archived run short name, e.g. old-idea

#Flags

#--all

Prune every archived run of the current namespace

#--force

Also prune runs whose branches hold unpreserved commits (discards those commits)

#--dry-run

Print the preview and delete nothing

#-y --yes

Proceed without confirmation (required without a TTY)

#--json

Output as JSON; never prompts

#Examples

phax prune old-idea

phax prune --all --dry-run

phax prune --all --yes

#phax run

• Usage: phax run <FLAGS> [short-name]

Extracts a plan from the plan.md given by --plan, creates a run entry in the registry, and executes each phase sequentially in its own Git worktree using the configured AI agent. Each phase runs its gate profile's every-phase steps after execution; the final phase also runs the profile's terminal steps. Each step's surface (local, structural, or product) is recorded per phase and the run's verified surfaces are reported at run end.

Extraction results are cached by content hash under ~/.phax/cache/plans/; a repeated run of the same plan.md reuses the cached extraction without calling the LLM again. Use --refresh to force a fresh extraction.

Side effects: creates worktrees, commits files, writes to ~/.phax/runs/.

#Arguments

#[short-name]

Run short name, e.g. usage-cli

#Flags

#--plan <path>

Path to the plan.md file to extract from

#--allow-dirty

Allow starting when the working tree is dirty

#--provider-priority <list>

Comma-separated provider priority override (e.g. mistral-vibe,claude-code)

#--dry-run

Preview only — extracts the plan but performs no run actions

#--security <mode>

Security mode override (secure|unsafe|isolated, overrides config default)

#--refresh

Re-extract the plan even if a cached extraction exists

#--allow-skill-edits

Allow phases to edit the .claude/skills files the plan declares

#Examples

phax run --plan plan.md

phax run my-feature --plan plan.md

phax run --plan plan.md --dry-run

phax run --plan plan.md --refresh

#phax review-handoff

• Usage: phax review-handoff [--allow-partial] <short-name>

Regenerate review-handoff.md and global file reconciliation for a review_open run

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#--allow-partial

Generate a partial document when some phase artifacts are missing

#phax publish-pr

• Usage: phax publish-pr <short-name>

Pushes the final worktree branch to the GitHub remote and creates a pull request, or reuses an existing PR for the same branch. Requires a GitHub remote and gh CLI authentication.

Side effects: git push to remote, GitHub API call to create or update a pull request.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax publish-pr usage-cli

#phax review-compliance

• Usage: phax review-compliance <short-name>

Runs a non-mutating plan-compliance review by invoking the AI agent with the run's handoff artifacts and the original plan. Does not modify the worktree, registry, or any files.

Side effects: spawns a short-lived AI agent session (network I/O); no filesystem mutations.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Examples

phax review-compliance usage-cli

#phax review-code

• Usage: phax review-code [FLAGS] <short-name>

Opens an interactive, pre-prompted code-review session for a review_open run by launching the AI agent in the run's worktree with the code-review prompt. The session is resumable: re-running resumes the existing session, while --new-session starts fresh. The developer takes over the session to investigate, discuss, and apply fixes.

Side effects: writes a code-review prompt file under the worktree's .phax-context/ and a session record under the run directory; spawns a long-lived interactive AI agent session (network I/O).

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#--new-session

Start a fresh review session instead of resuming the existing one

#--model <model>

Override the model, including on resume (default: review.code.model, else claude-opus-5-5)

#--effort <effort>

Override the effort (low | medium | high), including on resume (default: review.code.effort, else high)

#Examples

phax review-code usage-cli

#phax adjust-plan

• Usage: phax adjust-plan <FLAGS> <plan>

Opens an interactive, pre-prompted session to help you adjust a plan.md after a landed run has introduced drift. The session establishes which of the plan's declared files, line references, and decisions are invalidated by the landed run's actual changes, asks clarifying questions where needed, proposes concrete edits and waits for your explicit approval, and only then edits and commits the plan — all interactively within the session. The command itself mutates nothing.

Input: the path to the plan.md to adjust and --landed <run> (the run whose actual changes drive the adjustment). The landed run must have a global-file-reconciliation.json (i.e. it must have reached review). Re-invocation without --new-session resumes the same session; --new-session starts a fresh one.

Side effects: spawns a long-lived interactive provider session (network I/O); the session may, after developer approval, edit and commit the plan.md.

#Arguments

#<plan>

Path to the plan.md to adjust

#Flags

#--landed <run>

The landed run whose actual changes drive the adjustment

#--new-session

Start a fresh adjustment session instead of resuming

#--model <model>

Override the model (default: claude-opus-5-5)

#--effort <effort>

Override the effort (low | medium | high)

#Examples

phax adjust-plan docs/plans/2609101030-plan-prune-plan.md --landed my-feature

#phax init

• Usage: phax init [--force] [--yes]

Creates phax.json and phax.schema.json in the current directory. Use --force to overwrite an existing phax.json. Does not connect to any network or external service.

#Flags

#--force

Overwrite and reconfigure an existing phax.json

#--yes

Accept detected defaults without prompting

#Examples

phax init

phax init --force

#phax report

• Usage: phax report [--no-gist] [short-name]

Creates a GitHub issue from local run telemetry. By default, uploads the full log as a secret GitHub gist and links it in the issue body. Use --no-gist to inline the log directly.

Side effects: GitHub API calls — creates a GitHub issue and, unless --no-gist is set, a secret gist.

#Arguments

#[short-name]

Run short name, e.g. usage-cli

#Flags

#--no-gist

Inline the full log in the issue body instead of creating a secret gist

#Examples

phax report

phax report usage-cli

phax report usage-cli --no-gist

#phax orient

• Usage: phax orient [--file <path>] [id]

Requires an orient provider in phax.json:

"orient": { "command": "node ./orient.mjs" }

phax runs the command with no shell — the string is split on whitespace, so use a wrapper script for pipelines or paths with spaces — from the current directory (the phase worktree during a run), writes one JSON request on stdin and expects exit code 0 and one JSON response on stdout.

Index request {"files": ["src/a.ts", "src/b.ts"]} Index response {"rows": [{"id": "...", "title": "...", "severity": "error"|"warn"|"info", "trigger": "..."}]}

Expand request {"expand": "<id>"} Expand response {"row": {"id", "title", "severity", "trigger", "body"}} or {"row": null} when the id is unknown

All fields are non-empty strings. A non-zero exit, non-JSON stdout or a response that fails validation is reported as a provider error (exit 1); an empty index or a null row prints "No orientation available." and exits 0.

During a run phax sends the index request for each phase's planned files and weaves the rows into the phase prompt. When orient is configured, phax orient is allowed to the in-phase agent without an explicit agentCommands grant.

#Arguments

#[id]

Row id to expand

#Flags

#--file <path>

Return an index for an arbitrary file instead of expanding a row id

#Examples

phax orient core-no-adapters

phax orient --file src/jobs/sync.ts

#phax completions

• Usage: phax completions <shell>

Generate a shell completion script (zsh, bash, fish, nu, powershell). Requires the usage CLI.

#Arguments

#<shell>

Shell to generate completions for (zsh, bash, fish, nu, powershell)

#phax resume

• Usage: phax resume [FLAGS] <short-name>

Picks up a run from its next pending phase, re-entering the same execution loop as phax run. Prompts for confirmation before proceeding unless --yes is set.

Side effects: creates worktrees, commits files, writes to ~/.phax/runs/.

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#Flags

#-y --yes

Proceed without confirmation

#--verbose

Print human-readable progress and system events

#--trace

Write structured JSONL trace events to the run folder

#--provider-priority <list>

Comma-separated provider priority override (e.g. mistral-vibe,claude-code)

#Examples

phax resume usage-cli

phax resume usage-cli --yes

#phax reset-phase

• Usage: phax reset-phase [FLAGS] <short-name> [phase-id]

Reset a stuck or failed phase so phax resume re-runs it from scratch

#Arguments

#<short-name>

Run short name, e.g. usage-cli

#[phase-id]

Phase identifier to reset, e.g. phase-02; defaults to the stuck phase

#Flags

#-y --yes

Proceed without confirmation (removes the worktree and branch)

#--verbose

Print human-readable progress and system events

#--trace

Write structured JSONL trace events to the run folder

#phax agent

• Usage: phax agent <SUBCOMMAND>

Inspect and manage model routing and provider configuration

#phax agent models

• Usage: phax agent models

Print the routing table and provider priority

#phax agent resolve

• Usage: phax agent resolve <FLAGS>

Show how a model+effort request resolves to a provider and concrete model

#Flags

#--model <id>

Requested model id (e.g. claude-sonnet-4-6)

#--effort <level>

Effort/thinking level (none|off|low|medium|high|xhigh|max|ultracode|ultra)

#--json

Output the resolution as JSON

#phax agent probe

• Usage: phax agent probe

Check which provider executables are available on PATH; never throws on an unavailable provider

#phax agent setup

• Usage: phax agent setup <SUBCOMMAND>

Set up provider integrations

#phax agent setup mistral-vibe

• Usage: phax agent setup mistral-vibe [--dry-run] [--install-model-aliases]

Append PHAX-owned Mistral Vibe model aliases to ~/.vibe/config.toml (append-only, atomic)

#Flags

#--dry-run

Preview what would be appended without writing anything

#--install-model-aliases

Actually append the missing aliases and write the backup

#phax agent setup providers

• Usage: phax agent setup providers [FLAGS]

Reconcile ~/.phax/providers.json enabled flags from live executable probes (dry-run by default)

#Flags

#--write

Persist the reconciled config (writes a timestamped backup first)

#--prune

Also disable providers whose executable is unavailable

#--with-routing

Scaffold ~/.phax/model-routing.json from defaults when absent (never overwrites)

#phax security

• Usage: phax security [--verbose] [--trace] <SUBCOMMAND>

Security-related commands

#Flags

#--verbose

Print human-readable progress and system events

#--trace

Write structured JSONL trace events to the run folder

#phax security status

• Usage: phax security status [--verbose] [--trace]

Show provider security capabilities and availability

#Flags

#--verbose

Print human-readable progress and system events

#--trace

Write structured JSONL trace events to the run folder

#phax skills

• Usage: phax skills <SUBCOMMAND>

Manage PHAX skills

#phax skills install

• Usage: phax skills install <--target <target>> [--scope <scope>] [skill]

Install bundled PHAX skills into an agent's native skill directory

#Arguments

#[skill]

Skill to install (phax-planning|phax-cli|phax-spec); installs all skills when omitted

#Flags

#--target <target>

Agent target (claude|codex|agent)

#--scope <scope>

Installation scope (project|user)

Default: project

#phax schema

• Usage: phax schema <SUBCOMMAND>

Manage the local phax.schema.json

#phax schema upgrade

• Usage: phax schema upgrade

Regenerate phax.schema.json from the installed binary's config contract; never modifies phax.json

#phax artifact

• Usage: phax artifact <SUBCOMMAND>

Parent command for inspecting and transitioning the lifecycle status of a spec (docs/specs/) or plan (docs/plans/). Specs carry Draft, Approved, Abandoned, or Completed; plans additionally carry Stale. Transitioning to a terminal status (Abandoned, Completed) moves the file into the artifact's archive/ subdirectory as part of the transition. A headless-authored artifact's JSON document sidecar (<name>.json beside the .md) travels with it: every transition's write-set includes it, and a terminal transition moves it into archive/ alongside the .md. Illegal transitions and validation failures (missing frontmatter block, unknown status, status/location disagreement) refuse with exit code 12.

#Examples

phax artifact status docs/plans/2607101056-typescript-7-migration-plan.md

#phax artifact status

• Usage: phax artifact status <path>

Reports an artifact's kind (spec or plan), current status, and the legal transitions from that status. For Approved specs, also reports the approval date and baseline, and whether the spec has been edited since that approval (recorded) or has no approval record (unrecorded). Also reports how the artifact was authored: interactive (no sidecar), or headless with its JSON document sidecar and whether the body is still the sidecar's rendering (in sync), differs from it (diverged — the body was edited by hand), or the sidecar is not a valid document (invalid). Frontmatter changes never count as divergence. Read-only — no side effects.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact status docs/plans/2607101056-typescript-7-migration-plan.md

phax artifact status docs/specs/2609030749-spec-approval-ground.md

#phax artifact approve

• Usage: phax artifact approve <path>

Transitions an artifact to Approved. Legal from Draft (both kinds) and from Stale (plans only); re-approving an already-Approved artifact re-records the approval, refreshing its timestamp and baseline — this is the correct way to record an in-place revision of a spec, not editing the date by hand. Rewrites the frontmatter status key in place.

For specs: stamps approved: { date, baseline } in the frontmatter and writes a record to docs/specs/approvals.json. For plans: stamps approved: { date, baseline } in the frontmatter and writes a record to docs/plans/approvals.json. Plan approval refuses with exit 12 if the declared Source-Spec is Approved but its approval is unrecorded or edited since approval — re-approve the spec first. For headless-authored artifacts (either kind): approval refuses with exit 12 when the JSON document sidecar is diverged (the body differs from the sidecar's rendering) or invalid, naming the two remedies — re-author the artifact with --headless, or delete the sidecar to demote the artifact to hand-authored.

Side effects: writes the artifact file and commits the transition's write-set (the artifact file, its JSON document sidecar when headless-authored, plus the approval record) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact approve docs/plans/2607101056-typescript-7-migration-plan.md

phax artifact approve docs/specs/2609030749-spec-approval-ground.md

#phax artifact stale

• Usage: phax artifact stale <path>

Manually marks a plan Stale. Legal from Approved only — Stale has no automatic trigger (that belongs to a future lineage spec). Rewrites the frontmatter status key in place.

Side effects: writes the plan file and commits the write-set in a single commit; refuses with exit code 12 if the plan file already has uncommitted changes.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact stale docs/plans/2607101056-typescript-7-migration-plan.md

#phax artifact abandon

• Usage: phax artifact abandon <path>

Abandons an artifact — a terminal status distinct from Completed, for work dropped without execution. Legal from Draft or Approved (specs) or Draft, Approved, or Stale (plans).

Side effects: moves the file into the artifact's archive/ subdirectory with its frontmatter status key rewritten to Abandoned and commits the move (and, for plans, the approval-record removal) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact abandon docs/plans/2607101056-typescript-7-migration-plan.md

#phax artifact complete

• Usage: phax artifact complete <path>

Completes an artifact — a terminal status for work that ran to completion. Legal from Approved (specs) or Approved or Stale (plans).

Side effects: moves the file into the artifact's archive/ subdirectory with its frontmatter status key rewritten to Completed and commits the move (and, for plans, the approval-record removal) in a single commit; refuses with exit code 12 if any write-set path already has uncommitted changes.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact complete docs/specs/2608091526-artifact-lifecycle-status.md

#phax artifact reopen

• Usage: phax artifact reopen <path>

Reopens a Stale plan back to Draft, for when re-planning is needed before re-approval. Legal from Stale only. Rewrites the frontmatter status key in place.

Side effects: writes the plan file and commits the write-set in a single commit; refuses with exit code 12 if the plan file already has uncommitted changes.

#Arguments

#<path>

Path to a spec or plan file under docs/specs/ or docs/plans/

#Examples

phax artifact reopen docs/plans/2607101056-typescript-7-migration-plan.md

#phax artifact new

• Usage: phax artifact new <SUBCOMMAND>

Parent command for creating a Draft spec or plan named from the current UTC minute: <YYMMDDHHMM>-<slug>.md for a spec, <YYMMDDHHMM>-<slug>-plan.md for a plan. The instant is captured when the command runs, never chosen or backdated. A bad slug, an existing target name, or (for a plan) a --spec that is missing or not a spec all refuse with exit code 12 before anything is written.

#Examples

phax artifact new spec plan-prune

#phax artifact new spec

• Usage: phax artifact new spec [FLAGS] <slug>

Creates a Draft spec at docs/specs/<YYMMDDHHMM>-<slug>.md, with a frontmatter-only skeleton (status, date, audience, scope). The slug must match [a-z0-9]+(-[a-z0-9]+)*.

Side effects: writes the new spec file. Does not commit — transition commands (phax artifact approve) commit, creation does not.

Pass --headless --brief <file|-> (experimental) to author the spec itself instead of writing a blank skeleton: phax spawns a recorded agent session with the phax-spec skill and the spec document JSON Schema, accepts a schema-valid document as the session's only output, renders it to the canonical Markdown, and writes the rendered spec plus its JSON sidecar. --model and --effort override the resolved authoring model/effort (flag, then phax.json's authoring.spec, then the catalog default). Side effects: spawns a provider session; on success, writes and commits the spec and its sidecar in one commit; nothing lands on a refusal or an invalid session result. When records are configured, every session that ran — committed or failed — writes one authoring record (key authoring/<YYMMDDHHMM>-<slug>) on phax/records/v1, and phax records explain <commit> resolves it through the artifact commit's Authoring-Id trailer.

#Arguments

#<slug>

Slug matching [a-z0-9]+(-[a-z0-9]+)*

#Flags

#--headless

Author via a recorded agent session from a brief instead of a blank skeleton (experimental)

#--brief <file|->

Path to a brief file, or - to read the brief from stdin

#--model <model>

Override the authoring model (default: flag → config → catalog)

#--effort <effort>

Override the authoring effort (low|medium|high)

#Examples

phax artifact new spec plan-prune

phax artifact new spec plan-prune --headless --brief brief.md

#phax artifact new plan

• Usage: phax artifact new plan [FLAGS] <slug>

Creates a Draft plan at docs/plans/<YYMMDDHHMM>-<slug>-plan.md, with a frontmatter-only skeleton (status, source-spec). Pass --spec <path> to bind an existing spec as the plan's source-spec; the path must classify as a spec (live or archived), exist, and pass artifact validation. Without --spec, source-spec is written as null. The slug must match [a-z0-9]+(-[a-z0-9]+)*.

Side effects: writes the new plan file. Does not commit — transition commands (phax artifact approve) commit, creation does not.

Pass --headless --brief <file|-> (experimental) to author the plan itself instead of writing a blank skeleton: phax spawns a recorded agent session with the phax-planning skill and the plan document JSON Schema (the extracted-plan shape plus informational content), accepts a schema-valid document as the session's only output, renders it to the phax-planning Markdown shape, writes the rendered plan plus its JSON sidecar, and seeds the extraction cache so phax run never re-extracts it. --model and --effort override the resolved authoring model/effort (flag, then phax.json's authoring.plan, then the catalog default). Side effects: spawns a provider session; on success, writes and commits the plan and its sidecar in one commit and seeds the extraction cache; nothing lands on a refusal or an invalid session result. When records are configured, every session that ran — committed or failed — writes one authoring record (key authoring/<YYMMDDHHMM>-<slug>) on phax/records/v1, and phax records explain <commit> resolves it through the artifact commit's Authoring-Id trailer.

#Arguments

#<slug>

Slug matching [a-z0-9]+(-[a-z0-9]+)*

#Flags

#--spec <path>

Path to the source spec to bind as source-spec

#--headless

Author via a recorded agent session from a brief instead of a blank skeleton (experimental)

#--brief <file|->

Path to a brief file, or - to read the brief from stdin

#--model <model>

Override the authoring model (default: flag → config → catalog)

#--effort <effort>

Override the authoring effort (low|medium|high)

#Examples

phax artifact new plan plan-prune --spec docs/specs/2609091412-plan-prune.md

phax artifact new plan catalog-refresh

phax artifact new plan plan-prune --headless --brief brief.md --spec docs/specs/2609091412-plan-prune.md

#phax artifact schema

• Usage: phax artifact schema <kind>

Prints the JSON Schema of the experimental spec document (kind spec) or plan document (kind plan), pretty-printed to stdout, so a consumer can read the contract a headless authoring session must satisfy without a model call.

Both formats are experimental: outside the version 1 stability promise, they may change between releases, and each schema is titled accordingly. The plan document's extracted fields are the extracted-plan shape phax run reads. The spec document additionally requires traceability — every acceptance criterion references existing requirements, every requirement is covered, every open question has two or more options and a recommendation among them — which the JSON Schema does not express and phax checks when it decodes a document.

Side effects: none — read-only.

#Arguments

#<kind>

Document kind: spec or plan

#Examples

phax artifact schema spec

phax artifact schema plan

#phax plans

• Usage: phax plans <SUBCOMMAND>

Parent command for reporting on plans: the mechanical defects of a single plan (lint), staleness of Approved plans against their recorded approval, and cross-plan file overlap.

#Examples

phax plans lint docs/plans/2609101200-foo-plan.md

phax plans status

phax plans overlap docs/plans/2609101031-a-plan.md docs/plans/2609101032-b-plan.md

#phax plans status

• Usage: phax plans status [--apply] [--json]

Reports every live, Approved plan's staleness against the ground it was approved against: the declared source spec's content, the plan's own content, and the files changed since the recorded baseline intersected with the plan's footprint. Each stale entry names its reasons (spec-changed, ground-changed, self-changed) with evidence; a plan with no approval record — or one whose baseline commit no longer exists — reports missing-record, which renders as stale. This is a report, not a gate: it exits 0 whether or not stale plans exist. Use --apply to flip stale-computed plans Approved -> Stale as an explicit gesture (the flip is never automatic). Use --json for machine-readable output.

Side effects: read-only unless --apply is set, in which case it writes the flipped plans' frontmatter status key.

#Flags

#--apply

Flip stale-computed plans Approved -> Stale

#--json

Emit the report as JSON instead of a rendered table

#Examples

phax plans status

phax plans status --apply

phax plans status --json

#phax plans overlap

• Usage: phax plans overlap [FLAGS] <plan>…

Reports which of two or more plans can run in parallel without a merge conflict — predicted from each plan's declared file-sets, or confirmed against a landed run's actual diff.

(Predicted) Without --landed: reads each plan.md's structured form through the content-addressed extraction cache (a cold cache miss extracts once via LLM and caches the result; use --no-extract to fail on a miss instead). Unions each plan's declared phase file-sets into a per-plan footprint, intersects footprints pairwise, and reports the severity-graded conflict matrix, clean pairs, the largest fully-disjoint parallel-safe set, and a greedy wave schedule.

(Confirmed) With --landed <run>: takes a run that has already produced changes and reports which of the given plans need re-adjustment because they touch a file the run actually changed. The landed run's footprint is read from its persisted global-file-reconciliation.json (the real git diff across its phases), giving actual-vs-declared impact with no false negatives.

Caveats: the predicted mode reflects declared file intentions, not what agents will actually touch. Conflicts are file-level, not hunk-level — two plans editing different regions of the same file are flagged even if git would auto-merge them. Regenerated artifacts (phax.usage.kdl, docs/cli/reference.md) are a hard-conflict class.

Side effects: read-only with respect to your plans; may run one LLM extraction per uncached plan.md.

#Arguments

#<plan>…

Paths to two or more plan.md files

#Flags

#--json

Emit the overlap result as JSON instead of a report

#--no-extract

Fail on a cache miss instead of extracting the plan.md

#--landed <run>

Report which of the given plans need re-adjustment after this run's actual changes

#Examples

phax plans overlap docs/plans/2609101031-a-plan.md docs/plans/2609101032-b-plan.md

phax plans overlap --landed my-feature docs/plans/2609101033-other-plan.md

#phax plans lint

• Usage: phax plans lint [--json] <plan>

Reports every mechanical defect of a plan.md that phax can establish before a run, as findings with a severity (error or warning), a check, and the phase they concern.

Five checks run: structure — every field the deterministic extraction requires, reported in full rather than stopping at the first; files — the planned create/edit lists walked in phase order against the working tree, so an edit of a file no earlier phase creates, a create of a file that already exists or was already created, and a phase that both creates and edits a path are errors (a path listed both to create and as optional is the one warning; optional files are never checked); commands — the plan's required commands against security.agentCommands and the gate profile; models — each phase's model and effort against the routing catalog, with alternatives when one is refused; advisory — when phax.json registers a planAuditor, phax writes the plan projection (the ordered phases, each with its planned create/edit files, and nothing else) to that command's stdin and reports every finding it returns as a warning naming the phases it concerns; a failing auditor is a single warning, and so is one that outruns the 30s cap phax spawns it under; with no auditor, or a plan the parser cannot read, there are no advisory findings. Advisory findings never affect the exit code.

A plan under docs/plans/ is first validated like any artifact (a name off <YYMMDDHHMM>-<slug>-plan.md, an invalid frontmatter block or a status/location disagreement refuses with exit code 12), and a slug that differs from its source spec's slug is a structure error; a loose plan.md outside docs/plans/ is exempt from both.

The file-plan ground is the working tree as it is now, not any commit. Read-only and model-free: it never writes, never reads the extraction cache and never falls back to the extraction model, so a plan the deterministic parser cannot read reports its structural errors and stops. Exits 1 when at least one finding is an error, 0 otherwise (warnings alone do not fail).

Side effects: none of phax's own; a registered plan auditor is spawned once with the projection on stdin, capped at 30s.

#Arguments

#<plan>

Path to the plan.md

#Flags

#--json

Emit the findings as JSON

#Examples

phax plans lint docs/plans/2609101200-foo-plan.md

phax plans lint docs/plans/2609101200-foo-plan.md --json

#phax records

• Usage: phax records <SUBCOMMAND>

Manage phax run records

#phax records init

• Usage: phax records init [--force]

Configure records for this project (transcript, destination, auto-push)

#Flags

#--force

Reconfigure records even if already configured

#phax records sync

• Usage: phax records sync

Bring the local records clone in line with its configured remote

#phax records status

• Usage: phax records status

Show pending (unpushed) records, by run and phase

#phax records list

• Usage: phax records list [--run <id>]

List records present: phase records by run, phase, and verified surfaces; authoring records by id and artifact

#Flags

#--run <id>

Only show records for this run id

#phax records explain

• Usage: phax records explain [FLAGS] <sha>

Explain a commit from its record: prompt, diff, gates and verified surfaces, handoff, transcript, usage — or, for a headless artifact commit, its authoring record

#Arguments

#<sha>

Commit sha in the source repository (a phase commit or an artifact commit)

#Flags

#--prompt

Print the full prompt

#--diff

Print the full diff

#--transcript

Print the full transcript

#--gates

Print the gate check logs