agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: README・ガイドを現行アーキテクチャに合わせて全面修正

Browse Source 
- expert-review → expert（実ファイル名に合わせる）
- ビルトインエージェント名を実ファイル名に統一
- Model Selectionをプロバイダー透過型に修正
- {report_dir}の例を.takt/reports/プレフィックス付きに更新
- {report:filename}テンプレート変数を追加
- gh CLIを#N用の条件付き要件として記載
- 日本語READMEにモデル選択・グローバル設定セクション追加
- docs/workflows.md: rules形式・パラレルステップに全面書き直し
- docs/agents.md: ルールベース自動注入・6エージェント構成に全面書き直し
- CHANGELOG.md: v0.3.0リリースノート追加
This commit is contained in:
nrslib 2026-01-30 21:44:12 +09:00
parent 01c182c3dc
commit 897b63da8e
5 changed files with 484 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
CHANGELOG.md
View File

@ -0,0 +1,165 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [0.3.0] - 2026-01-30
### Added
- Rule-based workflow transitions with 5-stage fallback evaluation (#30)
- Tag-based conditions: agent outputs `[STEP:N]` tags matched by index
- `ai()` conditions: AI evaluates free-text conditions against agent output (#9)
- `all()`/`any()` aggregate conditions for parallel step results (#20)
- 5-stage evaluation order: aggregate → Phase 3 tag → Phase 1 tag → AI judge → AI fallback
- 3-phase step execution model (#33)
- Phase 1: Main work (coding, review, etc.)
- Phase 2: Report output (when `step.report` defined)
- Phase 3: Status judgment (when tag-based rules exist)
- Session resumed across phases for context continuity
- Parallel step execution with concurrent sub-steps via `Promise.all()` (#20)
- GitHub Issue integration: execute/add tasks by issue number, e.g. `takt #6` (#10, #34)
- NDJSON session logging with real-time streaming writes (#27, #36)
- Builtin resources embedded in npm package with `/eject` command for customization (#4, #40)
- `edit` property for per-step file edit control
- Rule match method visualization and logging
- Report output auto-generation from YAML `report.format`
- Parallel review support in builtin workflows with spec compliance checking (#31)
- WorkflowEngine mock integration tests (#17, #41)
### Changed
- Report format unified to auto-generation; manual `order`/`instruction_template` for reports removed
- `gitdiff` report type removed in favor of format-based reports
### Fixed
- Report directory correctly includes `.takt/reports/` prefix (#37, #42)
- Unused import in eject.ts (#43)
## [0.2.3] - 2026-01-29
### Added
- `/list-tasks` command for branch management (try merge, merge & cleanup, delete)
### Changed
- Isolated execution migrated from `git worktree` to `git clone --shared` to prevent Claude Code SDK from traversing back to main repository
- Clone lifecycle: auto-deletion after task completion removed; use `/list-tasks` for cleanup
- `worktree.ts` split into `clone.ts` + `branchReview.ts`
- Origin remote removed from clones to block SDK traversal
- All workflow report steps granted Write permission
- `git clone --shared` changed to `--reference --dissociate`
### Fixed
- Version read from `package.json` instead of hardcoded `0.1.0` (#3)
## [0.2.2] - 2026-01-29
### Added
- `/review` instruct action for executing instructions on task branches
- AI-powered task name summarization to English slugs for branch names
- Worktree session inheritance
- Execution Rules metadata (git commit prohibition, cd prohibition)
### Changed
- Status output rule headers auto-generated
- Instructions auto-include worktree change context
- Try Merge changed to squash merge
- `expert-review` renamed to `expert-cqrs`; common reviewers consolidated under `expert/`
### Fixed
- Tasks incorrectly progressing to `completed` on abnormal termination
## [0.2.1] - 2026-01-28
### Added
- Language setting (`ja`/`en`)
- Multiline input support for `/add-task`
- `/review-tasks` command
- Cursor-based (arrow key) menu selection replacing numeric input
- `answer` status, `autoCommit`, `permission_mode`, verbose logging options
### Fixed
- Multiple worktree-related bugs (directory resolution, session handling, creation flow)
- ESC key cancels workflow/task selection
## [0.2.0] - 2026-01-27
### Added
- `/watch` command for file system polling and auto-executing tasks from `.takt/tasks/`
- `/refresh-builtin` command for updating builtin resources
- `/add-task` command for interactive task creation
- Enhanced default workflows
## [0.1.7] - 2026-01-27
### Added
- Schema permission support for workflow validation
## [0.1.6] - 2026-01-27
### Added
- Mock execution mode for testing
### Changed
- `-r` option omitted; default changed to conversation continuation mode
## [0.1.5] - 2026-01-27
### Added
- Total execution time output
### Fixed
- Workflow unintentionally stopping during execution
## [0.1.4] - 2026-01-27
### Changed
- Workflow prompts strengthened
- Transition prompts consolidated into workflow definitions
## [0.1.3] - 2026-01-26
### Fixed
- Iteration stalling issue
## [0.1.2] - 2026-01-26
### Added
- Codex provider support
- Model selection per step/agent
- Permission mode configuration
- Worktree support for isolated task execution
- Project `.gitignore` initialization
### Changed
- Agent prompts refined
## [0.1.1] - 2026-01-25
### Added
- GitHub Actions workflow for npm publish
### Changed
- Interactive mode removed; CLI simplified

49
README.md
View File

@ -11,6 +11,7 @@ TAKT is built with TAKT (dogfooding).
## Requirements ## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or Codex must be installed and configured - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or Codex must be installed and configured
- [GitHub CLI](https://cli.github.com/) (`gh`) — required only for `takt "#N"` (GitHub Issue execution)
TAKT supports both Claude Code and Codex as providers; you can choose the provider during setup. TAKT supports both Claude Code and Codex as providers; you can choose the provider during setup.
@ -80,7 +81,7 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
|----------|----------| |----------|----------|
| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. | | `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
| `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. | | `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. |
| `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). | | `expert` / `expert-cqrs` | Web development projects. Sequential multi-expert review with fix loops (`expert`: Architecture, Frontend, Security, QA; `expert-cqrs`: CQRS+ES, Frontend, Security, QA). |
| `research` | Research and investigation. Autonomous research without asking questions. | | `research` | Research and investigation. Autonomous research without asking questions. |
| `magi` | Fun deliberation. Three AI personas analyze and vote (Evangelion-inspired). | | `magi` | Fun deliberation. Three AI personas analyze and vote (Evangelion-inspired). |
@ -196,20 +197,22 @@ TAKT ships with several built-in workflows:
| `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. | | `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. |
| `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. | | `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. |
| `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. | | `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. |
| `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops. | | `expert` | Sequential review with domain experts: Architecture, Frontend, Security, QA reviews with fix loops. |
| `expert-cqrs` | Expert review focused on CQRS+ES, Frontend, AI, Security, and QA. Plan → implement → multi-expert review → supervise. | | `expert-cqrs` | Sequential review with domain experts: CQRS+ES, Frontend, Security, QA reviews with fix loops. |
| `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. | | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
Switch between workflows with `takt /switch`. Switch between workflows with `takt /switch`.
## Built-in Agents ## Built-in Agents
- **coder** - Implements features and fixes bugs | Agent | Description |
- **architect** - Reviews architecture and code quality, verifies spec compliance |-------|-------------|
- **supervisor** - Final verification, validation, and approval | **planner** | Task analysis, spec investigation, and implementation planning |
- **planner** - Task analysis, spec investigation, and implementation planning | **coder** | Implements features and fixes bugs |
- **ai-reviewer** - AI-generated code quality review | **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) |
- **security** - Security vulnerability assessment | **architecture-reviewer** | Reviews architecture and code quality, verifies spec compliance |
| **security-reviewer** | Security vulnerability assessment |
| **supervisor** | Final verification, validation, and approval |
## Custom Agents ## Custom Agents
@ -239,30 +242,15 @@ You are a code reviewer focused on security.
## Model Selection ## Model Selection
### Claude Models The `model` field in workflow steps, agent configs, and global config is passed directly to the provider (Claude Code CLI or Codex SDK). TAKT does not resolve model aliases — the provider handles that.
You can specify models using either **aliases** or **full model names**: ### Claude Code
**Aliases** (recommended for simplicity): Claude Code supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). See [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models.
- `opus` - Claude Opus 4.5 (highest reasoning capability)
- `sonnet` - Claude Sonnet 4.5 (balanced, best for most tasks)
- `haiku` - Claude Haiku 4.5 (fast and efficient)
- `opusplan` - Opus for planning, Sonnet for execution
- `default` - Recommended model for your account type
**Full model names** (recommended for production): ### Codex
- `claude-opus-4-5-20251101`
- `claude-sonnet-4-5-20250929`
- `claude-haiku-4-5-20250101`
### Codex Models The model string is passed to the Codex SDK. Defaults to `codex` if not specified. See Codex documentation for available models.
Available Codex models:
- `gpt-5.2-codex` - Latest agentic coding model (default)
- `gpt-5.1-codex` - Previous generation
- `gpt-5.1-codex-max` - Optimized for long-running tasks
- `gpt-5.1-codex-mini` - Smaller, cost-effective version
- `codex-1` - Specialized model aligned with coding preferences
## Project Structure ## Project Structure
@ -485,7 +473,8 @@ Available variables in `instruction_template`:
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) | | `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
| `{previous_response}` | Previous step's output (auto-injected if not in template) | | `{previous_response}` | Previous step's output (auto-injected if not in template) |
| `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) | | `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
| `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) | | `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) |
| `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) |
### Designing Workflows ### Designing Workflows

57
docs/README.ja.md
View File

@ -7,6 +7,7 @@
## 必要条件 ## 必要条件
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) または Codex がインストール・設定済みであること - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) または Codex がインストール・設定済みであること
- [GitHub CLI](https://cli.github.com/) (`gh`) — `takt "#N"`（GitHub Issue実行）を使う場合のみ必要
TAKTはClaude CodeとCodexの両方をプロバイダーとしてサポートしています。セットアップ時にプロバイダーを選択できます。 TAKTはClaude CodeとCodexの両方をプロバイダーとしてサポートしています。セットアップ時にプロバイダーを選択できます。
@ -76,7 +77,7 @@ Select workflow:
|------------|------------| |------------|------------|
| `default` | 本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。 | | `default` | 本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。 |
| `simple` | README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。 | | `simple` | README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。 |
| `expert-review` / `expert-cqrs` | Web開発プロジェクト。マルチエキスパートレビュー（CQRS、フロントエンド、セキュリティ、QA）。 | | `expert` / `expert-cqrs` | Web開発プロジェクト。修正ループ付き逐次マルチエキスパートレビュー（`expert`: アーキテクチャ、フロントエンド、セキュリティ、QA。`expert-cqrs`: CQRS+ES、フロントエンド、セキュリティ、QA）。 |
| `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 | | `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 |
| `magi` | 審議システム。3つのAIペルソナが分析・投票（エヴァンゲリオン風）。 | | `magi` | 審議システム。3つのAIペルソナが分析・投票（エヴァンゲリオン風）。 |
@ -192,20 +193,34 @@ TAKTには複数のビルトインワークフローが同梱されています:
| `default` | フル開発ワークフロー: 計画 → 実装 → AIレビュー → 並列レビュー（アーキテクト＋セキュリティ）→ スーパーバイザー承認。各レビュー段階に修正ループあり。 | | `default` | フル開発ワークフロー: 計画 → 実装 → AIレビュー → 並列レビュー（アーキテクト＋セキュリティ）→ スーパーバイザー承認。各レビュー段階に修正ループあり。 |
| `simple` | defaultの簡略版: 計画 → 実装 → アーキテクトレビュー → AIレビュー → スーパーバイザー。中間の修正ステップなし。 | | `simple` | defaultの簡略版: 計画 → 実装 → アーキテクトレビュー → AIレビュー → スーパーバイザー。中間の修正ステップなし。 |
| `research` | リサーチワークフロー: プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。 | | `research` | リサーチワークフロー: プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。 |
| `expert-review` | ドメインエキスパートによる包括的レビュー: CQRS+ES、フロントエンド、AI、セキュリティ、QAレビューと修正ループ。 | | `expert` | ドメインエキスパートによる逐次レビュー: アーキテクチャ、フロントエンド、セキュリティ、QAレビューと修正ループ。 |
| `expert-cqrs` | CQRS+ES、フロントエンド、AI、セキュリティ、QA専門のエキスパートレビュー。計画 → 実装 → マルチエキスパートレビュー → スーパーバイザー。 | | `expert-cqrs` | ドメインエキスパートによる逐次レビュー: CQRS+ES、フロントエンド、セキュリティ、QAレビューと修正ループ。 |
| `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 | | `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 |
`takt /switch` でワークフローを切り替えられます。 `takt /switch` でワークフローを切り替えられます。
## ビルトインエージェント ## ビルトインエージェント
- **coder** - 機能を実装しバグを修正 | エージェント | 説明 |
- **architect** - アーキテクチャとコード品質をレビュー、仕様準拠を検証 |------------|------|
- **supervisor** - 最終検証、バリデーション、承認 | **planner** | タスク分析、仕様調査、実装計画 |
- **planner** - タスク分析、仕様調査、実装計画 | **coder** | 機能の実装、バグ修正 |
- **ai-reviewer** - AI生成コードの品質レビュー | **ai-antipattern-reviewer** | AI特有のアンチパターンレビュー（存在しないAPI、誤った仮定、スコープクリープ） |
- **security** - セキュリティ脆弱性の評価 | **architecture-reviewer** | アーキテクチャとコード品質のレビュー、仕様準拠の検証 |
| **security-reviewer** | セキュリティ脆弱性の評価 |
| **supervisor** | 最終検証、バリデーション、承認 |
## モデル選択
`model` フィールド（ワークフローステップ、エージェント設定、グローバル設定）はプロバイダー（Claude Code CLI / Codex SDK）にそのまま渡されます。TAKTはモデルエイリアスの解決を行いません。
### Claude Code
Claude Code はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`default`）およびフルモデル名（例: `claude-sonnet-4-5-20250929`）をサポートしています。利用可能なモデルは [Claude Code ドキュメント](https://docs.anthropic.com/en/docs/claude-code)を参照してください。
### Codex
モデル文字列はCodex SDKに渡されます。未指定の場合は `codex` がデフォルトです。利用可能なモデルはCodexのドキュメントを参照してください。
## カスタムエージェント ## カスタムエージェント
@ -254,6 +269,27 @@ agents:
ビルトインリソースはnpmパッケージ（`dist/resources/`）に埋め込まれています。`~/.takt/` のユーザーファイルが優先されます。 ビルトインリソースはnpmパッケージ（`dist/resources/`）に埋め込まれています。`~/.takt/` のユーザーファイルが優先されます。
### グローバル設定
デフォルトのプロバイダーとモデルを `~/.takt/config.yaml` で設定:
```yaml
# ~/.takt/config.yaml
language: ja
default_workflow: default
log_level: info
provider: claude # デフォルトプロバイダー: claude または codex
model: sonnet # デフォルトモデル（オプション）
trusted_directories:
- /path/to/trusted/dir
```
**モデル解決の優先順位:**
1. ワークフローステップの `model`（最優先）
2. カスタムエージェントの `model`
3. グローバル設定の `model`
4. プロバイダーデフォルト（Claude: sonnet、Codex: codex）
## 実践的な使い方ガイド ## 実践的な使い方ガイド
### タスク管理 ### タスク管理
@ -423,7 +459,8 @@ agent: /path/to/custom/agent.md
| `{step_iteration}` | ステップごとのイテレーション数（このステップが実行された回数） | | `{step_iteration}` | ステップごとのイテレーション数（このステップが実行された回数） |
| `{previous_response}` | 前のステップの出力（テンプレートになければ自動注入） | | `{previous_response}` | 前のステップの出力（テンプレートになければ自動注入） |
| `{user_inputs}` | ワークフロー中の追加ユーザー入力（テンプレートになければ自動注入） | | `{user_inputs}` | ワークフロー中の追加ユーザー入力（テンプレートになければ自動注入） |
| `{report_dir}` | レポートディレクトリ名（例: `20250126-143052-task-summary`） | | `{report_dir}` | レポートディレクトリパス（例: `.takt/reports/20250126-143052-task-summary`） |
| `{report:filename}` | `{report_dir}/filename` に展開（例: `{report:00-plan.md}`） |
### ワークフローの設計 ### ワークフローの設計

139
docs/agents.md
View File

@ -4,27 +4,27 @@ This guide explains how to configure and create custom agents in TAKT.
## Built-in Agents ## Built-in Agents
TAKT includes three built-in agents: TAKT includes six built-in agents (located in `resources/global/{lang}/agents/default/`):
| Agent | Tools | Purpose | | Agent | Description |
|-------|-------|---------| |-------|-------------|
| `coder` | Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch | Implements features and fixes bugs | | **planner** | Task analysis, spec investigation, and implementation planning |
| `architect` | Read, Glob, Grep, WebSearch, WebFetch | Reviews code and provides feedback | | **coder** | Implements features and fixes bugs |
| `supervisor` | Read, Glob, Grep, Bash, WebSearch, WebFetch | Final verification and approval | | **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 ## Specifying Agents
In workflow YAML, agents can be specified by: In workflow YAML, agents are specified by file path:
```yaml ```yaml
# Built-in agent name # Relative to workflow file directory
agent: coder agent: ../agents/default/coder.md
# Path to prompt file # Home directory
agent: ~/.takt/agents/my-agent.md agent: ~/.takt/agents/default/coder.md
# Project-local agent
agent: ./.takt/agents/reviewer.md
# Absolute path # Absolute path
agent: /path/to/custom/agent.md agent: /path/to/custom/agent.md
@ -50,25 +50,9 @@ You are a security-focused code reviewer.
- Focus on OWASP Top 10 issues - Focus on OWASP Top 10 issues
- Check for SQL injection, XSS, CSRF - Check for SQL injection, XSS, CSRF
- Verify proper error handling - Verify proper error handling
## Output Format
Output one of these status markers:
- [REVIEWER:APPROVE] if code is secure
- [REVIEWER:REJECT] if issues found
``` ```
### Status Markers > **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.
Agents must output status markers for workflow transitions:
| Status | Example Pattern |
|--------|----------------|
| done | `[AGENT:DONE]` |
| blocked | `[AGENT:BLOCKED]` |
| approved | `[AGENT:APPROVED]`, `[AGENT:APPROVE]` |
| rejected | `[AGENT:REJECTED]`, `[AGENT:REJECT]` |
## Advanced Configuration
### Using agents.yaml ### Using agents.yaml
@ -76,77 +60,78 @@ For more control, define agents in `.takt/agents.yaml`:
```yaml ```yaml
agents: agents:
- name: security-reviewer - name: my-reviewer
prompt_file: .takt/prompts/security-reviewer.md prompt_file: .takt/prompts/reviewer.md
allowed_tools: allowed_tools:
- Read - Read
- Glob - Glob
- Grep - Grep
status_patterns: provider: claude # Optional: claude or codex
approved: "\\[SECURITY:APPROVE\\]" model: opus # Optional: model alias or full name
rejected: "\\[SECURITY:REJECT\\]"
``` ```
### Tool Permissions ### Agent Configuration Options
Available tools: | Field | Description |
- `Read` - Read files |-------|-------------|
- `Glob` - Find files by pattern | `name` | Agent identifier (referenced in workflow steps) |
- `Grep` - Search file contents | `prompt_file` | Path to Markdown prompt file |
- `Edit` - Modify files | `prompt` | Inline prompt text (alternative to `prompt_file`) |
- `Write` - Create/overwrite files | `allowed_tools` | List of tools the agent can use |
- `Bash` - Execute commands | `claude_agent` | Claude Code agent name (for Claude Code native agents) |
- `WebSearch` - Search the web | `claude_skill` | Claude Code skill name (for Claude Code native skills) |
- `WebFetch` - Fetch web content | `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 ## Best Practices
1. **Clear role definition** - State what the agent does and doesn't do 1. **Clear role definition** — State what the agent does and doesn't do
2. **Explicit output format** - Define exact status markers 2. **Minimal tools** — Grant only necessary permissions
3. **Minimal tools** - Grant only necessary permissions 3. **Use `edit: false`** — Review agents should not modify files
4. **Focused scope** - One agent, one responsibility 4. **Focused scope** — One agent, one responsibility
5. **Examples** - Include examples of expected behavior 5. **Customize via `/eject`** — Copy builtin agents to `~/.takt/` for modification rather than writing from scratch
## Example: Multi-Reviewer Setup ## Example: Multi-Reviewer Setup
```yaml ```yaml
# .takt/agents.yaml # .takt/agents.yaml
agents: agents:
- name: security-reviewer
prompt_file: .takt/prompts/security.md
allowed_tools: [Read, Glob, Grep]
status_patterns:
approved: "\\[SEC:OK\\]"
rejected: "\\[SEC:FAIL\\]"
- name: performance-reviewer - name: performance-reviewer
prompt_file: .takt/prompts/performance.md prompt_file: .takt/prompts/performance.md
allowed_tools: [Read, Glob, Grep, Bash] allowed_tools: [Read, Glob, Grep, Bash]
status_patterns:
approved: "\\[PERF:OK\\]"
rejected: "\\[PERF:FAIL\\]"
``` ```
```yaml ```yaml
# workflow.yaml # workflow.yaml
steps: steps:
- name: implement - name: implement
agent: coder agent: ../agents/default/coder.md
# ... edit: true
rules:
- condition: Implementation complete
next: review
- condition: Cannot proceed
next: ABORT
- name: security-review - name: review
agent: security-reviewer
transitions:
- condition: approved
next_step: performance-review
- condition: rejected
next_step: implement
- name: performance-review
agent: performance-reviewer agent: performance-reviewer
transitions: edit: false
- condition: approved rules:
next_step: COMPLETE - condition: Approved
- condition: rejected next: COMPLETE
next_step: implement - condition: Needs fix
next: implement
instruction_template: |
Review the implementation for performance issues.
``` ```

322
docs/workflows.md
View File

@ -7,13 +7,13 @@ This guide explains how to create and customize TAKT workflows.
A workflow is a YAML file that defines a sequence of steps executed by AI agents. Each step specifies: A workflow is a YAML file that defines a sequence of steps executed by AI agents. Each step specifies:
- Which agent to use - Which agent to use
- What instructions to give - What instructions to give
- How to transition to the next step - Rules for routing to the next step
## File Locations ## File Locations
Workflows can be placed in: - Builtin workflows are embedded in the npm package (`dist/resources/`)
- `~/.takt/workflows/` - Global workflows (available in all projects) - `~/.takt/workflows/` — User workflows (override builtins with the same name)
- `.takt/workflows/` - Project-specific workflows - Use `takt /eject <workflow>` to copy a builtin to `~/.takt/workflows/` for customization
## Workflow Schema ## Workflow Schema
@ -25,79 +25,161 @@ initial_step: first-step # Optional, defaults to first step
steps: steps:
- name: step-name - name: step-name
agent: coder # Built-in agent or path to .md file agent: ../agents/default/coder.md # Path to agent prompt file
allowed_tools: # Optional tool allowlist for this step agent_name: coder # Display name (optional)
- Read edit: true # Whether the step can edit files
- Grep allowed_tools: # Optional tool allowlist
instruction_template: |
Your instructions here with {variables}
transitions:
- condition: done
next_step: next-step
- condition: blocked
next_step: ABORT
on_no_status: complete # What to do if no status detected
```
## Available Variables
| Variable | Description |
|----------|-------------|
| `{task}` | Original user request |
| `{iteration}` | Current iteration number (1-based) |
| `{max_iterations}` | Maximum allowed iterations |
| `{previous_response}` | Previous step's output |
| `{user_inputs}` | Additional inputs during workflow |
## Transitions
### Conditions
Conditions match agent output patterns:
- `done` - Agent completed the task (`[CODER:DONE]`, etc.)
- `blocked` - Agent is blocked (`[CODER:BLOCKED]`)
- `approved` - Review passed (`[ARCHITECT:APPROVED]`)
- `rejected` - Review failed (`[ARCHITECT:REJECTED]`)
### Special Next Steps
- `COMPLETE` - End workflow successfully
- `ABORT` - End workflow with failure
### on_no_status Options
When no status pattern is detected:
- `complete` - Treat as workflow complete
- `continue` - Move to next step
- `stay` - Repeat current step
## Examples
### Simple Implementation Workflow
```yaml
name: simple
max_iterations: 5
steps:
- name: implement
agent: coder
allowed_tools:
- Read - Read
- Glob - Glob
- Grep - Grep
- Edit - Edit
- Write - Write
- Bash - Bash
- WebSearch rules:
- WebFetch - condition: "Implementation complete"
next: next-step
- condition: "Cannot proceed"
next: ABORT
instruction_template: | instruction_template: |
{task} Your instructions here with {variables}
transitions: ```
- condition: done
next_step: COMPLETE ## Available Variables
- condition: blocked
next_step: ABORT | Variable | Description |
|----------|-------------|
| `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Workflow-wide turn count (total steps executed) |
| `{max_iterations}` | Maximum iterations allowed |
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
| `{previous_response}` | Previous step's output (auto-injected if not in template) |
| `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
| `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) |
| `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) |
> **Note**: `{task}`, `{previous_response}`, and `{user_inputs}` are auto-injected into instructions. You only need explicit placeholders if you want to control their position in the template.
## Rules
Rules define how each step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output.
```yaml
rules:
- condition: "Implementation complete"
next: review
- condition: "Cannot proceed"
next: ABORT
appendix: |
Explain what is blocking progress.
```
### Rule Condition Types
| Type | Syntax | Description |
|------|--------|-------------|
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
| AI judge | `ai("condition text")` | AI evaluates the condition against agent output |
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results |
### Special `next` Values
- `COMPLETE` — End workflow successfully
- `ABORT` — End workflow with failure
### Rule Field: `appendix`
The optional `appendix` field provides a template for additional AI output when that rule is matched. Useful for structured error reporting or requesting specific information.
## Parallel Steps
Steps can execute sub-steps concurrently with aggregate evaluation:
```yaml
- name: reviewers
parallel:
- name: arch-review
agent: ../agents/default/architecture-reviewer.md
edit: false
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Review architecture and code quality.
- name: security-review
agent: ../agents/default/security-reviewer.md
edit: false
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Review for security vulnerabilities.
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
```
- `all("X")`: true if ALL sub-steps matched condition X
- `any("X")`: true if ANY sub-step matched condition X
- Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing)
## Report Files
Steps can generate report files in the report directory:
```yaml
# Single report file
report: 00-plan.md
# Single report with format specification
report:
name: 00-plan.md
format: |
```markdown
# Plan
...
```
# Multiple report files
report:
- Scope: 01-scope.md
- Decisions: 02-decisions.md
```
## Step Options
| Option | Default | Description |
|--------|---------|-------------|
| `edit` | - | Whether the step can edit project files (`true`/`false`) |
| `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` |
| `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
| `provider` | - | Override provider for this step (`claude` or `codex`) |
| `model` | - | Override model for this step |
| `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
| `report` | - | Report file configuration (name, format) for auto-generated reports |
## Examples
### Simple Implementation Workflow
```yaml
name: simple-impl
max_iterations: 5
steps:
- name: implement
agent: ../agents/default/coder.md
edit: true
permission_mode: acceptEdits
allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
rules:
- condition: Implementation complete
next: COMPLETE
- condition: Cannot proceed
next: ABORT
instruction_template: |
Implement the requested changes.
``` ```
### Implementation with Review ### Implementation with Review
@ -108,42 +190,29 @@ max_iterations: 10
steps: steps:
- name: implement - name: implement
agent: coder agent: ../agents/default/coder.md
allowed_tools: edit: true
- Read permission_mode: acceptEdits
- Glob allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
- Grep rules:
- Edit - condition: Implementation complete
- Write next: review
- Bash - condition: Cannot proceed
- WebSearch next: ABORT
- WebFetch
instruction_template: | instruction_template: |
{task} Implement the requested changes.
transitions:
- condition: done
next_step: review
- condition: blocked
next_step: ABORT
- name: review - name: review
agent: architect agent: ../agents/default/architecture-reviewer.md
allowed_tools: edit: false
- Read allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
- Glob rules:
- Grep - condition: Approved
- WebSearch next: COMPLETE
- WebFetch - condition: Needs fix
next: implement
instruction_template: | instruction_template: |
Review the implementation for: Review the implementation for code quality and best practices.
- Code quality
- Best practices
- Potential issues
transitions:
- condition: approved
next_step: COMPLETE
- condition: rejected
next_step: implement
``` ```
### Passing Data Between Steps ### Passing Data Between Steps
@ -151,42 +220,33 @@ steps:
```yaml ```yaml
steps: steps:
- name: analyze - name: analyze
agent: architect agent: ../agents/default/planner.md
allowed_tools: edit: false
- Read allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
- Glob rules:
- Grep - condition: Analysis complete
- WebSearch next: implement
- WebFetch
instruction_template: | instruction_template: |
Analyze this request and create a plan: {task} Analyze this request and create a plan.
transitions:
- condition: done
next_step: implement
- name: implement - name: implement
agent: coder agent: ../agents/default/coder.md
pass_previous_response: true # Enable {previous_response} edit: true
allowed_tools: pass_previous_response: true
- Read permission_mode: acceptEdits
- Glob allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
- Grep rules:
- Edit - condition: Implementation complete
- Write next: COMPLETE
- Bash
- WebSearch
- WebFetch
instruction_template: | instruction_template: |
Implement based on this analysis: Implement based on this analysis:
{previous_response} {previous_response}
transitions:
- condition: done
next_step: COMPLETE
``` ```
## Best Practices ## Best Practices
1. **Keep iterations reasonable** - 5-15 is typical 1. **Keep iterations reasonable** — 10-30 is typical for development workflows
2. **Always handle blocked state** - Provide an escape path 2. **Use `edit: false` for review steps** — Prevent reviewers from modifying code
3. **Use descriptive step names** - Makes logs easier to read 3. **Use descriptive step names** — Makes logs easier to read
4. **Test workflows incrementally** - Start simple, add complexity 4. **Test workflows incrementally** — Start simple, add complexity
5. **Use `/eject` to customize** — Copy a builtin as starting point rather than writing from scratch