takt-piece（节拍片）

TAKT Piece Creator

TAKTピース（ワークフローYAML）とその関連ファセットファイルを作成する。

前提 takt バージョン: v0.30.0

参照資料

taktのコードベースとドキュメントは references/takt/ にある。必要に応じて以下を参照する。

重要: ピース作成前に references/takt/builtins/ja/pieces/default.yaml を読み、プロジェクトのパターンを把握する。

ワークフロー

Step 1: 要件ヒアリング

以下を確認する（不明な点はユーザーに質問）:

1. 目的: このピースで何を達成するか
2. ムーブメント構成: どんなステップが必要か（plan→implement→review→supervise等）
3. レビュー体制: 並列レビューの有無、レビュアーの種類
4. ループ制御: 修正ループの有無と閾値
5. 出力先: ピースとファセットの配置場所（デフォルト: ~/.takt/pieces/）

Step 2: ビルトイン参照

ビルトインピース（references/takt/builtins/ja/pieces/）から類似パターンを探す。

注意: v0.28.1 で expert → dual にリネーム、default-mini は廃止。*-cqrs, *-mini, *-review, *-review-fix 等のバリエーションが多数追加されている。全一覧は references/takt/builtins/ja/pieces/ を参照。

ビルトイン再利用の判断

カスタムファセットを作る前に、まずビルトインで代替できないか確認する。ビルトインは takt 本体でテスト済みであり、一貫性と保守性の面で有利。

判断基準: 「このファセットはビルトインと何が違うか？」を一文で説明できなければ、ビルトインを使う。

Step 3: ピースYAML作成

以下の構造でYAMLを作成する。

name: piece-name
description: ピースの説明
max_movements: 30
initial_movement: plan

# セクションマップ（カスタムファセットがある場合のみ）
personas:
  custom-role: ../personas/custom-role.md
policies:
  custom-policy: ../policies/custom-policy.md
instructions:
  custom-step: ../instructions/custom-step.md
knowledge:
  domain: ../knowledge/domain.md
report_formats:
  custom-report: ../output-contracts/custom-report.md

movements:
  - name: plan
    edit: false
    persona: planner          # ビルトイン参照（bare name）
    knowledge: architecture
    instruction: plan
    provider_options:          # v0.30.0: ツール制限はプロバイダ別に指定
      claude:
        allowed_tools:
          - Read
          - Glob
          - Grep
          - Bash
          - WebSearch
          - WebFetch
    output_contracts:
      report:
        - name: 00-plan.md
          format: plan
    rules:
      - condition: 要件が明確で実装可能
        next: implement
      - condition: 要件が不明確、情報不足
        next: ABORT

  - name: implement
    edit: true
    persona: coder
    policy: [coding, testing]
    session: refresh
    instruction: implement
    rules:
      - condition: 実装完了
        next: review

Parallel Movement 例

  - name: reviewers
    parallel:
      - name: arch-review
        edit: false
        persona: architecture-reviewer
        policy: review
        instruction: review-arch
        output_contracts:
          report:
            - name: 05-architect-review.md
              format: architecture-review
        rules:
          - condition: approved
          - condition: needs_fix
      - name: qa-review
        edit: false
        persona: qa-reviewer
        policy: [review, qa]
        instruction: review-qa
        rules:
          - condition: approved
          - condition: needs_fix
    rules:
      - condition: all("approved")
        next: supervise
      - condition: any("needs_fix")
        next: fix

注意: サブステップの rules は結果分類用。next は無視され、親の rules が遷移先を決定する。

設計判断ガイド

edit:false ムーブメントの安全ルール

edit: false のムーブメント（plan, review, supervise等）は読み取り専用サンドボックスで動作する。これはtaktエンジンが強制する制約であり、以下を必ず守る:

1. allowed_tools に Bash を含めない — Bash があるとエージェントがビルドコマンド（cargo check, npm test 等）を試みて必ず失敗する。読み取り専用で必要なのは Read, Glob, Grep 等のみ
2. インストラクションに「やらないこと」を明記 — 「コンパイル・ビルド・テスト実行は行わない」と明示する
3. CI/ビルド結果が必要なら — edit: true の前段ムーブメント（implement/fix）でビルドを実行し、レポートに記録する。edit:false ムーブメントはそのレポートを読んで判断する

# ❌ 間違い: review に Bash を含めている
- name: review
  edit: false
  provider_options:
    claude:
      allowed_tools:
        - Read
        - Glob
        - Grep
        - Bash          # ← 読み取り専用で Bash は使えない！

# ✅ 正解: review は読み取り専用ツールのみ
- name: review
  edit: false
  provider_options:
    claude:
      allowed_tools:
        - Read
        - Glob
        - Grep
        - WebSearch

ルール設計

