Harness orchestration

The harness coordinates each task through implementation, independent verification, rework, and a commit. Zdev supplies the records and checks; each adapter uses its harness’s native workers. The versioned observations below were checked on 2026-08-20.

Routes and native adapters

Codex and Claude Code installations also package an explicitly selected T3 Code route. It replaces native dispatch and continuation when the main thread is running in T3 Code and the user requests T3 orchestration. Worker targets and profiles resolve by each worker’s harness. Ownership, verification, snapshot comparison, completion, and commits retain the common contract below. Other requests continue through the native adapters.

Each harness installs one discoverable zdev skill. The skill routes these user intents to internal contracts and harness-native adapters:

• zdev-implement <area> selects and completes one ready task through implementation, independent verification, any task-owned rework, task completion, and commit.

• zdev-verify <area> <task-id> independently verifies the current work for one explicit task. REWORK is a verdict, not a fourth public workflow. This workflow never completes or commits the task.

• zdev-audit [<boundary>] performs a read-only codebase audit, checks the candidate findings, and returns either no findings, checked findings, or a blocker. An omitted boundary means the current repository.

• zdev-loop <area> [focus...] continues an area one verified task and commit at a time; zdev-goal is its exact alias. The remaining words are fuzzy selection guidance. OpenCode and Pi currently expose the same bounded form, which completes at most one task and returns CONTINUE only after a verified commit when fresh ready work remains.

• In Codex and Claude Code, an explicit Research run request uses the harness-specific installed references/research.md to coordinate serial research on the current branch. It generates mixed work within the authorized scope, charges dispatch before work, accepts only independently verified keeps, and recovers from the existing run and experiment commands. Empty queues permit further proposals. Ordinary routes retain their hypothesis guards.

Packaged workflows, commands, and prompts support those routes. They do not form additional skills or change the root activation name.

Installed artifacts

Harness	Installed skill and adapters	Native workers
Codex	One zdev/SKILL.md; audit, task, verification, serial research, and continuation contracts live under zdev/references/	The root skill passes the resolved routine-implementer, implementer, verifier, or advanced-implementer profile when spawning a native Codex subagent. Its continuation route uses Codex’s native goal when clear and a one-task fallback only after clear inspection when creation is unavailable.
Claude Code	One skills-directory plugin whose .claude-plugin/plugin.json declares "workflows": "./workflows/", containing workflows/zdev-implement.js, workflows/zdev-verify.js, workflows/zdev-audit.js, workflows/zdev-loop.js, workflows/zdev-goal.js, and workflows/zdev-research.js with matching meta.name values, plus contracts/task-workflows.md	agents/zdev-planner.md, agents/zdev-routine-implementer.md, agents/zdev-implementer.md, agents/zdev-verifier.md, and agents/zdev-advanced-implementer.md. Each agent() call selects a concise scoped role and passes a stored work-context locator. The detailed derived-work contract is loaded only when a split is needed.
OpenCode	commands/zdev-implement.md, commands/zdev-verify.md, commands/zdev-audit.md, commands/zdev-parallel.md, commands/zdev-loop.md, and commands/zdev-goal.md under the selected OpenCode scope	agents/zdev-planner.md, agents/zdev-routine-implementer.md, agents/zdev-implementer.md, agents/zdev-verifier.md, and agents/zdev-advanced-implementer.md; one-task commands use the native task tool and compact file/snapshot locators. The parallel command stops before mutation because foreground batches do not return coordinator control per completed child. The documented directory is plural commands/.
Pi	prompts/zdev-implement.md, prompts/zdev-verify.md, prompts/zdev-audit.md, prompts/zdev-parallel.md, prompts/zdev-loop.md, and prompts/zdev-goal.md	extensions/zdev-subagent.ts keeps single configured roles and adds bounded, task-keyed planner and source-implementer batches with explicit working directories. Calls carry compact locators rather than the rendered workflow.
Oh My Pi	prompts/zdev-implement.md, prompts/zdev-verify.md, prompts/zdev-audit.md, prompts/zdev-parallel.md, prompts/zdev-loop.md, and prompts/zdev-goal.md	Concise blocking agents handle ordinary one-task work. Separate non-blocking routine, standard, and advanced implementers run assigned source worktrees for parallel batches; the coordinator uses blocking planners and verifiers and retains integration, completion, and commits.

