maestro/pieces/piece-builder.yaml

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