| name | takt-builder |
| description | TAKTのワークフローYAMLとファセット（ペルソナ・ポリシー・ナレッジ・インストラクション・出力契約）を作成・更新する。スタイルガイドに準拠したファセット分離とYAMLスキーマに準拠したワークフロー設計を行う。トリガー：「ワークフローを作りたい」「ピースを作りたい」「ファセットを追加」「TAKTのペルソナを作成」「ポリシーを更新」「ナレッジを追加」「出力契約を作成」「ワークフローYAMLを設計」「ピースYAMLを設計」といったTAKTファセット・ワークフロー関連リクエストで起動。 |
| user-invocable | true |
TAKT Builder
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 本体を更新した場合は、対応するファイルをこのスキルにも反映する。
目次
- 引数
- 事前準備: リファレンスの読み込み
- 手順 1. 意図の分析
- 手順 2A. ワークフロー設計 / 2B. 分離判断
- 手順 3. ファセット作成
- 手順 4. ワークフローYAML作成/更新
- 手順 5. セルフチェック
- 手順 6. ビルドとテスト
- 手順 7. 結果の報告
引数
$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 済み環境、個人のカスタムファセット |
出力先の決定手順:
- cwd で
builtins/ja/STYLE_GUIDE.md を Glob → 見つかれば TAKT プロジェクト内（builtins/{lang}/ に出力）
- 見つからなければ AskUserQuestion で「プロジェクトローカル（
.takt/）に置くか、ユーザーグローバル（~/.takt/）に置くか」を確認
手順
1. 意図の分析
$ARGUMENTS を分析し、以下を判断する。
| 判断項目 | 選択肢 |
|---|
| 作業スコープ | ワークフロー作成 / ワークフロー更新 / ファセット作成・更新 |
| 必要なファセット | ペルソナ / ポリシー / ナレッジ / インストラクション / 出力契約 |
| 言語 | ja（マスター） + en（翻訳） |
ワークフロー作成の場合 → ステップ 2A（ワークフロー設計）へ
ファセット作成・更新の場合 → ステップ 2B（分離判断）へ
2A. ワークフロー設計（ワークフロー作成時）
references/yaml-schema.md を読み込み、ワークフローの構造を設計する。
設計の手順:
-
フロー設計: ステップの遷移フロー（状態遷移図）を決める
- どのステップが必要か（plan → implement → review → ...）
- 各ステップ間の遷移条件（rules）
- ループの有無（review → fix → review のサイクル等）
- max_steps の見積もり
-
ファセット割り当て: 各ステップに必要なファセットを決める
- persona: どのエージェントが担当するか
- policy: どの共有ルールを適用するか
- knowledge: どのドメイン知識が必要か
- instruction: どんな手順で実行するか
- output_contracts: どんなレポートを出力するか
-
既存ファセットの確認: 再利用可能な既存ファセットを探す
- 出力先ディレクトリの既存ファセットを Glob で確認
- 既存のものは再利用、不足分のみ新規作成
-
参考ワークフローの確認: 同種の既存ワークフローYAMLがあれば Read で読み込み参考にする
設計をユーザーに提示して確認を取ってから、ステップ 3 以降でファセット作成 → ワークフローYAML作成に進む。
2B. 分離判断（ファセット作成・更新時）
内容をファセットに分離する。STYLE_GUIDE.md の分離判断フローに従う。
この内容は…
├── 特定のエージェントだけが必要 → ペルソナ
├── 「〜すべき」行動規範（複数エージェント共有） → ポリシー
├── 「〜はこう動く」ドメイン知識 → ナレッジ
├── ステップ固有の手順 → インストラクション
└── エージェント出力の構造定義 → 出力契約
判断に迷ったら AskUserQuestion で確認する。
判断ポイント:
| 迷いやすいケース | 判断基準 |
|---|
| ペルソナ vs ナレッジ | そのエージェントだけが使う → ペルソナ、複数エージェントが参照 → ナレッジ |
| ポリシー vs ナレッジ | 「〜すべき/禁止」ルール → ポリシー、「〜はこう動く」知識 → ナレッジ |
| ペルソナの行動姿勢 vs ポリシー | 1行の指針 → ペルソナ行動姿勢、詳細ルール(テーブル/コード例) → ポリシー |
| インストラクション vs ペルソナ | 「今このステップでやること」→ インストラクション、「常に持つ知識」→ ペルソナ |
3. ファセット作成
まず出力先を確定する。 「事前準備」セクションの「ファセット・ワークフローの出力先」に従い、出力先ディレクトリを決定してから作成に入る。
対象ファセットごとにスタイルガイドとテンプレートを読み込み、準拠したファイルを作成する。
作成順序: 日本語（マスター）→ 英語（翻訳）
各ファセットの作成ルール:
ペルソナ:
- テンプレートを選択（simple / expert / character）
- ロール定義 1-2文、「あなたは〜です。」
- 役割の境界（やること/やらないこと + 担当エージェント名）
- 行動姿勢（3-8項目、1行の指針）
- ドメイン知識（エージェント固有のみ）
- 見出し最大
###、文体は常体
ポリシー:
- 目的説明 1文
- 原則テーブル（5-10行）
- ルールカテゴリ（
## で直接分ける）
- 「基準 → 判定」テーブル
- 見出し最大
###、文体は常体
ナレッジ:
- プロジェクト固有の手順をそのまま書かない。 汎用的なパターン/原則として記述する（KNOWLEDGE_STYLE_GUIDE.md「抽象度の原則」参照）
- トピック概要（各
## の冒頭1-2文）
- 評価基準テーブル
- コード例（良い例/悪い例ペア）
- 見出し最大
###、文体は常体
インストラクション:
- 目的宣言（1-2行、命令形「〜してください。」）
- やること（番号付きリスト or 箇条書き）
{task}, {previous_response}, {user_inputs} は書かない（自動注入）- 文体は丁寧語
出力契約:
4. ワークフローYAML作成/更新
references/yaml-schema.md に準拠してワークフローYAMLを作成する。
セクションマップは基本不要。 TAKT は 3層解決（project .takt/ → user ~/.takt/ → builtin builtins/{lang}/）でファセットを自動検索する。ステップ内でファセット名（キー名）を指定すれば、標準パス（facets/personas/{name}.md 等）に配置されたファセットは自動解決される。
セクションマップが必要なのは次の場合のみ:
- ファセット名とファイル名が異なる場合
- 標準パス外にファセットを配置する場合
- repertoire パッケージのファセットを参照する場合
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層ファセット検索の順で解決される。インストラクションファセットとして作成し、キー名で参照する。
5. セルフチェック
各ファセットのスタイルガイドのチェックリストで検証する。
共通チェック:
ペルソナチェック:
ポリシーチェック:
ナレッジチェック:
インストラクションチェック:
ワークフローYAMLチェック:
不合格の場合: 該当ファセットのステップ 3 に戻って修正し、再度セルフチェックする。ワークフローYAMLの問題はステップ 4 に戻る。
6. ビルドとテストの確認
TAKT プロジェクト内で作業している場合は、ファイル作成後に以下を実行する。
npm run build && npm run test
TAKT プロジェクト外の場合はスキップする。
7. 結果の報告
作成・更新したファイルの一覧と構成のサマリーを表示する。
作成物:
| 種別 | ファイル（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
