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

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

## ListPieces — 一覧

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

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

## GetPiece — 取得

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

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

## CreatePiece — 作成

```js
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 — 更新

```js
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 の改良が原則**。