特殊遷移先: COMPLETE（成功終了）、ABORT（失敗終了）

Step 4: ファセットファイル作成

カスタムファセットが必要な場合、以下の規約で作成する。

ディレクトリ構造

~/.takt/
├── pieces/
│   └── my-piece.yaml
├── personas/
│   └── custom-role.md
├── policies/
│   └── custom-policy.md
├── instructions/
│   └── custom-step.md
├── knowledge/
│   └── domain.md
└── output-contracts/
    └── custom-report.md

ファセット作成規約

Persona: system promptに配置。identity + 専門性 + 境界。

# {ロール名}

{1-2文のロール定義}

## 役割の境界

**やること:**
- ...

**やらないこと:**
- ...（担当エージェント名を明記）

## 行動姿勢

- ...

Policy: 複数ムーブメントで共有する行動規範。

# {ポリシー名}

## 原則

| 原則 | 基準 |
|------|------|
| ... | REJECT / APPROVE 判定 |

## 禁止事項

- ...

Instruction: ムーブメント固有の手順。命令形で記述。{task}, {previous_response}は自動注入されるため不要。

Knowledge: 判断の前提となる参照情報。記述的（「こうなっている」）。

Output Contract: レポートの構造定義。

{レポートタイトル}

結果: APPROVE / REJECT

サマリー

{1-2文で要約}

詳細

詳細なスタイル規約は references/takt/builtins/ja/STYLE_GUIDE.md を参照。

Step 5: Loop Monitor（任意）

修正ループが想定される場合に設定する。

loop_monitors:
  # AI修正ループ監視
  - cycle: [ai_review, ai_fix]
    threshold: 5
    judge:
      persona: supervisor
      instruction_template: loop-monitor-ai-fix    # v0.30.0: ビルトインテンプレート参照
      rules:
        - condition: 健全（進捗あり）
          next: ai_review
        - condition: 非生産的（改善なし）
          next: ABORT

  # レビュアー修正ループ監視
  - cycle: [reviewers, fix]
    threshold: 3
    judge:
      persona: supervisor
      instruction_template: loop-monitor-reviewers-fix  # v0.30.0: 新規ビルトインテンプレート
      rules:
        - condition: 健全（指摘数が減少、修正が反映されている）
          next: reviewers
        - condition: 非生産的（同じ指摘が繰り返される）
          next: ABORT

注意（v0.30.0）: instruction_template にはビルトインファセット名を指定することを推奨する。これにより一貫性と保守性が向上する。インラインテキストも引き続き使用可能だが、ビルトインに同等のテンプレートがある場合は参照名を優先する。カスタムテンプレートが必要な場合は、instructions セクションマップにカスタムファセットを登録し、そのキー名を指定する。

Loop Monitor 安全ルール

• loop_monitors[*].cycle の「健全（進捗あり）」遷移先は、必ず cycle の先頭ノードにする

- 例: cycle: [reviewers, fix] の場合、健全時 next: reviewers

• judge.instruction_template で参照する {report:...} は、対象 cycle 内 movement が生成するレポートのみ許可

- cycle 外 movement（例: verify）専用レポートは参照しない

• 上記2点を満たさない場合は、ループ継続判定が壊れるため修正してから保存する

Step 6: 検証

作成したファイルの整合性を確認する:

• セクションマップのキーとムーブメント内の参照が一致
• セクションマップのパスが実際のファイル位置と一致（ピースYAMLからの相対パス）
• ビルトイン参照（bare name）とカスタム参照（セクションマップキー）が混在していないか
• initial_movement が movements 配列内に存在
• 全ムーブメントの rules.next が有効な遷移先（他のムーブメント名 or COMPLETE/ABORT）
• parallel ムーブメントの親ルールが all() / any() を使用
• parallel サブステップのルールに next がない（親が制御）
• loop monitor の健全時 next が cycle 先頭ノードと一致
• loop monitor の instruction_template が cycle 外レポートを参照していない
• edit: false ムーブメントの allowed_tools に Bash が含まれていない
• implement / fix ムーブメントに session: refresh が設定されている
• ビルトインで代替可能なカスタムファセットが不必要に作成されていない

バリデーション

作成・編集したファイルは validate-takt-files.sh で機械的に検証できる:

bash .agents/skills/takt-piece/scripts/validate-takt-files.sh

検証項目:

• ピース YAML: 必須フィールド（name/initial_movement/movements）、initial_movement の movement 参照、ファセットファイル参照の実在
• loop_monitors: 健全時 next が cycle 先頭ノード、instruction_template のレポート参照が cycle 内 movement 生成物に限定されていること
• ファセット.md: 空チェック、persona/policy/knowledge は # 見出し 必須、instruction/output-contract は内容存在

オプション --pieces / --facets で対象を絞り込み可能。