maestro/docs/tools/listpieces.md

Piece 編集ツール（ListPieces / GetPiece / CreatePiece / UpdatePiece）

Piece（ワークフロー定義 YAML）を CRUD するツール群。piece-builder piece で使用。

ListPieces — 一覧

ListPieces()
// → 全 Piece の名前・説明・トリガーキーワード一覧

新規 Piece を作る前に 必ず実行して既存 Piece を確認する。重複・類似機能の Piece を作らないように。

GetPiece — 取得

GetPiece({ name: "research" })
// → 指定 Piece の完全な YAML 定義

• 既存 Piece の構造を参考にする
• UpdatePiece の前に現状を確認

CreatePiece — 作成

CreatePiece({
  name: "my-new-piece",   // 英小文字・数字・ハイフンのみ
  yaml_content: `
name: my-new-piece
description: ...
initial_movement: gather
movements:
  - name: gather
    persona: ...
    instruction: ...
    allowed_tools: [Read, Write, ...]
    rules:
      - condition: ...
        next: ...
`
})

必須要素:

• name
• description
• initial_movement
• movements（少なくとも 1 つ）
• 各 movement の rules（遷移条件、next を明示）

UpdatePiece — 更新

UpdatePiece({
  name: "research",
  yaml_content: "..."   // 全体を置き換える
})

差分更新ではなく全体置換。GetPiece で取得 → 編集 → UpdatePiece の流れ。

制限

• general と chat は削除不可（更新は可能）
• YAML パースエラーは即座にエラー
• movement 構造の検証あり（rules[].next が存在する movement か等）

設計指針

新しい Piece を作る前に:

1. ListPieces で既存を確認
2. 既存 Piece に少しの調整で対応できないか検討
3. 必要なら GetPiece で類似 Piece を参考にする
4. その上で CreatePiece

「Piece が増えすぎる」のはメンテナンス負債。Piece は追加よりも既存 Piece の改良が原則。