| name | phase-create |
| description | Use when the user (or the advisor) wants to design and register a NEW optional pipeline phase conversationally — "add a phase that does X". Interviews for goal-type, trigger signal, report sections, and verdict; synthesizes a phase.json + persona; registers them via `evolve phases create`; self-corrects from the command's JSON envelope. The Go binary is the single enforcement point, so this flow works from any LLM CLI. |
| argument-hint | <what the phase should do> |
Phase Create — conversational phase registration (ADR-0038)
You turn a phase idea into a registered, advisor-selectable pipeline phase. All
validation, collision-checking, scaffolding, and index rebuilding live in
evolve phases create — your job is to design a good spec, call the command,
and self-correct from its JSON envelope. Never write .evolve/phases/ or
agents/ files directly; the command is the only sanctioned writer.
What a phase IS here
A phase is pure declarative config: a phase.json descriptor (the contract)
plus a persona markdown (the prompt). No executable code. User phases are
always optional:true, kind:"llm", and can never displace the
build→audit→ship spine — the same gates and policies apply to every phase.
Stage 1 — Interview (one question at a time)
Establish, in order:
- Purpose — one sentence: what does the phase produce? (becomes
description)
- Archetype —
plan (decides/scopes before build) or evaluate (verifies
after build). User phases are never build/control.
- Goal types — which cycles is it for?
categories: subset of
bugfix | feature | refactor | security | performance | release | docs.
- Trigger — the objective signal that should make the advisor SELECT it
(becomes
when_to_use, ≤140 chars, and ideally a routing.insert_when
condition on a real signal like scout.goal_type or build.diff_loc).
- Report shape — 2–3 required
## section headings for its report
(classify.require_sections); evaluate phases should opt into a verdict
(verdict_on_pass: "PASS") and, when they do, into the failure-signal
contract (require_failure_context: true, ADR-0039): a FAIL/WARN verdict
sentinel must then carry failure: {class, defects[], evidence_paths[]} —
the contract gate teaches the exact line and re-dispatches on omission.
- writes_source? — does it write files into the worktree? (true ⇒ sandbox
role-gate; most evaluate phases are read-only.)
- Position —
after which phase? (empty = the pre-audit slot.)
Skip questions the user's request already answers. Check the existing catalog
first — evolve phases list (or .evolve/phase-inventory.json) — and tell the
user when an existing phase already covers the need (SELECT over MINT applies
to humans too).
Stage 2 — Synthesize
Draft the phase.json (kebab-case name; optional:true; kind:"llm"; the
metadata trio description / when_to_use / categories; typed
inputs/outputs incl. signals; classify; routing; after) and a persona
markdown. Model the persona on agents/evolve-bug-reproduction.md: frontmatter
(name/description/model/tools/output-format), pipeline-position diagram,
numbered workflow, an Output Contract section naming the required headings,
and an anti-Goodhart note. Show both to the user for approval before
registering.
Stage 3 — Register and self-correct
evolve phases create --spec - <<'SPEC'
{ ...the phase.json... }
SPEC
Pass the persona with --persona <file> (write it to a temp file first;
only one input may use stdin). The command prints ONE JSON envelope to stdout:
{"ok":true, "artifact":…, "required_sections":[…], "emits_verdict":…, "inventory_rebuilt":true} — done. Report the derived contract to the user
and note the advisor can SELECT the phase from the next cycle start.{"ok":false, "errors":[…], "warnings":[…], "hint":…} (exit 2) — fix every
listed error in the spec and re-run. At most 3 correction passes; if
still failing, show the user the errors verbatim and stop.
Treat warnings as advice worth fixing (unknown category, missing
require_sections) but not blockers.
Mint promotion
To persist a good ephemeral mint from a routing plan, pass the mint JSON
(plus a name) instead of a spec:
evolve phases create --mint - <<'MINT'
{"name":"context-condense","prompt":"<persona>","tier":"balanced","writes_source":false}
MINT
The prompt becomes the persona body; tier becomes the model. Flesh out the
generated spec (categories, when_to_use, classify) afterwards via the normal
interview if the mint should become a first-class catalog citizen.
Plugin distribution
A phase created here lands in .evolve/phases/ (project-local). To ship
phases as a plugin bundle: put the same <name>/phase.json dirs in any
directory and add it to the colon-separated paths.phase_roots field in
.evolve/policy.json. Left-most root wins on name collision; built-ins always
win. Details: docs/architecture/phase-plugin-system.md.
