Help us improve
Share bugs, ideas, or general feedback.
From claude-code-harness
Executes Plans.md tasks using auto-selected solo, parallel, or breezing modes based on task count. Supports explicit flags for team run, parallel workers, or codex delegation.
npx claudepluginhub chachamaru127/claude-code-harness --plugin claude-code-harnessHow this skill is triggered — by the user, by Claude, or both
Slash command
/claude-code-harness:harness-work [all] [task-number|range] [--codex] [--parallel N] [--no-commit] [--resume id] [--breezing] [--auto-mode] [--tdd-bypass][all] [task-number|range] [--codex] [--parallel N] [--no-commit] [--resume id] [--breezing] [--auto-mode] [--tdd-bypass]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Harness の統合実行スキル。
Team execution mode that wraps harness-work with orchestration, supporting parallel tasks, cursor backend, and reviewer-only delegation.
Executes Plans.md tasks end-to-end in solo, parallel, or full team modes with auto-mode selection based on task count.
Executes an approved implementation plan task-by-task, dispatching one fresh subagent per task with an RTCO brief, then validates output through schema check, self-review, and plan-compliance review before marking complete.
Share bugs, ideas, or general feedback.
Harness の統合実行スキル。 以下の旧スキルを統合:
work — Plans.md タスクの実装(スコープ自動判断)impl — 機能実装(タスクベース)breezing — チームフル自動実行parallel-workflows — 並列ワークフロー最適化ci — CI 失敗時の復旧| ユーザー入力 | モード | 動作 |
|---|---|---|
/harness-work | auto | タスク数で自動判定(下記参照) |
/harness-work all | auto | 全未完了タスクを自動モードで実行 |
/harness-work 3 | solo | タスク3だけ即実行 |
/harness-work --parallel 5 | parallel | 5ワーカーで並列実行(強制) |
/harness-work --codex | codex | Codex CLI に委託(明示時のみ) |
| Cursor host (adapter candidate) | cursor | Task/subagent routing via .cursor/AGENTS.md; not auto-selected |
/harness-work --breezing | breezing | チーム実行を強制 |
/harness-work 3 --plan roadmap | solo | named Plans の roadmap からタスク3を実行 |
明示的なモードフラグ(--parallel, --breezing, --codex)がない場合、
対象タスク数に応じて最適なモードを自動選択する:
| 対象タスク数 | 自動選択モード | 理由 |
|---|---|---|
| 1 件 | Solo | オーバーヘッド最小。直接実装が最速 |
| 2〜3 件 | Parallel(Task tool) | Worker 分離のメリットが出始める閾値 |
| 4 件以上 | Breezing | Lead 調整 + Worker 並列 + Reviewer 独立の三者分離が効果的 |
--parallel N → Parallel モード(タスク数に関係なく)--breezing → Breezing モード(タスク数に関係なく)--codex → Codex モード(タスク数に関係なく)--codex は明示時のみ発動。Codex CLI が未インストールの環境があるため、自動選択しない--codex は他モードと組み合わせ可能: --codex --breezing → Codex + Breezingバックエンド(どのランタイムが実装するか)は、実行モード(トポロジー: solo / parallel / breezing)と直交する。 実行モードが「何ワーカーで・どう分割して回すか」を決めるのに対し、バックエンドは「実装の手を誰が動かすか」を決める。
| backend | 実装の担い手 | 委託コマンド |
|---|---|---|
claude(既定) | Task subagent(agents/worker.md) | Agent tool で worker を spawn |
codex | Codex CLI | bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" task --write "<prompt>" |
cursor | cursor-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 の同名行 > 既定値 claude。プロジェクト設定はユーザースコープを上書きする。
明示フラグ(--backend / --cursor / --codex)は env / file / default を常に上書きする。
ユーザーが 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 を Claude Worker 内の追加 agent と解釈せず、非 claude backend の規約どおり Worker agent を挟まずに cursor-companion.sh を直接呼ぶ。
バックエンドは role-scoped。解決済みバックエンドを使うのは実装(worker)ロールだけ。
Reviewer と Advisor の両ロールは常に brain(--host claude、Opus)に固定する。
Reviewer を cursor / codex バックエンドに routing しない(実装したバックエンドが自分の出力をレビューしてはならない)。
# 実装ロールだけ解決済み backend に従う(例: backend=cursor なら composer-2.5-fast を解決)
bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model
# review / advisor は常に claude(Opus)固定
bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host claude --role reviewer --field model
bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host claude --role advisor --field model
モデル名の正本は
model-routing.sh側。本ドキュメント中のcomposer-2.5-fastは参照値であり、実際の解決は上記コマンドに従う(drift 防止)。
claude バックエンドのトポロジー(Worker 介在なし)backend が codex または cursor の場合、Lead は Worker agent (claude-code-harness:worker) を spawn しない。
代わりに Lead 自身が cursor-companion.sh / codex-companion.sh を直接呼ぶ。
Worker 層の介在は backend=claude のときだけ。
配線:
| backend | 経路 |
|---|---|
claude(既定) | Lead → Worker (claude-code-harness:worker agent) → … → Lead review → cherry-pick |
codex | Lead → codex-companion.sh task --write → Lead review → cherry-pick |
cursor | Lead → cursor-companion.sh task --write --workspace <isolated-wt> → Lead review → cherry-pick |
非 claude backend で Worker を間に挟むと、Lead → Worker → companion → composer/codex と二段委譲になり、Worker の存在意義(agent 契約による self_review 5 件のゲート)が空回りする(非 claude では worker-report.v1 も self_review も生成されないため)。Lead は Worker をスキップして companion を直接呼ぶ。
非 claude backend の companion 呼び出しでも、Lead は先に専用 worktree を作り、companion stdout を companion-result.v1 相当の {baseCommit, commit, worktreePath, branch, files_changed, summary} に正規化してから既存の Lead review / cherry-pick 経路へ渡す。REQUEST_CHANGES 時は SendMessage を使わず、同じ worktree で cursor-companion.sh / codex-companion.sh を再実行し、baseCommit..HEAD を再レビューして range cherry-pick する。
claude バックエンドの self_review ゲートbackend が codex または cursor の場合、worker-report.v1 も self_review 配列も生成されない。
そのため Lead は self_review ゲートをスキップし、Lead の diff レビューを唯一の品質ゲートとする(既存の codex path と同じ扱い)。
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 を参照。
非 claude backend (cursor / codex) の出力を main にとり込む前に、Lead は 目視 diff + contract grep の二段ゲートを必ず通す。目視 diff だけで APPROVE しない。
| ゲート | コマンド | 検知できるもの |
|---|---|---|
| diff 目視 | git show <sha> | 変更が意図どおりか・他ファイル touch なしか・support tier 表記不変か |
| contract grep | bash tests/test-support-claim-wording.sh | 公開 support 表記の破壊 |
| contract grep | bash scripts/ci/check-consistency.sh | i18n / locale / mirror / capability matrix の固定文字列契約破壊 |
| contract grep | bash tests/validate-plugin.sh | plugin 配布契約・hook 配線 |
全 PASS のときだけ cherry-pick。1 件でも fail なら revert または composer に再委託(同一文字列契約を保つよう明示)。
理由: docs / README / locale / capability-matrix / spec.md には grep で監視される 固定文字列契約がある (例: README_ja.md の 5動詞ワークフロー)。composer は表面的な言語的重複を機械的に削減する傾向があり、目視 diff では「綺麗な dedup」に見えても固定句を破壊しうる。
| オプション | 説明 | デフォルト |
|---|---|---|
all | 全未完了タスクを対象 | - |
N or N-M | タスク番号/範囲指定 | - |
--parallel N | 並列ワーカー数 | auto |
--sequential | 直列実行強制 | - |
--codex | Codex CLI で実装委託(明示時のみ、自動選択しない) | false |
--backend <claude|codex|cursor> | 明示バックエンド選択(worker ロールのみ適用、precedence 最上位) | claude |
--cursor | cursor backend(--codex と同様、明示時のみ。cursor-agent 未インストール環境があるため自動選択しない) | false |
--plan NAME | plans/manifest.json の named plan を使う | active/default |
--no-commit | 自動コミット抑制 | false |
--resume <id|latest> | 前回セッション再開。長く空いた後は /recap 併用を推奨 | - |
--breezing | Lead/Worker/Reviewer のチーム実行 | false |
--no-tdd | TDD フェーズスキップ | false |
--tdd-bypass | 緊急時だけ TDD 強制を bypass。HARNESS_TDD_BYPASS_REASON または明示理由を audit に残す | false |
--no-simplify | Auto-Refinement スキップ | false |
--auto-mode | Harness 側の Auto Mode rollout を明示。CC 2.1.111 で不要になった --enable-auto-mode とは別物 | false |
まずこの本文で入口、自動選択、停止条件だけを確認する。 詳細は必要になった時だけ読む。
| 詳細 | 参照 |
|---|---|
| Solo / Parallel / Codex / Breezing の具体手順 | references/execution-modes.md |
| Codex review、Reviewer fallback、AI Residuals、修正ループ | references/review-loop.md |
| Solo / Breezing 完了報告の生成 | references/completion-report.md |
| テスト/CI 失敗時の再チケット化 | references/failure-reticketing.md |
| 仕様正本チェックの基準 | docs/plans/spec-ssot.md |
Plans.md が旧フォーマットで DoD / Depends / Status を読めない時は停止する。scripts/ ではなく ${HARNESS_PLUGIN_ROOT}/scripts/ から呼ぶ。--plan NAME を明示して新しい run を開始する。Token Optimization (v2.1.69+): git 操作を伴わない軽量タスクでは plugin settings の
includeGitInstructions: falseを有効にして プロンプトトークンを削減できる。
Prompt Cache (CC 2.1.108+): 長めの実装や
--resumeを多用する作業ではENABLE_PROMPT_CACHING_1H=1を優先する。
/harness-work
どこまでやりますか?
1) 次のタスク: Plans.md の次の未完了タスク → Solo で実行
2) 全部(推奨): 残りのタスクをすべて完了 → タスク数で自動モード選択
3) 番号指定: タスク番号を入力(例: 3, 5-7)→ 件数で自動モード選択
引数ありなら即実行(対話スキップ):
/harness-work all → 全タスク、自動モード選択/harness-work 3-6 → 4件なので Breezing 自動選択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 を選ぶ方式に統一する。
これは docs/model-routing-policy.md(effort を free-text から推測しない)と
.claude/rules/opus-4-7-prompt-audit.md 合格条件 5(xhigh は呼び出し側が選ぶ)と整合する。
タスク着手時に以下のスコアを合算する。
| 要素 | 条件 | スコア |
|---|---|---|
| ファイル数 | 変更対象 4 ファイル以上 | +1 |
| ディレクトリ | core/, guardrails/, security/ を含む | +1 |
| キーワード | architecture, security, design, migration を含む | +1 |
| 失敗履歴 | agent memory に同タスクの失敗記録あり | +2 |
| 明示指定 | PM テンプレートに effort: high / effort: xhigh(旧 ultrathink も互換受理)記載あり | +3(自動採用) |
スコアから effort tier を escalation signal として決める(ultrathink 等の marker 文字列を spawn prompt に 書かない)。
適用 lever は次の 2 つだけ:
/effort: 複雑タスクのバッチに入る前に host が /effort high / /effort xhigh を設定する(session 単位で効く確実な lever)。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 が一本化して管理)。
Worker は Sonnet 4.6 のため xhigh は実効 high にダウングレードされるが、tier 引き上げ自体は有効(docs/effort-level-policy.md)。
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 を前提にする。
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_non_claude_companion_review_loop(worker_result)
else:
run_native_solo_or_parallel()
def enter_non_claude_companion_review_loop(worker_result):
# companion-result.v1 has no worker_id and no worker_result.self_review.
# Do not use the Worker-only SendMessage/self_review loop for cursor/codex.
latest_commit = worker_result.commit
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 = 0
MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3
while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
previous_commit = latest_commit
if backend == "cursor":
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.\"")
else:
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 backend == "cursor" and 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("{backend} companion retry produced no new commit")
worker_result.commit = latest_commit
worker_result.summary = companion_output
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++
if verdict == "APPROVE":
git cherry-pick --no-commit {worker_result.baseCommit}..{worker_result.commit}
Parallel は task ごとにこの resolver path を適用する。
backend=cursor / codex の場合は native Worker spawn を使わず、task ごとに isolated companion worktree を作成して companion-result.v1 に正規化してから non-Claude companion 専用の range review / cherry-pick loop に入る。
harness-plan create --ci を自動呼び出し → Plans.md を生成して続行Plans.md が旧フォーマットです。harness-plan create で再生成してください。 → 停止cc:TODO で自動追記
git grep / Glob で 影響範囲(変更が及ぶファイル/モジュール)を推論表示docs/spec/00-project-spec.md, docs/ARCHITECTURE.md, docs/HANDOFF.md, docs/oem/PROJECT_COMPASS.md, docs/specs/)docs/spec/00-project-spec.md を作るspec_path または spec_skip_reason を含めるcc:WIP に更新[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 を生成bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で approved を確認needs-spike / security-sensitive / state-migration)は、初回実行前に 1 回だけ相談するPIVOT_REQUIRED を返した時は、ユーザーへ止めて投げる前に 1 回だけ相談するadvisor-response.v1 で受け取り、PLAN は進め方の組み替え、CORRECTION は局所修正、STOP は即エスカレーションとして扱うtrigger_hash では 1 回しか相談しない。task ごとの相談回数は最大 3 回claude: local / native Read/Write/Edit/Bash path で実装cursor / codex: 上記 companion worktree path で実装し、companion-result.v1 を共通 review loop に渡す/simplify で Auto-Refinement(--no-simplify で省略可)sprint-contract.json の reviewer_profile が runtime の場合は bash "${HARNESS_PLUGIN_ROOT}/scripts/run-contract-review-checks.sh" を実行MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3)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 文字)を取得cc:完了 [a1b2c3d] 形式で更新--no-commit 時)は hash なしで cc:完了 のみ--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-plugin-cc の companion 経由で Codex CLI にタスクを委託する。
# タスク委託(書き込み可能・worktree 分離)
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 を作成してください。"
# stdin 経由(大きなプロンプト向け)
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"
# Lead review 後に承認されたら range を取り込む
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・構造化出力を提供する。 結果を検証し、品質基準を満たさない場合は自力で修正。
Cursor host では .cursor/AGENTS.md と .cursor-plugin/plugin.json が
bootstrap route。Cursor は candidate のまま — supported claim は禁止。
.cursor/agents/worker.md subagentModel routing:
bash scripts/model-routing.sh --host cursor --role worker --format json
Explicit Task/subagent model が routed default より優先。
検証:
bash tests/test-cursor-adapter-candidate.sh
--breezing で強制)Lead / Worker / Advisor / Reviewer の役割分離でチーム実行する。
Codex では spawn_agent, wait, send_input, resume_agent, close_agent
を使った native subagent orchestration を前提にし、
古い TeamCreate / TaskCreate ベースの説明を採らない。
Cursor では Task/subagent/background agents へ mapping するが、
review/cherry-pick の直列責務は core 側に残す(adapter smoke target)。
権限ポリシー:
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 (task-worker agent) — 実装担当
├── Advisor (claude-code-harness:advisor) — 方針助言
└── Reviewer (code-reviewer agent) — レビュー担当
Phase A: Pre-delegate(準備):
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 注記: 以下は Claude Code の API 構文で記述。 Codex 環境では
Agent(...)→spawn_agent(...),SendMessage(...)→send_input(...)に読み替え。 詳細はteam-composition.mdの API マッピング表を参照。
for task in execution_order:
# 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 spawn(フォアグラウンド、worktree 分離)
# Agent tool の戻り値に agentId が含まれる — 修正ループで SendMessage に使用
Plans.md: task.status = "cc:WIP" # 着手時に更新(未着手タスクは cc:TODO のまま)
# 逐次 /harness-work を連打している時も universal violations を伝播させる
# (初回実行時は universal_violations = [] で初期化済み想定)
briefing_header = ""
if universal_violations:
briefing_header = (
"🚨 同一セッションで既に検出された universal 違反(再発禁止):\n"
+ "\n".join(f"- {v}" for v in universal_violations)
+ "\n\n"
)
worker_result = Agent(
subagent_type="claude-code-harness:worker",
prompt=briefing_header + "タスク: {task.内容}\nDoD: {task.DoD}\ncontract_path: {contract_path}\nmode: breezing",
isolation="worktree",
run_in_background=false # フォアグラウンドで実行 → Worker 完了まで待機
)
worker_id = worker_result.agentId # SendMessage 用に保持
# worker_result には {commit, worktreePath, files_changed, summary} が含まれる
# B-3. Worker が advice request を返した時だけ、Lead が Advisor を呼ぶ
if worker_result.type == "advisor-request.v1":
advisor_result = Advisor(
prompt=worker_result.request_json
)
worker_result = SendMessage(
to=worker_id,
message="advisor-response.v1: {advisor_result}"
)
# B-3.5. self_review ゲート(Reviewer spawn 前、Lead が機械的に検証)
# Worker の worker-report.v1 に active self_review rules がそろい、全 verified=true かつ evidence 非空であること
# tdd.enforce.enabled=true かつ tdd_required=true の時は `tdd-red-evidence-attached` も active rule として必須
# verified=false または evidence=="" が 1 件でもあれば Reviewer を spawn せず Worker に差し戻す
self_review_failures = 0
MAX_SELF_REVIEW_RETRIES = 2 # 3 回目 (retries=2) で Lead が escalate
while True:
unverified = [
r for r in worker_result.self_review
if (not r.get("verified")) or (not r.get("evidence"))
]
if not unverified:
break # 全 rule verified → B-4 (実レビュー) へ進む
self_review_failures += 1
if self_review_failures > MAX_SELF_REVIEW_RETRIES:
# 3 回目でも未確認項目あり → Lead に escalate
Plans.md: task.status = "cc:TODO" # 着手前に戻す
raise EscalationError(f"self_review が 3 回の差し戻しでも未確認 (rules: {[u['rule'] for u in unverified]})")
# Worker に差し戻し (Reviewer spawn せず)
SendMessage(
to=worker_id,
message=f"self_review に未確認 rule があります: {[u['rule'] for u in unverified]}。各 rule の evidence を実コマンド出力または literal テスト結果で埋め、TDD 必須時は .claude/state/tdd-red-log/<task-id>.jsonl または literal failing test output を添えて verified=true にしてから amend してください"
)
worker_result = wait_for_response(worker_id)
# B-4. Lead がレビュー実行(Codex exec 優先)
diff_text = git("-C", worker_result.worktreePath, "show", worker_result.commit)
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 まで)
# Worker はフォアグラウンドで完了済みだが、SendMessage で再開可能
# (CC: SendMessage(to: agentId) / Codex: resume_agent(agent_id) + send_input)
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:
SendMessage(to=worker_id, message="指摘内容: {issues}\n修正して amend してください")
# Worker が修正 → amend → 更新された commit hash を返す
updated_result = wait_for_response(worker_id)
latest_commit = updated_result.commit
diff_text = git("-C", worker_result.worktreePath, "show", latest_commit)
verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
review_count++
# B-6. 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:
git cherry-pick --no-commit {latest_commit} # feature branch → 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-7. Progress feed
print("📊 Progress: Task {completed}/{total} 完了 — {task.内容}")
Advisor は「実装者」でも「レビュー担当」でもない。 迷った時だけ、実行役が次の一歩を決めるための相談役として入る。
advisor-request.v1 を返すPLAN / CORRECTION / STOP のどれかを返すsolo 実行では親セッション自身が Lead を兼ねる。 つまり「自分で実装し、自分で advisor に相談し、最後は独立レビューに回す」形になる。
STOP はその場で止まり、ユーザー判断へ上げる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 などの検証コマンド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, browserPhase C: Post-delegate(統合・報告):
CI が失敗した場合:
タスク完了後にテスト/CI が失敗した場合、修正タスク案を自動生成し、承認後に Plans.md へ反映する:
| 条件 | アクション |
|---|---|
cc:完了 後にテスト失敗 | 修正タスク案を state に保存し、承認を待つ |
| CI 失敗(3回未満) | 修正を実施し、失敗カウントをインクリメント |
| CI 失敗(3回目) | 修正タスク案を提示 + エスカレーション |
.claude/state/pending-fix-proposals.jsonl に修正タスク案を保存:
.fix サフィックス(例: 26.1.fix)fix: [元タスク名] - [失敗原因カテゴリ]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(フォールバック)
レビュアーには以下の閾値基準を渡し、この基準のみで verdict を判定させる。
基準外の改善提案は recommendations として返すが、verdict には影響しない。
| 重要度 | 定義 | verdict への影響 |
|---|---|---|
| critical | セキュリティ脆弱性、データ損失リスク、本番障害の可能性 | 1 件でも → REQUEST_CHANGES |
| major | 既存機能の破壊、仕様との明確な矛盾、テスト不通過 | 1 件でも → REQUEST_CHANGES |
| minor | 命名改善、コメント不足、スタイル不統一 | verdict に影響しない |
| recommendation | ベストプラクティス提案、将来の改善案 | verdict に影響しない |
重要: minor / recommendation のみの場合は 必ず APPROVE を返すこと。 「あったほうが良い改善」は REQUEST_CHANGES の理由にならない。
タスク開始時の HEAD を BASE_REF として保持し、その ref との差分をレビュー対象にする。
公式プラグイン codex-plugin-cc の companion review を使用する。
# タスク開始時に base ref を記録(Step 2 の cc:WIP 更新前に実行)
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 影響 |
|---|---|---|
approve | APPROVE | - |
needs-attention | REQUEST_CHANGES | - |
findings[].severity: critical | critical_issues[] | 1件でも → REQUEST_CHANGES |
findings[].severity: high | major_issues[] | 1件でも → REQUEST_CHANGES |
findings[].severity: medium/low | recommendations[] | verdict に影響しない |
AI Residuals スキャンは引き続き bash "${HARNESS_PLUGIN_ROOT}/scripts/review-ai-residuals.sh" で実行し、
companion review の結果と合わせて最終 verdict を判定する。
# AI Residuals スキャン(companion review と並行実行可能)
AI_RESIDUALS_JSON="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/review-ai-residuals.sh" --base-ref "${BASE_REF}" --include-untracked 2>/dev/null || echo '{"tool":"review-ai-residuals","scan_mode":"diff","base_ref":null,"include_untracked":true,"files_scanned":[],"untracked_files_scanned":[],"summary":{"verdict":"APPROVE","major":0,"minor":0,"recommendation":0,"total":0},"observations":[]}')"
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 無効)で安全にレビューを実行する。
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 モードでは Lead がレビューループを実行する(上記 Phase B 参照):
MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3 回まで)cc:完了 [{hash}] に更新タスク完了時(cc:完了 + commit 後)に自動出力される視覚的サマリ。
非専門家にも変更内容と影響が伝わることを目的とする。
┌─────────────────────────────────────────────┐
│ ✓ Task {N} 完了: {タスク名} │
├─────────────────────────────────────────────┤
│ │
│ ■ 何をしたか │
│ • {変更内容 1} │
│ • {変更内容 2} │
│ │
│ ■ 何が変わるか │
│ Before: {旧動作} │
│ After: {新動作} │
│ │
│ ■ 変更ファイル ({N} files) │
│ {ファイルパス 1} │
│ {ファイルパス 2} │
│ │
│ ■ 残りの課題 │
│ • Task {X} ({status}): {内容} ← Plans.md │
│ • Task {Y} ({status}): {内容} ← Plans.md │
│ (Plans.md に {M} 件の未完了タスクあり) │
│ │
│ commit: {hash} | review: {APPROVE} │
└─────────────────────────────────────────────┘
git diff --stat HEAD~1 と commit message から自動抽出。技術用語は最小限にし、動詞で始めるgit diff --name-only HEAD~1 から取得。5 ファイル超は省略して件数表示cc:TODO / cc:WIP タスクを一覧表示。Plans.md に記載済みかどうかを明示--parallel 強制時): Solo テンプレートを使用全タスク完了後にまとめて出力。各タスクは簡略版(何をしたか + commit hash のみ)で一覧し、 最後に全体サマリ(合計変更ファイル数 + 残り課題)を出力する:
┌─────────────────────────────────────────────┐
│ ✓ Breezing 完了: {N}/{M} タスク │
├─────────────────────────────────────────────┤
│ │
│ 1. ✓ {タスク名 1} [{hash1}] │
│ 2. ✓ {タスク名 2} [{hash2}] │
│ 3. ✓ {タスク名 3} [{hash3}] │
│ │
│ ■ 全体の変更 │
│ {N} files changed, {A} insertions(+), │
│ {D} deletions(-) │
│ │
│ ■ 残りの課題 │
│ Plans.md に {K} 件の未完了タスクあり │
│ • Task {X}: {内容} │
│ │
└─────────────────────────────────────────────┘
harness-plan — 実行するタスクを計画するharness-sync — 実装と Plans.md を同期するharness-review — 実装のレビューharness-release — バージョンバンプ・リリース