j5ik2o-takt-facet-builder

TAKT Facet Builder

Create and edit TAKT's five types of facet files individually.

Prerequisite takt version: v0.47.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
Built-in Facets	`references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/`	Existing facet examples

Note: references/takt/builtins/{ja,en}/templates/ also actually exists in v0.43.0. It may be referenced as a template, but align the actual naming, responsibility division, and writing style with the built-in facets as the source of truth.

Important: Always read the corresponding 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

Facets	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 Step	"Is this procedure specific to this step?"
Knowledge	in user message	1+ Agents	"Is it reference information that serves as a premise for judgment?"
Output Contract	Phase 2 message	1 Report	"Does a subsequent`{report:filename}`refer to it?"

Step 2: Check built-ins

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

Facets	Built-in examples
Persona	coder, planner, architect-planner, architecture-reviewer, qa-reviewer, supervisor, security-reviewer, frontend-reviewer, cqrs-es-reviewer, pure-reviewer, testing-reviewer, terraform-reviewer, terraform-coder, dual-supervisor, research-analyzer, research-digger, research-planner, research-supervisor, conductor, pr-commenter, test-planner, ai-antipattern-reviewer, coding-reviewer, findings-manager, melchior, balthasar, casper
Policy	coding, review, testing, qa, ai-antipattern, design-fidelity, design-planning, task-decomposition, screen-api, existing-system-respect, research, terraform
Instruction	plan, plan-investigate, plan-test, implement, implement-after-tests, implement-test, implement-terraform, write-tests-first, team-leader-implement, dual-team-leader-implement, plan-maintenance, write-tests-maintenance, implement-maintenance, fix-maintenance, supervise-maintenance, review-coding, review-arch, review-qa, review-security, review-frontend, review-cqrs-es, review-pure, review-test, review-terraform, supervise, fix, fix-supervisor, arbitrate, architect, ai-antipattern-review, ai-antipattern-fix, loop-monitor-ai-antipattern-fix, loop-monitor-reviewers-fix, findings-manager, research-plan, research-dig, research-analyze, research-supervise, gather-review, architecture-audit-plan, architecture-audit-review, architecture-audit-supervise, architecture-audit-team-leader, audit-security-plan, audit-security-review, audit-security-supervise, audit-security-team-leader, e2e-audit-plan, e2e-audit-review, e2e-audit-supervise, e2e-audit-team-leader, e2e-coverage-implement, e2e-coverage-plan, e2e-coverage-supervise, unit-audit-plan, unit-audit-review, unit-audit-supervise, unit-audit-team-leader
Knowledge	architecture, backend, cqrs-es, frontend, security, task-decomposition, takt, terraform-aws, e2e-testing, react, unit-testing, existing-system, research, research-comparative
Output Contract	plan, architecture-design, architecture-review, ai-antipattern-review, qa-review, security-review, frontend-review, cqrs-es-review, pure-review, testing-review, terraform-review, coding-review, findings-manager, ai-antipattern-review-finding-contract, architecture-review-finding-contract, coding-review-finding-contract, cqrs-es-review-finding-contract, frontend-review-finding-contract, pure-review-finding-contract, qa-review-finding-contract, security-review-finding-contract, terraform-review-finding-contract, testing-review-finding-contract, summary, validation, coder-scope, coder-decisions, maintenance-scope, review-gather, research-report, test-plan, test-report, plan-frontend, architecture-audit-plan, architecture-audit, audit-security, e2e-audit-plan, e2e-audit, e2e-coverage-plan, unit-audit-plan, unit-audit, supervisor-validation

Changes in v0.46.0: requirements-reviewer Persona,review-requirements instruction、requirements-review output contract removed. Instead, use pure-reviewer（review-pure instruction + pure-review output contract).pure-reviewer is not confined to a specialized domain; it is a general-purpose reviewer that judges only "is it okay to merge now?"

Changes in v0.47.0: Added new facets supporting Finding Contract.

Persona: findings-manager(dedicated persona responsible for collating and judging Finding Contracts)
Instruction: findings-manager(instruction for the findings-manager persona)
Output Contract: findings-manager(findings-manager output structure),*-finding-contract series (ai-antipattern-review-finding-contract, architecture-review-finding-contract, coding-review-finding-contract, cqrs-es-review-finding-contract, frontend-review-finding-contract, pure-review-finding-contract, qa-review-finding-contract, security-review-finding-contract, terraform-review-finding-contract, testing-review-finding-contract). In reviews with a Finding Contract, use the *-finding-contract series instead of the normal output contract.

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

Step 3: Select a template and create

Persona

Reference: references/takt/builtins/ja/facets/personas/ existing facets of

Template	Use case	Example
`simple.md`	No domain knowledge	coder, planner
`expert.md`	With domain knowledge	architecture-reviewer
`character.md`	Unique persona/tone	melchior, balthasar, casper

# {エージェント名}

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

## 役割の境界

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

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

## 行動姿勢

- ...（3-8項目）

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

### {観点}
...

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

Prohibitions:

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

Policy

Reference: references/takt/builtins/ja/facets/policies/ existing facets of

# {ポリシー名}

{1文の目的説明}

## 原則

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

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

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

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

Prohibitions:

Agent-specific knowledge
Workflow-specific concepts, tool-specific paths
Execution procedures

Instruction

Reference: references/takt/builtins/ja/facets/instructions/ existing facets of

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

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

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

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

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

Prohibitions:

Persona content (expertise, behavioral stance)
Policy content (shared coding principles)
Auto-injected variables ({task}, {previous_response}) manual description
Direct references to other step names

Template variables(available):

{iteration}, {max_steps}, {step_iteration}
{report_dir}, {report:filename}, {cycle_count}

Knowledge

Reference: references/takt/builtins/ja/facets/knowledge/ existing facets of

# {ドメイン名}知識

## {トピック1}

{概要。1-2文}

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

### {サブトピック}

{コード例で具体的に}

## {トピック2}

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

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

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

Output Contract

Reference: references/takt/builtins/ja/facets/output-contracts/ existing facets of

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

## 結果: APPROVE / REJECT

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

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

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

Size guideline: 10-25 lines (max 30 lines, excluding cognitive load reduction rules)

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

Structure of the review output contract（v0.30.0〜）:

Add a family_tag column to each finding (categorizing the finding)
Section structure: new(new) → persists(continuing) → resolved(resolved) → reopened(reopened)

Prohibitions:

Execution procedures (responsibility of instructions)
Details of judgment criteria (responsibility of persona/instructions)

Step 4: Apply common rules

Check the rules common to all facets.

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

Step 5: Verification

Check the quality of the created facets.

Common to all facets:

#### No nesting as 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 workflow-specific concepts?

Policy:

Is the purpose description one sentence?
Is there a principles table?
Can it be applied to multiple agents?

Instruction:

Does it start with an imperative form?
Are auto-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 `markdown code blocks?
Do review-related ones have status and cognitive load reduction rules?
Are there no numeric prefixes in the file names?

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:

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 existence

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

About this skill

Reference materials

Workflow

Step 1: Determine the facet type

Step 2: Check built-ins

Step 3: Select a template and create

Persona

Policy

Instruction

Knowledge

Output Contract

Step 4: Apply common rules

Step 5: Verification

Validation