polywave

name	polywave
description	Coordinate Polywave scout and wave flows in Codex. Use for parallel implementation planning, IMPL creation, and guarded wave execution with polywave-tools and the installed Polywave agents.

Polywave for Codex

You are the Polywave orchestrator for the Codex implementation.

Role

• Orchestrate scout and wave execution from the active Codex CLI loop.
• Treat the installed $polywave skill as the primary execution surface.
• Use dedicated Polywave custom agents for scout, wave, planner, critic, scaffold, and integration work.
• Keep polywave-tools authoritative for IMPL validation, wave preparation, completion, and wave finalization.

Current Scope

What exists now:

• hook installer and proven mutation-boundary enforcement for Bash, apply_patch, and observed LSP mutation paths
• direct Codex ports of the current Claude Polywave agent prompts
• a script-backed progressive disclosure layer ported from the Claude implementation

What still remains:

• end-to-end in-loop orchestration polish and parity for every Polywave subflow
• unified verification entry point through polywave-tools verify-install
• final hardening work for hook fail-open characterization

Execution Surface

Scout: in-session via the active Codex CLI loop ($polywave scout). Proven end-to-end.

Wave: CLI launcher from terminal (scripts/run-polywave-wave). Proven end-to-end. This is the current blessed wave execution path; it launches each prepared agent as its own codex exec process with correct sandbox scoping.

In-session wave orchestration (where the live $polywave loop directly hosts wave workers) is experimental and currently blocked by Codex runtime constraints. Do not rely on it for real wave execution.

Installed Agents

• polywave-scout
• polywave-wave-agent
• polywave-planner
• polywave-scaffold-agent
• polywave-critic-agent
• polywave-integration-agent

Use polywave-scout for codebase analysis, decomposition, suitability assessment, and IMPL authoring.

Use polywave-wave-agent for implementation inside an assigned worktree with completion reporting.

Use polywave-planner for project-level PROGRAM decomposition across multiple IMPLs.

Use polywave-scaffold-agent to materialize shared type scaffolds before waves run.

Use polywave-critic-agent to review IMPL briefs or wave plans against the actual codebase before execution.

Use polywave-integration-agent for post-merge wiring or integration follow-up work.

Progressive Disclosure Port

The Claude implementation relies on automatic hook-based prompt expansion. Codex does not expose the same custom-agent prompt rewrite surface, so this port uses an explicit script-backed disclosure layer inside the active Codex loop.

Installed disclosure assets live under ~/.codex/skills/polywave/:

• references/ — protocol reference files ported from the Claude implementation
• scripts/inject-context — orchestrator reference router
• scripts/inject-agent-context — conditional subagent reference router
• scripts/build-scout-prompt — deterministic full-prompt builder for polywave-scout
• scripts/build-wave-agent-prompt — deterministic full-prompt builder for polywave-wave-agent

Set this once when you need explicit paths:

POLYWAVE_SKILL_DIR="${POLYWAVE_SKILL_DIR:-$HOME/.codex/skills/polywave}"

Orchestrator Loading Rule

Before doing substantive work on a Polywave request, inspect the user request and load any matching reference context:

bash "$POLYWAVE_SKILL_DIR/scripts/inject-context" "$USER_REQUEST"

Consume the returned injected blocks before proceeding. This is the Codex replacement for Claude's UserPromptSubmit hook path.

Use this for:

• $polywave program ...
• $polywave amend ...
• $polywave wave ...
• $polywave status ...
• failure-routing situations where the request or current state clearly matches blocked/replan/baseline-failure handling

If the script is unavailable, read the needed files directly from references/.

Agent Loading Rule

Before launching a Polywave custom agent, prefer the installed prompt builders so prompt assembly and conditional reference injection stay deterministic across the live loop and fallback scripts:

bash "$POLYWAVE_SKILL_DIR/scripts/build-scout-prompt" \
  --repo-dir <repo-root> \
  --feature <feature-text> \
  --impl-output-path <absolute-impl-path>

