Agent Browser Skill

ブラウザ自動化を行うスキル。agent-browser CLI を使用して、UI デバッグ・検証・自動操作を実行します。

トリガーフレーズ

このスキルは以下のフレーズで自動起動します：

• 「ページを開いて」「URLを確認して」
• 「クリックして」「入力して」「フォームに」
• 「スクリーンショットを撮って」
• 「UIを確認して」「画面をテストして」
• "open this page", "click on", "fill the form", "screenshot"

機能詳細

実行手順

Step 0: agent-browser の確認

# インストール確認
which agent-browser

# 未インストールの場合
npm install -g agent-browser
agent-browser install

Step 1: ユーザーのリクエストを分類

Step 2: AI スナップショットワークフロー（推奨）

ほとんどの操作で、まずスナップショットを取得してから要素参照で操作します：

# 1. ページを開く
agent-browser open https://example.com

# 2. スナップショット取得（AI 向け、インタラクティブ要素のみ）
agent-browser snapshot -i -c

# 出力例:
# - link "Home" [ref=e1]
# - button "Login" [ref=e2]
# - input "Email" [ref=e3]
# - input "Password" [ref=e4]
# - button "Submit" [ref=e5]

# 3. 要素参照で操作
agent-browser click @e2           # Login ボタンをクリック
agent-browser fill @e3 "user@example.com"
agent-browser fill @e4 "password123"
agent-browser click @e5           # Submit

Step 3: 結果の確認

# 現在の状態をスナップショットで確認
agent-browser snapshot -i -c

# または URL を確認
agent-browser get url

# スクリーンショットを取得
agent-browser screenshot result.png

クイックリファレンス

基本操作

ナビゲーション

情報取得

待機

デバッグ

セッション管理

複数のタブ/セッションを並列管理：

# セッションを指定
agent-browser --session admin open https://admin.example.com
agent-browser --session user open https://example.com

# セッション一覧
agent-browser session list

# 特定セッションで操作
agent-browser --session admin snapshot -i -c

MCP ブラウザツールとの使い分け

原則: まず agent-browser を試し、うまくいかない場合のみ MCP ツールを使用。

注意事項

• agent-browser はヘッドレスモードがデフォルト
• --headed オプションでブラウザを表示可能
• セッションは明示的に close するまで維持される
• 認証が必要なサイトはセッションを活用

Auth Skills

認証と決済機能の実装を担当するスキル群です。

機能詳細

実行手順

1. 品質判定ゲート（Step 0）
2. ユーザーのリクエストを分類(認証 or 決済)
3. 上記の「機能詳細」から適切な参照ファイルを読む
4. その内容に従って実装

Step 0: 品質判定ゲート（セキュリティチェックリスト）

認証・決済機能は常にセキュリティリスクが高いため、作業開始前に必ず以下を表示:

🔐 セキュリティチェックリスト

この作業はセキュリティ上重要です。以下を確認してください：

### 認証関連
- [ ] パスワードはハッシュ化（bcrypt/argon2）
- [ ] セッション管理は安全か（HTTPOnly Cookie）
- [ ] CSRF 対策は実装されているか
- [ ] レート制限（ブルートフォース対策）

### 決済関連
- [ ] 機密情報（カード番号等）をサーバーに保存しない
- [ ] Stripe/決済プロバイダの SDK を正しく使用
- [ ] Webhook の署名検証
- [ ] 金額改ざん防止（サーバー側で金額を確定）

### 共通
- [ ] エラーメッセージが詳細すぎないか（情報漏洩防止）
- [ ] ログに機密情報を出力していないか

セキュリティ重要度表示

⚠️ 注意レベル: 🔴 高

この機能は以下のリスクがあります：
- 認証情報の漏洩
- 不正アクセス
- 決済の不正操作

専門家によるレビューを推奨します。

VibeCoder 向け

🔐 安全にログイン・決済機能を作るために

1. **パスワードは「ハッシュ化」する**
   - 元のパスワードを復元できない形で保存
   - 万が一データが漏れても安全

2. **カード情報はサーバーに保存しない**
   - Stripe などの専用サービスに任せる
   - 自分のサーバーには一切保存しない

3. **エラーメッセージは曖昧に**
   - 「パスワードが違います」ではなく「認証に失敗しました」
   - 悪意ある人にヒントを与えない

Breezing — Team Execution Mode (Codex Host)

この SKILL.md は Codex host 版です。 Claude Code 版は skills/breezing/SKILL.md を参照してください。 backend は resolver で選びます。配布 plugin のフラグなし既定は claude 互換のままです。 --cursor / --backend cursor、または HARNESS_IMPL_BACKEND=cursor を設定した環境では Cursor worker backend を使います。 frontmatter の allowed-tools も、この4つの Codex native tool 名に合わせます。

後方互換エイリアス: harness-work --breezing をチーム実行モードで動かします。

Quick Reference

breezing                        # スコープを聞いてから実行
breezing all                    # resolved backend で ready task を完走（配布既定は claude、現環境は user config で cursor 可）
breezing 3-6                    # resolved backend でタスク3〜6を完走
breezing composer 2.5 all       # 自然言語 trigger: cursor backend として扱う
breezing --backend cursor all    # Cursor worker backend を明示
breezing --backend claude all    # Codex native spawn_agent worker を明示
breezing --codex all             # Codex CLI worker backend を明示
breezing --cursor all            # Cursor worker backend を明示
breezing --max-workers 2 all     # ready task の同時 spawn 上限を2に
breezing --max-workers 1 all     # 旧来の直列挙動に戻す
breezing --no-discuss all       # 計画議論スキップで全タスク完走

Options

Execution

このスキルは harness-work --breezing に委譲します。 以下の設定で実行してください:

1. 引数を harness-work --breezing に渡す（--max-workers N は breezing 固有オプションとして解釈し、harness-work の --parallel とは別概念）
2. チーム実行モードを強制 — Lead → Worker spawn → 必要時 Advisor → companion review Reviewer の四者分離
3. Lead は delegate 専念 — コードを直接書かない

Execution Backend (persistent)

バックエンド選択（worker を claude / codex / cursor のどれで実装するか）の正本は harness-work の「Execution Backend Selection（実装バックエンド選択）」を参照する。 そこに precedence、role-scope（review / advisor は Opus 固定）、self_review スキップ、cursor banner が定義されている。 backend 判定は 必ず resolver 経由にし、HARNESS_IMPL_BACKEND env だけを直読みしない。

Codex Breezing も配布 plugin では call-site default を変えない:

bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh"

precedence は --backend / --cursor / --codex > HARNESS_IMPL_BACKEND env > project env.local > user ~/.config/claude-harness/impl-backend.env > call-site default claude。 つまり配布 plugin のフラグなし breezing all は互換性のため claude のまま。 この環境のように user/project config で HARNESS_IMPL_BACKEND=cursor が設定されている場合だけ、 フラグなしで Cursor worker backend になる。Codex native subagent worker を明示する時は --backend claude を指定する。

composer / コンポーザー / Composer で / composer 2.5 / composer モード は、正式に cursor backend の trigger として扱う。 これは --cursor 相当の intent であり、Lead は resolve-impl-backend.sh を経由して backend を確定する。 解決時は明示 override として --backend cursor を渡し、env / project / user file / default より優先させる。 composer は Codex native Worker の内側に spawn する追加 agent ではなく、非 claude backend の規約どおり Lead が cursor-companion.sh を直接呼ぶ。

既定の worker 数は max。 ここでの max は「対象スコープ内で Depends が満たされ、今すぐ実行できる ready task の最大数」を意味する。 無制限に Worker を spawn する意味ではない。 依存待ちのタスクは、前段タスクが完了して ready になるまで spawn しない。 旧来の 1 件ずつ進める直列挙動に戻したい場合は --max-workers 1 を指定する。

Worker の実装は並列化できるが、レビューと main への cherry-pick は直列で行う。 これは同じ main worktree への書き込み競合を避けるため。

harness-work との違い

Team Composition（Codex Native）

Flow Summary

breezing [scope] [--backend claude|codex|cursor] [--max-workers N] [--no-discuss]
    │
    ↓ Load harness-work --breezing
    │
Phase 0: Planning Discussion (--no-discuss でスキップ)
Phase A: Pre-delegate（チーム初期化 + worktree 準備）
Phase B: Delegate（resolver-selected worker + 必要時 Advisor + companion review レビュー）
Phase C: Post-delegate（統合検証 + Plans.md 更新 + commit）

Advisor Protocol

Worker は generic な subagent を増やさない。 迷った時は構造化 JSON で相談要求だけ返し、Lead が advisor を呼ぶ。

1. Worker → advisor-request.v1
2. Lead → Advisor
3. Advisor → advisor-response.v1
4. Lead → 同じ Worker に advice を返して続行
5. Reviewer は最後の成果物だけを見る

相談条件は loop / solo とそろえる。

• 高リスク task（needs-spike / security-sensitive / state-migration）の初回実行前
• 同じ原因の失敗が 2 回続いた後
• plateau により PIVOT_REQUIRED を返す直前
• 同じ trigger_hash は 1 回だけ。task ごとの相談回数は最大 3 回

Realtime Handoff / Silence Policy

Codex 0.123.0 以降では、background agent が realtime handoff の transcript delta を受け取れる。 Breezing ではこの仕組みを「余計な通知を増やす入口」ではなく、「必要な時だけ判断を更新するための入力」として扱う。

ひとことで: Worker / Advisor / Reviewer は、状態が変わらない transcript delta には反応せず、Lead への報告は material state change に絞る。

たとえると、複数人の作業部屋で全員が独り言を実況するのではなく、担当作業が終わった時、詰まった時、判断待ちの時だけ声をかける形。

報告するもの:

• Worker の完了 JSON、blocked 理由、必要な advisor-request.v1
• Advisor の PLAN / CORRECTION / STOP
• Reviewer の APPROVE / REQUEST_CHANGES
• validation failure、contract readiness failure、plateau、drift 検知
• Lead が出す task 完了単位の progress feed

沈黙してよいもの:

• transcript delta を受け取っただけで、task status、review verdict、advisor decision が変わっていない場合
• tool stdout の細かな増分で、job log に残っていれば十分なもの
• parallel spawn 中の待機 heartbeat。待機は wait_agent / job status に任せる

途中報告の頻度:

• Lead の progress feed は task 完了ごとに 1 回を基本にする。
• Worker / Reviewer は「完了・差し戻し・ブロック」の結果だけを返し、delta ごとの小報告は避ける。
• user が明示的に status を求めた場合だけ、Lead がまとめて現在地を返す。

Advisor / Reviewer drift との関係:

• silence policy は Advisor / Reviewer を黙らせる免除ではない。
• advisor-request.v1 送信後に response が返らない、reviewer profile に必要な result がない、review loop が plateau した場合は drift として扱う。
• Advisor は方針助言、Reviewer は品質判定という役割分離を維持し、沈黙は「不要な通知を出さない」ためだけに使う。

Phase 0: Planning Discussion（構造化 3 問チェック）

全タスク実行前に、以下の 3 問で計画の健全性を確認する。 --no-discuss 指定時は全スキップ。

Q1. スコープ確認:

「{{N}} 件のタスクを実行します。スコープは適切ですか？」

Q2. 依存関係確認（Plans.md に Depends カラムがある場合のみ）:

「タスク {{X}} は {{Y}} に依存しています。実行順序は合っていますか？」

Q3. リスクフラグ（[needs-spike] タスクがある場合のみ）:

「タスク {{Z}} は [needs-spike] です。先に spike しますか？」

Phase A: Pre-delegate

1. Plans.md を読み込み、対象タスクを特定
2. 依存グラフを解析し、実行順序を決定
3. 各タスク用に git worktree を作成

Phase B: Delegate（Codex Host Orchestration）

for task in execution_order:
    # B-0. 作業ディレクトリ分離
    worktree_path = "/tmp/worker-{task.number}-$$"
    branch_name = "worker-{task.number}-$$"
    git worktree add -b {branch_name} {worktree_path}
    TASK_BASE_REF = git rev-parse HEAD

    # B-1. sprint-contract を生成
    contract_path = bash("node \"${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js\" {task.number}")
    contract_path = bash("scripts/enrich-sprint-contract.sh {contract_path} --check \"DoD を reviewer 観点で確認\" --approve")
    bash("scripts/ensure-sprint-contract-ready.sh {contract_path}")

    # B-2. Worker 委託
    Plans.md: task.status = "cc:WIP"

    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 backend == "cursor":
        print("🚀 cursor / $(bash \"${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh\" --host cursor --role worker --field model) / {branch_name} / {task.ID}")
        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: breezing delegated change")
            latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
        if latest_commit == TASK_BASE_REF:
            raise EscalationError("cursor companion produced no commit")
        worker_result = {type: "companion-result.v1", baseCommit: TASK_BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: branch_name, files_changed: git("-C", worktree_path, "diff", "--name-only", "{TASK_BASE_REF}..HEAD"), summary: companion_output}
        worker_id = null
    elif backend == "codex":
        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 == TASK_BASE_REF:
            raise EscalationError("codex companion produced no commit")
        worker_result = {type: "companion-result.v1", baseCommit: TASK_BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: branch_name, files_changed: git("-C", worktree_path, "diff", "--name-only", "{TASK_BASE_REF}..HEAD"), summary: companion_output}
        worker_id = null
    else:
        print("🚀 claude / native-subagent / {branch_name} / {task.ID}")
        worker_id = spawn_agent({
            message: "作業ディレクトリ: {worktree_path} で作業してください。\n\nタスク: {task.内容}\nDoD: {task.DoD}\ncontract_path: {contract_path}\n\n実装してください。完了後 git commit してください。\n\n完了時、以下の JSON を返してください:\n{\"commit\": \"<hash>\", \"files_changed\": [...], \"summary\": \"...\"}",
            fork_context: true
        })
        worker_result = wait_agent({ targets: [worker_id] })

    # B-3. Worker が advice request を返した時だけ、Lead が Advisor を呼ぶ
    if backend == "claude" and worker_result.type == "advisor-request.v1":
        advisor_id = spawn_agent({
            agent_type: "default",
            message: worker_result.request_json,
            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 がレビュー実行（TASK_BASE_REF 起点）
    # 公式プラグイン companion review を使用（harness-work の「レビューループ」参照）:
    #   bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" review --base {TASK_BASE_REF}
    #   → verdict マッピング: approve→APPROVE, needs-attention→REQUEST_CHANGES
    VERDICT = review_task(worktree_path, TASK_BASE_REF)  # static review（harness-work 参照）
    PROFILE = jq(contract_path, ".review.reviewer_profile")
    BROWSER_MODE = jq(contract_path, ".review.browser_mode // \"scripted\"")
    REVIEW_INPUT = "review-output.json"
    if PROFILE == "runtime":
        # worktree 内で runtime checks を実行
        REVIEW_INPUT = bash("cd {worktree_path} && 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":
            REVIEW_INPUT = "review-output.json"  # static review にフォールバック
    if PROFILE == "browser":
        # browser artifact は PENDING_BROWSER scaffold。reviewer agent が後続で実行。
        BROWSER_ARTIFACT = bash("scripts/generate-browser-review-artifact.sh {contract_path}")
        # REVIEW_INPUT は static review のまま維持
    if REVIEW_INPUT != "review-output.json" and jq(REVIEW_INPUT, ".verdict") == "DOWNGRADE_TO_STATIC":
        REVIEW_INPUT = "review-output.json"
    bash("scripts/write-review-result.sh {REVIEW_INPUT} {commit_hash}")

    # 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
    while VERDICT == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
        if backend == "claude":
            send_input({
                target: worker_id,
                message: "指摘内容: {issues}\n修正して git commit --amend してください。修正後 JSON を再出力してください。"
            })
            wait_agent({ targets: [worker_id] })
        elif backend == "cursor":
            previous_commit = git("-C", worktree_path, "rev-parse", "HEAD")
            bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worktree_path} \"Review findings:\n{issues}\n\nFix the findings and create one new git commit before returning.\"")
            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: breezing review fix")
                latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
            if latest_commit == previous_commit:
                raise EscalationError("cursor companion retry produced no new commit")
        else:
            previous_commit = git("-C", worktree_path, "rev-parse", "HEAD")
            companion_state_file = "{worktree_path}/.claude/state/codex-primary-environment.json"
            bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worktree_path} \"Review findings:\n{issues}\n\nFix the findings and create one new git commit before returning.\"")
            latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
            if latest_commit == previous_commit:
                raise EscalationError("codex companion retry produced no new commit")
        VERDICT = review_task(worktree_path, TASK_BASE_REF)
        review_count++

    # B-6. Worker 終了
    if backend == "claude":
        close_agent({ target: worker_id })

    # B-7. 結果処理
    if VERDICT == "APPROVE":
        commit_hash = git("-C", worktree_path, "rev-parse", "HEAD")
        git cherry-pick --no-commit {TASK_BASE_REF}..{commit_hash}
        git commit -m "{task.内容}"
        Plans.md: task.status = "cc:完了 [{short_hash}]"
    else:
        → ユーザーにエスカレーション（Plans.md は cc:WIP のまま）
        → 後続タスクも停止

    # B-8. Worktree クリーンアップ
    git worktree remove {worktree_path}
    git branch -D {branch_name}

    # B-9. Progress feed
    print("📊 Progress: Task {completed}/{total} 完了 — {task.内容}")

ready task の並列 spawn（既定 max / --max-workers N 指定時）

Depends が満たされた ready task が複数ある場合、既定では ready task の数まで同時 spawn する。 --max-workers N を指定すると、同時 spawn 数を N 件までに制限する。 --max-workers 1 は旧来の直列挙動に戻す escape hatch。

wait_agent のセマンティクス: wait_agent({targets: [a, b]}) は最初に完了した1つを返す（全完了待ちではない）。 したがって、全 Worker の完了を待つにはループで個別に wait_agent を呼ぶ。

# 独立タスク A, B を並列 spawn（各自 worktree 分離済み）
worker_a = spawn_agent({ message: "作業ディレクトリ: /tmp/worker-a-$$ ...", fork_context: true })
worker_b = spawn_agent({ message: "作業ディレクトリ: /tmp/worker-b-$$ ...", fork_context: true })

# 各 Worker の完了を個別に待ち → レビュー → cherry-pick（直列）
# wait_agent は最初の1つを返すので、残りの Worker はまだ動作中
for worker_id in [worker_a, worker_b]:
    wait_agent({ targets: [worker_id] })    # この Worker の完了を待つ
    VERDICT = review_task(worktree_path, TASK_BASE_REF)  # harness-work 参照
    # 修正ループ（必要なら）...
    close_agent({ target: worker_id })
    if VERDICT == "APPROVE":
        cherry-pick → Plans.md 更新

制約: 並列化できるのは Depends が満たされた ready task のみ。 max は ready task 数の上限であり、無制限 spawn ではない。 レビュー → cherry-pick は直列実行（main への書き込みが競合するため）。

Worker の出力契約

Worker プロンプトには、完了時に以下の JSON を返すことを明示する:

{
  "commit": "a1b2c3d",
  "files_changed": ["src/foo.ts", "tests/foo.test.ts"],
  "summary": "foo モジュールに bar 機能を追加"
}

Lead はこの JSON を解析して commit hash とファイル一覧を取得する。

Progress Feed（Phase B 中の進捗通知）

📊 Progress: Task 1/5 完了 — "harness-work に失敗再チケット化を追加"
📊 Progress: Task 2/5 完了 — "harness-sync に --snapshot を追加"

完了報告（Phase C）

全タスク完了後、Lead が以下の手順でリッチ完了報告を生成:

1. git log --oneline {session_base_ref}..HEAD で全 cherry-pick コミットを収集
2. git diff --stat {session_base_ref}..HEAD で全体の変更規模を取得
3. Plans.md の残タスクを抽出
4. Breezing テンプレートに従い出力

Claude Code 版との差分

Related Skills

• harness-work — 単一タスクからチーム実行まで（本体）
• harness-sync — 進捗同期
• harness-review — コードレビュー

CC-Cursor-CC Skill (Plan Validation Round Trip)

Supports the flow of sending brainstormed content from Claude Code to Cursor (PM) for feasibility validation.

Prerequisites

This skill assumes 2-agent operation.

Execution Flow

Step 1: Extract Brainstorming Context

Extract from recent conversation:

1. Goal (feature/purpose)
2. Technology choices
3. Decisions made
4. Undecided items
5. Concerns

Step 2: Add Provisional Tasks to Plans.md

## 🟠 Under Validation: {{Project}} `pm:awaiting-validation`

### Provisional Tasks (To Validate)
- [ ] {{task1}} `awaiting-validation`
- [ ] {{task2}} `awaiting-validation`

### Undecided Items
- {{item1}} → **Requesting PM decision**

Step 3: Generate Validation Request for Cursor

Generate text to copy-paste to Cursor:

## 📋 Plan Validation Request

**Goal**: {{summary}}

**Provisional tasks**:
1. {{task1}}
2. {{task2}}

### ✅ Requesting Cursor (PM) to:
1. Validate feasibility
2. Break down tasks
3. Decide undecided items
4. Update Plans.md (awaiting → cc:TODO)

Step 4: Guide Next Action

1. Copy & paste request to Cursor
2. Run /plan-with-cc in Cursor
3. Cursor updates Plans.md
4. Cursor runs /handoff-to-claude
5. Copy & paste back to Claude Code

Overall Flow

Claude Code (Brainstorm)
    ↓ /cc-cursor-cc
Cursor (PM validates & breaks down)
    ↓ /handoff-to-claude
Claude Code (/work implements)

Claude/Codex Update Review ガードレール

Claude Code / OpenAI Codex のアップデート統合時に「Feature Table に書いただけ」を防止する品質ガードレール。 Feature Table への追加が実装・検証・明示的な将来タスク化を伴っているかを分類し、不足があれば実装案を強制出力する。

Quick Reference

以下の状況でこのスキルがトリガーされる:

• Claude Code / Codex upstream update 統合 PR のレビュー時
• docs/CLAUDE-feature-table.md に新行が追加された diff を検出した時
• /harness-review が upstream update 統合 PR と判定した場合の内部呼び出し
• claude-codex-upstream-update スキル更新のレビュー時

トリガーしない状況:

• 通常の実装作業
• Feature Table / upstream 追従に関係しない変更
• セットアップ・初期化作業

差分入力の取得

このスキルは diff-aware review 専用のため、必ず以下のどちらかでレビュー対象差分を確定する。

1. 呼び出し元の /harness-review が PR diff / changed files / Feature Table 追加行を渡す
2. このスキル自身が read-only Bash で git status --short, git diff --name-only, git diff -- docs/CLAUDE-feature-table.md, git show --stat --name-only などを実行して確認する

Bash は read-only git inspection のみに使う。テスト実行、format、生成、network access、ファイル変更を伴うコマンドは実行しない。 diff が取得できない場合は B: 書いただけ 0 件 と推定せず、「差分未提供のため分類不能」としてレビューを止める。

前提チェック

レビュー冒頭で必ず確認する:

