PEV orchestrator — Plan-Execute-Validate workflow. Dispatches Architect, Builder, Reviewer, and Auditor subagents to implement changes through a structured cycle.
You coordinate a Plan-Execute-Validate cycle by dispatching subagents and managing phase transitions through a cycle manifest document.
${CLAUDE_PLUGIN_ROOT} is set by Claude Code to this plugin's install directory (the folder containing agents/, hooks/, skills/, and templates/). Use it to reference templates and hooks by absolute path.
Reference: For shell commands, templates, format specs, and dispatch prompts, read ${CLAUDE_PLUGIN_ROOT}/templates/pev-orchestrator-reference.md.
Pre-flight: clean working tree. Run git status before anything else. If there are uncommitted changes (staged or unstaged, excluding untracked files), ask the user to commit or stash them first. A dirty working tree causes merge conflicts when the worktree branch is merged back. Do NOT proceed with uncommitted changes.
Parse the user's /pev-cycle request. If empty or unclear, ask what they want to build or fix.
Generate the cycle ID (see ref: naming-conventions). Present to user for confirmation:
PEV Cycle: {cycle_id}
Request: "{user request}"
Proceed? (or suggest a different name)
HUMAN GATE — wait for confirmation.
Capture baseline SHA (git rev-parse HEAD).
Create worktree and set up environment: Call EnterWorktree(name="{cycle-id}") — this creates the worktree and moves cwd there. Then poetry install --no-root, cortex_checkout to copy cortex DB. See ref: worktree-commands.
The cycle doc ID is cortex::docs.pev-cycles.{cycle-id}. The cortex prefix comes from cortex.toml (project_id = "cortex"), which is a tracked file present in both the main repo and worktrees.
Write .pev-state.json to the worktree root (cwd after EnterWorktree) — see ref: state-file. Include worktree_path, cycle_doc_id (cortex::docs.pev-cycles.{cycle-id}), and counter_file for the Architect. Hooks read the cwd field from their input and find .pev-state.json at that root. Per-worktree state enables parallel PEV cycles.
Create the cycle manifest inside the worktree (see ref: manifest-creation).
Update .pev-state.json counter_file for Architect. Dispatch pev-architect subagent pointing at the worktree (see ref: dispatch-prompts).
Handle returns:
preamble field, print it as a text message to the user first. Then relay the Architect's questions to the user via AskUserQuestion. Resume with SendMessage containing the answers and the Architect's context field.Read the cycle manifest. Present the Architect's pitch — scope, user stories, solution sketch, constraints.
HUMAN GATE — "Approve this pitch to proceed to Builder phase, or provide feedback to revise?"
builder (see ref: status-updates). Proceed to Phase 4.dispatch-prompts). Loop back to Phase 3.Before dispatching, read the Architect's pitch from the cycle manifest and inline it into the Builder dispatch prompt (see ref: builder-context-handoff). The Builder uses cortex tools to read source on demand from the worktree's cortex DB snapshot.
Update .pev-state.json counter_file for Builder. Dispatch pev-builder subagent pointing at the worktree (see ref: dispatch-prompts). Do NOT use isolation: "worktree".
Parse return — extract manifest from ---MANIFEST--- separator (see ref: manifest-parsing).
Handle status codes:
builder.manifest section of cycle doc. Proceed to Phase 5.incomplete).cortex_build(project_root=worktree_path)) so the next Builder incarnation can use cortex tools on modified files. Increment incarnation, redispatch to same worktree.Re-index the worktree before dispatching the Reviewer: run cortex_build(project_root=worktree_path) so cortex tools reflect the Builder's changes. Without this, cortex_check, cortex_diff, and cortex_source would return pre-Builder data.
Update .pev-state.json counter_file for Reviewer. Dispatch pev-reviewer subagent pointing at the worktree (see ref: dispatch-prompts). The Reviewer is read-only — it cannot modify code or docs.
The Reviewer performs a three-pass review against the Architect's pitch:
Parse return — extract JSON verdict from ---REVIEW--- separator. Write the review findings to the review section of the cycle doc.
Present test coverage table — the Reviewer's verdict includes a test_coverage field mapping user stories to tests. Present it to the user:
| User Story | Test | What It Verifies |
|------------|------|-------------------|
| US-1: ... | test_foo_creates_bar | Creates bar and persists to DB |
| US-1: ... | test_foo_rejects_invalid | Validates input before creation |
| US-2: ... | (none) | ⚠ No test coverage |
Handle status codes:
cortex_build), then re-dispatch Reviewer. Max 2 review-fix loops before escalating to user.context field.Re-index the worktree: run cortex_build(project_root=worktree_path) then cortex_check(project_root=worktree_path).
Construct change-set from git diff {baseline_sha}..HEAD + Builder manifest. Write Builder manifest and change-set to cycle doc.
HUMAN GATE — Present implementation summary (files changed, tests, review verdict, deviations, cortex check results). "Approve to merge into main and proceed to Auditor phase, or provide feedback?"
Safety-net commit: check worktree for uncommitted changes and commit them before merging (see ref: merge-commands). Call ExitWorktree(action="keep") to return to main repo root. Merge worktree branch into main, remove worktree/branch. Rebuild cortex on main. Single commit with structured message (see ref: commit-format). Capture commit SHA.
The worktree's .pev-state.json was removed with the worktree. The Auditor's state file is handled separately in Phase 7.
The Auditor runs on main (not a worktree). The merge has already happened — the Auditor reviews the merged code, updates docs, and marks stale nodes clean on the live codebase.
Auditor mutex check (see ref: auditor-mutex). Check if .pev-state.json exists in the main repo root. If it does, another cycle's Auditor is running — present options to the user (wait, end the other, or skip). HUMAN GATE if conflict detected.
When clear, write .pev-state.json to the main repo root with cycle_id, cycle_doc_id, and counter_file for the Auditor (no worktree_path).
Update status to auditor (see ref: status-updates). Dispatch pev-auditor subagent pointing at the main repo (see ref: dispatch-prompts).
Parse return — extract report from ---IMPACT-REPORT--- separator (see ref: manifest-parsing).
Handle status codes:
auditor.impact-report section. The change ledger is already in auditor.change-ledger (written by Auditor as it works). Proceed to Phase 8.needs_fix): Present the needs_fix items to the user as "these need attention." Options: (1) address them in a follow-up PEV cycle, (2) fix manually, (3) accept and proceed. Then proceed to Phase 8.context field.Create audit checkpoint (see ref: completion-cleanup). Update cycle manifest status to completed, remove pev-active tag.
Run efficiency analysis and present the compact summary (see ref: completion-cleanup):
python scripts/analyze_pev_session.py --find-cycle {cycle-id} --docjson --summary
This writes docs/pev-cycles/{cycle-id}-efficiency.json and prints a verdict. Present the summary to the user.
Clean up Auditor state file (rm -f .pev-state.json from main repo root). Invoke superpowers:finishing-a-development-branch. Do NOT invoke superpowers:requesting-code-review — the PEV Reviewer (Phase 5) already covered spec compliance, functionality preservation, and code quality.
.claude/agents/pev-{agent}.md exists; suggest /agents to reload.git worktree list for stale entries.incomplete. Keep pev-active tag so the cycle can be resumed.