Every installation also contains one rendered references/parallel.md route. Codex maps it to live-agent inspection, bounded collaboration dispatch, waits, supported interruption, explicit source cwd values, and the configured role profiles. OpenCode renders an explicit unsupported result with a sequential option and its discoverable command checks the current Task surface before mutation. Oh My Pi’s prompt checks its live conditional Task schema, background job controls, agent discovery, and explicit path access before creating zdev worktrees; it omits native isolation so automatic merge and cleanup cannot bypass coordinator gates. Pi uses a transient session-local handle to return one completed source result at a time, then requires serial destination verification before coordination continues the run. The shared route owns admission, isolation, serial integration, recovery, and cleanup rules; no adapter adds a persistent scheduler or batch record.

For an ongoing goal or loop with explicit blanket parallel approval, the coordinator retains the approved area, eligible work, worker limit, destination, worktree and cleanup choices in its existing handoff. Later compatible finite batches reuse that authority while repeating fresh admission and every per-task verification and commit gate. One-batch approval ends with its batch; a change outside blanket authority needs a new decision. Claude uses its finite parallel workflow under coordinator control for this continuation, rather than its ordinary sequential loop workflow. Unsupported or bounded adapters retain their documented limits.

Install and check render the same files from the same inputs. The worker model and effort come from the contract in Worker profiles.

Worker prompts contain only their short role, repository guidance, task/file locators, snapshot IDs, and the preceding role’s small result. Coordination supplies the resolved route-contract path when a worker may need rare details, such as the derived-work form. It does not paste the full coordinator contract into every child call. Claude can additionally use ${CLAUDE_PLUGIN_ROOT} for its plugin contract.

Codex installation targets the shared skills/ root and manages only the zdev/ skill while leaving unrelated skills untouched.

Forced migration removes only hard-coded previous zdev-owned files: the five split Codex skill directories created by 1.1.0, two singular command/ files under OpenCode, and prompts/zdev-task.md under Pi. Empty legacy directories are pruned. A non-forced install and readiness check report the old integration as a conflict. No unrelated shared-root file is removed.

Codex serial research coordination

The research reference owns the ordered run route. One coordinator retains resolved concrete worker profiles, reads run context before costly work, recovers unfinished effects, admits and commits generated tasks, and dispatches one task at a time. Supporting tasks retain ordinary fresh verification and completion. Each preparation/support/rework/repair/rerun/confirmation dispatch is counted; measurement uses the bound local lifecycle. Finalize alone owns managed hypothesis retention/restoration, task completion and commit.

A proposed keep uses the checkpoint’s verification snapshot and a fresh independent verifier’s strict semantic result. The coordinator compares the snapshot and constructs the public envelope before finalize. Discards and terminal failures use coordinator checks and retain lessons for the next proposal. Shared failures halt affected experiments, permit counted supporting repair and require actual rebaseline after resolution. Resume preserves run identity, scope, target, deadline and costs.

Native continuation follows exposed get_goal, create_goal and update_goal capabilities and lifecycle rules. Clear inspection with unavailable creation permits at most one foreground work-item iteration; uncertain state blocks. No transient blocker or queue/allowance exhaustion establishes that an unfinished native objective is complete. Deterministic local scenarios are contract/API evidence; authenticated live Codex execution remains separate acceptance work.

Common execution contract

Deterministic task selection