• diff source が呼び出し元提供または read-only git inspection のどちらかで確定しているか
• skills/ や hooks/ を編集した PR の場合、直後に /reload-plugins を実行して runtime cache を更新したか（{skills,hooks}/** ガイドライン準拠）
• upstream のバージョン別分解表があるか
• Claude Code の一次情報 URL が anthropics/claude-code または公式 docs になっているか
• Codex の一次情報 URL が openai/codex/releases または OpenAI 公式記事になっているか
• B: 書いただけ が残っていないか
• skill mirror を触る場合、skills/, codex/.codex/skills/, .agents/skills/ の差分が意図通りか

禁止する古い参照:

• 旧 TypeScript guardrail path
• 旧 TypeScript implementation glob
• 旧 Codex feature-table path
• 旧 Codex plugin directory
• 旧 Codex state directory を現行正本として扱う記述
• 存在しない Anthropic 側 Codex repo URL

A/B/C/P 分類

Feature Table に追加された各項目を、以下の A/B/C/P のいずれかに分類する。

(A) 実装あり

定義: Feature Table の追加に対応する hooks / settings / Go / scripts / agents / skills / tests の変更が同じ PR に含まれている。

判定条件:

• Feature Table の行で言及されている機能に関連するファイルが変更されている
• hooks/hooks.json, .claude-plugin/hooks.json, .claude-plugin/settings.json, go/internal/guardrail/, go/internal/hookhandler/, scripts/, agents/, skills/, tests/ のいずれかに実体差分がある
• 対象テストまたは検証スクリプトで固定されている

例:

結果: OK。追加のアクション不要。

(B) 書いただけ

定義: Feature Table にのみ行が追加され、Harness 側の実装変更も Plans 化もない。かつ upstream 自動継承にも該当しない。

判定条件:

• Feature Table に新行がある
• 同じ PR 内で関連する実装 / test / skill / Plans の変更がない
• Harness が独自の付加価値を提供すべき機能である

例:

結果: NG。PR をブロックし、実装案または Plans 化を要求する。

(C) upstream 自動継承

定義: Claude Code / Codex 本体のパフォーマンス改善・バグ修正・内部最適化等で、Harness 側の変更が不要な項目。

判定条件:

• upstream 本体の修正であり、Harness がラップ・拡張する余地がない
• Harness の settings / hooks / guardrail / workflow / tests に影響しない
• Feature Table に「upstream 自動継承」または「CC 自動継承 / Codex 側自動継承」と明記されている

注意:

• permission / sandbox / security / Bash allowlist / MCP trust boundary は安易に C にしない
• その項目が Harness の独自 guardrail や settings に影響しないことを確認してから C にする
• Claude Code 2.1.113 の hardening は、sandbox.network.deniedDomains, wrapper Bash deny, find -exec/-delete, macOS dangerous rm paths を確認するまで C 判定しない

例:

結果: OK。ただし理由を明記する。

(P) Plans 化

定義: 今回は直接実装しないが、Harness に取り込む価値があるため Plans.md に明示タスクとして残す項目。

判定条件:

• Feature Table の付加価値列が A: 将来タスク化 または P: Plans 化 として読める
• Plans.md に対応タスクがあり、setup / guardrails / memory / Codex workflow など実装面が明記されている
• alpha release や大規模設計変更など、即実装しない理由が書かれている

例:

結果: OK。次回 cycle で拾える。

Upstream update PR チェックリスト

## Claude/Codex update 統合チェックリスト

### 1. 一次情報と分解表
- [ ] diff source が呼び出し元提供または read-only git inspection のどちらかで確定している
- [ ] Claude / Codex の公式 URL を確認した
- [ ] Version / Upstream item / Category / Harness surface / Action の表がある
- [ ] alpha / stable / docs-only の区別がある

### 2. Feature Table 差分
- [ ] `docs/CLAUDE-feature-table.md` の追加行を列挙した
- [ ] 各行に A / C / P のいずれかが付いている
- [ ] B が 0 件である

### 3. カテゴリ別の確認
- [ ] (A) 実装あり: 対応する実装ファイルとテストがある
- [ ] (B) 書いただけ: 0 件。残る場合は PR ブロック
- [ ] (C) 自動継承: permission / sandbox / security / workflow 影響を確認済み
- [ ] (P) Plans 化: `Plans.md` に将来タスクがある

### 4. Mirror と stale path
- [ ] `skills/` と `codex/.codex/skills/` の意図しない drift がない
- [ ] `.agents/skills/` が存在する場合、Claude/Codex 表記が壊れていない
- [ ] 旧 TypeScript guardrail path、旧 Codex plugin directory、旧 Codex feature-table path などの旧参照がない

### 5. CHANGELOG / tests
- [ ] CHANGELOG に「今まで / 今後」または相当する user-facing 説明がある
- [ ] upstream integration test または対象 unit test が追加 / 更新されている

カテゴリ B 検出時の出力フォーマット

カテゴリ B が 1 件以上検出された場合、以下のフォーマットで実装案を出力する。 このフォーマットの出力は必須であり、省略は許可されない。

## カテゴリ B 検出: 実装案

### B-{番号}. {Feature Table の項目名}

**現状**: Feature Table に記載のみ。Harness 側の実装 / 検証 / Plans 化なし。

**Harness ならではの付加価値**:
{この機能を Harness がどう活用すべきかの具体的な説明}

**実装案**:

| 対象ファイル | 変更内容 |
|------------|---------|
| `{ファイルパス}` | {具体的な変更内容} |
| `{ファイルパス}` | {具体的な変更内容} |

**ユーザー体験の改善**:
- 今まで: {現在のユーザー体験}
- 今後: {実装後のユーザー体験}

**実装の優先度**: {高 / 中 / 低}
**推定工数**: {小 / 中 / 大}

関連スキル

• claude-codex-upstream-update - upstream 差分調査と実装 cycle
• harness-review - コードレビュー
• harness-work - カテゴリ B / P の実装
• memory - 分類基準の SSOT 化

CI/CD Skills

CI/CD パイプラインに関する問題を解決するスキル群です。

発動条件

• 「CIが落ちた」「GitHub Actionsが失敗」
• 「ビルドエラー」「テストが通らない」
• 「パイプラインを直して」

機能詳細

実行手順

1. テスト vs 実装判定（Step 0）
2. ユーザーの意図を分類（分析 or 修正）
3. 複雑度を判定（下記参照）
4. 上記の「機能詳細」から適切な参照ファイルを読む、または ci-cd-fixer サブエージェント起動
5. 結果を確認し、必要に応じて再実行

Step 0: テスト vs 実装判定（品質判定ゲート）

CI 失敗時、まず原因の切り分けを行う:

CI 失敗報告
    ↓
┌─────────────────────────────────────────┐
│           テスト vs 実装判定             │
├─────────────────────────────────────────┤
│  エラーの原因を分析:                    │
│  ├── 実装が間違い → 実装を修正          │
│  ├── テストが古い → ユーザーに確認      │
│  └── 環境問題 → 環境修正                │
└─────────────────────────────────────────┘

禁止事項（改ざん防止）

⚠️ CI 失敗時の禁止事項

以下の「解決策」は禁止です：

| 禁止 | 例 | 正しい対応 |
|------|-----|-----------|
| テスト skip 化 | `it.skip(...)` | 実装を修正 |
| アサーション削除 | `expect()` を消す | 期待値を確認 |
| CI チェック迂回 | `continue-on-error` | 根本原因修正 |
| lint ルール緩和 | `eslint-disable` | コードを修正 |

判断フロー

🔴 CI が失敗しています

**判断が必要です**:

1. **実装が間違い** → 実装を修正 ✅
2. **テストの期待値が古い** → ユーザーに確認を求める
3. **環境の問題** → 環境設定を修正

⚠️ テストの改ざん（skip化、アサーション削除）は禁止です

どれに該当しますか？

承認が必要な場合

テスト/設定の変更がやむを得ない場合:

## 🚨 テスト/設定変更の承認リクエスト

### 理由
[なぜこの変更が必要か]

### 変更内容
[差分]

### 代替案の検討
- [ ] 実装の修正で解決できないか確認した

ユーザーの明示的な承認を待つ

Git log 拡張フラグの活用（CC 2.1.49+）

CI 失敗時の原因コミット特定に構造化ログを活用します。

原因コミットの特定

# 構造化フォーマットでコミット分析
git log --format="%h|%s|%an|%ad" --date=short -10

# トポロジカル順序で時系列分析
git log --topo-order --oneline -20

# 変更ファイルと原因の紐付け
git log --raw --oneline -5

主な活用場面

出力例

🔍 CI 失敗原因分析

最近のコミット（構造化）:
| Hash | Subject | Author | Date |
|------|---------|--------|------|
| a1b2c3d | feat: update API | Alice | 2026-02-04 |
| e4f5g6h | test: add tests | Bob | 2026-02-03 |

変更ファイル（--raw）:
├── src/api/endpoint.ts (Modified) ← 型エラー発生
├── tests/api.test.ts (Modified)
└── package.json (Modified)

→ a1b2c3d のコミットが原因の可能性大
  型エラー: src/api/endpoint.ts:42

サブエージェント連携

以下の条件を満たす場合、Task tool で ci-cd-fixer を起動:

• 修正 → 再実行 → 失敗のループが 2回以上 発生
• または、エラーが複数ファイルにまたがる複雑なケース

起動パターン:

Task tool:
  subagent_type="ci-cd-fixer"
  prompt="CI失敗を診断・修正してください。エラーログ: {error_log}"

ci-cd-fixer は安全第一で動作（デフォルト dry-run モード）。 詳細は agents/ci-cd-fixer.md を参照。

VibeCoder 向け

🔧 CI が壊れたときの言い方

1. **「CI が落ちた」「赤くなった」**
   - 自動テストが失敗している状態

2. **「なんで失敗してるの？」**
   - 原因を調べてほしい

3. **「直して」**
   - 自動で修正を試みる

💡 重要: テストを「ごまかす」修正は禁止です
   - ❌ テストを消す、スキップする
   - ⭕ コードを正しく直す

「テストが間違ってそう」と思ったら、
まず確認してから対応を決めましょう

CRUD Skill

Auto-generates CRUD functionality for specified entities (tables) at production-ready level.

Quick Reference

• "Create CRUD for task management" → /crud tasks
• "Want search and pagination too" → Includes all together
• "Include permissions (who can view/edit)" → Sets up authorization/rules together

Deliverables

• CRUD + validation + authorization + tests, complete production-safe set
• Minimize diff to match existing DB/code

Features:

• Validation (Zod) auto-add
• Auth/authorization (Row Level Security) auto-config
• Relations (one-to-many, many-to-many) support
• Pagination, search, filters
• Auto-generated test cases

Auto-invoke Skills

This skill must explicitly invoke the following skills with the Skill tool:

Execution Flow

Detailed steps are described in the phases below.

Phase 1: Entity Analysis

1. Parse entity name from $ARGUMENTS
2. Detect existing schema (Prisma, Drizzle, raw SQL)
3. Infer field types and relations

Phase 2: CRUD Generation

1. Generate model/schema if needed
2. Create API endpoints (REST or tRPC)
3. Add validation schemas (Zod)
4. Configure authorization rules

Phase 3: Test Generation

1. Create unit tests for each endpoint
2. Add integration tests
3. Generate test fixtures

Phase 4: Verification

1. Run type check
2. Run tests
3. Verify build

Supported Frameworks

Output Structure

src/
├── lib/
│   └── validations/
│       └── {entity}.ts        # Zod schemas
├── app/api/{entity}/
│   ├── route.ts              # GET (list), POST (create)
│   └── [id]/
│       └── route.ts          # GET, PUT, DELETE
└── tests/
    └── {entity}.test.ts      # Test cases

Related Skills

• impl - Feature implementation
• verify - Build verification
• auth - Authentication/authorization

cursor:ask — Read-Only Cursor Delegate

cursor-agent (Composer) に read-only で質問・調査・設計相談・敵対的レビューを委譲する軽量スキル。

cursor-companion.sh task は引数なしで --mode ask (hard read-only stop) が自動で付くため、--write を渡さない限り cursor 側は ファイル書き込み・コマンド実行ができない。これにより worktree 隔離・cherry-pick・Lead diff review がすべて不要になる。

Quick Reference

cursor:ask "この設計判断、Composer 視点でどう思う？"
cursor:ask "TASK_BASE_REF からの diff を読んで、見落としを 3 つ挙げて"
cursor:ask "harness-mem の cross-project N-call、楽観的すぎる前提はある？"

用途:

Narration Rules (UX Contract)

敵は 冗長さ であって進捗報告ではない。起動時に何を聞くか・どう進めるかを簡潔に明示してから実行する。冗長な繰り返し・中身のない前置きだけを禁ずる。

起動時に必ず出すもの (banner + plan、3 行以内)

🚀 cursor / composer-2.5-fast / ask
これから: <質問の要点> を composer に投げて、結果を 3-5 行で要約

banner 1 行 + 計画 1-2 行。1 秒以内に出し、即 Step 2 へ。

進捗報告は出してよい

• 委譲開始の 1 行 (→ composer に問い合わせ中)
• 判断に必要な経緯を 1 行で

禁止 (= 冗長さ)

• 同じ事実の 2 回言い換え: cursor-companion の結果を後段で再説明しない
• 中身のない前置き: 「使い方を確認します」だけの行など tool call で自明な宣言
• 3 行以上の経緯振り返り: 必要なら 1 行に圧縮
• 起動シーケンス中の ★ Insight ブロック: Insight は最終要約で 1 回のみ

違反例 (冗長):

× 「cursor に質問を投げる準備をします」→ bash → 「投げます」（中身のない前置き + 言い換え）
× 「ask モードは読み取り専用なので安全です」と再説明（既知事実の繰り返し）
× ★ Insight ──── まず cursor の状態を確認します: ...

正常例 (簡潔 + 計画明示):

🚀 cursor / composer-2.5-fast / ask
これから: 設計の弱点を composer に問い、結果を 3-5 行で要約

Execution Flow

Step 0: 起動時 banner + plan

上記 Narration Rules に従い、banner + 計画 (3 行以内) を出してから Step 1 へ。

Step 1: banner 確認

Step 0 で banner + 計画 (3 行以内) は出し切っているので、ここでは banner 行が出ていることを確認する。banner は:

🚀 cursor / composer-2.5-fast / ask

以降は委譲開始の 1 行ステータス等で進捗を見せてよい。冗長な繰り返しのみ避ける。

composer-2.5-fast は scripts/model-routing.sh --host cursor --role worker --field model で解決される値の代表表記。実際の resolved model は cursor-companion 側のログに出る。

Step 2: helper root 解決 + cursor-companion 直接実行

$ARGUMENTS を質問文として渡す。--write は絶対に付けない。scripts/cursor-companion.sh を相対パスで呼ぶと consumer repo の cwd 直下に見えず exit するため、CLAUDE_PLUGIN_ROOT / HARNESS_PLUGIN_ROOT を hooks.json と同じ valid_root パターンで解決する (Issue #193 §2):

QUESTION="$ARGUMENTS"
if [ -z "$QUESTION" ]; then
  echo "ERROR: question required. Usage: cursor:ask \"<your question>\"" >&2
  exit 1
fi

bash -c '
  set -euo pipefail
  valid_root() {
    [ -n "${1:-}" ] && [ -f "$1/scripts/cursor-companion.sh" ] && { [ -f "$1/.claude-plugin/plugin.json" ] || [ -f "$1/.codex-plugin/plugin.json" ] || [ -f "$1/.cursor-plugin/plugin.json" ]; }
  }
  HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
  ROOT="$HARNESS_PLUGIN_ROOT"
  if ! valid_root "$ROOT"; then
    ROOT=""
    if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then
      probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"
      while [ "$probe" != "/" ] && ! valid_root "$probe"; do
        probe="$(cd "$probe/.." && pwd)"
      done
      valid_root "$probe" && ROOT="$probe"
    fi
  fi
  if ! valid_root "$ROOT"; then
    ROOT=""
    for c in "${CLAUDE_PROJECT_DIR:-}" "$PWD" \
             "$HOME/.claude/plugins/marketplaces/claude-code-harness-marketplace" \
             "$HOME/.claude/plugins/cache/claude-code-harness-marketplace/claude-code-harness/"*; do
      if valid_root "$c"; then ROOT="$c"; break; fi
    done
  fi
  if ! valid_root "$ROOT"; then
    echo "ERROR: claude-code-harness plugin root not found (no scripts/cursor-companion.sh)" >&2
    exit 2
  fi
  HARNESS_PLUGIN_ROOT="$ROOT"
  bash "${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh" task "$1"
' _ "$QUESTION"

これだけで cursor-agent 側は --mode ask (hard read-only stop) に locked される。--force / --yolo も付かない。

Step 3: 結果を host が 3-5 行で要約

cursor の出力をそのまま貼らない。host (Claude/Codex) が読んで 3-5 行に要約 する:

• 結論
• なぜそう言えるか (cursor が挙げた根拠の核)
• 注意点 / 追加調査が必要な点
• 次の一手 (もしあれば)

要約後、最後に literal で次の一文を出力する:

↑この結果は host が要約します。Enter キーで次へ進むか、新規 prompt で別の指示を出してください。

Trust Boundary

cursor は不透明なサブプロセスであり、Harness のガードレール (R01-R13) は内部に適用されない。read-only 委譲でも以下の前提条件を満たすこと。

必須前提

詳細は .claude/rules/cursor-cli-only.md を参照。

ask mode で省略できるもの

それでも残るリスク

• 読み取り漏洩: .cursorignore を怠ると秘密ファイルが cursor 推論に渡る
• 誤った情報の鵜呑み: cursor 出力は untrusted。Step 3 の要約で必ず host が判断軸を残す
• allowlist 過信: Cursor 公式は "Allowlists are best-effort convenience. They are not a security guarantee." と明言。allowlist に依存しない

Topology

Lead (Claude/Codex) ──[cursor-companion.sh task]──> cursor-agent (--mode ask, locked read-only)
       │
       └──[Step 3: 3-5 行要約]──> User

Worker 介在なし。Reviewer 介在なし。worker-report.v1 / review-result.v1 契約は発生しない。

Related Skills / Rules

• cursor-do — 書込タスク委譲（worktree + Lead review + cherry-pick の full containment）
• breezing --cursor — Reviewer のみ cursor に逃がす lean second-opinion レーン
• harness-review --cursor — レビューを cursor (composer-2.5-fast) に second-opinion として依頼
• .claude/rules/cursor-cli-only.md — Cursor backend governance (trust boundary, prohibited flags)

cursor:do — Single-Task Write Delegate to Cursor Composer

1 件の実装タスクを Cursor Composer (composer-2.5-fast) に専用 worktree 内で委譲し、Lead が diff をレビューしてから main へ cherry-pick する skill。breezing の team フローを起こさず、1 タスク 1 cherry-pick を最短経路で回す。

封じ込めは Cursor 側にはない (.claude/rules/cursor-cli-only.md)。専用 .git を持つ worktree + Lead diff review + cherry-pick (R01-R13 経路) の 3 点だけが実効的な境界。cursor の出力は Lead レビューまで untrusted として扱う。

Step 0 — NARRATION RULES (UX Contract)

敵は 冗長さ であって進捗報告ではない。breezing と同じ契約。起動時に banner + 実行計画を簡潔に明示してから実行する。見やすい進捗報告は歓迎、冗長な繰り返しのみ禁止。

起動時に必ず出すもの (banner + plan、合計 5 行以内)

🚀 cursor / composer-2.5-fast / feat/foo-bar / Add login form validation
これから:
1. pre-check (branch / cursor-agent) → 専用 worktree 作成
2. composer に実装委譲 (--write)
3. diff レビュー → cherry-pick → Plans.md 更新

banner 1 行 (🚀 cursor / composer-2.5-fast / <branch> / <task>) + 計画 2-4 行。1 秒以内に出し、即 Step 1 へ。

進捗報告は出してよい (見やすい範囲で)

• 各ステップの開始・完了を 1 行ステータスで (✓ worktree 作成: .claude/worktrees/cursor-do-...)
• pre-check / resolve の要点、cherry-pick した SHA
• なぜこの分岐を取るかの理由を 1 行で

禁止 (= 冗長さ)

• 同じ事実の 2 回言い換え: pre-check 結果を後段で再説明しない
• 中身のない前置き: tool call で自明な宣言だけの行
• 3 行以上の経緯振り返り: 必要なら 1 行に圧縮
• 起動シーケンス中の ★ Insight ブロック: Insight は最終 report で 1 回のみ

違反例 (冗長):

× 「composer 2.5 で実装する流れですね、まず確認します」（中身のない前置き）
× 「Cursor を呼ぶ前に branch を見ます」 → bash → 「branch を確認しました」（言い換え）
× ★ Insight ──── Cursor の強みは…

正常例 (簡潔 + 計画明示):

🚀 cursor / composer-2.5-fast / feat/foo-bar / Add login form validation
これから: worktree 作成 → composer に実装委譲 → diff レビュー → cherry-pick

Step 1 — banner + plan を出し切る (1 秒以内)

引数 $ARGUMENTS をタスク説明として受ける。引数が空なら以下のマーカーを出力してユーザーに 1 行タスクを要求し、入力後に Step 2 へ進む:

CURSOR_DO_AWAITING_TASK: provide a one-line task description as $ARGUMENTS

引数があれば、即 1 行 echo:

🚀 cursor / composer-2.5-fast / <current-branch> / <task-first-60-chars>

<current-branch> は Step 2 で取得する値だが、Step 1 では未取得のため … でも可。Step 2 直後に確定値を 1 行で再出力する。Step 0 の banner + 実行計画 (5 行以内) はここで出し切り、以降は各ステップの 1 行ステータスで進捗を見せる。冗長な繰り返しのみ避ける。

Step 2 — 並列 pre-check (1 bash)

1 つの bash 呼び出しで以下を並列に取り、結果だけを 1 ブロックで受ける。個別の説明は出さない。

bash -c '
  set +e
  echo "==BRANCH=="; git branch --show-current
  echo "==VERSION=="; cat VERSION 2>/dev/null
  echo "==PLANS_TAIL=="; tail -n 12 Plans.md 2>/dev/null
  echo "==CURSOR_AGENT=="
  CURSOR_AGENT_BIN="${CURSOR_AGENT_BIN:-}"
  if [ -z "$CURSOR_AGENT_BIN" ]; then
    if command -v cursor-agent >/dev/null 2>&1; then
      CURSOR_AGENT_BIN="$(command -v cursor-agent)"
    elif [ -x "$HOME/.local/bin/cursor-agent" ]; then
      CURSOR_AGENT_BIN="$HOME/.local/bin/cursor-agent"
    fi
  fi
  if [ -z "$CURSOR_AGENT_BIN" ]; then
    echo "NOT_INSTALLED"
  else
    "$CURSOR_AGENT_BIN" --version 2>/dev/null || echo "NOT_INSTALLED"
  fi
'

判定:

• CURSOR_AGENT=NOT_INSTALLED → ERROR: cursor-agent not found (exit 3 expected from companion). Install via setup-cursor.sh. を出し終了。
• BRANCH が main / master → WARN: on protected branch — cherry-pick target is HEAD of this branch. Confirm intent or switch. を出し継続。

Step 3 — plugin root + backend + model resolve (1 bash)

HARNESS_PLUGIN_ROOT / CLAUDE_PLUGIN_ROOT が未設定だと :-. fallback が consumer repo の cwd に解決し、scripts/cursor-companion.sh が見えず起動不能になる (Issue #193 §2)。hooks.json と同じ valid_root パターンで堅牢に解決する。

bash -c '
  set -euo pipefail
  valid_root() {
    [ -n "${1:-}" ] && [ -f "$1/scripts/cursor-companion.sh" ] && { [ -f "$1/.claude-plugin/plugin.json" ] || [ -f "$1/.codex-plugin/plugin.json" ] || [ -f "$1/.cursor-plugin/plugin.json" ]; }
  }
  HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
  ROOT="$HARNESS_PLUGIN_ROOT"
  if ! valid_root "$ROOT"; then
    ROOT=""
    if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then
      probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"
      while [ "$probe" != "/" ] && ! valid_root "$probe"; do
        probe="$(cd "$probe/.." && pwd)"
      done
      valid_root "$probe" && ROOT="$probe"
    fi
  fi
  if ! valid_root "$ROOT"; then
    ROOT=""
    for c in "${CLAUDE_PROJECT_DIR:-}" "$PWD" \
             "$HOME/.claude/plugins/marketplaces/claude-code-harness-marketplace" \
             "$HOME/.claude/plugins/cache/claude-code-harness-marketplace/claude-code-harness/"*; do
      if valid_root "$c"; then ROOT="$c"; break; fi
    done
  fi
  if ! valid_root "$ROOT"; then
    echo "ERROR: claude-code-harness plugin root not found (no scripts/cursor-companion.sh)" >&2
    exit 2
  fi
  HARNESS_PLUGIN_ROOT="$ROOT"
  BACKEND=$(bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --backend cursor --role worker)
  MODEL=$(bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model)
  echo "PLUGIN_ROOT=${HARNESS_PLUGIN_ROOT}"
  echo "BACKEND=$BACKEND"
  echo "MODEL=$MODEL"
'

返却値: PLUGIN_ROOT (Step 5 で使う) / BACKEND (必ず cursor) / MODEL (通常 composer-2.5-fast)。BACKEND または MODEL が空なら ERROR: backend/model resolution failed を 1 行で出して終了。PLUGIN_ROOT 解決失敗は上記スクリプトが exit 2 で報告する。

Step 4 — 専用 worktree 作成

衝突しない id を作って worktree を切る。main tree や $HOME を指してはならない (companion 側 guard で exit 2 になる)。WT_DIR は絶対パスで作る (Step 5 の --workspace は companion の is not a directory ガードで相対パスを exit 2 にすることがあるため、Issue #193 §4)。

bash -c '
  set -euo pipefail
  REPO_ROOT="$(git rev-parse --show-toplevel)"
  cd "$REPO_ROOT"
  ID="$(date +%Y%m%d-%H%M%S)-$$"
  WT_DIR="$REPO_ROOT/.claude/worktrees/cursor-do-${ID}"
  BASE_REF="$(git rev-parse HEAD)"
  BASE_BRANCH="$(git branch --show-current)"
  WT_BRANCH="cursor-do/${ID}"
  mkdir -p "$REPO_ROOT/.claude/worktrees"
  git worktree add -b "${WT_BRANCH}" "${WT_DIR}" "${BASE_REF}"
  echo "REPO_ROOT=${REPO_ROOT}"
  echo "WT_DIR=${WT_DIR}"
  echo "WT_BRANCH=${WT_BRANCH}"
  echo "BASE_REF=${BASE_REF}"
  echo "BASE_BRANCH=${BASE_BRANCH}"
'

返却された WT_DIR / WT_BRANCH / BASE_REF / BASE_BRANCH を以降の Step で使う。失敗時 (branch 名衝突等) は ID を作り直して 1 回だけ retry。2 回連続失敗で ERROR: worktree creation failed を出し終了。

Step 5 — cursor-companion.sh task --write で委譲

Lead が直接 companion を呼ぶ (.claude/rules/cursor-cli-only.md Topology 節 — 非 claude backend では Worker 介在なし)。プロンプトは引数の task そのまま + 必要な追補のみ。冗長な前置きは付けない。

bash -c '
  set -euo pipefail
  valid_root() {
    [ -n "${1:-}" ] && [ -f "$1/scripts/cursor-companion.sh" ] && { [ -f "$1/.claude-plugin/plugin.json" ] || [ -f "$1/.codex-plugin/plugin.json" ] || [ -f "$1/.cursor-plugin/plugin.json" ]; }
  }
  HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
  ROOT="${PLUGIN_ROOT:-$HARNESS_PLUGIN_ROOT}"
  if ! valid_root "$ROOT"; then
    ROOT=""
    if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then
      probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"
      while [ "$probe" != "/" ] && ! valid_root "$probe"; do
        probe="$(cd "$probe/.." && pwd)"
      done
      valid_root "$probe" && ROOT="$probe"
    fi
  fi
  if ! valid_root "$ROOT"; then
    ROOT=""
    for c in "${CLAUDE_PROJECT_DIR:-}" "$PWD" \
             "$HOME/.claude/plugins/marketplaces/claude-code-harness-marketplace" \
             "$HOME/.claude/plugins/cache/claude-code-harness-marketplace/claude-code-harness/"*; do
      if valid_root "$c"; then ROOT="$c"; break; fi
    done
  fi
  if ! valid_root "$ROOT"; then
    echo "ERROR: claude-code-harness plugin root not found (no scripts/cursor-companion.sh)" >&2
    exit 2
  fi
  HARNESS_PLUGIN_ROOT="$ROOT"
  PROMPT="<task-description>

Constraints:
- Modify only files relevant to the task.
- Keep existing tests green. Add tests when the task is verifiable.
- Match existing code style and naming.
- Create exactly one git commit if your environment supports it; otherwise leave one dirty changeset for Lead auto-commit.
- Do not touch .claude-plugin/settings*, .claude/settings*, .eslintrc*, biome.json, tsconfig*.json."
  bash "${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh" task \
    --write \
    --workspace "${WT_DIR}" \
    "${PROMPT}"
' 2>&1

判定:

• exit 0 + result text → Step 6 へ
• exit 1 (result-error) → companion stderr を 1 行要約して ERROR: cursor returned is_error/empty result を出し終了。worktree は Step 8 のクリーンアップで削除
• exit 2 (bad-guard) → 設定不備。原因 (workspace 指定誤り等) を 1 行で示し終了
• exit 3 (not-found) → Step 2 で検出済みのはずだが、再度遭遇したら同様に終了

Step 6 — Lead diff review

worktree 内で Composer が作成した変更を読み、目視レビュー + contract grep の二段ゲートを通す (harness-work 「Lead の cherry-pick 前ゲート」と同じ契約)。

注意 (Issue #193 §1): Cursor Composer は --write でファイル編集を行うが commit は作らないことがある。worktree が dirty なまま放置すると Step 7 の cherry-pick 対象から漏れ、ユーザー視点で「完了したのに main に何も入らない」状態になる。本 Step 冒頭で dirty なら、既存 commit がある場合は amend、commit がない場合は Lead 側で 1 commit にまとめる。

bash -c '
  set -euo pipefail
  cd "${WT_DIR}"
  # Composer は dirty changeset を返すことがあるため、既存 commit に fold する
  if [ -n "$(git status --porcelain)" ]; then
    git add -A
    if [ "$(git rev-list --count "${BASE_REF}..HEAD")" -gt 0 ]; then
      git -c user.name="cursor-composer" -c user.email="cursor-composer@local" \
        commit --amend --no-edit --no-verify
      echo "==AUTO_AMENDED=="
    else
      git -c user.name="cursor-composer" -c user.email="cursor-composer@local" \
        commit --no-verify -m "cursor: ${TASK_SUMMARY:-cursor-do delegated change}"
      echo "==AUTO_COMMITTED=="
    fi
    git log -1 --oneline
  fi
  echo "==LOG=="
  git log --oneline "${BASE_REF}..HEAD"
  echo "==STAT=="
  git diff --stat "${BASE_REF}..HEAD"
  echo "==DIFF=="
  git diff "${BASE_REF}..HEAD"
'

TASK_SUMMARY は引数 task の先頭 60 文字以内に圧縮した文字列を Lead が事前に export しておく (例: TASK_SUMMARY="Add login form validation")。未設定なら fallback メッセージ cursor-do delegated change を使う。--no-verify を付けるのは worktree 内の編集を「Lead レビュー前の中間 commit」として扱うため (cherry-pick 後の main commit で R01-R13 と pre-commit hook を通す)。

Lead は diff 全文を Read し、以下を確認する:

• 変更が依頼タスクの範囲内か (関係ないファイルを触っていないか)
• protected path (.claude-plugin/settings*, .eslintrc*, etc.) を変更していないか
• secret / .env / 認証情報を含まないか
• 公開 support tier 表記を破壊していないか。contract gates は必ず candidate worktree (WT_DIR) 内で実行する:

  [ ! -f "${WT_DIR}/tests/test-support-claim-wording.sh" ] || (cd "${WT_DIR}" && bash tests/test-support-claim-wording.sh)
  [ ! -f "${WT_DIR}/scripts/ci/check-consistency.sh" ] || (cd "${WT_DIR}" && bash scripts/ci/check-consistency.sh)
  [ ! -f "${WT_DIR}/tests/validate-plugin.sh" ] || (cd "${WT_DIR}" && bash tests/validate-plugin.sh)
  

判定:

• 問題なし → Step 7 へ
• 範囲外変更あり → 該当 commit を git reset で巻き戻すか、Cursor に再委譲 (Step 5 を 1 回だけ retry)。2 回失敗で REQUEST_CHANGES: <理由> を出し、worktree を残したまま終了
• protected path / secret 検出 → 即 abort。ABORT: protected path violation を出し worktree 削除

Step 7 — cherry-pick + Plans.md cc:done 更新

worktree から main tree に cherry-pick する。Cursor prompt は exactly one commit 契約だが、Composer は dirty changeset を返すことがあるため Step 6 で commit/amend する。複数 commit が残った場合は main tree を触る前に停止する。 さらに cherry-pick 前に Plans.md の staged / unstaged 差分がないことを確認する。理由: 既存差分がある状態で後続の git add Plans.md && git commit --amend を行うと、task と無関係な plan/status 編集を Cursor の code commit に巻き込むため。 SHA 直接指定 (branch 名経由ではない) で reviewer state drift を避ける (MEMORY: reviewer_state_drift)。

bash -c '
  set -euo pipefail
  COMMIT_COUNT="$(cd "${WT_DIR}" && git rev-list --count "${BASE_REF}..HEAD")"
  if [ "${COMMIT_COUNT}" -eq 0 ]; then
    echo "ERROR: no commits to cherry-pick"
    exit 1
  fi
  if [ "${COMMIT_COUNT}" -ne 1 ]; then
    echo "ERROR: cursor returned ${COMMIT_COUNT} commits; expected exactly one. Keep worktree for manual review: ${WT_DIR}"
    exit 1
  fi
  if ! git diff --quiet -- Plans.md || ! git diff --cached --quiet -- Plans.md; then
    echo "ERROR: Plans.md has pre-existing local edits; refusing to cherry-pick before the cursor:do marker amend"
    exit 1
  fi
  SHA="$(cd "${WT_DIR}" && git rev-parse HEAD)"
  git cherry-pick "${SHA}"
  echo "==CHERRY_PICKED=="
  git log --oneline -n 1
'

cherry-pick で conflict が出たら git cherry-pick --abort し、CHERRY_PICK_CONFLICT: <files> を 1 行で示して終了 (worktree は残す、ユーザー判断)。

cherry-pick 後、Plans.md に対応行があれば該当タスクのマーカーを更新する。 上記の clean precondition を通過しているため、ここで発生する Plans.md 差分は marker-only diff として扱う:

| <task> | ... | cc:done [<merged-sha>] |

該当行の特定: 引数 task 文字列の先頭 40 文字で grep し、ヒットした最初の cc:TODO / cc:WIP / cc:todo 行を cc:done [<sha>] に置換する。ヒットなしなら更新スキップ (Plans.md 外のタスクとして扱う)。

マーカーを更新した場合、その編集は cherry-pick commit に含める。未コミットの Plans.md を残して cleanup / 完了報告へ進んではならない。 以下の amend block は、上記 precondition 通過後に実行した marker-only diff だけを対象にする:

bash -c '
  set -euo pipefail
  if git diff --quiet -- Plans.md; then
    echo "PLANS_UPDATED=0"
  else
    git add Plans.md
    git commit --amend --no-edit
    echo "PLANS_UPDATED=1"
    echo "MERGED_SHA=$(git rev-parse HEAD)"
  fi
'

Step 8 — worktree cleanup + 完了報告 (1 ブロック)

cherry-pick 成功後、worktree を delete する。失敗 path では呼ばれない（worktree を残してユーザー判断）。

bash -c '
  set -euo pipefail
  git worktree remove --force "${WT_DIR}"
  git branch -D "${WT_BRANCH}" 2>/dev/null || true
  echo "==CLEANUP=="
  git worktree list | grep -v "cursor-do-" || true
'

完了報告は 1 ブロック で出す。中間ナレーションなし:

cursor:do completed
   task: <task-first-60-chars>
   commits: <count>
   base: <BASE_REF> → cherry-picked into <BASE_BRANCH>
   plans: <updated|skipped (no match)>
   files: <changed-file-count> changed, +<inserts> -<deletes>

Full Containment (write mode 必須)

Prohibited

• --force / --yolo を companion に渡す（Cursor 公式 "Never use"）
• cursor 出力を Lead レビュー前に main へ直接 commit する
• protected path (.claude-plugin/settings*, .eslintrc*, tsconfig*.json, etc.) を Step 5 の prompt で許可する
• $HOME / / / main tree を --workspace に指定する
• Plans.md の cc:* マーカーを task と無関係に書き換える

Related Skills / Rules

• cursor:ask — 読取専用の質問・調査・敵対的視点 (worktree 不要)
• breezing --cursor — 複数タスクを team フローで cursor 委譲する場合
• harness-work — claude backend の default フロー (Worker agent 経由)
• .claude/rules/cursor-cli-only.md — Cursor backend governance + Topology

cursor:rescue - Cursor Backend Recovery

Cursor backend の failure path を短く切り分ける skill。変更は最小限にし、破壊的操作はしない。

Quick Reference

cursor:rescue "breezing fell back to claude"
cursor:rescue "cursor-agent not found"

Diagnosis Order

Run one compact diagnostic block:

set +e
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
if [ -z "$HARNESS_PLUGIN_ROOT" ]; then
  echo "ERROR: HARNESS_PLUGIN_ROOT is not set and could not be derived from CLAUDE_PLUGIN_ROOT or CLAUDE_SKILL_DIR" >&2
  exit 2
fi
echo "==RESOLVED_BACKEND=="
bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role worker
echo "==USER_OR_PROJECT_DEFAULT=="
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show
echo "==CURSOR_MODEL=="
bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model
echo "==CURSOR_AGENT=="
CURSOR_AGENT_BIN="${CURSOR_AGENT_BIN:-}"
if [ -z "$CURSOR_AGENT_BIN" ]; then
  if command -v cursor-agent >/dev/null 2>&1; then
    CURSOR_AGENT_BIN="$(command -v cursor-agent)"
  elif [ -x "$HOME/.local/bin/cursor-agent" ]; then
    CURSOR_AGENT_BIN="$HOME/.local/bin/cursor-agent"
  fi
fi
if [ -z "$CURSOR_AGENT_BIN" ]; then
  echo "NOT_INSTALLED: cursor-agent not found in PATH or $HOME/.local/bin"
else
  "$CURSOR_AGENT_BIN" --version
fi
echo "==CURSOR_PACKAGE_CHECK=="
bash "${HARNESS_PLUGIN_ROOT}/scripts/setup-cursor.sh" --check

Common Fixes

Output

Return:

• root cause candidate
• exact failing command
• minimal fix command
• whether retrying the original workflow is safe

cursor:review - Advisory Cursor Review

Cursor Composer (composer-2.5-fast) を read-only second opinion として使う review skill。primary verdict は host brain (Opus / Claude role) が出す。

Quick Reference

cursor:review --base origin/main
cursor:review "Phase 88.5 command namespace diff"

Rules

• Cursor review is advisory. The final verdict must come from the host reviewer.

• Do not pass --write to cursor-companion.sh.

• Use resolver/model routing, not direct env checks:

  bash scripts/resolve-impl-backend.sh --backend cursor --role reviewer
  bash scripts/model-routing.sh --host cursor --role worker --field model
  

• Prefer the existing harness-review contract when a full review is requested. This command exists for users who explicitly ask for the Cursor lane.

Flow

1. Resolve the Harness helper 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
   if [ -z "$HARNESS_PLUGIN_ROOT" ]; then
     echo "ERROR: HARNESS_PLUGIN_ROOT is not set and could not be derived from CLAUDE_PLUGIN_ROOT or CLAUDE_SKILL_DIR" >&2
     exit 2
   fi
   

2. Determine review scope:

   BASE_REF="${TASK_BASE_REF:-origin/main}"
   REVIEW_SCOPE="${ARGUMENTS:-}"
   if [ -n "${REVIEW_SCOPE}" ]; then
     set -- ${REVIEW_SCOPE}
     while [ "$#" -gt 0 ]; do
       case "$1" in
         --base)
           BASE_REF="${2:?--base requires a ref}"
           shift 2
           ;;
         --base=*)
           BASE_REF="${1#--base=}"
           shift
           ;;
         *)
           shift
           ;;
       esac
     done
   fi
   DIFF_STAT="$(git diff --stat "${BASE_REF}..HEAD")"
   DIFF_TEXT="$(git diff "${BASE_REF}..HEAD")"
   

3. Ask Cursor in read-only mode:

   PROMPT="$(cat <<EOF
   

Review this diff as an advisory second opinion. Base ref: ${BASE_REF} Requested scope: ${ARGUMENTS:-full diff}

Focus on bugs, regressions, missing tests, and unsafe assumptions. Do not propose broad refactors.

Diff stat: ${DIFF_STAT}

Diff: ${DIFF_TEXT} EOF )" bash "${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh" task "${PROMPT}"

4. Host reads Cursor's output and performs the primary review:

- Findings first, ordered by severity.
- Mark Cursor-originated points as advisory when used.
- `APPROVE` / `REQUEST_CHANGES` must be the host decision, not a copied Cursor verdict.

## Output

Use the standard review shape:

- findings
- open questions
- validation run
- final host verdict

cursor:setup - Cursor Backend Setup

Cursor backend の setup / verification 用 skill。配布 plugin の fallback は claude のままにし、現在の repo / user 環境だけ cursor default にする時に使う。

Quick Reference

cursor:setup --check
cursor:setup --user-default
cursor:setup --project-default
cursor:setup --unset

Rules

• Do not change distribution defaults or plugin manifests to make Cursor the shipped fallback.
• Use scripts/resolve-impl-backend.sh / scripts/set-impl-backend.sh; do not infer from HARNESS_IMPL_BACKEND alone.
• Treat ~/.cursor/permissions.json, .cursorignore, and Claude sandbox allowlists as manual/user-owned setup surfaces unless the user explicitly asks to edit a local file.

Flow

First resolve the Harness helper root. Keep the current working directory as the target project so project-scoped env.local writes still land in the user's repo:

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
if [ -z "$HARNESS_PLUGIN_ROOT" ]; then
  echo "ERROR: HARNESS_PLUGIN_ROOT is not set and could not be derived from CLAUDE_PLUGIN_ROOT or CLAUDE_SKILL_DIR" >&2
  exit 2
fi

1. For --check, run:

   bash "${HARNESS_PLUGIN_ROOT}/scripts/setup-cursor.sh" --check
   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show
   bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role worker
   CURSOR_AGENT_BIN="${CURSOR_AGENT_BIN:-}"
   if [ -z "$CURSOR_AGENT_BIN" ]; then
     if command -v cursor-agent >/dev/null 2>&1; then
       CURSOR_AGENT_BIN="$(command -v cursor-agent)"
     elif [ -x "$HOME/.local/bin/cursor-agent" ]; then
       CURSOR_AGENT_BIN="$HOME/.local/bin/cursor-agent"
     fi
   fi
   if [ -z "$CURSOR_AGENT_BIN" ]; then
     echo "ERROR: cursor-agent not found in PATH or $HOME/.local/bin" >&2
     exit 3
   fi
   "$CURSOR_AGENT_BIN" --version
   

2. For --user-default, run:

   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --user cursor
   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show
   

3. For --project-default, run:

   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" cursor
   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show
   

4. For --unset, ask whether the target is user or project scope if not clear from the request, then run exactly one matching unset command:

   Project scope:

   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --unset
   

   User scope:

   bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --unset --user
   

Output

Report three facts only:

• resolved backend (claude / codex / cursor)
• Cursor package readiness (setup-cursor.sh --check)
• next manual step if Cursor is not ready

Deploy Skills

デプロイとモニタリングの設定を担当するスキル群です。

機能詳細

実行手順

1. ユーザーのリクエストを分類
2. 上記の「機能詳細」から適切な参照ファイルを読む
3. その内容に従って設定

Generate Slide Skill

プロジェクトの内容を紹介・説明する1枚スライド画像を、Nano Banana Pro（Gemini 3 Pro Image Preview）API で自動生成します。

起動契約

このスキルは user-invocable: false かつ disable-model-invocation: true です。 通常のユーザー発話（例: 「スライド作って」）から Claude が自動選択する前提ではありません。

• 明示的な /generate-slide コマンド、または親メディアワークフローから内部的に起動される時だけ使います。
• allowed-tools は Claude Code 用です。Claude ではユーザー確認に AskUserQuestion を使えます。
• Codex mirror では同等の確認は request_user_input 相当の計画モード入力に読み替えます。通常実行でそのツールがない場合は、既定値を提示して停止せず進め、重要な未確定事項だけユーザーへ確認します。
• disable-model-invocation: true は「説明文だけを見てモデルが勝手に起動しない」という意味です。slash や親 workflow から明示起動された場合は本文手順に従います。

概要

3パターン x 各2枚候補 = 計6枚生成 → パターンごとに品質チェック → NG ならリトライ → 各パターンの最良1枚、計3枚を出力。

前提条件

• GOOGLE_AI_API_KEY 環境変数が設定済み
• Google AI Studio で Nano Banana Pro（Gemini 3 Pro Image Preview）が有効化済み

機能詳細

実行フロー

/generate-slide
    |
    +--[Step 1] 情報収集
    |   +-- ユーザー指定テキスト or コードベース自動分析（README, package.json 等）
    |   +-- プロジェクト名・概要・主要機能・技術スタックを抽出
    |
    +--[Step 2] 仕様確認（AskUserQuestion）
    |   +-- サイズ・アスペクト比（デフォルト: 16:9 / 2K）
    |   +-- トーン（テック、カジュアル、コーポレート等）
    |   +-- 強調したいポイント（曖昧な場合のみ質問）
    |
    +--[Step 3] 3パターン x 2枚生成（Nano Banana Pro API x 6回）
    |   +-- Pattern A: Minimalist（2枚）
    |   +-- Pattern B: Infographic（2枚）
    |   +-- Pattern C: Hero Visual（2枚）
    |
    +--[Step 4] パターンごとに品質チェック
    |   +-- 各パターンの2枚を Claude が Read で読み込み
    |   +-- 5段階スコアリング → 高い方を採用候補
    |   +-- 両方スコア2以下 → プロンプト改善してリトライ（最大3回）
    |   +-- リトライ上限到達 → ユーザーに報告、続行 or スキップを選択
    |
    +--[Step 5] 最良3枚を出力
        +-- 各パターンのベスト1枚を selected/ にコピー
        +-- 結果一覧（パス + スコア + 評価コメント）をユーザーに提示

デザインパターン

出力先

out/slides/
+-- minimalist_1.png       # Pattern A 候補1
+-- minimalist_2.png       # Pattern A 候補2
+-- infographic_1.png      # Pattern B 候補1
+-- infographic_2.png      # Pattern B 候補2
+-- hero_1.png             # Pattern C 候補1
+-- hero_2.png             # Pattern C 候補2
+-- selected/
|   +-- minimalist.png     # Pattern A 最良
|   +-- infographic.png    # Pattern B 最良
|   +-- hero.png           # Pattern C 最良
+-- quality-report.md      # 品質チェック結果レポート

実行手順

Step 1: 情報収集

プロジェクト情報を以下の優先順位で収集:

1. ユーザー指定テキスト: 引数でプロジェクト説明が渡された場合はそれを使用
2. コードベース自動分析: 引数がない場合、以下を自動分析
   • README.md — プロジェクト概要
   • package.json / Cargo.toml / pyproject.toml — プロジェクト名・説明・依存関係
   • CLAUDE.md — プロジェクト構成・目的
   • Plans.md — 進行中のタスク（存在する場合）

抽出する情報:

Step 2: 仕様確認

AskUserQuestion で以下を確認（デフォルト値があるため、曖昧な場合のみ質問）:

質問1: スライドのサイズ・アスペクト比は？
  - 16:9 / 2K（推奨）
  - 4:3 / 2K
  - 1:1 / 2K
  - カスタム

質問2: トーンは？
  - テック（ダークテーマ、コード感）
  - カジュアル（明るい、フレンドリー）
  - コーポレート（フォーマル、信頼感）
  - クリエイティブ（大胆、アート寄り）

Step 3: 画像生成

slide-generator.md の手順に従い、3パターン x 2枚 = 6枚を生成。

各パターンの生成は独立しているため、可能な限り並列で curl を実行:

# 並列実行例（3パターン x 2枚）
for pattern in minimalist infographic hero; do
  for i in 1 2; do
    # slide-generator.md の curl パターンを実行
    # → out/slides/${pattern}_${i}.png に保存
  done
done

Step 4: 品質チェック

slide-quality-check.md の基準に従い、各パターンの2枚を評価:

1. 各画像を Read で読み込み
2. 5段階スコアリング（情報伝達力、レイアウト、テキスト可読性、プロフェッショナル感、ブランド整合性）
3. パターン内でスコアが高い方を採用候補
4. 両方スコア2以下 → プロンプト改善して再生成（最大3回）

Step 5: 結果出力

# 最良画像を selected/ にコピー
mkdir -p out/slides/selected
cp out/slides/minimalist_best.png out/slides/selected/minimalist.png
cp out/slides/infographic_best.png out/slides/selected/infographic.png
cp out/slides/hero_best.png out/slides/selected/hero.png

品質レポート（out/slides/quality-report.md）を生成:

# Slide Quality Report

## 生成情報
- プロジェクト: {project_name}
- 生成日時: {datetime}
- アスペクト比: {aspect_ratio}
- トーン: {tone}

## 結果サマリー

| パターン | 候補1 | 候補2 | 採用 | スコア |
|---------|-------|-------|------|--------|
| Minimalist | 3/5 | 4/5 | 候補2 | 4/5 |
| Infographic | 4/5 | 3/5 | 候補1 | 4/5 |
| Hero Visual | 5/5 | 4/5 | 候補1 | 5/5 |

## 詳細評価
...

エラーハンドリング

GOOGLE_AI_API_KEY 未設定

GOOGLE_AI_API_KEY が設定されていません。

設定方法:
1. Google AI Studio でAPIキーを取得: https://ai.google.dev/aistudio
2. export GOOGLE_AI_API_KEY="your-api-key"

全パターンでリトライ上限到達

AskUserQuestion で選択肢を提示:

パターン {pattern} の画像が3回のリトライでも基準を満たしませんでした。

選択肢:
1. 最も高スコアの画像を採用して続行
2. このパターンをスキップ
3. プロンプトを手動で指定して再生成

関連スキル

• generate-video — プロダクトデモ動画生成（画像生成エンジンを共有）
• notebookLM — ドキュメント・スライド生成（別アプローチ）

Generate Video Skill

プロダクト説明動画の自動生成を担当するスキル群です。

起動契約

このスキルは user-invocable: false かつ disable-model-invocation: true です。 通常のユーザー発話（例: 「動画を作って」）で Claude が自動選択する前提にはしません。

• 明示的な /generate-video コマンド、または親メディアワークフローから内部的に起動される時だけ使います。
• allowed-tools は Claude Code 用です。Claude ではユーザー確認に AskUserQuestion を使えます。
• Codex mirror では同等の確認は request_user_input 相当の計画モード入力に読み替えます。通常実行でそのツールがない場合は、既定値を提示して停止せず進め、重要な未確定事項だけユーザーへ確認します。
• disable-model-invocation: true は「説明文だけを見てモデルが勝手に起動しない」という意味です。slash や親 workflow から明示起動された場合は本文手順に従います。

概要

/generate-video コマンドの内部で使用されるスキルです。 コードベース分析 → シナリオ提案 → 並列生成のフローを実行します。

機能詳細

Prerequisites

• Remotion がセットアップ済み（/remotion-setup）
• Node.js 18+
• （オプション）GOOGLE_AI_API_KEY - AI画像生成用

/generate-video フロー

/generate-video
    │
    ├─[Step 1] 分析（analyzer.md）
    │   ├─ フレームワーク検出
    │   ├─ 主要機能検出
    │   ├─ UIコンポーネント検出
    │   └─ プロジェクト資産解析（Plans.md, CHANGELOG等）
    │
    ├─[Step 2] シナリオ提案（planner.md）
    │   ├─ 動画タイプ自動判定
    │   ├─ シーン構成提案
    │   └─ ユーザー確認
    │
    ├─[Step 2.5] 素材生成（image-generator.md）← NEW
    │   ├─ 素材必要判定（イントロ、CTA等）
    │   ├─ Nano Banana Pro で2枚生成
    │   ├─ Claude が品質判定（image-quality-check.md）
    │   └─ OK → 採用 / NG → 再生成（最大3回）
    │
    └─[Step 3] 並列生成（generator.md）
        ├─ シーン並列生成（Task tool）
        ├─ 統合 + トランジション
        └─ 最終レンダリング

実行手順

1. ユーザーが /generate-video を実行
2. Remotion セットアップ確認
3. analyzer.md でコードベース分析
4. planner.md でシナリオ提案 + ユーザー確認
5. generator.md で並列生成
6. 完了報告

動画タイプ（ファネル別）

詳細: references/best-practices.md

シーンテンプレート

90秒ティザー（LP/広告向け）

3分Introデモ（検討向け）

共通シーン

詳細テンプレート: ${CLAUDE_SKILL_DIR}/references/best-practices.md

音声同期ルール（重要）

ナレーション付き動画では以下を厳守:

事前確認: ffprobe で音声長さを確認してからシーン設計

詳細: ${CLAUDE_SKILL_DIR}/references/generator.md

BGM サポート

詳細: ${CLAUDE_SKILL_DIR}/references/generator.md

字幕サポート

詳細: ${CLAUDE_SKILL_DIR}/references/generator.md

視覚効果ライブラリ

インパクトのある動画向けエフェクト集:

詳細: references/visual-effects.md

Notes

• Remotion未セットアップの場合は /remotion-setup を案内
• 並列生成数はシーン数に応じて自動調整（max 5）
• 生成された動画は out/ ディレクトリに出力
• AI生成画像は out/assets/generated/ に保存
• GOOGLE_AI_API_KEY 未設定時は画像生成をスキップ（既存素材 or プレースホルダー使用）

Gogcli Ops

Overview

Standardize gogcli usage: verify auth, resolve IDs from URLs, default to read-only checks, then run the minimum command needed.

Quick start

• Confirm gogcli is available: gog --version
• List accounts and pick one explicitly if more than one: gog auth list
• Resolve URL to ID with python3 scripts/gog_parse_url.py "<url-or-id>"
• Run a read-only metadata command first (Drive/Sheets/Docs/Slides)

Workflow decision tree

1. Identify target type: sheet | doc | slide | file | folder | id | unknown via scripts/gog_parse_url.py.
2. Choose the smallest read-only command to confirm access:
   • Sheets: gog sheets metadata <spreadsheetId>
   • Docs: gog docs info <docId>
   • Slides: gog slides info <presentationId>
   • Drive file/folder: gog drive get <fileId> or gog drive permissions <fileId>
3. Only proceed to write operations (update/append/move/share/delete) after explicit user confirmation.

Core tasks

Auth and account selection

• Show stored accounts: gog auth list
• Show auth configuration: gog auth status
• Add/authorize account: gog auth add <email>
• Always use --account <email> when multiple accounts exist.

Resolve IDs from URLs

• Parse a URL or ID:
  • python3 scripts/gog_parse_url.py "<url-or-id>"
• If output type is unknown, ask for a direct ID or a different URL.

Drive (files/folders)

• List root or a folder: gog drive ls
• Search by query: gog drive search "<query>"
• Get metadata: gog drive get <fileId>
• Download/export: gog drive download <fileId>
• Permissions check: gog drive permissions <fileId>

Sheets

• Metadata: gog sheets metadata <spreadsheetId>
• Read values: gog sheets get <spreadsheetId> <range>
• Export: gog sheets export <spreadsheetId>
• Write operations (update/append/clear/format): require explicit confirmation and exact range.

Docs

• Metadata: gog docs info <docId>
• Read text: gog docs cat <docId>
• Export: gog docs export <docId>

Slides

• Metadata: gog slides info <presentationId>
• Export: gog slides export <presentationId>

Output modes

• Use --plain for stable TSV output.
• Use --json when a caller wants structured output.
• Use --no-input in non-interactive flows to avoid hanging.

Error handling

• 403/404: verify account (gog auth list), check permissions (gog drive permissions <fileId>), and confirm the ID.
• If access fails, request the user to share the file with the selected account or provide the correct account.

Resources

• See ${CLAUDE_SKILL_DIR}/references/gogcli-cheatsheet.md for a compact command list.
• Use scripts/gog_parse_url.py to normalize URLs into IDs before running commands.

harness-accept

非エンジニアの発注者・プロデューサー職向けに、実装完了タスクの受け入れ判断 (ship / wait / reject) を HTML 1 枚 で提示するスキル。 発注者の認知負荷ピーク (3) 受け入れ判断の段階で使う。

Phase 65.1.x (harness-plan-brief) の対構造として動作し、Plan Brief で承認した acceptance_criteria を read 側で取り戻して評価する。

Quick Reference

• 「Acceptance Demo を作って」 → このスキル
• 「受け入れ判断したい」 → このスキル
• 「ship/wait/reject 判定」 → このスキル

責任境界

入力

引数 [task-description] にユーザーの request を渡す (Plan Brief 時と同じ文を使う)。 引数なしの場合は対話形式で受け取る。

出力

Schema: acceptance-context.v1

{
  "schema": "acceptance-context.v1",
  "user_request": "string",
  "user_request_hash": "sha256 hex (Plan Brief 側の personal-preference.v1 と join)",
  "demo_artifacts": [
    { "kind": "video|screenshot|text", "path": "string" }
  ],
  "verified_criteria": [
    { "name": "string", "passed": true, "evidence": "string" }
  ],
  "tdd_verified": "yes|no|not-required|skip:<reason>",
  "unverified_caveats": ["string"],
  "past_issue_patterns": [
    { "pattern_id": "P5", "title": "string", "verified_in_current_task": true }
  ],
  "recommendation": "ship|wait|reject",
  "recommendation_evidence": ["string"],
  "project": "string",
  "generated_at": "ISO8601"
}

完全 schema は schemas/acceptance-context.v1.schema.json を参照。

Recommendation 算出ロジック

verified_count    = count of verified_criteria where passed=true
total_criteria    = count of verified_criteria
ratio             = verified_count / total_criteria  (total=0 のときは 0)

  ratio >= 0.8 → "ship"
  ratio >= 0.5 → "wait"
  ratio <  0.5 → "reject"
  total = 0    → "reject" (criteria 0 件は判定不能、安全側 reject)

評価根拠は recommendation_evidence に literal な数値で残す。 例: "verified 4 件 / 全 5 件 (80%) → ship 閾値以上"

Execution Flow

スキル起動時、Claude は以下の手順で動作する。

Step 1: project name と user_request_hash を解決

PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)")"
USER_REQUEST_HASH="$(printf '%s' "$USER_REQUEST" | sha256sum | awk '{print $1}')"

PROJECT_NAME が空 (git 外) の場合は current をデフォルトに使う。

Step 2: harness-mem を project-only で検索し、Plan Brief 側 record を取得 (default)

引数に --cross-project-group <name> flag がない場合 (default behavior):

mcp__harness__harness_mem_search を以下のパラメータで呼び出す:

project: <PROJECT_NAME>
strict_project: true
tags: ["personal-preference", "plan-brief-approval"]
limit: 10

重要: project パラメータは必須。strict_project: true を指定し、cross-project な検索は絶対に行わない。

取得した record を data.user_request_hash == <USER_REQUEST_HASH> でフィルタし、最も新しい 1 件を選ぶ。 これが Plan Brief 時の承認内容 (chosen_option / acceptance_criteria 等) を保持している。

Step 2 (alt): cross-project search (Phase 65.3.5 opt-in)

引数に --cross-project-group <name> flag がある場合のみ、横断 group 内の他プロジェクトでの 類似 plan-brief-approval / acceptance-decision 履歴を取得する (D43 Option α):

MEMBERS_JSON="$(bash scripts/load-cross-project-groups.sh --group "<name>" 2>/dev/null)" || {
  echo "ERROR: cross-project group not found: <name>" >&2
  exit 1
}

MEMBERS_JSON が [] の場合は default の単一 project search に fallback。

MEMBERS_JSON が非空の場合、各 member project ごとに MCP search を 1 回発行:

for each project in MEMBERS_JSON:
  mcp__harness__harness_mem_search(
    project: <member>,
    strict_project: true,
    tags: ["personal-preference", "plan-brief-approval"],
    limit: 10
  )

結果を client 側でマージし、data.user_request_hash == <USER_REQUEST_HASH> でフィルタ。 hash 一致は基本的に同一 user request 由来のため複数 project での重複は稀だが、念のため id 単位で dedupe。

cross-project 由来の record を採用すると過去他案件の chosen_option / acceptance_criteria が混入する 可能性があるため、HTML 出力時は --with-redaction flag を必ず使用 すること:

bash scripts/render-html.sh --template accept ... --with-redaction

詳細は .claude/rules/cross-repo-handoff.md の「Phase 65.3 実装決定事項 (D43)」を参照。

Step 3: 過去の問題パターンを取得 (Phase 65.2.2 委譲)

bash scripts/accept-past-issues.sh --project "$PROJECT_NAME" --task "$USER_REQUEST" > "$PAST_ISSUES_JSON"

このスクリプトは patterns.md (P1-P33) と過去の acceptance-context.v1 record を semantic search し、 最大 3 件の past-issue.v1 を返す。各々 verified_in_current_task: bool 付き。

Step 4: verified_criteria を組み立てる

Plan Brief 時の acceptance_criteria 各項目について、現タスクの状態を評価する。 ユーザー (もしくは Claude) が「verify した evidence」を提示し、evidence 文字列を埋める。

evidence が空文字列の場合、HTML 上で警告表示される (DoD c)。

TDD が必要な task では、Acceptance Demo に TDD verified: yes|no の 1 行を必ず出す。 TDD 不要または skip の場合は TDD verified: not-required または TDD verified: skip:<reason> と表示する。 yes にできるのは .claude/state/tdd-red-log/<task-id>.jsonl の Red 証跡、または literal failing test output が確認できる時だけ。

Step 5: recommendation を算出する

上記「Recommendation 算出ロジック」に従って ship / wait / reject を決定する。

Step 6: HTML を生成する

scripts/render-html.sh (Phase 65.1.1) を templates/html/accept.html.template で呼ぶ:

bash scripts/render-html.sh \
  --template accept \
  --data "$CONTEXT_JSON" \
  --out "$HTML_OUT"

Step 7: ブラウザで自動 open する

scripts/plan-brief-open.sh (Phase 65.1.2 で導入された 汎用 OS dispatcher) を再利用:

bash scripts/plan-brief-open.sh "$HTML_OUT"

注: スクリプト名に「plan-brief」が入っているが、実体は OS 別 browser open dispatcher で kind 中立。 Phase 65.1.2 で先に導入されたため historical name。Layer 3 (HTML 直前最終 scan) 等の他用途でも再利用される。 BROWSER=true の env が設定されている場合 (CI 環境)、open は skip され printf で path だけ出力する。

Step 8: ユーザー判断待ち

「ship / wait / reject の recommendation を採用するか、override するか」を確認する。 判断後の memory write は別スキル (accept-record-decision.sh、Phase 65.2.3) の責務。

失敗時の挙動

Related

• harness-plan-brief (Phase 65.1.2) — 計画段階の対構造スキル。本スキルは Plan Brief 時の personal-preference.v1 を user_request_hash で join して read
• scripts/accept-past-issues.sh (Phase 65.2.2) — 過去の問題パターン取得 (read side)
• scripts/accept-record-decision.sh (Phase 65.2.3) — 承認 memory write (acceptance-decision.v1)
• scripts/render-html.sh (Phase 65.1.1) — HTML テンプレートエンジン
• scripts/plan-brief-open.sh (Phase 65.1.2) — 汎用 OS browser dispatcher
• harness-progress skill (Phase 65.4.1) — 進行管理スキル (3 surface のうち真ん中)

Harness Loop

Codex 版の harness-loop は、説明だけの擬似ループではなく、 実際にバックグラウンドで回るランナーを起動する。

ひとことで

$harness-loop は、1 回だけの実装依頼ではなく、 「今すぐ実行できる未完了タスクのまとまりを、Breezing で自動実行し続ける当番」を起動する入口。

ここでいう ready batch は、Depends が満たされていて、今すぐ並列実行できる cc:TODO / cc:WIP のまとまり。 1 cycle は 1 task ではなく、原則として 1 ready batch を処理する。

たとえると

人が横でずっと見張る代わりに、 「同時に進められる作業をまとめて見つける → Breezing に任せる → 結果を確認する → 次のまとまりへ進む」 を繰り返す監督係を、裏で常駐させるイメージ。

Quick Reference

実行コマンド

開始

harness codex-loop start all

範囲指定:

harness codex-loop start 41.1-41.4 --max-cycles 5 --pacing worker
harness codex-loop start JLB3R-02..JLB3R-08 --max-cycles 5 --pacing worker
harness codex-loop start all --max-workers max --pacing worker
harness codex-loop start all --plan roadmap --max-cycles 5
harness codex-loop start all --executor task --max-cycles 5

START..END は、Plans.md に並んでいる task ID をそのまま使う範囲指定。 英字やハイフンを含む task ID は .. を優先する。 41.1-41.4 のような従来の数値レンジも引き続き使える。

--max-workers は、Breezing が 1 cycle で同時に動かす worker 数の上限。 max は、選択範囲内で Depends が満たされた ready task の数をそのまま上限にする。 --executor task は、Breezing ではなく local worker に 1 task だけ渡す互換用の逃げ道。 問題切り分けや、並列実行したくない危険な作業で使う。 複数 Plans.md がある repo では、長時間 run の起動時に --plan NAME を明示する。 runner は開始時に解決した Plans file を cycle 間で保持するため、途中で active plan を切り替えない。

状態確認

harness codex-loop status
harness codex-loop status --json

停止

harness codex-loop stop

どう動くか

1. project root の .claude/state/codex-loop/ に Harness loop の実行状態を書き出す
2. 受け取った selection を Plans.md から正規化する
3. Plans.md から Depends が満たされた cc:TODO / cc:WIP を集め、ready batch を作る
4. --max-workers で ready batch の同時実行数を制限する
5. 既定では Breezing executor が ready batch を Lead / Worker / Reviewer 分離で実行する
6. --executor task の時だけ、互換用 local worker が 1 task per cycle で codex exec を起動する（CODEX_LOOP_TASK_DRIVER=companion の時だけ bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" task --background --write ... を使う）
7. 高リスク task / 2 回目失敗 / plateau 直前では advisor consult を挟む
8. ready batch 完了後に review / checkpoint / plateau 判定を行う
9. まだ対象タスクが残っていれば、待機後に次サイクルへ進む

Realtime Handoff / Silence Policy

Codex 0.123.0 以降の background agent は realtime handoff で transcript delta を受け取れる。 この delta は「状況把握用の追記」であり、毎回ユーザーへ返答する合図ではない。

ひとことで: background agent は、必要な時だけ報告し、何も判断が変わらない時は明示的に沈黙する。

たとえると、見張り役が廊下でずっと実況するのではなく、異常・完了・判断待ちだけを知らせる形。

報告してよいタイミング:

• loop 開始、停止、already running、stop 受理など、ユーザー操作に関わる lifecycle 境界
• 1 ready batch cycle の最終結果、commit、RESULT: APPROVED / RESULT: BLOCKED
• Breezing Lead が task 完了を progress feed としてまとめて出す時
• task が blocked、validation failure、review REQUEST_CHANGES、plateau、advisor STOP で止まる時
• user が status を実行した時、または明示的に途中状況を聞いた時
• advisor / reviewer drift、contract readiness failure など、放置すると品質判定がずれる時

沈黙するタイミング:

• transcript delta を受け取っただけで、task / review / advisor の状態が変わっていない時
• runner.log / jobs/*.log に既に残る細かな stdout だけが増えた時
• pacing 待機中で、次 cycle まで新しい判断材料がない時

途中報告の頻度:

• default は「1 ready batch cycle につき最終報告 1 回」。
• Breezing の task-level progress feed は、batch 内の完了数が動いた時だけ出す。
• 長い cycle でも、material state change がない限り heartbeat は出さない。
• 詳細な流れは harness codex-loop status --json と project root の .claude/state/codex-loop/runner.log に寄せ、会話側には要点だけ出す。

Advisor / Reviewer drift との関係:

• silence policy は drift 検知を弱めるためのものではない。
• advisor-request.v1 に response がない、review-result.v1 が返らない、contract が未承認などの異常は必ず state / log に残し、必要ならユーザーへ報告する。
• Advisor は PLAN / CORRECTION / STOP の相談役、Reviewer は最終品質判定役のまま分離する。

pacing

State Path Policy

Codex 版 harness-loop は、Codex native の会話・実行キャッシュと、Harness が共有する project state を分けて扱う。

• Harness 共通 state: project root の .claude/state/ 配下に置く。Claude 側の advisor / review / checkpoint と共有するため、harness codex-loop status もここを読む。
• Codex loop runner state: project root の .claude/state/codex-loop/ 配下に置く。これは「Codex 全体の正本」ではなく、Harness loop runner の job / cycle / log 用 state。
• Codex native state: ${CODEX_HOME:-~/.codex} 配下に残る Codex 自身の thread / transcript / cache。Harness loop の task status、advisor history、review result の正本にはしない。
• 禁止: .Codex/ や ~/.Codex を正本 path として案内しない。大文字 Codex ディレクトリは historical drift と見なす。

つまり、.claude/state/codex-loop/ は「この project の Harness loop state」であり、Codex native state 全体の固定保存先ではない。

状態ファイル

以下はすべて project root 基準。

• .claude/state/codex-loop/run.json
• .claude/state/codex-loop/cycles.jsonl
• .claude/state/codex-loop/runner.log
• .claude/state/codex-loop/current-job.json
• .claude/state/codex-loop/jobs/*.json
• .claude/state/codex-loop/jobs/*.log
• .claude/state/codex-loop/jobs/*.out
• .claude/state/advisor/history.jsonl
• .claude/state/advisor/last-request.json
• .claude/state/advisor/last-response.json
• .claude/state/locks/codex-loop.lock.d

Advisor Consult

Advisor は「代わりに実装する役」ではなく、「次の一手だけ返す相談役」。 loop では次の 3 箇所でだけ呼ぶ。

decision は 3 種だけ。

同じ trigger は trigger_hash = task_id + reason_code + normalized_error_signature で 1 回だけ相談する。 相談回数は task ごとに最大 3 回で、それ以上はユーザー判断に上げる。

注意点

• これは 本当に裏で動く。説明だけ返して終わるスキルではない。
• 同時に 2 本は起動できない。既に走っている場合は already running で止まる。
• 既定 executor は Breezing。旧来の 1 task per cycle 挙動が必要な時だけ --executor task を使う。
• 失敗したタスクを無理に飛ばして次へ進めるのではなく、基本はその場で止まって理由を残す。
• status と runner.log を見れば、今どこで止まっているか追いやすい。

具体例

「Phase 41 の残タスクを、今日の間は自動で回したい」なら:

harness codex-loop start 41.1-41.4 --max-cycles 8 --max-workers max --pacing worker

途中で様子を見る:

harness codex-loop status

夜になって止めたい:

harness codex-loop stop

なぜこの形か

Codex では Claude の /loop と同じ wake-up 機構をそのまま使えない。 その代わり、Codex loop runner を土台にして、 Harness 側で状態管理と再入制御を持ち、実作業は Breezing の batch 実行に寄せる。 そうすると、長時間タスクでも「止める」「再開する」「今の状態を見る」が素直になり、 依存関係を満たした作業だけを安全にまとめて進められる。

Harness Orchestration Scorecard

このセッション/プロジェクトの backend 活用度（Claude=ホスト / Codex / Cursor への委譲）を可視化する read-only スキル。 記録の正本は .claude/state/orchestration-ledger.jsonl（companion が委譲ごとに追記、Phase 90.1.1）と .claude/state/orchestration-totals.json（セッション終了/完了時に冪等 roll up、Phase 90.1.2）。

表示は on-demand のみ。作業中は出さず、見たい時にこのスキルで出す。 全タスク完了時の 1 回だけは task-completed が自動でターミナルサマリを出す（このスキルとは別経路）。

Quick Reference

• 「オーケストレーション活用度見せて」→ HTML スコアカードを生成して開く
• 「どのバックエンド使った」「Codex/Cursor どれだけ」→ ターミナルサマリ
• 「累計見せて」「自慢できるやつ」→ HTML スコアカード（lifetime totals が主役）

Deliverables

tri-state: used（count>0）/ available（設定済み未使用）/ not-configured（binary 不在＝中立、壊れではない）。 委譲ゼロなら "no delegations observed" に degrade。

Execution

helper script は plugin bundle root から呼ぶ:

HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"

ターミナルサマリ（--terminal）

bash "${HARNESS_PLUGIN_ROOT}/scripts/orchestration-scorecard.sh" --format terminal

3-5 行を要約してそのまま提示する。

HTML スコアカード（既定 / --out / --no-open）

OUT="${1:-.claude/state/orchestration-scorecard.html}"   # --out <path> で上書き
bash "${HARNESS_PLUGIN_ROOT}/scripts/orchestration-scorecard.sh" --format html-data \
  | bash "${HARNESS_PLUGIN_ROOT}/scripts/render-html.sh" --template orchestration --data - --out "$OUT"

• --no-open 指定がなければ生成後にパスを提示し、ブラウザで開くよう案内する（自動 open は環境依存なのでパス提示を基本とする）
• redaction は使わない: scorecard データは構造的に非機密（カウント + backend 名 + repo basename + 時刻のみ）。no-secret 保証は上流の ledger 契約が担保する

Related Skills

• harness-progress — 進捗ダッシュボード（タスク進捗。本スキルは backend 活用度に特化）
• harness-work / breezing — 実装（backend を実際に使う側）

harness-plan-brief

非エンジニアの発注者・プロデューサー職向けに、Claude が着手しようとしている計画を HTML 1 枚 で提示するスキル。 発注者の認知負荷ピーク (1) 計画理解の段階で使う。

Quick Reference

• 「Plan Brief を作って」 → このスキル
• 「実装前にざっくり整理」 → このスキル
• 「非エンジニア向けに計画を見せて」 → このスキル

責任境界

入力

引数 [task-description] にユーザーの request を渡す。 引数なしの場合は対話形式で受け取る。

出力

Schema: plan-brief-context.v1

{
  "schema": "plan-brief-context.v1",
  "user_request": "string (ユーザーの request 原文)",
  "my_understanding": "string (Claude の理解を 1-3 段落で)",
  "options": [
    { "name": "string", "summary": "string", "pros": ["string"], "cons": ["string"] }
  ],
  "risks": [
    { "kind": "string", "severity": "info|warn|critical", "description": "string", "mitigation": "string" }
  ],
  "acceptance_criteria": [
    { "id": "string", "description": "string", "verifiable_by": "string" }
  ],
  "tdd_required": "yes|no|skip:<reason>",
  "confidence": 0,
  "confidence_evidence": ["string"],
  "related_decisions": [
    { "id": "string", "title": "string", "relevance": "string" }
  ],
  "similar_past_plans": [
    { "archive_path": "string", "phase": "string", "outcome": "cc:完了|cc:WIP|cc:TODO|skipped", "relevance": "string" }
  ],
  "project": "string",
  "generated_at": "ISO8601"
}

完全 schema は schemas/plan-brief-context.v1.schema.json を参照。

Execution Flow

スキル起動時、Claude は以下の手順で動作する。

Step 1: project name を解決

PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)")"

PROJECT_NAME が空 (git 外) の場合は current をデフォルトに使う。

Step 2: harness-mem を project-only で検索する (default)

引数に --cross-project-group <name> flag がない場合 (default behavior):

mcp__harness__harness_mem_search を 必ず 以下のパラメータで呼び出す:

project: <PROJECT_NAME>
strict_project: true
query: <user request>
expand_links: true
limit: 5

重要: project パラメータは必須。空文字列や null を渡してはならない。 strict_project: true を指定し、cross-project な検索は絶対に行わない。 必要なら tags filter で decision / pattern を絞ってもよいが、project は固定。

過去 decision (D1-D41) / pattern (P1-P33) / Plans archive 28 件から類似案件を最大 5 件取得する。

Step 2 (alt): cross-project search (Phase 65.3.5 opt-in)

引数に --cross-project-group <name> flag がある場合のみ:

D43 Option α (MCP N-call) に従い、以下の手順で cross-project 検索を行う。

# (a) group → member projects に解決 (yaml SSOT)
MEMBERS_JSON="$(bash scripts/load-cross-project-groups.sh --group "<name>" 2>/dev/null)" || {
  echo "ERROR: cross-project group not found: <name>" >&2
  exit 1
}
# MEMBERS_JSON は ["proj1","proj2",...] 形式の JSON 配列

MEMBERS_JSON が [] (空配列) の場合は warning を出して default の単一 project search に fallback。

MEMBERS_JSON が非空の場合、各 member project に対して MCP search を 1 回ずつ発行 する:

for each project in MEMBERS_JSON:
  mcp__harness__harness_mem_search(
    project: <member>,
    strict_project: true,
    query: <user request>,
    expand_links: true,
    limit: 5
  )

各 search 結果を client 側でマージ・dedupe (id 単位)・relevance_score 降順 sort し、最大 5 件に絞る。 合計呼び出し数が多くなる (group が 5 project なら 5 回) ため、レイテンシは増える点に注意。

D43 判断 1 の根拠: MCP tool schema には projects: [array] も strict_project: false も exposed されていないため、横断検索は client 側 N-call が唯一の選択肢。 詳細は .claude/rules/cross-repo-handoff.md の「Phase 65.3 実装決定事項 (D43)」参照。

cross-project 結果には Layer 2/3 (Phase 65.3.2-65.3.4) の redaction を必ず通すこと:

• HTML レンダリング時に bash scripts/render-html.sh ... --with-redaction を使用
• これにより辞書 + NER + final scan の 3 段で固有名詞が漏れない

Step 3: context JSON を組み立てる

scripts/plan-brief-compile.sh (Phase 65.1.3 で実装) を使って、 mem search 結果から plan-brief-context.v1 schema 準拠の JSON を構築する。

65.1.3 が未実装の段階では、Claude が直接 jq で以下を組み立てる:

jq -n \
  --arg req "$USER_REQUEST" \
  --arg proj "$PROJECT_NAME" \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '{
    schema: "plan-brief-context.v1",
    user_request: $req,
    my_understanding: "(まだ未着手)",
    options: [],
    risks: [],
    acceptance_criteria: [],
    confidence: 0,
    confidence_evidence: ["(stub) 65.1.3 で算出ロジック実装"],
    tdd_required: "no",
    related_decisions: [],
    similar_past_plans: [],
    project: $proj,
    generated_at: $ts
  }' > "$CONTEXT_JSON"

Step 4: HTML を生成する

scripts/render-html.sh (Phase 65.1.1) を templates/html/plan-brief.html.template で呼ぶ:

HTML には TDD 判定を 1 行で表示する。 形式は tdd_required: yes、tdd_required: no、または tdd_required: skip:<reason> のいずれかにする。

bash scripts/render-html.sh \
  --template plan-brief \
  --data "$CONTEXT_JSON" \
  --out "$HTML_OUT"

Step 5: ブラウザで自動 open する

scripts/plan-brief-open.sh で OS 別 dispatch:

bash scripts/plan-brief-open.sh "$HTML_OUT"

BROWSER=true の env が設定されている場合 (CI 環境)、open は skip され printf で path だけ出力する。

Step 6: ユーザー承認待ち

「この理解で実装に進んでよいか」を確認する。 承認後の memory write は別スキル (Phase 65.1.4 の plan-brief-record-decision.sh) の責務。

失敗時の挙動

Related

• scripts/render-html.sh (Phase 65.1.1) — HTML テンプレートエンジン
• scripts/plan-brief-compile.sh (Phase 65.1.3) — context compilation
• scripts/plan-brief-record-decision.sh (Phase 65.1.4) — 承認 memory write
• harness-accept skill (Phase 65.2.1) — 受け入れ判断スキル (対構造)
• harness-progress skill (Phase 65.4.1) — 進行管理スキル (対構造)

Harness Plan

Harness の統合プランニングスキル。 以下の3つの旧スキルを統合:

• planning (plan-with-agent) — アイデア → Plans.md への落とし込み
• plans-management — タスク状態管理・マーカー更新
• sync-status — Plans.md と実装の同期確認

Quick Reference

Literal companion commands（CC 2.1.108+）

• /recap: 久しぶりに戻った時に要約を取り直してから sync へ入る
• /undo: /rewind の別名。直前の plan 更新を即座に戻したい時にそのまま使う

サブコマンド詳細

標準の計画品質契約

See references/planning-quality.md

harness-plan は、spec.md product contract and Plans.md task contract の co-required planning output を作る planning surface である。 precedence は spec.md > sub-spec > Plans.md のまま維持する。 Plans.md は task ledger、root spec.md は product contract であり、上下関係は崩さない。 渡された情報をそのまま Plans.md に落とさない。 計画作成や大きな task 追加では、最新情報・既存仕様・記憶・TeamAgent / サブエージェントによる複数視点の議論を確認し、 このプロダクトに取り入れるべき要素だけを task contract に変換する。 /harness-plan create は Spec delta または Spec skip reason と Plans.md task 生成をセットで返す。 出力には必ず Spec delta または Spec skip reason を含める。 Spec delta / Spec skip reason は Harness が生成し、consumer は承認・修正だけ行う。

Non-trivial planning gate:

単発・軽微タスクでない planning は、TeamAgent またはサブエージェント前提で扱う。 ここでの non-trivial は、複数 task / 複数 file / 複数 session / product behavior / API / data model / 権限 / 課金 / 外部連携 / 配布面 / セキュリティに影響する依頼を指す。 Task tool が使える場合は Product / Architecture / Security / QA / Skeptic の独立視点を走らせる。 使えない場合は サブエージェント未使用 と明示し、同じ観点を単独で分けて評価する。

non-trivial planning の出力には、次の検証を必ず含める。

• team_validation_mode: not_required_lightweight / native / subagent / manual-pass / unavailable
• spec.md / sub-spec / Plans.md の整合性
• harness-mem / harness-recall / repo memory による車輪の再発明防止確認
• プロダクト目的から外れていないか
• セキュリティ、権限、秘密情報、サプライチェーンに問題がないか
• lint / formatter baseline があるか。source code changes を含む plan で未設定なら、実装 task の前に setup task を置く
• ちゃんと動く計画か。つまり test / smoke / CI / review / release gate が task DoD に落ちているか

軽量 task は team_validation_mode: not_required_lightweight でよい。 non-trivial planning は native / subagent / manual-pass のいずれかを使う。 unavailable のまま Required にしてはいけない。 Product / Architecture / Security / QA / Skeptic は検証 perspective であり、agent_type 名ではない。 利用可能な TeamAgent / Task サブエージェントに perspective として依頼し、任意 agent spawn を要求しない。 Security gate は秘密情報の実読取を要求しない。 .env や secret の read が必要になる場合は Risk Gate として止め、許可された既存 guard / evidence で確認する。

適用する場面:

• create で新しい計画を作る
• add で product behavior / API / 権限 / 課金 / 外部連携 / 配布面に影響する task を足す
• ユーザーが外部プロダクト、競合、仕様案、改善案、比較材料を渡した
• 既存仕様や過去判断との衝突リスクがある

軽く扱ってよい場面:

• marker 更新だけの update
• status 照合だけの sync
• typo、format、README/CHANGELOG のみ
• 既存 spec とテストで正解が固定されている狭い変更

品質フロー:

1. 入力情報を分解し、評価対象・採点軸・不確かな事実を明示する
2. 最新情報を取得する。外部事実は WebSearch / 公式ドキュメント / 一次情報を優先し、重要点は複数ソースでクロスチェックする
3. 既存仕様・root spec.md・Plans.md・README・docs・CLAUDE.md・関連 skill を確認する
4. harness-mem / harness-recall / .claude/agent-memory/ / .claude/state/ など、利用可能な記憶面を project-scoped で確認する
5. non-trivial planning では TeamAgent / Task サブエージェントを使い、Product / Architecture / Security / QA / Skeptic など異なる視点で独立レビューする
6. source code changes を含む plan では lint / formatter baseline を確認し、未設定なら setup task を先行させる
7. 中立的な採点レビューを出し、Required / Recommended / Optional / Reject に分類する
8. $easy 形式で、提案内容・理由・どうなるのかを報告する
9. 採用する案だけを root spec.md / Plans.md / test task へ落とし込む

create — 計画作成

See references/create.md

アイデア・要件をヒアリングし、実行可能な Plans.md を生成する。

フロー:

1. 会話コンテキスト確認（直前の議論から抽出 or 新規ヒアリング）
2. 何を作るか聞く（max 3問）
3. 計画品質チェック（最新情報、既存仕様、記憶、TeamAgent / サブエージェント複数視点レビュー、採点）
4. 技術調査（WebSearch）
5. 機能リスト抽出
6. spec.md / Plans.md 二正本チェック（Spec delta または Spec skip reason + Plans.md task）
7. 優先度マトリクス（Required / Recommended / Optional / Reject）
8. TDD 採用判断（テスト設計）
9. Plans.md 生成（cc:TODO マーカー付き）
10. 次のアクション案内

spec.md / Plans.md 二正本チェック（デフォルト）

Plans.md は「やるべきこと」の task contract、root spec.md は「何が正しいか」の product contract として扱う。 co-required planning output は両方の出力を必須にするという意味であり、precedence は spec.md > sub-spec > Plans.md のまま維持する。 実装がぶれる可能性がある時は、Plans.md 生成前に root spec.md を更新する。 create と product-impacting add は毎回 root spec.md を読む。

優先する保存先:

1. root spec.md
2. consumer repo に root spec.md がない時だけ、既存の project spec / architecture / product compass
3. consumer repo に root spec.md がない時だけ、docs/spec/00-project-spec.md
4. 既存規約がある repo では、その規約に沿った spec path

作成/更新が必要な条件:

• ユーザーに見える振る舞い、API、データモデル、権限、課金、外部連携を決める task
• 複数の実装方針があり、選び方で product behavior が変わる task
• 過去または今回の会話で「仕様が曖昧で実装がぶれた」兆候がある task
• Plans.md には作業内容があるが、project としての正解条件が安定文書にない task

不要な条件:

• typo、format、dependency bump、README/CHANGELOG のみ
• 動作変更なしの狭い refactor
• 既存 spec とテストで正解が十分に固定されている修正

出力契約:

• Spec delta: product contract を更新する時に、対象 spec path と変更点を書く
• Spec skip reason: product contract を更新しない時に、理由を書く
• Spec delta / Spec skip reason は Harness が生成し、consumer は承認・修正だけ行う
• docs-only / mechanical task でも Spec skip reason を task context / sprint contract に残す
• missing search result、unavailable memory、未読ファイルを absent と断定しない。not_observed != absent
• ユーザーに spec を一から書かせない。agent が既存 spec と入力から最小 delta を作り、曖昧な時だけ判断分岐を出す

参照:

• docs/plans/spec-ssot.md

create 完了時のセッション起動案内（必須）

create が終わったら、説明だけで終わらせず、新しいセッションの起動コマンド と 起動後にそのまま入れる最初の指示プロンプト をセットで案内する。

優先順位は次の通り:

1. 未完了タスクが 1 件だけ、または最初の 1 件だけ始めるのが自然
   • 起動コマンド: claude
   • 最初の入力: /harness-work <task番号>
2. 依存の薄いタスクが複数あり、まとめて進めるのが自然
   • 起動コマンド: claude
   • 最初の入力: /breezing all
   • 代替: /harness-work all
3. 長時間実行や再入が前提
   • 起動コマンド: ENABLE_PROMPT_CACHING_1H=1 claude
   • 最初の入力: /harness-loop all
   • 代替: /breezing all

最低でも次の 3 行を含める:

• 新しいセッションの起動コマンド:
• 起動後の最初の入力:
• 向いている場面:

例:

新しいセッションの起動コマンド: claude
起動後の最初の入力: /breezing all
向いている場面: Phase 1 の task が複数あり、まとめて進めるほうが自然なため

長時間系を勧める場合は、Claude Code セッション起動コマンドも併記する:

新しいセッションの起動コマンド: ENABLE_PROMPT_CACHING_1H=1 claude
起動後の最初の入力: /harness-loop all
向いている場面: 5 分を超える待機や resume をまたぐ長時間タスクのため

補足:

• scripts/claude-longrun.sh はこのリポジトリの開発補助スクリプトで、plugin install 後の consumer 環境には配布されない
• そのため、consumer 向け案内では常に ENABLE_PROMPT_CACHING_1H=1 claude の 1 行コマンドを優先する
• リポジトリ開発中だけ同等のラッパーを使いたい場合、bash scripts/claude-longrun.sh はローカル checkout 上では利用してよい

CI モード (--ci): ヒアリングなし。既存の Plans.md をそのまま利用してタスク分解のみ行う。

add — タスク追加

Plans.md に新しいタスクを追加する。 product-impacting な追加では、上の「spec.md / Plans.md 二正本チェック」に従い Spec delta または Spec skip reason も出力する。

/harness-plan add タスク名: 詳細説明 [--phase フェーズ番号]

タスクは cc:TODO マーカーで追加される。

update — マーカー更新

タスクのステータスマーカーを変更する。

/harness-plan update [タスク名|タスク番号] [WIP|完了|blocked]

マーカー対応表:

sync — 進捗同期

実装状況と Plans.md を照合し、差分を検出・更新する。

See references/sync.md

フロー:

1. Plans.md の現状取得
2. Plans.md フォーマット検出（v1: 3 カラム / v2: 5 カラム）
3. git status / git log から実装状況取得
4. エージェントトレース確認（.claude/state/agent-trace.jsonl）
5. Plans.md と実装の差分検出
6. 未更新マーカーの自動修正提案
7. 次のアクション提示

レトロスペクティブ（デフォルト ON）: cc:完了 タスクが 1 件以上あれば自動的に振り返りを実行する。 見積もり精度、ブロック原因パターン、スコープ変動を分析し、学びを記録。 sync --no-retro で明示的にスキップ可能。

team mode / issue bridge

Plans.md は正本のまま維持し、GitHub Issue 連携は opt-in の team mode だけで使う。

• solo 開発では bridge を使わない
• team mode は tracking issue を 1 つ作り、その配下に task ごとの sub-issue payload を dry-run で生成する
• scripts/plans-issue-bridge.sh は実際に GitHub を更新せず、常に dry-run の payload を返す
• Plans.md への変更はこの bridge では行わない

参照:

• docs/plans/team-mode.md

named Plans

複数の Plans.md を使う場合は plans/manifest.json を正本にして、名前で選択する。

scripts/plan-registry.sh list
scripts/plan-registry.sh switch roadmap
scripts/plans-issue-bridge.sh --plan roadmap --format markdown
node scripts/generate-sprint-contract.js --plan roadmap 9.1.1

運用ルール:

• 1 run では 1 つの named plan だけを使う
• long-running / CI / issue bridge では active pointer に頼らず --plan <name> を渡す
• manifest path は project root 相対のみ。絶対パス、..、repo 外 symlink は拒否される

参照:

• docs/plans/named-plans.md

Plans.md フォーマット規約

フォーマット

# [プロジェクト名] Plans.md

作成日: YYYY-MM-DD

---

## Phase N: フェーズ名

| Task | 内容 | DoD | Depends | Status |
|------|------|-----|---------|--------|
| N.1  | 説明 | テスト通過 | - | cc:TODO |
| N.2  | 説明 | lint エラー 0 | N.1 | cc:WIP |
| N.3  | 説明 | マイグレーション実行可能 | N.1, N.2 | cc:完了 |

DoD（Definition of Done）: 検証可能な完了条件を 1 行で記述。「いい感じ」「ちゃんと動く」は禁止。Yes/No で判定できる形にする。

Depends: タスク間の依存関係。-（依存なし）、タスク番号（N.1）、カンマ区切り（N.1, N.2）、フェーズ依存（Phase N）。

TDD tags

Plans.md の task には、TDD 判定を明示するタグを内容または DoD に書ける。

<reason> は空にしない。 例: [tdd:skip:docs-only]、[tdd:skip:no-test-framework-detected]。

タグがない場合の tdd_required は次の順で推論する。

1. Plans.md tag: [tdd:required] / [tdd:skip:<reason>]
2. files: src/, app/, cmd/, lib/, pkg/, internal/, go/ など source 実装を含むなら required
3. TDD 推論: docs-only や test framework なしなら skip reason を付けて not required

optional briefs / manifest

harness-plan create は、必要なときだけ brief を付ける。

• project spec SSOT は project 全体の正解条件を固定する文書で、必要時だけ作る
• UI を含むタスクでは design brief
• API を含むタスクでは contract brief
• brief は「何を作るか」を短く固定する補助資料で、Plans.md や spec SSOT を置き換えない
• skill frontmatter の一覧は scripts/generate-skill-manifest.sh で machine-readable JSON にできる

参照:

• docs/plans/briefs-manifest.md
• docs/plans/spec-ssot.md

マーカー一覧

関連スキル

• harness-sync — 実装と Plans.md を同期する
• harness-work — 計画したタスクを実装する
• harness-review — 実装のレビュー
• harness-setup — プロジェクト初期化

Harness Progress Tracker

Phase 65.4 (Progress Tracker) — 3rd surface of the cognitive-load HTML triplet. Plan Brief / Acceptance Demo に続く 3 つ目の HTML surface で、進行中セッションの全体像を 1 枚の紙で把握 できるようにする。

Quick Reference

Mission

"今のセッションは何件のタスクをどこまで終わらせて、いつ終わる見込みで、いくら使ったか" を、 エンジニアじゃない vibecoder が 3 秒でブラウザで把握 できる HTML 1 枚を生成する。

やる:

• Plans.md の cc:TODO / cc:WIP / cc:完了 件数を集計
• progress_pct (完了率) を計算 (cc:完了 ÷ 総タスク × 100)
• 経過分数 / 推定総分数 / コスト so-far / コスト estimate を表示
• drift alert を表示 (Phase 65.4.3 以降で populate)

やらない (本 cycle):

• WebSocket / SSE による live update (静的 HTML、再生成で更新)
• 過去 session の history 比較 (Phase 65.4.4 で別軸)
• 他 project の cross-project view (Phase 65.3 と独立)

Schema: progress-snapshot.v1

詳細仕様: schemas/progress-snapshot.v1.schema.json

schema:        progress-snapshot.v1
project:       <basename of git repo>
current_task:  <cc:WIP の最初の項目 1 行サマリ、なければ空文字>
progress_pct:  <0-100 の整数、cc:完了 ÷ 総タスク × 100 の四捨五入>
todo_tasks:    [{number, title}]    ← cc:TODO のみ
wip_tasks:     [{number, title}]    ← cc:WIP のみ
done_tasks:    [{number, title, commit}]   ← cc:完了 [hash] のみ、hash は 7 chars
elapsed_minutes:          <int, state file から>
estimated_total_minutes:  <int, state file から>
cost_so_far_usd:          <float, state file から>
cost_estimate_usd:        <float, state file から>
alerts:                    []   ← Phase 65.4.3 以降で populate
generated_at:             <ISO8601 UTC>

Execution Flow

Step 0: PROJECT_NAME を取得

PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)" 2>/dev/null || echo "current")"

Step 1: snapshot を組み立て

SNAPSHOT_JSON="$(mktemp /tmp/progress-snapshot-XXXX.json)"
bash scripts/progress-snapshot.sh \
  --plans Plans.md \
  --project "$PROJECT_NAME" \
  > "$SNAPSHOT_JSON"

scripts/progress-snapshot.sh (Phase 65.4.1 で実装) は Plans.md を parse し progress-snapshot.v1 schema 準拠の JSON を出力する。

Step 2: HTML をレンダリング

OUT_PATH="${OUT_PATH:-out/progress-snapshot.html}"
mkdir -p "$(dirname "$OUT_PATH")"

bash scripts/render-html.sh \
  --template progress \
  --data "$SNAPSHOT_JSON" \
  --out "$OUT_PATH"

Step 3: ブラウザで開く

--no-open flag がない場合のみ実行 (PostToolUse hook からの背景再生成では skip):

bash scripts/plan-brief-open.sh --path "$OUT_PATH"

Cross-project search (default OFF)

Phase 65.4.4 で --cross-project-group <name> flag が追加される。本 cycle (65.4.1) では default OFF、現プロジェクトのみ集計する。

Failure modes

Related

• harness-plan-brief (Phase 65.1.x) — 1st surface (実装前の説明会)
• harness-accept (Phase 65.2.x) — 2nd surface (検収判断)
• harness-progress (本 skill, Phase 65.4.x) — 3rd surface (進捗ダッシュボード)
• 65.4.2 (PostToolUse auto-regen)、65.4.3 (drift alert 5 種)、65.4.4 (過去判断 lookup) で機能拡張

Harness Release (汎用)

Keep a Changelog + GitHub を使うあらゆるプロジェクト向けの汎用リリース自動化スキル。

設計原則: 単一確認ゲート。ユーザーは 1 回だけ全体計画を見て承認する。承認後はファイル書き換え → commit → branch push → PR 作成/更新 → default branch へ merge → default branch 上で tag → GitHub Release までを中断なく実行する。

Release complete の定義: release は「tag と GitHub Release を作った」だけでは完了ではない。対象 work と release bump が default branch（通常 main）に merge 済みで、release tag が default branch 到達可能 commit を指し、GitHub Release がその tag を公開している状態を完了とする。

Literal invocation note: この skill の入口は harness-release, /release, /release patch, /release --dry-run のような literal command をそのまま使う。

CC runtime hard floor との関係

Claude Code 2.1.183+ の runtime hard floor は GitHub CLI release publish 系コマンドを構造的に deny する (Anthropic 製品仕様、settings.json の permissions.ask で覆せない)。本 skill は publish 自体を実行せず、.github/workflows/release.yml (tag push trigger) に委譲する。skill は tag push までで責務を完了し、その後 scripts/release-verify-publish.sh で workflow による公開を verify する。

Revert 条件: CC が runtime hard floor に user explicit approval path を提供したら、Post-Gate に直接 publish step を戻すことを検討する。

Bare invocation contract

if $ARGUMENTS == "": → 「今までの作業をコミットし、PR/main 反映まで完了してリリースしたい」と解釈し、Review Gate 検出を実行する → 対象 work が 1 つに確定できる場合だけ Step 0 (Review Gate) へ自動進行する → 対象が不明または review state が無い場合は AskUserQuestion で選択肢を出してから進める

引数なし呼び出し時の最初の応答で必ず次の literal marker を出力する:

RELEASE_AUTOSTART: target=<work-summary>, base_ref=<ref>, mode=<patch|minor|major|auto>

「タスクが不明確」「指示を待ちます」「タスクがありません」「追加の指示をお待ちします」は禁止行動。

Output Contract (P35: 「止まったように見える」UX 対策)

skill 結論時の output の 最後の 1 行は必ず P35 footer を含め、footer は本文 (user-facing prose) と同じ言語で出力する（言語解決は既存の言語ルールに従い、footer 契約は言語を再定義しない）。これは <local-command-stdout> 経由の表示で user が「止まった」と感じる UX 問題への明示的な instruction (patterns.md P35) で、意図は言語に依存しないため literal は言語ごとに切り替える (#208):

• ja: ↑この結果は Claude が要約します。Enter キーで次へ進むか、新規 prompt で別の指示を出してください。
• en: ↑Claude will summarize this result. Press Enter to continue, or send a new prompt for a different instruction.
• その他の言語: 同じ意味の 1 行を本文と同じ言語で出力する

Language

User-facing prose follows the explicit session or project language. If no language is configured, use English. Use Japanese only when i18n.language: ja, CLAUDE_CODE_HARNESS_LANG=ja, or an explicit session instruction requests Japanese output. Machine-readable values stay English.

harness-release / /release だけが入力された場合、これは 「今までの作業をコミットし、PR/main 反映まで完了してリリースしたい」 という意味として扱う。 旧表現の 「今までの作業をコミットしてリリースしたい」 も同じ意図だが、完了条件には PR/main 反映を必ず含める。 「タスクがありません」「指示を待ちます」で止まってはいけない。

bare release では、通常の release preflight の前に Review Gate と Work Commit Gate を実行する。

1. git status --porcelain と git log @{upstream}..HEAD / main..HEAD を確認し、「今までの作業」の対象を特定する
2. .claude/state/review-result.json と .claude/state/review-approved.json を確認し、対象 work に APPROVE 済み review があるか確認する
3. APPROVE 済み review が無い場合は AskUserQuestion で確認する
4. ユーザーが「レビューから開始」を選んだら、harness-review を起動し、APPROVE になるまで release へ進まない
5. harness-review が REQUEST_CHANGES を返した場合は release を保留し、harness-work で修正してから harness-review を再実行する。これを APPROVE までループする
6. harness-review が APPROVE を返した後、working tree の作業 commit を作る
7. working tree clean になってから通常の release preflight / confirmation gate / PR merge / tag / GitHub Release へ進む

Review Gate AskUserQuestion

harness-release 実行時に review approval が確認できない場合は、推測で release しない。 次の Ask を出す。

question: "harness-release は今までの作業をコミットしてリリースしますが、この作業の APPROVE review が見つかりません。どう進めますか？"
options:
  - label: "レビューから開始 (Recommended)"
    description: "harness-review を実行し、APPROVE になった場合だけ commit/release へ進みます。"
  - label: "release dry-run"
    description: "ファイルを書き換えず、release 計画と不足 gate だけ確認します。"
  - label: "中止"
    description: "review も release も行わず止めます。"

ユーザーが「レビューから開始」を選んだ場合は、同じセッション内で harness-review から始める。 harness-review の対象決定は harness-review 側の bare review contract に従う。 review が APPROVE なら、そのまま harness-release の Work Commit Gate へ戻る。 review が REQUEST_CHANGES なら release は保留し、harness-work で修正してから harness-review を再実行する。 この修正後再レビュー loop は APPROVE まで継続する。

Persist Verdict after Review Gate (required / #218 fix)

harness-review 委譲後、必ず .claude/state/review-result.json に verdict が永続化されている ことを確認する。harness-review 側の Persist Verdict step が踏まれていれば既に保存済みだが、 踏み忘れ時の 二段防御として、Review Gate 側でも次の check + 補完保存を行う。これを欠かすと Work Commit Gate (Step 6) の git commit が PreToolUse commit guard でブロックされる。

# 1. 保存済みか確認
if [ -f .claude/state/review-result.json ] \
   && [ "$(jq -r '.verdict // empty' .claude/state/review-result.json 2>/dev/null)" = "APPROVE" ]; then
  echo "review-result.json already persisted with APPROVE"
else
  # 2. 未保存なら orchestrator が in-context の verdict JSON を一時ファイルへ書き出し
  mkdir -p .claude/state
  cat > .claude/state/tmp-review-result.json <<'JSON'
{ "schema_version": "review-result.v1", "verdict": "APPROVE", ... }
JSON
  bash "${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD}}/scripts/write-review-result.sh" \
    .claude/state/tmp-review-result.json \
    "$(git rev-parse --short HEAD 2>/dev/null || true)"
  rm -f .claude/state/tmp-review-result.json
fi

multi-commit セーフティ: Phase 94.1.3 で PostToolUse commit-cleanup が VERSION / .claude-plugin/plugin.json / harness.toml / CHANGELOG.md のみの bookkeeping commit を認識し承認削除を skip するようになったため、 Post-Gate の version bump commit (Step 11) は harness-release の自動 commit でそのまま通過する。 それ以前のバージョン (4.15.0 以前) を使う場合は、Work Commit Gate と version bump commit の間に 再度 Persist Verdict を行うこと。

ユーザーに戻してよいのは次の場合だけ。

1. 修正に仕様正本 / Plans.md / API / permission / migration / billing などの意思決定が必要で、AskUserQuestion が必要
2. 修正方針が複数あり、どれを採るかでユーザー価値や互換性が変わる
3. ユーザーが Ask で release dry-run または 中止 を選んだ

REQUEST_CHANGES 単体を最終停止理由にしてはいけない。

Work Commit Gate

bare release で working tree に未コミット変更がある場合、release version bump commit とは別に、 review 済み work commit を先に作る。

git status --short
git diff --stat
git add <reviewed files>
git commit -m "<type>: <summary>"

commit message は review summary / Plans.md task / branch name から短く生成する。 判断できない場合は AskUserQuestion で 2〜3 個の commit message 候補を出す。 work commit 作成後に .claude/state/review-result.json の commit_hash を確認または更新し、 release preflight へ進む。

通常の release preflight に入った後は、これまで通り working tree dirty を fail とする。 dirty tree のまま version bump / tag / GitHub Release に進まない。

Quick Reference

/release              # 今までの作業を review gate → commit → PR/main merge → release する
/release patch        # bump を patch に明示指定
/release minor        # bump を minor に明示指定
/release major        # bump を major に明示指定
/release --dry-run    # 計画の表示のみ、実行しない

前提条件

このスキルが動くプロジェクトは以下を満たす必要があります:

1. CHANGELOG.md が Keep a Changelog 形式
2. [Unreleased] セクションが存在する
3. 以下のいずれかの version file を持つ:
   • VERSION (単独ファイル)
   • package.json (npm)
   • pyproject.toml (Python, [project] または [tool.poetry])
   • Cargo.toml (Rust, [package])
4. gh CLI がインストール済みで、認証済み
5. git リモート origin が GitHub を指す
6. Claude Code plugin project の場合は、claude CLI が plugin tag をサポートしている

これらが満たされない場合、Preflight で detect して abort します。

prUrlTemplate による multi-host review URL は将来候補として認識するが、 このスキルの release automation は今も gh CLI と GitHub remote を primary path とする。 owner / branch / release asset / CI metadata の自動取得は host ごとの差が大きいため、Phase 56.2.3 では docs-only に留める。

単一ゲートフロー

[Bare release only: 作業 review/commit 前段]
  ↓
  0. Review Gate (未レビューなら AskUserQuestion → harness-review)
  0.5 Work Commit Gate (review APPROVE 済み work を release bump と分けて commit)
  ↓
[Pre-Gate: 情報収集のみ、ファイル未変更]
  ↓
  1. Preflight (working tree clean / CHANGELOG / gh 等の確認)
  2. Version file 自動検出
  3. 現在バージョンの読み取り
  4. Claude plugin tag preflight (plugin project の場合のみ)
  5. [Unreleased] 内容の解析 → bump level 推定
  6. 新バージョン算出
  7. CHANGELOG 差分ドラフト作成 (メモリ上)
  8. GitHub Release notes ドラフト作成 (メモリ上)

★━━━━━━ 単一確認ゲート ━━━━━━★
  ユーザーに全計画を 1 回だけ提示:
    - 検出された version file
    - 現バージョン → 新バージョン
    - bump 判定理由 ("[Unreleased] に ### Added があるため minor" 等)
    - CHANGELOG 変更プレビュー
    - GitHub Release notes ドラフト
    - コミット対象ファイル一覧
    - 最終アクション (branch push + PR merge + tag + release publish)

  ユーザー応答:
    "yes"        → Post-Gate へ進む
    "<修正指示>"  → 指示に応じて draft を再生成、再確認
    "cancel/no"  → 何もせず終了
★━━━━━━━━━━━━━━━━━━━━━━━★
  ↓
[Post-Gate: 承認後、中断なし]

  9. Version file 書き換え
  10. CHANGELOG.md 書き換え ([Unreleased] → [X.Y.Z] 昇格 + compare link)
  11. git add + commit
  12. release branch push
  13. PR 作成/更新
  14. default branch へ merge
  15. default branch を fetch/checkout し、release commit が到達可能であることを確認
  16. Claude plugin tag validation + tag (plugin project の場合のみ)
  17. GitHub Release 用 semver tag (必要な project のみ)
  18. git push origin <default-branch> --tags
  19. tag push 後、`.github/workflows/release.yml` が release を公開し、`release-verify-publish.sh` で verify
  20. 完了報告

Pre-Gate 詳細

1. Preflight

# 必須ツール
command -v gh >/dev/null || { echo "gh CLI がありません"; exit 1; }
command -v python3 >/dev/null || { echo "python3 が必要です"; exit 1; }

# working tree
if [ -n "$(git status --porcelain)" ]; then
  echo "working tree に未コミット変更があります"; exit 1;
fi

# CHANGELOG
[ -f CHANGELOG.md ] || { echo "CHANGELOG.md がありません"; exit 1; }
grep -q "^## \[Unreleased\]" CHANGELOG.md || { echo "[Unreleased] セクションがありません"; exit 1; }

# plugin/mirror projects
scripts/release-preflight.sh

この working tree clean check は通常 release preflight の gate である。 bare release で「今までの作業」を commit したい場合は、この check の前に Review Gate と Work Commit Gate を完了させる。 未レビューの dirty tree をこの check だけで abort して終わらせてはいけない。

scripts/release-preflight.sh は tag 作成前に opencode/, skills-codex/, codex/.codex/skills/ の mirror drift も検出する。node scripts/build-opencode.js が差分を生成した場合は release を止め、その差分を commit してから tag に進む。

2. Version File 自動検出

以下を優先順で探索。最初に見つかったものを正本とする:

# Python snippet to run inline
import os, json, re
import tomllib  # Python 3.11+

def detect_version_file():
    if os.path.exists("VERSION"):
        with open("VERSION") as f:
            return ("VERSION", f.read().strip(), None)
    if os.path.exists("package.json"):
        with open("package.json") as f:
            data = json.load(f)
        return ("package.json", data["version"], None)
    if os.path.exists("pyproject.toml"):
        with open("pyproject.toml", "rb") as f:
            data = tomllib.load(f)
        if "project" in data:
            return ("pyproject.toml", data["project"]["version"], "[project]")
        if "tool" in data and "poetry" in data["tool"]:
            return ("pyproject.toml", data["tool"]["poetry"]["version"], "[tool.poetry]")
    if os.path.exists("Cargo.toml"):
        with open("Cargo.toml", "rb") as f:
            data = tomllib.load(f)
        return ("Cargo.toml", data["package"]["version"], "[package]")
    raise RuntimeError("No supported version file found")

詳細: version-files.md

3. Claude Plugin Tag Preflight

.claude-plugin/plugin.json が存在する project では、通常の GitHub Release tag とは別に Claude plugin release tag も作る。

ひとことで言うと、git tag -a を手で組み立てる前に、Claude Code 本体の plugin validation に通してから {plugin-name}--v{version} tag を作る。

Pre-Gate ではファイルを書き換えず、以下を確認する。 version sync は grep / sed で拾わず、JSON は structured parser で読む:

command -v claude >/dev/null || { echo "claude CLI がありません"; exit 1; }
claude plugin validate .claude-plugin/plugin.json

HARNESS_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-.}"
python3 "${HARNESS_PLUGIN_ROOT}/scripts/check-release-version-sync.py" --root .

claude plugin tag .claude-plugin --dry-run

${HARNESS_PLUGIN_ROOT}/scripts/check-release-version-sync.py は、存在する release surface をすべて読み取り、canonical を VERSION > package.json > .claude-plugin/plugin.json > .codex-plugin/plugin.json の順で決める。 そのうえで、以下の不一致・欠落が 1 つでもあれば tag / release に進まない:

• VERSION
• package.json の .version
• .claude-plugin/plugin.json の .version
• .codex-plugin/plugin.json の .version
• .claude-plugin/marketplace.json の .metadata.version
• .claude-plugin/marketplace.json の .plugins[].version（配列内の各 plugin entry）

不一致時は、どの surface が canonical と違うか、またはどの field が missing / invalid かを表示する。 機械処理や CI で読む場合は --json を使う:

python3 "${HARNESS_PLUGIN_ROOT}/scripts/check-release-version-sync.py" --root . --json

この check は 3 つの事故を防ぐためにある:

• VERSION と .claude-plugin/plugin.json の version がずれたまま tag を切る事故
• package.json / marketplace entry の version が古いまま release workflow に進む事故
• plugin manifest / marketplace entry の validation を通さず、あとで plugin install / update 側で詰まる事故

--dry-run では claude plugin tag が実際に作る tag 名と内部の git tag -a / push 相当コマンドが見える。ここで見えた command を Confirmation Gate の plan に含める。

4. Bump 自動推定

[Unreleased] 直下の見出しを解析して bump level を決定:

ユーザーが /release patch|minor|major で明示指定した場合はそちらを優先。 詳細: bump-detection.md

5. CHANGELOG ドラフト作成 (メモリ上)

以下を計算、まだ書き込まない:

1. ## [Unreleased] の本文を切り出し
2. ## [Unreleased] と ## [<previous>] の間に ## [<new>] - YYYY-MM-DD を挿入した形を作成
3. 末尾 compare link:
   • [Unreleased]: .../compare/v<prev>...HEAD → v<new>...HEAD
   • [<new>]: .../compare/v<prev>...v<new> を追加
4. repo URL は既存の [Unreleased]: 行から動的抽出

6. Release Notes ドラフト作成 (メモリ上)

## [<new>] セクションの内容を元に、GitHub Release 用のマークダウンを生成:

## What's Changed

**<リリーステーマ(1行)>**

### Before / After
<テーブル>

### Added / Changed / Fixed / Removed
<該当セクションをコピー>

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

詳細: release-notes.md

Confirmation Gate

すべてのドラフトが揃ったら、ユーザーに 1 回だけ提示:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Release Plan: v<old> → v<new> (<bump>)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Version file: <detected file>
 Bump reason:  <why this level was chosen>

 CHANGELOG changes:
   [Unreleased] に <N> 項目の変更を検出
   [<new>] - YYYY-MM-DD として確定
   Compare link を追加

 GitHub Release notes preview:
   <最初の 10 行>
   ...

 Files to modify:
   - <version file>
   - CHANGELOG.md

 Final actions:
   - git commit -m "chore: release v<new>"
   - git push origin <release-branch>
   - gh pr create/update + gh pr merge into <default-branch>
   - git fetch origin <default-branch> && git checkout <default-branch>
   - claude plugin tag .claude-plugin --push --remote origin  # plugin project の場合。default branch 上で実行
   - git tag -a v<new>                                        # GitHub Release 用 semver tag が必要な場合。default branch 上で作成
   - git push origin <default-branch> --tags
   - (tag push 後は GitHub Actions release workflow が自動で release 公開)

Proceed? [yes / cancel / <修正指示>]

Post-Gate 詳細

承認後は中断なしで実行。失敗時は以下の方針:

PR / Main Merge Gate

Post-Gate の release commit 後は、tag を作る前に GitHub PR を default branch へ merge する。

release_branch="$(git branch --show-current)"
default_branch="${HARNESS_RELEASE_DEFAULT_BRANCH:-main}"

git push -u origin "$release_branch"
gh pr create --base "$default_branch" --head "$release_branch" --title "chore: release v<new>" --body "<release summary>"
gh pr merge --merge --delete-branch=false

git fetch origin "$default_branch" --tags
git checkout "$default_branch"
git pull --ff-only origin "$default_branch"
git merge-base --is-ancestor "<release-commit>" "origin/$default_branch"

既存 PR がある場合は新規作成せず、既存 PR の body を更新して merge する。repository policy が squash merge を要求する場合は、release commit hash ではなく release bump の内容（version files + CHANGELOG + source commits）が default branch に含まれることを確認する。

tag はこの Gate 完了後、default branch の HEAD もしくは release commit 到達可能な commit に対して作る。release branch 上だけに存在する commit を指す tag で GitHub Release を作ってはいけない。

Claude plugin project の tag 作成

.claude-plugin/plugin.json がある project では、PR/main merge 後に default branch 上でもう一度 version sync を確認してから plugin tag を作る:

HARNESS_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-.}"
python3 "${HARNESS_PLUGIN_ROOT}/scripts/check-release-version-sync.py" --root .

claude plugin tag .claude-plugin --dry-run
claude plugin tag .claude-plugin --push --remote origin

claude plugin tag が作る tag は {plugin-name}--v{version} 形式。既存の GitHub Release workflow が vX.Y.Z tag を前提にしている project では、plugin tag とは別に git tag -a v<new> を作る。plugin 配布の tag は claude plugin tag に任せ、GitHub Release 用 semver tag は release automation の互換 surface として扱う。

Verify Workflow Publish

Tag push 後、.github/workflows/release.yml が release を自動公開する。skill は以下で結果を verify する:

OWNER="$(git remote get-url origin | sed 's|.*github.com[:/]\([^/]*/[^/]*\)\.git|\1|')"
bash scripts/release-verify-publish.sh "v${NEW_VERSION}" "${OWNER}"

