SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsharness-loop

harness-loop

Agents & models

View repository

Updated 10-15 17:33

About this skill

harness-loop

/loop（CC dynamic mode）と ScheduleWakeup Combine, and for long-running tasks re-enter and execute with fresh context on each wake-up meta-skill that does.

On each wake-up, harness-work --breezing is called via the Agent, forming a re-entrant loop where 1 cycle = 1 completed task.

Long-session helpers (CC 2.1.108+): When a person comes back, /recap re-acquire the summary with /harness-loop status then check ENABLE_PROMPT_CACHING_1H=1 In operations with longer absences or many re-entries, prioritize

Long session recommended (CC 2.1.108+): If the session length is expected to exceed 30 minutes, after resolving the plugin bundle root, run bash "${HARNESS_PLUGIN_ROOT}/scripts/enable-1h-cache.sh" to opt in to the 1-hour prompt cache.

Codex 0.123.0 automatic bug fix inheritance: manual shell follow-up queue と /copy after rollback is automatically inherited as a Codex core TUI fix. The loop runner does not add an additional input queue, copy wrapper, or rollback workaround. When a follow-up is sent to a manual shell during long-running work, queueing is left to the Codex runtime.

Quick Reference

Input Behavior
/harness-loop all Run all incomplete tasks in a loop (default: max 8 cycles)
/harness-loop all --max-cycles 3 Stop after 3 cycles
/harness-loop 41.1-41.3 --pacing ci Run the task range with CI pacing
/harness-loop all --plan roadmap named Plans の roadmap Run in a loop targeting
/harness-loop all --pacing night Late-night batch (3600s interval)
/harness-loop status Check the status of a running runner
/harness-loop stop Request to stop a running runner

Options

Options Description Default
all Targets all incomplete tasks -
N-M Task number range specification -
--plan NAME plans/manifest.json Use the named plan of active/default
--max-cycles N Maximum number of cycles 8
--pacing <mode> Wake-up interval mode worker（270s）

pacing value mapping

pacing delaySeconds Purpose
worker 270 Immediately after Worker completion (cache warm within 5 min)
ci 270 Waiting for a short CI job
plateau 1200 20 min (retry interval after plateau detection)
night 3600 Long unattended late-night run

Constraints: ScheduleWakeup の delaySeconds is clamped at runtime to [60, 3600] . worker / ci of 270s and night The 3600s of is within this range. plateau The 1200s of is also within range. When specifying the value directly, always make it 60 or more and 3600 or less.

Startup flow (entry on each wake-up)

Detailed version: ${CLAUDE_SKILL_DIR}/references/flow.md

plugin bundle root resolution

harness-loop calls a helper script under the plugin bundle root, not the cwd of the host project. To put it another way, treat the work desk (host project) and the toolbox (plugin bundle) separately.

At the beginning of each wake-up, determine HARNESS_PLUGIN_ROOT in the following order:

  1. CLAUDE_PLUGIN_ROOT exists, andscripts/ If it contains , use that
  2. CLAUDE_PLUGIN_ROOT if there is noCLAUDE_SKILL_DIR Derive the plugin bundle root from
    • skills/harness-loop For distribution, ${CLAUDE_SKILL_DIR}/../..
    • .agents/skills/harness-loop For mirror distribution, ${CLAUDE_SKILL_DIR}/../../..
  3. If neither can resolve it, stop, setCLAUDE_PLUGIN_ROOT as the plugin bundle root, and re-run

Plans.md と .claude/state/... is placed on the host project side. Only the helper script is called from ${HARNESS_PLUGIN_ROOT}/scripts/... .

In a repo with multiple Plans.md files, specify --plan NAME when starting a long-running run. The runner retains the Plans file resolved at start across cycles, so do not switch the active plan midway.

wake-up
  │
  ▼
[Step 0] plugin bundle root を HARNESS_PLUGIN_ROOT に解決
  CLAUDE_PLUGIN_ROOT が有効ならそれを使用
  なければ CLAUDE_SKILL_DIR から plugin bundle root を逆算
  ※ host project cwd の scripts/ は参照しない
  │
  ▼
[Step 1] Plans.md を先に読む
  cc:WIP / cc:TODO の先頭タスクを特定（task_id を得る）
  ※ 未完了タスクなし → ループ終了（正常完了）
  │
  ▼
[Step 2] sprint-contract 存在確認 & 生成
  .claude/state/contracts/${task_id}.sprint-contract.json の有無を確認
  無ければ node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" ${task_id} で生成
  生成直後（初回のみ）: bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" <contract-path> \
    --check "wake-up 自動承認（harness-loop のため DoD を reviewer 観点で確認）" \
    --approve  ← draft → approved に昇格
  （既存 contract は approved 済みのためスキップ）
  │
  ▼
[Step 3] contract readiness チェック
  bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" <contract-path>
  │
  ▼
[Step 4] Resume pack 再読込
  harness-mem resume-pack（コンテキスト再注入）
  │
  ▼
