agentic-spec-reviewer

name	agentic-spec-reviewer
description	Use when a local Superpowers spec is written or materially revised and needs subagent-driven adversarial review before writing-plans.
argument-hint	<spec-path> [--workspace <repo-root>] [--rounds <1..5>]

Agentic Spec Reviewer

Execute adversarial review of a local Superpowers spec by dispatching four read-only lane reviewers by default and revising the spec as author until blocking findings are closed. Lane reviewers are read-only; the author fixes accepted findings in this session. Use this skill after the spec is written or materially revised, and before superpowers:writing-plans. It is a plan-readiness gate, not an implementation review or code quality review.

By default, ordinary local-spec review uses four read-only lanes: contract_state_lane, verification_lane, scope_reuse_lane, and implementation_consumability_lane. The main agent is the only author and synthesis owner; lane reviewers never edit files or own final dispositions. The fixed dispatch shape is parallel=4; the default is fixed for this phase. This phase does not define any parallel tuning argument, CLI flag, config key, or AGENTS.md short rule.

Phase 6.5 Delegation

Evaluate Phase 6.5 delegation through the shared trigger rule before any local review work. Trigger and non-trigger decisions are defined in skills/agentic-spec-confirmed-implementation/rules/phase65-trigger.md. When the rule returns a Phase 6.5 match, do not run local Superpowers gates: return delegate_phase65 and route through agentic-coding-spec to agentic-spec-confirmed-implementation.

This check happens before Subagent Route Resolution, embedded model routing, lane dispatch, and restart scheduling. Reuse the full shared rule as the source of truth; do not reduce it to an input-kind-only shortcut, and do not ignore Path B or manifest delegation.

The lane dispatch policy below only applies after this shared trigger returns non-match.

Structured Asset Context Budget

When a reviewed spec depends on FS7 context slices, reviewer packets must report the measured payload_tokens budget separately from advisory layers: framework_tokens, memory_tokens, tool_output_tokens, and runtime_advisory_tokens. Only payload_tokens can be used as a blocking budget gate in this repository.

If runtime telemetry for the current request differs from the deterministic payload estimate by more than max(2000, estimated_tokens * 0.25), reviewer packet assembly records context_runtime_token_telemetry_mismatch as a warning. Session cumulative token counters must not be used for this comparison.

Subagent Route Resolution

Use the same adversarial reviewer persona across install surfaces, but resolve it through the format supported by the current runtime:

• Codex local install: use the custom agent agentic-coding-adversarial-document-reviewer, backed by ~/.codex/agents/agentic-memory/agentic-coding-adversarial-document-reviewer.toml. A missing .agent.md file under the installed skill directory is not an installation error in Codex.
• repo or sandbox-pack source: use agents/agentic-coding-adversarial-document-reviewer.agent.md.

If neither the Codex custom agent nor the repo/pack .agent.md persona is available, return blocked with a missing-persona warning. Do not copy Markdown agent files into the Codex Agentic Memory skill directory as a fix.

agentic-subagent-routing resolves slot adversarial_spec_review before dispatch, so persona availability checks stay separate from route resolution.

Embedded Model Routing

The model route is embedded in the resolved route contract. Model selection is resolved inside agentic-subagent-routing from workspace-local model policy first, then the routing skill built-in inherit fallback. If model routing cannot produce a concrete override or a concrete override is rejected at spawn time, inherit the parent model, record resolver_warnings or spawn_fallbacks as appropriate, and continue the ordinary reviewer dispatch.

Round Policy

• The default 2 adversarial rounds are used when no override exists.
• AGENTS.md may override with Spec review adversarial rounds: <N>.
• Validate the override as integer range 1..5; invalid values fall back to the default 2 and must be reported as a warning.
• Exit early when any round proves blocking findings are zero, returns delegate_phase65, returns split_required, or returns hard blocked.
• If only advisory findings remain and the author disposition is recorded, exit without forcing unused rounds.
• Author fix-and-re-review cycles have their own cap of 3 per review (workflow step 7); diff re-reviews after author fixes do not consume adversarial rounds, and the loop exits immediately once blocking findings reach zero.
• If max rounds or the fix-cycle cap are reached with unresolved blocking findings, return revision_required or blocked; exhausting either budget never authorizes planning.

Parallel Lane Dispatch

For ordinary local Superpowers specs, dispatch parallel=4 read-only lanes by default:

• contract_state_lane: attack Boundary & State, Data Flow & Contract, State Trap, Migration Risk, and Observability.
• verification_lane: attack Testability, test-oriented Data Flow boundary assertions, and observability assertions.
• scope_reuse_lane: attack Vague Directives, No Hand-Roll / No Duplicate Build, Phase 6.5 delegation boundary, and scope split / roadmap pressure.
• implementation_consumability_lane: attacks whether current specs, derivation manifest, asset index, source coverage ledger, page interactions, business flows, and operation contracts are directly consumable by CodegenPlan without re-reading the full source requirement.

Each lane receives the same immutable input packet: spec path, user requirement summary, relevant L1 / L2 / L3 context list, Phase 6.5 boundary warning, allowed read scopes, attack matrix path, recent commits, derivation output, and prototype artifact references when they exist. Add a lane-specific scope block that states the lane id, review focus, output shape, and read-only constraints. implementation_consumability_lane must emit this shape:

implementation_consumability:
  ready_for_codegen_plan: false
  lane_status: completed
  blocking_pages: []
  blocking_forms: []
  blocking_flows: []
  blocking_operations: []
  minimum_remediation_path: []

If implementation_consumability_lane times out or reaches restart_exhausted, force implementation_consumability.ready_for_codegen_plan: false.

