agentsclimarketplace

Pev external reviewer

Skill myksyut/pev-harness/skills/pev-external-reviewer

Claude Opus 4.7 native Plan-Execute-Verify coding harness — a Claude Code plugin that enforces a 3-phase pipeline with hook-driven verification

Install
npx -y skills add myksyut/pev-harness --skill pev-external-reviewer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

外部 LLM CLI (v2.0 では OpenAI Codex) を Reviewer として subprocess invoke する skill。 git diff + plan.md + rubric を組み立てて codex exec --json --output-schema に渡し、 structured JSON output を verify.json に merge する。 timeout / non-zero exit / 認証失敗時は自動で dual-claude にfallback (graceful degrade)。

SKILL.md

9.3 KB, as published. Nobody here has run it

pev-external-reviewer

v2.0 で導入された external reviewer 起動 skill。 OpenAI Codex CLI を subprocess として呼び、 schema 強制 JSON を受け取って verifier の verify.json に merge する。 v2.1+ で Gemini CLI 等の他 vendor を同じ pattern で増設できるよう、 「subprocess + JSON schema + fallback」 を抽象化している。

When to Use

  • PEV_REVIEWER_MODE が dual-codex または codex-only の時、 verifier dispatch logic から起動
  • /pev <task> --reviewer-mode=dual-codex で明示指定された時
  • v2.0 では provider = codex のみ、 v2.1+ で gemini 等が追加予定

起動すべきでない場面:

  • PEV_REVIEWER_MODE=claude-only (default) — 本 skill は dispatch されない
  • codex CLI が未 setup (pev-bootstrap-codex が未実行) — Preflight が detect、 fallback に即遷移

Preflight check

skill 起動直後、 以下を確認 (どれか fail なら 即 fallback + verify.json.fallback_reason 記録):

  1. codex CLI 存在: command -v ${PEV_CODEX_BIN:-codex} で確認、 不在なら fallback_reason="codex_not_installed"
  2. 認証状態: codex login status を確認 (subscription auth または API key auth どちらでも OK):
    • "Logged in using ChatGPT" (subscription) → OK
    • "Logged in using API key" または "Logged in" (API key 経由) → OK
    • "Not logged in" または取得失敗 → fallback_reason="codex_not_authenticated"
  3. schema file 存在: schemas/codex-reviewer-output.json を確認、 不在なら fallback_reason="schema_missing"

fallback 先は PEV_REVIEWER_MODE 値次第:

  • dual-codex → dual-claude (Reviewer B が codex → sonnet に降格)
  • codex-only → claude-only (single verifier)

fallback 時は warning を stderr に出力、 verify.json に reviewer_mode (=実行モード) と intended_reviewer_mode (=要求モード) を両方記録。

Invocation pattern

codex exec の正確な command line (v2.0 で確立、 dog food 実証済)

PROMPT_FILE=$(mktemp -t pev-reviewer-prompt-XXXXXX)
OUTPUT_FILE=$(mktemp -t pev-reviewer-output-XXXXXX).json
STDERR_FILE=$(mktemp -t pev-reviewer-stderr-XXXXXX)

# Step A: prompt 構築 (git diff + plan AC + rubric を 1 file にまとめる)
cat > "$PROMPT_FILE" <<EOF
あなたはコードレビュアーです。 以下の rubric に従って構造化 JSON を返してください。

## Rubric
- verdict: PASS / FAIL のいずれか
- critical_issues: 確実に修正が必要な指摘 (bug / security / contract violation)
- suggestions: 任意の改善提案 (style / refactor / docs)
- ac_coverage: AC ごとの met (true/false) と evidence

## Plan / AC
$(cat .pev-artifacts/plan.md)

## Diff
$(git diff)

## Constraints
- AC を 1 つずつチェックして evidence を引用すること
- LLM 推測ではなく diff と plan.md に書かれた事実のみを根拠にすること
- output schema に従って JSON を 1 つだけ返すこと
EOF

# Step B: portable timeout wrapper (v2.0 dog food finding F1)
# macOS default では `timeout` コマンドが不在 → gtimeout (coreutils) を試す
if command -v timeout >/dev/null 2>&1; then
  TIMEOUT_PREFIX=(timeout "${PEV_CODEX_TIMEOUT:-300}")
elif command -v gtimeout >/dev/null 2>&1; then
  TIMEOUT_PREFIX=(gtimeout "${PEV_CODEX_TIMEOUT:-300}")
else
  TIMEOUT_PREFIX=()
  echo "WARNING: timeout/gtimeout 不在。 brew install coreutils を推奨 (subprocess の安全な上限制御のため)。 今回は timeout なしで実行" >&2
fi

# Step C: codex 起動
"${TIMEOUT_PREFIX[@]}" \
  "${PEV_CODEX_BIN:-codex}" exec \
    --json \
    --output-schema "schemas/codex-reviewer-output.json" \
    -o "$OUTPUT_FILE" \
    --ephemeral \
    --sandbox "${PEV_CODEX_SANDBOX:-workspace-write}" \
    --skip-git-repo-check \
    "$(cat "$PROMPT_FILE")" \
    2> "$STDERR_FILE"

