SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstakt-piece

takt-piece

Agents & models

View repository

Updated 10-15 23:45

About this skill

TAKT Piece Creator

Create TAKT pieces (workflow YAML) and their related facet files.

Prerequisite takt version: v0.30.0

Reference materials

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

Material path Purpose
YAML schema references/takt/builtins/skill/references/yaml-schema.md Piece 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 pieces references/takt/builtins/ja/pieces/ 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/{personas,policies,instructions,knowledge,output-contracts}/ Existing facet examples

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

Workflow

Step 1: Requirements hearing

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

  1. Purpose: What this piece aims to achieve
  2. Movement 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 for pieces and facets (default: ~/.takt/pieces/）

Step 2: Built-in reference

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

Built-in Composition Purpose
default.yaml plan→implement→ai_review→reviewers(arch+qa)→supervise Standard development (backend)
dual.yaml plan→implement→ai_review→reviewers(arch+frontend+security+qa)→supervise Full stack (FE+BE)
dual-mini.yaml plan→implement→supervise Full-stack minimal composition
backend.yaml plan→implement→ai_review→reviewers(arch+qa)→supervise Backend specialization
frontend.yaml plan→implement→ai_review→reviewers(frontend+qa)→supervise Frontend specialization
review.yaml Review only Code review only
review-fix.yaml review→fix loop Review + automatic fix
research.yaml Investigation→Report Research/Analysis

Note: v0.28.1 で expert → dual renamed todefault-mini has been discontinued.*-cqrs, *-mini, *-review, *-review-fix Many variations such as references/takt/builtins/ja/pieces/ have been added. For the full list, refer to

Judging built-in reuse

Before creating custom facets, first check whether built-ins can be used as substitutes. Built-ins are tested in takt itself and are advantageous in terms of consistency and maintainability.

Role Built-in name Cases where custom is needed
Planning planner Only when there is a project-specific planning method
Implementation coder Only when there are constraints for a special tech stack
review architecture-reviewer, frontend-reviewer, security-reviewer, qa-reviewer Only when unique review perspectives are needed
Supervision supervisor —
Fix (reuse coder) Only when there are fix-specific constraints

Judgment criteria: If you cannot explain in one sentence, "How is this facet different from a built-in?", use the built-in.

Step 3: Create piece YAML

Create YAML with the following structure.

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 example

  - 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

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

Design decision guide

Decision point Criteria
edit: true/false true only for movements that change code
session: refresh implement と fix Set this. Prevents accumulation of long context and carries over necessary information via reports
pass_previous_response: false When you do not want the review results read directly
required_permission_mode When edit permission is required, specify edit edit
quality_gates Completion criteria per movement (AI instructions). Example: ["All tests pass", "No lint errors"]
provider_options Provider-specific settings.allowed_tools は provider_options.claude.allowed_tools Place in (v0.30.0~)
Placement of CI execution responsibility CI involving builds is run in edit: true の fix/implement movements and recorded in the report.supervise For edit: false movements such as
supervise failure transition If the problem can be resolved by a fix, transition to fix .plan only when a fundamental design change is required.supervise → plan An easy transition to becomes a cause of loops

Safety rules for edit:false movements

edit: false Movements such as (plan, review, supervise, etc.) areread-only sandbox. This is a constraint enforced by the takt engine, and the following must always be observed:

  1. allowed_tools に Bash Do not include — Bash If there is , the agent will attempt build commands (cargo check, npm test etc.) and will always fail. What is needed for read-only is only Read, Glob, Grep etc.
  2. Explicitly state "what not to do" in the instructions — Explicitly state "Do not compile, build, or run tests"
  3. If CI/build results are needed, — edit: true Run the build in the preceding movement (implement/fix) and record it in the report. The edit:false movement reads that report and makes a judgment
# ❌ 間違い: 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

Rule design

Rule type Notation Usage distinction
Text condition "条件文" Phase 3 tag determination (recommended)
AI determination ai("条件") When tag determination is unsuitable
All match all("条件") parallel parent only
Any any("条件") parallel parent only

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

Step 4: Facet file creation

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

Directory structure

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

Facet creation conventions

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

# {ロール名}

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

## 役割の境界

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

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

## 行動姿勢

- ...

Policy: Code of conduct shared by multiple movements.

# {ポリシー名}

## 原則

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

## 禁止事項

- ...

Instruction: Movement-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 ("it is like this").

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

Note (v0.30.0): instruction_template It is recommended to specify a built-in facet name for . This improves consistency and maintainability. Inline text can still be used, but if an equivalent template exists as a built-in, prefer the reference name. If a custom template is needed,instructions register the custom facet in the section map and specify its key name.

Loop Monitor safety rules

  • loop_monitors[*].cycle The "healthy (progress made)" transition destination of must always be the first node of cycle as the first node
    • Example: cycle: [reviewers, fix] In the case of , when healthy next: reviewers
  • judge.instruction_template referenced by {report:...} is allowed only for reports generated by movements within the target cycle Only reports generated by movements within are allowed
    • Reports dedicated to movements outside the cycle (e.g., verify) are not referenced
  • If the above two points are not satisfied, the loop continuation determination will break, so fix it before saving

Step 6: Validation

Check the consistency of the created file:

  • The keys in the section map and the references within movements match
  • The paths in the section map match the actual file locations (relative paths from the piece YAML)
  • Whether built-in references (bare name) and custom references (section map keys) are mixed
  • initial_movement が movements Exists in the array
  • All movements' rules.next are valid transition destinations (another movement name or COMPLETE/ABORT)
  • The parent rule of a parallel movement uses all() / any() use
  • The rules of parallel substeps do not have next (controlled by the parent)
  • When the loop monitor is healthy next が cycle matches the first node
  • loop monitor の instruction_template does not reference reports outside the cycle
  • edit: false movement's allowed_tools に Bash is not included
  • implement / fix to the movement session: refresh is set
  • custom facets that can be replaced by built-ins are not unnecessarily created

Validation

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

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

Verification items:

  • Piece YAML: required fields (name/initial_movement/movements）、initial_movement movement references, existence of facet file references
  • loop_monitors: when healthy next is the cycle's first node,instruction_template report references are limited to artifacts generated by movements within the cycle
  • Facet .md: empty check, persona/policy/knowledge are # 見出し required, instruction/output-contract must have content

Option --pieces / --facets can be used to narrow down the target.