harness-work

# Harness Work Harness の統合実行スキル。 以下の旧スキルを統合: - `work` — Plans.md タスクの実装（スコープ自動判断） - `impl` — 機能実装（タスクベース） - `breezing` — チームフル自動実行 - `parallel-workflows` — 並列ワークフロー最適化 - `ci` — CI 失敗時の復旧 ## Quick Reference | ユーザー入力 | モード | 動作 | |------------|--------|------| | `harness-work` | **auto** | タスク数で自動判定（下記参照） | | `harness-work all` | **auto** | 全未完了タスクを自動モードで実行 | | `harness-work 3` | solo | タスク3だけ即実行 | | `harness-work --parallel 5` | parallel | 5ワーカーで並列実行（強制） | | `harness-work --codex` | codex | Codex CLI に委託（明示時のみ） | | `harness-work --breezing all` | breezing | resolved backend でチーム実行（配布既定は claude、user/project default で cursor 可） | | `harness-work --breezing --backend cursor all` | breezing | Cursor worker backend を明示してチーム実行 | | `harness-work --breezing --backend claude all` | breezing | Codex native subagent worker を明示してチーム実行 | | `harness-work --breezing` | breezing | チーム実行を強制 | | `harness-work 3 --plan roadmap` | solo | named Plans の `roadmap` からタスク3を実行 | ## Execution Mode Auto Selection（フラグなし時の自動判定） 明示的なモードフラグ（`--parallel`, `--breezing`, `--codex`）がない場合、 対象タスク数に応じて最適なモードを自動選択する: | 対象タスク数 | 自動選択モード | 理由 | |-------------|---------------|------| | **1 件** | Solo | オーバーヘッド最小。直接実装が最速 | | **2〜3 件** | Parallel（Task tool） | Worker 分離のメリットが出始める閾値 | | **4 件以上** | Breezing | Lead 調整 + Worker 並列 + Reviewer 独立の三者分離が効果的 | ### ルール 1. **明示フラグは常にオートモードを上書き**する - `--parallel N` → Parallel モード（タスク数に関係なく） - `--breezing` → Breezing モード（タスク数に関係なく） - `--codex` → Codex モード（タスク数に関係なく） 2. **`--codex` は明示時のみ発動**。Codex CLI が未インストールの環境があるため、自動選択しない 3. `--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`） | spawn_agent で 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 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 は実装役から分離し、担当ごとのモデルを解決する。Claude の計画と相談は Fable 5.1/high を既定にする。 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` | 直列実行強制 | - | | `--codex` | Codex CLI で実装委託（明示時のみ、自動選択しない） | false | | `--backend <claude\|codex\|cursor>` | 明示バックエンド選択（worker ロールのみ適用、precedence 最上位） | resolver result（未設定時は claude） | | `--cursor` | cursor backend（`--backend cursor` の別名） | false | | `--plan NAME` | `plans/manifest.json` の named plan を使う | active/default | | `--no-commit` | 自動コミット抑制 | false | | `--resume <id\|latest>` | 前回セッション再開 | - | | `--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` | Auto Mode rollout を明示。親セッションの permission mode が互換な場合のみ採用を検討 | false | ## Progressive Disclosure 実行依頼は、目的と理由、担当範囲、検証可能な DoD、選択した plan / spec、観測済み証拠、原依頼と適用される承認の参照を渡す。 以降の `{task prompt}` と companion のタスク本文にはこれらを含める。再試行でも元の範囲と条件を残し、追加の finding や advisor response だけで置き換えない。 方法は担当が選ぶ。承認済みの可逆作業を再確認で止めず、不足情報は契約と読み取り調査で回収する。軽微な仮定は明示し、重大な仕様判断や不足する権限に依存する操作だけ止める。 評価・相談だけの依頼から実装を開始しない。推定した変更範囲は保護操作の承認ではない。 独立して検証できる作業を、担当ファイルと同時実行上限を明記して委譲する。他担当の編集を戻さず、関連する follow-up は同じ担当へ返す。Lead も仕様調査や証拠照合を進める。 必須チェックと既定レビューを完了した後は、新しい変更、失敗、未解決の懸念がない限り追加テストや機能を増やさない。 完了報告は実際の差分と検証結果で支え、自己申告だけで完了を判定しない。理由と参照可能な証拠を返し、内部の思考過程は求めない。 まずこの本文で入口、自動選択、停止条件だけを確認する。 詳細は必要になった時だけ読む。 | 詳細 | 参照 | |---|---| | Codex native Solo / Parallel / Breezing の具体手順 | `references/execution-modes.md` | | companion 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` を有効にして > プロンプトトークンを削減できる。 ## スコープダイアログ（引数なし時） 直前の明示依頼や選択済み plan で対象が確定していれば、その範囲を使う。以下の確認は対象範囲が未決の場合だけ行う。 ``` harness-work どこまでやりますか? 1) 次のタスク: Plans.md の次の未完了タスク → Solo で実行 2) 全部（推奨）: 残りのタスクをすべて完了 → タスク数で自動モード選択 3) 番号指定: タスク番号を入力（例: 3, 5-7）→ 件数で自動モード選択 ``` 引数ありなら即実行（対話スキップ）: - `harness-work all` → 全タスク、自動モード選択 - `harness-work 3-6` → 4件なので Breezing 自動選択 ## Effort レベル制御（Codex 0.148 / managed routes） effort はモデルの推論強度を選ぶ正式なノブ。generic な standard / review route は `low(○)/medium(◐)/high(●)/xhigh` を使う。Breezing の implementation worker は managed `worker` route の設定をそのまま使い、skill から effort を上書きしない。 `/effort auto` は generic route の既定へ戻す操作であり、worker route の `max` 契約を `xhigh` へ静かに置換してはならない。 CCH のモデルと effort は未指定時の既定値であり、利用者の明示指定と手動変更を尊重する。native profile / 明示 override を正とし、AI が文言から再調整したり、親の変更を全 Worker へ配ったりしない。独立 Reviewer の隔離と read-only は維持する。 「浅い推論」を観測したら prompt で回避せず、対象 role の中央 routing 設定を確認する。 そのため複雑タスクの強化は **free-text marker（旧 `ultrathink`）を spawn prompt に注入する方式を廃止**し、 複雑度スコアは担当設定を見直す判断材料に限る。skill は利用者の明示 effort を変更せず、未指定の managed worker には配布既定の `max` を使う。 ### 多要素スコアリング タスク着手時に以下のスコアを合算する。 | 要素 | 条件 | スコア | |------|------|--------| | ファイル数 | 変更対象 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 に **書かない**）。 設定を確認する面は次の 2 つ。スコアは設定変更の承認にはならない: - **session `/effort`**: 利用者が明示した推論量を保持する。複雑度の推定だけで host が `/effort high` / `/effort xhigh` を設定しない。 - **managed worker**: Codex native は `.codex/agents/worker.toml`、companion は専用 `worker` route を使う。利用者が明示・手動変更した設定を尊重する。以下のスコア表は見直し候補であり、配布既定 `max` や明示設定を自動変更しない。 | スコア | code-risk（core/guardrails/security/architecture/migration を含む） | 見直し候補 | |--------|-----------------------------------|-------------| | 0-2 | 不問 | `medium` 候補（managed worker route は保持） | | ≥ 3 | なし | `high` | | ≥ 3 | あり | `xhigh` | breezing モードでも同じロジックを適用する（harness-work が一本化して管理）。 ## 実行モード詳細 ### Harness helper script root Harness が同梱する helper script は、作業対象プロジェクトの `scripts/` ではなく、必ず plugin bundle root から呼ぶ。 ```bash 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("CODEX_MODEL_TIER=worker 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")