From 897b63da8eef737fdf0f95fcfea26b2bceb9be4b Mon Sep 17 00:00:00 2001
From: nrslib <38722970+nrslib@users.noreply.github.com>
Date: Fri, 30 Jan 2026 21:44:12 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20README=E3=83=BB=E3=82=AC=E3=82=A4?=
 =?UTF-8?q?=E3=83=89=E3=82=92=E7=8F=BE=E8=A1=8C=E3=82=A2=E3=83=BC=E3=82=AD?=
 =?UTF-8?q?=E3=83=86=E3=82=AF=E3=83=81=E3=83=A3=E3=81=AB=E5=90=88=E3=82=8F?=
 =?UTF-8?q?=E3=81=9B=E3=81=A6=E5=85=A8=E9=9D=A2=E4=BF=AE=E6=AD=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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リリースノート追加
---
 CHANGELOG.md      | 165 ++++++++++++++++++++++++
 README.md         |  49 +++----
 docs/README.ja.md |  57 ++++++--
 docs/agents.md    | 139 +++++++++-----------
 docs/workflows.md | 322 +++++++++++++++++++++++++++-------------------
 5 files changed, 484 insertions(+), 248 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e69de29..c84ed8f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
\ No newline at end of file
diff --git a/README.md b/README.md
index 4394d0e..f0a5fd4 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ TAKT is built with TAKT (dogfooding).
 ## Requirements
 
 - [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.
 
@@ -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. |
 | `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. |
 | `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. |
 | `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. |
-| `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, 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` | Sequential review with domain experts: Architecture, Frontend, Security, QA reviews with fix loops. |
+| `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. |
 
 Switch between workflows with `takt /switch`.
 
 ## Built-in Agents
 
-- **coder** - Implements features and fixes bugs
-- **architect** - Reviews architecture and code quality, verifies spec compliance
-- **supervisor** - Final verification, validation, and approval
-- **planner** - Task analysis, spec investigation, and implementation planning
-- **ai-reviewer** - AI-generated code quality review
-- **security** - Security vulnerability assessment
+| 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 |
 
 ## Custom Agents
 
@@ -239,30 +242,15 @@ You are a code reviewer focused on security.
 
 ## 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):
-- `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
+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.
 
-**Full model names** (recommended for production):
-- `claude-opus-4-5-20251101`
-- `claude-sonnet-4-5-20250929`
-- `claude-haiku-4-5-20250101`
+### Codex
 
-### Codex 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
+The model string is passed to the Codex SDK. Defaults to `codex` if not specified. See Codex documentation for available models.
 
 ## Project Structure
 
@@ -485,7 +473,8 @@ Available variables in `instruction_template`:
 | `{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 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
 
diff --git a/docs/README.ja.md b/docs/README.ja.md
index f04bb38..7ec837d 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -7,6 +7,7 @@
 ## 必要条件
 
 - [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の両方をプロバイダーとしてサポートしています。セットアップ時にプロバイダーを選択できます。
 
@@ -76,7 +77,7 @@ Select workflow:
 |------------|------------|
 | `default` | 本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。 |
 | `simple` | README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。 |
-| `expert-review` / `expert-cqrs` | Web開発プロジェクト。マルチエキスパートレビュー（CQRS、フロントエンド、セキュリティ、QA）。 |
+| `expert` / `expert-cqrs` | Web開発プロジェクト。修正ループ付き逐次マルチエキスパートレビュー（`expert`: アーキテクチャ、フロントエンド、セキュリティ、QA。`expert-cqrs`: CQRS+ES、フロントエンド、セキュリティ、QA）。 |
 | `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 |
 | `magi` | 審議システム。3つのAIペルソナが分析・投票（エヴァンゲリオン風）。 |
 
@@ -192,20 +193,34 @@ TAKTには複数のビルトインワークフローが同梱されています:
 | `default` | フル開発ワークフロー: 計画 → 実装 → AIレビュー → 並列レビュー（アーキテクト＋セキュリティ）→ スーパーバイザー承認。各レビュー段階に修正ループあり。 |
 | `simple` | defaultの簡略版: 計画 → 実装 → アーキテクトレビュー → AIレビュー → スーパーバイザー。中間の修正ステップなし。 |
 | `research` | リサーチワークフロー: プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。 |
-| `expert-review` | ドメインエキスパートによる包括的レビュー: CQRS+ES、フロントエンド、AI、セキュリティ、QAレビューと修正ループ。 |
-| `expert-cqrs` | CQRS+ES、フロントエンド、AI、セキュリティ、QA専門のエキスパートレビュー。計画 → 実装 → マルチエキスパートレビュー → スーパーバイザー。 |
+| `expert` | ドメインエキスパートによる逐次レビュー: アーキテクチャ、フロントエンド、セキュリティ、QAレビューと修正ループ。 |
+| `expert-cqrs` | ドメインエキスパートによる逐次レビュー: CQRS+ES、フロントエンド、セキュリティ、QAレビューと修正ループ。 |
 | `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 |
 
 `takt /switch` でワークフローを切り替えられます。
 
 ## ビルトインエージェント
 
-- **coder** - 機能を実装しバグを修正
-- **architect** - アーキテクチャとコード品質をレビュー、仕様準拠を検証
-- **supervisor** - 最終検証、バリデーション、承認
-- **planner** - タスク分析、仕様調査、実装計画
-- **ai-reviewer** - AI生成コードの品質レビュー
-- **security** - セキュリティ脆弱性の評価
+| エージェント | 説明 |
+|------------|------|
+| **planner** | タスク分析、仕様調査、実装計画 |
+| **coder** | 機能の実装、バグ修正 |
+| **ai-antipattern-reviewer** | AI特有のアンチパターンレビュー（存在しないAPI、誤った仮定、スコープクリープ） |
+| **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/` のユーザーファイルが優先されます。
 
+### グローバル設定
+
+デフォルトのプロバイダーとモデルを `~/.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}` | ステップごとのイテレーション数（このステップが実行された回数） |
 | `{previous_response}` | 前のステップの出力（テンプレートになければ自動注入） |
 | `{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}`） |
 
 ### ワークフローの設計
 
diff --git a/docs/agents.md b/docs/agents.md
index 2c332ca..09392a0 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -4,27 +4,27 @@ This guide explains how to configure and create custom agents in TAKT.
 
 ## 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 |
-|-------|-------|---------|
-| `coder` | Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch | Implements features and fixes bugs |
-| `architect` | Read, Glob, Grep, WebSearch, WebFetch | Reviews code and provides feedback |
-| `supervisor` | Read, Glob, Grep, Bash, WebSearch, WebFetch | Final verification and approval |
+| 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 can be specified by:
+In workflow YAML, agents are specified by file path:
 
 ```yaml
-# Built-in agent name
-agent: coder
+# Relative to workflow file directory
+agent: ../agents/default/coder.md
 
-# Path to prompt file
-agent: ~/.takt/agents/my-agent.md
-
-# Project-local agent
-agent: ./.takt/agents/reviewer.md
+# Home directory
+agent: ~/.takt/agents/default/coder.md
 
 # Absolute path
 agent: /path/to/custom/agent.md
@@ -50,25 +50,9 @@ You are a security-focused code reviewer.
 - Focus on OWASP Top 10 issues
 - Check for SQL injection, XSS, CSRF
 - 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
-
-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
+> **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
 
@@ -76,77 +60,78 @@ For more control, define agents in `.takt/agents.yaml`:
 
 ```yaml
 agents:
-  - name: security-reviewer
-    prompt_file: .takt/prompts/security-reviewer.md
+  - name: my-reviewer
+    prompt_file: .takt/prompts/reviewer.md
     allowed_tools:
       - Read
       - Glob
       - Grep
-    status_patterns:
-      approved: "\\[SECURITY:APPROVE\\]"
-      rejected: "\\[SECURITY:REJECT\\]"
+    provider: claude             # Optional: claude or codex
+    model: opus                  # Optional: model alias or full name
 ```
 
-### Tool Permissions
+### Agent Configuration Options
 
-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
+| 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. **Explicit output format** - Define exact status markers
-3. **Minimal tools** - Grant only necessary permissions
-4. **Focused scope** - One agent, one responsibility
-5. **Examples** - Include examples of expected behavior
+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
 
 ```yaml
 # .takt/agents.yaml
 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
     prompt_file: .takt/prompts/performance.md
     allowed_tools: [Read, Glob, Grep, Bash]
-    status_patterns:
-      approved: "\\[PERF:OK\\]"
-      rejected: "\\[PERF:FAIL\\]"
 ```
 
 ```yaml
 # workflow.yaml
 steps:
   - 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
-    agent: security-reviewer
-    transitions:
-      - condition: approved
-        next_step: performance-review
-      - condition: rejected
-        next_step: implement
-
-  - name: performance-review
+  - name: review
     agent: performance-reviewer
-    transitions:
-      - condition: approved
-        next_step: COMPLETE
-      - condition: rejected
-        next_step: implement
+    edit: false
+    rules:
+      - condition: Approved
+        next: COMPLETE
+      - condition: Needs fix
+        next: implement
+    instruction_template: |
+      Review the implementation for performance issues.
 ```
diff --git a/docs/workflows.md b/docs/workflows.md
index 72066b5..335e3b5 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -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:
 - Which agent to use
 - What instructions to give
-- How to transition to the next step
+- Rules for routing to the next step
 
 ## File Locations
 
-Workflows can be placed in:
-- `~/.takt/workflows/` - Global workflows (available in all projects)
-- `.takt/workflows/` - Project-specific workflows
+- Builtin workflows are embedded in the npm package (`dist/resources/`)
+- `~/.takt/workflows/` — User workflows (override builtins with the same name)
+- Use `takt /eject <workflow>` to copy a builtin to `~/.takt/workflows/` for customization
 
 ## Workflow Schema
 
@@ -25,79 +25,161 @@ initial_step: first-step  # Optional, defaults to first step
 
 steps:
   - name: step-name
-    agent: coder           # Built-in agent or path to .md file
-    allowed_tools:         # Optional tool allowlist for this step
-      - Read
-      - Grep
-    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:
+    agent: ../agents/default/coder.md  # Path to agent prompt file
+    agent_name: coder                  # Display name (optional)
+    edit: true                         # Whether the step can edit files
+    allowed_tools:                     # Optional tool allowlist
       - Read
       - Glob
       - Grep
       - Edit
       - Write
       - Bash
-      - WebSearch
-      - WebFetch
+    rules:
+      - condition: "Implementation complete"
+        next: next-step
+      - condition: "Cannot proceed"
+        next: ABORT
     instruction_template: |
-      {task}
-    transitions:
-      - condition: done
-        next_step: COMPLETE
-      - condition: blocked
-        next_step: ABORT
+      Your instructions here with {variables}
+```
+
+## Available Variables
+
+| 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
@@ -108,42 +190,29 @@ max_iterations: 10
 
 steps:
   - name: implement
-    agent: coder
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
+    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: review
+      - condition: Cannot proceed
+        next: ABORT
     instruction_template: |
-      {task}
-    transitions:
-      - condition: done
-        next_step: review
-      - condition: blocked
-        next_step: ABORT
+      Implement the requested changes.
 
   - name: review
-    agent: architect
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
+    agent: ../agents/default/architecture-reviewer.md
+    edit: false
+    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
+    rules:
+      - condition: Approved
+        next: COMPLETE
+      - condition: Needs fix
+        next: implement
     instruction_template: |
-      Review the implementation for:
-      - Code quality
-      - Best practices
-      - Potential issues
-    transitions:
-      - condition: approved
-        next_step: COMPLETE
-      - condition: rejected
-        next_step: implement
+      Review the implementation for code quality and best practices.
 ```
 
 ### Passing Data Between Steps
@@ -151,42 +220,33 @@ steps:
 ```yaml
 steps:
   - name: analyze
-    agent: architect
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - WebSearch
-      - WebFetch
+    agent: ../agents/default/planner.md
+    edit: false
+    allowed_tools: [Read, Glob, Grep, WebSearch, WebFetch]
+    rules:
+      - condition: Analysis complete
+        next: implement
     instruction_template: |
-      Analyze this request and create a plan: {task}
-    transitions:
-      - condition: done
-        next_step: implement
+      Analyze this request and create a plan.
 
   - name: implement
-    agent: coder
-    pass_previous_response: true  # Enable {previous_response}
-    allowed_tools:
-      - Read
-      - Glob
-      - Grep
-      - Edit
-      - Write
-      - Bash
-      - WebSearch
-      - WebFetch
+    agent: ../agents/default/coder.md
+    edit: true
+    pass_previous_response: true
+    permission_mode: acceptEdits
+    allowed_tools: [Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch]
+    rules:
+      - condition: Implementation complete
+        next: COMPLETE
     instruction_template: |
       Implement based on this analysis:
       {previous_response}
-    transitions:
-      - condition: done
-        next_step: COMPLETE
 ```
 
 ## Best Practices
 
-1. **Keep iterations reasonable** - 5-15 is typical
-2. **Always handle blocked state** - Provide an escape path
-3. **Use descriptive step names** - Makes logs easier to read
-4. **Test workflows incrementally** - Start simple, add complexity
+1. **Keep iterations reasonable** — 10-30 is typical for development workflows
+2. **Use `edit: false` for review steps** — Prevent reviewers from modifying code
+3. **Use descriptive step names** — Makes logs easier to read
+4. **Test workflows incrementally** — Start simple, add complexity
+5. **Use `/eject` to customize** — Copy a builtin as starting point rather than writing from scratch