Skip to main content ホーム クリエイター chachamaru127 claude-code-harness harness-work
harness-work HAR: Execute Plans.md tasks from single task to full parallel team run. Trigger: implement, execute, do everything, breezing, team run, parallel, composer, composer 2.5. Do NOT load for: planning, review, release, setup.
インストールへ移動 Skills Marketplace コミュニティが作成したAIスキルを発見・探索
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/Chachamaru127/claude-code-harness --skill harness-workコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Zipをダウンロード ダウンロード中...
Generate an Acceptance Demo HTML for non-engineer vibecoders right before ship/wait/reject decision. Reads back the acceptance_criteria that were stored as personal-preference.v1 by harness-plan-brief (joined by user_request_hash), then renders a single-file HTML showing each criterion as verified or unverified along with a ship/wait/reject recommendation. Use when the user asks for an acceptance review, wants to decide whether to ship a delivered task, or says: acceptance demo, accept demo, 受け入れ判断, 受入レビュー, ship/wait/reject 判定, 検収レビュー. Do NOT load for: implementation, code review, release work.
name harness-work description HAR: Execute Plans.md tasks from single task to full parallel team run. Trigger: implement, execute, do everything, breezing, team run, parallel, composer, composer 2.5. Do NOT load for: planning, review, release, setup. description-en HAR: Execute Plans.md tasks from single task to full parallel team run. Trigger: implement, execute, do everything, breezing, team run, parallel, composer, composer 2.5. Do NOT load for: planning, review, release, setup. description-ja HAR:Plans.md タスクを1件から全並列チーム実行まで担当。実装して、実行して、全部やって、breezing、チーム実行、parallel、composer、コンポーザー、composer 2.5 で起動。プランニング・レビュー・リリース・セットアップには使わない。 kind workflow purpose Execute Plans.md tasks end to end through Codex-native tools trigger implement, execute, do everything, breezing, team run, parallel, composer, composer 2.5, composer mode, コンポーザー shape workflow role executor pair harness-review owner harness-core since 2026-05-05 allowed-tools ["Read","Write","Edit","Grep","Glob","Bash","spawn_agent","send_input","wait_agent","close_agent"] argument-hint [all] [task-number|range] [--backend claude|codex|cursor] [--cursor] [--codex] [--parallel N] [--no-commit] [--resume id] [--breezing] [--auto-mode] [--tdd-bypass] effort high
Harness Work
Harness の統合実行スキル。
以下の旧スキルを統合:
work — Plans.md タスクの実装（スコープ自動判断）impl — 機能実装（タスクベース）breezing — チームフル自動実行parallel-workflows — 並列ワークフロー最適化ci — CI 失敗時の復旧
Quick Reference
ユーザー入力 モード 動作 harness-workauto タスク数で自動判定（下記参照） harness-work allauto 全未完了タスクを自動モードで実行 harness-work 3solo タスク3だけ即実行 harness-work --parallel 5parallel 5ワーカーで並列実行（強制） harness-work --codexcodex Codex CLI に委託（明示時のみ） harness-work --breezing allbreezing resolved backend でチーム実行（配布既定は claude、user/project default で cursor 可） harness-work --breezing --backend cursor allbreezing Cursor worker backend を明示してチーム実行 harness-work --breezing --backend claude allbreezing Codex native subagent worker を明示してチーム実行 harness-work --breezingbreezing チーム実行を強制 harness-work 3 --plan roadmapsolo named Plans の roadmap からタスク3を実行
Execution Mode Auto Selection（フラグなし時の自動判定）
明示的なモードフラグ（--parallel, --breezing, --codex）がない場合、
対象タスク数に応じて最適なモードを自動選択する:
対象タスク数 自動選択モード 理由 1 件 Solo オーバーヘッド最小。直接実装が最速 2〜3 件 Parallel（Task tool） Worker 分離のメリットが出始める閾値
Lead 調整 + Worker 並列 + Reviewer 独立の三者分離が効果的
ルール
明示フラグは常にオートモードを上書き する
--parallel N → Parallel モード（タスク数に関係なく）--breezing → Breezing モード（タスク数に関係なく）--codex → Codex モード（タスク数に関係なく）
--codex は明示時のみ発動--codex は他モードと組み合わせ可能: --codex --breezing → Codex + Breezing
Execution Backend Selection（実装バックエンド選択） バックエンド（どのランタイムが実装するか ）は、トポロジー（実行モード: solo / parallel / breezing）と直交する。
トポロジーが「何ワーカーで・どう分割して回すか」を決めるのに対し、バックエンドは「実装の手を誰が動かすか」を決める。
この契約は host-neutral であり（spec.md「Execution Backend Contract」）、Codex host から harness を駆動しても Claude Code から駆動しても同じに振る舞う。
backend 実装の担い手 委託コマンド claude（global fallback）Codex native subagent（spawn_agent({message, fork_context})） spawn_agent で worker を spawn codexCodex CLI bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" task --write "<prompt>"cursorcursor-agent（model composer-2.5-fast） bash "${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh" task --write --workspace <worktree> "<prompt>"
解決手順 run 開始時に 1 回だけ解決する。backend 判定は 必ず resolver 経由 にし、HARNESS_IMPL_BACKEND env だけを直読みして判定しない:
bash "${HARNESS_PLUGIN_ROOT} /scripts/resolve-impl-backend.sh"
precedence（高い順）: --backend <v> / --cursor / --codex フラグ > HARNESS_IMPL_BACKEND 環境変数 > プロジェクト env.local の同名行 > ユーザー ~/.config/claude-harness/impl-backend.env の同名行 > call-site default。
明示フラグ（--backend / --cursor / --codex）は env / file / default を常に上書きする。プロジェクト設定はユーザースコープを上書きする。
Codex host の --breezing / breezing も配布 plugin では call-site default を変えない。
フラグなしは resolve-impl-backend.sh の結果に従い、未設定時の fallback は claude。
Cursor を既定にしたい環境は HARNESS_IMPL_BACKEND=cursor を env / project env.local / user-scope config に設定する。
明示的に Cursor を使う場合は --backend cursor / --cursor、Codex native subagent worker へ戻す場合は --backend claude を渡す。
モデル名の正本は model-routing.sh。本ドキュメント中の composer-2.5-fast は参照値であり、実解決は bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model に従う（drift 防止）。
自然言語 backend trigger ユーザーが composer / コンポーザー / Composer で / composer 2.5 / composer モード と言った場合は、cursor backend 指定として扱う。
これは --cursor と同じ intent だが、backend の確定値は必ず resolve-impl-backend.sh で解決する。
解決時は明示 override として --backend cursor を渡し、env / project / user file / default より優先させる。
Lead は composer を Codex native Worker 内の追加 agent と解釈せず、非 claude backend の規約どおり Worker agent を挟まずに cursor-companion.sh を直接呼ぶ。
role-scoped 制約 バックエンドは role-scoped 。解決済みバックエンドを使うのは実装（worker）ロールだけ。
Reviewer と Advisor の両ロールは常に brain（--host claude、Opus）に固定する。
Reviewer を cursor / codex バックエンドに routing しない（実装したバックエンドが自分の出力をレビューしてはならない）。
非 claude バックエンドの self_review ゲート backend が codex または cursor の場合、worker-report.v1 も self_review 配列も生成されない。
そのため Lead は self_review ゲートをスキップ し、Lead の diff レビューを唯一の品質ゲートとする（既存の codex path と同じ扱い）。
cursor バックエンドの banner（委託前に必須） backend が cursor のとき、Lead は委託前に次の 1 行 banner を必ず出力する:
⚠️ cursor backend: model=composer-2.5-fast / R01-R13 ガードレールは cursor-agent 内部に適用されない / 出力は Lead レビューまで untrusted
cursor の write 委託は専用 .git を持つ worktree 内で実行し、Lead が main へ cherry-pick する（cherry-pick 経路で R01-R13 が適用される）。
ガバナンス詳細は .claude/rules/cursor-cli-only.md を参照。
オプション オプション 説明 デフォルト all全未完了タスクを対象 - N or N-Mタスク番号/範囲指定 - --parallel N並列ワーカー数 auto --sequential直列実行強制 - --codexCodex CLI で実装委託（明示時のみ、自動選択しない） false --backend <claude|codex|cursor>明示バックエンド選択（worker ロールのみ適用、precedence 最上位） resolver result（未設定時は claude） --cursorcursor backend（--backend cursor の別名） false --plan NAMEplans/manifest.json の named plan を使うactive/default --no-commit自動コミット抑制 false --resume <id|latest>前回セッション再開 - --breezingLead/Worker/Reviewer のチーム実行 false --no-tddTDD フェーズスキップ false --tdd-bypass緊急時だけ TDD 強制を bypass。HARNESS_TDD_BYPASS_REASON または明示理由を audit に残す false --no-simplifyAuto-Refinement スキップ false --auto-modeAuto Mode rollout を明示。親セッションの permission mode が互換な場合のみ採用を検討 false
Progressive Disclosure まずこの本文で入口、自動選択、停止条件だけを確認する。
詳細は必要になった時だけ読む。
詳細 参照 Codex native Solo / Parallel / Breezing の具体手順 references/execution-modes.mdcompanion review、Reviewer fallback、AI Residuals、修正ループ references/review-loop.md完了報告の生成 references/completion-report.mdテスト/CI 失敗時の再チケット化 references/failure-reticketing.md仕様正本チェックの基準 docs/plans/spec-ssot.md
重要停止条件
Plans.md が旧フォーマットで DoD / Depends / Status を読めない時は停止する。仕様が実装判断に影響するのに project spec SSOT が見つからない時は、先に仕様正本を作成/更新してから実装する。
sprint-contract が required なのに ready でない時は実装に進まない。
critical / major review finding が残っている時は完了にしない。
テストを弱める、skip する、期待値を実装に合わせて緩める形では解決しない。
helper script は host project の scripts/ ではなく ${HARNESS_PLUGIN_ROOT}/scripts/ から呼ぶ。
複数 Plans.md がある場合は、1 run の中で plan を切り替えない。必要なら --plan NAME を明示して新しい run を開始する。
Token Optimization (v2.1.69+) : git 操作を伴わない軽量タスクでは
plugin settings の includeGitInstructions: false を有効にして
プロンプトトークンを削減できる。
スコープダイアログ（引数なし時） harness-work
どこまでやりますか?
1) 次のタスク: Plans.md の次の未完了タスク → Solo で実行
2) 全部（推奨）: 残りのタスクをすべて完了 → タスク数で自動モード選択
3) 番号指定: タスク番号を入力（例: 3, 5-7）→ 件数で自動モード選択
harness-work all → 全タスク、自動モード選択harness-work 3-6 → 4件なので Breezing 自動選択
Effort レベル制御（Opus 4.8 / v2.1.111+） effort はモデルの推論強度を選ぶ正式なノブ。low(○)/medium(◐)/high(●)/xhigh の 4 段階で、
/effort auto でデフォルトにリセットできる（max は v2.1.72 で廃止、xhigh が後継）。
Opus 4.8 では thinking は既定 off で、effort が推論深度の主レバー（過去のどの Opus より effort の影響が大きい）。
「浅い推論」を観測したら prompt で回避せず effort を上げる。
そのため複雑タスクの強化は free-text marker（旧 ultrathink）を spawn prompt に注入する方式を廃止 し、
複雑度スコアから Worker spawn の effort tier を選ぶ 方式に統一する。
多要素スコアリング 要素 条件 スコア ファイル数 変更対象 4 ファイル以上 +1 ディレクトリ core/, guardrails/, security/ を含む +1 キーワード architecture, security, design, migration を含む +1 失敗履歴 agent memory に同タスクの失敗記録あり +2 明示指定 PM テンプレートに effort: high / effort: xhigh（旧 ultrathink も互換受理）記載あり +3（自動採用）
effort tier の決め方（注入しない） スコアから effort tier を escalation signal として決める（ultrathink 等の marker 文字列を spawn prompt に 書かない ）。
適用 lever は次の 2 つだけ:
session /effort : 複雑タスクのバッチに入る前に host が /effort high / /effort xhigh を設定する（session 単位で効く確実な lever）。worker frontmatter : agents/worker.md の effort（既定 medium）が floor。CC の Agent / Task spawn API は per-spawn の effort 指定を公開しないため、worker 1 体ごとに effort を上げる機構はない。スコアは worker-report.v1 の task_complexity_note に記録し、Lead が session effort 引き上げの判断材料にする。 スコア code-risk（core/guardrails/security/architecture/migration を含む） effort tier 0-2 不問 medium（Worker frontmatter 既定のまま）≥ 3 なし high≥ 3 あり xhigh
breezing モードでも同じロジックを適用する（harness-work が一本化して管理）。
実行モード詳細
Harness helper script root Harness が同梱する helper script は、作業対象プロジェクトの scripts/ ではなく、必ず plugin bundle root から呼ぶ。
HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-} } "
if [ -z "$HARNESS_PLUGIN_ROOT " ] && [ -n "${CLAUDE_SKILL_DIR:-} " ]; then
probe="$(cd "${CLAUDE_SKILL_DIR} " && pwd) "
while [ "$probe " != "/" ] && [ ! -d "$probe /scripts" ]; do
probe="$(cd "$probe /.." && pwd) "
done
[ -d "$probe /scripts" ] && HARNESS_PLUGIN_ROOT="$probe "
fi
以降の node "${HARNESS_PLUGIN_ROOT}/scripts/..." / bash "${HARNESS_PLUGIN_ROOT}/scripts/..." は、この解決済み root を前提にする。
Backend-resolved executor path (Solo / Parallel / Breezing) Solo / Parallel / Breezing は同じ resolver result から実装 executor を選ぶ。
harness-work 3 --cursor と user/project HARNESS_IMPL_BACKEND=cursor は、1 件タスクでも local Read/Write/Edit/Bash に fall through してはいけない。
resolver_backend_arg = ""
if explicit_backend_value in ["claude", "codex", "cursor"]:
resolver_backend_arg = "--backend {explicit_backend_value}"
backend = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh\" {resolver_backend_arg}")
if explicit_flag == "--cursor":
backend = "cursor"
if explicit_flag == "--codex":
backend = "codex"
if topology in ["solo", "parallel"] and backend in ["cursor", "codex"]:
BASE_REF = git("rev-parse", "HEAD")
WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$$"
worktree_path = ".claude/worktrees/{backend}-{WT_ID}"
worktree_branch = "{backend}-work/{WT_ID}"
bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
if backend == "cursor":
companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worktree_path} \"{companion_prompt}\"")
else:
companion_state_file = "{worktree_path}/.claude/state/codex-primary-environment.json"
companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worktree_path} \"{companion_prompt}\"")
latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
if backend == "cursor" and git("-C", worktree_path, "status", "--porcelain") != "":
git("-C", worktree_path, "add", "-A")
git("-C", worktree_path, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: delegated change")
latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
if latest_commit == BASE_REF:
raise EscalationError("{backend} companion produced no commit")
worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
enter_shared_review_loop(worker_result)
else:
run_native_solo_or_parallel()
Parallel は task ごとにこの resolver path を適用する。
backend=cursor / codex の場合は native Worker spawn を使わず、task ごとに isolated companion worktree を作成して companion-result.v1 に正規化してから共通 review / cherry-pick loop に入る。
Solo モード（1 件時の自動選択）
Plans.md を読み込み、対象タスクを特定
Plans.md が存在しない場合 : harness-plan create --ci を自動呼び出し → Plans.md を生成して続行ヘッダーに DoD / Depends カラムがない場合: Plans.md が旧フォーマットです。harness-plan create で再生成してください。 → 停止
会話に未記載タスクがある場合 : 直前の会話コンテキストから要件を抽出し、Plans.md に cc:TODO で自動追記
抽出ロジック: ユーザー発言からアクション動詞（「〜を追加」「〜を修正」「〜を実装」）を検出
追記時は v2 フォーマット（Task / 内容 / DoD / Depends / Status）に準拠
追記後、ユーザーに「Plans.md に以下を追記しました」と表示（5 秒タイムアウト付きプロンプト、デフォルト: 続行）
1.5. タスク背景確認 （30 秒）:
タスクの「内容」と「DoD」から 目的 （このタスクが解く課題）を 1 行で推論表示
git grep / Glob で 影響範囲 （変更が及ぶファイル/モジュール）を推論表示推論に自信がある場合: そのまま実装に進む（フロー遅延なし）
推論に自信がない場合: ユーザーに 1 問だけ確認（「この理解で合っていますか？」）
1.6. 仕様正本 preflight :
既存の project spec SSOT を探す（例: docs/spec/00-project-spec.md, docs/ARCHITECTURE.md, docs/HANDOFF.md, docs/oem/PROJECT_COMPASS.md, docs/specs/）
task が product behavior / API / data model / permission / billing / integration / tenant boundary を変える場合、spec がなければ docs/spec/00-project-spec.md を作る
spec が古い、または task と矛盾する場合は、実装前に spec を更新する
typo / format / dependency bump / docs-only / 動作変更なし refactor は skip 理由を残して続行する
Worker / Reviewer へ渡す context には spec_path または spec_skip_reason を含める
タスクを cc:WIP に更新
TDD フェーズ （[skip:tdd] なし & テストFW存在時）:
a. テストファイルを先に作成（Red）
b. 失敗を確認
c. bash "${HARNESS_PLUGIN_ROOT}/scripts/log-tdd-red.sh" で .claude/state/tdd-red-log/<task-id>.jsonl に FAIL 証跡を残す。script が利用できない環境では、literal な failing test output を worker-report の self_review evidence に添付する
d. --tdd-bypass を使う場合は、HARNESS_TDD_BYPASS=1 と HARNESS_TDD_BYPASS_REASON="<理由>" を明示し、TDD を省略した理由を sprint-contract / worker-report に残すnode "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" <task-id> で sprint-contract.json を生成Reviewer 観点の追記を bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で approved を確認
Advisor consult（必要時のみ） :
高リスク task（needs-spike / security-sensitive / state-migration）は、初回実行前に 1 回だけ相談する
同じ原因の失敗が 2 回続いたら、3 回目に入る前に相談する
plateau（行き詰まり検知）が PIVOT_REQUIRED を返した時は、ユーザーへ止めて投げる前に 1 回だけ相談する
相談結果は advisor-response.v1 で受け取り、PLAN は進め方の組み替え、CORRECTION は局所修正、STOP は即エスカレーションとして扱う
同じ trigger_hash では 1 回しか相談しない。task ごとの相談回数は最大 3 回
backend-resolved executor path でコードを実装（Green）
backend=claude: local / native Read/Write/Edit/Bash path で実装
backend=cursor / codex: 上記 companion worktree path で実装し、companion-result.v1 を共通 review loop に渡す
/simplify で Auto-Refinement（--no-simplify で省略可）自動レビューステージ （「レビューループ」参照）:
Codex exec 優先でレビュー実行 → フォールバックで内部 Reviewer agent
sprint-contract.json の reviewer_profile が runtime の場合は bash "${HARNESS_PLUGIN_ROOT}/scripts/run-contract-review-checks.sh" を実行REQUEST_CHANGES の場合: 指摘を元に修正→再レビュー（MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3）
APPROVE で次ステップへ。self-check だけでは完了を確定しない
bash "${HARNESS_PLUGIN_ROOT}/scripts/write-review-result.sh" で review artifact を正規化して保存（browser profile は --browser-result を渡し、browser_verdict == PENDING_BROWSER の時は static verdict を採用）git commit で自動コミット（--no-commit で省略可）タスクを cc:完了 に更新（commit hash 付与）
git log --oneline -1 で直近の commit hash（短縮形 7 文字）を取得Plans.md の Status を cc:完了 [a1b2c3d] 形式で更新
commit がない場合（--no-commit 時）は hash なしで cc:完了 のみ
リッチ完了報告 （Completion Report Output Contract と references/completion-report.md を参照）失敗時の自動再計画 （テスト/CI 失敗時のみ）:
テスト実行結果を確認
失敗した場合: 修正タスク案を state に保存し、承認コマンド経由で Plans.md に追加（「失敗タスクの自動再チケット化」参照）
成功した場合: 次タスクへ進む
Parallel モード（2〜3 件時の自動選択 / --parallel N で強制） [P] マーク付きタスクを N ワーカーで並列実行。
--parallel N で明示指定した場合は、タスク数に関係なくこのモードを使用。
同一ファイルへの書き込みが競合する場合は git worktree で分離。
各 task の実装 executor は Backend-resolved executor path に従う。
--parallel N --cursor、--backend cursor、または default HARNESS_IMPL_BACKEND=cursor の場合、Parallel でも native Worker spawn ではなく task ごとの Cursor companion worktree を使う。
Codex モード（--codex 明示時のみ） 公式プラグイン codex-plugin-cc の companion 経由で Codex CLI にタスクを委託する。
BASE_REF="$(git rev-parse HEAD) "
WT_ID="codex-$(date +%Y%m%d-%H%M%S) -$$"
WORKTREE_PATH=".claude/worktrees/${WT_ID} "
git worktree add -b "codex-work/${WT_ID} " "$WORKTREE_PATH " "$BASE_REF "
HARNESS_CODEX_PRIMARY_ENV_STATE_FILE="$WORKTREE_PATH /.claude/state/codex-primary-environment.json" \
bash "${HARNESS_PLUGIN_ROOT} /scripts/codex-companion.sh" task --write -C "$WORKTREE_PATH " \
"タスク内容。完了前にこの worktree で exactly one git commit を作成してください。"
CODEX_PROMPT=$(mktemp /tmp/codex-prompt-XXXXXX.md)
cat "$CODEX_PROMPT " | HARNESS_CODEX_PRIMARY_ENV_STATE_FILE="$WORKTREE_PATH /.claude/state/codex-primary-environment.json" \
bash "${HARNESS_PLUGIN_ROOT} /scripts/codex-companion.sh" task --write -C "$WORKTREE_PATH "
rm -f "$CODEX_PROMPT "
git -C "$WORKTREE_PATH " diff "$BASE_REF ..HEAD"
WORKTREE_HEAD="$(git -C "$WORKTREE_PATH " rev-parse HEAD) "
git cherry-pick --no-commit "$BASE_REF ..$WORKTREE_HEAD "
companion は App Server Protocol 経由で Codex と通信し、
Job 管理・thread resume・構造化出力を提供する。
結果を検証し、品質基準を満たさない場合は自力で修正。
Breezing モード（4 件以上で自動選択 / --breezing で強制） Lead / Worker / Advisor / Reviewer の役割分離でチーム実行する。
Codex host の Breezing は resolver result に従う。配布 plugin のフラグなし fallback は claude なので、
spawn_agent, wait_agent, send_input, close_agent を使った Codex native subagent orchestration が互換既定。
--backend cursor / --cursor、または user/project config の HARNESS_IMPL_BACKEND=cursor がある時だけ
cursor-companion.sh で Cursor worker に委託する。
古い TeamCreate / TaskCreate ベースの説明は採らない。
現行の shipped default は bypassPermissions
--auto-mode は互換な親セッション向けの opt-in rollout フラグとして扱うpermissions.defaultMode や agent frontmatter の permissionMode には未文書化の autoMode 値を書かない
CC v2.1.69+ : nested teammates はプラットフォーム側で禁止されるため、
Worker/Reviewer プロンプトには冗長な nested 防止文言を追加しない。
Lead (this agent)
├── Worker (resolver result: Codex native spawn_agent / codex-companion / cursor-companion) — 実装担当
├── Advisor (claude-code-harness:advisor) — 方針助言
└── Reviewer (code-reviewer agent) — レビュー担当
Phase A: Pre-delegate（準備） :
Plans.md を読み込み、対象タスクを特定
依存グラフを解析し、実行順序を決定（Depends カラム）
各タスクの仕様正本 preflight を行い、必要なら docs/spec/00-project-spec.md または既存 spec を実装前に更新
各タスクの effort スコアリング（effort tier 判定 — high/xhigh）
node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" で sprint-contract.json を生成bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で Reviewer 観点を加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で未承認なら停止 Phase B: Delegate（Worker spawn → 必要時 Advisor → レビュー → cherry-pick） :
API 注記 : 以下は Codex native の subagent API 構文で記述する。
backend=claude の時だけ spawn_agent(...), send_input(...), wait_agent(...), close_agent(...) をそのまま使う。
backend=cursor / codex の時は Worker agent を spawn せず、Lead が companion を直接呼ぶ。
Claude Code 向けのサブエージェント構文やメッセージ送信構文は混ぜない。
for task in execution_order:
# B-0. backend 解決（配布 fallback は claude、user/project default で cursor 可）
resolver_backend_arg = ""
if explicit_backend_value in ["claude", "codex", "cursor"]:
resolver_backend_arg = "--backend {explicit_backend_value}"
backend = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh\" {resolver_backend_arg}")
if explicit_flag == "--cursor":
backend = "cursor"
if explicit_flag == "--codex":
backend = "codex"
# B-1. sprint-contract を生成
contract_path = bash("node \"${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js\" {task.number}")
contract_path = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh\" {contract_path} --check \"DoD を reviewer 観点で確認\" --approve")
bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh\" {contract_path}")
# B-2. Worker 委託（worktree 分離）
Plans.md: task.status = "cc:WIP" # 着手時に更新（未着手タスクは cc:TODO のまま）
if backend == "cursor":
BASE_REF = git("rev-parse", "HEAD")
WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$$"
worktree_path = ".claude/worktrees/cursor-{WT_ID}"
worktree_branch = "cursor-work/{WT_ID}"
bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
print("🚀 cursor / $(bash \"${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh\" --host cursor --role worker --field model) / {branch} / {task.number}")
companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worktree_path} \"{companion_prompt}\"")
latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
if git("-C", worktree_path, "status", "--porcelain") != "":
git("-C", worktree_path, "add", "-A")
git("-C", worktree_path, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: delegated change")
latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
if latest_commit == BASE_REF:
raise EscalationError("cursor companion produced no commit")
worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
worker_id = null
elif backend == "codex":
BASE_REF = git("rev-parse", "HEAD")
WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$$"
worktree_path = ".claude/worktrees/codex-{WT_ID}"
worktree_branch = "codex-work/{WT_ID}"
bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
companion_state_file = "{worktree_path}/.claude/state/codex-primary-environment.json"
companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worktree_path} \"{companion_prompt}\"")
latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
if latest_commit == BASE_REF:
raise EscalationError("codex companion produced no commit")
worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
worker_id = null
else:
print("🚀 claude / native-subagent / {branch} / {task.number}")
worker_id = spawn_agent({
message: "タスク: {task.内容}\nDoD: {task.DoD}\ncontract_path: {contract_path}\nspec_path: {spec_path}\nspec_skip_reason: {spec_skip_reason}\nmode: breezing\n\n作業は分離 worktree で行い、完了後に git commit してください。\n完了時は {commit, worktreePath, branch, files_changed, summary} を返してください。",
fork_context: true
})
worker_result = wait_agent({ targets: [worker_id] })
# worker_result には {commit, worktreePath, branch, files_changed, summary} が含まれる
# backend=cursor/codex では Lead が companion stdout を companion-result.v1 に正規化する。
# B-3. Worker が advice request を返した時だけ、Lead が Advisor を呼ぶ
if backend == "claude" and worker_result.type == "advisor-request.v1":
advisor_id = spawn_agent({
message: worker_result.request_json,
agent_type: "default",
fork_context: true
})
advisor_result = wait_agent({ targets: [advisor_id] })
close_agent({ target: advisor_id })
send_input({
target: worker_id,
message: "advisor-response.v1: {advisor_result}"
})
worker_result = wait_agent({ targets: [worker_id] })
# B-4. Lead がレビュー実行（Codex exec 優先）
if backend == "claude":
diff_text = git("-C", worker_result.worktreePath, "show", worker_result.commit)
else:
diff_text = git("-C", worker_result.worktreePath, "diff", "{worker_result.baseCommit}..HEAD")
verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
profile = jq(contract_path, ".review.reviewer_profile")
review_input = "review-output.json"
if profile == "runtime":
review_input = bash("cd {worker_result.worktreePath} && bash \"${HARNESS_PLUGIN_ROOT}/scripts/run-contract-review-checks.sh\" {contract_path}")
runtime_verdict = jq(review_input, ".verdict")
if runtime_verdict == "REQUEST_CHANGES":
verdict = "REQUEST_CHANGES"
elif runtime_verdict == "DOWNGRADE_TO_STATIC":
pass # runtime 検証コマンドなし → static verdict をそのまま使う
browser_result = ""
if profile == "browser":
# browser artifact から route / browser_mode / execution_instructions を再利用して browser runner を起動する。
browser_artifact = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/generate-browser-review-artifact.sh\" {contract_path}")
browser_result = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/browser-review-runner.sh\" {browser_artifact}")
browser_verdict = jq(browser_result, ".browser_verdict")
if browser_verdict == "REQUEST_CHANGES":
verdict = "REQUEST_CHANGES"
elif browser_verdict == "APPROVE" and verdict != "REQUEST_CHANGES":
verdict = "APPROVE"
# browser_verdict == PENDING_BROWSER のときは static verdict を維持する
# review_input が DOWNGRADE_TO_STATIC の場合は static review 結果を使う
if review_input != "review-output.json" and jq(review_input, ".verdict") == "DOWNGRADE_TO_STATIC":
review_input = "review-output.json" # static review の結果にフォールバック
bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/write-review-result.sh\" {review_input} {latest_commit} --browser-result {browser_result}")
# B-5. 修正ループ（REQUEST_CHANGES 時、contract の max_iterations まで）
review_count = 0
# sprint-contract が存在するときのみ max_iterations を読む。存在しない場合は 3（後方互換）
MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3
latest_commit = worker_result.commit
while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
if backend == "claude":
send_input({
target: worker_id,
message: "指摘内容: {issues}\n修正して amend してください"
})
# Worker が修正 → amend → 更新された commit hash を返す
updated_result = wait_agent({ targets: [worker_id] })
latest_commit = updated_result.commit
elif backend == "cursor":
previous_commit = latest_commit
companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worker_result.worktreePath} \"Review findings:\n{issues}\n\nFix the findings and commit the result.\"")
latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
if git("-C", worker_result.worktreePath, "status", "--porcelain") != "":
git("-C", worker_result.worktreePath, "add", "-A")
git("-C", worker_result.worktreePath, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: review fix")
latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
if latest_commit == previous_commit:
raise EscalationError("cursor companion retry produced no new commit")
worker_result.commit = latest_commit
worker_result.summary = companion_output
else:
previous_commit = latest_commit
companion_state_file = "{worker_result.worktreePath}/.claude/state/codex-primary-environment.json"
companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worker_result.worktreePath} \"Review findings:\n{issues}\n\nFix the findings and commit the result.\"")
latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
if latest_commit == previous_commit:
raise EscalationError("codex companion retry produced no new commit")
worker_result.commit = latest_commit
worker_result.summary = companion_output
if backend == "claude":
diff_text = git("-C", worker_result.worktreePath, "show", latest_commit)
else:
diff_text = git("-C", worker_result.worktreePath, "diff", "{worker_result.baseCommit}..HEAD")
verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
review_count++
# B-6. Worker 終了
if backend == "claude":
close_agent({ target: worker_id })
# B-7. APPROVE → trunk に cherry-pick（feature ブランチ経由）
# Worker の Branch Guard により trunk HEAD は動かず、commit は feature ブランチ上にある想定
if verdict == "APPROVE":
TRUNK=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || echo "main")
git checkout "$TRUNK" # safety: 既に trunk なら no-op
# feature ブランチの commit が既に trunk にある（Branch Guard 失敗時のフォールバック）か確認
if git("merge-base", "--is-ancestor", latest_commit, "HEAD"):
pass # 既に trunk 上 — cherry-pick 不要（再入防止）
else:
if backend == "claude":
git cherry-pick --no-commit {latest_commit} # feature branch → trunk
else:
git cherry-pick --no-commit {worker_result.baseCommit}..{latest_commit} # companion range → trunk
git commit -m "{task.内容}"
# Worker の worktree を remove してから feature ブランチを削除
if worker_result.worktreePath:
git worktree remove {worker_result.worktreePath} --force
if worker_result.branch and worker_result.branch not in ["main", "master"] and worker_result.branch != TRUNK:
git branch -D {worker_result.branch}
Plans.md: task.status = "cc:完了 [{hash}]"
# auto-checkpoint 記録（冪等性ガード (c)）
# Plans.md 書き換え直後に呼ぶ。失敗しても fail-open（|| true）でループを止めない
HASH=$(git rev-parse --short HEAD)
REVIEW_RESULT_PATH=".claude/state/review-results/${task.number}.review-result.json"
bash "${HARNESS_PLUGIN_ROOT}/scripts/auto-checkpoint.sh" \
"${task.number}" "${HASH}" "${contract_path}" "${REVIEW_RESULT_PATH}" \
|| true # fail-open: harness-mem 未起動環境でも継続
else:
→ ユーザーにエスカレーション
# B-8. Progress feed
print("📊 Progress: Task {completed}/{total} 完了 — {task.内容}")
Work Mode Lifecycle (bin/harness work-mode) Claude Code 版と同一の契約（正本: skills/harness-work/SKILL.md の同名節）。
R04/R05 の確認 skip が読む ctx.WorkMode は SQLite work_states 行でのみ立てられる
（HARNESS_WORK_MODE / ULTRAWORK_MODE env は skill から設定できない）。
Lead は Phase A 開始前（solo 実行では最初の実装アクション前）に bin/harness work-mode on を実行し、
run 終了時は成功・失敗・中断の全経路 で bin/harness work-mode off を実行する。run 単位で 1 回のみ。
session ID が解決できない場合、work-mode は非ゼロ終了し理由を stderr に出す。
Advisor Protocol（全モード共通） Advisor は「実装者」でも「レビュー担当」でもない。
迷った時だけ、実行役が次の一歩を決めるための相談役として入る。
Worker は generic な subagent を増やさず、必要時だけ advisor-request.v1 を返す
Lead が advisor を 1 回だけ呼ぶ
Advisor は PLAN / CORRECTION / STOP のどれかを返す
Lead はその advice を同じ Worker に返して続行させる
Reviewer は最後の成果物だけを見る。advisor の返答に APPROVE / REQUEST_CHANGES を出さない
Solo モードでの Advisor solo 実行では親セッション自身が Lead を兼ねる。
つまり「自分で実装し、自分で advisor に相談し、最後は独立レビューに回す」形になる。
相談条件は loop / breezing と同じ
相談 budget も task ごとに最大 3 回で同じ
STOP はその場で止まり、ユーザー判断へ上げるreview artifact の gate は飛ばさない
Sprint Contract sprint-contract は「このタスクを何で合格にするか」を機械でも人でも同じ意味で読める形にする小さな契約ファイルです。
既定の保存先は .claude/state/contracts/<task-id>.sprint-contract.json です。
node "${HARNESS_PLUGIN_ROOT} /scripts/generate-sprint-contract.js" 32.1.1
checks: DoD を分解した確認項目non_goals: 今回やらないことruntime_validation: test, lint, typecheck などの検証コマンド
If you grep the same symbol twice in the same session, switch to harness_ast_search.
For a bugfix where homologous implementations appear across multiple modules, run harness_ast_search to find all implementations before editing.
Only when changed files include .ts or .tsx, the DoD requires zero new harness_lsp_diagnostics errors; if the harness MCP is not connected or the changed file types are not eligible, treat diagnostics as not-configured and non-blocking.
browser_validation: browser reviewer が残すべき UI フロー検証項目browser_mode: scripted または exploratoryroute: browser reviewer が playwright / agent-browser / chrome-devtools のどれを使うかrisk_flags: needs-spike, security-sensitive, ux-regression などreviewer_profile: static, runtime, browser Phase C: Post-delegate（統合・報告） :
全タスクの commit log を集計
リッチ完了報告 （Completion Report Output Contract と references/completion-report.md の Breezing テンプレート）を出力Plans.md の最終確認（全タスク cc:完了 になっているか）
CI 失敗時の対応
ログを確認してエラーを特定
修正を実施
同一原因で 3 回失敗したら自動修正ループを停止
失敗ログ・試みた修正・残る論点をまとめてエスカレーション
失敗タスクの自動再チケット化 タスク完了後にテスト/CI が失敗した場合、修正タスク案を自動生成し、承認後に Plans.md へ反映する:
トリガー条件 条件 アクション cc:完了 後にテスト失敗修正タスク案を state に保存し、承認を待つ CI 失敗（3回未満） 修正を実施し、失敗カウントをインクリメント CI 失敗（3回目） 修正タスク案を提示 + エスカレーション
修正タスクの自動生成
失敗原因を分類（syntax_error / import_error / type_error / assertion_error / timeout / runtime_error）
.claude/state/pending-fix-proposals.jsonl に修正タスク案を保存:
番号: 元タスク番号 + .fix サフィックス（例: 26.1.fix）
内容: fix: [元タスク名] - [失敗原因カテゴリ]
DoD: テスト/CI が通ること
Depends: 元タスク番号
ユーザーが approve fix <task_id> を送ると Plans.md に cc:TODO で追加
reject fix <task_id> で提案を破棄。pending が1件だけのときは yes / no でも応答可能
レビューループ 実装完了後（ステップ 5 の後）に自動実行される品質検証ステージ。
全モード共通 （Solo / Parallel / Breezing）で統一的に適用される。
Parallel モードでは各 Worker が step 10（外部レビュー受付）として同じループを実行する。
レビュー実行の優先順位 1. Codex exec（優先）
↓ codex コマンドが存在しない or タイムアウト（120s）
2. 内部 Reviewer agent（フォールバック）
APPROVE / REQUEST_CHANGES の判定基準 レビュアーには以下の閾値基準を渡し、この基準のみ で verdict を判定させる。
基準外の改善提案は recommendations として返すが、verdict には影響しない。
重要度 定義 verdict への影響 critical セキュリティ脆弱性、データ損失リスク、本番障害の可能性 1 件でも → REQUEST_CHANGES major 既存機能の破壊、仕様との明確な矛盾、テスト不通過 1 件でも → REQUEST_CHANGES minor 命名改善、コメント不足、スタイル不統一 verdict に影響しない recommendation ベストプラクティス提案、将来の改善案 verdict に影響しない
重要 : minor / recommendation のみの場合は 必ず APPROVE を返すこと。
「あったほうが良い改善」は REQUEST_CHANGES の理由にならない。
Codex exec レビュー（公式プラグイン経由） タスク開始時の HEAD を BASE_REF として保持し、その ref との差分をレビュー対象にする。
公式プラグイン codex-plugin-cc の companion review を使用する。
BASE_REF=$(git rev-parse HEAD)
bash "${HARNESS_PLUGIN_ROOT} /scripts/codex-companion.sh" review --base "${BASE_REF} "
REVIEW_EXIT=$?
verdict マッピング （公式プラグイン → Harness 形式）:
公式プラグインは review-output.schema.json 準拠の構造化出力を返す。
Harness の verdict 形式への変換ルール:
公式 plugin Harness verdict 影響 approveAPPROVE- needs-attentionREQUEST_CHANGES- findings[].severity: criticalcritical_issues[]1件でも → REQUEST_CHANGES findings[].severity: highmajor_issues[]1件でも → REQUEST_CHANGES findings[].severity: medium/lowrecommendations[]verdict に影響しない
AI Residuals スキャンは引き続き bash "${HARNESS_PLUGIN_ROOT}/scripts/review-ai-residuals.sh" で実行し、
companion review の結果と合わせて最終 verdict を判定する。
AI_RESIDUALS_JSON="$(bash "${HARNESS_PLUGIN_ROOT} /scripts/review-ai-residuals.sh" --base-ref "${BASE_REF} " 2>/dev/null || echo '{"tool" :"review-ai-residuals" ,"scan_mode" :"diff" ,"base_ref" :null,"files_scanned" :[],"summary" :{"verdict" :"APPROVE" ,"major" :0,"minor" :0,"recommendation" :0,"total" :0},"observations" :[]}') "
内部 Reviewer agent フォールバック Codex exec が使えない場合（command -v codex が失敗、または exit code ≠ 0）:
Agent tool: subagent_type="reviewer"
prompt: "以下の変更をレビューしてください。判定基準: critical/major → REQUEST_CHANGES、minor/recommendation のみ → APPROVE。diff: {git diff ${BASE_REF}}"
Reviewer agent は Read-only（Write/Edit/Bash 無効）で安全にレビューを実行する。
修正ループ（REQUEST_CHANGES 時） review_count = 0
# sprint-contract が存在するときのみ max_iterations を読む。存在しない場合は 3（後方互換）
contract_path = get_sprint_contract_path() # 例: .claude/state/contracts/<task-id>.sprint-contract.json
MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3
while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
1. レビュー指摘を解析（critical / major のみ対象）
2. 各指摘に対して修正を実装
3. 再度レビューを実行（同じ判定基準・同じ優先順位）
review_count++
if review_count >= MAX_REVIEWS and verdict != "APPROVE":
→ ユーザーにエスカレーション
→ 「MAX_REVIEWS 回修正しましたが以下の critical/major 指摘が残っています」+ 指摘一覧を表示
→ ユーザー判断を待つ（続行 / 中断）
Breezing モードでの適用 Breezing モードでは Lead がレビューループを実行する（上記 Phase B 参照）:
Worker が worktree 内で実装・commit → Lead に結果返却
Lead が Codex exec でレビュー（優先）/ Reviewer agent（フォールバック）
REQUEST_CHANGES → Lead が send_input で Worker に修正指示し、wait_agent で再応答を待つ → Worker が amend
修正後、再レビュー（MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3 回まで）
APPROVE → Lead が trunk（デフォルトブランチ）に cherry-pick → Plans.md を cc:完了 [{hash}] に更新
Completion Report Output Contract Before rendering a Solo, forced single-task Parallel, or Breezing completion
report:
Resolve the active locale with the shared get_harness_locale function from
${HARNESS_PLUGIN_ROOT}/scripts/config-utils.sh. Pass an explicit session or
user language as its optional argument; otherwise keep the resolver priority
of project i18n.language, CLAUDE_CODE_HARNESS_LANG, then default en.
Unset, invalid, and resolved en render the English template.
Only resolved ja renders the Japanese template.
Japanese input alone does not select the Japanese template.
Read references/completion-report.md and render exactly one template for
the selected mode and locale.
Keep machine-readable status and review values in English, and never mix
English and Japanese labels in one report.
関連スキル
harness-plan — 実行するタスクを計画するharness-sync — 実装と Plans.md を同期するharness-review — 実装のレビューharness-release — バージョンバンプ・リリース 