タイムアウト: 5 秒間隔 × 60 回 = 最大 5 分 polling。

• exit 0: PASS — draft=false 且つ assets 4 platform 揃って公開済
• exit 2: WARN — timeout (tag は push 済のため abort せず人間判断を促す)
• exit 3: ERROR — API error (権限/認証問題、手動調査が必要)

Verify は gh api 経由 (gh release prefix は CC runtime hard floor で deny されるため)。

--dry-run モード

Pre-Gate 全てを実行し、Confirmation Gate までの内容を表示するが、gate で止まり Post-Gate に進まない。

Claude plugin project の場合、dry-run でも python3 "${HARNESS_PLUGIN_ROOT}/scripts/check-release-version-sync.py" --root . と claude plugin tag .claude-plugin --dry-run を実行し、実際に作られる plugin tag 名と push 対象を表示する。ここで VERSION / package.json / .claude-plugin/plugin.json / .codex-plugin/plugin.json / .claude-plugin/marketplace.json の version surface が不一致または欠落していれば、dry-run の時点で止める。

環境変数

プロジェクトごとの調整に使用:

CHANGELOG 書き方ルール

[Unreleased] セクションは必ず以下のいずれかのサブセクションを持つ:

## [Unreleased]

### Added       ← minor
### Changed     ← patch
### Deprecated  ← minor
### Removed     ← major
### Fixed       ← patch
### Security    ← patch
### Breaking Changes  ← major (Keep a Changelog 非標準だが一般的)

