From 44032910460b1f749cdfac33069293df8454b2e2 Mon Sep 17 00:00:00 2001 From: nrslib <38722970+nrslib@users.noreply.github.com> Date: Thu, 29 Jan 2026 15:44:27 +0900 Subject: [PATCH] =?UTF-8?q?README=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 64 ++++++++--- docs/README.ja.md | 108 +++++++++++++----- resources/global/en/agents/default/coder.md | 2 + resources/global/en/agents/default/planner.md | 15 ++- resources/global/ja/agents/default/coder.md | 2 + resources/global/ja/agents/default/planner.md | 15 ++- 6 files changed, 159 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index a48f4f7..4c4a432 100644 --- a/README.md +++ b/README.md @@ -42,20 +42,58 @@ takt /list-tasks takt /switch ``` +### What happens when you run a task + +When you run `takt "Add a login feature"`, TAKT guides you through an interactive flow: + +**1. Workflow selection** + +``` +Select workflow: + (↑↓ to move, Enter to select) + + ❯ default (current) (default) + expert + expert-cqrs + magi + research + simple + Cancel +``` + +**2. Isolated clone** (optional) + +``` +? Create worktree? (y/N) +``` + +Choose `y` to run in a `git clone --shared` isolated environment, keeping your working directory clean. + +**3. Execution** — The selected workflow orchestrates multiple agents to complete the task. + +### Recommended workflows + +| Workflow | Best for | +|----------|----------| +| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with fix loops. | +| `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. | +| `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). | +| `research` | Research and investigation. Autonomous research without asking questions. | +| `magi` | Fun deliberation. Three AI personas analyze and vote (Evangelion-inspired). | + ## Commands | Command | Alias | Description | |---------|-------|-------------| -| `takt "task"` | | Execute task with current workflow (continues session) | -| `takt -r "task"` | | Execute task, resuming previous session | +| `takt "task"` | | Execute task with current workflow (session auto-continued) | | `takt /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` | | `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) | | `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) | | `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) | -| `takt /switch` | | Switch workflow interactively | +| `takt /switch` | `/sw` | Switch workflow interactively | | `takt /clear` | | Clear agent conversation sessions | | `takt /refresh-builtin` | | Update builtin agents/workflows to latest version | -| `takt /config` | | Display current configuration | +| `takt /config` | | Configure permission mode | | `takt /help` | | Show help | ## Workflows @@ -112,6 +150,7 @@ TAKT ships with several built-in workflows: | `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. | | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. | Switch between workflows with `takt /switch`. @@ -186,6 +225,7 @@ Available Codex models: ├── tasks/ # Pending task files (.yaml, .md) ├── completed/ # Completed tasks with reports ├── worktree-meta/ # Metadata for task branches +├── worktree-sessions/ # Per-clone agent session storage ├── reports/ # Execution reports (auto-generated) └── logs/ # Session logs (incremental) ├── latest.json # Pointer to current/latest session @@ -217,20 +257,6 @@ trusted_directories: ## Practical Usage Guide -### Resuming Sessions with `-r` - -When TAKT prompts for additional input during execution (e.g., "Please provide more details"), use the `-r` flag to continue the conversation: - -```bash -# First run - agent might ask for clarification -takt "Fix the login bug" - -# Resume the same session to provide the requested information -takt -r "The bug occurs when the password contains special characters" -``` - -The `-r` flag preserves the agent's conversation history, allowing for natural back-and-forth interaction. - ### Interactive Workflow When running `takt "task"`, you are prompted to: @@ -396,7 +422,7 @@ TAKT writes session logs incrementally to `.takt/logs/`. Logs are saved at workf - `.takt/logs/previous.json` - Pointer to the previous session - `.takt/logs/{sessionId}.json` - Full session log with step history -Agents can read `previous.json` to pick up context from a prior run (e.g., when resuming with `takt "続けて"`). +Agents can read `previous.json` to pick up context from a prior run. Session continuity is automatic — simply run `takt "task"` to continue where the previous session left off. ### Workflow Variables diff --git a/docs/README.ja.md b/docs/README.ja.md index a0f0b79..5082aea 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -31,40 +31,68 @@ takt /run-tasks # タスクを監視して自動実行 takt /watch +# タスクブランチ一覧（マージ・削除） +takt /list-tasks + # ワークフローを切り替え takt /switch ``` -## コマンド一覧 +### タスク実行の流れ -| コマンド | 説明 | -|---------|------| -| `takt "タスク"` | 現在のワークフローでタスクを実行（セッション継続） | -| `takt -r "タスク"` | 前回のセッションを再開してタスクを実行 | -| `takt /run-tasks` | `.takt/tasks/` の保留中タスクをすべて実行 | -| `takt /watch` | `.takt/tasks/` を監視してタスクを自動実行（常駐プロセス） | -| `takt /add-task` | 新しいタスクを対話的に追加（YAML形式） | -| `takt /switch` | ワークフローを対話的に切り替え | -| `takt /clear` | エージェントの会話セッションをクリア | -| `takt /refresh-builtin` | ビルトインのエージェント/ワークフローを最新版に更新 | -| `takt /config` | 現在の設定を表示 | -| `takt /help` | ヘルプを表示 | +`takt "ログイン機能を追加して"` を実行すると、以下の対話フローが表示されます： -## 実践的な使い方ガイド +**1. ワークフロー選択** -### `-r` でセッションを再開する +``` +Select workflow: + (↑↓ to move, Enter to select) -TAKTの実行中にエージェントから追加の情報を求められた場合（例：「詳細を教えてください」）、`-r`フラグを使って会話を継続できます： - -```bash -# 最初の実行 - エージェントが確認を求めることがある -takt "ログインのバグを直して" - -# 同じセッションを再開して要求された情報を提供 -takt -r "パスワードに特殊文字が含まれているとバグが発生します" + ❯ default (current) (default) + expert + expert-cqrs + magi + research + simple + Cancel ``` -`-r`フラグはエージェントの会話履歴を保持し、自然なやり取りを可能にします。 +**2. 隔離クローン作成**（オプション） + +``` +? Create worktree? (y/N) +``` + +`y` を選ぶと `git clone --shared` で隔離環境を作成し、作業ディレクトリをクリーンに保てます。 + +**3. 実行** — 選択したワークフローが複数のエージェントを連携させてタスクを完了します。 + +### おすすめワークフロー + +| ワークフロー | おすすめ用途 | +|------------|------------| +| `default` | 本格的な開発タスク。TAKT自身の開発で使用。修正ループ付きの多段階レビュー。 | +| `simple` | README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。 | +| `expert-review` / `expert-cqrs` | Web開発プロジェクト。マルチエキスパートレビュー（CQRS、フロントエンド、セキュリティ、QA）。 | +| `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 | +| `magi` | 審議システム。3つのAIペルソナが分析・投票（エヴァンゲリオン風）。 | + +## コマンド一覧 + +| コマンド | エイリアス | 説明 | +|---------|-----------|------| +| `takt "タスク"` | | 現在のワークフローでタスクを実行（セッション自動継続） | +| `takt /run-tasks` | `/run` | `.takt/tasks/` の保留中タスクをすべて実行 | +| `takt /watch` | | `.takt/tasks/` を監視してタスクを自動実行（常駐プロセス） | +| `takt /add-task` | `/add` | 新しいタスクを対話的に追加（YAML形式、複数行対応） | +| `takt /list-tasks` | `/list` | タスクブランチ一覧（マージ・削除） | +| `takt /switch` | `/sw` | ワークフローを対話的に切り替え | +| `takt /clear` | | エージェントの会話セッションをクリア | +| `takt /refresh-builtin` | | ビルトインのエージェント/ワークフローを最新版に更新 | +| `takt /config` | | パーミッションモードを設定 | +| `takt /help` | | ヘルプを表示 | + +## 実践的な使い方ガイド ### タスク管理 @@ -139,6 +167,28 @@ takt /watch - 外部プロセスがタスクを追加する自動化ワークフロー - タスクを順次キューイングする長時間の開発セッション +#### `/list-tasks` でタスクブランチを一覧表示 + +```bash +takt /list-tasks +``` + +`takt/`プレフィックスのブランチをファイル変更数とともに一覧表示します。各ブランチに対して以下の操作が可能です： +- **Try merge** - mainにスカッシュマージ（変更をステージングのみ、コミットなし） +- **Instruct** - 一時クローン経由で追加指示を与える +- **Merge & cleanup** - マージしてブランチを削除 +- **Delete** - マージせずにブランチを削除 + +### セッションログ + +TAKTはセッションログを`.takt/logs/`にインクリメンタルに書き込みます。ログはワークフロー開始時、各ステップ完了後、ワークフロー終了時に保存されるため、プロセスが途中でクラッシュしても部分的なログが保持されます。 + +- `.takt/logs/latest.json` - 現在（または最新の）セッションへのポインタ +- `.takt/logs/previous.json` - 前回セッションへのポインタ +- `.takt/logs/{sessionId}.json` - ワークフロー実行ごとの完全なセッションログ + +エージェントは`previous.json`を読み取って前回の実行コンテキストを引き継ぐことができます。セッション継続は自動的に行われます — `takt "タスク"`を実行するだけで前回のセッションから続行されます。 + ### カスタムワークフローの追加 `~/.takt/workflows/`にYAMLファイルを追加して独自のワークフローを作成できます： @@ -247,7 +297,7 @@ transitions: next_step: ABORT # ワークフローを失敗終了 ``` -使用可能な遷移条件：`done`、`blocked`、`approved`、`rejected`、`improve`、`always` +使用可能な遷移条件：`done`、`blocked`、`approved`、`rejected`、`improve`、`answer`、`always` 特殊なnext_step値：`COMPLETE`（成功）、`ABORT`（失敗） **ステップオプション：** @@ -259,6 +309,7 @@ transitions: | `allowed_tools` | - | エージェントが使用できるツール一覧（Read, Glob, Grep, Edit, Write, Bash等） | | `provider` | - | このステップのプロバイダーを上書き（`claude`または`codex`） | | `model` | - | このステップのモデルを上書き | +| `permission_mode` | `default` | パーミッションモード：`default`、`acceptEdits`、`bypassPermissions` | ## ワークフロー @@ -301,6 +352,7 @@ TAKTには複数のビルトインワークフローが同梱されています | `simple` | defaultの簡略版：計画 → 実装 → アーキテクトレビュー → AIレビュー → スーパーバイザー。中間の修正ステップなし。 | | `research` | リサーチワークフロー：プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。 | | `expert-review` | ドメインエキスパートによる包括的レビュー：CQRS+ES、フロントエンド、AI、セキュリティ、QAレビューと修正ループ。 | +| `expert-cqrs` | CQRS+ES、フロントエンド、AI、セキュリティ、QA専門のエキスパートレビュー。計画 → 実装 → マルチエキスパートレビュー → スーパーバイザー。 | | `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 | `takt /switch` でワークフローを切り替えられます。 @@ -343,8 +395,12 @@ agents: ├── tasks/ # 保留中のタスクファイル（.yaml, .md） ├── completed/ # 完了したタスクとレポート ├── worktree-meta/ # タスクブランチのメタデータ +├── worktree-sessions/ # クローンごとのエージェントセッション保存 ├── reports/ # 実行レポート（自動生成） -└── logs/ # セッションログ +└── logs/ # セッションログ（インクリメンタル） + ├── latest.json # 現在/最新セッションへのポインタ + ├── previous.json # 前回セッションへのポインタ + └── {sessionId}.json # ワークフロー実行ごとの完全なセッションログ ``` ## API使用例 diff --git a/resources/global/en/agents/default/coder.md b/resources/global/en/agents/default/coder.md index ece3074..5532167 100644 --- a/resources/global/en/agents/default/coder.md +++ b/resources/global/en/agents/default/coder.md @@ -32,6 +32,7 @@ When receiving a task, first understand the requirements precisely. - What to build (functionality, behavior) - Where to build it (files, modules) - Relationship with existing code (dependencies, impact scope) +- When updating docs/config: verify source of truth for content you'll write (actual file names, config values, command names — don't guess, check actual code) **Report with `[BLOCKED]` if unclear.** Don't proceed with guesses. @@ -90,6 +91,7 @@ Perform self-check after implementation. | Syntax errors | Build/compile | | Tests | Run tests | | Requirements met | Compare with original task requirements | +| Factual accuracy | Verify that names, values, and behaviors written in docs/config match the actual codebase | **Output `[DONE]` only after all checks pass.** diff --git a/resources/global/en/agents/default/planner.md b/resources/global/en/agents/default/planner.md index ebed782..3b6ec14 100644 --- a/resources/global/en/agents/default/planner.md +++ b/resources/global/en/agents/default/planner.md @@ -33,7 +33,20 @@ Identify the scope of changes: - Dependencies - Impact on tests -### 3. Implementation Approach +### 3. Fact-Checking (Source of Truth Verification) + +Always verify information used in your analysis against the source of truth: + +| Information Type | Source of Truth | +|-----------------|-----------------| +| Code behavior | Actual source code | +| Config values / names | Actual config files / definition files | +| APIs / commands | Actual implementation code | +| Documentation claims | Cross-check with actual codebase | + +**Don't guess.** Always verify names, values, and behaviors against actual code. + +### 4. Implementation Approach Determine the implementation direction: diff --git a/resources/global/ja/agents/default/coder.md b/resources/global/ja/agents/default/coder.md index a8a23a3..8ccfccc 100644 --- a/resources/global/ja/agents/default/coder.md +++ b/resources/global/ja/agents/default/coder.md @@ -32,6 +32,7 @@ - 何を作るのか（機能・振る舞い） - どこに作るのか（ファイル・モジュール） - 既存コードとの関係（依存・影響範囲） +- ドキュメント・設定を更新する場合: 記述する内容のソース・オブ・トゥルース（実際のファイル名、設定値、コマンド名は推測せず実コードで確認） **不明点があれば `[BLOCKED]` で報告。** 推測で進めない。 @@ -91,6 +92,7 @@ | テスト | テスト実行 | | 要求充足 | 元のタスク要求と照合 | | デッドコード | 変更・削除した機能を参照する未使用コードが残っていないか確認（未使用の関数、変数、インポート、エクスポート、型定義、到達不能コード） | +| 事実の正確性 | ドキュメントや設定に書いた名前・値・振る舞いが、実際のコードベースと一致しているか確認 | **すべて確認してから `[DONE]` を出力。** diff --git a/resources/global/ja/agents/default/planner.md b/resources/global/ja/agents/default/planner.md index 1a83a41..98cca26 100644 --- a/resources/global/ja/agents/default/planner.md +++ b/resources/global/ja/agents/default/planner.md @@ -33,7 +33,20 @@ - 依存関係 - テストへの影響 -### 3. 実装アプローチ +### 3. 情報の裏取り（ファクトチェック） + +分析で使用する情報は必ずソース・オブ・トゥルースで裏取りする: + +| 情報の種類 | ソース・オブ・トゥルース | +|-----------|----------------------| +| コードの振る舞い | 実際のソースコード | +| 設定値・名前 | 実際の設定ファイル・定義ファイル | +| API・コマンド | 実際の実装コード | +| ドキュメント記述 | 実際のコードベースと突合 | + +**推測で書かない。** 名前・値・振る舞いは必ずコードで確認する。 + +### 4. 実装アプローチ 実装の方向性を決める: