@ronkovic/aad 0.3.8 → 0.4.0

package/README.md

@@ -6,8 +6,8 @@ TypeScript/Bun製マルチエージェント開発オーケストレーター。
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 [![Bun](https://img.shields.io/badge/Bun-1.2+-black)](https://bun.sh/)
 [![npm](https://img.shields.io/npm/v/@ronkovic/aad)](https://www.npmjs.com/package/@ronkovic/aad)
-[![Tests](https://img.shields.io/badge/tests-913%20passing-brightgreen)]()
-[![Version](https://img.shields.io/badge/version-0.3.7-orange)]()
+[![Tests](https://img.shields.io/badge/tests-973%20passing-brightgreen)]()
+[![Version](https://img.shields.io/badge/version-0.3.9-orange)]()
 
 ## 主要機能
 
@@ -112,6 +112,229 @@ bun run dev
 
 > **macOS:** メモリ監視は `vm_stat` ベースで実装されています。Linux環境では `/proc/meminfo` を使用します。
 
+## コマンドリファレンス
+
+### グローバルオプション
+
+以下のオプションはすべてのコマンドで使用可能です:
+
+| オプション | 説明 | デフォルト |
+|----------|------|----------|
+| `-w, --workers <数>` | 並列実行するワーカー数 | 2 |
+| `--persist <モード>` | 永続化モード: `memory` (インメモリ) または `fs` (ファイルシステム) | `memory` |
+| `--debug` | デバッグログを有効化 | `false` |
+| `--no-dashboard` | Webダッシュボードを無効化 | `false` (有効) |
+| `--provider <タイプ>` | デフォルトのClaudeプロバイダー: `cli` または `sdk` | `sdk` |
+
+### コマンド一覧
+
+#### `aad` (引数なし)
+
+インタラクティブモードを起動します。認証設定、プロジェクト設定、実行を対話的に行うウィザードです。
+
+```bash
+aad
+```
+
+**フロー:**
+1. **認証設定**: Claude API キーまたは OAuth トークンを設定
+2. **プロジェクト設定**: 要件ファイルとプロジェクトディレクトリを選択
+3. **実行**: ワーカー数とプロバイダーを選択して実行
+
+---
+
+#### `aad run <requirements>`
+
+要件ファイルを元にタスクを計画・実行します。
+
+```bash
+aad run requirements.md [オプション]
+```
+
+**引数:**
+- `<requirements>`: 要件ファイルのパス（必須）
+
+**オプション:**
+
+| オプション | 説明 | デフォルト |
+|----------|------|----------|
+| `-w, --workers <数>` | 並列実行するワーカー数 | 2 |
+| `--persist <モード>` | 永続化モード: `memory` または `fs` | `memory` |
+| `--debug` | デバッグログを有効化 | `false` |
+| `--no-dashboard` | Webダッシュボードを無効化 | `false` |
+| `--provider <タイプ>` | Claudeプロバイダー: `cli` または `sdk` | `sdk` |
+| `--repos <パス>` | マルチリポジトリモード: カンマ区切りのリポジトリパス | - |
+| `--strategy <戦略>` | マルチリポジトリ戦略: `independent` (独立) または `coordinated` (協調) | `independent` |
+| `--plugins <パス>` | カスタムプラグインのパス（カンマ区切り） | - |
+| `--keep-worktrees` | 完了後にworktreeとブランチを自動削除しない | `false` (自動削除) |
+| `--dry-run` | タスク一覧のみ表示して実行しない（ドライラン） | `false` |
+
+**例:**
+
+```bash
+# 基本的な実行
+aad run requirements.md
+
+# ワーカー数を指定
+aad run requirements.md --workers 4
+
+# CLIプロバイダーを使用
+aad run requirements.md --provider cli
+
+# ダッシュボードを無効化
+aad run requirements.md --no-dashboard
+
+# ドライラン（タスク一覧のみ表示）
+aad run requirements.md --dry-run
+
+# worktreeを残す（手動クリーンアップが必要）
+aad run requirements.md --keep-worktrees
+
+# デバッグモード
+aad run requirements.md --debug
+
+# マルチリポジトリモード
+aad run requirements.md --repos /path/to/repo1,/path/to/repo2 --strategy coordinated
+```
+
+---
+
+#### `aad resume <runId>`
+
+中断された実行を再開します。
+
+```bash
+aad resume <runId>
+```
+
+**引数:**
+- `<runId>`: 再開する実行のID（必須）
+
+**例:**
+
+```bash
+# 特定のrunを再開
+aad resume abc-123-def-456
+
+# runIdは `aad status` で確認可能
+aad status
+aad resume <表示されたrunId>
+```
+
+**動作:**
+- `running` または `failed` 状態のタスクを `pending` にリセット
+- ワーカーを再初期化してタスクを再実行
+- 完了済みのタスクはスキップ
+
+---
+
+#### `aad status [run-id]`
+
+実行の進捗とタスクステータスを表示します。
+
+```bash
+aad status [run-id]
+```
+
+**引数:**
+- `[run-id]`: 確認する実行のID（省略時は最新の実行を表示）
+
+**例:**
+
+```bash
+# 最新の実行を表示
+aad status
+
+# 特定のrunを表示
+aad status abc-123-def-456
+```
+
+**表示内容:**
+- 実行ID、親ブランチ、開始時刻
+- タスク総数、pending/running/completed/failed の数
+- 各タスクの詳細（タスクID、タイトル、ステータス、ワーカーID）
+
+---
+
+#### `aad cleanup [run-id]`
+
+worktreeと孤立したブランチをクリーンアップします。
+
+```bash
+aad cleanup [run-id] [オプション]
+```
+
+**引数:**
+- `[run-id]`: クリーンアップする実行のID（省略時はすべてのAAD worktreeを対象）
+
+**オプション:**
+
+| オプション | 説明 | デフォルト |
+|----------|------|----------|
+| `-f, --force` | 変更があるworktreeも強制削除、parentブランチも削除 | `false` |
+
+**例:**
+
+```bash
+# すべてのAAD worktreeをクリーンアップ（parentは保護）
+aad cleanup
+
+# 特定のrunのみクリーンアップ
+aad cleanup abc-123-def-456
+
+# 強制削除（parentブランチも削除、変更も無視）
+aad cleanup --force
+aad cleanup abc-123-def-456 --force
+```
+
+**動作:**
+- デフォルトではparentブランチとworktreeを保護（レビュー用）
+- `--force` を指定すると parent を含むすべてのworktreeとブランチを削除
+- 孤立したworktreeは自動的にprune
+
+---
+
+#### `aad update`
+
+AADを最新バージョンに更新します。
+
+```bash
+aad update [オプション]
+```
+
+**オプション:**
+
+| オプション | 説明 | デフォルト |
+|----------|------|----------|
+| `--check` | 更新の有無のみ確認（インストールしない） | `false` |
+
+**例:**
+
+```bash
+# 最新版に更新
+aad update
+
+# 更新の有無のみ確認
+aad update --check
+```
+
+**動作:**
+- 現在のバージョンと最新バージョンをnpmレジストリから取得して比較
+- `bun`使用時は `bunx` キャッシュをクリア（次回実行時に最新版を使用）
+- `npm`使用時は `npm install -g @ronkovic/aad@latest` を実行
+
+---
+
+#### `aad interactive`
+
+インタラクティブモードを明示的に起動します（`aad` のみと同じ）。
+
+```bash
+aad interactive
+```
+
+---
+
 ## クイックスタート
 
 ### 1. 要件ファイルの作成
@@ -136,6 +359,9 @@ bun run dev
 
 ```bash
 # 直接実行
+aad run requirements.md
+
+# ワーカー数を指定
 aad run requirements.md --workers 4
 
 # インタラクティブモード（対話型ウィザード）
@@ -149,31 +375,62 @@ AADが自動的に:
 4. ワーカーで並列実行 (TDD: テスト作成 → 実装 → 検証 → レビュー)
 5. 親ブランチへのマージ
 
+**よく使うオプション:**
+- `--workers <数>`: 並列ワーカー数（デフォルト: 2）
+- `--provider cli`: Claude CLIを使用（デフォルトは SDK）
+- `--dry-run`: タスク一覧のみ表示（実行しない）
+- `--keep-worktrees`: 完了後もworktreeを削除しない
+- `--debug`: デバッグログを有効化
+
+詳細は [コマンドリファレンス](#コマンドリファレンス) をご覧ください。
+
 ### 3. 進捗確認・管理
 
 ```bash
-# ステータス確認
-aad status [run_id]
+# ステータス確認（最新の実行）
+aad status
+
+# 特定の実行のステータス確認
+aad status <run_id>
 
-# 実行の再開
+# 中断された実行の再開
 aad resume <run_id>
 
-# worktreeのクリーンアップ
-aad cleanup [run_id] [--force]
+# worktreeのクリーンアップ（parentは保護）
+aad cleanup
+
+# 特定のrunのクリーンアップ
+aad cleanup <run_id>
+
+# 強制クリーンアップ（parentも削除）
+aad cleanup --force
 
 # バージョン確認・アップデート
-aad update [--check]
+aad update
+aad update --check
 ```
 
+すべてのコマンドとオプションの詳細は [コマンドリファレンス](#コマンドリファレンス) をご覧ください。
+
 ### 4. Webダッシュボード
 
 ダッシュボードはデフォルトで有効です。`http://localhost:7333` でリアルタイムの進捗・ログ・依存グラフを確認できます。
 
-無効にする場合:
+**ダッシュボード機能:**
+- タスク進捗のリアルタイム可視化
+- ワーカーステータス監視
+- タスク依存グラフ (DAG)
+- 構造化ログのストリーミング表示
+- タスクタイムライン (Gantt)
+
+**無効にする場合:**
 ```bash
-aad run requirements.md --workers 4 --no-dashboard
+aad run requirements.md --no-dashboard
 ```
 
+**ポート変更:**
+設定ファイル `.aad/config.json` で `dashboard.port` を変更できます。
+
 ## 開発ガイド
 
 ### 環境セットアップ
@@ -308,16 +565,22 @@ aad run requirements.md --provider cli
 ```bash
 # 構造化ログの確認
 cat .aad/docs/<run_id>/logs/structured.jsonl | bunx pino-pretty
+
+# デバッグモードで実行
+aad run requirements.md --debug
 ```
 
 ### Worktreeが残っている
 
 ```bash
-# 全AAD worktreeをクリーンアップ
+# 全AAD worktreeをクリーンアップ（parentは保護）
 aad cleanup
 
 # 特定のrunのみ
 aad cleanup <run_id>
+
+# parentも含めて強制削除
+aad cleanup --force
 ```
 
 ### タスクがスタックした
@@ -326,10 +589,27 @@ aad cleanup <run_id>
 # ステータス確認
 aad status <run_id>
 
-# 強制クリーンアップ
+# 実行を再開
+aad resume <run_id>
+
+# 強制クリーンアップして最初からやり直し
 aad cleanup <run_id> --force
+aad run requirements.md
+```
+
+### メモリ不足エラー
+
+AADは自動的にメモリを監視し、不足時にワーカー数を削減します。手動でワーカー数を減らすこともできます:
+
+```bash
+# ワーカー数を1に減らす
+aad run requirements.md --workers 1
 ```
 
+### コマンドオプションの詳細
+
+すべてのコマンドとオプションの詳細は [コマンドリファレンス](#コマンドリファレンス) をご覧ください。
+
 ## ライセンス
 
 [MIT License](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronkovic/aad",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Autonomous Agent Development Orchestrator - Multi-agent TDD pipeline powered by Claude",
   "module": "src/main.ts",
   "type": "module",
@@ -11,6 +11,7 @@
   "files": [
     "bin",
     "src",
+    "templates",
     "README.md",
     "LICENSE",
     "tsconfig.json"
@@ -34,6 +35,10 @@
     "test:coverage:report": "bun test --coverage --coverage-reporter=html",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
+    "ci": "bash scripts/ci-local.sh",
+    "ci:lint": "bash scripts/ci-local.sh --lint",
+    "ci:test": "bash scripts/ci-local.sh --test",
+    "ci:build": "bash scripts/ci-local.sh --build",
     "prepublishOnly": "bun run typecheck && bun run lint && bun test"
   },
   "dependencies": {

package/src/__tests__/e2e/pipeline-e2e.test.ts

@@ -57,6 +57,7 @@ function createMockConfig(): Config {
     teams: { splitter: false, reviewer: false },
     memorySync: false,
     dashboard: { enabled: false, port: 7333, host: "localhost" },
+    git: { autoPush: false },
   };
 }
 

package/src/__tests__/e2e/resume-e2e.test.ts

@@ -52,7 +52,9 @@ describe("E2E Resume", () => {
         teams: { splitter: false, reviewer: false },
         memorySync: false,
         dashboard: { enabled: false, port: 7333, host: "localhost" },
+    git: { autoPush: false },
       },
+    git: { autoPush: false },
       eventBus,
       logger: createMockLogger(),
       stores,

package/src/__tests__/integration/pipeline.test.ts

@@ -31,6 +31,7 @@ describe("Cross-Module Integration: Pipeline", () => {
       teams: { splitter: false, reviewer: false },
       memorySync: false,
       dashboard: { enabled: false, port: 7333, host: "localhost" },
+      git: { autoPush: false },
     };
     stores = createStores("memory");
   });

package/src/modules/claude-provider/__tests__/claude-sdk-real-env.test.ts

@@ -94,7 +94,7 @@ describe.skipIf(!hasAuth)("ClaudeSdkAdapter - Real Environment", () => {
     const adapter = createAdapter();
     const response = await adapter.call({
       prompt: "Reply with exactly: HI",
-      model: "claude-haiku-3-5-20241022",
+      model: "claude-haiku-4-5-20251001",
     });
 
     expect(response.result).toBeDefined();

package/src/modules/claude-provider/__tests__/claude-sdk.adapter.test.ts

@@ -70,6 +70,7 @@ describe("ClaudeSdkAdapter", () => {
       teams: { splitter: false, reviewer: false },
       memorySync: false,
       dashboard: { enabled: false, port: 7333, host: "localhost" },
+    git: { autoPush: false },
     };
 
     logger = pino({ level: "silent" });
@@ -150,6 +151,7 @@ describe("ClaudeSdkAdapter", () => {
             model: "claude-sonnet-4-5-20250929",
             content: [{ type: "text", text: "Error response" }],
           },
+    git: { autoPush: false },
           error: "rate_limit",
         } as MockSDKMessage;
         yield {

package/src/modules/claude-provider/__tests__/provider-registry.test.ts

@@ -58,6 +58,7 @@ const mockAppConfig: Config = {
     port: 7333,
     host: "localhost",
   },
+    git: { autoPush: false },
 };
 
 describe("ProviderRegistry", () => {

package/src/modules/cli/__tests__/cleanup.test.ts

@@ -108,4 +108,76 @@ describe("cleanupWorktrees", () => {
     // Should have attempted both despite error
     expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledTimes(2);
   });
+
+  test("detects AAD worktrees with path containing /.aad/worktrees/", async () => {
+    mockApp.worktreeManager.listWorktrees = mock(async () => [
+      {
+        path: "/different/base/.aad/worktrees/task-1",
+        branch: "aad/task-1",
+        head: "abc123",
+      },
+      {
+        path: "/some/other/path/task-2",
+        branch: "aad/task-2",
+        head: "def456",
+      },
+    ]);
+
+    await cleanupWorktrees(mockApp);
+
+    // Should only remove the one with /.aad/worktrees/ in path
+    expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledTimes(1);
+    expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledWith(
+      "/different/base/.aad/worktrees/task-1",
+      false
+    );
+  });
+
+  test("skips parent-* worktrees without --force", async () => {
+    mockApp.worktreeManager.listWorktrees = mock(async () => [
+      {
+        path: `${process.cwd()}/.aad/worktrees/task-1`,
+        branch: "aad/task-1",
+        head: "abc123",
+      },
+      {
+        path: `${process.cwd()}/.aad/worktrees/parent-run-001`,
+        branch: "feat/run-001/parent",
+        head: "def456",
+      },
+    ]);
+
+    await cleanupWorktrees(mockApp, undefined, false);
+
+    // Should only remove task-1, not parent-run-001
+    expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledTimes(1);
+    expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledWith(
+      expect.stringContaining("task-1"),
+      false
+    );
+    expect(mockApp.worktreeManager.removeWorktree).not.toHaveBeenCalledWith(
+      expect.stringContaining("parent-"),
+      expect.anything()
+    );
+  });
+
+  test("includes parent-* worktrees with --force", async () => {
+    mockApp.worktreeManager.listWorktrees = mock(async () => [
+      {
+        path: `${process.cwd()}/.aad/worktrees/task-1`,
+        branch: "aad/task-1",
+        head: "abc123",
+      },
+      {
+        path: `${process.cwd()}/.aad/worktrees/parent-run-001`,
+        branch: "feat/run-001/parent",
+        head: "def456",
+      },
+    ]);
+
+    await cleanupWorktrees(mockApp, undefined, true);
+
+    // Should remove both task-1 and parent-run-001
+    expect(mockApp.worktreeManager.removeWorktree).toHaveBeenCalledTimes(2);
+  });
 });

package/src/modules/cli/__tests__/resume.test.ts

@@ -69,6 +69,7 @@ describe("resumeRun", () => {
         teams: { splitter: false, reviewer: false },
         memorySync: false,
         dashboard: { enabled: false, port: 7333, host: "localhost" },
+        git: { autoPush: false },
       },
       eventBus,
       logger: {

package/src/modules/cli/__tests__/run.test.ts

@@ -34,6 +34,7 @@ describe("runPipeline", () => {
         teams: { splitter: false, reviewer: false },
         memorySync: false,
         dashboard: { enabled: false, port: 7333, host: "localhost" },
+        git: { autoPush: false },
       },
       eventBus,
       logger: {