このスキルはこれらの見出しを機械的に解析するため、見出しの表記揺れ（### Fix / ### Bug Fixes 等）は認識できません。KaCL 標準の見出しを使用してください。

関連スキル

• harness-release-internal - 本体 claude-code-harness のリリース時に追加で走らせる harness 固有 preflight/finalization（配布対象外）
• harness-plan - Plans.md 管理
• harness-review - リリース前のコードレビュー

設計思想

• 単一ゲート: ユーザーの判断タイミングは 1 回だけ。mini-confirmation を挟むとラバースタンプ化して意味を失う
• 事前に全て描く: Post-Gate に入ってからの「考え直し」を禁ずる。Gate 前に全 draft を揃える
• main 反映が完了条件: release tag / GitHub Release は default branch 反映後にだけ作る。branch-only release は未完了として扱う
• 失敗は transparent: 途中で失敗したら自動ロールバックは試みず、ユーザーに現状を提示して判断させる
• プロジェクト非依存: VERSION file 形式、mirror、residue check など特定環境の前提を持たない。本体 harness 固有の処理は harness-release-internal に分離

Harness Review

Harness の統合レビュースキル。 この SKILL.md は薄い dispatcher であり、詳細な品質基準は references/ を読む。

if $ARGUMENTS == "": → 「今までの作業のレビュー」と解釈し、Review target detection を実行する → review target が 1 つに確定できる場合だけ自動開始する → review target が不明または複数候補の場合は AskUserQuestion で選択肢を出し、認識を揃えてから開始する

