j5ik2o-takt-workflow-builder

TAKT Workflow Builder

Create a TAKT workflow (workflow YAML) and its related facet files.

Prerequisite takt version: v0.47.0

Reference materials

takt's codebase and documentation are references/takt/ are located in. Refer to the following as needed.

Material	path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Workflow YAML structure definition
Engine specification	references/takt/builtins/skill/references/engine.md	Details of prompt construction and rule evaluation
Faceted Prompting	references/takt/docs/faceted-prompting.ja.md	Theory of 5-facet design
built-in workflows	references/takt/builtins/ja/workflows/	Examples (default.yaml, dual.yaml, etc.)
style guide	references/takt/builtins/ja/STYLE_GUIDE.md	Facet description conventions
persona guide	references/takt/builtins/ja/PERSONA_STYLE_GUIDE.md	Persona description conventions
built-in facets	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	Existing facet examples

Important: Before creating a workflow, read references/takt/builtins/ja/workflows/default.yaml and understand the project's patterns.

Workflows

Step 1: Requirements hearing

Confirm the following (ask the user about anything unclear):

1. Purpose: What is to be achieved with this workflow
2. Step composition: What steps are needed (plan→implement→review→supervise, etc.)
3. Review structure: Whether there is parallel review, types of reviewers
4. Loop control: Whether there is a fix loop and its threshold
5. Output destination: Placement location of the workflow and facets (default: ~/.takt/workflows/）

Step 2: Built-in reference

Built-in workflows (references/takt/builtins/ja/workflows/) to find similar patterns.

built-in	Composition	Purpose
default.yaml	plan→write_tests→implement→ai_review→reviewers(arch+qa)→fix→supervise	Standard development
dual.yaml	plan→write_tests→team_leader_implement→ai_review→reviewers(2 stages)→fix→supervise	frontend + backend
backend.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	Backend specialization
backend-cqrs.yaml / backend-cqrs-mini.yaml	CQRS+ES backend development	CQRS/ES specialization
frontend.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	Frontend specialization
frontend-maintenance.yaml	plan→write_tests→implement→ai_review→reviewers→fix→supervise	Existing frontend maintenance
backend-mini.yaml / dual-mini.yaml / dual-cqrs-mini.yaml / frontend-mini.yaml	plan→implement→supervise	Minimal composition
review-default.yaml / review-backend.yaml / review-dual.yaml / review-frontend.yaml	review workflow	code review
review-fix-default.yaml / review-fix-backend.yaml / review-fix-dual.yaml / review-fix-frontend.yaml	Review→fix loop	Review + fix
takt-default.yaml / review-takt-default.yaml / review-fix-takt-default.yaml	For TAKT development	TAKT development
takt-default-with-fc.yaml	takt-default with Finding Contract (plan→write_tests→draft→peer-review-with-fc→supervise)	TAKT development (Finding Contract enabled)
peer-review-with-fc.yaml	peer-review with Finding Contract (6 parallel reviews + findings-manager verification),callable: true	peer-review with Finding Contract
audit-architecture.yaml / audit-architecture-backend.yaml / audit-architecture-dual.yaml / audit-architecture-frontend.yaml	Architecture audit	Quality audit
audit-e2e.yaml / audit-security.yaml / audit-unit.yaml	E2E/security/unit test audit	Quality audit
terraform.yaml	infrastructure	Terraform
research.yaml / deep-research.yaml	Investigation/research	research
magi.yaml / compound-eye.yaml	Special composition	Multi-perspective analysis

Representative examples added/expanded in v0.42.0:

• default-draft.yaml, draft.yaml: Draft operation assuming managed PR
• default-high.yaml: High-load profile including deeper review and verification
• default-mini.yaml: standard minimal configuration
• default-peer-review.yaml, peer-review.yaml: branching with explicit peer review
• auto-improvement-loop.yaml: system step と managed_pr self-improvement loop using
• review-backend-cqrs.yaml, review-dual-cqrs.yaml, review-fix-backend-cqrs.yaml, review-fix-dual-cqrs.yaml: CQRS-style review / review-fix
• takt-default-refresh-fast.yaml, takt-default-refresh-all.yaml: TAKT's own refresh-style workflows

Representative examples added/expanded in v0.43.0:

• frontend-maintenance.yaml: frontend maintenance workflow premised on respecting existing systems and managing maintenance scope
• default-peer-review.yaml, peer-review.yaml: coding-review added parallel review
• quality_gates の type: command: command gate can be executed within the worktree after step completion (requires workflow_command_gates.custom_scripts: true in configuration)

Representative examples added/expanded in v0.44.0:

• coding-review parallel review (coding-reviewer personas + review-coding instruction + coding-review output contract) expanded to the parallel review stages of all built-in review / review-fix / development workflows (backend, frontend, dual, terraform and their variants). Intentionally minimal *-mini と compound-eye is excluded
• New provider kiro(kiro-cli) added. provider、provider_options.<provider> can be used in places where a provider can be specified (such as config's kiro ). In the initial implementation, model is not passed as a CLI flag

Representative examples added/expanded in v0.46.0:

• requirements-reviewer personas andreview-requirements instruction・requirements-review output contract removed. Instead, the newly established pure-reviewer persona (review-pure instruction + pure-review output contract) was incorporated into peer-review / review / review-fix workflows.pure-reviewer is a general-purpose reviewer that does not confine itself to a specialized domain and judges only whether it is okay to merge now
• provider_options.$ref support.provider_options blocks can be externalized to a common YAML using a path relative to the workflow file (inline values override the same leaf)
• Built-in provider-options/ presets added (provider-options/edit.yaml, review-files.yaml, review-readonly.yaml, review-web.yaml). By referencing these in $ref , it is possible to specify both claude and opencode allowed_tools in one go
• provider_options.opencode.allowed_tools added. OpenCode's tool allowlist can be specified per step / workflow (tool names are lowercase, e.g. read, glob, grep, bash, websearch, webfetch )
• provider_options.kiro.agent added. Kiro CLI's custom agent name can be specified per step / workflow (passed askiro-cli chat --agent .TAKT_PROVIDER_OPTIONS_KIRO_AGENT can also be specified via environment variable)
• team_leader.max_parts → max_concurrency(limit 3) + max_total_parts(limit 20) split (still accepted as a compatibility alias for the old max_parts は max_concurrency )

Representative additions and extensions in v0.47.0:

• BREAKING: provider_options.$ref → provider_options.extends renamed to. The value also changed from a file path (provider-options/edit.yaml) to a bare name (edit). The old $ref becomes invalid, so custom workflows must migrate to extends .
• BREAKING: persona_providers is deprecated. Use provider_routing(project/global settings) instead.provider_routing.personas(matched by raw persona key),provider_routing.tags(matched by step tags),provider_routing.steps(matched by step name) can be routed along 3 axes. Resolution priority: step > provider_routing.steps > provider_routing.tags > provider_routing.personas > persona_providers(deprecated) > workflow > CLI
• Built-in provider-options/ directory moved from builtins/{lang}/workflows/provider-options/ to builtins/{lang}/provider-options/ .extends: edit reference by bare name (3-layer resolver: .takt/provider-options/ → ~/.takt/provider-options/ → builtin）
• Finding Contract（finding_contract: section) added. Structured lifecycle management of review findings (ledger, severity, deduplication). Added new workflows takt-default-with-fc(takt-default with Finding Contract),peer-review-with-fc(peer-review with Finding Contract)
• Step tags（tags: field) can be added to steps and parallel substeps. All built-in workflows have tags such as plan, coding, review, implementation, edit .provider_routing.tags used for per-tag provider/model specification
• peer-review-with-fc.yaml: Finding Contract enabled peer-review (6 parallel + matching by findings-manager).subworkflow: { callable: true } で takt-default-with-fc called from
• Trace discovery enhanced (WorkflowTraceTaskMetadata): task metadata (source, issue/PR number, branch, slug, summary) is propagated to OTel spans and trace discovery, enabling association with executions in Grafana Tempo etc.

Reuse decision: If built-in facets are sufficient, do not create custom facets.

Step 3: Creating workflow YAML

Create YAML with the following structure.

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 commonization via (v0.47.0~, old $ref abolished): provider_options can reference built-in presets and custom YAML in .takt/provider-options/ by bare name. Inline values override the same leaf. Built-in presets: 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]