EXIT=$?

注意 (v2.0 dog food finding F2): --output-schema に渡す JSON Schema は OpenAI structured outputs strict 仕様 に従う必要:

  • properties の全 key を required 配列に含めること (optional 不可)
  • optional 項目は型を ["string", "null"] 等で表現して null 許容にする
  • additionalProperties: false を全 object level に書く
  • oneOf / anyOf 等は使用不可

schemas/codex-reviewer-output.json は v2.0 で既に strict 仕様に揃えて出荷済。 team が custom rubric を追加する際も同 spec を踏襲する。

Exit code handling

Exit意味skill 挙動
0正常終了OUTPUT_FILE を parse → reviewer JSON として merge
124timeout (timeout command 由来)fallback、 fallback_reason="codex_timeout"
その他 non-zerocodex 内部 error (auth / network / sandbox 違反)stderr を verify.json の reviewers[].error に記録 + fallback

Output parse

OUTPUT_FILE は --output-schema の強制で JSON 1 件。 JSON.parse 失敗 (schema 違反) は fallback 対象 (fallback_reason="schema_violation")。

Sandbox

default は workspace-write (workspace 内 file write 可、 network 不可)。 codex は review 用途で read-only 動作のはずだが、 万一 file 書き換えが起きると pev pipeline と衝突するため workspace-write を選択して 意図しない write を .pev-artifacts/ 配下に閉じ込める。 --sandbox danger-full-access は 禁止 (skill 内 hard-coded で reject)。

verify.json への merge

{
  "verdict": "PASS",
  "reviewer_mode": "dual-codex",
  "intended_reviewer_mode": "dual-codex",
  "fallback_reason": null,
  "reviewers": [
    {
      "provider": "claude-opus-4-8",
      "verdict": "PASS",
      "critical_issues": [],
      "suggestions": ["..."],
      "raw_output_excerpt": "..."
    },
    {
      "provider": "codex/<model>",
      "verdict": "PASS",
      "critical_issues": [],
      "suggestions": ["..."],
      "raw_output_path": "/tmp/pev-reviewer-output-XXXXX.json",
      "latency_ms": 47200
    }
  ],
  "merge": {
    "agreement_pct": 92,
    "both_pass": true,
    "critical_issues_dedupe": [],
    "final_verdict": "PASS"
  }
}

merge ロジックは現 pev-dual-review の dedupe + agreement_pct を踏襲、 provider field を追加して trace 可能化。

並列起動 (dual-codex mode)

verifier が dispatch する時、 Reviewer A (claude opus) と Reviewer B (codex) を 同一メッセージ内で同時起動:

  • Reviewer A: Agent tool で subagent_type=verifier, model=opus
  • Reviewer B: Bash tool で codex exec subprocess (本 skill の Invocation pattern)

両者の完了を待って merge。 codex は subprocess なので OS process boundary で context isolation が自然、 Claude 側の Agent 並列起動と同じ独立性が確保される。

Security considerations

  • 認証は codex CLI 内部 (~/.codex/ session token or env var) で管理、 本 skill は API key / session token を読まない
  • stderr file ($STDERR_FILE) は verify.json への記録時に「API key 系トークンを含む可能性のある行を redact」 する filter を通す (e.g., sed -E 's/(sk-[A-Za-z0-9_-]{20,})/[REDACTED]/g')
  • prompt は git diff を含むので、 codex 側にもコードが送られる。 これは Anthropic Claude 経由でも同じだが、 OpenAI への送信は team policy で禁止されているケースあり → ONBOARDING で明示

Examples

dual-codex mode で /pev --strict

PEV_REVIEWER_MODE=dual-codex /pev "Add /healthz endpoint" --strict

verifier が:

  1. claude verifier 単独 verify を実行 (build / type / lint / unit / e2e)
  2. 同時に Reviewer A (claude opus subagent) + Reviewer B (codex subprocess) を起動
  3. 両者の JSON を merge して final verdict を verify.json に書く

codex-only mode (cost 削減)

PEV_REVIEWER_MODE=codex-only /pev "Refactor: rename foo to bar"

claude verifier を skip、 codex 単独で verify。 token cost が低い軽微 task 向け。

Related

Notes

  • skill 自体は stateless、 各 verify round で fresh に invoke (前 round の codex session を引き継がない、 --ephemeral flag で保証)
  • codex CLI の --model flag は v0.130 時点で interactive /model command のみ documented、 future v2.1+ で env var (PEV_CODEX_MODEL) → flag mapping を検討
  • v2.0 では provider = codex 1 種、 v2.1+ で gemini / 他 vendor を本 skill 内の switch / case で拡張する想定 (interface = subprocess + JSON schema)

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.