zdev-implement collects a stored work-context snapshot first. The command validates goal lifecycle before collecting branch or Git facts, so a validated closed result returns no work without those reads. Open results contain nested status and goal projections plus HEAD and exact staged, unstaged, and untracked evidence. The coordinator requires the projections to agree, requires branch_status.task_work.safe, reports stale_advisory once, and uses only the ready goal’s task as its subject. Structurally unsafe state still blocks. Workers receive the opaque stored locator and read the exact context themselves instead of relaying it through a model response.

For an area-only loop or goal, the binary chooses ready work by AFK suitability, priority, then numeric task ID. If the user supplies any fuzzy focus, the coordinator reads every task in the complete ready frontier, chooses the best fit, and admits that explicit ID with work-context --task. It repeats that selection after every commit and never stores the focus in zdev state.

An implement context that is open / empty, open / exhausted, or closed is a successful no-work result. Closed requires no branch or Git evidence; open no-work retains the open-work gates. No worker is started, and no state changes. A malformed graph, unsafe open branch, changed focus task, or other validation error is a blocker. The stored-and-shown verification snapshot is also the fresh context admission after implementation and after each rework. Before each rework implementation handoff, the coordinator still reruns ordinary work-context and requires the same task ID. If selection changes during a long conversation, the workflow stops before implementing the wrong task.

zdev-verify requires the explicit task ID to equal the current ready focus task. Any no-work context is a blocker and starts no worker. Its one stored-and-shown snapshot call is both admission preflight and verifier snapshot, and it does not invoke an implementer. The verifier shows the supplied snapshot and runs validation; coordination compares it after the response. zdev-audit has no area selection and does not call zdev goal.

The native goal behavior described in Explicit area continuation across harnesses belongs only to explicit zdev-loop or zdev-goal continuation. Codex and Oh My Pi apply the short native condition when no conflicting native goal exists. Claude uses its standalone workflow; OpenCode and Pi use the bounded continuation. Ordinary implementation and verification use work-context regardless of native goal support.

Ownership and delegation

The coordinating session owns:

• area and task selection, branch gates, the Git baseline, and overlap checks;
• user questions and product decisions;
• choosing the dated or configured worker profile;
• dispatch, result validation, diff inspection, and rework routing;
• zdev task done, zdev commit, and the final user report.

The implementer owns only task-approved source and test changes plus the recorded validation. It does not edit .zdev, delegate, change task lifecycle, or commit. The verifier is a fresh worker for every verdict. It reads the brief, task, supplied snapshot, full diff, and relevant source; runs required checks; and makes no intentional edits. A validation command that writes files is reported as REWORK and attributed before work continues. Coordination owns snapshot collection, comparison, advisory attachment, and public identity.

The opt-in assigned-worktree path uses the same ownership contract. Coordination records absolute authoritative and source roots, pins admission with --task, and uses an ordinary source commit plus no-commit three-way integration as durable transport. Harness adapters provide dispatch and cwd handling; they do not own another scheduler, lifecycle, record copy, merge policy, or completion path. Codex states the source cwd explicitly because its collaboration surface shares the parent directory.

Implementation role selection follows the task’s authored complexity. routine uses routine-implementer; standard and omitted complexity use implementer; and advanced first obtains one fresh read-only plan from advanced-implementer, then uses that role for the edits. Every verdict comes from a fresh standard verifier. Ordinary rework returns to the selected implementation tier without replanning. After standard implementation only, a verifier may recommend one move to advanced-implementer during the current in-memory task run; the repair is followed by another fresh standard verifier. Routine and already advanced work cannot escalate. zdev-verify starts a fresh verifier. Before substantive findings drive rework or reporting, an independent coordinator inspects their evidence or a different fresh verifier checks them. The executable Claude routes use a fresh verifier and compare the task snapshot again afterward. Zero findings and valid mechanical validation-write markers need no extra reviewer.

zdev-audit starts one verifier, or one per explicit lens. Substantive findings receive the same independent check; a default audit with no findings and a lens audit whose reviewers all pass need no checking worker. These workers use the resolved profiles; zdev does not invent an auditor or advanced-verifier role.

