takt/docs/agents.md

Agent Guide

This guide explains how to configure and create custom agents in TAKT.

Built-in Agents

TAKT includes six built-in agents (located in resources/global/{lang}/agents/default/):

Agent	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

Specifying Agents

In workflow YAML, agents are specified by file path:

# Relative to workflow file directory
agent: ../agents/default/coder.md

# Home directory
agent: ~/.takt/agents/default/coder.md

# Absolute path
agent: /path/to/custom/agent.md

Creating Custom Agents

Agent Prompt File

Create a Markdown file with your agent's instructions:

# 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

: Agents do NOT need to output status markers manually. The workflow engine auto-injects status output rules into agent instructions based on the step'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:

agents:
  - name: my-reviewer
    prompt_file: .takt/prompts/reviewer.md
    allowed_tools:
      - Read
      - Glob
      - Grep
    provider: claude             # Optional: claude or codex
    model: opus                  # Optional: model alias or full name

Agent Configuration Options

Field	Description
name	Agent identifier (referenced in workflow steps)
prompt_file	Path to Markdown prompt file
prompt	Inline prompt text (alternative to prompt_file)
allowed_tools	List of tools the agent can use
claude_agent	Claude Code agent name (for Claude Code native agents)
claude_skill	Claude Code skill name (for Claude Code native skills)
provider	Provider override: claude or codex
model	Model override (alias or full name)

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
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 agents to ~/.takt/ for modification rather than writing from scratch

Example: Multi-Reviewer Setup

# .takt/agents.yaml
agents:
  - name: performance-reviewer
    prompt_file: .takt/prompts/performance.md
    allowed_tools: [Read, Glob, Grep, Bash]

# workflow.yaml
steps:
  - name: implement
    agent: ../agents/default/coder.md
    edit: true
    rules:
      - condition: Implementation complete
        next: review
      - condition: Cannot proceed
        next: ABORT

  - name: review
    agent: performance-reviewer
    edit: false
    rules:
      - condition: Approved
        next: COMPLETE
      - condition: Needs fix
        next: implement
    instruction_template: |
      Review the implementation for performance issues.