Teamwork Parent

---
name: teamwork-parent
description: 親issueがsub-issueに分割された場合の進行管理を自動化する。ユーザーが「チームワークスキルを使って」「sub-issueを立てて分担して」等、既存または今後作成するsub-issue群の進行をこのセッションに任せたいときに使う。呼び出し後このセッションは「チームワークセッション」となり、sub-issueのワークツリーを購読し、進行可能なタスクを自動で子ワークツリーとして生成・監視し、全sub-issueがクローズしたら完了報告する。このセッション自身が誰かのsub-issueとして作られている場合は teamwork-child の義務と併用する。
allowed-tools: mcp__plugin_oretachi_oretachi__oretachi_add_task, mcp__plugin_oretachi_oretachi__oretachi_subscribe_worktree, mcp__plugin_oretachi_oretachi__oretachi_unsubscribe_worktree, mcp__plugin_oretachi_oretachi__oretachi_list_subscriptions, mcp__plugin_oretachi_oretachi__oretachi_poll_inbox, mcp__plugin_oretachi_oretachi__oretachi_ack_message, mcp__plugin_oretachi_oretachi__oretachi_get_worktree_status, mcp__plugin_oretachi_oretachi__oretachi_inspect_worktree, mcp__plugin_oretachi_oretachi__oretachi_list_repository, mcp__plugin_oretachi_oretachi__notify_worktree, mcp__plugin_oretachi_oretachi__oretachi_set_tray_notification, mcp__plugin_oretachi_oretachi__artifact, mcp__plugin_oretachi_oretachi__artifact_module, mcp__plugin_oretachi_oretachi__search_artifact, Read, Write, Edit, Glob, Grep, Bash(gh issue:*), Bash(gh api:*), Bash(gh repo view:*), Bash(git branch:*)
---

# teamwork-parent スキル

このセッションは以後「チームワークセッション」として、sub-issueの分担・進行管理に徹する。実際のコード実装は各sub-issue用の子ワークツリーに委ね、このセッション自身はコードを書かない。

## Step 1: 計画とユーザー承認

1. 対象issueの本文・既存コメント・既存sub-issue(あれば`gh issue list`等で確認)から、タスク分担と依存関係を洗い出す。sub-issueがまだ存在しない場合は、分割案を作成し「sub-issueを新規作成するか」を後続の承認要求に含める(この時点では作成しない)。
2. 各sub-issueに決定的なブランチ名を採番する(例: `issue-<番号>`)。
3. **停止条件をヒアリングする。** 分割案と同時に、次の2種類の停止条件の候補を挙げてユーザーに提示し、回答を得る:
   - **タスクの停止条件**(子ワークツリーが自分の作業中に止まる項目) — 例: 「追加テーブルのスキーマが確定したら確認」「動作確認の結果を見て判断」
   - **エッジの停止条件**(次タスクへ進む遷移で親自身が止まる項目) — 例: 「#141 の成果を見て #142 の分割方針を再確認」
   AIが候補を出し、ユーザーが取捨選択・追加する形で確定させる。**ユーザーの回答を得てから**`data/flow`にセットすること。
4. 5章の手順で計画フロー図をartifactとして作成する(状態はすべて`not_started`、停止条件は確定した内容を`checked: false`で入れる)。**この計画フローartifactが以後の唯一の進捗管理データになる**(別途マークダウン等は作らない)。
5. ユーザーに承認を求める。承認内容には次を含める:
   - sub-issue新規作成の要否(対象がある場合)
   - 計画フロー(依存関係・ユーザーが介入するタイミング)
   - **各タスク/エッジに設定した停止条件の一覧**
   **承認が得られるまでStep2(`oretachi_add_task`の呼び出し)を行わない。**
6. **承認が得られたら、Step 2 に入る直前に自分自身のワークツリーのトレイ通知をオフにする**(この呼び出し自体に承認は要らない。自分のノイズを止めるだけで他ワークツリーの通知には影響しないため):
   ```
   oretachi_set_tray_notification(project_dir: <自分の作業ディレクトリ絶対パス>, enabled: false)
   ```
   ここから先は子ワークツリーの購読で待機と再開を繰り返すため、自分のフック由来通知(`Stop`→`completed` 等)がトレイのノイズになる。**逆に計画が確定するまでの項番3のヒアリング・項番5の承認要求ではオンのままにしておく**(通常のフック由来通知でユーザーが呼び戻される状態を保つため、ここでは先にオフにしない)。