Note: Old terminology aliases (movements, initial_movement, max_movements, piece_config, piece_categories) remain unusable. Use only the official names.

Parallel Step example

  - 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

Note: Substeps' rules is for result classification.next is ignored, and the parent's rules determines the transition destination.

Finding Contract example (v0.47.0~)

Adding finding_contract: at the workflow top level enables structured lifecycle management of review findings (ledger, severity, deduplication).peer-review-with-fc.yaml A configuration that calls a callable workflow such as call: from a step is recommended.

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

Design decision guide

Decision point	Criteria
edit: true/false	true only for steps that modify code
session: refresh	start a new session in implementation steps
pass_previous_response: false	When you do not want the review results to be read directly
required_permission_mode	When edit permission is required, edit specify
provider_options.claude.allowed_tools	Restrict Claude's tools per step
provider_options.opencode.allowed_tools	Restrict OpenCode's tools per step (lowercase: read, glob, grep, bash etc.)
provider_options.kiro.agent	Specify the Kiro CLI custom agent name (kiro-cli chat --agent passed as)
provider_options.extends	Reference preset YAML by bare name (3-layer resolver: .takt/provider-options/ → ~/.takt/provider-options/ → builtin. inline values override leaf. Old $ref was removed in v0.47.0)
provider_options.<provider>.effort	Specify when increasing thinking depth. Check model compatibility
quality_gates	Completion condition for agent step. String gate and type: command gate can be mixed
tags	Tag array for step / parallel substeps (e.g.: [plan], [coding], [review]）。provider_routing.tags used for per-tag provider/model specification
finding_contract	Add at workflow top level to enable Finding Contract.ledger_path, raw_findings_path, manager（persona/instruction/output_contract) specify