Dispatch lanes concurrently when the platform accepts native subagent fan-out. If a spawn request is rejected because concurrent fan-out is unavailable but a sequential subagent primitive works, run the same lane packets sequentially and record spawn_rejected_sequential_fallback. If the platform exposes no subagent primitive, return blocked; do not replace lane review with controller self-review.

The main agent waits for all lane reports before synthesis, except it may end early when a lane returns delegate_phase65, split_required, or hard blocked. Early ending must preserve the triggering lane report and mark the remaining lane statuses as not run due to terminal routing.

Workflow

1. Run the shared Phase 6.5 trigger rule at skills/agentic-spec-confirmed-implementation/rules/phase65-trigger.md first. Only when it returns non-match, continue local Superpowers spec review.
2. Load AGENTS.md (including any Spec review adversarial rounds: <N> override), the active spec, relevant L1 / L2 / L3 supporting docs, and skills/agentic-spec-reviewer/rules/attack-matrix.md. Include recent commits, the original user requirement summary, derivation output, and prototype artifacts when they exist.
3. Resolve the reviewer persona, then dispatch the four read-only lane subagents using the resolved agentic-coding-adversarial-document-reviewer persona and the Parallel Lane Dispatch policy. Lane reviewers must not edit files, push, merge, generate prototypes, run CI handoff, or write memory.
4. Give every lane its immutable input packet plus lane scope. Reviewers must not inherit the author's optimistic conclusions: require each lane to independently verify referenced paths, commands, existing skills, non-goals, acceptance criteria, and Phase 6.5 conflicts against the repository instead of trusting the spec's claims.
5. Require each round to produce a Spec 漏洞与盲区报告 following the Vulnerability Report Shape in the attack matrix, with concrete findings and blocking flags.
6. As author, disposition every finding as one of: accepted_and_revised, rejected_with_evidence, deferred_to_followup, or blocked_needs_user_decision. For every finding dispositioned accepted_and_revised, revise the spec yourself in this session immediately; do not return revision_required for findings the author can fix directly. The main agent is the single synthesis owner: merge lane-scoped findings into SYN-### synthesized findings, retain lane_provenance for every source lane and source finding id, inherit blocking severity when any contributing lane finding is blocking, and write one unique disposition table instead of separate lane tables.
7. After each batch of author revisions, rerun the same reviewer persona with review_kind: diff_recheck against a narrow re-review packet. The packet must include affected lanes, each changed artifact or section, the relevant SYN-### ids, and the author disposition evidence. affected-lane routing matrix:
   • summary/template/schema/timeout changes route to contract_state_lane and verification_lane.
   • Phase 6.5/persona/resolver/reuse-policy changes route to .

Reviewer Subagent Dispatch

This skill is a subagent-driven workflow: invoking it is the request to spawn the read-only reviewer lane subagents. Dispatch reviewers directly through the platform's native subagent primitive (for example spawn_agent in Codex) without asking for additional confirmation. If the platform does not expose a subagent primitive, return blocked with a warning; do not silently replace the reviewer with controller-side self-review.

Lane Timeout, Stall, and Restart Policy

restart_exhausted is a terminal lane status that must be considered before any no-blocker planning status is allowed. A lane timeout or stall is never evidence that planning is safe, must force implementation_consumability.ready_for_codegen_plan: false for implementation_consumability_lane, and must not be reported as ready_for_plan.

The scheduler may restart only the affected lane when a lane times out, stalls, or loses its subagent session. The main agent session must not execute the lane reviewer prompt itself. Restart prompts must be narrower than the original prompt and include only the lane attack scope, evidence packet, unresolved findings, and previous timeout/restart reason. Restart each affected lane at most 2 times / max 2 with fixed backoff delays of 1s then 2s.

Record restart_count, timed_out_lanes, lane_statuses, spawn_fallbacks, and any restart_exhausted lane in the final summary. Hard boundary: 主 agent session 不得运行 reviewer prompt，不得冒充 lane report，也不得 convert missing lane evidence into author confidence.

If a blocking-sensitive lane reaches restart_exhausted, return blocked unless explicit evidence proves that lane's unanswered scope is irrelevant to the current spec and changed artifacts.

Memory

After review, best-effort record the review phase:

agentic-memory record-design --phase review --spec <spec> --summary "<review summary>"

If review caused spec revisions, best-effort record the revision phase:

agentic-memory record-design --phase revision --spec <spec> --summary "<revision summary>"

Memory recording is non-blocking; warnings must be included in the final reply.

Exit Policy

• ready_for_codegen_plan: use this gate signal before ready_for_plan; it is true only when implementation_consumability.ready_for_codegen_plan: true and blocking findings are zero.
• ready_for_plan: blocking findings are zero and planning may continue.
• ready_for_plan_with_warnings: blocking findings are zero, non-blocking warnings remain, and warnings are visible to derivation/prototype/planning.
• revision_required: blocking findings remain that autonomous author fixes could not close within the fix-cycle cap; the spec must be revised before planning.
• split_required: the scope must be split by roadmap or multiple specs.
• delegate_phase65: the request belongs to Phase 6.5 confirmed implementation.
• blocked: missing facts, missing reviewer persona, a platform without a subagent primitive, or user decisions prevent safe planning.

Guardrails

• Do not duplicate the existing Superpowers spec self-review path.
• Do not hand-roll or duplicate existing skills, helpers, contracts, Phase 6.5 flows, prototype tools, or Agentic Memory commands without evidence.
• Do not let vague directives pass: require explicit state, retry, recovery, fallback, test, migration, and observability behavior when applicable.
• Do not enter superpowers:writing-plans while blocking findings remain.
• Keep reviewer output concrete: cite file paths, commands, contracts, states, or missing fields where possible.
• Write everything reported back to the main agent — reviewer findings, the final review summary, and warnings — in the language of the spec text.