Output Contract (P35: 「止まったように見える」UX 対策)

skill 結論時の output の 最後の 1 行は必ず P35 footer を含め、footer は本文 (user-facing prose) と同じ言語で出力する（言語解決は既存の言語ルールに従い、footer 契約は言語を再定義しない）。これは <local-command-stdout> 経由の表示で user が「止まった」と感じる UX 問題への明示的な instruction (patterns.md P35) で、意図は言語に依存しないため literal は言語ごとに切り替える (#208):

• ja: ↑この結果は Claude が要約します。Enter キーで次へ進むか、新規 prompt で別の指示を出してください。
• en: ↑Claude will summarize this result. Press Enter to continue, or send a new prompt for a different instruction.
• その他の言語: 同じ意味の 1 行を本文と同じ言語で出力する

Dispatcher Contract

この skill の責務は review 判定だけ。 commit / push / release は既定では行わない。

• review default read-only boundary: 既定は read-only。APPROVE でも自動 commit しない
• Do not push just to review: review 目的だけで push しない
• commit が必要な場合は、ユーザー明示依頼、harness-work、または harness-release の Work Commit Gate に委譲する
• --commit-on-approve のような明示 opt-in が設計されるまで、この skill 単体の default side effect は禁止

Quick Reference

Mode Decision

引数から実行 mode を決定し、必要な references/ を選択ロードする。

quick と codex-closeout は軽量 path。 小さな dirty change、single commit、PR branch の closeout を速く見る。 品質 gate を捨てるものではない。

Cursor Default ON

mode 判定時、明示 mode words (plan, scope, full) と明示フラグを先に確定する。no-arg / code review の場合だけ helper root を解決して resolver を 1 回だけ実行し、resolver 不在時は claude とみなす。

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
if [ -x "${HARNESS_PLUGIN_ROOT:-}/scripts/resolve-impl-backend.sh" ]; then resolved_backend="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role reviewer)"; else resolved_backend="claude"; fi

no-arg / code review で結果が cursor の場合は --cursor と同じ cursor-second-opinion を追加するが、core review gates (references/code-review.md, references/governance.md) は必ず先に読み、Cursor reference は additive にだけ扱う。primary verdict は Opus/brain 側で維持し、cursor は dual_review.cursor_verdict の advisory に限る。plan / scope など明示 mode word は resolver result より優先し、cursor default によって plan/scope references も code/governance references も置き換えない。 結果が claude / codex の場合は従来どおりで、review の primary 判定面は変えない。

Review Target Detection

REVIEW_AUTOSTART 契約: 引数なし ($ARGUMENTS == "") で呼ばれた場合、review / /review / /harness-review だけの入力を「今までの作業のレビュー」と解釈する。 Step 1 開始前の handshake 行として次を 1 行だけ出力する。

REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode}

