| name | long-run-harness-execution |
| description | Use when running multi-hour or multi-session agent workflows that require planner-generator-evaluator orchestration, resumable artifacts, and optimized tool selection. |
Long-Run Harness Execution
Use this skill to execute long-running autonomous work with explicit contracts, independent evaluation, and resumable progress.
Bundled Resources
Load these resources before running orchestration:
When To Use
- tasks are expected to run across long sessions
- scope is too large for single-pass implementation
- quality must be validated by an independent evaluator
- resumable state and deterministic handoff are required
Do not use this skill for small one-shot tasks.
Core Architecture
- coordinator orchestrates run lifecycle and escalation
- planner expands objectives into backlog and sprint contracts
- generator implements one sprint contract at a time
- evaluator validates independently and can fail the sprint
- coordinator mediates all planner/generator/evaluator handoffs
Tool Selection Optimization
Use the minimum-cost tool that can provide sufficient evidence.
Tier 0
- local read and search for repository facts and code patterns
Tier 1
- context7 for framework behavior uncertainty
- brave-search for external standards and prior art
Tier 2
- execute for deterministic checks and reproducible validation
Tier 3
- playwright for interaction verification only when acceptance criteria require it
Escalate tool tier only when prior tier evidence is insufficient, and record why.
Required Artifacts
- run-manifest.md
- objective, constraints, acceptance criteria, stop conditions, budget limits
- backlog.md
- prioritized items with dependencies and gate mapping
- sprint-contract.md
- scope, done criteria, verification criteria for current sprint
- heartbeat.md
- progress, blockers, next action, budget usage
- resume-token.md
- last accepted sprint, unresolved defects, deterministic next step
All required artifact fields are valid only when present and non-empty.
Use the templates in templates/ as the default artifact shape.
Handoff Contract
Request Envelope
task_id: string
parent_task_id: string | null
caller_agent: string
target_agent: string
objective: string
constraints:
- string
success_criteria:
- string
input_context_ref:
- path-or-artifact
timeout_s: number
max_turns: number
objective_signature: string
Return Envelope
status: done | blocked | needs-human | failed
sprint_state: accepted | failed | cancelled | needs-human | null
summary: string
artifacts:
- path-or-artifact
failure_reason: string | null
next_agent: string | null
proof_refs:
- path-or-command
gate_scores:
functionality: number
coverage: number
regression: number
evidence: number
overall_gate_result: pass | conditional | fail
defect_count: number
evaluator_independence_claim:
basis: string
potential_conflicts:
- string
attempt_index: number
max_fix_attempts: number
Status Semantics
- status is transport state for envelope routing
- sprint_state is coordinator verdict for run progression
- done: all criteria met with proof
- blocked: dependency or proof gap prevents completion
- needs-human: decision or credential required from user
- failed: work completed but criteria not met
Evaluator scoring thresholds:
- pass: all gate scores >= 0.85 and no unresolved critical defect
- conditional: all gate scores >= 0.70, no critical defect, and <=2 non-critical defects
- fail: any gate score < 0.70 or any unresolved critical defect
Gate consistency rules:
- overall_gate_result must match gate_scores and defect_count
- mismatched gate payloads are treated as failed and returned for correction
- non-empty evaluator_independence_claim.potential_conflicts requires needs-human escalation
Retry and Escalation
- enforce
max_fix_attempts per sprint (default 2, hard max 3)
- retry only while
attempt_index < max_fix_attempts
- if
attempt_index >= max_fix_attempts, force sprint state to failed
- escalate to user only for true human-only decisions or evaluator conflicts
- stop run if budget, safety, or quality bounds are exceeded
Checkpoint Discipline
- use fail-closed checkpoints
- do not claim success without explicit proof
- use blocked state when proof is missing
- carry unresolved blockers into next-step guidance
- refresh heartbeat after each evaluator verdict
- refresh resume-token after each accepted sprint and before any context reset
- after each meaningful accepted sprint, provide concise closure, validation status, and one short next-step question
- wait for user confirmation before broadening scope beyond current sprint boundaries
- ask before dependency additions, destructive operations, or broad validation outside sprint criteria
Expansion Risk Tiers
Ask before expansion using tiered boundaries:
| Tier | Trigger | Confirmation Requirement |
|---|
| LOW | Within approved sprint contract and touched-file verification scope | Continue at normal checkpoint cadence |
| MEDIUM | Additional modules or tests outside sprint contract | Ask one short next-step question and wait for explicit confirmation |
| HIGH | Architecture/public contract changes, dependencies, destructive operations, or broad validation | Ask before expansion and require explicit user confirmation |
Verification Checklist
- contracts are present and complete
- status vocabulary is consistent
- evaluator gate decision is explicit
- heartbeat and resume-token reflect current state
- tool tier escalations are justified
Quick deterministic checks:
python scripts/envelope_check.py request <request_json>python scripts/envelope_check.py return <return_json>
Recommended Pairings
- workflow-governor for workflow-surface hygiene before or after rollout
- validate-skills for new skill validation
- subagent-orchestration-contracts for envelope consistency across agent surfaces
- use the bundled references and templates before first sprint dispatch
