takt-facet

TAKT Facet Creator

Individually create and edit the five types of TAKT facet files.

Prerequisite takt version: v0.30.0

Reference materials

When creating a facet, refer to the materials in references/takt/builtins/ja/ .

Material	Path	Purpose
Style guide overview	references/takt/builtins/ja/STYLE_GUIDE.md	Positioning of each facet
Persona Guide	references/takt/builtins/ja/PERSONA_STYLE_GUIDE.md	Persona description conventions
Policy Guide	references/takt/builtins/ja/POLICY_STYLE_GUIDE.md	Policy description conventions
Instruction Guide	references/takt/builtins/ja/INSTRUCTION_STYLE_GUIDE.md	Instruction description conventions
Output contract guide	references/takt/builtins/ja/OUTPUT_CONTRACT_STYLE_GUIDE.md	Output contract description conventions
Faceted Prompting	references/takt/docs/faceted-prompting.ja.md	Theory of 5-facet design
Template	references/takt/builtins/ja/templates/	Templates for each facet
Built-in Facet	references/takt/builtins/ja/{personas,policies,instructions,knowledge,output-contracts}/	Existing facet examples

Important: Always read the applicable style guide before creating a facet.

Workflow

Step 1: Determine the facet type

Determine the facet type to create from the user's requirements.

この内容は…
├── 特定エージェントのidentity・専門知識 → Persona
├── 複数エージェントが共有する行動規範 → Policy
├── ムーブメント固有の実行手順 → Instruction
├── 判断の前提となる参照情報 → Knowledge
└── エージェント出力の構造定義 → Output Contract

Facet	Placement	Target	Key judgment
Persona	system prompt	1 Agent	"Is this knowledge specific to this agent?"
Policy	In user message	Multiple agents	"Do multiple agents follow the same rule?"
Instruction	Phase 1 message	1 Movement	"Is this procedure specific to this movement?"
Knowledge	In user message	1+ Agents	"Is it reference information that serves as a premise for judgment?"
Output Contract	Phase 2 message	1 Report	"Will subsequent steps reference it in{report:filename}?"

Step 2: Check built-ins

Check built-in facets of the same type and determine whether they can be reused.

Facet	Built-in examples
Persona	coder, planner, architecture-reviewer, qa-reviewer, supervisor, security-reviewer
Policy	coding, review, testing, qa, ai-antipattern
Instruction	plan, implement, review-arch, review-qa, supervise, fix, loop-monitor-ai-fix, loop-monitor-reviewers-fix
Knowledge	architecture, backend, cqrs-es, frontend, security
Output Contract	plan, architecture-review, ai-review, summary, validation

Reuse judgment: If a built-in is sufficient, do not create a custom facet.

Step 3: Select a template and create

Persona

Template: templates/personas/{simple,expert,character}.md

Template	Purpose	Example
simple.md	No domain knowledge	coder, planner
expert.md	With domain knowledge	architecture-reviewer
character.md	Unique personality/tone	melchior, balthasar

# {エージェント名}

{1-2文のロール定義。「あなたは〜です。」で始める}

## 役割の境界

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

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

## 行動姿勢

- ...（3-8項目）

## ドメイン知識（expertのみ）

### {観点}
...

Size guideline: simple 30-50 lines (max 100 lines), expert 50-300 lines (max 550 lines)

Prohibited items:

• Transcribing detailed policy rules (code examples, tables) (one-line behavioral guidelines are OK)
• Piece-specific concepts (movement names, report file names)
• Tool-specific paths (.takt/runs/, etc.)
• Execution procedures

Policy

Template: templates/policies/policy.md

# {ポリシー名}

{1文の目的説明}

## 原則

| 原則 | 基準 |
|------|------|
| ... | ... |

## {ルールカテゴリ1}

{テーブル、コード例、箇条書きを自由に組み合わせ}

Size guideline: 60-250 lines (max 300 lines)

Prohibited items:

• Knowledge specific to a particular agent
• Piece-specific concepts, tool-specific paths
• Execution procedures