REVIEW_TARGET_ASK 契約: bare 呼び出しで review target が不明または複数候補の場合、Step 1 に進む前に AskUserQuestion を 1 回だけ使い、候補を 2-3 個に絞って確認する。

• 候補は 1. working tree（未コミット変更のみ）、2. branch range（upstream または main/master から HEAD）、3. recent commits（clean tree 時の直近 1 commit / 直近 5 commits）の順で作る
• 複数候補が同時に成立する場合は REVIEW_TARGET_AMBIGUOUS: working_tree_and_branch_commits、clean tree かつ branch 差分がない場合は REVIEW_TARGET_AMBIGUOUS: clean_tree_no_branch_commits を 1 行出力してから AskUserQuestion を出す
• ユーザー回答後は REVIEW_TARGET_CONFIRMED: {choice} に続けて REVIEW_AUTOSTART 行を出力する
• AskUserQuestion の選択肢 literal・推奨 (Recommended) の付け方・各候補の比較範囲は references/code-review.md の Target Selection 節に従う

禁止:

• 「タスクが不明確です」と応答して停止する
• 「何をレビューすればよいですか」と自由記述で聞いて停止する
• host project の session-start rules を理由に auto-start を飛ばす
• target が曖昧なのに推測で範囲を広げる

Minimal Flow

1. mode を決める
2. 上記の Review Target Detection で対象と base ref を決める
3. 必要な reference だけ読む
4. 差分、untracked files、関連テスト、仕様正本、Plans.md を確認する
5. APPROVE / REQUEST_CHANGES / decision_needed を返す
6. REQUEST_CHANGES の場合は critical / major の修正方針と修正後再レビュー条件を示す

Review Governance Contract

詳細は references/governance.md。 ここでは最低限の合格ラインだけ固定する。

明確な合格ライン

APPROVE は次のすべてを満たす時だけ返す。

• critical / major が 0 件
• 仕様正本 (spec_path) または明示された spec_skip_reason と矛盾しない
• Plans.md の task / DoD / Depends と矛盾しない
• 既存テスト、既存 UX、既存 CLI、既存設定、既存 docs、配布 mirror のいずれにもデグレ証拠がない
• 検証証跡がある。APPROVE なのに evidence が空の出力は禁止
• TeamAgent Debate を実行した場合、反対意見が解消済み、または minor / recommendation として理由付きで格下げ済み

TeamAgent Debate

詳細は references/team-debate.md。 TeamAgent Debate は、異なる見解を read-only で衝突させる review pass。

Codex 環境で native TeamAgent が使えない場合でも、この gate を省略してはいけない。 codex-companion.sh review、利用可能な reviewer subagent、または明示的に分けた read-only manual-pass で同じ 2-4 視点を再現し、team_agent_mode に native / codex-companion / manual-pass / unavailable を記録する。

Code Review Summary

詳細は references/code-review.md。 通常 code review は次を見る。

• Security
• Performance
• Quality
• Accessibility
• AI Residuals
• Spec Alignment
• Plans Alignment
• Regression Safety
• TDD compliance

仕様正本 alignment check は必須。 spec_path がある場合は差分が仕様正本と矛盾しないか確認し、仕様正本が必要なのに無い場合は spec_skip_reason の妥当性を見る。 Plans.md alignment check とデグレ alignment check も同じ gate で扱う。

AI Residuals は scripts/review-ai-residuals.sh と scripts/review-weak-supervision-report.sh を優先して使う。 untracked も見る場合は --include-untracked を使う。 mockData, dummy, fake, localhost, TODO, FIXME, it.skip, test.skip, expect(true).toBe(true) などは候補であり、diff 文脈で severity を決める。 finding 段階は網羅優先。minor と判定した指摘も observations[] / recommendations[] に残し、gate は verdict 段階だけで行う（Opus 4.8 は low-severity の報告を絞る癖がある。references/code-review.md の Finding coverage 参照）。

TDD compliance check

TDD が required の task では skip_tdd_reason、red-log、focused tests の証跡を確認する。 証跡なしで APPROVE しない。

Quick / Codex Closeout Summary

詳細は references/codex-closeout.md。

軽量 path の原則:

• target selection を先に固定する
• Codex 指摘は advisory として扱い、実コードで確認してから採否を決める
• final report には review command / tests / accepted findings / rejected findings / clean result を含める
• stop-on-clean: clean result 後に、見栄えのためだけの追加 review をしない
• Codex が使えない場合は full manual pass に fallback し、失敗を成功扱いしない

helper:

bash scripts/harness-review-closeout.sh --dry-run --uncommitted
bash scripts/harness-review-closeout.sh --base origin/main --parallel-tests --test "bash tests/test-harness-review-governance.sh"
bash scripts/harness-review-closeout.sh --commit HEAD

Plan Review Summary

