/opencode-wave — High-Effort Deterministic OpenCode Multi-Agent Wave Dispatch

The campaign coordinator for running multi-issue resolution waves in OpenCode. It takes a cohort of tracked GitHub issues or ticket tranches, verifies pairwise tree-disjoint package boundaries, isolates concurrent workers in detached worktrees, spawns user-visible detached OpenCode processes (opencode run --variant high --auto), enforces direct leaf execution within package boundaries (prohibiting nested task calls to prevent depth limit recursion failures, #12028), and supervises execution through automated harvest and safe git landing.

Six Invariants of Deterministic OpenCode Wave Dispatch

1. GitHub Issues & Tranche Grounding First: Every substantive unit of work must be tracked in a GitHub issue and grounded on ticket specifications before worker execution begins. When targeting companion repositories (e.g. anthony-chaudhary/fak-private), explicitly bind candidate issues to the target repo and local ticket tranche (docs/tickets/.../INDEX.md).
2. Mandatory Worktree Isolation: Dispatched workers touching identical Go packages must execute in detached worker worktrees (--worktree) or be partitioned into sequential waves. Concurrent edits to shared packages in the same working tree cause compilation cross-contamination and test failures.
3. Strict Ban on Loose Scripts (Modular Native Go Dispatch Only): Creating new PowerShell (.ps1), Bash (.sh), or batch (.bat) scripts is prohibited. Wave planning, process spawning, and harvest reconciliation must run through first-class Go tooling (fak issue-orchestrator).
4. High-Reasoning Effort & Auto-Approve Flags: Dispatched child OpenCode sessions run with --variant high --auto (or --dangerously-skip-permissions). This activates Gemini 3.8 Flash high reasoning mode for complex debugging, concurrency verification, and kernel implementation.
5. Leaf Worker Direct Execution (No Nested Subagents): Dispatched sessions act as depth-1 leaf workers focused on assigned lane and boundary paths. Workers execute deliverables directly within package boundaries, author reproduction tests, and run package verification without calling the task tool or attempting nested subagent delegation. The coordinator manages wave fan-out; leaf workers execute directly to prevent recursion depth limit failures (Subagent depth limit reached (1), #12028, #12029).
6. Automated Closed-Loop Supervision & Harvest: Waves do not stop at process launch. The coordinator supervises active workers, enforces the 4-state harvest protocol (StateVerifiedCleared, StateResidualReview, StateQuietIncomplete, StateSpinningStalled), lands verified worktrees to trunk, and verifies GitHub comment receipts.

Execution Protocol

Phase 1: Intake & Issue Tranche Ingestion

Query candidate issues from the target repository and pipe directly into structured JSON:

# Ingest candidate issues from target repository (public fak or private companion)
gh issue list -R anthony-chaudhary/fak-private --limit 15 --json number,title,labels,body > _scratch/issues.json

When executing a local campaign tranche, reconcile against the ticket index:

# Verify ticket definitions and acceptance criteria
cat docs/tickets/<campaign>/INDEX.md

Phase 2: Tree-Disjoint Wave Partitioning & Lease Arbitration

Partition the candidate issue set into ordered, collision-free waves where no two concurrent issues in the same wave touch overlapping packages:

# Plan safe waves with pairwise tree-disjoint boundaries and lease verification
go run ./cmd/fak issue-orchestrator \
  --workspace . \
  --from-issues _scratch/issues.json \
  --wave-size 4 \
  --plan-waves \
  --worktree \
  --json

Verify that each planned wave respects lane leases (dos arbitrate) and isolates high-blast-radius core packages into single-worker waves.

Phase 3: Native Go Wave Dispatch

Launch detached OpenCode worker processes for the target wave using first-class native Go tooling:

# Dispatch Wave 1 with high reasoning effort and detached worktree isolation
go run ./cmd/fak issue-orchestrator \
  --workspace . \
  --from-issues _scratch/issues.json \
  --spawn-opencode \
  --spawn-wave 1 \
  --wave-size 4 \
  --variant high \
  --worktree \
  --json

For private platform components in fak-private, specify the companion workspace root:

go run ./cmd/fak issue-orchestrator \
  --workspace ../fak-private \
  --from-issues _scratch/issues.json \
  --spawn-opencode \
  --spawn-wave 1 \
  --variant high \
  --worktree \
  --json

Phase 4: Live Supervision & Watchdog Monitoring

Audit running worker processes, session database registrations, and log streams:

# Check registered OpenCode database sessions
opencode session list

# Check running processes and resource utilization
powershell -Command "Get-Process -Name 'opencode' | Select-Object Id, ProcessName, CPU, WorkingSet64, StartTime | Format-Table -AutoSize"

# Inspect real-time execution log of active worker
cat _scratch/logs/opencode-issue-<issue_number>.err.log

Phase 5: Automated Closed-Loop Harvest & Safe Git Landing

Reconcile wave outcomes against the 4-state harvest protocol:

# Execute automated wave harvest and receipt generation
go run ./cmd/fak issue-orchestrator \
  --workspace . \
  --harvest \
  --json

Reconciliation states:

• StateVerifiedCleared: Git commit witnessed on worktree, tests pass green, and 5-gate boundary clean. Auto-land worktree to trunk (fak-flow land or fak sync push) and close/comment on GitHub issue.
• StateResidualReview: Diffs exist but uncorroborated or tests failing. Flag for manual inspection.
• StateQuietIncomplete: No commits or modifications found. Soft re-queue for next wave.
• StateSpinningStalled: Process exceeded turn budget or deadlocked. Terminate PID and release lease.

Verify on-device package tests before closing the wave:

go test -v ./internal/<changed-pkg>/...
go vet ./internal/<changed-pkg>/...

Verification and Witness

Verify this skill definition using the project gates:

# 1. Structural admission and anti-slop verification:
python tools/skill_slop_scorecard.py .claude/skills/opencode-wave/SKILL.md --corpus .claude/skills

# 2. Frontmatter portability check:
python tools/skill_frontmatter_lint.py --check

# 3. Synchronize cross-harness adapter for OpenCode (.agents/skills/opencode-wave/SKILL.md):
go run ./cmd/fak-project-assets sync --json

# 4. Verify zero unexplained parity gaps across harnesses:
go run ./cmd/fak-project-assets parity --json