The harness runtime owns child execution, cancellation, and delivery only. A child session, job, transcript, or agent ID is not zdev state. Audit reviewers are read-only. For a large boundary or an explicit swarm request, the coordinator may fan out independent audit lenses, but one fresh verifier checks and deduplicates their findings before they reach the user.

Result envelopes

The first line is the machine-checkable envelope. The remainder is concise Markdown evidence; harness-native structured output may carry the same fields, but must render this public form.

Workflow	Allowed first line	Required body
zdev-implement	PASS zdev-implement <area> <task-id> or BLOCKER zdev-implement <area> <task-id>	Exact repeated area/task fields, summary, changed files, validation, verifier evidence, and commit ID on pass; stage, reason, and preserved state on blocker.
zdev-verify	One coordinator-constructed strict verifier JSON object with verdict pass, rework, or blocker	Exact schema version, kind, area, task ID, summary, generated snapshot/advisory evidence, findings, and constrained escalation.
zdev-audit	PASS zdev-audit, FINDINGS zdev-audit, or BLOCKER zdev-audit	Boundary, what was inspected and omitted, and checked findings with location, impact, and confidence.

An implementer handoff has nine required JSON fields. Planners return the four semantic fields verdict, summary, plan, and findings; task verifiers return verdict, summary, findings, and escalation. Coordination extracts one balanced JSON object and validates the required fields. A short sentence or Markdown fence is harmless. It passes an accepted semantic plan unchanged to the advanced implementer and constructs the compatible nine-key public planner or verifier envelope itself. For verifier results it first compares the stored snapshot. Missing output, legacy or malformed JSON, duplicate or missing required keys, multiple objects, contradictory verdict or escalation, or an unavailable required artifact becomes a coordinator-generated BLOCKER. It is never interpreted as success.

Rework, retry, and completion

Each verifier rework result returns the concrete findings to the same implementer when the harness can preserve that worker context, or to a replacement implementer with the current goal, baseline, and full findings. Oh My Pi may message the existing implementer through hub; OpenCode may resume its implementer child; Codex and Claude Code may use their native follow-up mechanism. Pi starts a fresh child. A fresh verifier then performs a focused recheck of accepted corrections, affected contracts, and repair regressions, retaining conclusions for unchanged code and running required validation.

The ordinary cycle allows one full review, one correction pass, and one focused recheck. Remaining required corrections stop automatic repair with the task open and work preserved; another repair needs an explicit user continuation decision. Carry that stage through recovery and goal/loop continuation. Transport errors, unavailable models, permission failures, timeouts, and invalid envelopes are blockers when they prevent safe progress; zdev does not hide them behind blind transport retries or turn the adapter into a scheduler.

The shared review guidance watches for death loops across retries, worker replacement, recovery, and task splitting. A repeated failure needs a concrete changed approach and a checkable reason to retry. If that approach returns to the same failure without useful evidence, stop automatic retries and preserve the work. New task IDs or fresh workers do not reset the attempt history.

Only a verified pass allows zdev-implement to complete the task and run zdev commit. A completion or commit failure changes the public result to BLOCKER; the report names the successful verification and exact remaining state. zdev-verify and zdev-audit never change lifecycle state or commit. An audit also never creates tasks automatically; the user decides whether a checked finding should become durable work.

Unsupported facilities and fallback

If a named worker artifact is unavailable but the harness can start a fresh generic child with the required tools and resolved model controls, the coordinator supplies the same role prompt and records that fallback. If it cannot create a separate verification context, the workflow stops with BLOCKER; the coordinating model must not verify its own work and call that independent.

If a harness lacks a native goal, the JSON projection remains ordinary prompt context. If a model or effort is unavailable, the explicit worker-profile rules apply; there is no model search or silent substitution by zdev. If a native adapter is absent, the installed zdev skill follows the internal route contract directly and reports the bounded behavior it actually completed.