Rule design

Rule type	Notation	Usage
Text condition	"条件文"	Phase 3 tag judgment (recommended)
AI judgment	ai("条件")	When tag judgment is unsuitable
All match	all("条件")	parallel parent only
Any	any("条件")	parallel parent only
Deterministic condition	when: <expr>	Routing without AI (condition: not required)

when: can use comparison operators (==, !=, >, <, >=, <=), boolean logic (&&, \|\|), workflow state references (context.*, structured.*, effect.*).

Special transition targets: COMPLETE(successful termination),ABORT(failed termination)

Subworkflow call (call: step)

Call another workflow as a subroutine.

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

• The callee requires subworkflow: { callable: true } is required
• Recursive call detection present, maximum nesting depth: 5

System step (kind: system）

A step executed without going through an AI agent. Executes side effects (PR creation, task queue operations, etc.).

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 types: enqueue_task, comment_pr, sync_with_root, resolve_conflicts_with_ai, merge_pr

Structured output (structured_output:）

Validate and save step output with a JSON schema.

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

From other steps, {structured:step-name.field} can be referenced as a template.

Step 4: Facet file creation

If a custom facet is needed, create it according to the following conventions.

Directory structure

~/.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

Facet creation conventions

Persona: Place in system prompt. identity + expertise + boundaries.

# {ロール名}

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

## 役割の境界

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

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

## 行動姿勢

- ...

Policy: Behavioral norms shared across multiple steps.

# {ポリシー名}

## 原則

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

## 禁止事項

- ...

Instruction: Step-specific procedure. Describe in imperative form.{task}, {previous_response}is automatically injected, so it is unnecessary.

Knowledge: Reference information that serves as the basis for judgment. Descriptive ("this is how it is").

Output Contract: Report structure definition.

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

## 結果: APPROVE / REJECT

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

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

For detailed style conventions, see references/takt/builtins/ja/STYLE_GUIDE.md .

Step 5: Loop Monitor (optional)

Set this when a revision loop is expected.

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: Verification

Check the consistency of the created files:

• The section map keys and the references within the steps match
• The section map paths match the actual file locations (relative paths from the workflow YAML)
• Whether built-in references (bare name) and custom references (section map keys) are mixed
• initial_step が steps Exists within the array
• All steps' rules.next are valid transition destinations (another step name or COMPLETE/ABORT)
• The parent rule of the parallel step uses all() / any() all() / any()
• The rules of the parallel substeps have no next (controlled by the parent)

Validation

Created/edited files can be mechanically verified with validate-takt-files.sh :

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

Verification items:

• Workflow YAML: Required fields (name/initial_step/steps）、initial_step step references, existence of facet file references
• Facet .md: Empty check, persona/policy/knowledge require # 見出し , instruction/output-contract require content presence

Optional --workflows / --facets can be used to narrow down the targets.