docs: align agent/custom persona documentation
This commit is contained in:
nrslib
parent
00b3277324
commit
9a953e4774
@ -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)
|
||||
|
||||
14
CLAUDE.md
14
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
|
||||
- Custom agents via `.takt/agents.yaml` or prompt files (.md)
|
||||
- 5-layer resolution for provider/model: CLI `--provider` / `--model` → persona_providers → movement override → project `.takt/config.yaml` → global `~/.takt/config.yaml`
|
||||
- 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)
|
||||
2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml`
|
||||
3. **Global config `model`** - Default model in `~/.takt/config.yaml`
|
||||
4. **Provider default** - Falls back to provider's default (Claude: sonnet, Codex: gpt-5.2-codex)
|
||||
1. **Persona-level `model`** - `persona_providers.<persona>.model`
|
||||
2. **Movement `model`** - `step.model` / `stepModel` (`piece movement` field)
|
||||
3. **CLI/task override `model`** - `--model` or task options
|
||||
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
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
135
docs/agents.md
135
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
|
||||
# Security Reviewer
|
||||
|
||||
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
|
||||
`agents.yaml` is not used in the current TAKT implementation.
|
||||
Use `~/.takt/personas/<name>.md` or direct file references in piece YAML instead.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear role definition** — State what the agent does and doesn't do
|
||||
2. **Minimal tools** — Grant only necessary permissions
|
||||
3. **Use `edit: false`** — Review agents should not modify files
|
||||
4. **Focused scope** — One agent, one responsibility
|
||||
5. **Customize via `/eject`** — Copy builtin personas to `~/.takt/` for modification rather than writing from scratch
|
||||
|
||||
## 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.
|
||||
```
|
||||
1. **Clear role definition** — State what the persona does and does not do
|
||||
2. **Minimal permission scope** — Keep rules and instructions focused
|
||||
3. **Use `edit: false`** — Review personas should not modify files
|
||||
4. **Focused scope** — One persona, one responsibility
|
||||
5. **Customize via `/eject`** — Copy builtin personas to `~/.takt/` and modify locally
|
||||
|
||||
@ -665,7 +665,7 @@ const match = await detectMatchedRule(step, response.content, tagContent, {...})
|
||||
**主要な処理**:
|
||||
1. **エージェント仕様解決**:
|
||||
- ビルトインエージェント (`coder`, `architect`, など)
|
||||
- カスタムエージェント (`.takt/agents.yaml`)
|
||||
- カスタムエージェント（`~/.takt/personas/<name>.md`）
|
||||
- プロンプトファイル (`.md`)
|
||||
|
||||
2. **プロバイダー取得**:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user