Writing a plan#

#Write a plan

Create the plan file with phax artifact new plan <slug> --spec <spec path> (or without --spec when there is no source spec), then fill it in. Author plan.md with the phax-planning skill — it is the source of truth for the plan format that phax run extracts and phax plans lint checks. The skill defines the per-phase template contract (heading + {#phase-NN-<slug>} anchor, recommended model/effort, the three planned-file lists, gate-profile verification, commit subject/body) and the planning doctrine (plan outside-in, implement inside-out, verify outside-in). Point your agent at that skill when drafting or reviewing a plan; don't hand-roll the format.

In short: plan.md is a Markdown document with one ## phase-NN — <title> {#phase-NN-<slug>} section per phase, each carrying an objective, detailed instructions, planned-file lists, a gate-profile verification step, and a commit subject/body. See examples/hello-world/plan.md for a worked example and .claude/skills/phax-planning/SKILL.md for the full template contract.

#Headless authoring

phax artifact new spec|plan <slug> --headless --brief <file|-> (experimental) spawns the authoring session itself instead of leaving you a blank skeleton: it loads the matching skill (phax-spec or phax-planning) and the document's JSON Schema, accepts a schema-valid document as the session's only output, renders it deterministically to the same Markdown shape the interactive path expects, writes a JSON sidecar beside it, and commits both in one commit. A plan authored this way seeds the extraction cache, so phax run never re-extracts it. --model/--effort override the resolved authoring model/effort (flag, then phax.json's authoring.spec/authoring.plan, then the catalog default — see Configure).

phax artifact new spec headless-authoring --headless --brief brief.md
phax artifact new plan headless-authoring --headless --brief brief.md --spec docs/specs/2609230835-headless-authoring.md
cat brief.md | phax artifact new spec headless-authoring --headless --brief -

authoring spec headless-authoring — claude-opus-5-5 / high
created docs/specs/2609230835-headless-authoring.md (Draft, headless)
sidecar docs/specs/2609230835-headless-authoring.json
commit a1b2c3d — docs(specs): draft headless-authoring
record authoring/2609230835-headless-authoring

The last line names the session's authoring record on phax/records/v1 (record off when records are off; a warning when it could not be written — never a failure). phax records explain <commit> on the artifact commit resolves it.

The interactive path (artifact new spec|plan <slug> without --headless) is unchanged: no session, no sidecar, no commit. The spec document, the plan document and the authoring record manifest are persisted formats — see Persisted formats.

#Lint the plan

phax plans lint docs/plans/2609091412-plan-prune-plan.md

This is a read-only, model-free check: it reports every structural defect the deterministic parser can find, whether the planned-file lists are coherent with the working tree and with earlier phases, whether every required command is covered, whether each phase's model/effort is in the routing catalog, and — when a plan auditor is registered — every advisory finding it returns about the plan's shape. It exits 1 when any finding is an error; advisory findings are always warnings.