70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
# Agent Guide
|
|
|
|
This guide explains how to configure custom personas in TAKT.
|
|
|
|
## Built-in Personas
|
|
|
|
TAKT includes built-in personas (located in `builtins/{lang}/facets/personas/`):
|
|
|
|
| Persona | Description |
|
|
|---------|-------------|
|
|
| **planner** | Task analysis, spec investigation, and implementation planning |
|
|
| **coder** | Implements features and fixes bugs |
|
|
| **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) |
|
|
| **architecture-reviewer** | Reviews architecture and code quality, verifies spec compliance |
|
|
| **security-reviewer** | Security vulnerability assessment |
|
|
| **supervisor** | Final verification, validation, and approval |
|
|
|
|
## Custom Personas
|
|
|
|
### 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)
|
|
personas:
|
|
coder: ../facets/personas/coder.md
|
|
reviewer: ../facets/personas/architecture-reviewer.md
|
|
|
|
movements:
|
|
- name: implement
|
|
persona: coder # References the key in the section map
|
|
- name: review
|
|
persona: reviewer # References the key in the section map
|
|
```
|
|
|
|
You can also specify a persona file path directly:
|
|
|
|
```yaml
|
|
movements:
|
|
- name: review
|
|
persona: ~/.takt/personas/my-reviewer.md
|
|
```
|
|
|
|
If `persona` is a bare name and no section-map entry exists, TAKT checks `~/.takt/personas/<name>.md` as a fallback.
|
|
|
|
> **Note**: Personas do not need to output status markers manually. The engine auto-injects status routing rules into the generated instructions.
|
|
|
|
## Behavior Notes
|
|
|
|
`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 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
|