詳細は references/plan-review.md。 Plan Review は Plans.md の DoD / Depends / Status と実装順序を見る。 仕様正本が必要なタスクで spec_path がない場合は、decision_needed として止める。

Scope Review Summary

詳細は references/scope-review.md。 Scope Review は、要求・差分・テスト・docs の境界が膨らんでいないかを見る。 範囲変更が必要なら、推測で進めず AskUserQuestion または plan 更新に戻す。

Security / UI / Dual

• Security: references/security-profile.md
• UI rubric: references/ui-rubric.md
• high-res vision flow: references/vision-high-res-flow.md
• Dual review: references/dual-review.md

/ultrareview は Harness flow 内では既定で呼ばない。 Harness flow の review-result.v1、commit guard、sprint-contract との接続を置き換えないため。 claude ultrareview [target] --json は CI / script からの second-opinion としてだけ扱う。

PR Host Boundary

GitHub-first。 PR host 上の review 事実は GitHub を正とし、local diff は補助証拠として扱う。 ただし local uncommitted review は GitHub に push しない。

Output Contract

User-facing prose follows the explicit session or project language. If no language is configured, use English. Use Japanese only when i18n.language: ja, CLAUDE_CODE_HARNESS_LANG=ja, or an explicit session instruction requests Japanese output. Machine-readable values stay English.

Start with the result summary.

## Review Result

### {APPROVE | REQUEST_CHANGES | decision_needed} - {one-line conclusion}

Target: `{BASE_REF}..HEAD` or `{target}`
Verification: {commands run}

Strengths:
- ...

Findings:
- [severity] file:line - issue and evidence

Next Actions:
- ...

Details:
```json
{
  "schema_version": "review-result.v1",
  "verdict": "APPROVE | REQUEST_CHANGES",
  "decision_needed": {
    "required": false,
    "ask_tool": "AskUserQuestion"
  },
  "accepted_findings": [],
  "rejected_findings": [],
  "acceptance_bar": {
    "critical_major_zero": true,
    "spec_alignment": "pass | fail | not_applicable",
    "plans_alignment": "pass | fail | not_applicable",
    "regression_safety": "pass | fail | not_applicable",
    "verification_evidence": "pass | fail | not_applicable"
  },
  "team_debate": {
    "required": false,
    "mode": "native | codex-companion | manual-pass | unavailable",
    "team_agent_mode": "native | codex-companion | manual-pass | unavailable",
    "agents": [],
    "disagreements": []
  },
  "critical_issues": [],
  "major_issues": [],
  "observations": [],
  "recommendations": []
}
```

