Use this skill for long-running work that must survive fresh contexts, background relaunches, or planned handoffs. Do not use it for one-shot Q&A.
When To Use
- Unattended improve-verify loops
- Overnight debugging, fixing, auditing, or shipping work
- Resume from durable state after a fresh Codex session
- Background runs that should relaunch fresh
codex execsessions - Scoped multi-agent inspection, verification, or review
What This Skill Owns
- Persistent run control through
scripts/harness_run_ctl.py - Durable state under
.harness-run/ - Run-local collaboration docs under
.harness-run/docs/ - Per-round evidence, generated knowledge, and design notes under
.harness-run/evidence/,.harness-run/generated/, and.harness-run/design/ - Foreground and background parity
- Resume, status, stop, and handoff behavior
- One-round-at-a-time improve-verify loops
User Entry
run-task: start a durable run with one natural-language goal;--verifyis optionalstatus: inspect the current run in human-readable formstop: stop the current run cleanly
Normal users should not have to operate internal commands or design a full launch contract. When this skill triggers, accept a goal-only request, infer the plan, scope, metric, and verification approach from project evidence, run the helper script yourself, and report the durable state paths plus the current status. Only mention internal commands when debugging or when a fresh Codex session must reconstruct the runtime prompt manually.
Every run initializes a mini collaboration record under .harness-run/docs/. This record is the run-local equivalent of a project docs system: architecture snapshot, run plan, constraints, validation pipeline, progress, decisions, handoff, completion, and sync policy. If the target repo has its own docs/, keep .harness-run/docs/ as the execution layer and sync only concise summaries when the run's sync-policy.md allows it.
Launch Contract
Only Goal is required from the user. Infer these fields before starting:
GoalScopeMetricDirectionVerify
Optional fields:
GuardIterationsStop conditionRun modeExecution policy
If a field can be inferred safely, infer it. If scope is unclear, default to the current repo or current working directory and narrow it after reading evidence. If verification is unclear, do not block launch; use plan/checklist completion with concrete evidence. Ask only when continuing would likely produce work opposite to the user's intent.
If the user explicitly says to follow a directory, plan file, roadmap, issue list, checklist, or existing project plan, treat that plan as authoritative scope and sequence. Read it, follow it, and do not renegotiate the plan unless it contradicts safety, repo instructions, or executable evidence.
Default execution policy is workspace_write. Do not use danger_full_access unless the user explicitly requests or accepts that elevated background risk; that mode injects Codex's dangerous bypass argument into nested codex exec sessions.
Default stop behavior:
- when
direction=pass, the run stops once verification passes - when
direction=complete, the run stops once the recorded metric reaches completion - when
verifyis provided andmetricis omitted, the verify command itself is used as the tracked metric label - when
verifyis omitted, usemetric=planned work checklist,direction=complete,stop_condition=complete, and recordcompleteonly after the inferred or user-specified plan is satisfied with evidence - background runs default to an iteration cap of 25 when no explicit cap is provided
Quick Start
Background:
- Start with
run-task. - Use
statusto inspect the runtime andstopto end it. - If the process stops on
needs_human, read.harness-run/runtime.log,.harness-run/state.json, and.harness-run/rounds.tsvbefore continuing. - Read
.harness-run/docs/handoff.md,.harness-run/docs/run-plan.md, and.harness-run/docs/constraints.mdbefore resuming work.
Foreground:
run-task --foregroundprepares the durable run in the current Codex session.- Read the repo
AGENTS.md, current source, build/test config, and recent logs. - Measure the baseline.
- Initialize state after the baseline exists.
- Run one focused change, verify with the command or evidence checklist, and record the result.
- Update
.harness-run/docs/handoff.mdevery round; update progress, decisions, constraints, and architecture only when facts change. - Repeat from persisted state.
Common commands:
python <skill-root>/scripts/harness_run_ctl.py run-task --goal "<goal>"
python <skill-root>/scripts/harness_run_ctl.py run-task --foreground --goal "<goal>"
python <skill-root>/scripts/harness_run_ctl.py run-task --goal "<goal>" --verify "<command>"
python <skill-root>/scripts/harness_run_ctl.py run-task --foreground --goal "<goal>" --verify "<command>"
python <skill-root>/scripts/harness_run_ctl.py status
python <skill-root>/scripts/harness_run_ctl.py stop
Durable State
All normal run artifacts live under:
<workspace_root>/.harness-run/
Files:
launch.json: confirmed launch manifeststate.json: primary recovery snapshotrounds.tsv: append-only audit trailruntime.json: background controller pid, status, and last decisionruntime.log: controller and nested Codex outputcontext.json: canonical path map for the active rundocs/: run-local collaboration docs and handoff recordsevidence/: concise per-round evidence notesgenerated/: generated knowledge snapshots with source commandsdesign/: design notes too large for the decision log
Each managed git repo may also get a git-local pointer at:
git rev-parse --git-path harness-run/pointer.json
That pointer resolves back to the workspace-owned context.json.
The run-local docs are initialized from templates in references/templates/. They are not a replacement for target repo docs. They are the durable execution record that lets fresh Codex sessions continue without hidden conversation state.
Core run docs:
project-architecture.mdproduct-context.mdrun-plan.mdconstraints.mdchange-inventory.mdvalidation-pipeline.mdoperability.mdsecurity-boundary.mdsync-policy.mdprogress.mddecisions.mdhandoff.mdcompletion.md
Round Rules
- Rebuild context from source files, logs, tests, and durable state.
- Read
.harness-run/docs/constraints.md,run-plan.md,project-architecture.md,validation-pipeline.md, andhandoff.mdbefore editing. - Establish or refresh the baseline before mutating anything.
- If verification is unclear, create or infer an execution checklist and evidence checklist before editing.
- Make one focused change or one falsifiable diagnosis.
- Verify mechanically when a command exists; otherwise verify by concrete evidence such as file inventory, diff review, build feasibility, sample output, screenshots, generated reports, or checklist completion.
- Keep, discard, block, or mark no-op.
- Record exactly one outcome before the next round.
- For partial goal-only rounds, use
refine,search, orpivotwithmetric=incomplete; do not usekeepuntil the metric is actuallycomplete. - Update
handoff.mdevery round. Update at least one progress/evidence artifact each recorded round:progress.md,decisions.md,change-inventory.md,run-plan.md,completion.md, or.harness-run/evidence/round-XXXX.md. - Keep raw logs and secrets out of Markdown docs; summarize only redacted facts.
- Never leave the next round dependent on hidden conversation state.
Internal Control Plane
The skill keeps the heavier runtime protocol in references/runtime-loop.md and the helper script.
run-taskis the user entry. It creates or resumes the durable run and starts the background controller by default.create-launch,launch,start,controller,init-state,record, andresume-promptare internal or advanced commands.- The controller loop survives Codex context limits by relaunching fresh
codex execsessions from.harness-run/. needs_humanmeans the controller stopped on a real blocker, inconsistent state, missing run artifacts, stale controller process, or stagnation, not that the user should keep waiting.
Typical flow:
- Use
run-task. - Check
statusif you need a progress summary. - Use
stopwhen you want to end the run. For a prepared foreground run,stopclears the prepared state even when no background controller exists. - If a fresh Codex session must continue manually, use the internal
resume-promptcommand or read.harness-run/state.json.
Repeated starts:
- running
run-taskagain with the same goal, scope, and verify command reuses the existing run - running goal-only again with the same goal and scope reuses the existing plan/checklist run
- running it with a different behavior contract stops with
needs_humaninstead of mixing state; contract comparison includes goal, scope, verify, metric, direction, guard, iterations, stop condition, execution policy, and codex args - advanced fresh starts can pass
--force, which archives existing.harness-runfiles before creating the new run --forcerefuses to archive while a background controller is still active; runstopfirst
Multi-Agent Mode
- Delegate only independent side work.
- Use one agent for bounded source inspection, one for log or test verification, or one for review when those paths do not overlap.
- Do not duplicate the same investigation in multiple agents.
- Merge useful findings into durable state before the next round.
Resume Discipline
- Resume from
.harness-run/state.json,.harness-run/rounds.tsv, and.harness-run/launch.json, not from conversation memory. - Re-read the state file, latest rounds, latest logs,
docs/handoff.md,docs/run-plan.md,docs/constraints.md, anddocs/project-architecture.mdbefore changing anything. - If evidence is missing, collect it first.
- If the harness state is inconsistent, stop as
needs_humanrather than inventing a recovery path.
Boundary
harness-run makes runs resumable and can keep relaunching Codex while the Python controller and machine stay alive. It does not auto-restart after reboot, logout, or process termination. That is acceptable for this skill: after a reboot, manually start a fresh Codex session, read .harness-run/state.json, .harness-run/rounds.tsv, and .harness-run/launch.json, then continue with run-task using the same goal. It also does not prove semantic task completion by itself; completion still requires run-plan.md, completion.md, verification output, and evidence artifacts to support the final complete metric.
References
- references/runtime-loop.md: launch contract, state files, round protocol, supervisor decisions, and prompt template
- references/collaboration-protocol.md: run-local collaboration discipline and update cadence
- references/run-docs-protocol.md:
.harness-run/docs/file roles and sync boundaries - references/recovery-runbook.md:
needs_human, stale runtime, and recovery rules - references/persistence-and-redaction.md: local-only files, redaction, and repo-sync safety