What stays common and what stays Claude-specific

The current Claude task and audit workflows contain portable ideas that every adapter keeps:

• a read-only preflight before delegation;
• one coordinator owning the baseline and task lifecycle;
• a separate implementation handoff and fresh evidence-based verification;
• a small verdict vocabulary with invalid output failing closed;
• task-owned rework followed by full verification;
• an audit fan-out followed by one evidence-vetting pass.

The JavaScript execution details stay Claude-specific: the literal meta block, global args, top-level await, agent(), pipeline(), labels, workflow progress rendering, and the plugin workflow namespace. Other adapters express the same sequence through their own skills, commands, prompts, and tools; the common contract does not imitate the JavaScript runtime.

Claude retains the canonical zdev-implement.js, zdev-verify.js, zdev-audit.js, and zdev-parallel.js scripts. The parallel workflow accepts an explicitly consented finite batch, overlaps bounded implementation lanes in ordinary assigned worktrees, and serializes transport, independent verification, completion, and commits in the authoritative checkout. One canonical continuation source renders zdev-loop.js and its zdev-goal.js alias. The implementation workflow keeps its deterministic preflight, implementation, fresh-verification, and while (REWORK) control flow, but routes agent() calls through the scoped named role, refreshes work-context before each handoff, validates the common envelopes, and returns the coordinator enough evidence to complete and commit. The audit workflow keeps its review-and-vet pipeline. These are native advantages, not behavior other harnesses must reimplement in JavaScript.

Versions inspected

Harness	Version and source revision
Codex	CLI 0.148.0 (rust-v0.148.0), release source revision 3ba0f711642a888aec92a611a3f3b2211157ff89, including the native multi-agent handlers. Release (accessed 2026-08-20).
Claude Code	Claude Code 2.1.237, source/changelog revision 770933ea1ad2fa7b858191e397a65e6644771c64; Claude Agent SDK 0.3.237, revision 591a180a197a73ce90042a6f97a7c59c100d2c3a. Claude Code release and SDK release (accessed 2026-08-20).
OpenCode	1.18.19, release source revision 2b72179c663cadcb54f54d9f19221b3fb3d11fb6. Release (accessed 2026-08-20).
Pi	0.84.2, release documentation/source revision 914cf1472e715297caa30db4b9535d534a9eb718. Release (accessed 2026-08-20).
Oh My Pi	17.4.0, source revision 72000acfeb902e21816252699482887f34d1a5a4. Release (accessed 2026-08-20).

The version numbers above are observation points, not minimum supported versions. Minimum supported versions need separate compatibility testing.

Observed harness capabilities

Codex

Codex supports reusable skills and native subagents. Skills are invoked with $name; the main thread can spawn, message, wait for, interrupt, and close agent threads. Project or skill instructions may request delegation, and a custom agent can set its own model, reasoning effort, instructions, and sandbox. The parent runtime still controls live approval and sandbox choices. Codex skills, subagent orchestration, and the pinned multi-agent spawn implementation (accessed 2026-08-20).

This is enough for a zdev skill to remain the coordinator and use fresh native workers. Zdev does not need an SDK process, task queue, or stored session ID.

Claude Code

Claude Code plugins can package skills, named agents, and JavaScript workflows. A workflow script lives in workflows/ at the plugin root by default; the manifest’s workflows string-or-array field can replace that default path. Plugin workflows are distributed and resolved under the plugin namespace, so meta.name = 'release-audit' in plugin acme-tools becomes /acme-tools:release-audit. The feature request that originally identified the distribution gap was closed as completed on 2026-08-17. Dynamic workflow distribution, plugin component paths, and Claude Code issue 66032 (accessed 2026-08-20).