[Step 4.5] Advisor consult（必要時のみ）
  高リスク task の初回実行前 / 同じ原因の 2 回目失敗後 / plateau 直前で
  `advisor-request.v1` を組み立てて相談する
  │
  ├── PLAN        → 次回 executor prompt に advice を prepend
  ├── CORRECTION  → 局所修正の指示として再実行
  └── STOP        → その場で loop を停止し、理由を残す
  │
  ▼
[Step 5] 1 タスクサイクル実行
  worker_result = Agent(
      subagent_type="claude-code-harness:worker",  # worker エージェント（harness-work ではない）
      prompt="タスク: ${task_id}\nDoD: <Plans.md から抽出>\ncontract_path: ${CONTRACT_PATH}\nmode: breezing",
      isolation="worktree",
      run_in_background=false
  )
  # worker_result: { commit, branch, worktreePath, files_changed, summary }
  │
  ▼
[Step 5.5] Lead レビュー実行
  diff_text = git show worker_result.commit
  verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
  ※ 詳細は flow.md 参照
  │
  ▼
[Step 5.6] APPROVE → main に cherry-pick / REQUEST_CHANGES → 修正ループ（contract の max_iterations 回、デフォルト 3）
  APPROVE: git cherry-pick → Plans.md を cc:完了 [{hash}] に更新 → feature branch 削除
  REQUEST_CHANGES x MAX_REVIEWS 後も否決: エスカレーション
  ※ 詳細は flow.md 参照
  │
  ▼
[Step 6] plateau 判定
  bash "${HARNESS_PLUGIN_ROOT}/scripts/detect-review-plateau.sh" ${current_task_id}
  │
  ├── PIVOT_REQUIRED（exit 2）  → ループ停止 + ユーザーエスカレーション
  ├── INSUFFICIENT_DATA（exit 1）→ 続行
  └── PIVOT_NOT_REQUIRED（exit 0）→ 続行
  │
  ▼
[Step 7] サイクル数チェック
  │
  ├── cycles >= max_cycles → ループ停止（上限到達）
  │
  ▼
[Step 8] checkpoint 記録
  harness_mem_record_checkpoint(
      session_id, title, content=サイクル結果サマリ
  )
  │
  ▼
[Step 9] 次 wake-up 予約
  ScheduleWakeup(
      delaySeconds=<pacing値>,
      prompt="/harness-loop <同じ引数>",
      reason="サイクル {N}/{max} 完了 — 次タスクへ"
  )

Cycle Stop Conditions

Condition Stop Type Handling
cycles >= max_cycles Normal stop (limit reached) Report to user
PIVOT_REQUIRED（exit 2） Abnormal stop (escalation) Ask user for a decision
No incomplete tasks Normal stop (all complete) Output completion report

--max-cycles 3 When specified, stop after 3 cycles are completed. default (--max-cycles 8) stops after 8 cycles.

Interim Reports / Silence Policy

In long-running loops, interim reports are treated not as a "heartbeat for reassurance" but as a "notification when the judgment has changed." In environments where a Codex 0.123.0 background agent can receive transcript deltas, do not reply merely because a delta arrived; when unnecessary, remain explicitly silent.

Things to report:

  • cycle completion, limit reached, all complete, blocked
  • validation failure、review REQUEST_CHANGES、plateau、advisor STOP
  • advisor / reviewer drift、contract readiness failure
  • user が status summary when requested

Things that may remain silent:

  • When only transcript deltas have increased and the task / review / advisor state has not changed
  • When only fine-grained stdout that remains in the log has increased
  • While pacing and waiting until the next wake-up

The default is "one final report per cycle." However, an unanswered Advisor request, an unreceived Reviewer result, or a warning just before plateau takes priority over the silence policy and is reported.

Cooperation with /loop

This skill is the CC's /loop(dynamic mode).

/loop is enabled, CC continues autonomous re-entry execution, and by calling ScheduleWakeup at the end of each cycle, it schedules the next wake-up.

/loop sentinel: <<autonomous-loop-dynamic>>

Each wake-up starts with fresh context , preventing context contamination from the previous cycle. harness-mem resume-pack reloading of the resume pack is mandatory (Step 2).

checkpoint recording

harness_mem_record_checkpoint schema:

{
  "session_id": "<セッション ID>",
  "title": "harness-loop cycle {N}/{max}: {タスク名}",
  "content": "cycle_result の 1 行サマリ + commit hash"
}

Advisor Strategy

The main actor of this skill is the executor, and the advisor is called only when necessary. To put it another way, the person in charge usually runs autonomously and consults a veteran only at difficult points.

Consultation conditions are fixed, and natural-language "low confidence" judgments are not used.

Condition Whether to consult
needs-spike / security-sensitive / state-migration to do
<!-- advisor:required --> to do
Second failure with the same cause to do
Immediately before stopping due to plateau to do

The same trigger is consulted on only once. For that determination, use trigger_hash = task_id + reason_code + normalized_error_signature .

Related Skills

  • harness-work — Task implementation skill executed in each cycle
  • harness-plan — Planning of loop target tasks
  • harness-review — Review of individual tasks
  • session-control — Session state management