### フローを修正するとき

タスクの追加・削除や依存関係の変更を行う場合は、**その差分について停止条件を改めてユーザーに聞く**。新しいタスクにはそのタスクの停止条件を、新しいエッジにはその遷移の停止条件を、Step1と同じ手順でヒアリングしてから`data/flow`を更新する。既存の停止条件をそのまま流用する・不要と判断する、といった推測はしない。

## Step 2: 子ワークツリー作成(承認不要、開始・完了トリガーで自動)

依存が無い、または既に解消済みの`not_started`のsub-issueについて、承認後は都度**ユーザーに確認せず**以下を実行する。

**ただし、そのタスクへ入るエッジに未クリアの停止条件が1つでもあれば、この手順に入らない。** `blocks` / `informs` のどちらでも同じ(停止条件が付いている以上、その遷移では親が止まる)。その場合はStep3の「親自身の停止条件」の扱いに従い、`notify_worktree`でユーザーを呼び戻して回答を得てからにする。

1. **そのタスクの停止条件をsub-issue本文に書き込む。** `data/flow`のタスク側`stopConditions`を、sub-issue本文の末尾に`## 停止条件`セクションとしてチェックリストで追記する(既にあれば内容を同期する):
   ```markdown
   ## 停止条件

   - [ ] 追加テーブルのスキーマが確定したら確認する <!-- sc-142-1 -->
   - [ ] 動作確認の結果をユーザーが見て判断する <!-- sc-142-2 -->
   ```
   **`data/flow`の`id`をHTMLコメントで埋め込む。** 子はこのidをクリア報告に含めるため、
   親は文面のゆらぎに関係なく対象の停止条件を特定できる。
   `gh issue edit <番号> --body-file <一時ファイル>`等で本文を更新する。**これが子へ停止条件を伝える唯一の経路**(`oretachi_add_task`のpromptはURLのみのため、本文に書かないと子は停止条件を知れない)。エッジの停止条件は親自身のものなのでsub-issue本文には書かない。
2. `oretachi_add_task`を呼ぶ。**promptの冒頭に必ず`teamwork-child`スキルの読み込み指示を入れ、本文はsub-issueのURL参照のみに留める**(issue本文を転記しない):
   ```
   oretachi_add_task(prompt: "teamwork-child スキルを読み込んでから対応してください。\nSub-issue: <URL>")
   ```
3. `oretachi_add_task`は非同期発火のため、ターン境界を挟んで`oretachi_get_worktree_status(query: <採番したブランチ名>)`をポーリングし、実際に作成されたワークツリー名を確認する。
4. `oretachi_subscribe_worktree(target: <確認したワークツリー名>, event_kinds: ["worktree.closed", "worktree.created", "worktree.message"])`で購読する。
5. 5章の手順で計画フローartifactの`data/flow`モジュールを更新し、対象タスクの`status`を`in_progress`にし、`branch`が実際の値と一致していることを確認する。

## Step 3: 子ワークツリーイベントへの対応

