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 に委託（明示時のみ） | | 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を実行 | ## Execution Mode Auto Selection（フラグなし時の自動判定） 明示的なモードフラグ（`--parallel`, `--breezing`, `--codex`）がない場合、 対象タスク数に応じて最適なモードを自動選択する: | 対象タスク数 | 自動選択モード | 理由 | |-------------|---------------|------| | **1 件** | Solo | オーバーヘッド最小。直接実装が最速 | | **2〜3 件** | Parallel（Task tool） | Worker 分離のメリットが出始める閾値 | | **4 件以上** | Breezing | Lead 調整 + Worker 並列 + Reviewer 独立の三者分離が効果的 | ### ルール 1. **明示フラグは常にオートモードを上書き**する（`--parallel N` / `--breezing` / `--codex` はタスク数に関係なく強制） 2. **`--codex` は明示時のみ発動**。Codex CLI が未インストールの環境があるため、自動選択しない 3. `--codex` は他モードと組み合わせ可能: `--codex --breezing` → Codex + Breezing ## Execution Backend Selection（実装バックエンド選択） バックエンド（どのランタイムが**実装するか**）は、実行モード（トポロジー: 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>"` | Codex 呼び出しのガバナンス詳細（禁止事項・verdict マッピング等）は [references/codex-cli-only.md](${CLAUDE_SKILL_DIR}/references/codex-cli-only.md) を参照。 run 開始時に resolver で 1 回だけ解決する。`HARNESS_IMPL_BACKEND` env を直接読んで backend を決めてはならない: ```bash bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" ``` precedence（高い順）: 明示フラグ（`--backend` / `--cursor` / `--codex`） > env > project file > user file > 既定 `claude`。プロジェクト設定はユーザースコープを上書きする。 ### Backend 既定（`claude` は意図された既定、警告は不正値 fallback 時のみ） 既定 backend は `claude`（Native subagent）。resolver の未設定 fallback も `claude` であり、正常に `claude` へ解決された場合に警告は**出さない**（2026-07-24 operator 裁定。フォーマットは `breezing` の Narration Rules「Backend 既定と per-run のフラット判断」と同一、cross-ref: `skills/breezing/SKILL.md`）。 - ⚠️ 警告を出すのは resolver が **不正値 fallback** の stderr 警告を出した時だけ。banner 直後に 1 行、同一 run 内で繰り返さない - Lead は作業内容・量に応じて per-run で backend をフラットに選んでよい。選ぶ時は resolver への明示 override（`--backend <v>` / `--codex` / `--cursor`）を使う - `composer` / `コンポーザー` / `composer 2.5` 等の自然言語表現は `--cursor` と同じ intent として扱い、resolver に `--backend cursor` を明示 override で渡す（自然言語 backend trigger） バックエンドは **role-scoped**: 解決済みバックエンドに従うのは実装（worker）ロールのみ。Reviewer / Advisor は常に brain（`--host claude`）固定（primary reviewer を cursor/codex に routing しない）。例外は **fresh-context advisory pre-review** のみ: diff を生成した session と会話状態を共有しない cursor `review` tier が advisory findings を出すことは許可、primary verdict（`APPROVE | REQUEST_CHANGES`）は brain のみが出す。 ```bash bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host claude --role reviewer --field model ``` backend が `codex` / `cursor` の場合、Lead は Worker agent を spawn せず companion を直接呼ぶ（Worker 介在なしトポロジー）。self_review ゲートはスキップし、Lead の diff レビューが唯一の品質ゲートになる。委託前に cursor backend banner を出力し、cherry-pick 前に contract grep 二段ゲート（`test-support-claim-wording.sh` / `check-consistency.sh` / `validate-plugin.sh`）を通す。Mode 1 の Producer → Sub-Lead → Composer 階層、review→iterate ループの詳細は [references/backend-selection.md](${CLAUDE_SKILL_DIR}/references/backend-selection.md) を参照。 ## オプション | オプション | 説明 | デフォルト | |----------|------|----------| | `all` | 全未完了タスクを対象 | - | | `N` or `N-M` | タスク番号/範囲指定 | - | | `--parallel N` | 並列ワーカー数（CC 側の同時実行キャップ 既定 20 が上限。詳細は下記） | 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 | ## Progressive Disclosure 実行依頼は、目的と理由、担当範囲、検証可能な DoD、選択した plan / spec、観測済み証拠、原依頼と適用される承認の参照を渡す。 以降の `{task prompt}` と companion のタスク本文にはこれらを含める。再試行でも元の範囲と条件を残し、追加の finding や advisor response だけで置き換えない。 方法は担当が選ぶ。承認済みの可逆作業を再確認で止めず、不足情報は契約と読み取り調査で回収する。軽微な仮定は明示し、重大な仕様判断や不足する権限に依存する操作だけ止める。 評価・相談だけの依頼から実装を開始しない。推定した変更範囲は保護操作の承認ではない。 独立して検証できる作業を、担当ファイルと同時実行上限を明記して委譲する。他担当の編集を戻さず、関連する follow-up は同じ担当へ返す。Lead も仕様調査や証拠照合を進める。 必須チェックと既定レビューを完了した後は、新しい変更、失敗、未解決の懸念がない限り追加テストや機能を増やさない。 完了報告は実際の差分と検証結果で支え、自己申告だけで完了を判定しない。理由と参照可能な証拠を返し、内部の思考過程は求めない。 まずこの本文で入口、自動選択、停止条件だけを確認する。詳細は必要になった時だけ読む。 | 詳細 | 参照 | |---|---| | Solo / Breezing の 1〜17 ステップ完全版、Phase A/B/C 完全版 | `references/execution-modes.md` | | Backend role-scoped 制約、非 claude トポロジー、Mode 1 階層、review→iterate | `references/backend-selection.md` | | Codex review、Reviewer fallback、verdict mapping、修正ループ | `references/review-loop.md` | | Sprint Contract フィールド一覧、PR Closeout | `references/sprint-contract.md` | | effort tier の多要素スコアリング詳細 | `references/effort-routing.md` | | Solo / Breezing 完了報告の生成 | `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 を開始する。 ### 自主停止の禁止 (140.3、2026-08-22 の release run で 2 回発生した停止パターンの再発防止) 以下は禁止行動。literal に列挙する (AUTOSTART pattern と同じ方式): - background 待ちで turn を終えて停止しない (turn を終えると background 子プロセスは残らない) - 「検証を待ちます」「確認します」「完了を待機します」で turn を終えない - 待つなら同期実行 (foreground / Monitor) で待ち切る。待てないものは保留として報告し、次のタスクへ進む > **Token Optimization (v2.1.69+)**: git 操作を伴わない軽量タスクでは > plugin settings の `includeGitInstructions: false` を有効にしてプロンプトトークンを削減できる。 > **Prompt Cache (CC 2.1.108+)**: 長めの実装や `--resume` を多用する作業では > `ENABLE_PROMPT_CACHING_1H=1` を優先する。 ## スコープダイアログ（引数なし時） 直前の明示依頼や選択済み plan で対象が確定していれば、その範囲を使う。以下の確認は対象範囲が未決の場合だけ行う。 ``` /harness-work どこまでやりますか? 1) 次のタスク: Plans.md の次の未完了タスク → Solo で実行 2) 全部（推奨）: 残りのタスクをすべて完了 → タスク数で自動モード選択 3) 番号指定: タスク番号を入力（例: 3, 5-7）→ 件数で自動モード選択 ``` 引数ありなら即実行（対話スキップ）: - `/harness-work all` → 全タスク、自動モード選択 - `/harness-work 3-6` → 4件なので Breezing 自動選択 ## モデルごとの推論量 effort は推論に使う量の指定。利用者の明示設定を優先し、未指定の担当は `scripts/model-routing.sh` の役割別設定を使う。 CCH のモデルと effort は未指定時の既定値であり、利用者の明示指定と手動変更を尊重する。AI が文言から再調整したり、親の変更を全 Worker へ配ったりしない。担当別 profile と独立 Reviewer の隔離契約は維持する。 Fable 5.1 の計画と相談は `high`。実装 worker と独立 reviewer は、それぞれの設定を使う。 複雑度スコアは見直しの判断材料であり、明示した推論量を自動変更する許可ではない。 free-text marker（旧 `ultrathink`）を spawn prompt に注入しない。 | スコア | code-risk（core/guardrails/security/architecture/migration を含む） | 見直し候補 | |--------|-----------------------------------|-------------| | 0-2 | 不問 | `medium`（Worker frontmatter 既定のまま） | | ≥ 3 | なし | `high` | | ≥ 3 | あり | `xhigh` | breezing モードでも同じロジックを適用する（harness-work が一本化して管理）。スコアリング内訳・lever の詳細は [references/effort-routing.md](${CLAUDE_SKILL_DIR}/references/effort-routing.md) を参照。 ## 実行モード詳細 ### 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` や resolver 出力が `cursor` の run（project / user file 経由の default 含む）は、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") 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")