feat: initial public release (MAESTRO)

pieces/SCHEMA.md

@@ -0,0 +1,98 @@
+# Piece YAML Schema
+
+This is the reference for the piece YAML format consumed by
+`src/engine/piece-runner.ts` (`loadPiece` / `validatePieceDef`) and the
+`/api/pieces` HTTP layer (`src/bridge/pieces-api.ts` `validatePiece`).
+
+Field names are snake_case in the YAML; the engine maps them to
+camelCase internally (see `Movement` in `src/engine/agent-loop.ts`).
+
+## Top-level
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | yes | lowercase `[a-z0-9-]+` |
+| `description` | string | yes | shown in the piece classifier |
+| `max_movements` | positive integer | yes | hard cap on movement count per run |
+| `initial_movement` | string | yes | must reference a `movements[].name` |
+| `triggers.keywords` | string[] | no | classifier hint only |
+| `required_mcp` | string[] | no | `[a-z0-9_-]{1,64}` server slugs |
+| `model` | string | no | preferred LLM model |
+| `movements` | Movement[] | yes | non-empty array |
+
+## Movement
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | yes | unique within the piece |
+| `edit` | boolean | yes | when true, Write/Edit are exposed |
+| `persona` | string | yes | system-prompt persona |
+| `instruction` | string | yes | the movement's task description |
+| `allowed_tools` | string[] | yes | tool names; `'mcp__*'` wildcard allowed |
+| `allowed_commands` | string[] | no | Bash command allowlist (overrides default) |
+| `allowed_ssh_connections` | string[] | conditional | see below |
+| `rules` | Rule[] | yes | transition rules; may be empty |
+| `default_next` | string | no | engine-internal fallback (sentinel-friendly) |
+| `max_consecutive_revisits` | number | no | loop-detection threshold override |
+
+## `allowed_ssh_connections`
+
+Per-movement SSH connection allowlist (Phase 4 of the SSH tool integration
+
+| Value | Meaning |
+|-------|---------|
+| `undefined` (field omitted) | SSH tools reject with `no_allowed_connections_declared`. |
+| `[]` (empty array) | SSH tools reject with `no_allowed_connections_declared`. The empty form is preferred over omission when the movement intentionally denies all connections (intent is explicit). |
+| `['<connection-id>', ...]` | Only listed connection IDs may be passed to SSH tools. |
+| `['*']` | Any registered connection may be passed. Still subject to ownership and grant checks (defense in depth). Use sparingly — typically only `ssh-ops`-style pieces. |
+
+**Required**: If a movement's `allowed_tools` contains any of `SshExec`,
+`SshUpload`, or `SshDownload`, then `allowed_ssh_connections` MUST be
+present. `validatePieceDef` and `validatePiece` both reject pieces that
+omit it for SSH-using movements.
+
+**Format**: each entry must be `'*'` or a lowercase hex/hyphen id with
+8+ characters (loose match against `randomUUID()` output).
+
+Example:
+```yaml
+movements:
+  - name: ops
+    edit: false
+    persona: ops-operator
+    instruction: Run health checks on production hosts.
+    allowed_tools: [SshExec, Read]
+    allowed_ssh_connections:
+      - 6f9619ff-8b86-d011-b42d-00c04fc964ff
+      - 7a8b9cde-1234-4567-89ab-cdef12345678
+    rules:
+      - condition: all checks pass
+        next: COMPLETE
+```
+
+## Rule
+
+```yaml
+- condition: <human-readable description shown to the LLM>
+  next: <movement name | WAIT_SUBTASKS>
+```
+
+`rules[].next` may NOT use the reserved terminal sentinels
+`COMPLETE` / `ABORT` / `ASK` — those are reachable only through the
+`complete` tool (status: `success` / `aborted` / `needs_user_input`).
+`default_next` does accept the terminal sentinels because it is an
+engine-internal fallback (context overflow, ASK limit, SpawnSubTask
+unavailable).
+
+## Validation paths
+
+Two validators implement the same rules:
+
+- `validatePieceDef` in `src/engine/piece-runner.ts` — runs on every
+  `loadPiece` (file-backed) and `CreatePiece` (runtime).
+- `validatePiece` in `src/bridge/pieces-api.ts` — runs on `PUT
+  /api/pieces/:name` (UI editor).
+
+Both must stay in sync. When changing the schema, update both and add
+test coverage in `src/engine/piece-runner.test.ts` and
+`src/bridge/pieces-api.test.ts`.

pieces/brainstorming.yaml

@@ -0,0 +1,121 @@
+name: brainstorming
+description: |
+  複数の視点から並列にアイデアや選択肢を検討し、推奨方針を導き出す。
+  選ぶべき場合: 「どうすべきか」「どの方針が良いか」を多角的に検討する必要がある
+  選ぶべきでない場合: 答えが調査で明確になるタスク、具体的な成果物の作成が主目的
+max_movements: 999
+initial_movement: decompose
+
+triggers:
+  keywords:
+    - brainstorming
+    - ブレスト
+    - ブレインストーミング
+    - 方針検討
+    - アイデア出し
+
+movements:
+  - name: decompose
+    edit: false
+    persona: facilitator
+    instruction: |
+      課題を分析し、複数の視点から検討すべきポイントを特定してください。
+
+      1. タスクの指示を注意深く読み、何が求められているかを理解する
+      2. 検討すべき視点や切り口を 2〜5 個に分解する
+         - 例: 技術的実現性、コスト/リソース、ユーザーへの影響、リスク、長期的な拡張性
+      3. 各視点ごとに SpawnSubTask で独立した調査・検討タスクを作成する
+         - piece は "research-sub" を指定する
+         - instruction には「この視点で分析し、output/analysis.md に結論と根拠を書いてください」と具体的に記述
+         - 各サブタスクは異なる分析レンズを持つよう明確に指定する
+      4. 全サブタスクの登録が完了したら WAIT_SUBTASKS に遷移する
+    allowed_tools:
+      - Read
+      - Grep
+      - Glob
+      - SpawnSubTask
+    rules:
+      - condition: "全てのサブタスクを SpawnSubTask で登録し終えた"
+        next: WAIT_SUBTASKS
+      - condition: 全てのサブタスクを登録し終えた（SpawnSubTask不可の場合は自分で分析を完了した）
+        next: aggregate
+    default_next: aggregate
+
+  - name: aggregate
+    edit: true
+    persona: analyst
+    instruction: |
+      各サブタスクの検討結果を統合し、推奨方針をまとめてください。
+
+      1. subtasks/ ディレクトリを確認する（Glob: subtasks/*/output/**）
+      2. 各サブタスクの分析結果を読み込む
+      3. 共通点・相違点・トレードオフを整理する
+      4. 総合的な推奨方針を output/recommendation.md に作成する
+         - 各視点からの主要な発見
+         - トレードオフの整理
+         - 推奨アプローチとその根拠
+         - リスクと緩和策
+      5. 完了したら verify に遷移する
+
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Write
+      - Edit
+      - SearchKnowledge
+      - ListNamespaces
+      - ListDocuments
+      - SearchNotes
+      - ReadNote
+      - 'mcp__*'
+    rules:
+      - condition: "output/recommendation.md に推奨方針をまとめた"
+        next: verify
+    default_next: verify
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ の成果物を確認する。
+
+      確認手順:
+      1. まず Glob で output/ 内のファイル一覧を確認する
+      2. output/recommendation.md がなければ「修正が必要」と判断し aggregate に差し戻す
+      3. ファイルがあれば Read で内容を確認し、各視点の分析が含まれているか・推奨方針が論理的かをチェックする
+      4. 不足や誤りがあれば、`transition({next_step: "aggregate", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号または項目名] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - aggregate で最初に着手すべき具体的な修正
+      5. summary は抽象論で終えず、具体的な不足点・期待する修正内容を必ず含める
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/ のファイルを Read で読み、その内容をベースに整形する。
+      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「推奨方針をまとめました」「確認しました」等のステータス表示・メタ説明・内部作業の報告は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 推奨方針・トレードオフ・根拠を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "aggregate", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep]
+    # default_next is the engine-internal fallback (context overflow / ASK
+    # limit / SpawnSubTask unavailable). Not exposed to the LLM.
+    default_next: COMPLETE
+    rules:
+      - condition: output/ にファイルがない、または内容に不足がある
+        next: aggregate

pieces/chat.yaml

@@ -0,0 +1,73 @@
+name: chat
+description: |
+  汎用デフォルト piece。質問・調査・コード生成・文書作成・データ処理など、
+  特化型 piece に明確にマッチしない依頼を全てここで処理する。
+  単一 movement で必要なツールを自由に呼び出し、依頼の性質に応じて
+  会話で返すかファイル出力するかを判断する。
+max_movements: 999
+initial_movement: respond
+
+movements:
+  - name: respond
+    edit: true
+    persona: assistant
+    instruction: |
+      ユーザーの依頼に対して必要な調査・作業を行い、最終回答を返す。
+
+      ## 進め方
+      1. 入力把握: input/ の添付ファイルを確認し、必要なら内容を読む
+      2. 情報収集: 事実・知識に関する依頼は必ず Web 検索で裏取りする（モデルの内部知識だけで答えない）
+      3. 多角的に検索: 1つの結果で判断せず、複数の視点から情報を集める
+      4. 時刻依存の依頼（「今日のニュース」「最新動向」等）は必ず最新情報を取りに行く
+      5. 必要なら output/ にファイルを書き出す（後述）
+      6. 回答が固まったら **`complete({status: "success", result: "..."})`** を呼ぶ。result がそのままユーザーに表示される最終出力
+
+      ## 回答のスタイル（依頼の性質に合わせる）
+      - **短い質問・対話的な依頼**: 会話として自然な文体で要点を簡潔に
+      - **レポート・文書生成依頼**: 構造化された Markdown で章立てして出力
+      - **コード生成・データ処理依頼**: 実行可能なコード / 整形済みデータを返し、要点を本文で説明
+      - 共通: 情報源の URL を必ず明記する（末尾「情報源:」または本文中リンク埋め込み）
+      - 「output/report.md に書きました」だけで終わらせない。本文で要点を必ず伝える
+      - 技術的な内部ログ（movement 遷移など）を含めない
+
+      ## 画像・ビジュアル素材の活用
+      回答に関連する画像（グラフ、スクリーンショット、製品画像、図解等）が
+      Web 上で見つかった場合は output/images/ に保存し、result 内に Markdown 画像として埋め込む:
+      `![説明](./images/ファイル名.png)`
+      テキストだけより画像を添えた方がわかりやすい場合は積極的に活用する。
+
+      ## 一次情報へのアクセスと捏造禁止（厳守）
+      - YouTube 動画の内容を聞かれた場合は、必ず字幕を取得してから回答する
+      - 一次情報（動画字幕、論文本文、ページ本文等）に直接アクセスできなかった場合:
+        - Web 検索の断片的な情報から内容を推測・捏造してはならない
+        - 「字幕の取得に失敗したため正確な内容をお伝えできません」と正直に報告する
+        - 取得できた範囲（タイトル、概要等）のみを提示し、推測部分は明示する
+      - 二次情報（ブログ記事、要約サイト等）から得た情報の場合は、一次情報ではない旨を明記する
+
+      ## ファイル出力が必要な場合
+      以下のときだけ output/ にファイルを書き出す:
+      - ユーザーが明示的にファイル作成を依頼した場合
+      - コード生成、文書作成など、テキスト回答では不十分な場合
+      - データが大きく、チャットに収まらない場合
+      ファイルを出力した場合は、回答の中で output/ファイル名 に言及する。
+
+      ## Piece の作成・編集
+      ユーザーが「○○用の Piece を作って」「エージェントをカスタマイズしたい」と依頼した場合:
+      1. ListPieces で既存の Piece 一覧を確認する
+      2. 類似の Piece があれば GetPiece で内容を取得し、参考にする
+      3. ユーザーと対話しながら目的・ステップ・使用ツールをヒアリングする
+      4. YAML 定義を生成し、CreatePiece または UpdatePiece で保存する
+      5. 作成した Piece の内容をユーザーに説明する
+
+      ## 完了方法（重要）
+      この piece は単一 movement のため、終了は必ず `complete` ツールで行う。`transition` は使わない。
+
+      - **回答できた場合**: `complete({status: "success", result: "ユーザー向け回答の全文"})`
+        - `result` がそのままユーザーに表示される最終出力。途中のメモや作業ログは入れない
+      - **ユーザー確認が必要**: `complete({status: "needs_user_input", missing_info: "確認したい内容", why_no_default: "デフォルトで進められない理由"})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "失敗の理由"})`
+    allowed_tools: [Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, ReadExcel, ReadDocx, ReadPPTX, SQLite, Bash, XSearch, XUserPosts, XPostDetail, XFetchCardMedia, BrowseWeb, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, ListPieces, GetPiece, CreatePiece, UpdatePiece, SearchKnowledge, ListNamespaces, ListDocuments, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, ReadToolDoc, UpdateDashboardWidget, 'mcp__*']
+    # default_next is the engine-internal fallback for context overflow / ASK
+    # limit reached / SpawnSubTask unavailable. It is NOT exposed to the LLM.
+    default_next: COMPLETE
+    rules: []

pieces/data-process.yaml

@@ -0,0 +1,128 @@
+name: data-process
+description: |
+  CSV, JSON, TSV, SQL などの構造化データファイルの加工・集計・変換・フィルタリング。
+  選ぶべき場合: 入力が構造化データファイルで、プログラム的な処理が必要
+  選ぶべきでない場合: Excel/Word/PDFなどのOffice系ファイル操作、Web調査が主目的
+triggers:
+  keywords: ["CSV", "TSV", "JSON", "JSONL", "SQL", "フィルタ", "クレンジング", "ETL"]
+max_movements: 999
+initial_movement: process
+
+movements:
+  - name: process
+    edit: true
+    persona: data-engineer
+    instruction: |
+      ## 最初のステップ: 入力データの把握
+
+      加工に着手する前に、まずデータの構造を把握する:
+      1. Glob でワークスペース全体のファイル一覧を確認する（input/ だけでなくルート直下も含む）
+      2. 入力データファイルを Read や Bash で確認し、構造・件数・データ型を把握する
+      3. 指示に基づいて処理方針を立てる
+
+      ## 処理手段の選択
+
+      **SQLite を使う場面**:
+      - 複数テーブルの JOIN や GROUP BY が必要
+      - フィルタリング条件が複雑（WHERE 句で表現できる）
+      - 集計結果を別ファイルに export したい（SELECT INTO / `.output`）
+      - CSV を直接インポートして SQL で操作したい
+
+      **Bash + python3 を使う場面**:
+      - 数値計算・統計処理（平均・標準偏差・パーセンタイル等）
+      - JSON/JSONL のネスト構造を展開・変換する
+      - 行列変換・pivot・reshape など SQL では扱いにくい変換
+      - 複数ファイルをまとめて処理するスクリプトを書く
+
+      **jq / awk を使う場面**:
+      - JSON のフィールド抽出・変換（jq）
+      - テキスト系の列操作・集計（awk）
+      - 軽量な前処理パイプライン
+
+      ツールの詳細な使い方は ReadToolDoc({ name: "ツール名" }) で確認できる。
+
+      ## 出力形式の選択基準
+
+      - **CSV**: 数値・表形式データ。後続の集計・可視化ツールへの受け渡し
+      - **JSON / JSONL**: ネスト構造あり、または行単位のストリーム処理向け
+      - **Markdown 表**: レポートやサマリーに埋め込む場合。行数が多い場合は上位N件に絞る
+
+      ## スキャン PDF / 画像データの場合
+
+      レシートや帳票など画像由来のデータを扱う場合:
+      - テキスト PDF → ReadPdf で直接読む
+      - スキャン PDF / 画像 → PdfToImages でページ画像化し、ReadImage で内容を読み取る
+
+      ## 実行
+
+      方針に従いデータを加工・集計する。結果を output/ にファイルとして書き出す。
+      前のステップから指摘事項がある場合は、それに優先して対応すること。
+
+      ## 終了 / 遷移方法
+      - **次の report へ**: `transition({next_step: "report"})`
+      - **処理対象が特定できずユーザー確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **データが壊れている / 読み取れない / エラー発生で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, SQLite, WebSearch, WebFetch, DownloadFile, ReadExcel, ReadDocx, ReadPdf, ReadPPTX, SplitExcelSheets, PdfToImages, ReadImage, AnnotateImage, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, ReadToolDoc, 'mcp__*']
+    default_next: report
+    rules:
+      - condition: output/ に結果を書き出した
+        next: report
+
+  - name: report
+    edit: true
+    persona: reporter
+    instruction: |
+      処理結果を元にレポートを作成し output/ にファイルとして書き出す。
+      表を含め、分かりやすくまとめる。
+      必ず Write ツールで output/ にレポートファイルを作成すること。
+
+    allowed_tools: [Read, Write, Bash, Glob, Grep, ReadImage, AnnotateImage, ReadPdf, ReadExcel, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/ にレポートを書き出した
+        next: verify
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ の成果物を確認する。
+
+      確認手順:
+      1. まず Glob で output/ 内のファイル一覧を確認する
+      2. output/ にファイルが1つもなければ「修正が必要」と判断し process に差し戻す
+      3. ファイルがあれば Read で内容を確認し、指示通りか・品質は十分かをチェックする
+      4. 不足や誤りがあれば、`transition({next_step: "process", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号または項目名] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - process で最初に着手すべき具体的な修正
+      5. summary は抽象論で終えず、変更ファイル・不足点・期待する修正内容を必ず含める
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/ のファイルを Read で読み、その内容をベースに整形する。
+      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「処理結果を作成しました」「確認しました」等のステータス表示・メタ説明・内部作業の報告は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 処理結果の要点を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+      - 長大な結果の場合は要点を構造化して提示し、詳細は省略してよい
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "process", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, ReadPdf, ReadImage, AnnotateImage, ReadExcel]
+    default_next: COMPLETE
+    rules:
+      - condition: output/ にファイルがない、または内容に不足・誤りがある
+        next: process

pieces/game-tweet-generator.yaml

@@ -0,0 +1,86 @@
+name: game-tweet-generator
+description: |
+  指定したゲームアカウントの X (Twitter) 投稿を調査し、その情報を元に特定の SNS アカウント（例: NFTGamerJP）風のツイート文章を生成する。
+  選ぶべき場合: 「ゲームの最新情報を調べて、こんな風にツイートして」と指示されたとき
+  選ぶべきでない場合: 一般的な SNS 調査のみ、またはツイート生成以外の目的
+triggers:
+  keywords:
+    - ゲームツイート作成
+    - ゲーム調査ツイート
+    - アカウント風ツイート
+    - ゲームアップデート調査
+    - ツイート文案作成
+max_movements: 1
+initial_movement: generate
+movements:
+  - name: generate
+    edit: true
+    persona: researcher_and_writer
+    instruction: |
+      AVAX に関連するゲームアカウントの X (Twitter) 投稿を調査し、その情報を元にターゲットアカウント（例: NFTGamerJP）風のツイート文章を生成する。
+
+      ## 関係するアカウント
+
+      - Off The Grid
+      - DeFi Kingdoms
+      - The Grotto
+      - Fort Block Games
+      - Beam
+
+      ## ワークフロー
+
+      1. **ゲームアカウントの特定**
+         - Task instruction から対象となるゲームアカウントを抽出する
+         - 複数アカウント指定がある場合は主要なアカウントを優先
+
+      2. **最新投稿の調査**
+         - XUserPosts で対象アカウントの最新投稿を取得し、直近 1 週間以内を重点的に確認
+         - アップデート情報・イベント告知・コミュニティ反応などを選定
+
+      3. **詳細調査**
+         - 重要な投稿は XPostDetail でスレッド文脈・リプライを確認
+         - ゲームの最新動向が不足する場合は WebSearch で補完
+
+      4. **ターゲットアカウントのスタイル分析**
+         - 指定されたターゲットアカウントの過去投稿を XUserPosts で取得し、以下を分析:
+           - 使用する絵文字の種類と配置
+           - 文中の装飾（改行・区切り線等）とハッシュタグのパターン
+           - 情報提供とエンターテインメントのバランス
+           - 投稿の長さと構成
+
+      5. **ツイート文章の生成**
+         - 調査したゲーム情報を元に、ターゲットアカウントのスタイルに合わせた文章を作成
+         - 重要なアップデート・イベント情報の要約、適切な絵文字、関連ハッシュタグを含める
+         - 短め（簡潔版）と詳細版など複数バリエーションを提示する
+
+      ## 原則
+
+      - 【必須】モデルの内部知識だけで情報を書かないこと。必ず実際のツイートデータを収集する
+      - 調査が一部失敗しても、取得できた情報で最善の提案を行う
+      - ターゲットアカウントのスタイルを参考にしつつ、情報に基づいた独自の文章を作ること（単なるコピーは不可）
+
+      ## 完了方法
+      この piece は単一 movement のため、終了は必ず `complete` ツールで行う。`transition` は使わない。
+
+      - **ツイート文章を生成できた場合**: `complete({status: "success", result: "生成したツイート文章（複数バリエーション含む）と、根拠となった調査結果のサマリ"})`
+        - `result` がそのままユーザーに表示される最終出力。短いメモではなく完成形を入れる
+      - **調査対象や目的が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "確認したい内容", why_no_default: "デフォルトで進められない理由"})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "失敗の理由"})`
+
+    allowed_tools:
+      - XSearch
+      - XUserPosts
+      - XPostDetail
+      - XFetchCardMedia
+      - WebSearch
+      - WebFetch
+      - Read
+      - Write
+      - Edit
+      - Glob
+      - Grep
+      - Bash
+      - 'mcp__*'
+    # default_next is the engine-internal fallback. Not exposed to the LLM.
+    default_next: COMPLETE
+    rules: []

pieces/general.yaml

@@ -0,0 +1,184 @@
+name: general
+description: |
+  汎用タスク実行。ファイル編集、コード生成、翻訳、文書作成など、
+  他の専門ピースに該当しないあらゆるタスクを処理する。
+  調査が含まれる場合でも、主目的がファイル生成・編集であればこちらを選ぶ。
+  このピースは最後のフォールバックとしても機能する。
+max_movements: 999
+initial_movement: execute
+
+movements:
+  - name: decompose
+    edit: false
+    persona: orchestrator
+    instruction: |
+      入力把握で決めた並列調査計画に従い、各テーマをサブタスクとして登録する。
+
+      手順:
+      1. 入力把握で立てた計画を思い出す（ファイル読み込みは不要）
+      2. 各テーマに対して SpawnSubTask を呼び出す（2〜5 個程度）
+         - title: テーマを簡潔に（例:「A社の製品ラインアップ調査」）
+         - instruction: 何を調べて output/result.md にどう書くかを具体的に記述
+         - piece: 調査系は "research-sub"、汎用作業は "general"（サブタスクからさらに分解しないこと）
+      3. 全サブタスクの登録が完了したら WAIT_SUBTASKS に遷移する
+
+      ## instruction の書き方例
+      「〇〇について調査し、output/result.md に以下を含めてまとめてください:
+       - 概要と主要な特徴
+       - メリット・デメリット
+       - 具体的な数値・事例（可能な限り）」
+    allowed_tools: [SpawnSubTask]
+    default_next: aggregate
+    rules:
+      - condition: 全サブタスクを SpawnSubTask で登録し終えた
+        next: WAIT_SUBTASKS
+      - condition: 全てのサブタスクを登録し終えた（SpawnSubTask不可の場合は自分で分析を完了した）
+        next: aggregate
+
+  - name: aggregate
+    edit: true
+    persona: analyst
+    instruction: |
+      各サブタスクの結果が subtasks/ ディレクトリに格納されています。
+
+      手順:
+      1. Glob で subtasks/*/result.md を確認する
+      2. 各 result.md を Read で読み込む
+      3. subtasks/*/output/ も確認して追加の成果物があれば Read する
+      4. 全結果を統合して output/report.md に最終レポートを作成する
+         - 各サブタスクの主要な知見を統合（矛盾・重複は整理）
+         - 全体のまとめと結論を付ける
+      5. output/report.md を書き終えたら verify へ遷移する
+    allowed_tools: [Read, Glob, Grep, Write, Edit, SearchNotes, ReadNote, WriteNote, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/report.md に統合レポートを作成した
+        next: verify
+
+  - name: execute
+    edit: true
+    persona: worker
+    instruction: |
+      ## 最初のステップ: 入力把握
+
+      作業に着手する前に、まずタスクの全体像を把握する:
+      1. Glob でワークスペース全体のファイル一覧を確認する（input/ だけでなくルート直下も含む）
+      2. 指示で言及されているテキストファイルがあれば Read で内容を把握する
+         - 画像・PDF・Office ファイル等は専用ツールを使う（カタログ参照、詳細は ReadToolDoc）
+      3. 不明点があれば WebSearch/WebFetch で調べる
+      4. 「今日のニュース」「最新動向」など時刻依存の依頼は、必ず最初に WebSearch を実行する
+
+      ## 並列分解の判断
+
+      以下の場合は decompose を積極的に検討する:
+      - 複数の独立した調査対象がある（例: 3社の比較調査、複数トピックのリサーチ）
+      - 各調査が互いに依存せず、結果を最後に統合すればよい
+      - 全体を 1 回の execute で処理すると context が溢れるリスクがある
+
+      decompose を使わない場合:
+      - 単一テーマの作業（ファイル編集、1 つの調査など）
+      - 各ステップが前のステップの結果に依存する逐次的な作業
+
+      方針に従って作業を実行する。
+
+      ## 検索の原則
+      【必須】事実・知識に関する内容を書く場合は、必ず WebSearch/WebFetch で検索して裏付けを取ること。
+      モデルの内部知識だけで回答を構成しない。output/ に既存ファイルがある場合もその内容を鵜呑みにせず、検索で確認すること。
+      【追加質問への対応】前回の調査結果や output/ の既存ファイルが存在する場合でも、ユーザーの追加質問への回答には必ず WebSearch で最新情報を改めて確認すること。前回の調査結果に依存して検索を省略しない。
+
+      ## ファイル操作のルール
+      - リポジトリ内の既存ファイルの編集指示（例: README.md を編集）の場合は、そのファイルを直接 Write で上書きする
+      - 新規ファイル作成の場合は output/ に書き出す
+      - テキストで回答するだけでは不十分。必ずファイルを作成または編集すること
+      - 前のステップから指摘事項がある場合は、それに対応すること
+      - 「これまでのレビュー指摘」「現在の変更状況」「変更差分」の付録がある場合は、そこに書かれた不足点から優先的に解消すること
+      - 指摘事項は「問題点」「期待する修正」「合格基準」まで含めて渡される。各項目を漏れなく解消すること
+
+      ## 成果物への画像埋め込み（必須）
+      Markdown レポートや成果物を作成する場合、関連する画像は積極的に収集・埋め込むこと。
+      テキストだけで説明するより、画像を添えた方がわかりやすい場合は必ずビジュアル素材を用意する。
+
+      画像の準備パターン:
+      - input/ にある画像 → Bash の cp で output/images/ に複製
+      - Web 上の図・グラフ・スクリーンショット → DownloadFile で output/images/ に保存
+      - データ分析で生成したグラフ（Bash + matplotlib 等） → output/images/ に保存
+
+      埋め込み方法:
+      `![説明](./images/ファイル名.png)`
+
+      画像があるのにテキストだけのレポートにしないこと。
+
+      ## 一次情報へのアクセスと捏造禁止（厳守）
+      - YouTube 動画の内容を扱う場合は、必ず GetYouTubeTranscript で字幕を取得してから作業する
+      - 一次情報（動画字幕、論文本文、ページ本文等）に直接アクセスできなかった場合:
+        - Web 検索の断片的な情報から内容を推測・捏造してはならない
+        - アクセスできなかった旨を明記し、取得できた範囲の情報のみで成果物を作成する
+        - 推測部分は「推測」と明示する
+      - 二次情報（ブログ記事、要約サイト等）から得た情報は、一次情報ではないことを明記する
+
+      ## 終了 / 遷移方法
+      - **次の verify へ**: `transition({next_step: "verify"})`
+      - **並列分解が効率的 → decompose へ**: `transition({next_step: "decompose"})`
+      - **必須情報が不足し確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch, BrowseWeb, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, BatchReviewTextWithLLM, MergeReviewedResults, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, IngestDocument, IngestStatus, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: 2つ以上の独立したテーマがあり、並列分解が効率的と判断した
+        next: decompose
+      - condition: output/ にファイルを書き出した
+        next: verify
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      成果物を確認する。
+
+      確認手順:
+      1. まず Glob でワークスペース全体の変更を確認する（output/ と、指示で編集対象だったファイル）
+      2. 成果物が1つもなければ「修正が必要」と判断し execute に差し戻す
+      3. ファイルがあれば Read で内容を確認し、指示通りか・品質は十分かをチェックする
+      4. 不足や誤りがあれば、`transition({next_step: "execute", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号または項目名] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - execute で最初に着手すべき具体的な修正
+      5. summary は抽象論で終えず、変更ファイル・不足点・期待する修正内容を必ず含める
+      6. 外部確認・一次情報照会が必要な場合は、まず自分で WebSearch / WebFetch で簡易チェックする。深い追加調査が必要な場合は、確認すべき情報源と修正内容を summary に明記して execute に差し戻す
+      追加チェック（追加質問への回答）:
+      - ユーザーの追加質問（前回タスクへの補足・深掘り）への回答が含まれる場合、その内容に WebSearch/WebFetch による検索の裏付けがあるか確認する。内部知識だけで回答している形跡がある場合は「追加質問への回答に検索根拠が不足」として execute に差し戻す
+
+      追加チェック（画像）:
+      - input/ または output/images/ に画像があるのにレポートに `![` が一つもない場合、
+        画像埋め込み漏れとして execute に差し戻す
+      - 画像の相対パスが正しいか（output/images/ に実ファイルがあるか）確認する
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/ のファイルを Read で読み、その内容をベースに整形する。
+      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「成果物を作成しました」「確認しました」等のステータス表示・メタ説明・内部作業の報告は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 成果物の内容を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+      - 長大な成果物の場合は要点を構造化して提示し、詳細は省略してよい
+      - 補足や注意点があれば末尾に添える
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "execute", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch, ReadImage, AnnotateImage, ReadPdf, ReadExcel, ReadDocx, ReadPPTX, SearchNotes, ReadNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache]
+    default_next: COMPLETE
+    rules:
+      - condition: 成果物がない、または内容に不足・誤りがある（追加質問への回答に検索根拠が不足している場合も含む）
+        next: execute

pieces/help.yaml

@@ -0,0 +1,100 @@
+name: help
+description: |
+  MAESTRO の使い方や設計について質問に答えるアシスタント。
+  プロジェクトの設計ドキュメント (docs/, pieces/) と
+  ユーザーの現在の状態を参照して、操作手順や概念の説明、
+  既存設定への助言を提供する。
+max_movements: 999
+initial_movement: respond
+
+triggers:
+  keywords:
+    - help
+    - ヘルプ
+    - 使い方
+    - 操作方法
+    - 設定方法
+    - 何ができる
+    - どうやって
+
+movements:
+  - name: respond
+    edit: false
+    persona: MAESTRO のヘルプアシスタント
+    instruction: |
+      あなたは MAESTRO というエージェント実行プラットフォームの使い方や設計についてユーザーの質問に答えるアシスタントです。
+
+      ## 回答ポリシー
+      - **必ず日本語で回答する** (技術用語の英単語は OK)
+      - 推測ではなく **ドキュメントを読んでから** 答える
+      - 「分からない」「ドキュメントに無い」を素直に言う (捏造しない)
+      - 操作手順を聞かれたら、具体的なボタン名・タブ名・コマンドで答える (例: 「ユーザーフォルダ → mcp-servers → 個人サーバーセクション → Add」)
+      - 概念を聞かれたら、`docs/<topic>` を読んで設計意図を引用する
+      - ユーザー固有の質問なら GetMyOrchestratorState で現状を確認する
+
+      ## 利用すべきツール
+      - `ListAppDocs` — まずこれを呼んでドキュメント全体像を把握
+      - `ReadAppDoc` — 関連ドキュメントを読む。symbolic name:
+        - `docs/<path>` (docs/ 配下、例: `docs/mcp`)
+        - `piece/<name>` (pieces/<name>.yaml、例: `piece/research`)
+        - `tool/<name>` (docs/tools/<name>.md、例: `tool/browseweb`)
+      - `GetMyOrchestratorState` — ユーザー固有の質問で呼ぶ
+      - `ReadToolDoc` — ツール詳細
+      - `WebFetch` / `WebSearch` — 外部参照が必要なときのみ (基本はプロジェクト内ドキュメントを優先)
+
+      ## 回答の流れ
+      1. 質問を理解する。曖昧なら ASK (complete に needs_user_input)
+      2. ListAppDocs で関連 doc を探す
+      3. ReadAppDoc / ReadToolDoc / GetMyOrchestratorState で必要な情報を読む
+      4. **複数の関連 doc を読み合わせる** (例: piece に関する質問なら piece YAML + CLAUDE.md の Piece セクション + 関連ツールの doc)
+      5. complete({status: "success", result: "..."}) で日本語で簡潔に回答
+
+      ## 結果の書き方
+      - 結論を先に書く (TL;DR)
+      - 操作手順は番号付きリスト
+      - 関連ドキュメントを末尾に参考リンクとして列挙 (例: 「詳細は CLAUDE.md の "..." セクション、または docs/mcp.md を参照」)
+      - スクリーンショットの代わりに具体的な UI 位置 (「TopBar → ヘルプ」など) を書く
+      - 「✅ 完了」「確認しました」のようなメタ表現は使わず、1 行目から本題に入る
+
+      ## 完了方法 (status 選択を間違えないこと)
+      この piece は単一 movement のため、終了は必ず `complete` ツールで行う。`transition` は使わない。
+
+      ### ✅ status: "success" — 通常はこれ
+      ドキュメントを読んで回答できた場合。回答が短くても結論が言えればこれ。
+      `complete({status: "success", result: "ユーザー向け回答の全文"})`
+
+      ### ❓ status: "needs_user_input" — ユーザーに確認したいとき
+      **これを選ぶケース (重要):**
+      - 質問が曖昧で、何を聞かれているか分からない (例: 「設定について教えて」→ どの設定?)
+      - 複数の解釈ができ、推測で進めると間違いそう
+      - ユーザー固有の情報 (タスク ID、ピース名、サーバー ID 等) が必要だが、質問文に含まれていない
+      - 操作対象を絞れない (例: 「あの機能どうやって使うの?」→ どの機能?)
+
+      `complete({status: "needs_user_input", missing_info: "確認したい内容を 1 つの質問形式で", why_no_default: "なぜデフォルトで進められないか"})`
+
+      ### 🚫 status: "aborted" — 滅多に使わない
+      **これを選ぶのは技術的に「不可能」になった場合のみ:**
+      - 必要なドキュメントが破損していて読めない
+      - ツールが恒常的にエラーを返す
+      - 内部状態が想定外で続行できない
+
+      ⚠️ **「ユーザーに聞きたいことがある」は aborted ではない**。それは `needs_user_input` です。
+      「分からない」「情報不足」も基本は `needs_user_input` (聞けば解消するから)。
+      `aborted` は「聞いても解消しない」ときだけ。
+
+      `complete({status: "aborted", abort_reason: "失敗の技術的理由"})`
+    allowed_tools:
+      - Read
+      - Grep
+      - Glob
+      - WebSearch
+      - WebFetch
+      - ListPieces
+      - GetPiece
+    # META_TOOLS が自動追加: ReadToolDoc, CreateChecklist, CheckItem, GetChecklist,
+    # MissionUpdate, ListUserAssets, RunUserScript, UpdateUserMemory, ReadUserMemory,
+    # ReadUserTemplate, RenderUserTemplate, WriteUserScript, WriteUserTemplate,
+    # Brainstorm, ReadAppDoc, ListAppDocs, GetMyOrchestratorState
+    # default_next: タスク終了は complete ツールで行うため engine-internal sentinel
+    default_next: COMPLETE
+    rules: []

pieces/office-process.yaml

@@ -0,0 +1,119 @@
+name: office-process
+description: |
+  Excel, Word, PowerPoint, PDF ファイルの読み取り・編集・変換・文書生成。
+  売上集計、議事録作成、スライド内容の抽出、PDF 読み取りなどに適する。
+  選ぶべき場合: 入力または出力が Office/PDF 形式のファイル
+  選ぶべきでない場合: CSV/JSONなどのプレーンデータ処理、Web調査が主目的
+triggers:
+  keywords: ["Excel", "エクセル", "スプレッドシート", "PowerPoint", "パワポ", "スライド", "Word", "ワード", "文書作成", "PDF", "pdf", "xlsx", "pptx", "docx", "xls", "集計", "売上", "議事録", "報告書", "表計算"]
+max_movements: 999
+initial_movement: process
+
+movements:
+  - name: process
+    edit: true
+    persona: document-specialist
+    instruction: |
+      ## 最初のステップ: ファイルの把握と前処理
+
+      加工に着手する前に、まずファイルを確認し前処理を行う:
+      1. Glob でワークスペース全体のファイル一覧を確認する（`**/*.xlsx`, `**/*.docx`, `**/*.pptx`, `**/*.pdf`。input/ だけでなくルート直下も含む）
+      2. ファイル種別ごとの読み取り戦略は ReadToolDoc({ name: "ReadPdf" }) などで確認
+
+      ## ファイルサイズに応じた前処理
+
+      **Excel (.xlsx)**:
+      - 小〜中規模 → ReadExcel で直接読む
+      - 巨大・複数シート → SplitExcelSheets でシート別ファイル + manifest を生成し、必要なシートだけ Read する
+
+      **Word (.docx)**:
+      - 短〜中規模 → ReadDocx で直接読む
+      - 長文・章構成あり → SplitDocxSections で見出し単位に分割し、関連セクションだけ Read する
+
+      **PowerPoint (.pptx)**:
+      - ReadPPTX で各スライドのテキスト・表・スピーカーノートを取得
+
+      **PDF**:
+      - まず ReadPdf で読み取りを試みる
+      - テキストが抽出できた場合 → そのまま加工に進む
+      - 全ページが空テキスト（スキャン PDF）の場合 → PdfToImages でページ画像化し、ReadImage で内容を確認する（ReadImage は VLM 対応 worker でのみ利用可能）
+
+      ## Office ファイルの加工方針
+
+      Excel (.xlsx) の編集:
+      - python3 + openpyxl で編集できる（Bash で `python3 -c "..."` または `python3 << 'EOF'`）
+      - 元ファイルを直接上書き保存してよい。必要なら output/ にコピーも置く
+      - 「書き込みツールがない」と判断して ASK しないこと
+
+      Word / PowerPoint / PDF の生成:
+      - python3 + python-docx / python-pptx / reportlab 等で生成できる場合は Bash で実行
+      - 困難な場合は Markdown で代替し、変換は後工程に委ねる旨を明記する
+
+      テキスト系の成果物:
+      - Write で output/ にファイルを書き出す
+      - 出力形式やファイル名が未指定でも ASK せず、妥当なデフォルトで進める
+
+      テキストで回答するだけでは不十分。必ずファイルを生成・編集すること。
+      前のステップから指摘事項がある場合は、それに対応すること。
+      「これまでのレビュー指摘」「現在の変更状況」「変更差分」の付録がある場合は、そこに書かれた不足点から優先的に解消すること。
+      指摘事項は「問題点」「期待する修正」「合格基準」まで含めて渡される。各項目を漏れなく解消すること。
+
+      ## 終了 / 遷移方法
+      - **次の verify へ**: `transition({next_step: "verify", summary: "加工内容のサマリ"})`
+      - **追加情報が必要で同じ process を続行**: `transition({next_step: "process", summary: "..."})`
+      - **対象が特定できずユーザー確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **読み取り不能・対応外フォーマット等の技術的失敗**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, ReadExcel, ReadDocx, ReadPdf, ReadPPTX, SplitExcelSheets, SplitDocxSections, PdfToImages, ReadImage, WebSearch, WebFetch, DownloadFile, SQLite, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, ReadToolDoc, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/ に成果物を書き出した（または既存ファイルを編集した）
+        next: verify
+      - condition: 追加情報が必要
+        next: process
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ の成果物を確認する。
+
+      確認手順:
+      1. まず Glob で output/ 内のファイル一覧を確認する（既存 Office ファイルの編集の場合はそのファイルも対象）
+      2. 成果物が1つもなければ「修正が必要」と判断し process に差し戻す
+      3. 成果物があれば適切なツール（ReadPdf / ReadExcel / ReadDocx / ReadPPTX / Read 等）で内容を確認し、指示通りか・品質は十分かをチェックする
+      4. 不足や誤りがあれば、`transition({next_step: "process", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号またはシート名・スライド番号など] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - process で最初に着手すべき具体的な修正
+      5. summary は抽象論で終えず、変更ファイル・不足点・期待する修正内容を必ず含める
+      6. 外部仕様や一次情報の確認が必要でも ASK しないこと。process は WebSearch / WebFetch を使えるので、確認すべき論点と修正方針を summary に具体的に書いて差し戻すこと
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/ のファイルを適切なツールで読み、その内容をベースに整形する。
+      - 「output/xxx.xlsx を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「成果物を作成しました」「確認しました」等のステータス表示・メタ説明・内部作業の報告は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 成果物の内容を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+      - 長大な成果物の場合は要点を構造化して提示し、詳細は省略してよい
+      - 補足や注意点があれば末尾に添える
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "process", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, ReadPdf, ReadImage, ReadExcel, ReadDocx, ReadPPTX, ReadToolDoc]
+    default_next: COMPLETE
+    rules:
+      - condition: 成果物がない、または内容に不足・誤りがある
+        next: process

pieces/piece-builder.yaml

@@ -0,0 +1,155 @@
+name: piece-builder
+description: |
+  Piece の設計・作成・編集を行う専用エージェント。
+  ユーザーの要件をヒアリングし、適切な movement 構成・ツール選定・遷移ルールを設計して Piece を作成する。
+  「エージェントを作りたい」「ワークフローを自動化したい」「Piece を作って」などの依頼に対応。
+max_movements: 999
+initial_movement: design
+
+triggers:
+  keywords: [piece, エージェント作成, ワークフロー作成, 自動化, piece作成]
+
+movements:
+  - name: design
+    edit: false
+    persona: architect
+    instruction: |
+      ## Piece 設計フェーズ
+
+      ユーザーが作りたい Piece の要件を整理し、設計を行う。
+
+      ### 手順
+      1. ListPieces で既存の Piece 一覧を確認する（最優先）
+      2. 類似の Piece があれば GetPiece で YAML 定義を取得し、構造を参考にする
+      3. **新規 Piece を作る前に**: 既存 Piece の改良・拡張で要件を満たせないか検討する
+      4. 新規作成が正当化される場合にのみ、以下を整理する:
+         - 目的（何を自動化するか）
+         - movement の構成とステップ間の遷移条件
+         - 各ステップで使うツール（`allowed_tools`）
+         - 入力と出力の形式
+
+      ツールの詳細仕様は ReadToolDoc で確認できる（例: `ReadToolDoc({ name: "SpawnSubTask" })`）。
+
+      ### YAML 構造の制約
+      ```yaml
+      name: 英小文字・数字・ハイフンのみ
+      description: |
+        Piece の説明（LLM が分類に使う。具体的に書くこと）
+      max_movements: 999
+      initial_movement: 最初の movement 名
+
+      triggers:
+        keywords: [関連キーワード]
+
+      movements:
+        - name: ステップ名
+          edit: true/false  # Write/Edit を許可するか
+          persona: 役割名
+          instruction: |
+            このステップで行うこと（WHAT を書く。HOW はツールドキュメントに委ねる）
+          allowed_tools: [使用するツール]
+          default_next: 次のステップ名 or COMPLETE
+          rules:
+            - condition: 遷移条件の説明
+              next: 遷移先
+      ```
+
+      ### Movement・Rules の設計指針
+      - `edit: true` にしないと Write/Edit が LLM に提示されない
+      - `allowed_tools` に載っていないツールは LLM に提示されない — 必要最小限に絞る
+      - `rules` に明示した遷移先のみ LLM が選択できる
+      - `default_next` はコンテキスト上限到達・ASK 上限フォールバックなど機械的用途のみ（LLM の選択肢にならない）
+      - verify movement を設けると品質チェックが可能
+      - ループ検出: 同じ movement への連続訪問が閾値超過で ABORT されるため、A→B→A の無限循環を避ける
+
+      ### Persona / Instruction / Allowed_tools の使い分け
+      - `persona`: そのステップの役割（architect / builder / reviewer など）。LLM の振る舞いのトーンに影響
+      - `instruction`: WHAT を行うかの指示。具体的・明確に書く。ツールの使い方（HOW）は書かない
+      - `allowed_tools`: そのステップで実際に必要なツールのみを列挙
+
+      ## 終了 / 遷移方法
+      - **設計完了 → build へ**: `transition({next_step: "build", summary: "設計内容のサマリ"})`
+      - **ユーザーに確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [ListPieces, GetPiece, ReadToolDoc, Read, Glob, Grep, WebSearch, WebFetch]
+    default_next: build
+    rules:
+      - condition: 設計が完了した
+        next: build
+
+  - name: build
+    edit: false
+    persona: builder
+    instruction: |
+      ## Piece 構築フェーズ
+
+      design フェーズの設計に基づいて Piece を作成・更新する。
+
+      ### 手順
+      1. 設計内容をもとに YAML 定義を組み立てる
+      2. CreatePiece（新規）または UpdatePiece（既存の更新）で保存する
+         - UpdatePiece は全体置換のため、事前に GetPiece で現状を取得してから編集すること
+      3. 保存した Piece を GetPiece で読み返して内容を確認する
+
+      ### 注意事項
+      - name は英小文字・数字・ハイフンのみ
+      - instruction は WHAT を具体的に書く（曖昧な指示は避ける）
+      - allowed_tools には必要なツールを過不足なく列挙する
+      - rules の condition は日本語で明確に書く
+      - `general`、`chat` は削除不可だが更新は可能
+
+      ## 終了 / 遷移方法
+      - **作成完了 → verify へ**: `transition({next_step: "verify", summary: "Piece の概要"})`
+      - **設計レベルの見直しが必要 → design に戻る**: `transition({next_step: "design", summary: "..."})`
+      - **ユーザーに確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [ListPieces, GetPiece, CreatePiece, UpdatePiece, ReadToolDoc, Read, Glob, Grep]
+    default_next: verify
+    rules:
+      - condition: Piece の作成・更新が完了した
+        next: verify
+      - condition: 設計に不備があり再検討が必要
+        next: design
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      ## Piece 検証フェーズ
+
+      作成・更新された Piece の品質を確認する。
+
+      ### 確認手順
+      1. GetPiece で作成した Piece の YAML 定義を取得する
+      2. 以下の観点でチェックする:
+         - name が英小文字・数字・ハイフンのみか
+         - description が具体的で、LLM が分類に使えるレベルか
+         - 各 movement の instruction が具体的で曖昧でないか
+         - allowed_tools に必要なツールが過不足なく含まれているか
+         - rules に全ての遷移先が明示されているか（default_next だけに頼っていないか）
+         - edit: true/false が各 movement の用途に合っているか
+         - ループの可能性がないか（A→B→A が無限に繰り返される構造でないか）
+      3. 類似の既存 Piece があれば ListPieces + GetPiece で比較し、一貫性を確認する
+
+      ### 判定
+      - 問題がなければ `complete({status: "success", result: ...})` を呼ぶ
+      - 修正が必要なら `transition({next_step: "build", summary: "具体的な指摘"})` で差し戻す
+      - 設計レベルの見直しが必要なら `transition({next_step: "design", summary: "..."})` で戻す
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      `complete({status: "success", result: ...})` を呼ぶ。result はそのままユーザーに表示される最終回答。
+      - Piece 名、目的、movement 構成、主要なツールを簡潔にまとめる
+      - 「作成しました」等のメタ説明ではなく、Piece の内容そのものを伝える
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "Piece 概要"})`
+      - build に差し戻し: `transition({next_step: "build", summary: "指摘"})`
+      - design に戻す: `transition({next_step: "design", summary: "..."})`
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, ListPieces, GetPiece, ReadToolDoc]
+    default_next: COMPLETE
+    rules:
+      - condition: 修正が必要
+        next: build
+      - condition: 設計レベルの見直しが必要
+        next: design

pieces/research-sub.yaml

@@ -0,0 +1,110 @@
+name: research-sub
+description: |
+  サブタスク専用の調査ピース。親タスクの decompose から SpawnSubTask で起動される。
+  dig → analyze → verify の 3 ステップで調査を完結させる。
+  さらなるサブタスク分解（SpawnSubTask）は行わない。
+max_movements: 999
+initial_movement: dig
+
+movements:
+  - name: dig
+    edit: true
+    persona: researcher
+    instruction: |
+      ## 最初のステップ: 入力把握と調査計画
+
+      情報収集に着手する前に、調査対象と目的を整理する:
+      1. Glob でワークスペース全体のファイル一覧を確認する（input/ だけでなくルート直下も含む）
+      2. 指示で言及されているファイルがあれば適切なツールで内容を把握する（カタログ参照、詳細は ReadToolDoc）
+      3. 調査対象と目的を整理し、どこから情報を集めるか、何を分析するかを明確にする
+      4. 「今日のニュース」「最新動向」「直近」など時刻依存の調査依頼では、必ず最初のアクションを WebSearch にする
+
+      ## 計画に従って情報を収集する
+
+      WebSearch、WebFetch、ファイル読み込み等で情報を集め、必ず Write で output/ にファイルとして書き出すこと。
+      テキストで回答するだけでは不十分。
+
+      ## 検索の原則（必須）
+
+      - モデルの内部知識だけで情報を書かないこと。主張・事実・数値は必ず WebSearch/WebFetch で裏付けを取る
+      - output/ に既存ファイルがある場合でもその内容を鵜呑みにせず、検索で正確性を確認する
+
+      ## 一次情報へのアクセスと捏造禁止（厳守）
+
+      - YouTube 動画の内容を調査する場合は、必ず GetYouTubeTranscript で字幕を取得してから作業する
+      - 一次情報に直接アクセスできなかった場合:
+        - Web 検索の断片的な情報から内容を推測・捏造してはならない
+        - アクセスできなかった旨を明記し、取得できた範囲の情報のみで成果物を作成する
+
+      ## 画像・ビジュアル素材の収集（必須）
+
+      調査中は画像・グラフ・図表を積極的に収集し、output/images/ に保存すること。
+
+      ## 終了 / 遷移方法
+      - **次の analyze へ**: `transition({next_step: "analyze"})`
+      - **追加調査のため同じ dig を続行**: `transition({next_step: "dig"})`
+      - **対象が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch, BrowseWeb, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, BatchReviewTextWithLLM, MergeReviewedResults, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, XSearch, XUserPosts, XPostDetail, XFetchCardMedia, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, 'mcp__*']
+    default_next: analyze
+    rules:
+      - condition: output/ に情報を書き出した
+        next: analyze
+      - condition: 追加調査が必要
+        next: dig
+
+  - name: analyze
+    edit: true
+    persona: analyst
+    instruction: |
+      収集した情報を分析し、調査レポートを output/ に作成する。
+      重要なポイント、トレンド、結論をまとめる。
+      必ず Write ツールで output/ にレポートファイルを書き出すこと。
+      前のステップから指摘事項がある場合は、それに対応すること。
+
+      ## 検索の原則（必須）
+
+      - レポートに記載する事実・数値・主張は、dig で収集した検索結果に基づくこと
+      - 情報が不足している場合は、ここでも追加の WebSearch/WebFetch を行い裏付けを取る
+      - 「これまでのレビュー指摘」がある場合は、各項目を漏れなく解消すること
+
+      ## 画像の活用（必須）
+
+      output/images/ に画像がある場合は、必ずレポートの該当箇所に埋め込む:
+      `![説明](./images/ファイル名.png)`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch, BrowseWeb, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, BatchReviewTextWithLLM, MergeReviewedResults, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, XSearch, XUserPosts, XPostDetail, XFetchCardMedia, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/ にレポートを書き出した
+        next: verify
+      - condition: 追加調査が必要
+        next: dig
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ のレポートを確認する。
+
+      確認手順:
+      1. まず Glob で output/ 内のファイル一覧を確認する
+      2. output/ にファイルが1つもなければ「不足がある」と判断し analyze に差し戻す
+      3. ファイルがあれば Read で内容を確認し、網羅性・正確性・分かりやすさをチェックする
+      4. 不足があれば analyze に差し戻す
+
+      ## 合格時
+
+      合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザー（親タスク）に返される。
+      - 調査結果・発見・結論を簡潔にまとめる
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+
+      ## 終了方法
+      - 合格: `complete({status: "success", result: "調査結果のまとめ"})`
+      - 修正必要: `transition({next_step: "analyze", summary: "差し戻し指摘"})`
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch, ReadImage, AnnotateImage, ReadPdf, ReadExcel, ReadDocx, ReadPPTX, SearchNotes, ReadNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache]
+    default_next: COMPLETE
+    rules:
+      - condition: output/ にファイルがない、または内容に不足がある
+        next: analyze

pieces/research.yaml

@@ -0,0 +1,206 @@
+name: research
+description: |
+  Web検索やファイル読み込みによる情報収集と、収集情報の分析・レポート作成。
+  複数ソースからの調査、比較分析、トレンド調査、文献サーベイに適する。
+  選ぶべき場合: タスクの主目的が「調べること」「情報を集めて整理すること」
+  選ぶべきでない場合: 既にデータがあり加工するだけ、Officeファイルの操作が主目的
+triggers:
+  keywords: ["調べて", "調査", "リサーチ", "分析して", "比較して", "まとめて", "レポート"]
+max_movements: 999
+initial_movement: dig
+
+movements:
+  - name: decompose
+    edit: false
+    persona: orchestrator
+    instruction: |
+      入力把握で決めた並列調査計画に従い、各テーマをサブタスクとして登録する。
+
+      手順:
+      1. 入力把握で立てた調査テーマを思い出す（ファイル読み込みは不要）
+      2. 各テーマに対して SpawnSubTask を呼び出す（2〜5 個程度、piece は "research-sub"）
+      3. 全サブタスクの登録が完了したら WAIT_SUBTASKS に遷移する
+
+      instruction には「何を調べて output/result.md にどう書くか」を具体的に記述する
+      （概要・主要な特徴・数値や事例・まとめと考察 など、構成を明示）。
+    allowed_tools: [SpawnSubTask]
+    default_next: aggregate
+    rules:
+      - condition: 全サブタスクを SpawnSubTask で登録し終えた
+        next: WAIT_SUBTASKS
+      - condition: 全てのサブタスクを登録し終えた（SpawnSubTask不可の場合は自分で調査を完了した）
+        next: aggregate
+
+  - name: aggregate
+    edit: true
+    persona: analyst
+    instruction: |
+      各サブタスクの調査結果が subtasks/ ディレクトリに格納されている。
+
+      手順:
+      1. Glob で subtasks/*/result.md と subtasks/*/output/ を確認する
+      2. 各 result.md と追加成果物を Read で読み込む
+      3. 全結果を統合して output/report.md に最終レポートを作成する
+         - 各テーマの主要な知見を統合（矛盾・重複は整理）
+         - 比較・対照が必要なら表形式で整理
+         - 全体のまとめと考察を付ける
+      4. output/report.md を書き終えたら verify へ遷移する
+    allowed_tools: [Read, Glob, Grep, Write, Edit, SearchNotes, ReadNote, WriteNote, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/report.md に統合レポートを作成した
+        next: verify
+
+  - name: dig
+    edit: true
+    persona: researcher
+    instruction: |
+      ## 最初のステップ: 入力把握と調査計画
+
+      情報収集に着手する前に、調査対象と目的を整理する:
+      1. Glob でワークスペース全体のファイル一覧を確認する（input/ だけでなくルート直下も含む）
+      2. 指示で言及されているファイルがあれば適切なツールで内容を把握する（カタログ参照、詳細は ReadToolDoc）
+      3. 調査対象と目的を整理し、どこから情報を集めるか、何を分析するかを明確にする
+      4. 「今日のニュース」「最新動向」「直近」など時刻依存の調査依頼では、必ず最初のアクションを WebSearch にする
+
+      ## 並列分解の判断
+
+      decompose を積極的に検討するケース:
+      - 複数の独立した調査対象がある（例: 3社の比較、複数技術の比較）
+      - 各調査が互いに依存せず、結果を最後に統合すればよい
+      - 全体を 1 回の dig → analyze で処理すると context が溢れるリスクがある
+
+      decompose を使わないケース:
+      - 単一テーマの調査
+      - 各ステップが前のステップの結果に依存する逐次的な調査
+
+      ## 計画に従って情報を収集する
+
+      WebSearch、WebFetch、ファイル読み込み等で情報を集め、必ず Write で output/ にファイルとして書き出すこと。
+      テキストで回答するだけでは不十分。
+
+      ## 検索の原則（必須）
+
+      - モデルの内部知識だけで情報を書かないこと。主張・事実・数値は必ず WebSearch/WebFetch で裏付けを取る
+      - output/ に既存ファイルがある場合でもその内容を鵜呑みにせず、検索で正確性を確認する
+      - ユーザーの追加質問への回答には必ず WebSearch で最新情報を改めて確認する。前回の調査結果に依存して検索を省略しない
+
+      ## 一次情報へのアクセスと捏造禁止（厳守）
+
+      - YouTube 動画の内容を調査する場合は、必ず GetYouTubeTranscript で字幕を取得してから作業する
+      - 一次情報（動画字幕、論文本文、ページ本文等）に直接アクセスできなかった場合:
+        - Web 検索の断片的な情報から内容を推測・捏造してはならない
+        - アクセスできなかった旨を明記し、取得できた範囲の情報のみで成果物を作成する
+        - 推測部分は「推測」と明示する
+      - 二次情報（ブログ記事、要約サイト等）から得た情報は、一次情報ではないことを明記する
+
+      ## 画像・ビジュアル素材の収集（必須）
+
+      調査中は画像・グラフ・図表を積極的に収集し、output/images/ に保存すること。
+      テキストだけの調査で終わらせない。ビジュアル素材がレポートの品質を大きく左右する。
+
+      収集すべきもの:
+      - 記事・ページ内のグラフ・チャート・比較表の画像
+      - 製品・サービスのスクリーンショットや公式画像
+      - データの可視化（統計グラフ、トレンド図等）
+      - 関連する図解・インフォグラフィック
+
+      収集した画像はレポートの Markdown から相対パスで参照する: `![説明](./images/ファイル名.png)`
+
+      ## 終了 / 遷移方法
+      - **次の analyze へ**: `transition({next_step: "analyze"})`
+      - **並列分解 → decompose へ**: `transition({next_step: "decompose"})`
+      - **追加調査のため同じ dig を続行**: `transition({next_step: "dig"})`
+      - **対象が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch, BrowseWeb, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, BatchReviewTextWithLLM, MergeReviewedResults, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, XSearch, XUserPosts, XPostDetail, XFetchCardMedia, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, 'mcp__*']
+    default_next: analyze
+    rules:
+      - condition: 2つ以上の独立した調査テーマがあり、並列分解が効率的と判断した
+        next: decompose
+      - condition: output/ に情報を書き出した
+        next: analyze
+      - condition: 追加調査が必要
+        next: dig
+
+  - name: analyze
+    edit: true
+    persona: analyst
+    instruction: |
+      収集した情報を分析し、調査レポートを output/ に作成する。
+      重要なポイント、トレンド、結論をまとめる。
+      必ず Write ツールで output/ にレポートファイルを書き出すこと。
+      前のステップから指摘事項がある場合は、それに対応すること。
+
+      ## 検索の原則（必須）
+
+      - レポートに記載する事実・数値・主張は、dig で収集した検索結果に基づくこと
+      - 情報が不足している場合は、ここでも追加の WebSearch/WebFetch を行い裏付けを取る。モデルの内部知識だけで補完しない
+      - ユーザーの追加質問への回答には必ず WebSearch で最新情報を改めて確認する。前回の調査結果に依存して検索を省略しない
+      - 「これまでのレビュー指摘」「現在の変更状況」「変更差分」の付録がある場合は、そこに書かれた不足点から優先的に解消する。指摘事項は「問題点」「期待する修正」「合格基準」まで含めて渡されるので、各項目を漏れなく解消すること
+
+      ## 画像の活用（必須）
+
+      output/images/ に画像が保存されている場合は、必ずレポートの該当箇所に埋め込む:
+      `![説明](./images/ファイル名.png)`
+      画像があるのにテキストだけのレポートにしないこと。
+      レポート作成中に追加で必要な図・グラフを見つけた場合も DownloadFile で収集して埋め込む。
+
+    allowed_tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch, BrowseWeb, DownloadFile, ReadImage, AnnotateImage, ReadPdf, PdfToImages, BatchReviewTextWithLLM, MergeReviewedResults, SearchPlaces, GetDirections, ReverseGeocode, GetYouTubeTranscript, SearchYouTube, SearchAmazon, TranscribeAudio, SearchKnowledge, ListNamespaces, ListDocuments, XSearch, XUserPosts, XPostDetail, XFetchCardMedia, SearchNotes, ReadNote, WriteNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/ にレポートを書き出した
+        next: verify
+      - condition: 追加調査が必要
+        next: dig
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ のレポートを確認する。
+
+      確認手順:
+      1. まず Glob で output/ 内のファイル一覧を確認する
+      2. output/ にファイルが1つもなければ「不足がある」と判断し analyze に差し戻す
+      3. ファイルがあれば Read で内容を確認し、網羅性・正確性・分かりやすさをチェックする
+      4. 不足があれば、`transition({next_step: "analyze", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号または項目名] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - 差し戻し先で最初に着手すべき具体的な作業
+      5. summary は抽象論で終えず、変更ファイル・不足点・期待する修正内容を必ず含める
+      6. 技術的正確性の再確認が必要な場合は、まず自分で WebSearch / WebFetch で簡易チェックする。深い追加調査が必要な場合は、確認すべき URL・検索語・論点を summary に具体的に書いて analyze に差し戻す
+
+      追加チェック（追加質問への回答）:
+      - ユーザーの追加質問（前回タスクへの補足・深掘り）への回答が含まれる場合、その内容に WebSearch/WebFetch による検索の裏付けがあるか確認する。内部知識だけで回答している形跡がある場合は「追加質問への回答に検索根拠が不足」として analyze に差し戻す
+
+      追加チェック（画像）:
+      - output/images/ に画像があるのにレポートに `![` が一つもない場合、
+        画像埋め込み漏れとして analyze に差し戻す
+
+      ## 合格時のユーザーへの返答（complete ツール）
+
+      合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/ のレポートを Read で読み、その内容をベースに整形する。
+      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「レポートを作成しました」「確認しました」等のステータス表示・メタ説明・内部作業の報告は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 調査結果・発見・結論を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+      - 長大なレポートの場合は要点を構造化して提示し、詳細は省略してよい
+      - 補足や今後の検討事項があれば末尾に添える
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "analyze", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch, ReadImage, AnnotateImage, ReadPdf, ReadExcel, ReadDocx, ReadPPTX, SearchNotes, ReadNote, SearchMicrosoftLearn, FetchMicrosoftLearn, SearchMicrosoftLearnCache, RefreshMicrosoftLearnCache]
+    default_next: COMPLETE
+    rules:
+      - condition: output/ にファイルがない、または内容に不足がある（追加質問への回答に検索根拠が不足している場合も含む）
+        next: analyze

pieces/slide.yaml

@@ -0,0 +1,192 @@
+name: slide
+description: |
+  pptxgenjs を使って、PowerPoint で再編集可能なクオリティの高い .pptx を生成する。
+  プレゼン資料、LT 資料、講演スライド、提案資料、報告スライドをゼロから組み立てる場合に選ぶ。
+  選ぶべき場合: ゼロからスライド (.pptx) を作る
+  選ぶべきでない場合: 既存 .pptx の解析・編集 (→ office-process)、文書作成 (→ general)
+triggers:
+  keywords:
+    - スライド
+    - slide
+    - プレゼン
+    - presentation
+    - 講演資料
+    - LT資料
+    - ライトニングトーク
+    - 資料作成
+    - パワポ
+    - powerpoint
+    - pptx
+    - 提案資料
+    - 報告書スライド
+max_movements: 999
+initial_movement: process
+
+movements:
+  - name: process
+    edit: true
+    persona: slide-designer
+    instruction: |
+      ## 最初のステップ: 入力把握と構成立案
+
+      1. Glob でワークスペース全体 (input/ + ルート直下) のファイル一覧を確認する
+      2. ユーザー指示で言及されている素材 (PDF / Word / 画像 / テキスト) を Read する
+      3. 外部画像が必要なら DownloadFile で input/ に保存してから使う
+      4. スライド構成 (タイトル / 目次 / 本編 / まとめ、8〜20 枚目安) を立てる
+
+      ## テーマ選択 (SetTheme で 1 度だけ呼ぶ)
+
+      タスクの雰囲気から preset を選び、必要なら overrides で色やフォントを上書きする。
+
+      - `corporate-blue` : 営業・社内提案・株主向け
+      - `minimal-mono`   : 既定。汎用・技術発表
+      - `vibrant`        : LT・勉強会
+      - `academic`       : 学会・論文発表
+      - `dark`           : デモ・製品ローンチ
+      - `warm-paper`     : クリエイティブ系・教育
+
+      例:
+        SetTheme({ preset: "corporate-blue" })
+        SetTheme({ preset: "minimal-mono", overrides: { primary: "#1A5490", heading_font: "Yu Gothic UI" } })
+
+      ## スライド組み立て (AddSlide を順に呼ぶ)
+
+      使えるレイアウト: title / section / bullets / two-column / image-right /
+      image-left / image-full / table / chart / quote / closing / custom
+
+      推奨パターン:
+      - 1 枚目: layout="title"
+      - 2 枚目: layout="bullets" (目次) または section
+      - 本編: 内容に応じて選択
+        * 単純な箇条書き → bullets
+        * 比較 → two-column
+        * 数値データ → chart (bar/line/pie/doughnut/area/scatter)
+        * 一覧表 → table
+        * 画像が主役 → image-full / image-right / image-left
+        * 章の区切り → section
+        * 引用 → quote
+      - 最後: layout="closing"
+      - notes フィールドにスピーカーノートを入れる (推奨)
+      - 同じ layout を 5 枚以上連続させない (単調になる)
+
+      ## 自由配置 (custom layout)
+
+      テンプレに収まらないスライドは custom で elements 配列を直接渡す:
+        AddSlide({
+          layout: "custom",
+          content: { elements: [
+            { type:"text", text:"...", x:1, y:1, w:8, h:0.8, options:{font_size:28, bold:true} },
+            { type:"shape", shape:"roundRect", x:1, y:3, w:4, h:2, options:{fill:"#5EE2FF"} },
+            { type:"image", path:"input/foo.png", x:6, y:3, w:6, h:3 }
+          ] }
+        })
+
+      座標は inch 単位、安全領域は x=0.5, y=0.5, w=12.33, h=6.5。
+
+      ## 完了
+
+      最後に必ず BuildPptx を呼ぶ:
+        BuildPptx({ output: "output/slides.pptx" })
+
+      ## 注意
+
+      - `output/.slides.json` は内部状態ファイル。Write / Edit で直接編集しないこと
+      - 全枚やり直す場合のみ ResetSlides() を呼ぶ
+      - PDF が必要な場合: ユーザーに PowerPoint / Keynote / LibreOffice で開いて Export してもらう。
+        このツールは PDF 出力に非対応
+
+      ## 終了 / 遷移方法
+      - **次の verify へ**: `transition({next_step: "verify", summary: "生成したファイル一覧"})`
+      - **追加情報が必要で同じ process を続行**: `transition({next_step: "process"})`
+      - **題材・構成が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗 (pptxgenjs エラー等)**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools:
+      - Read
+      - Write
+      - Edit
+      - Glob
+      - Grep
+      - SetTheme
+      - AddSlide
+      - BuildPptx
+      - ResetSlides
+      - WebSearch
+      - WebFetch
+      - DownloadFile
+      - ReadImage
+      - ReadPdf
+      - ReadDocx
+      - ReadExcel
+      - ReadPPTX
+      - SearchKnowledge
+      - ListDocuments
+      - ListNamespaces
+      - ReadToolDoc
+      - 'mcp__*'
+    default_next: verify
+    rules:
+      - condition: SetTheme + AddSlide × N + BuildPptx を実行し output/slides.pptx を生成済み
+        next: verify
+      - condition: 追加情報が必要
+        next: process
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      output/ の成果物を確認する。
+
+      確認手順:
+      1. Glob で output/ 内のファイル一覧を取得
+      2. output/slides.pptx が存在し、ファイルサイズ > 0 か確認
+      3. output/.slides.json を Read して以下をチェック:
+         - スライド枚数が指示通り (極端な過不足、空スライドがないか)
+         - 1 枚目が layout="title"
+         - 最後が layout="closing" (または妥当な締めスライド)
+         - 同じ layout の連続が 5 枚以上ないか
+         - chart レイアウトの data.categories / data.series が空でないか
+         - 画像参照パス (image-* / custom の image elements) が input/ または output/ に実在するか
+         - notes (スピーカーノート) が主要スライドに付いているか
+      4. .pptx 本体はバイナリなので存在確認のみ (内容は .slides.json で検証)
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了 (done/failed/skipped)
+      していることを確認する。remaining が 0 でないまま完了してはならない。
+
+      ## 差し戻し時の transition.summary
+
+      不足や誤りがあれば `transition({next_step: "process", summary: ...})` で差し戻す。summary は次の形式:
+
+      [判定] needs_fix
+      ## 問題点
+      - [ファイル名] 何が問題か
+      ## 期待する修正
+      - 何をどう直すべきか
+      ## 合格基準
+      - 再レビューで何を確認するか
+      ## 次にやること
+      - process で最初に着手すべき具体的な修正
+
+      ## 合格時のユーザーへの返答 (complete ツール)
+
+      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。
+
+      - 【厳守】「✅ 完了」「成果物を作成しました」等のメタ説明は書かない。1 行目から本題
+      - 生成したファイル (output/slides.pptx) を明記
+      - 使ったテーマ・スライド枚数を明記
+      - スライド構成 (タイトル + 章立て / 主要な論点) を箇条書きで伝える
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "process", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - ReadToolDoc
+    default_next: COMPLETE
+    rules:
+      - condition: 成果物が不足または内容に誤りがある
+        next: process

pieces/sns-research.yaml

@@ -0,0 +1,147 @@
+name: sns-research
+description: |
+  X (Twitter)・Reddit・Hacker News などの SNS から意見・評判・議論を収集しレポートにまとめる。
+  選ぶべき場合: 「Redditで何と言われているか」「Xでの反応」など SNS の声を調べたいとき
+  選ぶべきでない場合: 一般的なWeb調査、ニュース記事の収集、ドキュメント処理
+triggers:
+  keywords: ["Reddit", "reddit", "Twitter", "Hacker News", "HackerNews", "サブレディット", "subreddit"]
+max_movements: 999
+initial_movement: gather
+
+movements:
+  - name: gather
+    edit: true
+    persona: researcher
+    instruction: |
+      ## 調査計画
+
+      着手前に調査計画を立てる:
+      1. 調査対象と対象 SNS を決定する
+      2. 検索クエリ案を複数考える（日本語・英語の両方を検討）
+      3. verify からの差し戻しがある場合は、不足点を優先的に解消する
+
+      計画に従って SNS から情報を収集し、Write で output/raw/ にテキストファイルとして書き出す。
+
+      ## SNS 別の収集方針
+
+      ### X (Twitter)
+      - キーワードで広く拾う → XSearch
+      - 特定アカウントの発言を追う → XUserPosts
+      - 議論の流れ・リプライツリーまで欲しい → XPostDetail
+
+      ### Reddit
+      BrowseWeb で必ず **old.reddit.com** を使う（軽量でテキスト抽出しやすい）。
+      - 検索: `old.reddit.com/search?q=キーワード`
+      - スレッド: `old.reddit.com/r/{サブレディット}/comments/...`
+
+      ### Hacker News
+      WebFetch で Algolia API を使う。
+      - 検索: `https://hn.algolia.com/api/v1/search?query=キーワード`
+      - 記事詳細: `https://hn.algolia.com/api/v1/items/{id}`
+
+      ## ファイル命名規則
+      `output/raw/{platform}-{query-slug}.txt`
+      例: reddit-ollama-vs-vllm.txt, x-ollama-review.txt, hn-local-llm.txt
+
+      ## SNS 調査の原則
+      モデルの内部知識だけで情報を書かないこと。必ず実際の SNS データを収集する。
+      検索ヒットがゼロだった場合も、その事実を raw ファイルに記録する（捏造しない）。
+
+      ## 画像・スクリーンショットの収集
+      SNS 投稿には画像・グラフが含まれることが多い。重要なビジュアルは DownloadFile で
+      `output/images/{platform}-{slug}.png` に保存する。
+
+      ## 終了 / 遷移方法
+      - **次の analyze へ**: `transition({next_step: "analyze"})`
+      - **追加収集のため同じ gather を続行**: `transition({next_step: "gather"})`
+      - **対象が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [XSearch, XUserPosts, XPostDetail, XFetchCardMedia, BrowseWeb, WebFetch, WebSearch, Read, Write, Edit, Glob, Grep, DownloadFile, SearchKnowledge, ListNamespaces, ListDocuments, SearchNotes, ReadNote, 'mcp__*']
+    default_next: analyze
+    rules:
+      - condition: 追加収集が必要（別のSNS、追加クエリ等）
+        next: gather
+      - condition: 十分な情報を収集した
+        next: analyze
+
+  - name: analyze
+    edit: true
+    persona: analyst
+    instruction: |
+      output/raw/ の収集データを読み込み、分析してレポートを作成する。
+
+      手順:
+      1. Glob で output/raw/ 内のファイル一覧を確認
+      2. 各ファイルを Read で読み込む
+      3. 重要な意見・トレンド・共通見解を抽出
+      4. ポジティブ/ネガティブな意見を分類
+      5. output/report.md にレポートを書き出す
+
+      ## レポートの構成
+      - トピック概要
+      - SNS 別の主な意見（X / Reddit / HN それぞれ）
+      - 共通する見解・分岐する意見
+      - まとめ
+
+      ## 画像の活用
+      output/images/ に画像がある場合は必ずレポートに埋め込む:
+      `![説明](./images/ファイル名.png)`
+
+      情報が不足している場合は gather に戻る（追加の検索クエリを明示すること）。
+      verify からの差し戻しがある場合は、指摘された不足点・期待する修正を優先的に解消すること。
+
+    allowed_tools: [Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, DownloadFile, BatchReviewTextWithLLM, MergeReviewedResults, SearchKnowledge, ListNamespaces, ListDocuments, SearchNotes, ReadNote, 'mcp__*']
+    default_next: verify
+    rules:
+      - condition: output/report.md にレポートを書き出した
+        next: verify
+      - condition: 情報が不十分で追加収集が必要
+        next: gather
+
+  - name: verify
+    edit: false
+    persona: supervisor
+    instruction: |
+      output/ のレポートを確認する。
+
+      確認手順:
+      1. Glob で output/ 内のファイル一覧を確認する
+      2. output/report.md がなければ「不足がある」と判断し analyze に差し戻す
+      3. ファイルがあれば Read で内容を確認し、網羅性・正確性・分かりやすさをチェックする
+      4. 不足があれば、`transition({next_step: "analyze", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:行番号または項目名] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - 差し戻し先で最初に着手すべき具体的な作業
+      5. summary は抽象論で終えず、具体的な不足点・期待する修正内容を必ず含める
+
+      追加チェック（画像）:
+      - output/images/ に画像があるのにレポートに `![` が一つもない場合、
+        画像埋め込み漏れとして analyze に差し戻す
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。output/report.md を Read で読み、その内容をベースに整形する。
+      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
+      - 【厳守】「✅ 完了」「レポートを作成しました」「確認しました」等のステータス表示・メタ説明は一切書かない。1行目からいきなり本題の内容を書き始めること
+      - 調査結果・発見・結論を会話調で分かりやすく伝える
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "analyze", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep]
+    default_next: COMPLETE
+    rules:
+      - condition: output/ にファイルがない、または内容に不足がある
+        next: analyze

pieces/ssh-console.yaml

@@ -0,0 +1,76 @@
+name: ssh-console
+description: |
+  AI と人間が共有する SSH コンソール。タスクに 1 つの PTY セッションを開き、
+  両者がコマンドを打ち、出力を見られる。長時間の対話作業、TUI が必要な
+  操作 (vim/top/less/tmux 等)、複数ラウンドの調査に向く。
+
+  選ぶべき場合: 「リモートサーバーで色々確認したい」「ログを tail しながら作業」
+  「対話的に shell を触りたい」
+  選ぶべきでない場合: 1 コマンドの単発実行 (ssh-ops piece が適切)、ファイル転送だけ
+
+  事前条件:
+  - admin が config.yaml で ssh.enabled: true / ssh.console.enabled: true を設定済み
+  - 利用する SSH 接続が登録され、TOFU host key 検証が完了している
+  - ジョブ owner に接続への grant がある
+triggers:
+  keywords: ["対話", "shell", "console", "ターミナル", "tmux", "vim", "tail", "対話的"]
+max_movements: 80
+initial_movement: interact
+
+movements:
+  - name: interact
+    edit: true
+    persona: ops-operator
+    instruction: |
+      ## 詳細ドキュメント (必ず最初に読む)
+      ReadToolDoc({name: "SshConsoleEnsure"}) で 3 ツール (Ensure / Send / Snapshot) の
+      完全な仕様と典型 flow が見られる。引数と return shape、TUI 操作のコツ、エラー
+      コードのリカバリ手順まで網羅。alias なので SshConsoleSend / SshConsoleSnapshot
+      でも同じ doc が返る。SshListConnections は ReadToolDoc({name: "SshListConnections"})。
+
+      ## 標準 flow
+      1. タスク本文を読み、どのリモートホストでどんな作業をするか把握する
+      2. connection_id (UUID) がタスク本文に無ければ SshListConnections({}) で発見する
+         - **必ず id フィールドを使う**。label ("terminal" など) や host ("192.168.1.x" など) を connection_id として渡してはいけない
+         - UUID を覚えていないからといって**勝手に UUID をでっち上げない** — 必ず SshListConnections で確認する
+      3. SshConsoleEnsure({connection_id}) でセッションを開く (冪等)
+      4. SshConsoleSend / SshConsoleSnapshot を呼ぶ
+         - **2 回目以降の呼び出しでは connection_id を省略するのが推奨** (active session が自動採用される)
+         - ジョブ間で UUID を覚え直す必要がなくなる
+
+      ## 使い方の要点
+      - 1 行コマンド: SshConsoleSend({input: "ls -la\n"})  — connection_id は省略
+      - 連続入力 (heredoc / 複数行 stdin): input に \n 含めて送る
+      - TUI に入る: SshConsoleSend({input: "vim test.txt\n", wait_ms: 1000}) → SshConsoleSnapshot で画面確認
+      - control 文字: \x03 Ctrl-C / \x04 Ctrl-D / \x1b Esc / \t Tab を input にそのまま含めて送れる
+      - vim 抜ける: SshConsoleSend({input: "\x1b:q!\n"})
+
+      ## エラーリカバリ
+      - "this task already has an active session on connection X" → 表示されている X を connection_id に使う (or 省略する)。
+        本当に別接続に切り替えたいときだけ SshConsoleEnsure({connection_id, force_replace: true})
+      - "this task has an active session on connection X, not Y" → 同上 (Send/Snapshot 側のエラー)
+      - "no live session for this task" → 初回 ensure が必要。SshConsoleEnsure({connection_id}) を呼ぶ
+
+      ## ファイル転送 (SFTP, PTY とは独立)
+      - 設定ファイルを置いて反映したい / リモートのログや成果物を手元で解析したい場合は
+        SshUpload / SshDownload を使う。これらは SFTP 経路で動き、active console session
+        とは別チャンネルなので PTY を閉じる必要はない (転送後に SshConsoleSend で
+        リロードコマンドを送ればよい)
+      - リモートパスは接続の remote_path_prefix 配下のみ。ローカルパスは workspace の
+        output/ または input/ 配下を使う。詳細・エラーコードは ReadToolDoc({name: "SshUpload"})
+        / ReadToolDoc({name: "SshDownload"})
+
+      ## 注意
+      - shell 状態 (cd / env / foreground プロセス) はタスク内で維持される。毎ターン cd し直す必要なし
+      - 機密値はコマンド文字列に直接書かない (audit log に hash で残る)
+      - 大量出力で screen_after が切れた場合は SshConsoleSnapshot({kind: "scrollback"}) で全文取得
+      - command_rejected が出たら admin に許可パターン追加を相談する (ローカルで回避してはいけない)
+
+      ## 終了
+      - 完了: complete({status: "success", result: "..."})
+      - 中断: complete({status: "aborted", abort_reason: "..."})
+      - 確認待ち: complete({status: "needs_user_input", missing_info: "..."})
+    allowed_tools: [SshConsoleEnsure, SshConsoleSend, SshConsoleSnapshot, SshUpload, SshDownload, SshListConnections, Read, Write, Bash, Glob, Grep]
+    allowed_ssh_connections: ['*']
+    default_next: COMPLETE
+    rules: []

pieces/ssh-ops.yaml

@@ -0,0 +1,131 @@
+name: ssh-ops
+description: |
+  SSH 経由でリモートホストに対するオペレーションを実行する。
+  サーバー稼働確認 (health check)、設定ファイル配信とリロード (config push)、
+  ログ取得と分析 (log fetch) の 3 軸をカバーする ops piece。
+
+  選ぶべき場合: タスクが「SSH で〜したい」「リモートサーバーで〜を実行」「サーバーから〜を取得」等
+  選ぶべきでない場合: ローカル作業のみ、Web 調査のみ、Office 加工のみ
+
+  事前条件:
+  - admin が `config.yaml` の `ssh.enabled: true` を設定済み
+  - 利用する SSH 接続が登録され、TOFU host key 検証が完了
+    (Settings → User Folder → SSH Connections → 該当接続 → Test)
+  - ジョブ owner に接続への grant がある (private は owner 自身、global は admin の grant)
+
+  詳細: docs/ssh.md (operator runbook) と docs/tools/ssh-tools.md (LLM 向け)
+triggers:
+  keywords: ["SSH", "リモート", "サーバー", "デプロイ", "ヘルスチェック", "ログ取得", "remote"]
+max_movements: 50
+initial_movement: execute
+
+movements:
+  - name: execute
+    edit: true
+    persona: ops-operator
+    instruction: |
+      ## 最初のステップ: タスク把握と接続の選定
+
+      1. Glob で input/ と output/ の現状を確認する
+      2. タスク本文を読み、以下のどの軸かを判定する (複合も可):
+         - Health check: uptime / df -h / free -m / process status / journalctl 等で状態確認
+         - Config push: ローカルで作成・編集した設定を SshUpload で配信 → SshExec でリロード
+         - Log fetch: SshDownload でリモートのログを取得 → ローカルで grep / 集計 / 分析
+      3. タスクで指定された SSH 接続 ID を確認する。指定が無く接続候補が複数ある場合は
+         `complete({status: "needs_user_input", missing_info: "どの SSH 接続を使うか"})` で確認する
+
+      ## SshExec の使い方
+
+      - 単発コマンド: `SshExec({connection_id, command})`
+      - output は JSON envelope (`{stdout, stderr, exit_code, truncated, ...}`)。
+        `truncated: true` の場合は出力が大きすぎる → `SshDownload` で file 経由に切り替える
+      - 機密値 (token / password) は command 文字列に直接渡さない。リモート側の env や config に置く
+      - 接続ごとに deny-list / allow-list が設定されていることがある。`command_rejected` エラーは
+        admin に許可パターン追加を相談する (ローカルで回避してはいけない)
+
+      ## SshUpload / SshDownload の使い方
+
+      - リモートパスは接続の `remote_path_prefix` 配下のみ書き換え可能。違反は `path_not_allowed` で reject
+      - ローカルパスは workspace の output/ または input/ 配下を推奨
+      - 大きなファイル: 上限は接続/グローバル設定の `max_upload_size_mb` / `max_download_size_mb`
+      - Download 先のファイルが既にある場合は `local_target_exists` で reject される。
+        旧版を消すかリネームしてから再実行する
+
+      ## エラーハンドリング (詳細は docs/tools/ssh-tools.md の error code 表)
+
+      - `host_key_not_verified`: TOFU 未完了。
+        `complete({status: "needs_user_input", missing_info: "SSH 接続 <id> の host key を UI で検証してください (Settings → User Folder → SSH Connections → Test)"})` で停止する
+      - `host_key_mismatch`: MITM 疑い。**自動でリトライしない**。
+        `complete({status: "aborted", abort_reason: "host_key_mismatch: <details>"})` で停止する
+      - `abuse_locked`: 連続失敗で接続がロック。
+        `complete({status: "needs_user_input", missing_info: "接続が <until> までロックされています。admin に force-unlock を依頼してください"})` で停止する
+      - `no_grant` / `access_denied`: 権限不足。admin に grant 追加を依頼するよう user に報告して停止する
+      - `connect_timeout` / `auth_failed` 等の一時失敗: 同じ command を最大 2 回まで再試行。
+        それ以上は `complete({status: "aborted", abort_reason: "..."})`
+
+      ## 成果物
+
+      ops の結果は output/report.md にまとめる。**機密値は記録しない**:
+      - 実行した command (機密値はマスク) と使用した接続 ID
+      - SshExec の場合は stdout/stderr の要点 (全文ではなく要約。重要な行のみ転載)
+      - SshUpload/SshDownload の場合は転送したファイル名 + サイズ
+      - 観測した状態 / 異常があれば項目立てて記述
+      - 推奨アクション (異常があれば「再起動を提案」等) または「異常なし」の明示
+
+      ## 終了 / 遷移方法
+
+      - **次の verify へ**: `transition({next_step: "verify"})`
+      - **必要情報不足で停止**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **致命的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [SshExec, SshUpload, SshDownload, SshListConnections, Read, Write, Bash, Glob, Grep]
+    allowed_ssh_connections: ['*']
+    default_next: verify
+    rules:
+      - condition: output/report.md に ops 結果をまとめた
+        next: verify
+
+  - name: verify
+    edit: false
+    persona: reviewer
+    instruction: |
+      ops 結果を確認する。
+
+      確認手順:
+      1. Glob で output/report.md の存在を確認する
+      2. 報告書が無い、または内容が抽象論だけで実行結果が記載されていない場合は execute に差し戻す
+      3. Read で report.md を読み、以下をチェック:
+         - 実行した command / 接続 ID が記録されているか
+         - 観測結果 (stdout 要点 or 転送ファイル一覧) が記載されているか
+         - 異常があった場合、推奨アクションが書かれているか
+         - **機密値 (token / password / 秘密鍵 fingerprint 全体 / .env 内容等) が漏れていないか**
+      4. 不足があれば `transition({next_step: "execute", summary: ...})` で差し戻す:
+         [判定] needs_fix
+         ## 問題点
+         - [報告書の項目] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - execute で最初に着手すべき具体的な作業
+      5. **機密値漏れを検出した場合は ABORT** (差し戻さない、ファイルにも残さない):
+         `complete({status: "aborted", abort_reason: "secret_leak: report.md contained <field> credential"})`
+
+      ## 合格時のユーザーへの返答
+
+      `complete({status: "success", result: ...})` で output/report.md の要点を会話調で返す。
+      result そのものが user に表示される最終回答 (「report.md を確認」のような参照ではなく内容を書く)。
+      - 1 行目からいきなり本題: 「✅ 完了」等のメタ文言は禁止
+      - 観測した状態 + 推奨アクションを構造化して提示
+      - 異常無しなら明示する
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "execute", summary: "差し戻し指摘"})`
+      - 機密漏れ: `complete({status: "aborted", abort_reason: "secret_leak: ..."})`
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools: [Read, Glob, Grep]
+    default_next: COMPLETE
+    rules:
+      - condition: ops 報告が不足している
+        next: execute

pieces/x-ai-digest.yaml

@@ -0,0 +1,197 @@
+name: x-ai-digest
+description: |
+  X (Twitter) から AI 技術関連ツイートを収集・深掘りし、ダイジェスト記事（Markdown）を生成する。
+  選ぶべき場合: 「AI技術ダイジェスト」「AIヘッドライン」の作成を指示されたとき
+  選ぶべきでない場合: 一般的な SNS 調査、意見収集、ドキュメント処理
+triggers:
+  keywords:
+    - AIダイジェスト
+    - AI技術ダイジェスト
+    - AIヘッドライン
+    - ダイジェスト朝刊
+    - ダイジェスト夕刊
+max_movements: 999
+initial_movement: collect
+movements:
+  - name: collect
+    edit: true
+    persona: researcher
+    instruction: |
+      X (Twitter) から AI 技術関連のツイートを収集し、深掘り調査を行う。
+
+      ## 手順
+
+      1. Task instruction に記載された検索クエリで XSearch を実行する
+         - 各クエリの結果から24時間以内の投稿を抽出する
+      2. Task instruction に記載された追跡アカウントを XUserPosts で確認する
+      3. 収集した全候補から Task instruction の選定基準に従って 5〜10 件を選定する
+         - 新機能・新サービス・新モデルのリリース情報を優先
+         - 24h 外やノイズ投稿は除外
+      4. 各候補について XPostDetail でスレッド文脈を確認する
+         - リプライツリー・引用元・追記ポストを確認し、文脈を補完する
+      5. ツイート内に URL がある場合は WebFetch で深掘りする
+         - 論文（arXiv 等）→ Abstract・概要を取得
+         - GitHub → README 概要を取得
+         - 記事・ブログ → 要点を抽出
+         - 取得できない場合はスキップ（深掘りなしでも記事は作成する）
+      6. 収集結果を output/raw/ に書き出す
+
+      ## ファイル命名規則
+      output/raw/{source}-{slug}.txt
+      例: xsearch-ai-llm.txt, xuser-huggingmodels.txt, detail-12345.txt
+
+      ## 画像・スクリーンショットの収集（必須）
+      ツイートに添付された画像（モデル比較グラフ、ベンチマーク結果、アーキテクチャ図、
+      デモスクリーンショット等）は積極的に DownloadFile で output/images/ に保存する。
+      - filename: "images/{slug}.png"
+      - section: "output"
+      深掘り先の記事・論文に含まれる図表も同様に収集すること。
+      ビジュアル素材が記事の品質を大きく左右する。
+
+      ## 原則
+      - 【必須】モデルの内部知識だけで情報を書かないこと。必ず実際のツイートデータを収集する
+      - 検索が一部失敗しても、取得できた分で続行する
+      - verify 由来の指摘がある場合は、不足点を優先的に補完する
+
+      ## 終了 / 遷移方法
+      - **次の compose へ**: `transition({next_step: "compose"})`
+      - **対象が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
+      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools:
+      - XSearch
+      - XUserPosts
+      - XPostDetail
+      - XFetchCardMedia
+      - BrowseWeb
+      - WebFetch
+      - WebSearch
+      - Read
+      - Write
+      - Edit
+      - Glob
+      - Grep
+      - Bash
+      - DownloadFile
+      - SearchKnowledge
+      - ListNamespaces
+      - ListDocuments
+      - SearchNotes
+      - ReadNote
+      - 'mcp__*'
+    default_next: compose
+    rules:
+      - condition: 十分な情報を収集し output/raw/ に書き出した
+        next: compose
+  - name: compose
+    edit: true
+    persona: writer
+    instruction: |
+      output/raw/ の収集データから、articles JSON とヘッドライン記事 Markdown を生成する。
+
+      ## 最初に確認
+      Glob で output/raw/ のファイル一覧を確認する。ファイルがなければ collect に遷移すること。
+
+      ## 手順
+
+      1. output/raw/ の各ファイルを Read で読み込む
+      2. output/x-ai-digest-articles.json を生成する
+         形式:
+         {"articles":[{"title":"タイトル","summary":"要約","comment":"一言コメント","url":"ツイートURL"}]}
+      3. Bash で JST の日付を取得する: TZ=Asia/Tokyo date +%Y-%m-%d
+      4. Task instruction で指定されたセッション種別（朝刊/夕刊）に従い、
+         output/headline-YYYY-MM-DD-{session}.md を生成する
+         - {session} は morning または evening
+
+      ## ヘッドライン記事のフォーマット（厳守）
+
+      - Docusaurus frontmatter 付き（sidebar_position: 100, title, description）
+      - タイトル形式: MM/DD AIヘッドライン（朝刊|夕刊）
+        - MM は必ずゼロ埋め2桁（02/25 ○、2/25 ×）
+        - （朝刊）/（夕刊）は必ずつける
+      - 各トピックは 概要・深掘り・ポイント の3セクション構成
+      - 末尾に「まとめ」セクション（今日の注目ポイントをリスト形式で）
+      - 最終行: *情報はYYYY年MM月DD日時点のものです。*
+
+      ## 画像の活用（必須）
+      output/images/ に画像が保存されている場合は、各トピックの該当箇所に埋め込む:
+      `![説明](./images/ファイル名.png)`
+      画像があるのにテキストだけの記事にしないこと。
+      特にベンチマーク結果やモデル比較のグラフは、記事の説得力を大きく向上させる。
+
+      ## verify 由来の指摘がある場合
+      「これまでのレビュー指摘」がある場合は、指摘事項を漏れなく解消すること。
+
+    allowed_tools:
+      - Read
+      - Write
+      - Edit
+      - Glob
+      - Grep
+      - Bash
+      - 'mcp__*'
+    default_next: verify
+    rules:
+      - condition: 2ファイル（articles JSON + headline MD）を書き出した
+        next: verify
+      - condition: 情報が不十分で追加収集が必要（output/raw/ が空を含む）
+        next: collect
+  - name: verify
+    edit: false
+    persona: supervisor
+    instruction: |
+      出力ファイルの存在とフォーマットを確認する。
+
+      ## 確認手順
+
+      1. Glob で output/ 内のファイル一覧を確認する
+      2. output/x-ai-digest-articles.json を確認する
+         - ファイルが存在すること
+         - Read で内容を読み、articles 配列が存在すること
+         - 各要素に title, summary, comment, url の4フィールドがあること
+         - articles が1件以上あること
+      3. output/headline-*.md を確認する
+         - ファイルが存在すること
+         - Read で内容を読み、以下をチェック:
+           a. frontmatter に sidebar_position, title, description があること
+           b. title が「MM/DD AIヘッドライン（朝刊）」または「MM/DD AIヘッドライン（夕刊）」形式であること
+           c. MM がゼロ埋め2桁であること（01〜12）
+           d. 各トピックに「概要」「深掘り」「ポイント」の3セクションがあること
+           e. 末尾に「まとめ」セクションがあること
+           f. headline MD の session（morning/evening）が Task instruction と一致すること
+      4. output/images/ に画像があるのに headline MD に `![` が一つもない場合、
+         画像埋め込み漏れとして compose に差し戻す
+
+      ## チェックシート確認
+      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
+      remaining が 0 でないまま完了してはならない。
+
+      5. 不足があれば、`transition({next_step: "compose", summary: ...})` で差し戻す。summary は次の形式で書く:
+         [判定] needs_fix
+         ## 問題点
+         - [ファイル名:項目] 何が問題か
+         ## 期待する修正
+         - 何をどう直すべきか
+         ## 合格基準
+         - 再レビューで何を確認するか
+         ## 次にやること
+         - compose で最初に着手すべき作業
+
+      ## 合格時のユーザーへの返答（complete ツール）
+      合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
+      result はそのままユーザーに表示される最終回答。headline MD を Read で読み、記事の見出し一覧と各トピックの概要を整形する。
+      - 【厳守】「完了しました」「確認しました」等のステータス表示やメタ説明は一切書かない
+      - 1行目からいきなり記事の内容を書き始めること
+      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする
+
+      ## 終了方法のまとめ
+      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
+      - 修正必要: `transition({next_step: "compose", summary: "差し戻し指摘"})` (上記形式で)
+      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+    default_next: COMPLETE
+    rules:
+      - condition: ファイルがない、またはフォーマットに不足がある
+        next: compose