- **`worktree.closed`**: 対応するsub-issueの`status`を`data/flow`更新で`done`にする。依存が解消されて着手可能になった`not_started`のsub-issueがあれば、Step2の手順で次の子ワークツリーを**承認を求めず**自動作成する。 **このとき、そのタスクの停止条件がすべて`checked: true`になっているか確認する。** 子がクリア報告を送り損ねている場合があるので、sub-issue本文の`## 停止条件`のチェックボックスと`data/flow`を突き合わせ、ズレていれば`data/flow`を実態に合わせて更新してから`done`にする。
- **`worktree.message`**: `oretachi_poll_inbox`で内容を確認し、`oretachi_ack_message`で既読化する。
  - issueコメントのURLのみの場合は必要に応じて参照し、ユーザーの判断が必要な内容かどうかを見極める。
  - ユーザー判断が必要な内容だけを提示し、それ以外は自動で流れを継続する。
  - **受信内容が「子が自分の停止条件で止まった」ことを示す場合、親は停止も`notify_worktree`もしない。** 子の停止条件は子ワークツリー上でユーザーが解決するものなので、親は`MESSAGES`に記録して流れを継続する(親がここで止まると、子と親の二重で人を呼ぶことになる)。
  - **子から停止条件のクリア報告を受けたら、`data/flow`の該当条件を`checked: true`にして`checkedAt`を入れる。** 子は`停止条件クリア: [<id>]「<テキスト>」→ <ユーザーの判断内容>`の書式で送ってくる(teamwork-child 義務2)。`<id>`で対象を特定し、無ければテキストで照合する。

- **ユーザーの判断・操作が必要になったときは必ず`notify_worktree`を呼ぶ。** Step 1 の末尾(承認取得後)でトレイ通知をオフにしているため、この時点ではテキストを出力するだけではユーザーは気付けない。トレイ通知オフでも通るのは`notify_worktree`による明示通知と承認待ち(`approval`)の2経路だけで、**「ユーザーに問いを立てる」意図を確実に伝えられるのは`notify_worktree`のほう**なので、省略しない。
- すべてのイベントを5章の手順で`data/flow`の`MESSAGES`に追記する(新しい順に先頭へ追加)。
- 状態に迷ったら`oretachi_list_subscriptions`で購読状態を確認してよい。

### 親自身の停止条件(エッジ)への対応

`from`が`done`になり、次タスク`to`を起動しようとする時点で、`to`へ入るエッジ(`blocks` / `informs`いずれも)に未クリアの停止条件があれば:

1. **`oretachi_add_task`を実行しない。**
2. `notify_worktree`でユーザーを呼び戻し、該当する停止条件の内容を提示して回答を求める。
3. 回答を得たら`data/flow`のそのエッジの条件を`checked: true` / `checkedAt`に更新する。
4. すべてクリアになってからStep2の手順で子ワークツリーを作成する。

複数の停止条件がある場合は、すべてクリアされるまで起動しない。

## Step 4: 完了判定

全sub-issueが`done`になったら:
- `oretachi_set_tray_notification(project_dir: <自分の作業ディレクトリ絶対パス>, enabled: true)`を呼び、トレイ通知をオンへ戻す(ワークツリーは完了後も残って再利用されうるため、オフのまま放置しない)。ワークツリー作成時にトレイ通知オフが焼き込まれていた場合は、`enabled: false`のままにするかをユーザーに確認してから戻すこと。
- ユーザーに完了を報告し、作業を停止する。
- **このワークツリー自身が誰かのsub-issueである場合**(teamwork-childの義務を負っている場合)は、続けて`teamwork-child`スキルの完了報告手順(親issueへの報告 → `oretachi_close_worktree`の承認)に従う。

## トレイ通知のノイズ対策(原則)

チームワークセッションは子ワークツリーのイベントを購読して待機と再開を繰り返すため、自分自身のフック由来通知(`Stop`→`completed`など)がトレイに溢れやすい。**原則として親ワークツリー(このセッション)はトレイ通知をオフにし、人の判断・操作が必要なときにのみ明示的に`notify_worktree`で通知する。** ただしオフにするのは **Step 1 のユーザー承認を得た直後(Step 2 に入る直前)** の1回だけ(Step 1 項番6)。計画確定までのヒアリング・承認要求の区間はユーザーを呼び戻す必要が最も高いので、通常のフック由来通知が出るオンのまま残す。

`enabled`を省略して呼ぶと「未設定」に戻る(実効値は`true` = 通知する)。ワークグループの`trayNotification`は**新規ワークツリー作成時の初期値**でしかなく、フォールバック先にはならないので、省略呼び出しは「作成時の設定へ戻す」ことにはならない点に注意する(Step 4)。

**対象は自分自身のワークツリーだけ**。子ワークツリーは承認待ちをユーザーに見せる必要があるため、通知はオンのままにする(子側の設定に触れない)。

オフにしても次は変わらない:

- 自動承認は動き続ける(通知イベント自体は流れており、抑制されるのはトレイへの提示だけ)。
- **承認待ち(`PermissionRequest`由来の`approval` = ツール許可 / プラン承認 / AskUserQuestion)は抑制されない**(#225)。オフで止まるのは`Stop`→`completed`や高頻度な`hook`のノイズだけなので、ダイアログで止まったまま気付かれない状態にはならない(ただしリポジトリに通知フックが1件も設定されていない場合は、この経路自体が発火しない)。
- **ユーザー判断が必要なときは`notify_worktree`を明示的に呼ぶ。トレイ通知がオフでもこれは常に通る**(このツール経由の通知は`kind`にかかわらず、リポジトリの通知フック設定にも左右されず常にトレイへ出る)。`approval`が抑制されなくなっても`notify_worktree`は省略しない —— **ダイアログを出さずにテキストだけで問いを立てる場合、フック由来の通知は何も出ない**ため。
  - 逆に`AskUserQuestion`などダイアログを伴う問いでは、`notify_worktree`と`approval`で通知が2件重なる(debounceのキーが`(ワークツリー, kind, tray)`単位なので畳まれない)。呼び戻しの確実さを優先して重複は許容する方針だが、ダイアログだけで用が足りる場面まで機械的に`notify_worktree`を足す必要はない。

したがって Step 3 で「ユーザー判断が必要な内容だけを提示する」際は、テキスト出力に頼らず`notify_worktree`を呼んでユーザーを呼び戻すこと。

## 禁止事項

- Step1の承認前に`oretachi_add_task`を呼ばない。
- sub-issueの本文をそのまま`oretachi_add_task`のpromptに転記しない(URLのみ)。
- `oretachi_add_task`のprompt冒頭の`teamwork-child`読み込み指示を省略しない(子ワークツリーが正しいスキルを読み込む唯一の経路のため)。
- ユーザー判断が不要なメッセージでユーザーの手を止めない。
- トレイ通知をオフにしたまま、ユーザー判断が必要な場面で`notify_worktree`を省略しない(ユーザーが永久に気付けなくなる)。
- 子ワークツリーのトレイ通知を`oretachi_set_tray_notification`でオフにしない(承認待ちが見えなくなる)。
- **親の停止条件(エッジ)を飛ばして次タスクを起動しない。** 未クリアの停止条件が残っているエッジの先にあるタスクは、`oretachi_add_task`の対象にしない。
- 子の停止条件による子の停止を、親の停止として扱わない(親は止まらず流れを継続する)。
- 停止条件をユーザーに聞かずにAIの判断だけで設定・変更・削除しない。
- 進捗を別ファイル(マークダウン等)へ二重に記録しない。進捗の唯一の記録先は計画フローartifactの`data/flow`。

---

# 計画フロー図artifactモジュール

## 引数

```
$ARGUMENTS: <artifact-id> [--repo <repo>] [--branch <branch>]
```

- `artifact-id`(必須): 作成するアーティファクトID(例: `teamwork-plan-139`)
- `--repo` / `--branch`(任意): 保存先ワークツリーを明示したい場合のみ、両方セットで指定

## テンプレートを読み込む

このスキルディレクトリ(`SKILL.md`と同じ場所)の`templates/`フォルダにある以下のファイルを使う:

| ファイル | アーティファクトモジュール | カスタマイズ要否 |
|---|---|---|
| `templates/entry-point.jsx` | エントリポイント(content) | `// CUSTOMIZE:` コメント箇所のみ変更 |
| `templates/components--TaskNode.jsx` | `components/TaskNode` | そのまま利用 |
| `templates/components--DependencyEdge.jsx` | `components/DependencyEdge` | そのまま利用 |
| `templates/lib--stopConditions.jsx` | `lib/stopConditions` | そのまま利用 |
| `templates/data--flow.example.jsx` | `data/flow` | ※スキーマ参照用、新規生成 |

**「そのまま利用」の3本(`components--TaskNode` / `components--DependencyEdge` / `lib--stopConditions`)はReadしない。**
`artifact_module`に`file_path`を渡せばoretachi側がファイルを読んで登録するので、読み込んだ内容を`content`へ
書き戻す往復(同じテキストが2回トークンを食う)が消える。Readが要るのは`entry-point.jsx`(CUSTOMIZE箇所を変える)と
`data--flow.example.jsx`(スキーマ参照)だけ。

`<SKILL_DIR>` は**スキル読み込み時に先頭へ注入される `Base directory for this skill:` の絶対パス**を
そのまま使う（例: `C:\Users\<user>\AppData\Roaming\com.ia.oretachi\claude-plugins\oretachi\skills\<スキル名>`）。
`${CLAUDE_PLUGIN_ROOT}` などの環境変数は展開されないので、素で渡してはいけない。
相対パスはワークツリー追加先ディレクトリ基準で解決されるため、テンプレートには届かない。

**`data/flow`が計画フローの唯一のデータソース(TASKS/DEPENDENCIES/MESSAGESの3つをこの1ファイルにまとめる)。** Step2/Step3で進捗が変わるたびに、このモジュールを`artifact_module(command:"update", ...)`で直接更新する。専用の進捗管理マークダウン等は作らない。

## 表示操作

domain-model-diagramと同様、ドラッグでパン・スクロールでズームイン/アウトができる(マウスホイールで0.2〜2.5倍)。右上の「⟲」ボタンで初期表示に戻せる。

**パン位置とズーム倍率はアーティファクトのメモリー(`useMemory`)に保存される。** 親セッションが`data/flow`を更新するとアーティファクトはリロードされるが、表示位置は直前のまま復元されるので、見ていた場所を見失わない。保存はドラッグ終了時とズーム確定時(最後のホイールから300ms)にだけ行う。「⟲」を押すと保存値も消え、次回は既定の表示位置から始まる。四隅の欄の開閉状態は保存しない(開きっぱなしが復元されるとフロー図を覆うため)。

フロー図を覆わないよう、四隅の欄は**既定ですべて畳まれている**。四隅のチップ(左上=進捗、右上=`⟲`/`?`、左下=凡例、右下=状況)をクリックすると展開し、同時に開くのは1つだけ。`Esc`キーまたは背景クリックで閉じる。右下の「状況」チップには畳んだ状態でも `▸<次に着手可能数> ⏸<未クリアの停止条件を持つタスク+エッジの数>` のバッジが出る(灰=未到達のものも含む総数)。

タスクノードのissue番号(`#261`等)は`data/flow`の`REPO_URL`を使ったissueへのリンクになる。
アーティファクトのiframeはsandbox内なのでクリックしてもブラウザは開かないが、**リンクにマウスを乗せると
oretachi側のポップアップが飛び先URLとコピーボタンを出す**ので、そこからURLを取ってissueを開ける。

停止条件を持つノード・依存線には `⏸`(未クリアあり) / `☑`(全クリア済み) のバッジが付き、**ホバーすると停止条件のtodoリストがポップアップする**(対象は白枠で強調される)。色は3フェーズを表す: 灰=未到達(タスクが未着手/ブロック中、またはエッジの遷移元がまだ`done`でない)、橙=到達済み(その作業・遷移の中で人の判定が入る)、緑=全条件クリア済み。

## レイアウト計算

Step1で洗い出したsub-issue一覧・依存関係から座標を割り当てる。

**ガイドライン:**
- 依存関係のトポロジカル・レベル(何段目の依存か)を列に割り当てる(依存が無いタスクは列0)
- 列の開始x: 40, 320, 600, 880, 1160, ...(列幅280px)
- 同じ列内のタスクは行間124px(84 + 間隔40)で縦に並べる
- `CANVAS_W` = 最大タスクx + 220(BOX_WIDTH) + 40(マージン)
- `CANVAS_H` = 最大タスクy + 84(BOX_HEIGHT) + 40(マージン)

## アーティファクト作成

以下の順序でMCPツールを呼び出す:

**1. エントリポイント作成**
```
artifact(command: "create", id: "<artifact-id>", type: "application/vnd.ant.react",
  title: "チームワーク計画フロー — #<親issue番号>",
  content: <entry-point.jsx の内容。CANVAS_W/H・タイトルを調整>)
```

**2. `components/TaskNode` モジュール作成**
```
artifact_module(command: "create", module_name: "components/TaskNode",
  file_path: "<SKILL_DIR>/templates/components--TaskNode.jsx")
```

**3. `components/DependencyEdge` モジュール作成**
```
artifact_module(command: "create", module_name: "components/DependencyEdge",
  file_path: "<SKILL_DIR>/templates/components--DependencyEdge.jsx")
```

**4. `lib/stopConditions` モジュール作成**
```
artifact_module(command: "create", module_name: "lib/stopConditions",
  file_path: "<SKILL_DIR>/templates/lib--stopConditions.jsx")
```

2〜4はテンプレートをそのまま登録するので`content`ではなく`file_path`を渡す(Readも書き戻しも不要)。

**5. `data/flow` モジュール作成**
```
artifact_module(command: "create", module_name: "data/flow",
  content: <Step1で分析したsub-issue一覧・依存関係。MESSAGESは空配列でよい>)
```

**`REPO_URL`に対象リポジトリのURLを入れること**(テンプレートでは空)。タスクノードのissue番号は
この値を使って`<REPO_URL>/issues/<番号>`へのリンクになる。値は`gh repo view --json url -q .url`で
取得し、**推測で書かない**(別リポジトリのURLを入れると全ノードが無関係な同番号issueへ飛ぶ。
空のままならリンクが出ないだけで済む)。`issueNumber`が数値のタスクだけがリンクになり、
採番前のプレースホルダ文字列は素のテキストのまま出る。

## 検証

```
artifact(command: "outline")
```

で構造確認。エントリポイント + 4モジュール(`lib/stopConditions`, `components/TaskNode`, `components/DependencyEdge`, `data/flow`)が揃っていれば完了。

`outline`では`REPO_URL`の設定漏れ・書き換え忘れは検知できないので、**アーティファクトを開いて、ノードのissue番号が下線付きリンクになっていること・ホバーで出るURLが対象リポジトリのものであることを目視で確認する**。

## 進捗の反映(`data/flow`の更新方法)

進捗管理マークダウン等の別ファイルは使わず、`data/flow`モジュール自体を`artifact_module(command:"update", ...)`で直接書き換えることで進捗を反映する。`old_str`/`new_str`はモジュール内で一意になる部分文字列を選ぶ。

> **issue番号のリンク化より前に作成したアーティファクトについて**: `data/flow`に`REPO_URL`を
> 足しても、登録済みの`components/TaskNode`とエントリポイントが旧版のままではリンクにならない。
> 「アーティファクト作成」の手順2で`components/TaskNode`を登録し直し、エントリポイントも
> 現行テンプレート(`REPO_URL`を`TaskNode`へ渡す版)へ更新すること。

**タスク状態の更新**(Step2でsubscribe完了時、Step3でworktree.closed受信時など):
```
artifact_module(command: "update", module_name: "data/flow",
  old_str: "status: 'not_started', branch: 'issue-142'",
  new_str: "status: 'in_progress', branch: 'issue-142'")
```

**メッセージログの追記**(worktree.message受信時。新しい順に配列先頭へ追加):
```
artifact_module(command: "update", module_name: "data/flow",
  old_str: "const MESSAGES = [",
  new_str: "const MESSAGES = [\n  { ts: '<ISO8601>', from: '#<issue番号>', text: '<要約>' },")
```

**停止条件のクリア**(子からクリア報告を受けたとき、または親自身の停止条件にユーザーが回答したとき):
```
artifact_module(command: "update", module_name: "data/flow",
  old_str: "{ id: 'sc-142-1', text: '追加テーブルのスキーマが確定したら確認', checked: false }",
  new_str: "{ id: 'sc-142-1', text: '追加テーブルのスキーマが確定したら確認', checked: true, checkedAt: '2026-09-05 14:30' }")
```

これにより、ユーザーはoretachi UIで計画フローartifactを開くだけで最新の進捗と、どこで人の判断待ちになっているかを確認できる。