/harness-loop

name: harness-loop
description: "Long-running task loop using /loop (Claude Code dynamic mode) and ScheduleWakeup to re-enter with fresh context on each wake-up. Internally invokes harness-work through Agent. Trigger: long-running, loop, wake-up, autonomous. Do NOT load for: one-shot task execution, review, release, planning."
description-en: "Long-running task loop using /loop (Claude Code dynamic mode) and ScheduleWakeup to re-enter with fresh context on each wake-up. Internally invokes harness-work through Agent. Trigger: long-running, loop, wake-up, autonomous. Do NOT load for: one-shot task execution, review, release, planning."
description-ja: "長時間タスクを /loop と ScheduleWakeup で wake-up 毎に fresh context で再入実行。harness-work を内部で Agent 呼び出し。長時間、ループ、loop、wake-up、autonomous に対応。"
kind: workflow
purpose: "Re-enter long-running Plans.md execution with fresh context"
trigger: "long-running, loop, wake-up, autonomous"
shape: delegate
role: orchestrator
base: harness-work
pair: harness-sync
owner: harness-core
since: "2026-05-05"
allowed-tools: ["Read", "Edit", "Bash", "Task", "ScheduleWakeup", "mcp__harness__harness_mem_resume_pack", "mcp__harness__harness_mem_record_checkpoint"]
argument-hint: "[all|N-M] [--max-cycles N] [--pacing worker|ci|plateau|night]"
user-invocable: true

harness-loop

`/loop`（CC dynamic mode）と `ScheduleWakeup` を組み合わせ、 長時間タスクを **wake-up 毎に fresh context で再入実行** するメタスキル。

各 wake-up で `harness-work --breezing` を Agent 経由で呼び出し、 1 サイクル = 1 タスク完結の再入可能ループを構成する。

> **Long-session helpers (CC 2.1.108+)**: > 人が戻ってきたら `/recap` で要約を取り直してから `/harness-loop status` を見る。 > 長めの離席や再入が多い運用では `ENABLE_PROMPT_CACHING_1H=1` を優先する。

> **長時間セッション推奨 (CC 2.1.108+)**: > セッション長が 30 分を超える見込みの場合、plugin bundle root 解決後に `bash "${HARNESS_PLUGIN_ROOT}/scripts/enable-1h-cache.sh"` を実行して 1 時間 prompt cache を opt-in すること。

> **Codex 0.123.0 automatic bug fix inheritance**: > manual shell follow-up queue と `/copy` after rollback は Codex 本体の TUI 修正として自動継承する。 > loop runner は追加入力 queue、copy wrapper、rollback workaround を追加しない。 > 長時間作業中に manual shell へ follow-up を投げた時の queueing は Codex runtime に任せる。

Quick Reference

| 入力 | 動作 | |------|------| | `/harness-loop all` | 全未完了タスクをループ実行（default: max 8 サイクル） | | `/harness-loop all --max-cycles 3` | 3 サイクルで停止 | | `/harness-loop 41.1-41.3 --pacing ci` | タスク範囲を CI pacing で実行 | | `/harness-loop all --plan roadmap` | named Plans の `roadmap` を対象にループ実行 | | `/harness-loop all --pacing night` | 深夜バッチ（3600s 間隔） | | `/harness-loop status` | 進行中ランナーの状態確認 | | `/harness-loop stop` | 進行中ランナーの停止要求 |

オプション

| オプション | 説明 | デフォルト | |----------|------|----------| | `all` | 全未完了タスクを対象 | - | | `N-M` | タスク番号範囲指定 | - | | `--plan NAME` | `plans/manifest.json` の named plan を使う | active/default | | `--max-cycles N` | 最大サイクル数 | `8` | | `--pacing <mode>` | wake-up 間隔モード | `worker`（270s） |

pacing 値マッピング

| pacing | delaySeconds | 用途 | |--------|-------------|------| | `worker` | 270 | Worker 完了直後（5 min 以内で cache warm） | | `ci` | 270 | CI 短時間ジョブ待ち | | `plateau` | 1200 | 20 min（plateau 検知後の再試行間隔） | | `night` | 3600 | 深夜の長時間放置 |

> **制約**: `ScheduleWakeup` の `delaySeconds` はランタイムで **[60, 3600]** に clamp される。 > `worker` / `ci` の 270s および `night` の 3600s はこの範囲内。 > `plateau` の 1200s も範囲内。値を直接指定する場合は必ず 60 以上 3600 以下にすること。

起動フロー（wake-up 毎のエントリ）

詳細版: [`${CLAUDE_SKILL_DIR}/references/flow.md`](${CLAUDE_SKILL_DIR}/references/flow.md)

plugin bundle root 解決

`harness-loop` は host project の cwd ではなく、plugin bundle root 配下の helper script を呼ぶ。 たとえると、作業机（host project）と工具箱（plugin bundle）を分けて扱う。

各 wake-up の冒頭で次の順に `HARNESS_PLUGIN_ROOT` を決める:

1. `CLAUDE_PLUGIN_ROOT` があり、`scripts/` を含むならそれを使う 2. `CLAUDE_PLUGIN_ROOT` がなければ、`CLAUDE_SKILL_DIR` から plugin bundle root を逆算する

• `skills/harness-loop` 配布なら `${CLAUDE_SKILL_DIR}/../..`
• `.agents/skills/harness-loop` mirror 配布なら `${CLAUDE_SKILL_DIR}/../../..`

3. どちらでも解けない場合は停止し、`CLAUDE_PLUGIN_ROOT` を plugin bundle root に設定して再実行する

`Plans.md` と `.claude/state/...` は host project 側に置く。 helper script だけを `${HARNESS_PLUGIN_ROOT}/scripts/...` から呼ぶ。

複数 Plans.md がある repo では、長時間 run の起動時に `--plan NAME` を明示する。 runner は開始時に解決した Plans file を cycle 間で保持するため、途中で active plan を切り替えない。

各サイクルは選択済み plan と最新の実行状態を読み、原依頼の目的、担当範囲、DoD、spec、証拠、承認の参照を Worker / Advisor に渡す。 再開時は既に決まった方針と理由、失敗した方法、未解決事項、直前の advisor response も回収する。前回の助言で元の契約を置き換えない。 承認済み可逆作業は再確認せず進める。不足は読み取りで補い、軽微な仮定と仕様・権限の判断を区別する。未承認の保護操作や `STOP` は既定の停止条件を守る。 必要なチェックとレビューを満たした task に追加機能や無条件の再テストを足さない。起動、実行中、検証済み完了を分けて報告する。

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}\n内容と目的: <選択済み Plans.md の内容・理由>\n担当範囲: <owned paths と除外範囲>\nDoD: <Plans.md から抽出>\nplan/spec: <選択済みパス>\ncontract_path: ${CONTRACT_PATH}\n証拠と前