takt-workflow-builder

TAKT Workflow Builder

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

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

参照資料

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

資料	パス	用途
YAMLスキーマ	references/takt/builtins/skill/references/yaml-schema.md	ワークフローYAMLの構造定義
エンジン仕様	references/takt/builtins/skill/references/engine.md	プロンプト構築・ルール評価の詳細
Faceted Prompting	references/takt/docs/faceted-prompting.ja.md	5ファセット設計の理論
ビルトインワークフロー	references/takt/builtins/ja/workflows/	実例（default.yaml, dual.yaml等）
スタイルガイド	references/takt/builtins/ja/STYLE_GUIDE.md	ファセット記述規約
ペルソナガイド	references/takt/builtins/ja/PERSONA_STYLE_GUIDE.md	ペルソナ記述規約
ビルトインファセット	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	既存ファセット例

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

ワークフロー

Step 1: 要件ヒアリング

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

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

Step 2: ビルトイン参照

ビルトインワークフロー（references/takt/builtins/ja/workflows/）から類似パターンを探す。

ビルトイン	構成	用途
default.yaml	plan→write_tests→implement→ai_review→reviewers(arch+qa)→fix→supervise	標準開発
dual.yaml	plan→write_tests→team_leader_implement→ai_review→reviewers(2段階)→fix→supervise	フロントエンド＋バックエンド
backend.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	バックエンド特化
backend-cqrs.yaml / backend-cqrs-mini.yaml	CQRS+ESバックエンド開発	CQRS/ES特化
frontend.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	フロントエンド特化
frontend-maintenance.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	既存フロントエンド保守
backend-mini.yaml / dual-mini.yaml / dual-cqrs-mini.yaml / frontend-mini.yaml	plan→implement→supervise	最小構成
review-default.yaml / review-backend.yaml / review-dual.yaml / review-frontend.yaml	レビューワークフロー	コードレビュー
review-fix-default.yaml / review-fix-backend.yaml / review-fix-dual.yaml / review-fix-frontend.yaml	レビュー→修正ループ	レビュー＋修正
takt-default.yaml / review-takt-default.yaml / review-fix-takt-default.yaml	TAKT開発用	TAKT開発
takt-default-with-fc.yaml	Finding Contract付き takt-default（plan→write_tests→draft→peer-review-with-fc→supervise）	TAKT開発（Finding Contract有効）
peer-review-with-fc.yaml	Finding Contract付き peer-review（6並列レビュー + findings-manager照合）、callable: true	Finding Contract付き peer-review
audit-architecture.yaml / audit-architecture-backend.yaml / audit-architecture-dual.yaml / audit-architecture-frontend.yaml	アーキテクチャ監査	品質監査
audit-e2e.yaml / audit-security.yaml / audit-unit.yaml	E2E/セキュリティ/ユニットテスト監査	品質監査
terraform.yaml	インフラストラクチャ	Terraform
research.yaml / deep-research.yaml	調査・研究	リサーチ
magi.yaml / compound-eye.yaml	特殊構成	多視点分析

v0.42.0 で追加・拡張された代表例:

• default-draft.yaml, draft.yaml: managed PR 前提のドラフト運用
• default-high.yaml: 深めのレビュー・検証を含む高負荷プロファイル
• default-mini.yaml: 標準系の最小構成
• default-peer-review.yaml, peer-review.yaml: peer review を明示した分岐
• auto-improvement-loop.yaml: system step と managed_pr を使う自己改善ループ
• review-backend-cqrs.yaml, review-dual-cqrs.yaml, review-fix-backend-cqrs.yaml, review-fix-dual-cqrs.yaml: CQRS 系 review / review-fix
• takt-default-refresh-fast.yaml, takt-default-refresh-all.yaml: TAKT 自身の refresh 系ワークフロー

v0.43.0 で追加・拡張された代表例:

• frontend-maintenance.yaml: 既存システム尊重・保守スコープ管理を前提にしたフロントエンド保守ワークフロー
• default-peer-review.yaml, peer-review.yaml: coding-review 並列レビューを追加
• quality_gates の type: command: step 完了後に worktree 内でコマンド gate を実行可能（設定で workflow_command_gates.custom_scripts: true が必要）

