SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstakt-piece-builder

takt-piece-builder

Agents & models

View repository

Updated 10-16 09:57

About this skill

TAKT Piece Builder

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

Prerequisite takt version: v0.31.0

Reference materials

The takt codebase and documentation are references/takt/ are in. Refer to the following as needed.

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

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

Workflow

Step 1: Requirements hearing

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

  1. Purpose: What this piece achieves
  2. Movement composition: What steps are needed (plan→implement→review→supervise, etc.)
  3. Review setup: 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 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→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
frontend.yaml plan→write_tests→implement→ai_review→reviewers→fix→supervise Frontend specialization
backend-mini.yaml / dual-mini.yaml / frontend-mini.yaml plan→implement→supervise Minimal composition
review.yaml / review-fix.yaml Review→fix loop code review
takt-default.yaml plan→write_tests→team_leader_implement→ai_review→reviewers→fix→supervise For TAKT development

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

Step 3: Piece YAML creation

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
    provider_options:          # v0.30.0〜: allowed_tools はここに配置
      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

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: substep rules is for result classification.next is ignored, and the parent rules determines the transition destination.

Design decision guide

Decision point Criteria
edit: true/false True only for movements that change code
session: refresh Start a new session for implementation-type movements
pass_previous_response: false When you do not want review results read directly
required_permission_mode Specify edit when edit permission is required
provider_options.claude.allowed_tools Restrict Claude's tools to use per movement (moved from allowed_tools in v0.30.0)

Rule design

Rule type Notation Usage
Text condition "条件文" Phase 3 tag determination (recommended)
AI determination ai("条件") When tag determination is unsuitable
Exact match all("条件") Only parallel's parent
either any("条件") Only parallel's parent

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

Step 4: Facet file creation

When 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: Placed in the system prompt. Identity + expertise + boundaries.

# {ロール名}

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

## 役割の境界

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

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

## 行動姿勢

- ...

Policy: Code of conduct shared across multiple movements.

# {ポリシー名}

## 原則

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

## 禁止事項

- ...

Instruction: Movement-specific procedures. 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, refer to references/takt/builtins/ja/STYLE_GUIDE.md .

Step 5: Loop Monitor (optional)

Set this when a correction loop is anticipated.

loop_monitors:
  - cycle: [ai_review, ai_fix]
    threshold: 3
    judge:
      persona: supervisor
      instruction: loop-monitor-ai-fix               # ビルトインファセット参照
      rules:
        - condition: 健全（進捗あり）
          next: ai_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

Verify the consistency of the created files:

  • The keys in the section map match the references within the movements
  • 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
  • The rules.next of all movements is a valid transition target (another movement name or COMPLETE/ABORT)
  • The parent rule of the parallel movement is all() / any() uses
  • to the rules of the parallel substep next There is no (controlled by the parent)

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 reference, existence of facet file references
  • facet .md: Empty check, persona/policy/knowledge require # 見出し , instruction/output-contract require content presence

Option --pieces / --facets You can narrow down the targets with .