PEV Loop

Long-running goals with fresh planners, scoped executors, and blind verification

Why PEV · Architecture · Install · Use · Safety

---

pev is a skill for complex implementation goals that should not be planned, executed, and approved by the same context. It keeps the primary agent as a thin controller and creates a fresh isolated agent for each Planner, Executor, and Verifier role.

It ships in two runtime flavors from one shared design:

• codex/ — for the Codex CLI. Invoked with $pev, targets gpt-5.6-sol, and manages a native Codex goal when available.
• claude-code/ — for Claude Code. Invoked with /pev, routes roles to Opus subagents (Sonnet for mechanical units), and runs its own bounded loop since Claude Code's built-in /goal cannot be set programmatically.

Both share the same contract: a thin controller, fresh role contexts, OS-temp-only state, dual product/controller gates, and a second fresh final verifier. The design has one hard completion rule:

No goal is complete until a fresh blind verifier proves every definition-of-done item from direct evidence, and a second fresh final verifier confirms it from scratch.

Why PEV

A conventional long-running agent often accumulates three responsibilities:

1. It decides what to build.
2. It builds it.
3. It decides whether its own work is good enough.

That is efficient, but it lets planning assumptions, implementation rationale, and optimistic self-evaluation share one context. Long transcripts also accumulate source output, test logs, and abandoned approaches.

PEV Loop separates those responsibilities. The controller retains only canonical state and compact receipts. Product reasoning happens in disposable role contexts, while the verifier receives neither the plan nor the executor's explanation.

Architecture

flowchart LR
    U["$pev objective"] --> C["Thin Sol controller"]
    C --> T[("Private OS temp state")]

    C --> P["Fresh Planner<br/>Sol medium/high"]
    P -. "task packet only" .-> C

    C --> E["Fresh Executor<br/>Sol low/medium/high"]
    E --> W["Product / working tree"]
    E -. "compact receipt only" .-> C

    C --> V["Fresh blind Verifier<br/>Sol high/xhigh"]
    W --> V
    V -. "PASS / NEEDS_WORK + evidence" .-> C

    C -->|"NEEDS_WORK"| P
    C -->|"candidate PASS"| FV["Fresh final Verifier"]
    FV -->|"full-rubric PASS"| D["Goal complete"]

    classDef controller fill:#111827,color:#fff,stroke:#111827
    classDef planner fill:#e0e7ff,color:#312e81,stroke:#818cf8
    classDef executor fill:#dbeafe,color:#1e3a8a,stroke:#60a5fa
    classDef verifier fill:#dcfce7,color:#14532d,stroke:#4ade80
    classDef state fill:#fef3c7,color:#78350f,stroke:#f59e0b

    class C controller
    class P planner
    class E executor
    class V,FV,D verifier
    class T state

Loading

Role boundaries

Role	Reads	May change	Must not do
Controller	Canonical temp state and compact receipts	Temp state and native goal status	Inspect product bodies, implement, or grade
Planner	Goal, rubric, progress, repository	Nothing	Implement or declare success
Executor	One task packet and owned scope	Product files in scope	Update rubric or grade its work
Verifier	Original goal, frozen rubric, current product	Nothing	See P/E reasoning or fix failures

Every role context is fresh. The Planner and Executor can never award rubric credit. The Controller copies only verifier-backed evidence into progress state.

How the loop works

1. Invocation ($pev on Codex, /pev on Claude Code) establishes or reuses the goal — a native Codex goal when available, otherwise a self-managed bounded run.
2. A specification planner converts the objective into an immutable, machine-checkable rubric whose items all start unproven.
3. A fresh Planner selects one bounded work unit.
4. A fresh Executor implements that unit with effort matched to its risk.
5. A fresh blind Verifier evaluates the whole product definition of done independently.
6. NEEDS_WORK starts a new iteration with a new Planner.
7. A candidate PASS triggers another fresh full-rubric verifier before completion.
8. The Controller separately audits iteration, isolation, temp-state, and authorization records.

The default limit is 6 iterations on Codex and 5 on Claude Code. Users may select 1..10; reaching the limit never becomes an automatic success or blocked claim.

Product quality and orchestration integrity are separate gates. PEV's iteration count, model routing, context isolation, and state bookkeeping never become product rubric items, so a Product Verifier cannot be anchored by internal workflow state.