v0.44.0 新增和扩展的代表性示例:

• 将 coding-review 并行评审（coding-reviewer persona + review-coding instruction + coding-review output contract）扩展到所有内置 review / review-fix / 开发类工作流（backend、frontend、dual、terraform 及其 variants）的并行评审阶段。刻意采用最小配置的 *-mini 和 compound-eye 除外
• 新增 provider kiro（kiro-cli）。可在支持指定 provider 的位置（config 中的 provider、provider_options.<provider> 等）使用 kiro。初始实现不会将 model 作为 CLI 标志传递

v0.46.0 新增和扩展的代表性示例:

• 删除 requirements-reviewer persona、review-requirements instruction 和 requirements-review output contract。改为新增 pure-reviewer persona（review-pure instruction + pure-review output contract），并将其集成到 peer-review / review / review-fix 类工作流中。pure-reviewer 不局限于特定领域，是只判断「现在是否可以合并」的通用评审者
• 支持 provider_options.$ref。可通过相对于工作流文件的路径，将 provider_options 块抽取到通用 YAML 文件中（inline 值会覆盖相同的 leaf）
• 新增内置 provider-options/ 预设（provider-options/edit.yaml、review-files.yaml、review-readonly.yaml、review-web.yaml）。通过 $ref 引用这些预设，即可统一指定 claude 和 opencode 的 allowed_tools
• 新增 provider_options.opencode.allowed_tools。可按 step / workflow 指定 OpenCode 的工具允许列表（工具名称使用小写形式，如 read、glob、grep、bash、websearch、webfetch）
• 新增 provider_options.kiro.agent。可按 step / workflow 指定 Kiro CLI 的 custom agent 名称（将作为 kiro-cli chat --agent 传递。也可通过 TAKT_PROVIDER_OPTIONS_KIRO_AGENT 环境变量指定）
• 将 team_leader.max_parts 拆分为 max_concurrency（上限 3）+ max_total_parts（上限 20）（仍接受旧的 max_parts，作为 max_concurrency 的兼容别名）

v0.47.0 新增和扩展的代表性示例:

• BREAKING：将 provider_options.$ref 重命名为 provider_options.extends。值也从文件路径（provider-options/edit.yaml）改为裸名称（edit）。旧的 $ref 将失效，因此自定义工作流需要迁移到 extends
• BREAKING：persona_providers 已弃用。请改用 provider_routing（项目/全局设置）。可通过 3 个维度进行路由：provider_routing.personas（按原始 persona 键匹配）、provider_routing.tags（按 step tags 匹配）、provider_routing.steps（按 step 名称匹配）。解析优先级：step > provider_routing.steps > provider_routing.tags > provider_routing.personas > persona_providers（已弃用）> workflow > CLI
• 内置 provider-options/ 目录从 builtins/{lang}/workflows/provider-options/ 移至 builtins/{lang}/provider-options/。使用裸名称引用，例如 extends: edit（3 层解析器：.takt/provider-options/ → ~/.takt/provider-options/ → builtin）
• 新增 Finding Contract（finding_contract: 区段）。用于结构化管理 review findings 的生命周期（ledger、severity、deduplication）。新增工作流 takt-default-with-fc（带 Finding Contract 的 takt-default）和 peer-review-with-fc（带 Finding Contract 的 peer-review）
• 可在 step 和 parallel 子 step 中添加 Step tags（tags: 字段）。所有内置工作流都包含 plan、coding、review、implementation、edit 等标签。可使用 provider_routing.tags 按标签指定 provider / model
• peer-review-with-fc.yaml：启用 Finding Contract 的 peer-review（6 路并行 + 由 findings-manager 进行核对）。通过 subworkflow: { callable: true } 从 takt-default-with-fc 调用
• 增强 Trace discovery（WorkflowTraceTaskMetadata）：任务元数据（source、issue/PR 编号、branch、slug、summary）会传递到 OTel span 和 trace discovery，可在 Grafana Tempo 等工具中关联执行记录

复用判断：如果内置 facet 已足够，就不要创建自定义 facet。

第 3 步：创建工作流 YAML

按以下结构创建 YAML。

name: workflow-name
description: ワークフローの説明
max_steps: 30
initial_step: plan

