README を大幅改訂し、詳細情報を docs/ に分離

README を約950行から約270行に圧縮し、詳細は個別ドキュメントに分離した。
コンセプトを実態に合わせて再定義（4軸: すぐ始められる・実用的・再現可能・マルチエージェント）し、
基本ユースケースを takt → takt run のフローに修正した。
英語版・日本語版の両方を対応し、日本語版はネイティブ日本語で記述。

docs/builtin-catalog.ja.md

@@ -0,0 +1,109 @@
+# ビルトインカタログ
+
+[English](./builtin-catalog.md)
+
+TAKT に同梱されているすべてのビルトイン piece と persona の総合カタログです。
+
+## おすすめ Piece
+
+| Piece | 推奨用途 |
+|----------|-----------------|
+| `default-mini` | ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。 |
+| `frontend-mini` | フロントエンド向けの mini 構成です。 |
+| `backend-mini` | バックエンド向けの mini 構成です。 |
+| `expert-mini` | エキスパート向けの mini 構成です。 |
+| `default` | 本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。 |
+
+## 全ビルトイン Piece 一覧
+
+カテゴリ順に並べています。
+
+| カテゴリ | Piece | 説明 |
+|---------|----------|-------------|
+| 🚀 クイックスタート | `default-mini` | ミニ開発 piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor) -> 必要に応じて修正。レビュー付き軽量版。 |
+| | `frontend-mini` | ミニフロントエンド piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。フロントエンドナレッジ注入付き。 |
+| | `backend-mini` | ミニバックエンド piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。バックエンドナレッジ注入付き。 |
+| | `default` | フル開発 piece: plan -> implement -> AI review -> 並列レビュー (architect + QA) -> supervisor 承認。各レビュー段階に修正ループあり。 |
+| | `compound-eye` | マルチモデルレビュー: 同じ指示を Claude と Codex に同時送信し、両方のレスポンスを統合。 |
+| ⚡ Mini | `backend-cqrs-mini` | ミニ CQRS+ES piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。CQRS+ES ナレッジ注入付き。 |
+| | `expert-mini` | ミニエキスパート piece: plan -> implement -> 並列レビュー (AI antipattern + expert supervisor)。フルスタックナレッジ注入付き。 |
+| | `expert-cqrs-mini` | ミニ CQRS+ES エキスパート piece: plan -> implement -> 並列レビュー (AI antipattern + expert supervisor)。CQRS+ES ナレッジ注入付き。 |
+| 🎨 フロントエンド | `frontend` | フロントエンド特化開発 piece。React/Next.js に焦点を当てたレビューとナレッジ注入付き。 |
+| ⚙️ バックエンド | `backend` | バックエンド特化開発 piece。バックエンド、セキュリティ、QA エキスパートレビュー付き。 |
+| | `backend-cqrs` | CQRS+ES 特化バックエンド開発 piece。CQRS+ES、セキュリティ、QA エキスパートレビュー付き。 |
+| 🔧 エキスパート | `expert` | フルスタック開発 piece: architecture、frontend、security、QA レビューと修正ループ付き。 |
+| | `expert-cqrs` | フルスタック開発 piece (CQRS+ES 特化): CQRS+ES、frontend、security、QA レビューと修正ループ付き。 |
+| 🛠️ リファクタリング | `structural-reform` | プロジェクト全体のレビューと構造改革: 段階的なファイル分割による反復的なコードベース再構築。 |
+| 🔍 レビュー | `review-fix-minimal` | レビュー特化 piece: review -> fix -> supervisor。レビューフィードバックに基づく反復改善向け。 |
+| | `review-only` | 変更を加えない読み取り専用のコードレビュー piece。 |
+| 🧪 テスト | `unit-test` | ユニットテスト特化 piece: テスト分析 -> テスト実装 -> レビュー -> 修正。 |
+| | `e2e-test` | E2E テスト特化 piece: E2E 分析 -> E2E 実装 -> レビュー -> 修正 (Vitest ベースの E2E フロー)。 |
+| その他 | `research` | リサーチ piece: planner -> digger -> supervisor。質問せずに自律的にリサーチを実行。 |
+| | `deep-research` | ディープリサーチ piece: plan -> dig -> analyze -> supervise。発見駆動型の調査で、浮上した疑問を多角的に分析。 |
+| | `magi` | エヴァンゲリオンにインスパイアされた合議システム。3つの AI persona (MELCHIOR, BALTHASAR, CASPER) が分析・投票。 |
+| | `passthrough` | 最薄ラッパー。タスクを coder にそのまま渡す。レビューなし。 |
+
+`takt switch` で piece をインタラクティブに切り替えできます。
+
+## ビルトイン Persona 一覧
+
+| Persona | 説明 |
+|---------|-------------|
+| **planner** | タスク分析、仕様調査、実装計画 |
+| **architect-planner** | タスク分析と設計計画: コード調査、不明点の解消、実装計画の作成 |
+| **coder** | 機能実装、バグ修正 |
+| **ai-antipattern-reviewer** | AI 固有のアンチパターンレビュー（存在しない API、誤った前提、スコープクリープ） |
+| **architecture-reviewer** | アーキテクチャとコード品質のレビュー、仕様準拠の検証 |
+| **frontend-reviewer** | フロントエンド (React/Next.js) のコード品質とベストプラクティスのレビュー |
+| **cqrs-es-reviewer** | CQRS+Event Sourcing のアーキテクチャと実装のレビュー |
+| **qa-reviewer** | テストカバレッジと品質保証のレビュー |
+| **security-reviewer** | セキュリティ脆弱性の評価 |
+| **conductor** | Phase 3 判定スペシャリスト: レポート/レスポンスを読み取りステータスタグを出力 |
+| **supervisor** | 最終検証、承認 |
+| **expert-supervisor** | エキスパートレベルの最終検証と包括的なレビュー統合 |
+| **research-planner** | リサーチタスクの計画とスコープ定義 |
+| **research-analyzer** | リサーチ結果の解釈と追加調査計画 |
+| **research-digger** | 深掘り調査と情報収集 |
+| **research-supervisor** | リサーチ品質の検証と完全性の評価 |
+| **test-planner** | テスト戦略の分析と包括的なテスト計画 |
+| **pr-commenter** | レビュー結果を GitHub PR コメントとして投稿 |
+
+## カスタム Persona
+
+`~/.takt/personas/` に Markdown ファイルとして persona プロンプトを作成できます。
+
+```markdown
+# ~/.takt/personas/my-reviewer.md
+
+You are a code reviewer specialized in security.
+
+## Role
+- Check for security vulnerabilities
+- Verify input validation
+- Review authentication logic
+```
+
+piece YAML の `personas` セクションマップからカスタム persona を参照します。
+
+```yaml
+personas:
+  my-reviewer: ~/.takt/personas/my-reviewer.md
+
+movements:
+  - name: review
+    persona: my-reviewer
+    # ...
+```
+
+## Persona 別 Provider オーバーライド
+
+`~/.takt/config.yaml` の `persona_providers` を使用して、piece を複製せずに特定の persona を異なる provider にルーティングできます。これにより、例えばコーディングは Codex で実行し、レビューアーは Claude に維持するといった構成が可能になります。
+
+```yaml
+# ~/.takt/config.yaml
+persona_providers:
+  coder: codex                      # coder を Codex で実行
+  ai-antipattern-reviewer: claude   # レビューアーは Claude を維持
+```
+
+この設定はすべての piece にグローバルに適用されます。指定された persona を使用する movement は、実行中の piece に関係なく、対応する provider にルーティングされます。

docs/builtin-catalog.md

@@ -0,0 +1,109 @@
+# Builtin Catalog
+
+[日本語](./builtin-catalog.ja.md)
+
+A comprehensive catalog of all builtin pieces and personas included with TAKT.
+
+## Recommended Pieces
+
+| Piece | Recommended Use |
+|----------|-----------------|
+| `default-mini` | Quick fixes. Lightweight plan → implement → parallel review → fix loop. |
+| `frontend-mini` | Frontend-focused mini configuration. |
+| `backend-mini` | Backend-focused mini configuration. |
+| `expert-mini` | Expert-level mini configuration. |
+| `default` | Serious development. Multi-stage review with parallel reviewers. Used for TAKT's own development. |
+
+## All Builtin Pieces
+
+Organized by category.
+
+| Category | Piece | Description |
+|----------|----------|-------------|
+| 🚀 Quick Start | `default-mini` | Mini development piece: plan -> implement -> parallel review (AI antipattern + supervisor) -> fix if needed. Lightweight with review. |
+| | `frontend-mini` | Mini frontend piece: plan -> implement -> parallel review (AI antipattern + supervisor) with frontend knowledge injection. |
+| | `backend-mini` | Mini backend piece: plan -> implement -> parallel review (AI antipattern + supervisor) with backend knowledge injection. |
+| | `default` | Full development piece: plan -> implement -> AI review -> parallel review (architect + QA) -> supervisor approval. Includes fix loops at each review stage. |
+| | `compound-eye` | Multi-model review: sends the same instruction to Claude and Codex simultaneously, then synthesizes both responses. |
+| ⚡ Mini | `backend-cqrs-mini` | Mini CQRS+ES piece: plan -> implement -> parallel review (AI antipattern + supervisor) with CQRS+ES knowledge injection. |
+| | `expert-mini` | Mini expert piece: plan -> implement -> parallel review (AI antipattern + expert supervisor) with full-stack knowledge injection. |
+| | `expert-cqrs-mini` | Mini CQRS+ES expert piece: plan -> implement -> parallel review (AI antipattern + expert supervisor) with CQRS+ES knowledge injection. |
+| 🎨 Frontend | `frontend` | Frontend-specialized development piece with React/Next.js focused reviews and knowledge injection. |
+| ⚙️ Backend | `backend` | Backend-specialized development piece with backend, security, and QA expert reviews. |
+| | `backend-cqrs` | CQRS+ES-specialized backend development piece with CQRS+ES, security, and QA expert reviews. |
+| 🔧 Expert | `expert` | Full-stack development piece: architecture, frontend, security, QA reviews with fix loops. |
+| | `expert-cqrs` | Full-stack development piece (CQRS+ES specialized): CQRS+ES, frontend, security, QA reviews with fix loops. |
+| 🛠️ Refactoring | `structural-reform` | Full project review and structural reform: iterative codebase restructuring with staged file splits. |
+| 🔍 Review | `review-fix-minimal` | Review-focused piece: review -> fix -> supervisor. For iterative improvement based on review feedback. |
+| | `review-only` | Read-only code review piece that makes no changes. |
+| 🧪 Testing | `unit-test` | Unit test focused piece: test analysis -> test implementation -> review -> fix. |
+| | `e2e-test` | E2E test focused piece: E2E analysis -> E2E implementation -> review -> fix (Vitest-based E2E flow). |
+| Others | `research` | Research piece: planner -> digger -> supervisor. Autonomously executes research without asking questions. |
+| | `deep-research` | Deep research piece: plan -> dig -> analyze -> supervise. Discovery-driven investigation that follows emerging questions with multi-perspective analysis. |
+| | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
+| | `passthrough` | Thinnest wrapper. Pass task directly to coder as-is. No review. |
+
+Use `takt switch` to switch pieces interactively.
+
+## Builtin Personas
+
+| Persona | Description |
+|---------|-------------|
+| **planner** | Task analysis, spec investigation, implementation planning |
+| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans |
+| **coder** | Feature implementation, bug fixing |
+| **ai-antipattern-reviewer** | AI-specific antipattern review (non-existent APIs, incorrect assumptions, scope creep) |
+| **architecture-reviewer** | Architecture and code quality review, spec compliance verification |
+| **frontend-reviewer** | Frontend (React/Next.js) code quality and best practices review |
+| **cqrs-es-reviewer** | CQRS+Event Sourcing architecture and implementation review |
+| **qa-reviewer** | Test coverage and quality assurance review |
+| **security-reviewer** | Security vulnerability assessment |
+| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags |
+| **supervisor** | Final validation, approval |
+| **expert-supervisor** | Expert-level final validation with comprehensive review integration |
+| **research-planner** | Research task planning and scope definition |
+| **research-analyzer** | Research result interpretation and additional investigation planning |
+| **research-digger** | Deep investigation and information gathering |
+| **research-supervisor** | Research quality validation and completeness assessment |
+| **test-planner** | Test strategy analysis and comprehensive test planning |
+| **pr-commenter** | Posts review findings as GitHub PR comments |
+
+## Custom Personas
+
+Create persona prompts as Markdown files in `~/.takt/personas/`:
+
+```markdown
+# ~/.takt/personas/my-reviewer.md
+
+You are a code reviewer specialized in security.
+
+## Role
+- Check for security vulnerabilities
+- Verify input validation
+- Review authentication logic
+```
+
+Reference custom personas from piece YAML via the `personas` section map:
+
+```yaml
+personas:
+  my-reviewer: ~/.takt/personas/my-reviewer.md
+
+movements:
+  - name: review
+    persona: my-reviewer
+    # ...
+```
+
+## Per-persona Provider Overrides
+
+Use `persona_providers` in `~/.takt/config.yaml` to route specific personas to different providers without duplicating pieces. This allows you to run, for example, coding on Codex while keeping reviewers on Claude.
+
+```yaml
+# ~/.takt/config.yaml
+persona_providers:
+  coder: codex                      # Run coder on Codex
+  ai-antipattern-reviewer: claude   # Keep reviewers on Claude
+```
+
+This configuration applies globally to all pieces. Any movement using the specified persona will be routed to the corresponding provider, regardless of which piece is being executed.

