// TAKTのワークフローYAMLとファセット（ペルソナ・ポリシー・ナレッジ・インストラクション・出力契約）を作成・更新する。スタイルガイドに準拠したファセット分離とYAMLスキーマに準拠したワークフロー設計を行う。トリガー：「ワークフローを作りたい」「ピースを作りたい」「ファセットを追加」「TAKTのペルソナを作成」「ポリシーを更新」「ナレッジを追加」「出力契約を作成」「ワークフローYAMLを設計」「ピースYAMLを設計」といったTAKTファセット・ワークフロー関連リクエストで起動。
| name | takt-builder |
| description | TAKTのワークフローYAMLとファセット（ペルソナ・ポリシー・ナレッジ・インストラクション・出力契約）を作成・更新する。スタイルガイドに準拠したファセット分離とYAMLスキーマに準拠したワークフロー設計を行う。トリガー：「ワークフローを作りたい」「ピースを作りたい」「ファセットを追加」「TAKTのペルソナを作成」「ポリシーを更新」「ナレッジを追加」「出力契約を作成」「ワークフローYAMLを設計」「ピースYAMLを設計」といったTAKTファセット・ワークフロー関連リクエストで起動。 |
| user-invocable | true |
TAKT のワークフローYAMLとファセットをスタイルガイドに準拠して作成・更新する。
使い方:
/takt-builder 調査用の deep-research ワークフローを作りたい — 新規ワークフロー作成/takt-builder default ワークフローにセキュリティレビューを追加 — 既存ワークフロー更新/takt-builder research 用の policy を作りたい — ファセット作成手順を飛ばさない。 事前準備（リファレンスの読み込み）から結果報告まで、ステップバイステップで実行する。「既に知っている」「前に読んだ」という判断でステップを省略しない。
ファセットはプロジェクト非依存で書く。 npm run build や pytest のようなプロジェクト固有のコマンド、特定のフレームワーク名、具体的なファイルパスをファセットに直接書かない。「ビルド（型チェック）を実行」「テストを実行」のように抽象的に記述する。具体的なコード例を含めるのは、ナレッジやポリシーで良い例/悪い例のパターンを示す場合に限る。
このスキルには具体的なルールや例を書かない。
すべてのスタイルルールは同梱の references/ 配下のスタイルガイドに記載されており、それらが Single Source of Truth である。
同期について: このスキルのスタイルガイド・テンプレート・YAMLスキーマは TAKT 本体の builtins/ から移植したもの。TAKT 本体を更新した場合は、対応するファイルをこのスキルにも反映する。
$ARGUMENTS にユーザーの意図が入る。省略時は AskUserQuestion で確認する。
意図の種類:
deep-research ワークフローを作りたい）default ワークフローにセキュリティレビューを追加）research ワークフローに knowledge を追加）research-planner ペルソナを更新）research 用の policy を作りたい）このスキルの references/ と templates/ にリファレンスが同梱されている。
スキルのベースディレクトリ（スキル読み込み時に表示される Base directory）をルートとして、Read tool で読み込む。
| ファイル | 目的 |
|---|---|
references/STYLE_GUIDE.md | 全体アーキテクチャと分離判断フロー |
| ファイル | 目的 |
|---|---|
references/yaml-schema.md | ワークフローYAMLの構造定義とフィールド説明 |
| 同種の既存ワークフローYAML | 参考パターンの把握 |
| 対象ファセット | スタイルガイド | テンプレート |
|---|---|---|
| ペルソナ | references/PERSONA_STYLE_GUIDE.md | templates/personas/{simple,expert,character}.md |
| ポリシー | references/POLICY_STYLE_GUIDE.md | templates/policies/policy.md |
| ナレッジ | references/KNOWLEDGE_STYLE_GUIDE.md | templates/knowledge/knowledge.md |
| インストラクション | references/INSTRUCTION_STYLE_GUIDE.md | templates/instructions/{plan,implement,review,...}.md |
| 出力契約 | references/OUTPUT_CONTRACT_STYLE_GUIDE.md | templates/output-contracts/{plan,review,...}.md |
作成したファセットやワークフローYAMLの配置先は、cwd が TAKT プロジェクトかどうかで決まる。
| 配置先 | 条件 | 用途 |
|---|---|---|
builtins/{lang}/ | cwd に builtins/ja/STYLE_GUIDE.md が存在する | TAKT プロジェクト本体の builtin 更新 |
.takt/ | 上記以外（ユーザー選択） | プロジェクト固有のファセット・ワークフロー |
~/.takt/ | 上記以外（ユーザー選択） | eject 済み環境、個人のカスタムファセット |
出力先の決定手順:
builtins/ja/STYLE_GUIDE.md を Glob → 見つかれば TAKT プロジェクト内（builtins/{lang}/ に出力）.takt/）に置くか、ユーザーグローバル（~/.takt/）に置くか」を確認$ARGUMENTS を分析し、以下を判断する。
| 判断項目 | 選択肢 |
|---|---|
| 作業スコープ | ワークフロー作成 / ワークフロー更新 / ファセット作成・更新 |
| 必要なファセット | ペルソナ / ポリシー / ナレッジ / インストラクション / 出力契約 |
| 言語 | ja（マスター） + en（翻訳） |
ワークフロー作成の場合 → ステップ 2A（ワークフロー設計）へ ファセット作成・更新の場合 → ステップ 2B（分離判断）へ
references/yaml-schema.md を読み込み、ワークフローの構造を設計する。
設計の手順:
フロー設計: ステップの遷移フロー（状態遷移図）を決める
ファセット割り当て: 各ステップに必要なファセットを決める
既存ファセットの確認: 再利用可能な既存ファセットを探す
参考ワークフローの確認: 同種の既存ワークフローYAMLがあれば Read で読み込み参考にする
設計をユーザーに提示して確認を取ってから、ステップ 3 以降でファセット作成 → ワークフローYAML作成に進む。
内容をファセットに分離する。STYLE_GUIDE.md の分離判断フローに従う。
この内容は…
├── 特定のエージェントだけが必要 → ペルソナ
├── 「〜すべき」行動規範（複数エージェント共有） → ポリシー
├── 「〜はこう動く」ドメイン知識 → ナレッジ
├── ステップ固有の手順 → インストラクション
└── エージェント出力の構造定義 → 出力契約
判断に迷ったら AskUserQuestion で確認する。
判断ポイント:
| 迷いやすいケース | 判断基準 |
|---|---|
| ペルソナ vs ナレッジ | そのエージェントだけが使う → ペルソナ、複数エージェントが参照 → ナレッジ |
| ポリシー vs ナレッジ | 「〜すべき/禁止」ルール → ポリシー、「〜はこう動く」知識 → ナレッジ |
| ペルソナの行動姿勢 vs ポリシー | 1行の指針 → ペルソナ行動姿勢、詳細ルール(テーブル/コード例) → ポリシー |
| インストラクション vs ペルソナ | 「今このステップでやること」→ インストラクション、「常に持つ知識」→ ペルソナ |
まず出力先を確定する。 「事前準備」セクションの「ファセット・ワークフローの出力先」に従い、出力先ディレクトリを決定してから作成に入る。
対象ファセットごとにスタイルガイドとテンプレートを読み込み、準拠したファイルを作成する。
作成順序: 日本語（マスター）→ 英語（翻訳）
各ファセットの作成ルール:
ペルソナ:
###、文体は常体ポリシー:
## で直接分ける）###、文体は常体ナレッジ:
## の冒頭1-2文）###、文体は常体インストラクション:
{task}, {previous_response}, {user_inputs} は書かない（自動注入）出力契約:
{簡潔な説明} 形式references/yaml-schema.md に準拠してワークフローYAMLを作成する。
セクションマップは基本不要。 TAKT は 3層解決（project .takt/ → user ~/.takt/ → builtin builtins/{lang}/）でファセットを自動検索する。ステップ内でファセット名（キー名）を指定すれば、標準パス（facets/personas/{name}.md 等）に配置されたファセットは自動解決される。
セクションマップが必要なのは次の場合のみ:
# セクションマップなし（推奨）— ファセット名で自動解決
name: workflow-name
max_steps: 10
initial_step: plan
steps:
- name: plan
persona: planner
policy: coding
instruction: plan
edit: false
output_contracts:
report:
- name: 01-plan.md
format: plan
rules:
- condition: 要件が明確で実装可能
next: implement
- condition: 要件が不明確
next: ABORT
# セクションマップあり — 名前とファイルが異なる場合のみ
personas:
arch-reviewer: ../facets/personas/architecture-reviewer.md
instruction はファイル参照を使う。 instruction フィールドはセクションマップ → パス → 3層ファセット検索の順で解決される。インストラクションファセットとして作成し、キー名で参照する。
各ファセットのスタイルガイドのチェックリストで検証する。
共通チェック:
#### 以下のネストがないか.takt/runs/ 等）がペルソナ/ポリシー/ナレッジに混入していないかペルソナチェック:
ポリシーチェック:
ナレッジチェック:
インストラクションチェック:
ワークフローYAMLチェック:
name, max_steps, initial_step, steps が定義されているかedit と rules が定義されているかCOMPLETE への遷移パスが存在するかall() / any() が使われているか不合格の場合: 該当ファセットのステップ 3 に戻って修正し、再度セルフチェックする。ワークフローYAMLの問題はステップ 4 に戻る。
TAKT プロジェクト内で作業している場合は、ファイル作成後に以下を実行する。
npm run build && npm run test
TAKT プロジェクト外の場合はスキップする。
作成・更新したファイルの一覧と構成のサマリーを表示する。
作成物:
| 種別 | ファイル（ja） | ファイル（en） |
|------|--------------|--------------|
| Workflow | workflows/xxx.yaml | workflows/xxx.yaml |
| Persona | facets/personas/xxx.md | facets/personas/xxx.md |
| Policy | facets/policies/xxx.md | facets/policies/xxx.md |
| ... | ... | ... |
ワークフロー:
plan → implement → reviewers → [fix ↔ reviewers] → supervise → COMPLETE