# ワークフロー全体の設定
workflow_config:
  provider_options:
    codex:
      network_access: true

# セクションマップ（カスタムファセットがある場合のみ）
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

steps:
  - name: plan
    edit: false
    persona: planner          # ビルトイン参照（bare name）
    knowledge: architecture
    provider_options:
      claude:
        allowed_tools:
          - Read
          - Glob
          - Grep
          - Bash
          - WebSearch
          - WebFetch
    instruction: plan
    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

使用 provider_options.extends 实现复用（v0.47.0 起，旧 $ref 已废弃）：provider_options 可通过裸名称引用内置预设或 .takt/provider-options/ 中的自定义 YAML。inline 值会覆盖相同的 leaf。内置预设：edit、review-readonly、review-files、review-web。

# プリセットを参照（claude + opencode の両方に allowed_tools が設定される）
provider_options:
  extends: review-readonly

# プリセットを参照しつつ一部を上書き
provider_options:
  extends: edit
  opencode:
    allowed_tools: [read, grep, bash]

注意：旧术语别名（movements、initial_movement、max_movements、piece_config、piece_categories）仍不可使用。请仅使用正式名称。

Parallel Step 示例

  - name: reviewers
    parallel:
      - name: arch-review
        edit: false
        tags: [review]            # v0.47.0〜: provider_routing.tags でルーティング可能
        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
        tags: [review]
        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

注意：子 step 的 rules 用于结果分类。next 会被忽略，转移目标由父级的 rules 决定。

Finding Contract 示例（v0.47.0 起）

在工作流顶层添加 finding_contract:，即可启用 review findings 生命周期的结构化管理（ledger、severity、deduplication）。建议通过 call: step 调用类似 peer-review-with-fc.yaml 这样的 callable 工作流。

name: takt-default-with-fc
description: Finding Contract付きワークフロー例
initial_step: plan
max_steps: 30

finding_contract:
  ledger_path: .takt/findings-ledger.yaml      # 既知/修正済みfindingを蓄積するledger
  raw_findings_path: .takt/raw-findings.yaml   # レビュー結果の生findings出力先
  manager:
    persona: findings-manager                   # ビルトイン: finding照合・判定ペルソナ
    instruction: findings-manager               # ビルトイン: findings-manager instruction
    output_contract: findings-manager           # ビルトイン: findings-manager output contract

steps:
  - name: plan
    tags: [plan]
    edit: false
    persona: planner
    instruction: plan
    rules:
      - condition: 実装可能
        next: implement

  - name: implement
    tags: [coding]
    edit: true
    persona: coder
    instruction: implement
    rules:
      - condition: 実装完了
        next: peer-review

  - name: peer-review
    call: peer-review-with-fc   # Finding Contract付き callable ワークフロー
    rules:
      - condition: approved
        next: supervise
      - condition: needs_fix
        next: fix

設計判断ガイド

判断ポイント	基準
edit: true/false	コード変更するステップのみtrue
session: refresh	実装系ステップで新規セッション開始
pass_previous_response: false	レビュー結果を直接読ませたくない場合
required_permission_mode	edit権限が必要な場合に edit を指定
provider_options.claude.allowed_tools	ステップ単位でClaudeの使用ツールを制限
provider_options.opencode.allowed_tools	ステップ単位でOpenCodeの使用ツールを制限（lowercase: read, glob, grep, bash 等）
provider_options.kiro.agent	Kiro CLI の custom agent 名を指定（kiro-cli chat --agent として渡される）
provider_options.extends	bare name でプリセット YAML を参照（3層リゾルバー: .takt/provider-options/ → ~/.takt/provider-options/ → builtin。inline 値が leaf を上書き。旧 $ref は v0.47.0 で廃止）
provider_options.<provider>.effort	思考深度を上げる場合に指定。モデル互換性を確認する
quality_gates	agent step の完了条件。文字列 gate と type: command gate を混在可能
tags	step / parallel サブステップのタグ配列（例: [plan], [coding], [review]）。provider_routing.tags でタグ単位のプロバイダー/モデル指定に使用
finding_contract	ワークフロートップレベルに追加して Finding Contract を有効化。ledger_path, raw_findings_path, manager（persona/instruction/output_contract）を指定する

