docs: align agent/custom persona documentation

CHANGELOG.md

@@ -30,7 +30,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
-- BREAKING: カスタムエージェント定義（`.takt/agents.yaml`）から `provider` / `model` フィールドを削除。エージェントのプロバイダー・モデルはピース側の解決ロジック（CLI → persona_providers → ステップ → ローカル → グローバル）に統一 (#390)
+- BREAKING: カスタムエージェント定義（`~/.takt/personas/*.md`）の `provider` / `model` を解釈しない方針とし、エージェントのプロバイダー・モデルはピース側の解決ロジック（CLI → persona_providers → ステップ → ローカル → グローバル）に統一 (#390)
 - エージェントの provider/model 解決ロジックを `resolveAgentProviderModel` に一元化し、ムーブメント解決と同じ優先順位チェーンを使用するよう変更 (#386)
 - `movement:start` イベントが `providerInfo` を含むよう変更し、表示側でのプロバイダー再解決を不要に (#390)
 - `takt list` の「Sync with root」を「Merge from root」にリネーム (#394)

CLAUDE.md

@@ -171,8 +171,8 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
 **Agent Runner** (`src/agents/runner.ts`)
 - Resolves agent specs (name or path) to agent configurations
 - Agent is optional — movements can execute with `instruction_template` only (no system prompt)
-- 4-layer resolution for provider/model: options.provider → options.stepProvider → config.provider → agentConfig.provider
+- 5-layer resolution for provider/model: CLI `--provider` / `--model` → persona_providers → movement override → project `.takt/config.yaml` → global `~/.takt/config.yaml`
-- Custom agents via `.takt/agents.yaml` or prompt files (.md)
+- Custom personas via `~/.takt/personas/<name>.md` or prompt files (.md)
 - Inline system prompts: If agent file doesn't exist, the agent string is used as inline system prompt
 
 **Provider Integration** (`src/infra/providers/`)
@@ -258,7 +258,6 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
 
 .takt/                    # Project-level config
   config.yaml             # Project configuration
-  agents.yaml             # Custom agent definitions
   facets/                 # Project-level facets
   tasks/                  # Task files for takt run
   runs/                   # Execution reports (runs/{slug}/reports/)
@@ -479,10 +478,11 @@ others_category_name: "Other Pieces"
 
 Model is resolved in the following priority order:
 
-1. **Piece movement `model`** - Highest priority (specified in movement YAML)
+1. **Persona-level `model`** - `persona_providers.<persona>.model`
-2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml`
+2. **Movement `model`** - `step.model` / `stepModel` (`piece movement` field)
-3. **Global config `model`** - Default model in `~/.takt/config.yaml`
+3. **CLI/task override `model`** - `--model` or task options
-4. **Provider default** - Falls back to provider's default (Claude: sonnet, Codex: gpt-5.2-codex)
+4. **Local/Global config `model`** - `.takt/config.yaml` and `~/.takt/config.yaml` when the resolved provider matches
+5. **Provider default** - Falls back to provider's default (for example, Claude: sonnet, Codex: gpt-5.2-codex)
 
 ### Loop Detection
 

docs/CHANGELOG.ja.md

@@ -30,7 +30,7 @@
 
 ### Changed
 
-- BREAKING: カスタムエージェント定義（`.takt/agents.yaml`）から `provider` / `model` フィールドを削除。エージェントのプロバイダー・モデルはピース側の解決ロジック（CLI → persona_providers → ステップ → ローカル → グローバル）に統一 (#390)
+- BREAKING: カスタムエージェント定義（`~/.takt/personas/*.md`）の `provider` / `model` を解釈しない方針とし、エージェントのプロバイダー・モデルはピース側の解決ロジック（CLI → persona_providers → ステップ → ローカル → グローバル）に統一 (#390)
 - エージェントの provider/model 解決ロジックを `resolveAgentProviderModel` に一元化し、ムーブメント解決と同じ優先順位チェーンを使用するよう変更 (#386)
 - `movement:start` イベントが `providerInfo` を含むよう変更し、表示側でのプロバイダー再解決を不要に (#390)
 - `takt list` の「Sync with root」を「Merge from root」にリネーム (#394)

docs/agents.md

@@ -1,6 +1,6 @@
 # Agent Guide
 
-This guide explains how to configure and create custom agents in TAKT.
+This guide explains how to configure custom personas in TAKT.
 
 ## Built-in Personas
 
@@ -15,132 +15,55 @@ TAKT includes built-in personas (located in `builtins/{lang}/facets/personas/`):
 | **security-reviewer** | Security vulnerability assessment |
 | **supervisor** | Final verification, validation, and approval |
 
-## Specifying Personas
+## Custom Personas
 
-In piece YAML, personas are specified via section maps:
+### Creating a Persona File
+
+Create a Markdown file with your persona instructions.
+
+Custom personas are loaded from:
+
+- `~/.takt/personas/<name>.md` (name-based persona)
+- explicit path (for example `~/.takt/facets/personas/<name>.md`, or a repertoire facet path) in piece YAML
+
+### Specifying Personas in Pieces
+
+In piece YAML, personas are usually configured via `personas` section map:
 
 ```yaml
-# Section map at top level (key → file path relative to piece YAML)
+# Section map at top level (key -> file path relative to piece YAML)
 personas:
   coder: ../facets/personas/coder.md
   reviewer: ../facets/personas/architecture-reviewer.md
 
 movements:
   - name: implement
-    persona: coder       # References the key in section map
+    persona: coder       # References the key in the section map
   - name: review
-    persona: reviewer    # References the key in section map
+    persona: reviewer    # References the key in the section map
 ```
 
-Alternatively, use file paths directly:
+You can also specify a persona file path directly:
 
 ```yaml
 movements:
-  - name: implement
-    persona: ../facets/personas/coder.md     # Relative to piece file
   - name: review
-    persona: ~/.takt/facets/personas/my-reviewer.md  # User custom
+    persona: ~/.takt/personas/my-reviewer.md
 ```
 
-## Creating Custom Personas
+If `persona` is a bare name and no section-map entry exists, TAKT checks `~/.takt/personas/<name>.md` as a fallback.
 
-### Persona Prompt File
+> **Note**: Personas do not need to output status markers manually. The engine auto-injects status routing rules into the generated instructions.
 
-Create a Markdown file with your persona's instructions:
+## Behavior Notes
 
-```markdown
+`agents.yaml` is not used in the current TAKT implementation.
-# Security Reviewer
+Use `~/.takt/personas/<name>.md` or direct file references in piece YAML instead.
-
-You are a security-focused code reviewer.
-
-## Your Role
-- Check for security vulnerabilities
-- Verify input validation
-- Review authentication logic
-
-## Guidelines
-- Focus on OWASP Top 10 issues
-- Check for SQL injection, XSS, CSRF
-- Verify proper error handling
-```
-
-> **Note**: Personas do NOT need to output status markers manually. The piece engine auto-injects status output rules into agent instructions based on the movement's `rules` configuration. Agents output `[STEP:N]` tags (where N is the 0-based rule index) which the engine uses for routing.
-
-### Using agents.yaml
-
-For more control, define agents in `.takt/agents.yaml`:
-
-```yaml
-agents:
-  - name: my-reviewer
-    prompt_file: .takt/prompts/reviewer.md
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-```
-
-### Agent Configuration Options
-
-| Field | Description |
-|-------|-------------|
-| `name` | Agent identifier (referenced in piece movements) |
-| `prompt_file` | Path to Markdown prompt file |
-| `prompt` | Inline prompt text (alternative to `prompt_file`) |
-| `allowed_tools` | List of tools the agent can use |
-
-### Available Tools
-
-- `Read` — Read files
-- `Glob` — Find files by pattern
-- `Grep` — Search file contents
-- `Edit` — Modify files
-- `Write` — Create/overwrite files
-- `Bash` — Execute commands
-- `WebSearch` — Search the web
-- `WebFetch` — Fetch web content
 
 ## Best Practices
 
-1. **Clear role definition** — State what the agent does and doesn't do
+1. **Clear role definition** — State what the persona does and does not do
-2. **Minimal tools** — Grant only necessary permissions
+2. **Minimal permission scope** — Keep rules and instructions focused
-3. **Use `edit: false`** — Review agents should not modify files
+3. **Use `edit: false`** — Review personas should not modify files
-4. **Focused scope** — One agent, one responsibility
+4. **Focused scope** — One persona, one responsibility
-5. **Customize via `/eject`** — Copy builtin personas to `~/.takt/` for modification rather than writing from scratch
+5. **Customize via `/eject`** — Copy builtin personas to `~/.takt/` and modify locally
-
-## Example: Multi-Reviewer Setup
-
-```yaml
-# .takt/agents.yaml
-agents:
-  - name: performance-reviewer
-    prompt_file: .takt/prompts/performance.md
-    allowed_tools: [Read, Glob, Grep, Bash]
-```
-
-```yaml
-# piece.yaml
-personas:
-  coder: ../facets/personas/coder.md
-
-movements:
-  - name: implement
-    persona: coder
-    edit: true
-    rules:
-      - condition: Implementation complete
-        next: review
-      - condition: Cannot proceed
-        next: ABORT
-
-  - name: review
-    persona: performance-reviewer    # References agents.yaml by name
-    edit: false
-    rules:
-      - condition: Approved
-        next: COMPLETE
-      - condition: Needs fix
-        next: implement
-    instruction_template: |
-      Review the implementation for performance issues.
-```

docs/data-flow.md

@@ -665,7 +665,7 @@ const match = await detectMatchedRule(step, response.content, tagContent, {...})
 **主要な処理**:
 1. **エージェント仕様解決**:
    - ビルトインエージェント (`coder`, `architect`, など)
-   - カスタムエージェント (`.takt/agents.yaml`)
+   - カスタムエージェント（`~/.takt/personas/<name>.md`）
    - プロンプトファイル (`.md`)
 
 2. **プロバイダー取得**: