phx-full

Full Phoenix Feature Development

Run the portable lifecycle: discover → plan → work → verify → read-only review →

compound. The filesystem is the state machine; no task API or named orchestrator

is required.

Usage

/skill:phx-full Add user authentication with magic links
/skill:phx-full Background email jobs --max-cycles 5 --max-retries 2

If input is an existing .claude/plans/*/plan.md, do not re-plan. Ask for the

native phx-work workflow or execute its portable behavior in this session.

Defaults are --max-cycles 10, --max-retries 3, and --max-blockers 5.

Lifecycle

1. DISCOVERING — inspect relevant code, tests, prior solutions, and optional

Tidewave evidence. Tidewave is optional; local files, logs, and mix commands

are the complete fallback. Record complexity and proposed depth, then wait for

the user's plan/implementation gate. Never auto-select a path that bypasses it.

1. PLANNING — invoke the runtime's native phx-plan skill when available, or

execute its portable research checklist and artifact format in this session.

Require .claude/plans/{slug}/plan.md. Present it and wait for approval before

implementation unless the user already explicitly authorized the full run.

1. WORKING — execute the plan sequentially. Task selection occurs only here.

The full-run limits override any baseline workflow retry defaults. Before every

attempt persist cycle, task retry, and blocker counters; if the next attempt

exceeds a limit, do not run it. --max-retries N means at most N retries after

the initial attempt (N+1 total attempts for that task). Mark [BLOCKED] and

stop at --max-blockers.

1. VERIFYING — run mix format --check-formatted, compile with warnings as

errors, focused tests during work, and the full relevant suite at this gate.

A failed gate appends FAIL and returns to WORKING only within the cycle limit.

1. REVIEWING — invoke portable phx-review, or perform the same read-only,

changed-file review sequentially. Generic workers are optional. Review never

edits. Findings or failures become plan tasks and return to WORKING.

1. COMPOUNDING — only after verification and a clean/accepted review. Do not

invoke phx-compound. Inline contract: write a solution artifact under

.claude/solutions/ only when the run produced a non-obvious, reusable learning,

including problem, root cause, solution, and verification. Otherwise append

COMPOUNDING SKIPPED: no reusable learning to progress. Never edit CLAUDE.md.

Track `INITIALIZING → DISCOVERING → PLANNING → WORKING → VERIFYING → REVIEWING →

COMPOUNDING → COMPLETED, with BLOCKED` reachable from every phase. A cycle is

one WORKING → VERIFYING → REVIEWING pass; increment and persist it before

entering VERIFYING. At --max-cycles, do not begin another pass: stop INCOMPLETE with remaining tasks,

failed evidence, and a concrete resume command for this runtime.

Iron Laws

1. Honor user gates — discovery and plan approval are not automatic transitions.
2. Never skip verification or the read-only review phase.
3. Only WORKING edits code; review findings become explicit plan tasks.
4. Respect every cycle, retry, and blocker limit; stop when exhausted.
5. Persist state before stopping so plan checkboxes and progress evidence resume.
6. Do not require hooks, MCP, named agents, background tasks, or a task UI.

Resume Ledger

progress.md is the sole state authority. It is append-only: never overwrite or

maintain a competing authoritative current-state record. Every event has monotonic

seq, phase_visit, phase, cycle, task, task_attempt, cumulative

blockers, outcome, and an evidence or artifact path. On resume, validate the

last valid event against evidence, plan checkboxes, artifacts, and git state, then

enter only its legal successor. Any WORKING edit after a VERIFYING or REVIEWING

pass invalidates both passes; the next legal phase is VERIFYING.

Completion requires all required plan tasks checked, no unresolved [BLOCKED],

the latest VERIFYING PASS after the last edit, the latest accepted REVIEWING after

that verify, and COMPOUNDING passed or explicitly skipped.

References

• references/execution-steps.md — portable phase gates and outputs
• references/example-run.md — example lifecycle
• references/safety-recovery.md — resume and blocker recovery
• references/cycle-patterns.md — bounded cycle patterns