docs/ci-cd.ja.md

@@ -0,0 +1,178 @@
+[English](./ci-cd.md)
+
+# CI/CD 連携
+
+TAKT は CI/CD パイプラインに統合して、タスク実行、PR レビュー、コード生成を自動化できます。このガイドでは GitHub Actions のセットアップ、pipeline モードのオプション、その他の CI システムでの設定について説明します。
+
+## GitHub Actions
+
+TAKT は GitHub Actions 連携用の公式アクション [takt-action](https://github.com/nrslib/takt-action) を提供しています。
+
+### 完全なワークフロー例
+
+```yaml
+name: TAKT
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  takt:
+    if: contains(github.event.comment.body, '@takt')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run TAKT
+        uses: nrslib/takt-action@main
+        with:
+          anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### パーミッション
+
+`takt-action` が正しく機能するには次のパーミッションが必要です。
+
+| パーミッション | 用途 |
+|-------------|------|
+| `contents: write` | ブランチの作成、コミット、コードのプッシュ |
+| `issues: write` | Issue の読み取りとコメント |
+| `pull-requests: write` | PR の作成と更新 |
+
+## Pipeline モード
+
+`--pipeline` を指定すると、非インタラクティブな pipeline モードが有効になります。ブランチの作成、piece の実行、コミット、プッシュを自動的に行います。このモードは人的操作が不可能な CI/CD 自動化向けに設計されています。
+
+Pipeline モードでは、`--auto-pr` を明示的に指定しない限り PR は作成**されません**。
+
+### Pipeline の全オプション
+
+| オプション | 説明 |
+|-----------|------|
+| `--pipeline` | **pipeline（非インタラクティブ）モードを有効化** -- CI/自動化に必要 |
+| `-t, --task <text>` | タスク内容（GitHub Issue の代替） |
+| `-i, --issue <N>` | GitHub Issue 番号（インタラクティブモードでの `#N` と同等） |
+| `-w, --piece <name or path>` | Piece 名または piece YAML ファイルのパス |
+| `-b, --branch <name>` | ブランチ名を指定（省略時は自動生成） |
+| `--auto-pr` | PR を作成（インタラクティブ: 確認スキップ、pipeline: PR 有効化） |
+| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（pipeline モード、piece のみ実行） |
+| `--repo <owner/repo>` | リポジトリを指定（PR 作成用） |
+| `-q, --quiet` | 最小出力モード: AI 出力を抑制（CI 向け） |
+| `--provider <name>` | エージェント provider を上書き（claude\|codex\|opencode\|mock） |
+| `--model <name>` | エージェントモデルを上書き |
+
+### コマンド例
+
+**基本的な pipeline 実行**
+
+```bash
+takt --pipeline --task "Fix bug"
+```
+
+**PR 自動作成付きの pipeline 実行**
+
+```bash
+takt --pipeline --task "Fix bug" --auto-pr
+```
+
+**GitHub Issue をリンクして PR を作成**
+
+```bash
+takt --pipeline --issue 99 --auto-pr
+```
+
+**Piece とブランチ名を指定**
+
+```bash
+takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug
+```
+
+**PR 作成用にリポジトリを指定**
+
+```bash
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+```
+
+**Piece のみ実行（ブランチ作成、コミット、プッシュをスキップ）**
+
+```bash
+takt --pipeline --task "Fix bug" --skip-git
+```
+
+**最小出力モード（CI ログ向けに AI 出力を抑制）**
+
+```bash
+takt --pipeline --task "Fix bug" --quiet
+```
+
+## Pipeline テンプレート変数
+
+`~/.takt/config.yaml` の pipeline 設定では、コミットメッセージと PR 本文をカスタマイズするためのテンプレート変数をサポートしています。
+
+```yaml
+pipeline:
+  default_branch_prefix: "takt/"
+  commit_message_template: "feat: {title} (#{issue})"
+  pr_body_template: |
+    ## Summary
+    {issue_body}
+    Closes #{issue}
+```
+
+| 変数 | 使用可能な場所 | 説明 |
+|------|--------------|------|
+| `{title}` | コミットメッセージ | Issue タイトル |
+| `{issue}` | コミットメッセージ、PR 本文 | Issue 番号 |
+| `{issue_body}` | PR 本文 | Issue 本文 |
+| `{report}` | PR 本文 | Piece 実行レポート |
+
+## その他の CI システム
+
+GitHub Actions 以外の CI システムでは、TAKT をグローバルにインストールして pipeline モードを直接使用します。
+
+```bash
+# takt のインストール
+npm install -g takt
+
+# pipeline モードで実行
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+```
+
+このアプローチは Node.js をサポートする任意の CI システムで動作します。GitLab CI、CircleCI、Jenkins、Azure DevOps などが含まれます。
+
+## 環境変数
+
+CI 環境での認証には、適切な API キー環境変数を設定してください。これらは他のツールとの衝突を避けるため TAKT 固有のプレフィックスを使用しています。
+
+```bash
+# Claude（Anthropic）用
+export TAKT_ANTHROPIC_API_KEY=sk-ant-...
+
+# Codex（OpenAI）用
+export TAKT_OPENAI_API_KEY=sk-...
+
+# OpenCode 用
+export TAKT_OPENCODE_API_KEY=...
+```
+
+優先順位: 環境変数は `config.yaml` の設定よりも優先されます。
+
+> **注意**: 環境変数で API キーを設定すれば、Claude Code、Codex、OpenCode CLI のインストールは不要です。TAKT が対応する API を直接呼び出します。
+
+## コストに関する注意
+
+TAKT は AI API（Claude または OpenAI）を使用するため、特に CI/CD 環境でタスクが自動実行される場合、大きなコストが発生する可能性があります。次の点に注意してください。
+
+- **API 使用量の監視**: 予期しない請求を避けるため、AI provider で課金アラートを設定してください。
+- **`--quiet` モードの使用**: 出力量は削減されますが、API 呼び出し回数は減りません。
+- **適切な piece の選択**: シンプルな piece（例: `default-mini`）はマルチステージの piece（例: 並列レビュー付きの `default`）よりも API 呼び出しが少なくなります。
+- **CI トリガーの制限**: 意図しない実行を防ぐため、条件付きトリガー（例: `if: contains(github.event.comment.body, '@takt')`）を使用してください。
+- **`--provider mock` でのテスト**: CI パイプラインの開発中は mock provider を使用して、実際の API コストを回避してください。

docs/ci-cd.md

@@ -0,0 +1,178 @@
+[日本語](./ci-cd.ja.md)
+
+# CI/CD Integration
+
+TAKT can be integrated into CI/CD pipelines to automate task execution, PR reviews, and code generation. This guide covers GitHub Actions setup, pipeline mode options, and configuration for other CI systems.
+
+## GitHub Actions
+
+TAKT provides the official [takt-action](https://github.com/nrslib/takt-action) for GitHub Actions integration.
+
+### Complete Workflow Example
+
+```yaml
+name: TAKT
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  takt:
+    if: contains(github.event.comment.body, '@takt')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run TAKT
+        uses: nrslib/takt-action@main
+        with:
+          anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Permissions
+
+The following permissions are required for `takt-action` to function correctly:
+
+| Permission | Required For |
+|------------|-------------|
+| `contents: write` | Creating branches, committing, and pushing code |
+| `issues: write` | Reading and commenting on issues |
+| `pull-requests: write` | Creating and updating pull requests |
+
+## Pipeline Mode
+
+Specifying `--pipeline` enables non-interactive pipeline mode. It automatically creates a branch, runs the piece, commits, and pushes. This mode is designed for CI/CD automation where no human interaction is available.
+
+In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly specified.
+
+### All Pipeline Options
+
+| Option | Description |
+|--------|-------------|
+| `--pipeline` | **Enable pipeline (non-interactive) mode** -- Required for CI/automation |
+| `-t, --task <text>` | Task content (alternative to GitHub Issue) |
+| `-i, --issue <N>` | GitHub issue number (same as `#N` in interactive mode) |
+| `-w, --piece <name or path>` | Piece name or path to piece YAML file |
+| `-b, --branch <name>` | Specify branch name (auto-generated if omitted) |
+| `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) |
+| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) |
+| `--repo <owner/repo>` | Specify repository (for PR creation) |
+| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
+| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|mock) |
+| `--model <name>` | Override agent model |
+
+### Command Examples
+
+**Basic pipeline execution:**
+
+```bash
+takt --pipeline --task "Fix bug"
+```
+
+**Pipeline execution with automatic PR creation:**
+
+```bash
+takt --pipeline --task "Fix bug" --auto-pr
+```
+
+**Link a GitHub issue and create a PR:**
+
+```bash
+takt --pipeline --issue 99 --auto-pr
+```
+
+**Specify piece and branch name:**
+
+```bash
+takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug
+```
+
+**Specify repository for PR creation:**
+
+```bash
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+```
+
+**Piece execution only (skip branch creation, commit, push):**
+
+```bash
+takt --pipeline --task "Fix bug" --skip-git
+```
+
+**Minimal output mode (suppress AI output for CI logs):**
+
+```bash
+takt --pipeline --task "Fix bug" --quiet
+```
+
+## Pipeline Template Variables
+
+Pipeline configuration in `~/.takt/config.yaml` supports template variables for customizing commit messages and PR bodies:
+
+```yaml
+pipeline:
+  default_branch_prefix: "takt/"
+  commit_message_template: "feat: {title} (#{issue})"
+  pr_body_template: |
+    ## Summary
+    {issue_body}
+    Closes #{issue}
+```
+
+| Variable | Available In | Description |
+|----------|-------------|-------------|
+| `{title}` | Commit message | Issue title |
+| `{issue}` | Commit message, PR body | Issue number |
+| `{issue_body}` | PR body | Issue body |
+| `{report}` | PR body | Piece execution report |
+
+## Other CI Systems
+
+For CI systems other than GitHub Actions, install TAKT globally and use pipeline mode directly:
+
+```bash
+# Install takt
+npm install -g takt
+
+# Run in pipeline mode
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+```
+
+This approach works with any CI system that supports Node.js, including GitLab CI, CircleCI, Jenkins, Azure DevOps, and others.
+
+## Environment Variables
+
+For authentication in CI environments, set the appropriate API key environment variable. These use TAKT-specific prefixes to avoid conflicts with other tools.
+
+```bash
+# For Claude (Anthropic)
+export TAKT_ANTHROPIC_API_KEY=sk-ant-...
+
+# For Codex (OpenAI)
+export TAKT_OPENAI_API_KEY=sk-...
+
+# For OpenCode
+export TAKT_OPENCODE_API_KEY=...
+```
+
+Priority: Environment variables take precedence over `config.yaml` settings.
+
+> **Note**: If you set an API key via environment variable, installing Claude Code, Codex, or OpenCode CLI is not necessary. TAKT directly calls the respective API.
+
+## Cost Considerations
+
+TAKT uses AI APIs (Claude or OpenAI), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Take the following precautions:
+
+- **Monitor API usage**: Set up billing alerts with your AI provider to avoid unexpected charges.
+- **Use `--quiet` mode**: Reduces output volume but does not reduce API calls.
+- **Choose appropriate pieces**: Simpler pieces (e.g., `default-mini`) use fewer API calls than multi-stage pieces (e.g., `default` with parallel reviews).
+- **Limit CI triggers**: Use conditional triggers (e.g., `if: contains(github.event.comment.body, '@takt')`) to prevent unintended executions.
+- **Test with `--provider mock`**: Use mock provider during CI pipeline development to avoid real API costs.

docs/cli-reference.ja.md

@@ -0,0 +1,290 @@
+# CLI リファレンス
+
+[English](./cli-reference.md)
+
+このドキュメントは TAKT CLI の全コマンドとオプションの完全なリファレンスです。
+
+## グローバルオプション
+
+| オプション | 説明 |
+|-----------|------|
+| `--pipeline` | pipeline（非インタラクティブ）モードを有効化 -- CI/自動化に必要 |
+| `-t, --task <text>` | タスク内容（GitHub Issue の代替） |
+| `-i, --issue <N>` | GitHub Issue 番号（インタラクティブモードでの `#N` と同等） |
+| `-w, --piece <name or path>` | Piece 名または piece YAML ファイルのパス |
+| `-b, --branch <name>` | ブランチ名を指定（省略時は自動生成） |
+| `--auto-pr` | PR を作成（インタラクティブ: 確認スキップ、pipeline: PR 有効化） |
+| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（pipeline モード、piece のみ実行） |
+| `--repo <owner/repo>` | リポジトリを指定（PR 作成用） |
+| `--create-worktree <yes\|no>` | worktree 確認プロンプトをスキップ |
+| `-q, --quiet` | 最小出力モード: AI 出力を抑制（CI 向け） |
+| `--provider <name>` | エージェント provider を上書き（claude\|codex\|opencode\|mock） |
+| `--model <name>` | エージェントモデルを上書き |
+| `--config <path>` | グローバル設定ファイルのパス（デフォルト: `~/.takt/config.yaml`） |
+
+## インタラクティブモード
+
+AI との会話を通じてタスク内容を精緻化してから実行するモードです。タスクの要件が曖昧な場合や、AI と相談しながら内容を詰めたい場合に便利です。
+
+```bash
+# インタラクティブモードを開始（引数なし）
+takt
+
+# 初期メッセージを指定（短い単語のみ）
+takt hello
+```
+
+**注意:** `--task` オプションを指定するとインタラクティブモードをスキップして直接実行します。Issue 参照（`#6`、`--issue`）はインタラクティブモードの初期入力として使用されます。
+
+### フロー
+
+1. Piece を選択
+2. インタラクティブモードを選択（assistant / persona / quiet / passthrough）
+3. AI との会話でタスク内容を精緻化
+4. `/go` でタスク指示を確定（`/go 追加の指示` のように追記も可能）、または `/play <task>` でタスクを即座に実行
+5. 実行（worktree 作成、piece 実行、PR 作成）
+
+### インタラクティブモードの種類
+
+| モード | 説明 |
+|--------|------|
+| `assistant` | デフォルト。AI がタスク指示を生成する前に明確化のための質問を行う。 |
+| `persona` | 最初の movement の persona と会話（そのシステムプロンプトとツールを使用）。 |
+| `quiet` | 質問なしでタスク指示を生成（ベストエフォート）。 |
+| `passthrough` | AI 処理なしでユーザー入力をそのままタスクテキストとして使用。 |
+
+Piece は YAML の `interactive_mode` フィールドでデフォルトモードを設定できます。
+
+### 実行例
+
+```
+$ takt
+
+Select piece:
+  > default (current)
+    Development/
+    Research/
+    Cancel
+
+Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit)
+
+> I want to add user authentication feature
+
+[AI が要件を確認・整理]
+
+> /go
+
+Proposed task instructions:
+---
+Implement user authentication feature.
+
+Requirements:
+- Login with email address and password
+- JWT token-based authentication
+- Password hashing (bcrypt)
+- Login/logout API endpoints
+---
+
+Proceed with these task instructions? (Y/n) y
+
+? Create worktree? (Y/n) y
+
+[Piece の実行を開始...]
+```
+
+## 直接タスク実行
+
+`--task` オプションを使用して、インタラクティブモードをスキップして直接実行できます。
+
+```bash
+# --task オプションでタスク内容を指定
+takt --task "Fix bug"
+
+# piece を指定
+takt --task "Add authentication" --piece expert
+
+# PR を自動作成
+takt --task "Fix bug" --auto-pr
+```
+
+**注意:** 引数として文字列を渡す場合（例: `takt "Add login feature"`）は、初期メッセージとしてインタラクティブモードに入ります。
+
+## GitHub Issue タスク
+
+GitHub Issue を直接タスクとして実行できます。Issue のタイトル、本文、ラベル、コメントがタスク内容として自動的に取り込まれます。
+
+```bash
+# Issue 番号を指定して実行
+takt #6
+takt --issue 6
+
+# Issue + piece 指定
+takt #6 --piece expert
+
+# Issue + PR 自動作成
+takt #6 --auto-pr
+```
+
+**要件:** [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ、認証済みである必要があります。
+
+## タスク管理コマンド
+
+`.takt/tasks.yaml` と `.takt/tasks/{slug}/` 配下のタスクディレクトリを使ったバッチ処理です。複数のタスクを蓄積し、後でまとめて実行するのに便利です。
+
+### takt add
+
+AI との会話でタスク要件を精緻化し、`.takt/tasks.yaml` にタスクを追加します。
+
+```bash
+# AI との会話でタスク要件を精緻化し、タスクを追加
+takt add
+
+# GitHub Issue からタスクを追加（Issue 番号がブランチ名に反映される）
+takt add #28
+```
+
+### takt run
+
+`.takt/tasks.yaml` のすべての pending タスクを実行します。
+
+```bash
+# .takt/tasks.yaml の pending タスクをすべて実行
+takt run
+```
+
+### takt watch
+
+`.takt/tasks.yaml` を監視し、タスクが追加されると自動実行する常駐プロセスです。
+
+```bash
+# .takt/tasks.yaml を監視してタスクを自動実行（常駐プロセス）
+takt watch
+```
+
+### takt list
+
+タスクブランチの一覧表示と操作（マージ、削除など）を行います。
+
+```bash
+# タスクブランチの一覧表示（マージ/削除）
+takt list
+
+# 非インタラクティブモード（CI/スクリプト向け）
+takt list --non-interactive
+takt list --non-interactive --action diff --branch takt/my-branch
+takt list --non-interactive --action delete --branch takt/my-branch --yes
+takt list --non-interactive --format json
+```
+
+### タスクディレクトリワークフロー（作成 / 実行 / 確認）
+
+1. `takt add` を実行し、`.takt/tasks.yaml` に pending レコードが作成されたことを確認。
+2. 生成された `.takt/tasks/{slug}/order.md` を開き、必要に応じて詳細な仕様や参考資料を追記。
+3. `takt run`（または `takt watch`）を実行して `tasks.yaml` の pending タスクを実行。
+4. `task_dir` と同じ slug の `.takt/runs/{slug}/reports/` で出力を確認。
+
+## Pipeline モード
+
+`--pipeline` を指定すると、非インタラクティブな pipeline モードが有効になります。ブランチの作成、piece の実行、コミットとプッシュを自動的に行います。CI/CD 自動化に適しています。
+
+```bash
+# pipeline モードでタスクを実行
+takt --pipeline --task "Fix bug"
+
+# pipeline 実行 + PR 自動作成
+takt --pipeline --task "Fix bug" --auto-pr
+
+# Issue 情報をリンク
+takt --pipeline --issue 99 --auto-pr
+
+# piece とブランチを指定
+takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug
+
+# リポジトリを指定（PR 作成用）
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+
+# piece のみ実行（ブランチ作成、コミット、プッシュをスキップ）
+takt --pipeline --task "Fix bug" --skip-git
+
+# 最小出力モード（CI 向け）
+takt --pipeline --task "Fix bug" --quiet
+```
+
+Pipeline モードでは、`--auto-pr` を指定しない限り PR は作成されません。
+
+**GitHub 連携:** GitHub Actions で TAKT を使用する場合は [takt-action](https://github.com/nrslib/takt-action) を参照してください。PR レビューやタスク実行を自動化できます。
+
+## ユーティリティコマンド
+
+### takt switch
+
+アクティブな piece をインタラクティブに切り替えます。
+
+```bash
+takt switch
+```
+
+### takt eject
+
+ビルトインの piece/persona をローカルディレクトリにコピーしてカスタマイズします。
+
+```bash
+# ビルトインの piece/persona をプロジェクト .takt/ にコピー
+takt eject
+
+# ~/.takt/（グローバル）にコピー
+takt eject --global
+
+# 特定のファセットをカスタマイズ用にエジェクト
+takt eject persona coder
+takt eject instruction plan --global
+```
+
+### takt clear
+
+エージェントの会話セッションをクリア（状態のリセット）します。
+
+```bash
+takt clear
+```
+
+### takt export-cc
+
+ビルトインの piece/persona を Claude Code Skill としてデプロイします。
+
+```bash
+takt export-cc
+```
+
+### takt catalog
+
+レイヤー間で利用可能なファセットの一覧を表示します。
+
+```bash
+takt catalog
+takt catalog personas
+```
+
+### takt prompt
+
+各 movement とフェーズの組み立て済みプロンプトをプレビューします。
+
+```bash
+takt prompt [piece]
+```
+
+### takt config
+
+パーミッションモードを設定します。
+
+```bash
+takt config
+```
+
+### takt reset
+
+Piece カテゴリをビルトインのデフォルトにリセットします。
+
+```bash
+takt reset categories
+```

docs/cli-reference.md

@@ -0,0 +1,290 @@
+# CLI Reference
+
+[日本語](./cli-reference.ja.md)
+
+This document provides a complete reference for all TAKT CLI commands and options.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--pipeline` | Enable pipeline (non-interactive) mode -- required for CI/automation |
+| `-t, --task <text>` | Task content (alternative to GitHub Issue) |
+| `-i, --issue <N>` | GitHub issue number (same as `#N` in interactive mode) |
+| `-w, --piece <name or path>` | Piece name or path to piece YAML file |
+| `-b, --branch <name>` | Specify branch name (auto-generated if omitted) |
+| `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) |
+| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) |
+| `--repo <owner/repo>` | Specify repository (for PR creation) |
+| `--create-worktree <yes\|no>` | Skip worktree confirmation prompt |
+| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
+| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|mock) |
+| `--model <name>` | Override agent model |
+| `--config <path>` | Path to global config file (default: `~/.takt/config.yaml`) |
+
+## Interactive Mode
+
+A mode where you refine task content through conversation with AI before execution. Useful when task requirements are ambiguous or when you want to clarify content while consulting with AI.
+
+```bash
+# Start interactive mode (no arguments)
+takt
+
+# Specify initial message (short word only)
+takt hello
+```
+
+**Note:** `--task` option skips interactive mode and executes the task directly. Issue references (`#6`, `--issue`) are used as initial input in interactive mode.
+
+### Flow
+
+1. Select piece
+2. Select interactive mode (assistant / persona / quiet / passthrough)
+3. Refine task content through conversation with AI
+4. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`), or use `/play <task>` to execute a task immediately
+5. Execute (create worktree, run piece, create PR)
+
+### Interactive Mode Variants
+
+| Mode | Description |
+|------|-------------|
+| `assistant` | Default. AI asks clarifying questions before generating task instructions. |
+| `persona` | Conversation with the first movement's persona (uses its system prompt and tools). |
+| `quiet` | Generates task instructions without asking questions (best-effort). |
+| `passthrough` | Passes user input directly as task text without AI processing. |
+
+Pieces can set a default mode via the `interactive_mode` field in YAML.
+
+### Execution Example
+
+```
+$ takt
+
+Select piece:
+  > default (current)
+    Development/
+    Research/
+    Cancel
+
+Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit)
+
+> I want to add user authentication feature
+
+[AI confirms and organizes requirements]
+
+> /go
+
+Proposed task instructions:
+---
+Implement user authentication feature.
+
+Requirements:
+- Login with email address and password
+- JWT token-based authentication
+- Password hashing (bcrypt)
+- Login/logout API endpoints
+---
+
+Proceed with these task instructions? (Y/n) y
+
+? Create worktree? (Y/n) y
+
+[Piece execution starts...]
+```
+
+## Direct Task Execution
+
+Use the `--task` option to skip interactive mode and execute directly.
+
+```bash
+# Specify task content with --task option
+takt --task "Fix bug"
+
+# Specify piece
+takt --task "Add authentication" --piece expert
+
+# Auto-create PR
+takt --task "Fix bug" --auto-pr
+```
+
+**Note:** Passing a string as an argument (e.g., `takt "Add login feature"`) enters interactive mode with it as the initial message.
+
+## GitHub Issue Tasks
+
+You can execute GitHub Issues directly as tasks. Issue title, body, labels, and comments are automatically incorporated as task content.
+
+```bash
+# Execute by specifying issue number
+takt #6
+takt --issue 6
+
+# Issue + piece specification
+takt #6 --piece expert
+
+# Issue + auto-create PR
+takt #6 --auto-pr
+```
+
+**Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
+
+## Task Management Commands
+
+Batch processing using `.takt/tasks.yaml` with task directories under `.takt/tasks/{slug}/`. Useful for accumulating multiple tasks and executing them together later.
+
+### takt add
+
+Refine task requirements through AI conversation, then add a task to `.takt/tasks.yaml`.
+
+```bash
+# Refine task requirements through AI conversation, then add task
+takt add
+
+# Add task from GitHub Issue (issue number reflected in branch name)
+takt add #28
+```
+
+### takt run
+
+Execute all pending tasks from `.takt/tasks.yaml`.
+
+```bash
+# Execute all pending tasks in .takt/tasks.yaml
+takt run
+```
+
+### takt watch
+
+Monitor `.takt/tasks.yaml` and auto-execute tasks as a resident process.
+
+```bash
+# Monitor .takt/tasks.yaml and auto-execute tasks (resident process)
+takt watch
+```
+
+### takt list
+
+List task branches and perform actions (merge, delete, etc.).
+
+```bash
+# List task branches (merge/delete)
+takt list
+
+# Non-interactive mode (for CI/scripts)
+takt list --non-interactive
+takt list --non-interactive --action diff --branch takt/my-branch
+takt list --non-interactive --action delete --branch takt/my-branch --yes
+takt list --non-interactive --format json
+```
+
+### Task Directory Workflow (Create / Run / Verify)
+
+1. Run `takt add` and confirm a pending record is created in `.takt/tasks.yaml`.
+2. Open the generated `.takt/tasks/{slug}/order.md` and add detailed specifications/references as needed.
+3. Run `takt run` (or `takt watch`) to execute pending tasks from `tasks.yaml`.
+4. Verify outputs in `.takt/runs/{slug}/reports/` using the same slug as `task_dir`.
+
+## Pipeline Mode
+
+Specifying `--pipeline` enables non-interactive pipeline mode. Automatically creates branch, runs piece, commits and pushes. Suitable for CI/CD automation.
+
+```bash
+# Execute task in pipeline mode
+takt --pipeline --task "Fix bug"
+
+# Pipeline execution + auto-create PR
+takt --pipeline --task "Fix bug" --auto-pr
+
+# Link issue information
+takt --pipeline --issue 99 --auto-pr
+
+# Specify piece and branch
+takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug
+
+# Specify repository (for PR creation)
+takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
+
+# Piece execution only (skip branch creation, commit, push)
+takt --pipeline --task "Fix bug" --skip-git
+
+# Minimal output mode (for CI)
+takt --pipeline --task "Fix bug" --quiet
+```
+
+In pipeline mode, PRs are not created unless `--auto-pr` is specified.
+
+**GitHub Integration:** When using TAKT in GitHub Actions, see [takt-action](https://github.com/nrslib/takt-action). You can automate PR reviews and task execution.
+
+## Utility Commands
+
+### takt switch
+
+Interactively switch the active piece.
+
+```bash
+takt switch
+```
+
+### takt eject
+
+Copy builtin pieces/personas to your local directory for customization.
+
+```bash
+# Copy builtin pieces/personas to project .takt/ for customization
+takt eject
+
+# Copy to ~/.takt/ (global) instead
+takt eject --global
+
+# Eject a specific facet for customization
+takt eject persona coder
+takt eject instruction plan --global
+```
+
+### takt clear
+
+Clear agent conversation sessions (reset state).
+
+```bash
+takt clear
+```
+
+### takt export-cc
+
+Deploy builtin pieces/personas as a Claude Code Skill.
+
+```bash
+takt export-cc
+```
+
+### takt catalog
+
+List available facets across layers.
+
+```bash
+takt catalog
+takt catalog personas
+```
+
+### takt prompt
+
+Preview assembled prompts for each movement and phase.
+
+```bash
+takt prompt [piece]
+```
+
+### takt config
+
+Configure permission mode.
+
+```bash
+takt config
+```
+
+### takt reset
+
+Reset piece categories to builtin defaults.
+
+```bash
+takt reset categories
+```

docs/configuration.ja.md

@@ -0,0 +1,400 @@
+# 設定
+
+[English](./configuration.md)
+
+このドキュメントは TAKT の全設定オプションのリファレンスです。クイックスタートについては [README](../README.md) を参照してください。
+
+## グローバル設定
+
+`~/.takt/config.yaml` で TAKT のデフォルト設定を行います。このファイルは初回実行時に自動作成されます。すべてのフィールドは省略可能です。
+
+```yaml
+# ~/.takt/config.yaml
+language: en                  # UI 言語: 'en' または 'ja'
+default_piece: default        # 新規プロジェクトのデフォルト piece
+log_level: info               # ログレベル: debug, info, warn, error
+provider: claude              # デフォルト provider: claude, codex, または opencode
+model: sonnet                 # デフォルトモデル（省略可、provider にそのまま渡される）
+branch_name_strategy: romaji  # ブランチ名生成方式: 'romaji'（高速）または 'ai'（低速）
+prevent_sleep: false          # 実行中に macOS のアイドルスリープを防止（caffeinate）
+notification_sound: true      # 通知音の有効/無効
+notification_sound_events:    # イベントごとの通知音切り替え（省略可）
+  iteration_limit: false
+  piece_complete: true
+  piece_abort: true
+  run_complete: true          # デフォルト有効。false で無効化
+  run_abort: true             # デフォルト有効。false で無効化
+concurrency: 1                # takt run の並列タスク数（1-10、デフォルト: 1 = 逐次実行）
+task_poll_interval_ms: 500    # takt run での新規タスクポーリング間隔（100-5000、デフォルト: 500）
+interactive_preview_movements: 3  # インタラクティブモードでの movement プレビュー数（0-10、デフォルト: 3）
+
+# ランタイム環境デフォルト（piece_config.runtime で上書きしない限りすべての piece に適用）
+# runtime:
+#   prepare:
+#     - gradle    # .runtime/ に Gradle キャッシュ/設定を準備
+#     - node      # .runtime/ に npm キャッシュを準備
+
+# persona ごとの provider 上書き（省略可）
+# piece を複製せずに特定の persona を別の provider にルーティング
+# persona_providers:
+#   coder: codex             # coder を Codex で実行
+#   ai-antipattern-reviewer: claude  # レビュアーは Claude のまま
+
+# provider 固有のパーミッションプロファイル（省略可）
+# 優先順位: プロジェクト上書き > グローバル上書き > プロジェクトデフォルト > グローバルデフォルト > required_permission_mode（下限）
+# provider_profiles:
+#   codex:
+#     default_permission_mode: full
+#     movement_permission_overrides:
+#       ai_review: readonly
+#   claude:
+#     default_permission_mode: edit
+
+# API キー設定（省略可）
+# 環境変数 TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY で上書き可能
+# anthropic_api_key: sk-ant-...  # Claude（Anthropic）用
+# openai_api_key: sk-...         # Codex（OpenAI）用
+# opencode_api_key: ...          # OpenCode 用
+
+# Codex CLI パス上書き（省略可）
+# Codex SDK が使用する Codex CLI バイナリを上書き（実行可能ファイルの絶対パスが必要）
+# 環境変数 TAKT_CODEX_CLI_PATH で上書き可能
+# codex_cli_path: /usr/local/bin/codex
+
+# ビルトイン piece フィルタリング（省略可）
+# builtin_pieces_enabled: true           # false ですべてのビルトインを無効化
+# disabled_builtins: [magi, passthrough] # 特定のビルトイン piece を無効化
+
+# pipeline 実行設定（省略可）
+# ブランチ名、コミットメッセージ、PR 本文をカスタマイズ
+# pipeline:
+#   default_branch_prefix: "takt/"
+#   commit_message_template: "feat: {title} (#{issue})"
+#   pr_body_template: |
+#     ## Summary
+#     {issue_body}
+#     Closes #{issue}
+```
+
+### グローバル設定フィールドリファレンス
+
+| フィールド | 型 | デフォルト | 説明 |
+|-----------|------|---------|------|
+| `language` | `"en"` \| `"ja"` | `"en"` | UI 言語 |
+| `default_piece` | string | `"default"` | 新規プロジェクトのデフォルト piece |
+| `log_level` | `"debug"` \| `"info"` \| `"warn"` \| `"error"` | `"info"` | ログレベル |
+| `provider` | `"claude"` \| `"codex"` \| `"opencode"` | `"claude"` | デフォルト AI provider |
+| `model` | string | - | デフォルトモデル名（provider にそのまま渡される） |
+| `branch_name_strategy` | `"romaji"` \| `"ai"` | `"romaji"` | ブランチ名生成方式 |
+| `prevent_sleep` | boolean | `false` | macOS アイドルスリープ防止（caffeinate） |
+| `notification_sound` | boolean | `true` | 通知音の有効化 |
+| `notification_sound_events` | object | - | イベントごとの通知音切り替え |
+| `concurrency` | number (1-10) | `1` | `takt run` の並列タスク数 |
+| `task_poll_interval_ms` | number (100-5000) | `500` | 新規タスクのポーリング間隔 |
+| `interactive_preview_movements` | number (0-10) | `3` | インタラクティブモードでの movement プレビュー数 |
+| `worktree_dir` | string | - | 共有クローンのディレクトリ（デフォルトは `../{clone-name}`） |
+| `auto_pr` | boolean | - | worktree 実行後に PR を自動作成 |
+| `verbose` | boolean | - | 詳細出力モード |
+| `minimal_output` | boolean | `false` | AI 出力を抑制（CI 向け） |
+| `runtime` | object | - | ランタイム環境デフォルト（例: `prepare: [gradle, node]`） |
+| `persona_providers` | object | - | persona ごとの provider 上書き（例: `coder: codex`） |
+| `provider_options` | object | - | グローバルな provider 固有オプション |
+| `provider_profiles` | object | - | provider 固有のパーミッションプロファイル |
+| `anthropic_api_key` | string | - | Claude 用 Anthropic API キー |
+| `openai_api_key` | string | - | Codex 用 OpenAI API キー |
+| `opencode_api_key` | string | - | OpenCode API キー |
+| `codex_cli_path` | string | - | Codex CLI バイナリパス上書き（絶対パス） |
+| `enable_builtin_pieces` | boolean | `true` | ビルトイン piece の有効化 |
+| `disabled_builtins` | string[] | `[]` | 無効化する特定のビルトイン piece |
+| `pipeline` | object | - | pipeline テンプレート設定 |
+| `bookmarks_file` | string | - | ブックマークファイルのパス |
+| `piece_categories_file` | string | - | piece カテゴリファイルのパス |
+
+## プロジェクト設定
+
+`.takt/config.yaml` でプロジェクト固有の設定を行います。このファイルはプロジェクトディレクトリで初めて TAKT を使用した際に作成されます。
+
+```yaml
+# .takt/config.yaml
+piece: default                # このプロジェクトの現在の piece
+provider: claude              # このプロジェクトの provider 上書き
+auto_pr: true                 # worktree 実行後に PR を自動作成
+verbose: false                # 詳細出力モード
+
+# provider 固有オプション（グローバルを上書き、piece/movement で上書き可能）
+# provider_options:
+#   codex:
+#     network_access: true
+
+# provider 固有パーミッションプロファイル（プロジェクトレベルの上書き）
+# provider_profiles:
+#   codex:
+#     default_permission_mode: full
+#     movement_permission_overrides:
+#       ai_review: readonly
+```
+
+### プロジェクト設定フィールドリファレンス
+
+| フィールド | 型 | デフォルト | 説明 |
+|-----------|------|---------|------|
+| `piece` | string | `"default"` | このプロジェクトの現在の piece 名 |
+| `provider` | `"claude"` \| `"codex"` \| `"opencode"` \| `"mock"` | - | provider 上書き |
+| `auto_pr` | boolean | - | worktree 実行後に PR を自動作成 |
+| `verbose` | boolean | - | 詳細出力モード |
+| `provider_options` | object | - | provider 固有オプション |
+| `provider_profiles` | object | - | provider 固有のパーミッションプロファイル |
+
+プロジェクト設定の値は、両方が設定されている場合にグローバル設定を上書きします。
+
+## API キー設定
+
+TAKT は3つの provider をサポートしており、それぞれに API キーが必要です。API キーは環境変数または `~/.takt/config.yaml` で設定できます。
+
+### 環境変数（推奨）
+
+```bash
+# Claude（Anthropic）用
+export TAKT_ANTHROPIC_API_KEY=sk-ant-...
+
+# Codex（OpenAI）用
+export TAKT_OPENAI_API_KEY=sk-...
+
+# OpenCode 用
+export TAKT_OPENCODE_API_KEY=...
+```
+
+### 設定ファイル
+
+```yaml
+# ~/.takt/config.yaml
+anthropic_api_key: sk-ant-...  # Claude 用
+openai_api_key: sk-...         # Codex 用
+opencode_api_key: ...          # OpenCode 用
+```
+
+### 優先順位
+
+環境変数は `config.yaml` の設定よりも優先されます。
+
+| Provider | 環境変数 | 設定キー |
+|----------|---------|---------|
+| Claude (Anthropic) | `TAKT_ANTHROPIC_API_KEY` | `anthropic_api_key` |
+| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` |
+| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` |
+
+### セキュリティ
+
+- `config.yaml` に API キーを記載する場合、このファイルを Git にコミットしないよう注意してください。
+- 環境変数の使用を検討してください。
+- 必要に応じて `~/.takt/config.yaml` をグローバル `.gitignore` に追加してください。
+- API キーを設定すれば、対応する CLI ツール（Claude Code、Codex、OpenCode）のインストールは不要です。TAKT が対応する API を直接呼び出します。
+
+### Codex CLI パス上書き
+
+Codex CLI バイナリパスは環境変数または設定ファイルで上書きできます。
+
+```bash
+export TAKT_CODEX_CLI_PATH=/usr/local/bin/codex
+```
+
+```yaml
+# ~/.takt/config.yaml
+codex_cli_path: /usr/local/bin/codex
+```
+
+パスは実行可能ファイルの絶対パスである必要があります。`TAKT_CODEX_CLI_PATH` は設定ファイルの値よりも優先されます。
+
+## モデル解決
+
+各 movement で使用されるモデルは、次の優先順位（高い順）で解決されます。
+
+1. **Piece movement の `model`** - piece YAML の movement 定義で指定
+2. **カスタムエージェントの `model`** - `.takt/agents.yaml` のエージェントレベルのモデル
+3. **グローバル設定の `model`** - `~/.takt/config.yaml` のデフォルトモデル
+4. **Provider デフォルト** - provider のビルトインデフォルトにフォールバック（Claude: `sonnet`、Codex: `codex`、OpenCode: provider デフォルト）
+
+### Provider 固有のモデルに関する注意
+
+**Claude Code** はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`default`）と完全なモデル名（例: `claude-sonnet-4-5-20250929`）をサポートしています。`model` フィールドは provider CLI にそのまま渡されます。利用可能なモデルについては [Claude Code ドキュメント](https://docs.anthropic.com/en/docs/claude-code) を参照してください。
+
+**Codex** は Codex SDK を通じてモデル文字列をそのまま使用します。未指定の場合、デフォルトは `codex` です。利用可能なモデルについては Codex のドキュメントを参照してください。
+
+**OpenCode** は `provider/model` 形式のモデル（例: `opencode/big-pickle`）が必要です。OpenCode provider でモデルを省略すると設定エラーになります。
+
+### 設定例
+
+```yaml
+# ~/.takt/config.yaml
+provider: claude
+model: opus     # すべての movement のデフォルトモデル（上書きされない限り）
+```
+
+```yaml
+# piece.yaml - movement レベルの上書きが最高優先
+movements:
+  - name: plan
+    model: opus       # この movement はグローバル設定に関係なく opus を使用
+    ...
+  - name: implement
+    # model 未指定 - グローバル設定（opus）にフォールバック
+    ...
+```
+
+## Provider プロファイル
+
+Provider プロファイルを使用すると、各 provider にデフォルトのパーミッションモードと movement ごとのパーミッション上書きを設定できます。異なる provider を異なるセキュリティポリシーで運用する場合に便利です。
+
+### パーミッションモード
+
+TAKT は provider 非依存の3つのパーミッションモードを使用します。
+
+| モード | 説明 | Claude | Codex | OpenCode |
+|--------|------|--------|-------|----------|
+| `readonly` | 読み取り専用、ファイル変更不可 | `default` | `read-only` | `read-only` |
+| `edit` | 確認付きでファイル編集を許可 | `acceptEdits` | `workspace-write` | `workspace-write` |
+| `full` | すべてのパーミッションチェックをバイパス | `bypassPermissions` | `danger-full-access` | `danger-full-access` |
+
+### 設定方法
+
+Provider プロファイルはグローバルレベルとプロジェクトレベルの両方で設定できます。
+
+```yaml
+# ~/.takt/config.yaml（グローバル）または .takt/config.yaml（プロジェクト）
+provider_profiles:
+  codex:
+    default_permission_mode: full
+    movement_permission_overrides:
+      ai_review: readonly
+  claude:
+    default_permission_mode: edit
+    movement_permission_overrides:
+      implement: full
+```
+
+### パーミッション解決の優先順位
+
+パーミッションモードは次の順序で解決されます（最初にマッチしたものが適用）。
+
+1. **プロジェクト** `provider_profiles.<provider>.movement_permission_overrides.<movement>`
+2. **グローバル** `provider_profiles.<provider>.movement_permission_overrides.<movement>`
+3. **プロジェクト** `provider_profiles.<provider>.default_permission_mode`
+4. **グローバル** `provider_profiles.<provider>.default_permission_mode`
+5. **Movement** `required_permission_mode`（最低限の下限として機能）
+
+movement の `required_permission_mode` は最低限の下限を設定します。provider プロファイルから解決されたモードが要求モードよりも低い場合、要求モードが使用されます。たとえば、movement が `edit` を要求しているがプロファイルが `readonly` に解決される場合、実効モードは `edit` になります。
+
+### Persona Provider
+
+piece を複製せずに、特定の persona を別の provider にルーティングできます。
+
+```yaml
+# ~/.takt/config.yaml
+persona_providers:
+  coder: codex             # coder persona を Codex で実行
+  ai-antipattern-reviewer: claude  # レビュアーは Claude のまま
+```
+
+これにより、単一の piece 内で provider を混在させることができます。persona 名は movement 定義の `persona` キーに対してマッチされます。
+
+## Piece カテゴリ
+
+`takt switch` や piece 選択プロンプトでの UI 表示を改善するために、piece をカテゴリに整理できます。
+
+### 設定方法
+
+カテゴリは次の場所で設定できます。
+- `builtins/{lang}/piece-categories.yaml` - デフォルトのビルトインカテゴリ
+- `~/.takt/config.yaml` または `piece_categories_file` で指定した別のカテゴリファイル
+
+```yaml
+# ~/.takt/config.yaml または専用カテゴリファイル
+piece_categories:
+  Development:
+    pieces: [default, simple]
+    children:
+      Backend:
+        pieces: [expert-cqrs]
+      Frontend:
+        pieces: [expert]
+  Research:
+    pieces: [research, magi]
+
+show_others_category: true         # 未分類の piece を表示（デフォルト: true）
+others_category_name: "Other Pieces"  # 未分類カテゴリの名前
+```
+
+### カテゴリ機能
+
+- **ネストされたカテゴリ** - 階層的な整理のための無制限の深さ
+- **カテゴリごとの piece リスト** - 特定のカテゴリに piece を割り当て
+- **その他カテゴリ** - 未分類の piece を自動収集（`show_others_category: false` で無効化可能）
+- **ビルトイン piece フィルタリング** - `enable_builtin_pieces: false` ですべてのビルトインを無効化、または `disabled_builtins: [name1, name2]` で選択的に無効化
+
+### カテゴリのリセット
+
+piece カテゴリをビルトインのデフォルトにリセットできます。
+
+```bash
+takt reset categories
+```
+
+## Pipeline テンプレート
+
+Pipeline モード（`--pipeline`）では、ブランチ名、コミットメッセージ、PR 本文をカスタマイズするテンプレートをサポートしています。
+
+### 設定方法
+
+```yaml
+# ~/.takt/config.yaml
+pipeline:
+  default_branch_prefix: "takt/"
+  commit_message_template: "feat: {title} (#{issue})"
+  pr_body_template: |
+    ## Summary
+    {issue_body}
+    Closes #{issue}
+```
+
+### テンプレート変数
+
+| 変数 | 使用可能な場所 | 説明 |
+|------|--------------|------|
+| `{title}` | コミットメッセージ | Issue タイトル |
+| `{issue}` | コミットメッセージ、PR 本文 | Issue 番号 |
+| `{issue_body}` | PR 本文 | Issue 本文 |
+| `{report}` | PR 本文 | Piece 実行レポート |
+
+### Pipeline CLI オプション
+
+| オプション | 説明 |
+|-----------|------|
+| `--pipeline` | pipeline（非インタラクティブ）モードを有効化 |
+| `--auto-pr` | 実行後に PR を作成 |
+| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（piece のみ実行） |
+| `--repo <owner/repo>` | PR 作成用のリポジトリを指定 |
+| `-q, --quiet` | 最小出力モード（AI 出力を抑制） |
+
+## デバッグ
+
+### デバッグログ
+
+`~/.takt/config.yaml` で `debug_enabled: true` を設定するか、`.takt/debug.yaml` ファイルを作成してデバッグログを有効化できます。
+
+```yaml
+# .takt/debug.yaml
+enabled: true
+```
+
+デバッグログは `.takt/logs/debug.log` に NDJSON 形式で出力されます。
+
+### 詳細モード
+
+空の `.takt/verbose` ファイルを作成すると、詳細なコンソール出力が有効になります。これにより、デバッグログも自動的に有効化されます。
+
+または、設定ファイルで `verbose: true` を設定することもできます。
+
+```yaml
+# ~/.takt/config.yaml または .takt/config.yaml
+verbose: true
+```

docs/configuration.md

@@ -0,0 +1,400 @@
+# Configuration
+
+[日本語](./configuration.ja.md)
+
+This document is a reference for all TAKT configuration options. For a quick start, see the main [README](../README.md).
+
+## Global Configuration
+
+Configure TAKT defaults in `~/.takt/config.yaml`. This file is created automatically on first run. All fields are optional.
+
+```yaml
+# ~/.takt/config.yaml
+language: en                  # UI language: 'en' or 'ja'
+default_piece: default        # Default piece for new projects
+log_level: info               # Log level: debug, info, warn, error
+provider: claude              # Default provider: claude, codex, or opencode
+model: sonnet                 # Default model (optional, passed to provider as-is)
+branch_name_strategy: romaji  # Branch name generation: 'romaji' (fast) or 'ai' (slow)
+prevent_sleep: false          # Prevent macOS idle sleep during execution (caffeinate)
+notification_sound: true      # Enable/disable notification sounds
+notification_sound_events:    # Optional per-event toggles
+  iteration_limit: false
+  piece_complete: true
+  piece_abort: true
+  run_complete: true          # Enabled by default; set false to disable
+  run_abort: true             # Enabled by default; set false to disable
+concurrency: 1                # Parallel task count for takt run (1-10, default: 1 = sequential)
+task_poll_interval_ms: 500    # Polling interval for new tasks during takt run (100-5000, default: 500)
+interactive_preview_movements: 3  # Movement previews in interactive mode (0-10, default: 3)
+
+# Runtime environment defaults (applies to all pieces unless piece_config.runtime overrides)
+# runtime:
+#   prepare:
+#     - gradle    # Prepare Gradle cache/config in .runtime/
+#     - node      # Prepare npm cache in .runtime/
+
+# Per-persona provider overrides (optional)
+# Route specific personas to different providers without duplicating pieces
+# persona_providers:
+#   coder: codex             # Run coder on Codex
+#   ai-antipattern-reviewer: claude  # Keep reviewers on Claude
+
+# Provider-specific permission profiles (optional)
+# Priority: project override > global override > project default > global default > required_permission_mode (floor)
+# provider_profiles:
+#   codex:
+#     default_permission_mode: full
+#     movement_permission_overrides:
+#       ai_review: readonly
+#   claude:
+#     default_permission_mode: edit
+
+# API Key configuration (optional)
+# Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY
+# anthropic_api_key: sk-ant-...  # For Claude (Anthropic)
+# openai_api_key: sk-...         # For Codex (OpenAI)
+# opencode_api_key: ...          # For OpenCode
+
+# Codex CLI path override (optional)
+# Override the Codex CLI binary used by the Codex SDK (must be an absolute path to an executable file)
+# Can be overridden by TAKT_CODEX_CLI_PATH environment variable
+# codex_cli_path: /usr/local/bin/codex
+
+# Builtin piece filtering (optional)
+# builtin_pieces_enabled: true           # Set false to disable all builtins
+# disabled_builtins: [magi, passthrough] # Disable specific builtin pieces
+
+# Pipeline execution configuration (optional)
+# Customize branch names, commit messages, and PR body.
+# pipeline:
+#   default_branch_prefix: "takt/"
+#   commit_message_template: "feat: {title} (#{issue})"
+#   pr_body_template: |
+#     ## Summary
+#     {issue_body}
+#     Closes #{issue}
+```
+
+### Global Config Field Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `language` | `"en"` \| `"ja"` | `"en"` | UI language |
+| `default_piece` | string | `"default"` | Default piece for new projects |
+| `log_level` | `"debug"` \| `"info"` \| `"warn"` \| `"error"` | `"info"` | Log level |
+| `provider` | `"claude"` \| `"codex"` \| `"opencode"` | `"claude"` | Default AI provider |
+| `model` | string | - | Default model name (passed to provider as-is) |
+| `branch_name_strategy` | `"romaji"` \| `"ai"` | `"romaji"` | Branch name generation strategy |
+| `prevent_sleep` | boolean | `false` | Prevent macOS idle sleep (caffeinate) |
+| `notification_sound` | boolean | `true` | Enable notification sounds |
+| `notification_sound_events` | object | - | Per-event notification sound toggles |
+| `concurrency` | number (1-10) | `1` | Parallel task count for `takt run` |
+| `task_poll_interval_ms` | number (100-5000) | `500` | Polling interval for new tasks |
+| `interactive_preview_movements` | number (0-10) | `3` | Movement previews in interactive mode |
+| `worktree_dir` | string | - | Directory for shared clones (defaults to `../{clone-name}`) |
+| `auto_pr` | boolean | - | Auto-create PR after worktree execution |
+| `verbose` | boolean | - | Verbose output mode |
+| `minimal_output` | boolean | `false` | Suppress AI output (for CI) |
+| `runtime` | object | - | Runtime environment defaults (e.g., `prepare: [gradle, node]`) |
+| `persona_providers` | object | - | Per-persona provider overrides (e.g., `coder: codex`) |
+| `provider_options` | object | - | Global provider-specific options |
+| `provider_profiles` | object | - | Provider-specific permission profiles |
+| `anthropic_api_key` | string | - | Anthropic API key for Claude |
+| `openai_api_key` | string | - | OpenAI API key for Codex |
+| `opencode_api_key` | string | - | OpenCode API key |
+| `codex_cli_path` | string | - | Codex CLI binary path override (absolute) |
+| `enable_builtin_pieces` | boolean | `true` | Enable builtin pieces |
+| `disabled_builtins` | string[] | `[]` | Specific builtin pieces to disable |
+| `pipeline` | object | - | Pipeline template settings |
+| `bookmarks_file` | string | - | Path to bookmarks file |
+| `piece_categories_file` | string | - | Path to piece categories file |
+
+## Project Configuration
+
+Configure project-specific settings in `.takt/config.yaml`. This file is created when you first use TAKT in a project directory.
+
+```yaml
+# .takt/config.yaml
+piece: default                # Current piece for this project
+provider: claude              # Override provider for this project
+auto_pr: true                 # Auto-create PR after worktree execution
+verbose: false                # Verbose output mode
+
+# Provider-specific options (overrides global, overridden by piece/movement)
+# provider_options:
+#   codex:
+#     network_access: true
+
+# Provider-specific permission profiles (project-level override)
+# provider_profiles:
+#   codex:
+#     default_permission_mode: full
+#     movement_permission_overrides:
+#       ai_review: readonly
+```
+
+### Project Config Field Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `piece` | string | `"default"` | Current piece name for this project |
+| `provider` | `"claude"` \| `"codex"` \| `"opencode"` \| `"mock"` | - | Override provider |
+| `auto_pr` | boolean | - | Auto-create PR after worktree execution |
+| `verbose` | boolean | - | Verbose output mode |
+| `provider_options` | object | - | Provider-specific options |
+| `provider_profiles` | object | - | Provider-specific permission profiles |
+
+Project config values override global config when both are set.
+
+## API Key Configuration
+
+TAKT supports three providers, each with its own API key. API keys can be configured via environment variables or `~/.takt/config.yaml`.
+
+### Environment Variables (Recommended)
+
+```bash
+# For Claude (Anthropic)
+export TAKT_ANTHROPIC_API_KEY=sk-ant-...
+
+# For Codex (OpenAI)
+export TAKT_OPENAI_API_KEY=sk-...
+
+# For OpenCode
+export TAKT_OPENCODE_API_KEY=...
+```
+
+### Config File
+
+```yaml
+# ~/.takt/config.yaml
+anthropic_api_key: sk-ant-...  # For Claude
+openai_api_key: sk-...         # For Codex
+opencode_api_key: ...          # For OpenCode
+```
+
+### Priority
+
+Environment variables take precedence over `config.yaml` settings.
+
+| Provider | Environment Variable | Config Key |
+|----------|---------------------|------------|
+| Claude (Anthropic) | `TAKT_ANTHROPIC_API_KEY` | `anthropic_api_key` |
+| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` |
+| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` |
+
+### Security
+
+- If you write API keys in `config.yaml`, be careful not to commit this file to Git.
+- Consider using environment variables instead.
+- Add `~/.takt/config.yaml` to your global `.gitignore` if needed.
+- If you set an API key, installing the corresponding CLI tool (Claude Code, Codex, OpenCode) is not necessary. TAKT directly calls the respective API.
+
+### Codex CLI Path Override
+
+You can override the Codex CLI binary path using either an environment variable or config:
+
+```bash
+export TAKT_CODEX_CLI_PATH=/usr/local/bin/codex
+```
+
+```yaml
+# ~/.takt/config.yaml
+codex_cli_path: /usr/local/bin/codex
+```
+
+The path must be an absolute path to an executable file. `TAKT_CODEX_CLI_PATH` takes precedence over the config file value.
+
+## Model Resolution
+
+The model used for each movement is resolved with the following priority order (highest first):
+
+1. **Piece movement `model`** - Specified in the movement definition in piece 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 the provider's built-in default (Claude: `sonnet`, Codex: `codex`, OpenCode: provider default)
+
+### Provider-specific Model Notes
+
+**Claude Code** supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). The `model` field is passed directly to the provider CLI. Refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models.
+
+**Codex** uses the model string as-is via the Codex SDK. If unspecified, defaults to `codex`. Refer to Codex documentation for available models.
+
+**OpenCode** requires a model in `provider/model` format (e.g., `opencode/big-pickle`). Omitting the model for the OpenCode provider will result in a configuration error.
+
+### Example
+
+```yaml
+# ~/.takt/config.yaml
+provider: claude
+model: opus     # Default model for all movements (unless overridden)
+```
+
+```yaml
+# piece.yaml - movement-level override takes highest priority
+movements:
+  - name: plan
+    model: opus       # This movement uses opus regardless of global config
+    ...
+  - name: implement
+    # No model specified - falls back to global config (opus)
+    ...
+```
+
+## Provider Profiles
+
+Provider profiles allow you to set default permission modes and per-movement permission overrides for each provider. This is useful when running different providers with different security postures.
+
+### Permission Modes
+
+TAKT uses three provider-independent permission modes:
+
+| Mode | Description | Claude | Codex | OpenCode |
+|------|-------------|--------|-------|----------|
+| `readonly` | Read-only access, no file modifications | `default` | `read-only` | `read-only` |
+| `edit` | Allow file edits with confirmation | `acceptEdits` | `workspace-write` | `workspace-write` |
+| `full` | Bypass all permission checks | `bypassPermissions` | `danger-full-access` | `danger-full-access` |
+
+### Configuration
+
+Provider profiles can be set at both global and project levels:
+
+```yaml
+# ~/.takt/config.yaml (global) or .takt/config.yaml (project)
+provider_profiles:
+  codex:
+    default_permission_mode: full
+    movement_permission_overrides:
+      ai_review: readonly
+  claude:
+    default_permission_mode: edit
+    movement_permission_overrides:
+      implement: full
+```
+
+### Permission Resolution Priority
+
+Permission mode is resolved in the following order (first match wins):
+
+1. **Project** `provider_profiles.<provider>.movement_permission_overrides.<movement>`
+2. **Global** `provider_profiles.<provider>.movement_permission_overrides.<movement>`
+3. **Project** `provider_profiles.<provider>.default_permission_mode`
+4. **Global** `provider_profiles.<provider>.default_permission_mode`
+5. **Movement** `required_permission_mode` (acts as a minimum floor)
+
+The `required_permission_mode` on a movement sets the minimum floor. If the resolved mode from provider profiles is lower than the required mode, the required mode is used instead. For example, if a movement requires `edit` but the profile resolves to `readonly`, the effective mode will be `edit`.
+
+### Persona Providers
+
+Route specific personas to different providers without duplicating pieces:
+
+```yaml
+# ~/.takt/config.yaml
+persona_providers:
+  coder: codex             # Run coder persona on Codex
+  ai-antipattern-reviewer: claude  # Keep reviewers on Claude
+```
+
+This allows mixing providers within a single piece. The persona name is matched against the `persona` key in the movement definition.
+
+## Piece Categories
+
+Organize pieces into categories for better UI presentation in `takt switch` and piece selection prompts.
+
+### Configuration
+
+Categories can be configured in:
+- `builtins/{lang}/piece-categories.yaml` - Default builtin categories
+- `~/.takt/config.yaml` or a separate categories file specified by `piece_categories_file`
+
+```yaml
+# ~/.takt/config.yaml or dedicated categories file
+piece_categories:
+  Development:
+    pieces: [default, simple]
+    children:
+      Backend:
+        pieces: [expert-cqrs]
+      Frontend:
+        pieces: [expert]
+  Research:
+    pieces: [research, magi]
+
+show_others_category: true         # Show uncategorized pieces (default: true)
+others_category_name: "Other Pieces"  # Name for uncategorized category
+```
+
+### Category Features
+
+- **Nested categories** - Unlimited depth for hierarchical organization
+- **Per-category piece lists** - Assign pieces to specific categories
+- **Others category** - Automatically collects uncategorized pieces (can be disabled via `show_others_category: false`)
+- **Builtin piece filtering** - Disable all builtins via `enable_builtin_pieces: false`, or selectively via `disabled_builtins: [name1, name2]`
+
+### Resetting Categories
+
+Reset piece categories to builtin defaults:
+
+```bash
+takt reset categories
+```
+
+## Pipeline Templates
+
+Pipeline mode (`--pipeline`) supports customizable templates for branch names, commit messages, and PR bodies.
+
+### Configuration
+
+```yaml
+# ~/.takt/config.yaml
+pipeline:
+  default_branch_prefix: "takt/"
+  commit_message_template: "feat: {title} (#{issue})"
+  pr_body_template: |
+    ## Summary
+    {issue_body}
+    Closes #{issue}
+```
+
+### Template Variables
+
+| Variable | Available In | Description |
+|----------|-------------|-------------|
+| `{title}` | Commit message | Issue title |
+| `{issue}` | Commit message, PR body | Issue number |
+| `{issue_body}` | PR body | Issue body |
+| `{report}` | PR body | Piece execution report |
+
+### Pipeline CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--pipeline` | Enable pipeline (non-interactive) mode |
+| `--auto-pr` | Create PR after execution |
+| `--skip-git` | Skip branch creation, commit, and push (piece-only) |
+| `--repo <owner/repo>` | Repository for PR creation |
+| `-q, --quiet` | Minimal output mode (suppress AI output) |
+
+## Debugging
+
+### Debug Logging
+
+Enable debug logging by setting `debug_enabled: true` in `~/.takt/config.yaml` or by creating a `.takt/debug.yaml` file:
+
+```yaml
+# .takt/debug.yaml
+enabled: true
+```
+
+Debug logs are written to `.takt/logs/debug.log` in NDJSON format.
+
+### Verbose Mode
+
+Create an empty `.takt/verbose` file to enable verbose console output. This automatically enables debug logging.
+
+Alternatively, set `verbose: true` in your config:
+
+```yaml
+# ~/.takt/config.yaml or .takt/config.yaml
+verbose: true
+```

docs/task-management.ja.md

@@ -0,0 +1,323 @@
+[English](./task-management.md)
+
+# タスク管理
+
+## 概要
+
+TAKT は複数のタスクを蓄積してバッチ実行するためのタスク管理ワークフローを提供します。基本的な流れは次の通りです。
+
+1. **`takt add`** -- AI との会話でタスク要件を精緻化し、`.takt/tasks.yaml` に保存
+2. **タスクの蓄積** -- `order.md` ファイルを編集し、参考資料を添付
+3. **`takt run`** -- すべての pending タスクを一括実行（逐次または並列）
+4. **`takt list`** -- 結果を確認し、ブランチのマージ、失敗のリトライ、指示の追加
+
+各タスクは隔離された共有クローン（オプション）で実行され、レポートを生成し、`takt list` でマージまたは破棄できるブランチを作成します。
+
+## タスクの追加（`takt add`）
+
+`takt add` を使用して `.takt/tasks.yaml` に新しいタスクエントリを作成します。
+
+```bash
+# インラインテキストでタスクを追加
+takt add "Implement user authentication"
+
+# GitHub Issue からタスクを追加
+takt add #28
+```
+
+タスク追加時に次の項目を確認されます。
+
+- **Piece** -- 実行に使用する piece（ワークフロー）
+- **Worktree パス** -- 隔離クローンの作成場所（Enter で自動、またはパスを指定）
+- **ブランチ名** -- カスタムブランチ名（Enter で `takt/{timestamp}-{slug}` が自動生成）
+- **Auto-PR** -- 実行成功後に PR を自動作成するかどうか
+
+### GitHub Issue 連携
+
+Issue 参照（例: `#28`）を渡すと、TAKT は GitHub CLI（`gh`）を介して Issue のタイトル、本文、ラベル、コメントを取得し、タスク内容として使用します。Issue 番号は `tasks.yaml` に記録され、ブランチ名にも反映されます。
+
+**要件:** [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ、認証済みである必要があります。
+
+### インタラクティブモードからのタスク保存
+
+インタラクティブモードからもタスクを保存できます。会話で要件を精緻化した後、`/save`（またはプロンプト時の save アクション）を使用して、即座に実行する代わりに `tasks.yaml` にタスクを永続化できます。
+
+## タスクディレクトリ形式
+
+TAKT はタスクのメタデータを `.takt/tasks.yaml` に、各タスクの詳細仕様を `.takt/tasks/{slug}/` に保存します。
+
+### `tasks.yaml` スキーマ
+
+```yaml
+tasks:
+  - name: add-auth-feature
+    status: pending
+    task_dir: .takt/tasks/20260201-015714-foptng
+    piece: default
+    created_at: "2026-02-01T01:57:14.000Z"
+    started_at: null
+    completed_at: null
+```
+
+フィールドの説明は次の通りです。
+
+| フィールド | 説明 |
+|-----------|------|
+| `name` | AI が生成したタスクスラグ |
+| `status` | `pending`、`running`、`completed`、または `failed` |
+| `task_dir` | `order.md` を含むタスクディレクトリのパス |
+| `piece` | 実行に使用する piece 名 |
+| `worktree` | `true`（自動）、パス文字列、または省略（カレントディレクトリで実行） |
+| `branch` | ブランチ名（省略時は自動生成） |
+| `auto_pr` | 実行後に PR を自動作成するかどうか |
+| `issue` | GitHub Issue 番号（該当する場合） |
+| `created_at` | ISO 8601 タイムスタンプ |
+| `started_at` | ISO 8601 タイムスタンプ（実行開始時に設定） |
+| `completed_at` | ISO 8601 タイムスタンプ（実行完了時に設定） |
+
+### タスクディレクトリのレイアウト
+
+```text
+.takt/
+  tasks/
+    20260201-015714-foptng/
+      order.md          # タスク仕様（自動生成、編集可能）
+      schema.sql        # 添付の参考資料（任意）
+      wireframe.png     # 添付の参考資料（任意）
+  tasks.yaml            # タスクメタデータレコード
+  runs/
+    20260201-015714-foptng/
+      reports/           # 実行レポート（自動生成）
+      logs/              # NDJSON セッションログ
+      context/           # スナップショット（previous_responses など）
+      meta.json          # 実行メタデータ
+```
+
+`takt add` は `.takt/tasks/{slug}/order.md` を自動作成し、`task_dir` への参照を `tasks.yaml` に保存します。実行前に `order.md` を自由に編集したり、タスクディレクトリに補足ファイル（SQL スキーマ、ワイヤーフレーム、API 仕様など）を追加したりできます。
+
+## タスクの実行（`takt run`）
+
+`.takt/tasks.yaml` のすべての pending タスクを実行します。
+
+```bash
+takt run
+```
+
+`run` コマンドは pending タスクを取得して、設定された piece を通じて実行します。各タスクは次の処理を経ます。
+
+1. クローン作成（`worktree` が設定されている場合）
+2. クローン/プロジェクトディレクトリでの piece 実行
+3. 自動コミットとプッシュ（worktree 実行の場合）
+4. 実行後フロー（`auto_pr` 設定時は PR 作成）
+5. `tasks.yaml` のステータス更新（`completed` または `failed`）
+
+### 並列実行（Concurrency）
+
+デフォルトではタスクは逐次実行されます（`concurrency: 1`）。`~/.takt/config.yaml` で並列実行を設定できます。
+
+```yaml
+concurrency: 3              # 最大3タスクを並列実行（1-10）
+task_poll_interval_ms: 500   # 新規タスクのポーリング間隔（100-5000ms）
+```
+
+concurrency が 1 より大きい場合、TAKT はワーカープールを使用して次のように動作します。
+
+- 最大 N タスクを同時実行
+- 設定された間隔で新規タスクをポーリング
+- ワーカーが空き次第、新しいタスクを取得
+- タスクごとに色分けされたプレフィックス付き出力で読みやすさを確保
+- Ctrl+C でのグレースフルシャットダウン（実行中タスクの完了を待機）
+
+### 中断されたタスクの復旧
+
+`takt run` が中断された場合（プロセスクラッシュ、Ctrl+C など）、`running` ステータスのまま残ったタスクは次回の `takt run` または `takt watch` 起動時に自動的に `pending` に復旧されます。
+
+## タスクの監視（`takt watch`）
+
+`.takt/tasks.yaml` を監視し、タスクが追加されると自動実行する常駐プロセスを起動します。
+
+```bash
+takt watch
+```
+
+watch コマンドの動作は次の通りです。
+
+- Ctrl+C（SIGINT）まで実行を継続
+- `tasks.yaml` の新しい `pending` タスクを監視
+- タスクが現れるたびに実行
+- 起動時に中断された `running` タスクを復旧
+- 終了時に合計/成功/失敗タスク数のサマリを表示
+
+これは「プロデューサー-コンシューマー」ワークフローに便利です。一方のターミナルで `takt add` でタスクを追加し、もう一方で `takt watch` がそれらを自動実行します。
+
+## タスクブランチの管理（`takt list`）
+
+タスクブランチの一覧表示とインタラクティブな管理を行います。
+
+```bash
+takt list
+```
+
+リストビューでは、すべてのタスクがステータス別（pending、running、completed、failed）に作成日とサマリ付きで表示されます。タスクを選択すると、そのステータスに応じた操作が表示されます。
+
+### 完了タスクの操作
+
+| 操作 | 説明 |
+|------|------|
+| **View diff** | デフォルトブランチとの差分をページャで表示 |
+| **Instruct** | AI との会話で追加指示を作成し、再実行 |
+| **Try merge** | スカッシュマージ（コミットせずにステージング、手動レビュー用） |
+| **Merge & cleanup** | スカッシュマージしてブランチを削除 |
+| **Delete** | すべての変更を破棄してブランチを削除 |
+
+### 失敗タスクの操作
+
+| 操作 | 説明 |
+|------|------|
+| **Retry** | 失敗コンテキスト付きのリトライ会話を開き、再実行 |
+| **Delete** | 失敗したタスクレコードを削除 |
+
+### Pending タスクの操作
+
+| 操作 | 説明 |
+|------|------|
+| **Delete** | `tasks.yaml` から pending タスクを削除 |
+
+### Instruct モード
+
+完了タスクで **Instruct** を選択すると、TAKT は AI とのインタラクティブな会話ループを開きます。会話には次の情報がプリロードされます。
+
+- ブランチコンテキスト（デフォルトブランチとの差分統計、コミット履歴）
+- 前回の実行セッションデータ（movement ログ、レポート）
+- Piece 構造と movement プレビュー
+- 前回の order 内容
+
+どのような追加変更が必要かを議論し、AI が指示の精緻化を支援します。準備ができたら次の操作を選択できます。
+
+- **Execute** -- 新しい指示でタスクを即座に再実行
+- **Save task** -- 新しい指示でタスクを `pending` として再キューイングし、後で実行
+- **Cancel** -- 破棄してリストに戻る
+
+### Retry モード
+
+失敗タスクで **Retry** を選択すると、TAKT は次の処理を行います。
+
+1. 失敗の詳細を表示（失敗した movement、エラーメッセージ、最後のエージェントメッセージ）
+2. Piece の選択を促す
+3. どの movement から開始するかの選択を促す（デフォルトは失敗した movement）
+4. 失敗コンテキスト、実行セッションデータ、piece 構造がプリロードされたリトライ会話を開く
+5. AI の支援で指示を精緻化
+
+リトライ会話は Instruct モードと同じ操作（実行、タスク保存、キャンセル）をサポートします。リトライのメモは複数のリトライ試行にわたってタスクレコードに蓄積されます。
+
+### 非インタラクティブモード（`--non-interactive`）
+
+CI/CD スクリプト向けの非インタラクティブモードを使用できます。
+
+```bash
+# すべてのタスクをテキストで一覧表示
+takt list --non-interactive
+
+# すべてのタスクを JSON で一覧表示
+takt list --non-interactive --format json
+
+# 特定ブランチの差分統計を表示
+takt list --non-interactive --action diff --branch takt/my-branch
+
+# 特定ブランチをマージ
+takt list --non-interactive --action merge --branch takt/my-branch
+
+# ブランチを削除（--yes が必要）
+takt list --non-interactive --action delete --branch takt/my-branch --yes
+
+# Try merge（コミットせずにステージング）
+takt list --non-interactive --action try --branch takt/my-branch
+```
+
+利用可能なアクションは `diff`、`try`、`merge`、`delete` です。
+
+## タスクディレクトリワークフロー
+
+推奨されるエンドツーエンドのワークフローは次の通りです。
+
+1. **`takt add`** -- タスクを作成。`.takt/tasks.yaml` に pending レコードが追加され、`.takt/tasks/{slug}/` に `order.md` が生成される。
+2. **`order.md` を編集** -- 生成されたファイルを開き、必要に応じて詳細な仕様、参考資料、補足ファイルを追加。
+3. **`takt run`**（または `takt watch`）-- `tasks.yaml` の pending タスクを実行。各タスクは設定された piece ワークフローを通じて実行される。
+4. **出力を確認** -- `.takt/runs/{slug}/reports/` の実行レポートを確認（slug はタスクディレクトリと一致）。
+5. **`takt list`** -- 結果を確認し、成功したブランチのマージ、失敗のリトライ、追加指示を行う。
+
+## 隔離実行（共有クローン）
+
+タスク設定で `worktree` を指定すると、各タスクは `git clone --shared` で作成された隔離クローン内で実行され、メインの作業ディレクトリをクリーンに保ちます。
+
+### 設定オプション
+
+| 設定 | 説明 |
+|------|------|
+| `worktree: true` | 隣接ディレクトリ（または `worktree_dir` 設定で指定した場所）に共有クローンを自動作成 |
+| `worktree: "/path/to/dir"` | 指定パスにクローンを作成 |
+| `branch: "feat/xxx"` | 指定ブランチを使用（省略時は `takt/{timestamp}-{slug}` が自動生成） |
+| *(worktree を省略)* | カレントディレクトリで実行（デフォルト） |
+
+### 仕組み
+
+TAKT は `git worktree` の代わりに `git clone --shared` を使用して、独立した `.git` ディレクトリを持つ軽量クローンを作成します。これが重要な理由は次の通りです。
+
+- **独立した `.git`**: 共有クローンは独自の `.git` ディレクトリを持ち、エージェントツール（Claude Code など）が `gitdir:` 参照をたどってメインリポジトリに戻ることを防ぎます。
+- **完全な隔離**: エージェントはクローンディレクトリ内でのみ作業し、メインリポジトリを認識しません。
+
+> **注意**: YAML フィールド名は後方互換性のため `worktree` のままです。内部的には `git worktree` ではなく `git clone --shared` を使用しています。
+
+### エフェメラルなライフサイクル
+
+クローンはエフェメラルなライフサイクルに従います。
+
+1. **作成** -- タスク実行前にクローンを作成
+2. **実行** -- クローンディレクトリ内でタスクを実行
+3. **コミット & プッシュ** -- 成功時に変更を自動コミットしてブランチにプッシュ
+4. **保持** -- 実行後もクローンを保持（instruct/retry 操作用）
+5. **クリーンアップ** -- ブランチが永続的な成果物。`takt list` でマージまたは削除
+
+### デュアルワーキングディレクトリ
+
+worktree 実行中、TAKT は2つのディレクトリ参照を管理します。
+
+| ディレクトリ | 用途 |
+|------------|------|
+| `cwd`（クローンパス） | エージェントの実行場所、レポートの書き込み先 |
+| `projectCwd`（プロジェクトルート） | ログとセッションデータの保存先 |
+
+レポートは `cwd/.takt/runs/{slug}/reports/`（クローン内）に書き込まれ、エージェントがメインリポジトリのパスを発見することを防ぎます。`cwd !== projectCwd` の場合、クロスディレクトリ汚染を避けるためセッション再開はスキップされます。
+
+## セッションログ
+
+TAKT は NDJSON（改行区切り JSON、`.jsonl`）形式でセッションログを書き込みます。各レコードはアトミックに追加されるため、プロセスがクラッシュしても部分的なログは保存されます。
+
+### ログの場所
+
+```text
+.takt/runs/{slug}/
+  logs/{sessionId}.jsonl   # piece 実行ごとの NDJSON セッションログ
+  meta.json                # 実行メタデータ（タスク、piece、開始/終了、ステータスなど）
+  context/
+    previous_responses/
+      latest.md            # 最新の previous response（自動継承）
+```
+
+### レコードタイプ
+
+| レコードタイプ | 説明 |
+|--------------|------|
+| `piece_start` | タスクと piece 名による piece の初期化 |
+| `step_start` | Movement の実行開始 |
+| `step_complete` | ステータス、内容、マッチしたルール情報を含む movement 結果 |
+| `piece_complete` | Piece の正常完了 |
+| `piece_abort` | 理由を伴う中断 |
+
+### リアルタイム監視
+
+実行中にログをリアルタイムで監視できます。
+
+```bash
+tail -f .takt/runs/{slug}/logs/{sessionId}.jsonl
+```

docs/task-management.md

@@ -0,0 +1,323 @@
+[日本語](./task-management.ja.md)
+
+# Task Management
+
+## Overview
+
+TAKT provides a task management workflow for accumulating multiple tasks and executing them in batch. The basic flow is:
+
+1. **`takt add`** -- Refine task requirements through AI conversation and save to `.takt/tasks.yaml`
+2. **Tasks accumulate** -- Edit `order.md` files, attach reference materials
+3. **`takt run`** -- Execute all pending tasks at once (sequential or parallel)
+4. **`takt list`** -- Review results, merge branches, retry failures, or add instructions
+
+Each task executes in an isolated shared clone (optional), produces reports, and creates a branch that can be merged or discarded via `takt list`.
+
+## Adding Tasks (`takt add`)
+
+Use `takt add` to create a new task entry in `.takt/tasks.yaml`.
+
+```bash
+# Add a task with inline text
+takt add "Implement user authentication"
+
+# Add a task from a GitHub Issue
+takt add #28
+```
+
+When adding a task, you are prompted for:
+
+- **Piece** -- Which piece (workflow) to use for execution
+- **Worktree path** -- Where to create the isolated clone (Enter for auto, or specify a path)
+- **Branch name** -- Custom branch name (Enter for auto-generated `takt/{timestamp}-{slug}`)
+- **Auto-PR** -- Whether to automatically create a pull request after successful execution
+
+### GitHub Issue Integration
+
+When you pass an issue reference (e.g., `#28`), TAKT fetches the issue title, body, labels, and comments via the GitHub CLI (`gh`) and uses them as the task content. The issue number is recorded in `tasks.yaml` and reflected in the branch name.
+
+**Requirement:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
+
+### Saving Tasks from Interactive Mode
+
+You can also save tasks from interactive mode. After refining requirements through conversation, use `/save` (or the save action when prompted) to persist the task to `tasks.yaml` instead of executing immediately.
+
+## Task Directory Format
+
+TAKT stores task metadata in `.takt/tasks.yaml` and each task's detailed specification in `.takt/tasks/{slug}/`.
+
+### `tasks.yaml` Schema
+
+```yaml
+tasks:
+  - name: add-auth-feature
+    status: pending
+    task_dir: .takt/tasks/20260201-015714-foptng
+    piece: default
+    created_at: "2026-02-01T01:57:14.000Z"
+    started_at: null
+    completed_at: null
+```
+
+Fields:
+
+| Field | Description |
+|-------|-------------|
+| `name` | AI-generated task slug |
+| `status` | `pending`, `running`, `completed`, or `failed` |
+| `task_dir` | Path to the task directory containing `order.md` |
+| `piece` | Piece name to use for execution |
+| `worktree` | `true` (auto), a path string, or omitted (run in current directory) |
+| `branch` | Branch name (auto-generated if omitted) |
+| `auto_pr` | Whether to auto-create a PR after execution |
+| `issue` | GitHub Issue number (if applicable) |
+| `created_at` | ISO 8601 timestamp |
+| `started_at` | ISO 8601 timestamp (set when execution begins) |
+| `completed_at` | ISO 8601 timestamp (set when execution finishes) |
+
+### Task Directory Layout
+
+```text
+.takt/
+  tasks/
+    20260201-015714-foptng/
+      order.md          # Task specification (auto-generated, editable)
+      schema.sql        # Attached reference materials (optional)
+      wireframe.png     # Attached reference materials (optional)
+  tasks.yaml            # Task metadata records
+  runs/
+    20260201-015714-foptng/
+      reports/           # Execution reports (auto-generated)
+      logs/              # NDJSON session logs
+      context/           # Snapshots (previous_responses, etc.)
+      meta.json          # Run metadata
+```
+
+`takt add` creates `.takt/tasks/{slug}/order.md` automatically and saves the `task_dir` reference to `tasks.yaml`. You can freely edit `order.md` and add supplementary files (SQL schemas, wireframes, API specs, etc.) to the task directory before execution.
+
+## Executing Tasks (`takt run`)
+
+Execute all pending tasks from `.takt/tasks.yaml`:
+
+```bash
+takt run
+```
+
+The `run` command claims pending tasks and executes them through the configured piece. Each task goes through:
+
+1. Clone creation (if `worktree` is set)
+2. Piece execution in the clone/project directory
+3. Auto-commit and push (if worktree execution)
+4. Post-execution flow (PR creation if `auto_pr` is set)
+5. Status update in `tasks.yaml` (`completed` or `failed`)
+
+### Parallel Execution (Concurrency)
+
+By default, tasks run sequentially (`concurrency: 1`). Configure parallel execution in `~/.takt/config.yaml`:
+
+```yaml
+concurrency: 3              # Run up to 3 tasks in parallel (1-10)
+task_poll_interval_ms: 500   # Polling interval for new tasks (100-5000ms)
+```
+
+When concurrency is greater than 1, TAKT uses a worker pool that:
+
+- Runs up to N tasks simultaneously
+- Polls for newly added tasks at the configured interval
+- Picks up new tasks as workers become available
+- Displays color-coded prefixed output per task for readability
+- Supports graceful shutdown on Ctrl+C (waits for in-flight tasks to complete)
+
+### Interrupted Task Recovery
+
+If `takt run` is interrupted (e.g., process crash, Ctrl+C), tasks left in `running` status are automatically recovered to `pending` on the next `takt run` or `takt watch` invocation.
+
+## Watching Tasks (`takt watch`)
+
+Run a resident process that monitors `.takt/tasks.yaml` and auto-executes tasks as they appear:
+
+```bash
+takt watch
+```
+
+The watch command:
+
+- Stays running until Ctrl+C (SIGINT)
+- Monitors `tasks.yaml` for new `pending` tasks
+- Executes each task as it appears
+- Recovers interrupted `running` tasks on startup
+- Displays a summary of total/success/failed tasks on exit
+
+This is useful for a "producer-consumer" workflow where you add tasks with `takt add` in one terminal and let `takt watch` execute them automatically in another.
+
+## Managing Task Branches (`takt list`)
+
+List and manage task branches interactively:
+
+```bash
+takt list
+```
+
+The list view shows all tasks organized by status (pending, running, completed, failed) with creation dates and summaries. Selecting a task shows available actions depending on its status.
+
+### Actions for Completed Tasks
+
+| Action | Description |
+|--------|-------------|
+| **View diff** | Show full diff against the default branch in a pager |
+| **Instruct** | Open an AI conversation to craft additional instructions, then re-execute |
+| **Try merge** | Squash merge (stages changes without committing, for manual review) |
+| **Merge & cleanup** | Squash merge and delete the branch |
+| **Delete** | Discard all changes and delete the branch |
+
+### Actions for Failed Tasks
+
+| Action | Description |
+|--------|-------------|
+| **Retry** | Open a retry conversation with failure context, then re-execute |
+| **Delete** | Remove the failed task record |
+
+### Actions for Pending Tasks
+
+| Action | Description |
+|--------|-------------|
+| **Delete** | Remove the pending task from `tasks.yaml` |
+
+### Instruct Mode
+
+When you select **Instruct** on a completed task, TAKT opens an interactive conversation loop with the AI. The conversation is pre-loaded with:
+
+- Branch context (diff stat against default branch, commit history)
+- Previous run session data (movement logs, reports)
+- Piece structure and movement previews
+- Previous order content
+
+You can discuss what additional changes are needed, and the AI helps refine the instructions. When ready, choose:
+
+- **Execute** -- Re-execute the task immediately with the new instructions
+- **Save task** -- Requeue the task as `pending` with the new instructions for later execution
+- **Cancel** -- Discard and return to the list
+
+### Retry Mode
+
+When you select **Retry** on a failed task, TAKT:
+
+1. Displays failure details (failed movement, error message, last agent message)
+2. Prompts you to select a piece
+3. Prompts you to select which movement to start from (defaults to the failed movement)
+4. Opens a retry conversation pre-loaded with failure context, run session data, and piece structure
+5. Lets you refine instructions with AI assistance
+
+The retry conversation supports the same actions as Instruct mode (execute, save task, cancel). Retry notes are appended to the task record, accumulating across multiple retry attempts.
+
+### Non-Interactive Mode (`--non-interactive`)
+
+For CI/CD scripts, use non-interactive mode:
+
+```bash
+# List all tasks as text
+takt list --non-interactive
+
+# List all tasks as JSON
+takt list --non-interactive --format json
+
+# Show diff stat for a specific branch
+takt list --non-interactive --action diff --branch takt/my-branch
+
+# Merge a specific branch
+takt list --non-interactive --action merge --branch takt/my-branch
+
+# Delete a branch (requires --yes)
+takt list --non-interactive --action delete --branch takt/my-branch --yes
+
+# Try merge (stage without commit)
+takt list --non-interactive --action try --branch takt/my-branch
+```
+
+Available actions: `diff`, `try`, `merge`, `delete`.
+
+## Task Directory Workflow
+
+The recommended end-to-end workflow:
+
+1. **`takt add`** -- Create a task. A pending record is added to `.takt/tasks.yaml` and `order.md` is generated in `.takt/tasks/{slug}/`.
+2. **Edit `order.md`** -- Open the generated file and add detailed specifications, reference materials, or supplementary files as needed.
+3. **`takt run`** (or `takt watch`) -- Execute pending tasks from `tasks.yaml`. Each task runs through the configured piece workflow.
+4. **Verify outputs** -- Check execution reports in `.takt/runs/{slug}/reports/` (the slug matches the task directory).
+5. **`takt list`** -- Review results, merge successful branches, retry failures, or add further instructions.
+
+## Isolated Execution (Shared Clone)
+
+Specifying `worktree` in task configuration executes each task in an isolated clone created with `git clone --shared`, keeping your main working directory clean.
+
+### Configuration Options
+
+| Setting | Description |
+|---------|-------------|
+| `worktree: true` | Auto-create shared clone in adjacent directory (or location specified by `worktree_dir` config) |
+| `worktree: "/path/to/dir"` | Create clone at the specified path |
+| `branch: "feat/xxx"` | Use specified branch (auto-generated as `takt/{timestamp}-{slug}` if omitted) |
+| *(omit `worktree`)* | Execute in current directory (default) |
+
+### How It Works
+
+TAKT uses `git clone --shared` instead of `git worktree` to create lightweight clones with an independent `.git` directory. This is important because:
+
+- **Independent `.git`**: Shared clones have their own `.git` directory, preventing agent tools (like Claude Code) from traversing `gitdir:` references back to the main repository.
+- **Full isolation**: Agents work entirely within the clone directory, unaware of the main repository.
+
+> **Note**: The YAML field name remains `worktree` for backward compatibility. Internally, it uses `git clone --shared` instead of `git worktree`.
+
+### Ephemeral Lifecycle
+
+Clones follow an ephemeral lifecycle:
+
+1. **Create** -- Clone is created before task execution
+2. **Execute** -- Task runs inside the clone directory
+3. **Commit & Push** -- On success, changes are auto-committed and pushed to the branch
+4. **Preserve** -- Clone is preserved after execution (for instruct/retry operations)
+5. **Cleanup** -- Branches are the persistent artifacts; use `takt list` to merge or delete
+
+### Dual Working Directory
+
+During worktree execution, TAKT maintains two directory references:
+
+| Directory | Purpose |
+|-----------|---------|
+| `cwd` (clone path) | Where agents run, where reports are written |
+| `projectCwd` (project root) | Where logs and session data are stored |
+
+Reports are written to `cwd/.takt/runs/{slug}/reports/` (inside the clone) to prevent agents from discovering the main repository path. Session resume is skipped when `cwd !== projectCwd` to avoid cross-directory contamination.
+
+## Session Logs
+
+TAKT writes session logs in NDJSON (Newline-Delimited JSON, `.jsonl`) format. Each record is atomically appended, so partial logs are preserved even if the process crashes.
+
+### Log Location
+
+```text
+.takt/runs/{slug}/
+  logs/{sessionId}.jsonl   # NDJSON session log per piece execution
+  meta.json                # Run metadata (task, piece, start/end, status, etc.)
+  context/
+    previous_responses/
+      latest.md            # Latest previous response (inherited automatically)
+```
+
+### Record Types
+
+| Record Type | Description |
+|-------------|-------------|
+| `piece_start` | Piece initialization with task and piece name |
+| `step_start` | Movement execution start |
+| `step_complete` | Movement result with status, content, matched rule info |
+| `piece_complete` | Successful piece completion |
+| `piece_abort` | Abort with reason |
+
+### Real-Time Monitoring
+
+You can monitor logs in real-time during execution:
+
+```bash
+tail -f .takt/runs/{slug}/logs/{sessionId}.jsonl
+```