Instruction

Template: templates/instructions/{plan,implement,review,fix,supervise,...}.md

{目的宣言。1-2行、命令形}

**注意:** {条件付き注意事項（該当する場合）}

**やること:**
1. {手順1}
2. {手順2}
3. {手順3}

**必須出力（見出しを含める）**
## {出力セクション1}
- {内容}
## {出力セクション2}
- {内容}

Size guideline: Review sub-step 5-12 lines, planning/revision 10-20 lines, implementation/verification 30-50 lines

Prohibited items:

• Persona content (expertise, behavioral stance)
• Policy content (shared coding principles)
• Manual description of automatically injected variables ({task}, {previous_response})
• Direct reference to other movement names

Template variables(available):

• {iteration}, {max_movements}, {movement_iteration}
• {report_dir}, {report:filename}, {cycle_count}

Knowledge

Template: templates/knowledge/knowledge.md

# {ドメイン名}知識

## {トピック1}

{概要。1-2文}

| 基準 | 判定 |
|------|------|
| ... | ... |

### {サブトピック}

{コード例で具体的に}

## {トピック2}

| パターン | 例 | 問題 |
|---------|-----|------|
| ... | `{コード}` | ... |

検証アプローチ:
1. {手順}

Characteristics: Descriptive ("this is how it is"). Provides the "WHY" of the policy.

Output Contract

Template: templates/reports/{plan,review,validation,summary,...}.md

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

## 結果: APPROVE / REJECT

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

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

**認知負荷軽減ルール:**
- APPROVE → サマリーのみ（5行以内）
- REJECT → 問題点を表形式で（30行以内）

Additional structure of the review output contract (v0.30.0~):

In review-type output contracts, the following section structure is used to track findings across iterations:

Section	Content
## 今回の指摘（new）	Findings newly discovered this time.finding_id, family_tag with
## 継続指摘（persists）	Findings that remain uncorrected since last time
## 解消済み（resolved）	Items that were pointed out last time but resolved this time
## 再開指摘（reopened）	Findings that were once resolved but recurred

• family_tag: A tag that groups related findings across iterations
• REJECT judgment condition: new、persists, or reopened is 1 or more

Size guideline: 10-25 lines (upper limit 30 lines, excluding the cognitive load reduction rule)

Status Pattern: APPROVE / REJECT(binary),APPROVE / IMPROVE / REJECT(ternary),完了(fixed value)

Prohibited items:

• Execution procedure (responsibility of the instruction)
• Details of judgment criteria (responsibility of the persona/instruction)

Step 4: Apply common rules

Check the rules common to all facets.

Rule	Content
Heading depth	### until.#### or deeper is not allowed
Code examples	Pairs of good examples/bad examples.// REJECT // OK Comment
Writing style	Persona/policy/knowledge: plain style. Instruction: polite language (imperative tone)
File naming	{name}.md, hyphen-separated, lowercase English
Placement	~/.takt/{facet-type}/ or a project-specific location

Step 5: Verification

Check the quality of the created facets.

Common to all facets:

• #### Is there no nesting at or below
• Does it follow the file naming convention
• Is it within the size limit

Persona:

• Is the role definition 1-2 sentences
• Are the responsible agent names present in "what to do" and "what not to do"
• Are detailed policy rules not mixed in
• Are there no piece-specific concepts

Policy:

• Is the purpose explanation 1 sentence
• Is there a principles table
• Is it applicable to multiple agents

Instruction:

• Does it begin with an imperative form
• Are automatically injected variables not manually described
• Are persona/policy contents not mixed in

Knowledge:

• Is the writing style descriptive (declarative)
• Is it concrete with tables and code examples?

Output Contract:

• ``Is it enclosed in a `markdown code block?
• Do review-related items have status and cognitive load reduction rules?
• Is there no numeric prefix in the file name?

Validation

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

bash .agents/skills/takt-facet/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 are # 見出し required, instruction/output-contract content existence

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