Persist Verdict (required for commit guard / #218 fix)

Output Contract の JSON ブロックを出力したら、verdict が .claude/state/review-result.json に 必ず永続化されるよう以下の step を最後に実行する。これを踏み忘れると、PreToolUse commit guard が 後続 git commit を APPROVE 無しでブロックする (harness-work step 10 と同じ pattern)。

# 1. 上の JSON ブロックを一時ファイルへ書き出す (verdict / acceptance_bar 等を実値で)
mkdir -p .claude/state
cat > .claude/state/tmp-review-result.json <<'JSON'
{ "schema_version": "review-result.v1", "verdict": "APPROVE", ... }
JSON

# 2. write-review-result.sh で正規化保存 (commit_hash は省略可)
bash "${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD}}/scripts/write-review-result.sh" \
  .claude/state/tmp-review-result.json \
  "$(git rev-parse --short HEAD 2>/dev/null || true)"

# 3. 一時ファイル削除
rm -f .claude/state/tmp-review-result.json

verdict が REQUEST_CHANGES でも保存する (commit guard は APPROVE のみ通過させ、REQUEST_CHANGES は履歴として残す)。 harness-release の Review Gate から委譲された場合も同じ step を踏む。

reviewer subagent は read-only (allowed-tools: Read, Grep, Glob) のため、上記 write 操作は orchestrator (skill を呼んだ main agent) が行う。

Codex Environment

Codex 環境では使える tool が異なる。 それでも、合格ライン、仕様正本、Plans.md、デグレ、修正後再レビュー、AskUserQuestion / decision_needed.v1 の契約は同じ。

Related Skills

• harness-work: REQUEST_CHANGES 後の修正実行
• harness-plan: plan / scope / spec の更新
• harness-release: review 済み work の commit / release

Harness Setup

Harness の統合セットアップスキル。 以下の旧スキルを統合:

• setup — 統合セットアップハブ
• harness-init — プロジェクト初期化
• harness-update — Harness アップデート
• maintenance — ファイル整理・クリーンアップ

Quick Reference

Built-in slash discovery (CC 2.1.108+): /init のような built-in slash command も発見される。 Harness 固有の bootstrap が必要な時だけ /harness-setup init と使い分ける。

Claude Code setup guidance (CC 2.1.120+): MCP alwaysLoad、${CLAUDE_EFFORT}、claude plugin prune、claude project purge、 ANTHROPIC_BEDROCK_SERVICE_TIER、claude_code.skill_activated.invocation_trigger、 Windows PowerShell primary shell、forked skills / subagents の deferred tools は docs/claude-code-setup-mcp-telemetry-provider.md を正本として扱う。

Codex plugin workflows: Codex /goal と Plans.md を二重管理しない。 plugin-bundled hooks は opt-in、external agent import は ownership 明記、 MultiAgentV2 / agents.max_threads = 8 は上限として扱い、 sticky environments / app-server artifacts は safe default を優先する。 Codex 0.130.0 stable の codex remote-control、large thread pagination、 selected-environment view_image、live app-server config refresh、 accurate turn diffs、plugin details bundled hooks、sharing discoverability controls は docs/codex-plugin-workflows-policy.md を正本として扱う。 詳細は docs/codex-plugin-workflows-policy.md を参照。

サブコマンド詳細

init — プロジェクト初期化

新規プロジェクトに Harness を導入する。

生成ファイル:

project/
├── CLAUDE.md            # プロジェクト設定
├── Plans.md             # タスク管理（空テンプレート）
├── .claude/
│   ├── settings.json    # Claude Code 設定
│   └── hooks.json       # フック設定（Go バイナリ）
└── hooks/
    ├── pre-tool.sh      # 薄いシム（→ core/src/index.ts）
    └── post-tool.sh     # 薄いシム（→ core/src/index.ts）

フロー:

1. プロジェクト種別を検出（Node.js/Python/Go/Rust/その他）
2. 最小限の CLAUDE.md を生成
3. Plans.md テンプレートを生成
4. hooks.json を配置
5. Go バイナリ検証: harness version でバイナリが利用可能か確認（v4.0 以降 Node.js 不要）
6. プラグインファイル同期: harness sync で .claude-plugin/ 配下のファイルを最新に同期。harness.toml が無く sync が失敗する場合は先に harness init を実行する（Setup hook 導入前にブートストラップされたプロジェクトの復旧経路）
7. ヘルスチェック: harness doctor で全チェック項目をパス。問題があれば修正案を提示

Go バイナリ検証

# バイナリの存在と動作を確認
harness version
# 例: harness v4.0.0 (go1.22.0, darwin/arm64)

v4.0 以降、Harness のコアエンジンは Go バイナリに移行した。 Node.js は不要。バイナリは bin/harness（または PATH 上の harness）を使用する。

プラグインファイル同期

# .claude-plugin/ 配下のファイルを最新に同期
harness sync

# 同期内容の確認のみ（変更なし）
harness sync --dry-run

harness sync は skills/ の SSOT から各 mirror（codex/.codex/skills/、opencode/skills/）へ 変更を伝播させる。init 後に必ず実行すること。

ヘルスチェック

# 全チェック項目を実行
harness doctor

harness doctor は以下を確認する:

問題が検出された場合は修正コマンドを提示する。

ci — CI/CD 設定

GitHub Actions ワークフローを設定する。

# .github/workflows/ci.yml 生成例
name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

codex — Codex CLI 設定

# インストール確認（Codex CLI は Node.js ベース。Harness 本体とは別物）
which codex || npm install -g @openai/codex

# タイムアウトコマンド確認（macOS）
TIMEOUT=$(command -v timeout || command -v gtimeout || echo "")
# macOS の場合: brew install coreutils

注意: Harness v4.0 本体（harness コマンド）は Node.js 不要の Go バイナリ。 Codex CLI（codex コマンド）は別ツールであり、引き続き Node.js が必要。

Codex provider / model metadata policy (0.123.0+ / 0.130.0)

Codex 0.123.0 以降の provider / model guidance と、Codex 0.130.0 stable の Bedrock aws login guidance は docs/codex-provider-setup-policy.md を正本として扱う。

要点:

• Bedrock を使う場合は、Codex built-in provider の amazon-bedrock を使う。
• AWS profile は user / project の Codex config で [model_providers.amazon-bedrock.aws] に置く。
• AWS console-login credentials from aws login profiles は AWS 側の profile material として扱う。
• Harness は AWS credential、console-login cache、provider endpoint を書き込まない。
• Harness の配布用 Codex config には model = "gpt-5.4" を setup default として固定しない。
• Harness の配布用 Codex config には model_provider = "amazon-bedrock" も setup default として固定しない。
• gpt-5.4 は Codex 本体の current model metadata として扱い、古い gpt-5.2-codex などを推奨 sample として残さない。
• Claude Code 側の CLAUDE_CODE_USE_BEDROCK / ANTHROPIC_DEFAULT_* / modelOverrides guidance と、Codex の model_provider = "amazon-bedrock" は混ぜない。

Bedrock を使う user / project だけが、必要に応じて次を追加する:

model_provider = "amazon-bedrock"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"

Claude Code 側の provider / MCP / telemetry guidance は docs/claude-code-setup-mcp-telemetry-provider.md を参照する。 特に ANTHROPIC_BEDROCK_SERVICE_TIER は Bedrock 利用者の provider 環境だけで扱い、 Harness の plugin default / template / shared project settings には入れない。

Codex app-server / plugin workflow policy (0.130.0)

Codex 0.130.0 stable (rust-v0.130.0, published 2026-05-08T23:09:55Z) の app-server / plugin workflow guidance は docs/codex-plugin-workflows-policy.md を正本として扱う。

要点:

• codex remote-control は headless remotely controllable app-server の明示起動 entrypoint。Harness setup は remote-control defaults を config に書かない。
• App-server clients can page large threads。長い loop / Breezing transcript は必要な page 範囲を確認する。
• view_image は multi-environment session の selected environments 経由で file を解決できる。artifact report には environment / workdir を添える。
• Live app-server threads pick up config changes without restart。ただし secret / provider / hook policy の変更は diff と verification で扱う。
• Turn diffs stay accurate across apply_patch including partial failures。最終判断は git diff と tests で確認する。
• Plugin details now show bundled hooks。install / share 前に bundled hooks を確認し、Harness bundled hooks は opt-in のままにする。
• Plugin sharing exposes link metadata and discoverability controls。公開範囲と metadata は release surface として確認する。
• Configurable OpenTelemetry trace metadata は debugging / triage 補助に限定し、個人情報・顧客情報・secret を入れない。
• Built-in MCPs first-class runtime servers は Codex runtime owned surface として扱い、plugin-provided MCP と所有者を混ぜない。
• CODEX_HOME environments TOML provider は user-level environment source。選択 environment を報告し、write turn は one primary environment に固定する。
• Remove skills list extra roots に依存せず、Harness mirror install または [[skills.config]] path-based loading を明示する。

Codex MCP diagnostics / plugin loading (0.123.0+)

Codex 0.123.0 以降の MCP diagnostics / plugin MCP loading guidance は docs/codex-mcp-diagnostics.md を正本として扱う。

要点:

• Codex TUI では、普段は /mcp で軽量に server 状態だけ確認する。
• MCP server が見えない、resources が出ない、resource templates が読めない時だけ /mcp verbose を使う。
• /mcp verbose では diagnostics / resources / resource templates を確認する。
• plugin 内 .mcp.json は mcpServers 形式と top-level server map 形式の両方を受け取れる前提で案内する。
• 新規 plugin では共有しやすい mcpServers 形式を優先する。
• 既存 plugin が top-level server map 形式なら、Codex 側の loading 改善を利用し、不要な書き換えを避ける。
• Claude Code 側の claude mcp ...、.claude/mcp.json、hook type: "mcp_tool" guidance と混ぜない。

mcpServers 形式:

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

top-level server map 形式:

{
  "docs": {
    "command": "node",
    "args": ["server.js"]
  }
}

Codex sandbox / execution policy (0.123.0+)

Codex 0.123.0 以降の remote_sandbox_config と codex exec shared flags guidance は docs/codex-sandbox-execution-policy.md を正本として扱う。

要点:

• remote_sandbox_config は requirements.toml の host-specific sandbox policy として案内する。
• remote devbox / ephemeral CI runner / shared host のように、remote environment ごとの allowed_sandbox_modes を比較して決める。
• host matching は便利な分類だが、強い device authentication ではない。高リスク環境では broad wildcard を避ける。
• Harness の配布用 codex/.codex/config.toml には organization-specific な remote_sandbox_config を書かない。
• Codex 0.123.0 以降は codex exec が root-level shared flags を継承するため、wrapper 側で重複した --approval-policy / --sandbox pairs を追加しない。
• scripts/codex-companion.sh task --write が --sandbox workspace-write を付けるのは、Harness の「書き込みタスク」という意図を exec-local に変換しているためであり、root shared flags の重複転送ではない。
• scripts/codex/codex-exec-wrapper.sh の --full-auto は 53.2.4 では維持する。変更する場合は別 task で approval / sandbox behavior の回帰テストを追加する。

requirements example:

allowed_sandbox_modes = ["read-only"]

[[remote_sandbox_config]]
hostname_patterns = ["devbox-*.corp.example.com"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

使用パターン（公式プラグイン経由）:

bash scripts/codex-companion.sh task --write "タスク内容"
# または stdin 経由
cat /tmp/prompt.md | bash scripts/codex-companion.sh task --write

Cursor 実装バックエンド導入（脳 Opus / 体 composer）

Cursor を Harness の実装（worker）バックエンドとして使うための導入手順。 レビュー / advisor ロールは Opus に固定し、cursor バックエンドへ切り替えない（.claude/rules/cursor-cli-only.md の Role scope）。

1. AI 実行可（バックエンド選択の永続化）

set-impl-backend.sh でバックエンドを永続化する。Harness / AI がこのステップを実行できる。

# プロジェクトスコープ（このプロジェクトの env.local に書く）
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" cursor

# ユーザースコープ（全プロジェクト共通: ${HOME}/.config/claude-harness/impl-backend.env）
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --user cursor

# 現在解決されるバックエンドを表示して確認
bash "${HARNESS_PLUGIN_ROOT}/scripts/set-impl-backend.sh" --show

解決の優先順位: プロジェクト env.local がユーザースコープより優先される。

2. ユーザー手動（AI は編集不可。protected path + sandbox のため）

以下 3 ファイルは Edit/Write(.claude/settings*) deny と self-audit guard、および ~/.cursor/* が plugin write 対象外であるため Harness / AI が編集できない。ユーザー自身がターミナル / エディタで設定する。

• ~/.cursor/permissions.json: terminalAllowlist / mcpAllowlist を追加する。 テンプレートは .claude/rules/cursor-cli-only.md の ~/.cursor/permissions.json テンプレートを使う。 --force / Run Everything（--yolo）は使わない（Cursor 公式が "Never use"）。
• .cursorignore: secrets（.env, *.pem, *.key, .ssh, .aws, .git）を列挙する。 テンプレートは .claude/rules/cursor-cli-only.md の .cursorignore テンプレートを使う。
• ~/.claude/settings.json の sandbox（2 点）: (1) network.allowedDomains に *.cursor.sh を追加、 (2) 公式キー sandbox.filesystem.allowWrite に ~/.cursor を追加する（cursor-agent は実行時に ~/.cursor/projects/... と ~/.cursor/cli-config.json.tmp へ状態を書くため、未許可だと EPERM で失敗する）。⚠️ キー名は allowWrite: write という名前にすると未知キーとして 無視され設定が効かない（実測で確認）。~/ は sandbox 側で展開される（公式例 ["~/.kube"]）。 両方揃うと per-run の sandbox 無効化なしで実行できる。手順は docs/sandbox-allowlist-recipe.md の jq merge レシピと .claude/rules/cursor-cli-only.md の「Sandbox 要件」に従う。CC 完全再起動後に有効化される。

3. 境界（cursor は candidate のまま）

cursor バックエンドは candidate の位置づけ。安全性は Cursor の allowlist（best-effort、bypass 可能）ではなく、 専用 .git を持つ worktree での隔離実行 + Lead による diff レビュー + cherry-pick での本流取り込みで担保する。 cursor-agent の出力は Lead レビューまで untrusted として扱う。詳細は .claude/rules/cursor-cli-only.md を参照。

harness-mem — メモリ設定

Unified Harness Memory の設定を行う。

# メモリディレクトリ作成
mkdir -p .claude/agent-memory/claude-code-harness-worker
mkdir -p .claude/agent-memory/claude-code-harness-reviewer

# MEMORY.md テンプレート配置
cat > .claude/agent-memory/claude-code-harness-worker/MEMORY.md << 'EOF'
# Worker Agent Memory

## Project Context
[プロジェクト概要]

## Patterns
[学習パターン]
EOF

mirrors — 公開 skill bundle 同期

Windows の core.symlinks=false では repository symlink が通常ファイルになり、harness-* skill が command 一覧に出なくなることがあります。公開 bundle は実ディレクトリ mirror として同期します。

./scripts/sync-skill-mirrors.sh
./scripts/sync-skill-mirrors.sh --check

更新対象:

• skills/
• codex/.codex/skills/
• opencode/skills/

agents — エージェント設定

agents/ の3エージェント構成を設定する。

agents/
├── worker.md      # 実装担当（task-worker + codex-implementer + error-recovery）
└── reviewer.md    # レビュー担当（code-reviewer + plan-critic）

localize — ルールローカライズ

.claude/rules/ のルールを現プロジェクトに適応する。

# ルール一覧確認
ls .claude/rules/

# プロジェクト固有ルールの追加
cat >> .claude/rules/project-rules.md << 'EOF'
# Project-Specific Rules
[プロジェクト固有ルール]
EOF

Plugin インストール (v2.1.71+ Marketplace)

v2.1.71 で Marketplace の安定性が大幅に改善された。 Claude Code 2.1.117-2.1.118 以降の plugin / managed settings 方針は docs/plugin-managed-settings-policy.md を正本として扱う。

推奨インストール方式

# @ref 形式でバージョン固定（推奨）
claude plugin install owner/repo@v4.0.0

# 最新版
claude plugin install owner/repo

owner/repo@vX.X.X 形式を推奨。@ref パーサー修正により、タグ・ブランチ・コミットハッシュいずれも正確に解決される。

アップデート

claude plugin update owner/repo

v2.1.71 で update 時の merge conflict が修正され、安定したアップデートが可能になった。

その他の改善点

• MCP server 重複排除: 同一 MCP サーバーの多重登録を自動防止
• /plugin uninstall が settings.local.json を使用: ユーザーローカル設定に正確に反映

Managed marketplace / dependency policy (v2.1.117+)

企業利用で plugin marketplace を制御する場合は、Claude Code 本体の managed settings を使う。 Harness は独自の marketplace resolver や dependency resolver を重ねない。

DISABLE_AUTOUPDATER は自動更新を止める。 DISABLE_UPDATES は手動 claude update まで止めるため、企業の固定バージョン運用向け。 Harness の project default にはどちらも入れず、必要な組織が managed settings または端末管理で設定する。

依存関係が欠けた場合は、まず Claude Code の /plugin Errors、/doctor、claude plugin list --json を確認する。 marketplace 未登録が原因なら /plugin marketplace add または claude plugin marketplace add で登録し、本体の auto-resolve に任せる。

Maintenance — ファイル整理

定期メンテナンスタスク:

関連スキル

• harness-plan — セットアップ後にプロジェクト計画を作成
• harness-work — セットアップ後にタスクを実行
• harness-review — セットアップ設定をレビュー

Harness Sync

Plans.md と実装状況を照合し、差分を検出・更新する。 旧 sync-status および harness-plan sync サブコマンドの独立版。

Quick Reference

オプション

Step 0: Plans.md 検証

Plans.md の存在とフォーマットを確認する。問題がある場合は即座に案内して停止する。 複数 Plans.md がある repo では、対象 plan を scripts/plan-registry.sh list または --plan NAME で確認してから読む。

Step 1: 現状収集（並列）

# Plans.md の状態
cat Plans.md

# Git 変更状態
git status
git diff --stat HEAD~3

# 直近コミット履歴
git log --oneline -10

# エージェントトレース（直近の編集ファイル）
tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | jq -r '.files[].path' | sort -u

Step 1.5: Agent Trace 分析

Agent Trace から直近の編集履歴を取得し、Plans.md のタスクと照合する:

# 直近の編集ファイル一覧
RECENT_FILES=$(tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.files[].path' | sort -u)

# プロジェクト情報
PROJECT=$(tail -1 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.metadata.project')

照合ポイント:

Step 2: 差分検出

Step 3: Plans.md 更新提案

差分が検出された場合、提案して実行する:

Plans.md 更新が必要です

| Task | 現在 | 変更後 | 理由 |
|------|------|--------|------|
| XX   | cc:WIP | cc:完了 | コミット済み |
| YY   | cc:TODO | cc:WIP | ファイル編集済み |

更新しますか？ (yes / no)

Step 4: 進捗サマリー出力

## 進捗サマリー

**プロジェクト**: {{project_name}}

| ステータス | 件数 |
|----------|------|
| 未着手 (cc:TODO) | {{count}} |
| 作業中 (cc:WIP) | {{count}} |
| 完了 (cc:完了) | {{count}} |
| PM確認済 (pm:確認済) | {{count}} |

**進捗率**: {{percent}}%

### 直近の編集ファイル (Agent Trace)
- {{file1}}
- {{file2}}

Step 4.5: スナップショット保存（--snapshot 指定時）

--snapshot が指定された場合、現在の進捗状態を時刻付きスナップショットとして保存する。

保存先

.claude/state/snapshots/ ディレクトリに JSON 形式で保存:

SNAPSHOT_DIR="${PROJECT_ROOT}/.claude/state/snapshots"
mkdir -p "${SNAPSHOT_DIR}"
SNAPSHOT_FILE="${SNAPSHOT_DIR}/progress-$(date -u +%Y%m%dT%H%M%SZ).json"

スナップショット内容

{
  "timestamp": "2026-03-08T10:30:00Z",
  "phase": "Phase 26",
  "progress": {
    "total": 16,
    "todo": 5,
    "wip": 3,
    "done": 6,
    "confirmed": 2
  },
  "progress_rate": 50,
  "recent_commits": ["abc1234 feat: ...", "def5678 fix: ..."],
  "recent_files": ["skills/harness-work/SKILL.md", "..."],
  "notes": ""
}

差分比較

前回スナップショットが存在する場合、差分を表示:

## スナップショット差分

| 指標 | 前回 ({{prev_time}}) | 今回 | 変化 |
|------|---------------------|------|------|
| 進捗率 | {{prev}}% | {{current}}% | +{{diff}}%pt |
| 完了タスク | {{prev_done}} | {{current_done}} | +{{diff_done}} |
| WIP タスク | {{prev_wip}} | {{current_wip}} | {{diff_wip}} |

設計意図: snapshot はユーザーが「今の状態を記録しておきたい」と思った時に手動で使う。 breezing 中の自動的なプログレスフィード（26.2.3）とは別の機能。

Step 5: 次のアクション提案

次にやること

**優先 1**: {{タスク}}
- 理由: {{依頼中 / アンブロック待ち}}

**推奨**: harness-work, harness-review

異常検知

Step 6: レトロスペクティブ（デフォルト ON）

cc:完了 タスクが 1 件以上あれば自動的に振り返りを実行する。 --no-retro で明示的にスキップ可能。

Step R1: 完了タスク収集

# Plans.md から cc:完了 / pm:確認済 のタスクを抽出
grep -E 'cc:完了|pm:確認済' Plans.md

# 直近の完了コミット履歴
git log --oneline --since="7 days ago"

# 変更規模
git diff --stat HEAD~10

Step R2: 振り返り 4 項目

Step R3: 振り返りサマリー出力

## 振り返りサマリー

**期間**: {{start_date}} 〜 {{end_date}}

| 指標 | 値 |
|------|-----|
| 完了タスク | {{count}} 件 |
| ブロック発生 | {{blocked_count}} 件 |
| スコープ変動 | +{{added}} / -{{removed}} 件 |
| 見積もり精度 | 想定 {{est}} ファイル → 実際 {{actual}} ファイル |

### 学び
- {{1-2 行の学び}}

### 次に活かすこと
- {{1-2 行の改善アクション}}

Step R4: harness-mem への記録

振り返り結果を harness-mem に記録し、次回の create 時に参照できるようにする。 記録先: .claude/agent-memory/ 配下の該当エージェントメモリ。

関連スキル

• harness-plan — 計画作成・タスク管理
• harness-work — タスク実装
• harness-review — コードレビュー

Harness Work

Harness の統合実行スキル。 以下の旧スキルを統合:

• work — Plans.md タスクの実装（スコープ自動判断）
• impl — 機能実装（タスクベース）
• breezing — チームフル自動実行
• parallel-workflows — 並列ワークフロー最適化
• ci — CI 失敗時の復旧

Quick Reference

Execution Mode Auto Selection（フラグなし時の自動判定）

明示的なモードフラグ（--parallel, --breezing, --codex）がない場合、 対象タスク数に応じて最適なモードを自動選択する:

ルール

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 から駆動しても同じに振る舞う。

解決手順

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 を参照。

オプション

Progressive Disclosure

まずこの本文で入口、自動選択、停止条件だけを確認する。 詳細は必要になった時だけ読む。

重要停止条件

• 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 を選ぶ方式に統一する。

多要素スコアリング

タスク着手時に以下のスコアを合算する。

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 引き上げの判断材料にする。

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 件時の自動選択）

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 を含める
2. タスクを cc:WIP に更新
3. 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 に残す
4. node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" <task-id> で sprint-contract.json を生成
5. Reviewer 観点の追記を bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で approved を確認
6. 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 回
7. 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 に渡す
8. /simplify で Auto-Refinement（--no-simplify で省略可）
9. 自動レビューステージ（「レビューループ」参照）:
   • 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 だけでは完了を確定しない
10. bash "${HARNESS_PLUGIN_ROOT}/scripts/write-review-result.sh" で review artifact を正規化して保存（browser profile は --browser-result を渡し、browser_verdict == PENDING_BROWSER の時は static verdict を採用）
11. git commit で自動コミット（--no-commit で省略可）
12. タスクを cc:完了 に更新（commit hash 付与）

• git log --oneline -1 で直近の commit hash（短縮形 7 文字）を取得
• Plans.md の Status を cc:完了 [a1b2c3d] 形式で更新
• commit がない場合（--no-commit 時）は hash なしで cc:完了 のみ

13. リッチ完了報告（「完了報告フォーマット」参照）
14. 失敗時の自動再計画（テスト/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 にタスクを委託する。

# タスク委託（書き込み可能・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・構造化出力を提供する。 結果を検証し、品質基準を満たさない場合は自力で修正。

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（準備）:

1. Plans.md を読み込み、対象タスクを特定
2. 依存グラフを解析し、実行順序を決定（Depends カラム）
3. 各タスクの仕様正本 preflight を行い、必要なら docs/spec/00-project-spec.md または既存 spec を実装前に更新
4. 各タスクの effort スコアリング（effort tier 判定 — high/xhigh）
5. node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" で sprint-contract.json を生成
6. 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.内容}")

Advisor Protocol（全モード共通）

Advisor は「実装者」でも「レビュー担当」でもない。 迷った時だけ、実行役が次の一歩を決めるための相談役として入る。

1. Worker は generic な subagent を増やさず、必要時だけ advisor-request.v1 を返す
2. Lead が advisor を 1 回だけ呼ぶ
3. Advisor は PLAN / CORRECTION / STOP のどれかを返す
4. Lead はその advice を同じ Worker に返して続行させる
5. 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 などの検証コマンド
• browser_validation: browser reviewer が残すべき UI フロー検証項目
• browser_mode: scripted または exploratory
• route: browser reviewer が playwright / agent-browser / chrome-devtools のどれを使うか
• risk_flags: needs-spike, security-sensitive, ux-regression など
• reviewer_profile: static, runtime, browser

Phase C: Post-delegate（統合・報告）:

1. 全タスクの commit log を集計
2. リッチ完了報告（「完了報告フォーマット」の Breezing テンプレート）を出力
3. Plans.md の最終確認（全タスク cc:完了 になっているか）

CI 失敗時の対応

CI が失敗した場合:

1. ログを確認してエラーを特定
2. 修正を実施
3. 同一原因で 3 回失敗したら自動修正ループを停止
4. 失敗ログ・試みた修正・残る論点をまとめてエスカレーション

失敗タスクの自動再チケット化

タスク完了後にテスト/CI が失敗した場合、修正タスク案を自動生成し、承認後に Plans.md へ反映する:

トリガー条件

修正タスクの自動生成

1. 失敗原因を分類（syntax_error / import_error / type_error / assertion_error / timeout / runtime_error）
2. .claude/state/pending-fix-proposals.jsonl に修正タスク案を保存:
   • 番号: 元タスク番号 + .fix サフィックス（例: 26.1.fix）
   • 内容: fix: [元タスク名] - [失敗原因カテゴリ]
   • DoD: テスト/CI が通ること
   • Depends: 元タスク番号
3. ユーザーが approve fix <task_id> を送ると Plans.md に cc:TODO で追加
4. 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 には影響しない。

重要: minor / recommendation のみの場合は 必ず APPROVE を返すこと。 「あったほうが良い改善」は REQUEST_CHANGES の理由にならない。

Codex exec レビュー（公式プラグイン経由）

タスク開始時の 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 形式への変換ルール:

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}" 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 参照）:

1. Worker が worktree 内で実装・commit → Lead に結果返却
2. Lead が Codex exec でレビュー（優先）/ Reviewer agent（フォールバック）
3. REQUEST_CHANGES → Lead が send_input で Worker に修正指示し、wait_agent で再応答を待つ → Worker が amend
4. 修正後、再レビュー（MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3 回まで）
5. APPROVE → Lead が trunk（デフォルトブランチ）に cherry-pick → Plans.md を 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}           │
└─────────────────────────────────────────────┘

生成ルール

1. 何をしたか: git diff --stat HEAD~1 と commit message から自動抽出。技術用語は最小限にし、動詞で始める
2. 何が変わるか: タスクの「内容」と「DoD」から Before/After を推論。ユーザー体験の変化を重視
3. 変更ファイル: git diff --name-only HEAD~1 から取得。5 ファイル超は省略して件数表示
4. 残りの課題: Plans.md の cc:TODO / cc:WIP タスクを一覧表示。Plans.md に記載済みかどうかを明示
5. review: レビュー結果（APPROVE / REQUEST_CHANGES → APPROVE）を表示

Parallel モードでの報告

• 1 タスク（--parallel 強制時）: Solo テンプレートを使用
• 複数タスク: Breezing 集約テンプレートを使用（下記参照）

Breezing モードでの報告

全タスク完了後にまとめて出力。各タスクは簡略版（何をしたか + 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 — バージョンバンプ・リリース

Maintenance

散らかったファイルを整頓する単一目的スキル。auto-cleanup-hook が警告を出した時、 または定期的な家事として呼び出す。

前提: 破壊的操作（アーカイブ移動・行削除）の前に Plans.md / session-log.md の 重要情報が SSOT (decisions.md / patterns.md) に昇格済みか確認する。 未同期なら /memory sync を先に走らせる。

Quick Reference

--dry-run を付けると何をするかだけ列挙して実行しない。自由記述の指示（例: 「古いアーカイブも消して」「この session-log だけ残して」）は Step 1 で 受け付けて Step 2 以降の処理パラメータに反映する。

実行手順

1. ユーザー指示のパース: サブコマンド + 自由記述（除外対象、保存先、日数閾値）を抽出
2. SSOT 同期チェック: .claude/state/.ssot-synced-this-session が無ければ /memory sync を促す（Plans.md を触る場合のみ必須）
3. 参照ファイルを開く: ${CLAUDE_SKILL_DIR}/references/cleanup.md を読み対応セクションを実行
4. Before/After を報告: 行数と削除件数を表示して完了

サブコマンド詳細

対象ごとの実行手順・閾値・アーカイブ先は cleanup.md を参照。

auto-cleanup-hook との連携

PostToolUse hook (scripts/auto-cleanup-hook.sh / Go 版 auto_cleanup_hook.go) は Plans.md・session-log.md・CLAUDE.md の行数超過を検知すると /maintenance で古いタスクをアーカイブすることを推奨します と feedback を返す。 この警告を見たら該当サブコマンドを実行する。

注意事項

• 進行中タスクは動かさない: cc:WIP, pm:依頼中, cursor:依頼中 はアーカイブ対象外
• アーカイブ先ディレクトリは固定: .claude/memory/archive/ — 別の場所に移すときは ユーザーに確認する
• バックアップ: 200 行超のファイルを編集する前に cp <file> <file>.bak.$(date +%s) で ローカルバックアップを取る
• CLAUDE.md は警告のみ: 自動編集しない。分割提案だけ出す

関連スキル

• memory — Plans.md 整理前の SSOT 昇格（decisions.md / patterns.md 更新）
• harness-setup — セットアップ直後の定期メンテは harness-setup 経由でも呼べる
• session-init — セッション開始時のメンテ推奨通知を制御

Memory Skills

メモリとSSOT管理を担当するスキル群です。

機能詳細

Unified Harness Memory（共通DB）

Claude Code / Codex / OpenCode 共通の記録・検索は harness_mem_* MCP を優先する。

• 検索: harness_mem_search, harness_mem_timeline, harness_mem_get_observations
• 注入: harness_mem_resume_pack
• 記録: harness_mem_record_checkpoint, harness_mem_finalize_session, harness_mem_record_event

Claude Code 自動メモリとの関係（D22）

Harness の SSOT メモリ（Layer 2）は Claude Code の自動メモリ（Layer 1）と共存します。 自動メモリは汎用的な学習を暗黙的に記録し、SSOT はプロジェクト固有の意思決定を明示的に管理します。 Layer 1 の知見がプロジェクト全体に重要な場合、/memory ssot で Layer 2 に昇格してください。

詳細: D22: 3層メモリアーキテクチャ

実行手順

1. ユーザーのリクエストを分類
2. 上記の「機能詳細」から適切な参照ファイルを読む
3. その内容に従って実行

SSOT昇格

メモリシステム（Claude-mem / Serena）から重要な学びをSSOTに永続化します。

• "Save what we learned" → references/sync-ssot-from-memory.md
• "Promote decisions to SSOT" → references/sync-ssot-from-memory.md

NotebookLM Skill

ドキュメント生成を担当するスキル群です。

機能詳細

実行手順

1. ユーザーのリクエストを分類
2. 上記の「機能詳細」から適切な参照ファイルを読む
3. その内容に従って生成

🔧 PDF ページ範囲読み取り（Claude Code 2.1.49+）

大型 PDF を効率的に扱うための機能です。

ページ範囲指定で読み取り

// ページ範囲指定で読み取り
Read({ file_path: "docs/spec.pdf", pages: "1-10" })

// 目次だけ確認
Read({ file_path: "docs/manual.pdf", pages: "1-3" })

// 特定のセクションのみ
Read({ file_path: "docs/api-reference.pdf", pages: "25-45" })

ユースケース別の推奨アプローチ

NotebookLM YAML 生成時の活用例

大型PDF（300ページの技術仕様書）からYAMLを生成する場合：

1. **目次を読む**（1-5ページ）
   Read({ file_path: "spec.pdf", pages: "1-5" })
   → 章立てを把握

2. **各章の冒頭を読む**（各章の最初の2ページ）
   Read({ file_path: "spec.pdf", pages: "10-11" })  // 第1章
   Read({ file_path: "spec.pdf", pages: "45-46" })  // 第2章
   → 各章の概要を把握

3. **重要セクションを精読**
   Read({ file_path: "spec.pdf", pages: "78-95" })  // APIリファレンス
   → 詳細な内容を抽出

この方法で、300ページすべてを読むことなく効率的にYAMLを生成できます。

ベストプラクティス

従来の方法との比較

→ 90%のトークン削減と処理時間短縮が可能

Principles Skills

開発原則とガイドラインを提供するスキル群です。

機能詳細

実行手順

1. ユーザーのリクエストを分類
2. 上記の「機能詳細」から適切な参照ファイルを読む
3. その内容を参照・適用

Session Control Skill

/work の --resume / --fork フラグに応じてセッション状態を切り替える。

機能詳細

実行手順

1. workflow から渡された変数を確認
2. scripts/session-control.sh を適切な引数で実行
3. session.json と session.events.jsonl の更新を確認

Session Init Skill

セッション開始時の環境確認と現在のタスク状況把握を行うスキル。

呼び出し条件

このスキルは session / SessionStart 系フローから内部的に呼び出します。 ユーザー向けの入口は /session または通常のセッション開始フローです。

旧トリガーフレーズ:

• 「セッション開始」
• 「作業開始」
• 「今日の作業を始める」
• 「状況を確認して」
• 「何をすればいい？」
• "start session"
• "what should I work on?"

概要

Session Init スキルは、Claude Code セッション開始時に自動的に以下を確認します：

1. Git 状態: 現在のブランチ、未コミットの変更
2. Plans.md: 進行中タスク、依頼されたタスク
3. AGENTS.md: 役割分担、禁止事項の確認
4. 前回セッション: 引き継ぎ事項の確認
5. 最新 snapshot: 進捗スナップショットの要約と前回差分

実行手順

Step 0: ファイル状態チェック（自動整理）

セッション開始前にファイルサイズをチェック：

# Plans.md の行数チェック
if [ -f "Plans.md" ]; then
  lines=$(wc -l < Plans.md)
  if [ "$lines" -gt 200 ]; then
    echo "⚠️ Plans.md が ${lines} 行です。「整理して」で整理を推奨"
  fi
fi

# session-log.md の行数チェック
if [ -f ".claude/memory/session-log.md" ]; then
  lines=$(wc -l < .claude/memory/session-log.md)
  if [ "$lines" -gt 500 ]; then
    echo "⚠️ session-log.md が ${lines} 行です。「セッションログを整理して」で整理を推奨"
  fi
fi

整理が必要な場合は提案を表示（作業には影響しない）。

Step 0.5: 旧ローカルメモリ互換の扱い（任意）

現在の標準は Step 0.7 の Unified Harness Memory です。 旧ローカルメモリ互換の確認は原則不要で、特別な移行確認が必要な場合だけ個別に参照します。

注: 通常運用ではこのステップをスキップし、共通DB の Resume Pack を唯一の再開導線として扱います。

Step 0.7: Unified Harness Memory Resume Pack（必須）

Codex / Claude / OpenCode 共通DB（~/.harness-mem/harness-mem.db）から再開文脈を取得する。

必須呼び出し:

harness_mem_resume_pack(project, session_id?, limit=5, include_private=false)

運用ルール:

• project は必ず現在プロジェクト名を指定
• session_id は $CLAUDE_SESSION_ID → .claude/state/session.json の .session_id の順で取得する
• harness_mem_sessions_list(project, limit=1) の先頭利用は read-only（resume確認）に限定し、record_checkpoint / finalize_session での書き込みには使わない
• 取得結果はセッション開始時コンテキストに注入
• 取得失敗時は harness_mem_health() で daemon 状態を確認し、失敗を明示して続行
• 復旧は scripts/harness-memd doctor → scripts/harness-memd cleanup-stale → scripts/harness-memd start の順で行う

Step 1: 環境確認

以下を並列で実行：

# Git状態
git status -sb
git log --oneline -3

# Plans.md
cat Plans.md 2>/dev/null || echo "Plans.md not found"

# AGENTS.md の要点
head -50 AGENTS.md 2>/dev/null || echo "AGENTS.md not found"

Step 2: タスク状況の把握

Plans.md から以下を抽出：

• cc:WIP - 前回から継続中のタスク
• pm:依頼中 - PM から新規依頼されたタスク（互換: cursor:依頼中）
• cc:TODO - 未着手だが割り当て済みのタスク

Step 3: 状況レポートの出力

## 🚀 セッション開始

**日時**: {{YYYY-MM-DD HH:MM}}
**ブランチ**: {{branch}}
**セッションID**: ${CLAUDE_SESSION_ID}

---

### 📋 今日のタスク

**優先タスク**:
- {{pm:依頼中（互換: cursor:依頼中） または cc:WIP のタスク}}

**その他のタスク**:
- {{cc:TODO のタスク一覧}}

---

### ⚠️ 注意事項

{{AGENTS.md からの重要な制約・禁止事項}}

---

**作業を開始しますか？**

出力フォーマット

セッション開始時は、以下の情報を簡潔に提示：

関連コマンド

• /work - タスク実行（並列実行対応）
• /sync-status - Plans.md の進捗サマリー
• /maintenance - ファイルの自動整理

注意事項

• AGENTS.md を必ず確認: 役割分担を把握してから作業開始
• Plans.md が無い場合: /harness-init を案内
• 前回の作業が中断している場合: 継続するか確認

Session Memory Skill

セッション間の学習と記憶を管理するスキル。 過去の作業内容、決定事項、学んだパターンを記録・参照します。

トリガーフレーズ

このスキルは以下のフレーズで自動起動します：

• 「前回何をした？」「前回の続きから」
• 「履歴を見せて」「過去の作業」
• 「このプロジェクトについて教えて」
• "what did we do last time?", "continue from before"

概要

このスキルは .claude/memory/ に作業履歴を保存し、 セッション間での知識の継続を実現します。

あわせて、重要な情報は「どこに残すべきか」を明確にします（詳細: docs/MEMORY_POLICY.md）。

メモリ構造

.claude/
├── memory/
│   ├── session-log.md      # セッションごとのログ
│   ├── decisions.md        # 重要な決定事項
│   ├── patterns.md         # 学んだパターン
│   └── context.json        # プロジェクトコンテキスト
└── state/
    └── agent-trace.jsonl   # Agent Trace（ツール実行履歴）

推奨運用（SSOT/ローカル分離）

• SSOT（共有推奨）: decisions.md / patterns.md
  • 「決定（Why）」と「再利用できる解法（How）」を集約する
  • 各エントリは タイトル + タグ（例: #decision #db）を付け、先頭に Index を置く
• ローカル推奨: session-log.md / context.json / .claude/state/
  • ノイズ/肥大化しやすいため、基本は Git 管理しない（必要なら個別に判断）

自動記録される情報

session-log.md

各セッション記録には、実行環境から取得できるセッションIDを付与します。 Claude Code では ${CLAUDE_SESSION_ID} を優先し、Codex では Codex runtime が渡す session / thread ID を優先します。 どちらも取得できない場合は .claude/state/session.json の .session_id を読み、最後の fallback として日時ベースのIDを生成します。 これにより、セッション間のトレーサビリティが向上します。

## セッション: 2024-01-15 14:30 (session: abc123def)

### 実行したタスク
- [x] ユーザー認証機能の実装
- [x] ログインページの作成

### 生成したファイル
- src/lib/auth.ts
- src/app/login/page.tsx

### 重要な決定
- 認証方式: Supabase Auth を採用

### 次回への引き継ぎ
- ログアウト機能が未実装
- パスワードリセットも必要

Note: ${CLAUDE_SESSION_ID} は Claude Code が自動設定する環境変数です。 Codex 側ではこの変数が存在しない場合があるため、固定前提にせず、Codex runtime の session / thread ID または .claude/state/session.json を使います。

decisions.md

## 技術選定

| 日付 | 決定事項 | 理由 |
|------|---------|------|
| 2024-01-15 | Supabase Auth | 無料枠あり、セットアップ簡単 |
| 2024-01-14 | Next.js App Router | 最新のベストプラクティス |

## アーキテクチャ

- コンポーネント: `src/components/`
- ユーティリティ: `src/lib/`
- 型定義: `src/types/`

patterns.md

## このプロジェクトのパターン

### コンポーネント命名
- PascalCase
- 例: `UserProfile.tsx`, `LoginForm.tsx`

### API エンドポイント
- `/api/v1/` プレフィックス
- RESTful 設計

### エラーハンドリング
- try-catch で囲む
- エラーメッセージは日本語

context.json

{
  "project_name": "my-blog",
  "created_at": "2024-01-14",
  "stack": {
    "frontend": "next.js",
    "backend": "next-api",
    "database": "supabase",
    "styling": "tailwind"
  },
  "current_phase": "フェーズ2: コア機能",
  "last_session": "2024-01-15T14:30:00Z"
}

処理フロー

セッション開始時

1. .claude/memory/context.json を読み込み
2. 前回のセッションログを確認
3. Agent Trace から直近の編集履歴を取得
4. 未完了タスクを特定
5. コンテキストサマリーを生成

Agent Trace 活用:

# 前回の編集ファイル一覧を取得
tail -50 .claude/state/agent-trace.jsonl | jq -r '.files[].path' | sort -u

# プロジェクト情報を取得
tail -1 .claude/state/agent-trace.jsonl | jq '.metadata'

セッション中

1. 重要な決定を decisions.md に記録
2. 新しいパターンを patterns.md に追加
3. ファイル生成を session-log.md に記録

セッション終了時

1. セッションサマリーを生成
2. context.json を更新
3. 次回への引き継ぎ事項を記録

メモリ最適化（CC 2.1.49+）

Claude Code 2.1.49 以降、セッション再開時のメモリ使用量が 68% 削減 されました。

推奨ワークフロー

# 長時間作業は --resume を活用
claude --resume

# 大規模タスクは分割してセッション再開
claude --resume "続きから"

メモリ効率が大幅に改善されたため、セッション再開を積極的に活用してください。

/recap — セッション中の状況確認（CC 2.1.108+）

CC 2.1.108 で追加された /recap コマンド（/rewind のエイリアス）は、現在のセッション内で これまでに何をしたかを素早く振り返るために使用します。 --resume で別セッションに戻る前や、長時間作業の途中確認に組み合わせると効果的です。

推奨タイミング:

# 典型的な使用フロー
# 1. 現在の作業状況を確認
/recap

# 2. 必要に応じて session-log.md に手動追記後、セッションを再開
claude --resume

/recap はセッション内の振り返りのみ。前回セッションの内容は session-log.md または claude --resume でのコンテキスト継承で確認する。

使用例

前回の続きから開始

ユーザー: 「前回の続きから」

Claude Code:
📋 前回のセッション（2024-01-15）

完了したタスク:
- ユーザー認証機能
- ログインページ

未完了:
- ログアウト機能
- パスワードリセット

「ログアウト機能を作って」と言えば続きを実装します。

プロジェクトの状況確認

ユーザー: 「このプロジェクトについて教えて」

Claude Code:
📁 プロジェクト: my-blog

技術スタック:
- Next.js + Tailwind CSS + Supabase

現在のフェーズ: コア機能開発
進捗: 40% 完了

最近の決定:
- Supabase Auth を採用
- App Router を使用

Claude Code 自動メモリとの関係（D22）

Claude Code 2.1.32+ には「自動メモリ」機能があり、~/.claude/projects/<project>/memory/MEMORY.md にセッション間の学習を自動保存します。

Harness のメモリシステムとは3層アーキテクチャとして共存します:

使い分け:

• Layer 1 の知見がプロジェクト全体に重要 → /memory ssot で Layer 2 に昇格
• 日常的な学習は Layer 1 に任せる（無効化しない）
• Agent Teams 使用時は並列書き込みに注意

詳細: D22: 3層メモリアーキテクチャ

注意事項

• 自動保存: hooks/Stop により、セッション終了時に session-log.md へ要約を自動追記する運用を推奨（未導入の場合は手動運用でOK）
• プライバシー: 機密情報は記録しない
• Git方針: decisions.md/patterns.mdは共有推奨、session-log.md/context.json/.claude/state/はローカル推奨（詳細: docs/MEMORY_POLICY.md）
• 容量管理: ログが大きくなったら「セッションログを整理して」を推奨

Session State Skill

セッション状態の遷移を管理する内部スキル。 docs/SESSION_ORCHESTRATION.md に定義された状態機械に従って遷移を検証・実行する。

機能詳細

使用タイミング

• /work フェーズ境界での状態更新
• エラー発生時の escalated 遷移
• セッション終了時の stopped 遷移
• セッション再開時の initialized 復帰

注意事項

• このスキルは内部使用専用です
• ユーザーが直接呼び出すことは想定していません
• 状態遷移ルールは docs/SESSION_ORCHESTRATION.md で定義

Session Skill (Unified)

Consolidates all session-related functionality into one skill.

Usage

/session              # Show available options
/session list         # Show active sessions
/session inbox        # Check incoming messages
/session broadcast "message"  # Send message to all sessions

Subcommands

/session list - List Active Sessions

Shows all active Claude Code sessions in the current project.

📋 Active Sessions

| Session ID | Status | Last Activity |
|------------|--------|---------------|
| abc123     | active | 2 min ago     |
| def456     | idle   | 15 min ago    |

/session inbox - Check Inbox

Checks for incoming messages from other sessions.

📬 Session Inbox

| From | Time | Message |
|------|------|---------|
| abc123 | 5m ago | "Ready for review" |
| def456 | 10m ago | "API implementation done" |

/session broadcast "message" - Broadcast Message

Sends a message to all active sessions.

/session broadcast "Review complete, ready for merge"

Capabilities

メモリ最適化（CC 2.1.49+）

Claude Code 2.1.49 以降、セッション再開時のメモリ使用量が 68% 削減 されました。

長時間セッション管理のベストプラクティス

セッション名の自動生成（CC 2.1.41+）

/rename を引数なしで実行すると、会話コンテキストからセッション名を自動生成します。 長時間セッションや --resume を多用するワークフローでセッションの識別が容易になります。

効率的なワークフロー例

# 実装フェーズ1
claude "認証機能を実装"
# → 1時間後

# セッション再開（メモリ効率的）
claude --resume "パスワードリセット機能を追加"
# → 1時間後

# さらに再開
claude --resume "テストを追加"

メモリ管理の推奨事項