Ephemeral state

Each invocation initializes a private directory through the operating system's secure temp mechanism:

<os-temp>/codex-pev-<random>/        # claude-pev-<random>/ on Claude Code
├── goal.json
├── rubric.json
├── plan.json
├── progress.json
└── verdicts/
    ├── iteration-01.json
    └── iteration-02.json

No run-state is written under the repository, workspace, home directory, or skill directory. State files are never staged, committed, pushed, published, or copied into project documentation.

PEV also routes incidental test/build caches and logs to OS temp storage when tools support it. An agent may remove only an exact disposable artifact that its own assignment created and whose provenance is certain.

The temp directory remains available after success, failure, or an iteration-limit stop so the run can be inspected or resumed while the OS retains it. If the OS removes it, PEV reconstructs state and treats every prior completion claim as unproven.

This restriction applies to PEV's orchestration state. Product files explicitly required by the user's goal still belong in the target project.

Installation

Codex

mkdir -p ~/.codex/skills/pev
rsync -a codex/skills/pev/ ~/.codex/skills/pev/

Or via the Skills CLI:

npx skills add merttcetn/pev-loop -g --agent codex

Codex discovers skill changes automatically in current releases. If the skill does not appear, restart the client.

Claude Code

mkdir -p ~/.claude/skills/pev
rsync -a claude-code/skills/pev/ ~/.claude/skills/pev/

The skill is invocation-gated (disable-model-invocation: true), so it runs only when you type /pev.

Usage

Codex

Skills are invoked with $:

$pev Migrate the API layer to TypeScript, preserve behavior, compile in
strict mode without explicit any types, and keep the full test suite green.

Set an iteration limit with max=8, or apply another skill independently across roles with using=$frontend-design. When native goal tools are available, PEV establishes and manages the persistent goal programmatically; without them it runs the same bounded workflow but cannot promise automatic continuation.

Claude Code

Invoke with a slash command:

/pev Migrate the API layer to TypeScript, preserve behavior, compile in
strict mode without explicit any types, and keep the full test suite green.

Set an iteration limit with --max 8. Naming another skill in the task text (e.g. "…using /commit") folds its requirements into the rubric and passes it to every relevant role. Claude Code's built-in /goal is a transcript-only evaluator the model can't set programmatically, so PEV runs its own loop; you can optionally add /goal yourself as a seatbelt.

Model policy

Codex targets gpt-5.6-sol when available, routing effort by role risk:

Role	Default reasoning	Typical escalation
Controller	Active session	Remains orchestration-only
Specification Planner	High	Broad migration or critical ambiguity
Iteration Planner	Medium	Cross-cutting design or repeated failure
Executor	Low or medium	Risky or cross-cutting implementation
Verifier	High	xhigh for critical or irreversible work

Claude Code routes by role to fixed tiers instead of a reasoning knob:

Role	Model
Controller	the main session (orchestration only)
Planner / Plan reviewer / Verifier / Final verifier	opus, always fresh
Executor	opus; sonnet only for mechanical units

In both runtimes, when a preferred model is unavailable, context isolation takes priority and the substitution must be disclosed. Haiku is never used for any role.

Safety and limitations

• PEV uses more total compute than a single-agent loop: each iteration may run three fresh agents.
• Independent verification reduces self-approval bias; it does not make incomplete tests complete.
• The verifier treats missing, stale, ambiguous, or indirect evidence as NEEDS_WORK.
• Existing tests cannot be deleted, skipped, or weakened to manufacture a pass.
• Legitimate test changes are permitted only when the user goal requires them and receive verifier scrutiny.
• PEV does not commit, push, publish, deploy, or perform destructive external actions unless the goal explicitly authorizes them.
• Parallel write-heavy execution is intentionally avoided; each iteration has one Executor.
• Temp state may not survive a reboot or OS cleanup.

Repository layout

pev-loop/
├── codex/
│   └── skills/pev/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── references/contracts.md
│       └── scripts/init_run.py
├── claude-code/
│   └── skills/pev/
│       ├── SKILL.md
│       ├── references/contracts.md
│       └── scripts/init_run.py
├── tests/
│   └── test_init_run.py
└── README.md

Author

Created by Mert Çetin.

• LinkedIn
• GitHub repository

---

Built for bounded execution, clean coordinator context, and completion claims that carry evidence.