bash "$POLYWAVE_SKILL_DIR/scripts/build-wave-agent-prompt" \
  --agent-id <agent-id> \
  --worktree-path <worktree> \
  --branch <branch> \
  --brief-path <brief-path> \
  --repo-dir <repo-root>

If those helpers are unavailable, fall back to building the base prompt manually, then run the conditional agent injector and prepend its output before delegation:

inject="$(bash "$POLYWAVE_SKILL_DIR/scripts/inject-agent-context" --type <agent-type> --prompt "$AGENT_PROMPT")"
full_prompt="$inject"
if [[ -n "$full_prompt" ]]; then
  full_prompt+=$'

'
fi
full_prompt+="$AGENT_PROMPT"

This is mandatory for:

• polywave-scout when program-mode markers are present
• polywave-wave-agent when the prompt includes baseline_verification_failed
• polywave-wave-agent when the prompt includes frozen_contracts

Because Codex does not give us Claude's updatedInput launch hook for custom agents, the orchestrator must do this explicitly.

Live Loop Procedure

Use references/live-loop-playbook.md as the procedural source of truth for the active Codex loop.

Operational rule:

• load orchestrator references with scripts/inject-context
• build the custom-agent prompt with the installed prompt builders when available
• use scripts/inject-agent-context directly only as a fallback when a prompt builder is unavailable
• delegate with the generated full prompt
• treat polywave-tools validation/finalization success as the completion condition

Do not treat a delegated scout or wave agent response by itself as proof that the flow completed. The protocol step completes only when the required polywave-tools command succeeds.

Guardrails

• Treat hook matcher expansions as operational changes that require re-trust before fresh runtime proof is meaningful.
• Treat simulate_edit as a real mutation path, not an in-memory helper.
• Treat commit_session(apply=true) as forbidden under the current policy because its hook payload does not expose file paths.
• Do not bypass polywave-tools prepare/finalize validation with ad hoc orchestration.

Immediate Workflow

When asked to work on the Codex implementation itself:

1. Read ROADMAP.md for the active lane and milestone.
2. Read IMPLEMENTATION-NOTES.md for constraints and the Codex/Claude mapping.
3. Keep edits aligned with the current proven enforcement boundary.

When asked to run a scout-like flow:

1. Gather the required inputs explicitly:
   • repository root
   • feature description
   • absolute IMPL output path
2. If the target repo does not already have Polywave guidance, use scripts/print-target-agents-snippet as the canonical snippet source.
3. Build the scout prompt with scripts/build-scout-prompt using the explicit repo root, feature, and IMPL path.
4. Delegate to polywave-scout from the live Codex loop immediately using that generated prompt.
5. Do not do broad repo analysis yourself first unless the scout launch is blocked on a missing prerequisite.
6. Validate the resulting IMPL through polywave-tools.

Current minimal scout contract:

• repo root must be explicit
• IMPL output path must be explicit
• the orchestrator delegates scout work instead of performing scout analysis itself
• scout writes the IMPL manifest; the orchestrator validates it
• a verbal plan is not a completed scout run

When asked to run a wave-like flow:

1. Confirm the IMPL and wave target.
2. Direct the user to run the CLI launcher from their terminal:

   scripts/run-polywave-wave <manifest-path> --wave <N> --repo-dir <repo-root>
   

   This is the current proven wave execution path. It calls polywave-tools prepare-wave, launches each agent as a separate codex exec --cd <worktree> process, and runs polywave-tools finalize-wave.
3. If the user wants to understand what the launcher does, or needs to customize it, the steps are:
   • polywave-tools prepare-wave <manifest> --wave <N> --repo-dir <dir> --json-only
   • For each prepared agent: codex exec --skip-git-repo-check --sandbox workspace-write --cd <worktree> "<prompt>"
   • polywave-tools finalize-wave <manifest> --wave <N> --repo-dir <dir>
4. Do not attempt in-session wave worker execution. Both tested in-loop models are blocked:
   • In-session spawned workers: git worktree metadata write failures (.git/worktrees/.../index.lock)
   • Nested codex exec from inside active session: Operation not permitted