diff --git a/CHANGELOG.md b/CHANGELOG.md index f055ff6..2ce7b42 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/CLAUDE.md b/CLAUDE.md index 6317d24..72e3782 100644 --- a/CLAUDE.md +++ b/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/.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..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 diff --git a/docs/CHANGELOG.ja.md b/docs/CHANGELOG.ja.md index cdb724d..0a58fca 100644 --- a/docs/CHANGELOG.ja.md +++ b/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) diff --git a/docs/agents.md b/docs/agents.md index 0f252ec..a6b1608 100644 --- a/docs/agents.md +++ b/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/.md` (name-based persona) +- explicit path (for example `~/.takt/facets/personas/.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/.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/.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 diff --git a/docs/data-flow.md b/docs/data-flow.md index 25fc126..4c2514c 100644 --- a/docs/data-flow.md +++ b/docs/data-flow.md @@ -665,7 +665,7 @@ const match = await detectMatchedRule(step, response.content, tagContent, {...}) **主要な処理**: 1. **エージェント仕様解決**: - ビルトインエージェント (`coder`, `architect`, など) - - カスタムエージェント (`.takt/agents.yaml`) + - カスタムエージェント（`~/.takt/personas/.md`） - プロンプトファイル (`.md`) 2. **プロバイダー取得**: