cursor-do

# 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 側にはない ([references/cursor-cli-only.md](${CLAUDE_SKILL_DIR}/references/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` をタスク説明として受ける。空なら直前の明示依頼と選択済み Plans.md を読み、対象を回収する。 それでも対象を特定できない場合だけ、以下のマーカーを出力してユーザーに 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 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 # `agent`（公式の新表記）→ `cursor-agent`（legacy alias）の順に探す。 # `agent` は汎用的な名前なので、symlink 解決後の実パスの「成分」に # cursor-agent が完全一致で現れる場合だけ採用する（部分文字列一致だと # /x/cursor-agent-not-really/agent のようなディレクトリ名で突破される）。 for _c in agent cursor-agent; do _p="$(command -v "$_c" 2>/dev/null)" || continue [ -n "$_p" ] || continue _r="$(realpath "$_p" 2>/dev/null || readlink -f "$_p" 2>/dev/null || echo "$_p")" case "/$_r/" in */cursor-agent/*) CURSOR_AGENT_BIN="$_p"; break ;; esac done if [ -z "$CURSOR_AGENT_BIN" ] && [ -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 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 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 を呼ぶ ([references/cursor-cli-only.md](${CLAUDE_SKILL_DIR}/references/cursor-cli-only.md) Topology 節 — 非 claude backend では Worker 介在なし)。プロンプトは引数の task そのまま + 必要な追補のみ。冗長な前置きは付けない。 ```bash 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> Purpose and why: <expected outcome and user need> Owned paths and non-goals: <assigned files/modules and excluded work> Definition of done: <observable conditions and required checks> Contract and authorization references: <selected plan/spec paths and original user instruction or applicable approval record> Available evidence: <observed state, prior attempts, findings and artifact paths> Constraints: - Choose the implementation method within the assigned scope. Other workers may be active; preserve their edits. - Recover missing context from the supplied contracts and read-only inspection first. State minor assumptions; stop only the action that needs a material decision or missing authorization. - Complete authorized reversible work without asking again. Inferred scope is not authorization for protected operations. - Preserve required TDD and validation. After required checks pass, add checks only for new changes, failures, or unresolved concerns. - 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. - Return the result, decision reasons, changed paths, check commands/results and remaining limitations. A success claim alone is not evidence." 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 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" ' ```