ルール設計

ルール種別	記法	使い分け
テキスト条件	"条件文"	Phase 3タグ判定（推奨）
AI判定	ai("条件")	タグ判定が不適な場合
全一致	all("条件")	parallelの親のみ
いずれか	any("条件")	parallelの親のみ
決定論的条件	when: <expr>	AI不要のルーティング（condition: 不要）

when: は比較演算子（==, !=, >, <, >=, <=）、ブール論理（&&, \|\|）、ワークフロー状態参照（context.*, structured.*, effect.*）を使用可能。

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

サブワークフロー呼び出し（call: ステップ）

別のワークフローをサブルーチンとして呼び出す。

steps:
  - name: run-sub
    call: sub-workflow-name    # 呼び出し先ワークフロー名
    overrides:                  # プロバイダ/モデル上書き（任意）
      provider_options:
        claude:
          model: claude-opus-4-5
    rules:
      - condition: completed
        next: next-step

• 呼び出し先には subworkflow: { callable: true } が必要
• 再帰呼び出し検知あり、最大ネスト深度: 5

システムステップ（kind: system）

AIエージェントを介さず実行されるステップ。副作用（PR作成・タスクキュー操作等）を実行する。

steps:
  - name: enqueue
    kind: system
    system_inputs:
      task: context.task        # ランタイムコンテキストをバインド
    effects:
      - type: enqueue_task
        workflow: default
    rules:
      - when: "effect.enqueued == true"
        next: next-step

effects の種別: enqueue_task, comment_pr, sync_with_root, resolve_conflicts_with_ai, merge_pr

構造化出力（structured_output:）

ステップ出力をJSON スキーマでバリデーション・保存する。

schemas:
  review-result:
    type: object
    properties:
      approved: { type: boolean }
      issues: { type: array, items: { type: string } }

steps:
  - name: review
    instruction: review
    structured_output:
      schema_ref: review-result   # schemas: マップのキーを参照
    rules:
      - when: "structured.review.approved == true"
        next: COMPLETE
      - condition: needs_fix
        next: fix

他ステップから {structured:step-name.field} でテンプレート参照可能。

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

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

ディレクトリ構造

~/.takt/
├── workflows/
│   └── my-workflow.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: レポートの構造定義。

```markdown
# {レポートタイトル}

## 結果: APPROVE / REJECT

## サマリー
{1-2文で要約}

## 詳細
| 観点 | 結果 | 備考 |
|------|------|------|
```

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

Step 5: Loop Monitor（任意）

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

loop_monitors:
  - cycle: [ai_antipattern_review, ai_antipattern_fix]
    threshold: 3
    judge:
      persona: supervisor
      instruction: loop-monitor-ai-antipattern-fix   # ビルトインファセット参照
      rules:
        - condition: 健全（進捗あり）
          next: ai_antipattern_review
        - condition: 非生産的（改善なし）
          next: reviewers
  - cycle: [reviewers, fix]
    threshold: 3
    judge:
      persona: supervisor
      instruction: loop-monitor-reviewers-fix        # ビルトインファセット参照
      rules:
        - condition: 健全（指摘数が減少、修正が反映されている）
          next: reviewers
        - condition: 非生産的（同じ指摘が繰り返される）
          next: supervise

Step 6: 検証

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

• セクションマップのキーとステップ内の参照が一致
• セクションマップのパスが実際のファイル位置と一致（ワークフローYAMLからの相対パス）
• ビルトイン参照（bare name）とカスタム参照（セクションマップキー）が混在していないか
• initial_step が steps 配列内に存在
• 全ステップの rules.next が有効な遷移先（他のステップ名 or COMPLETE/ABORT）
• parallel ステップの親ルールが all() / any() を使用
• parallel サブステップのルールに next がない（親が制御）

バリデーション

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

bash .agents/skills/takt-workflow-builder/scripts/validate-takt-files.sh

検証項目:

• ワークフロー YAML: 必須フィールド（name/initial_step/steps）、initial_step の step 参照、ファセットファイル参照の実在
• ファセット .md: 空チェック、persona/policy/knowledge は # 見出し 必須、instruction/output-contract は内容存在

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