wiff: Instructions file for Codex

AGENTS.md

Instructions for coding agents. Two audiences: agents orchestrating with wiff from a harness, and agents working on this codebase.

Orchestrating with wiff (driving it from a harness)

wiff exposes five MCP tools through a disposable stdio bridge: workflow_start, workflow_status, workflow_wait, workflow_cancel, and workflow_models. The bridge auto-starts a detached local daemon that owns workflow execution, so runs survive the launching harness or MCP process exiting. You author a workflow as a plain JavaScript script and pass it to workflow_start with an absolute cwd; everything persists under ~/.wiff/runs/<runId>/.

Before authoring a script, read plugins/wiff/skills/workflow/references/api.md — it is the full script contract. Inside Codex the bundled $workflow skill loads it for you; from any other harness, read it (or copy the skill into your harness's skills directory).

Rules that catch agents out:

• Workflow code is sandboxed. No imports, filesystem, shell, network, time, or randomness inside the script — those all throw. Agents do the external work; the script only orchestrates.
• Give every agent() call a stable key. Keys are the resume/cache identity. A run resumed after a crash or script edit replays completed agents with unchanged (key, input) for free; without keys you re-pay for everything.
• parallel() takes thunks (() => agent(...)), not started promises, and preserves result order. Any rejection fails the workflow with AggregateError — that is deliberate (fail-hard). Use parallelSettled() only when the script explicitly handles per-item failure.
• Defaults: model gpt-5.6-sol, effort medium, sandbox read-only, 10-minute execution timeout after queue admission. Set effort: "low" for mechanical work and effort: "high" for deep review or synthesis; raise the sandbox to workspace-write only for agents that must edit files.
• Concurrent writers need isolation: "worktree". Each writing agent gets a fresh detached git worktree; clean ones vanish, dirty ones are kept and listed on the run for you to inspect or merge. Requires cwd to be inside a git repository.
• Deterministic scripts resume. To pick up a dead or cancelled run: workflow_start with { resumeFromRunId }. Completed agents replay from the journal; agents interrupted mid-turn re-run with a digest of their previous transcript injected.
• Concurrency is capped at min(16, max(2, cores − 2)) running children (excess queue), and a run may request at most 1000 agents.
• Personas (agentType: "name") resolve from <cwd>/.codex/agents/<name>.md, then ~/.codex/agents/<name>.md (CODEX_WORKFLOW_AGENTS_DIR overrides). Editing a persona invalidates the cache of agents that use it.
• Don't poll blindly. workflow_wait blocks up to 55 s for a state change; loop on it rather than hammering workflow_status.
• The parent may disconnect. Preserve the runId before ending the parent turn. A later MCP bridge can wait, inspect, or cancel the same daemon-owned run. Graceful daemon restarts resume durable active runs; abrupt daemon death leaves them safely interrupted for explicit resume.
• The first bridge supplies daemon environment. The daemon inherits that bridge's PATH, backend credentials, and Wiff/Codex environment defaults until it restarts. If those values change, gracefully terminate the pid in ~/.wiff/daemon.json or wait for idle shutdown before starting new work.
• Inspect failures from disk. ~/.wiff/runs/<runId>/journal.jsonl records every phase/agent event with input hashes and token usage; agents/*.jsonl hold full per-child transcripts. Read those before re-running anything.