Dynamic workflows require Claude Code 2.1.154 or later. Their runtime executes plain JavaScript with top-level await; meta supplies identity, args supplies invocation data, agent() starts a subagent, and pipeline() maps a list to agents. Script variables hold intermediate results, and the runtime keeps the orchestration repeatable and resumable within the session. Named plugin agents still provide the role prompts, tool constraints, models, and effort controls used by the workflow. Workflow behavior and API and plugin subagent configuration (accessed 2026-08-20).

Zdev uses native JavaScript workflows for Claude task work and audits. Named agents supply their roles and model settings.

OpenCode

OpenCode discovers Markdown commands from commands/; the file name becomes the slash command and its body becomes a prompt. It also discovers named Markdown subagents. A primary agent can invoke a subagent through the task tool, which creates a child session and returns its text. Supplying the prior task_id resumes that child; omitting it creates a fresh child. Background subagents remain experimental, but zdev’s sequential implementation and verification cycle does not need them. Commands, agents, and the pinned task-tool implementation (accessed 2026-08-20).

The OpenCode SDK can create sessions and send prompts or commands, including structured output. Those calls are useful for external applications, but the native command and task surfaces already cover zdev’s in-session workflow. OpenCode SDK (accessed 2026-08-20).

Pi

Stock Pi intentionally has no built-in subagent system. It supports skills, Markdown prompt templates, and TypeScript extensions that can register tools and commands. Its own subagent example starts a separate pi process with an isolated context and captures JSON output. Pi README and extension model and the pinned subagent extension example (accessed 2026-08-20).

Zdev follows that pattern with zdev_subagent: each call starts a no-session child with a restricted tool list. That gives implementation and verification fresh contexts, but it cannot resume an implementer for rework. A rework pass must start another child with the earlier findings and current checkout state.

Oh My Pi

Oh My Pi has native task and hub tools. task discovers named agents, supports blocking or background execution, returns structured result details, and can keep a completed non-isolated agent available. hub can message a finished agent and revive it when necessary. Custom prompt templates under .omp/prompts/ expand as slash commands. Pinned task documentation, hub documentation, agent discovery, and the pinned prompt-template loader (accessed 2026-08-20).

Oh My Pi also offers background jobs, batch fan-out, isolation, process supervision, and session artifacts. None is required for the ordinary zdev cycle. The adapter should use blocking named workers in the current checkout; zdev, not Oh My Pi’s job system, remains the workflow owner.

Confidence and limitations

The common workflow and installation rules follow the cited documentation and pinned source. Compatibility over time is less certain: several features were experimental or recently changed at the research date.

This investigation did not execute the five harnesses against live provider accounts. Claude Code’s main runtime is distributed as a compiled package, so its plugin documentation and public changelog provide stronger evidence than source inspection for plugin discovery. The current official workflow and plugin references explicitly document the plugin-root workflows/ directory, manifest field, and namespaced invocation, and issue 66032 is completed; those sources support retaining the canonical JavaScript route in 2.1.237. OpenCode background agents, Oh My Pi background jobs, and native session-goal behavior were not selected because the current sequential workflow does not need them.

Claude serial research coordination

The installed zdev-research workflow composes the canonical ordinary one-task body for supporting work and coordinates hypotheses through the binary lifecycle. It uses only args and sequential agent calls. Resolve all five native Claude roles before dispatch and pass retained concrete model/effort options to each planner, implementer and verifier. Each supporting dispatch and hypothesis retry has a fresh reservation before launch; begin charges initial candidate preparation and evaluate charges correctness/evaluator commands. Only proposed keep gets a fresh independent acceptance verifier with strict snapshot equality.

Pause/continue of live execution uses Claude controls. After stop/failure, use a new resume invocation identity with the same durable run and recover live effects before another reservation. Claude can replay completed cached agent calls on recovery, so restarting an interrupted worker with its old reservation would be unsafe accounting. The installed reference documents a bounded one foreground work-item fallback when packaged execution is unavailable. It has no /goal dependency or invented shell/clock/cancellation APIs. Deterministic command tests and authenticated provider execution are separate evidence. See Claude workflow execution and plugin workflow discovery.