@ronkovic/aad 0.3.9 → 0.5.0

package/README.md

@@ -6,13 +6,15 @@ 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-1037%20passing-brightgreen)]()
+[![Version](https://img.shields.io/badge/version-0.5.0-orange)]()
 
 ## 主要機能
 
 - **マルチエージェント並列実行**: 複数のClaudeエージェントが独立したタスクを並列処理
 - **TDDパイプライン**: Red → Green → Verify → Review → Merge の自動化されたテスト駆動開発
+- **スマート実行最適化**: テスト事前チェックで既に通過済みタスクを自動スキップ *(v0.5.0)*
+- **実行メトリクス**: スキップ/実行タスク数を完了時に表示、効率を可視化 *(v0.5.0)*
 - **インタラクティブモード**: `aad` で対話型ウィザードを起動、認証・プロジェクト設定を簡単に *(v0.3.6)*
 - **セルフアップデート**: `aad update` で最新版に自動更新 *(v0.3.6)*
 - **スマートブランチ命名**: 要件ドキュメントから自動でconventional commit prefix付きブランチ名を生成 *(v0.3.7)*
@@ -21,10 +23,40 @@ TypeScript/Bun製マルチエージェント開発オーケストレーター。
 - **プラグインシステム**: カスタムアダプター・パイプラインステップの拡張
 - **Git Workspace管理**: タスクごとに独立したworktreeを自動作成・管理
 - **依存関係解決**: タスク間の依存関係を自動検出し、適切な順序で実行
-- **リアルタイム監視**: Webダッシュボードで進捗・ログをリアルタイム表示
+- **リアルタイム監視**: TypeScript化されたWebダッシュボードで進捗・ログをリアルタイム表示 *(v0.5.0)*
 - **構造化ログ**: pinoによる構造化ログで詳細なトレーシングが可能
 - **メモリ安全機構**: OOMを防止する自動メモリゲート・シーケンシャルフォールバック
 
+## 🎉 v0.5.0の新機能
+
+### スマート実行最適化
+
+既にテストが通過しているタスクを自動でスキップする**pre-check機能**を追加しました。これにより、再実行時や部分的な変更時の実行時間を大幅に短縮できます。
+
+- **デフォルトで有効**: `skipCompleted: true` (設定で無効化可能)
+- **従来の動作に戻す**: `--strict-tdd` フラグで完全なTDDパイプラインを強制実行
+- **メトリクス表示**: 実行完了時にスキップ/実行タスク数を表示
+
+```bash
+# スマート実行（デフォルト）- テスト通過済みタスクを自動スキップ
+aad run requirements.md
+
+# 完全TDD実行 - 全タスクで完全なパイプラインを実行
+aad run requirements.md --strict-tdd
+```
+
+### UX改善
+
+- **Dashboard URL自動表示**: `aad run`/`aad resume`実行時にダッシュボードURLを自動表示
+- **Resume案内表示**: Ctrl+C中断時に`aad resume <run-id>`コマンド例を表示
+- **TypeScript化Dashboard**: React風コンポーネントでメンテナンス性向上
+
+### テストスイート強化
+
+- **1037テスト全pass**: 30個の失敗を解消し、全テストが通過
+- **E2Eテスト追加**: cleanup, TDD pipeline, dashboardの包括的E2Eテスト
+- **CI強化**: E2Eジョブ分離、build matrix (ubuntu + macos)
+
 ## アーキテクチャ
 
 AADは12個のモジュールで構成された**Hexagonal-flavored Modular Monolith**です:
@@ -112,6 +144,233 @@ 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` |
+| `--strict-tdd` | 事前チェックをスキップし、常に完全なTDDパイプラインを実行 | `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
+
+# 完全なTDDパイプライン（最適化無効）
+aad run requirements.md --strict-tdd
+
+# マルチリポジトリモード
+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 +395,9 @@ bun run dev
 
 ```bash
 # 直接実行
+aad run requirements.md
+
+# ワーカー数を指定
 aad run requirements.md --workers 4
 
 # インタラクティブモード（対話型ウィザード）
@@ -149,31 +411,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` を変更できます。
+
 ## 開発ガイド
 
 ### 環境セットアップ
@@ -254,7 +547,9 @@ describe("MyModule", () => {
   "dashboard": {
     "enabled": true,
     "port": 7333
-  }
+  },
+  "skipCompleted": true,
+  "strictTdd": false
 }
 ```
 
@@ -308,16 +603,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 +627,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.9",
+  "version": "0.5.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/cleanup-e2e.test.ts

@@ -0,0 +1,186 @@
+/**
+ * E2E Test: Cleanup command (worktree removal)
+ */
+import { describe, test, expect } from "bun:test";
+import { cleanupWorktrees } from "../../modules/cli/commands/cleanup";
+import { createMockLogger } from "../helpers/mock-logger";
+import type { App } from "../../modules/cli/app";
+
+interface WorktreeInfo {
+  path: string;
+  branch: string;
+  head: string;
+}
+
+describe("E2E Cleanup Command", () => {
+  test("cleanup lists all AAD worktrees", async () => {
+    const mockWorktrees: WorktreeInfo[] = [
+      { path: "/project/.aad/worktrees/run-1/task-1", branch: "aad/task-1", head: "abc123" },
+      { path: "/project/.aad/worktrees/run-1/task-2", branch: "aad/task-2", head: "def456" },
+      { path: "/project/.aad/worktrees/run-1/parent-main", branch: "main", head: "ghi789" },
+    ];
+
+    let listedWorktrees: WorktreeInfo[] = [];
+
+    const app = {
+      logger: createMockLogger(),
+      worktreeManager: {
+        async listWorktrees() {
+          listedWorktrees = mockWorktrees;
+          return mockWorktrees;
+        },
+        async removeWorktree() {},
+        async pruneWorktrees() {},
+      },
+      branchManager: {
+        async cleanupOrphanBranches() {
+          return [];
+        },
+      },
+    } as unknown as App;
+
+    await cleanupWorktrees(app);
+
+    // Verify worktrees were listed
+    expect(listedWorktrees.length).toBe(3);
+    expect(listedWorktrees.some((wt) => wt.path.includes("task-1"))).toBe(true);
+  }, 15_000);
+
+  test("cleanup removes specified worktrees", async () => {
+    const mockWorktrees: WorktreeInfo[] = [
+      { path: "/project/.aad/worktrees/run-1/task-1", branch: "aad/task-1", head: "abc123" },
+      { path: "/project/.aad/worktrees/run-1/task-2", branch: "aad/task-2", head: "def456" },
+    ];
+
+    const removedPaths: string[] = [];
+
+    const app = {
+      logger: createMockLogger(),
+      worktreeManager: {
+        async listWorktrees() {
+          return mockWorktrees;
+        },
+        async removeWorktree(path: string) {
+          removedPaths.push(path);
+        },
+        async pruneWorktrees() {},
+      },
+      branchManager: {
+        async cleanupOrphanBranches() {
+          return [];
+        },
+      },
+    } as unknown as App;
+
+    await cleanupWorktrees(app);
+
+    // Verify worktrees were removed
+    expect(removedPaths.length).toBe(2);
+    expect(removedPaths.some((p) => p.includes("task-1"))).toBe(true);
+    expect(removedPaths.some((p) => p.includes("task-2"))).toBe(true);
+  }, 15_000);
+
+  test("cleanup with --all flag removes all AAD worktrees", async () => {
+    const mockWorktrees: WorktreeInfo[] = [
+      { path: "/project/.aad/worktrees/run-1/task-1", branch: "aad/task-1", head: "abc123" },
+      { path: "/project/.aad/worktrees/run-1/parent-main", branch: "main", head: "def456" },
+    ];
+
+    const removedPaths: string[] = [];
+
+    const app = {
+      logger: createMockLogger(),
+      worktreeManager: {
+        async listWorktrees() {
+          return mockWorktrees;
+        },
+        async removeWorktree(path: string) {
+          removedPaths.push(path);
+        },
+        async pruneWorktrees() {},
+      },
+      branchManager: {
+        async cleanupOrphanBranches() {
+          return [];
+        },
+      },
+    } as unknown as App;
+
+    // force=true should include parent worktrees
+    await cleanupWorktrees(app, undefined, true);
+
+    // Verify all worktrees including parent were removed
+    expect(removedPaths.length).toBe(2);
+    expect(removedPaths.some((p) => p.includes("task-1"))).toBe(true);
+    expect(removedPaths.some((p) => p.includes("parent-main"))).toBe(true);
+  }, 15_000);
+
+  test("cleanup skips non-AAD worktrees", async () => {
+    const mockWorktrees: WorktreeInfo[] = [
+      { path: "/project/.aad/worktrees/run-1/task-1", branch: "aad/task-1", head: "abc123" },
+      { path: "/some/other/worktree", branch: "feature/xyz", head: "def456" },
+    ];
+
+    const removedPaths: string[] = [];
+
+    const app = {
+      logger: createMockLogger(),
+      worktreeManager: {
+        async listWorktrees() {
+          return mockWorktrees;
+        },
+        async removeWorktree(path: string) {
+          removedPaths.push(path);
+        },
+        async pruneWorktrees() {},
+      },
+      branchManager: {
+        async cleanupOrphanBranches() {
+          return [];
+        },
+      },
+    } as unknown as App;
+
+    await cleanupWorktrees(app);
+
+    // Verify only AAD worktree was removed
+    expect(removedPaths.length).toBe(1);
+    expect(removedPaths[0]).toContain(".aad/worktrees");
+    expect(removedPaths[0]).not.toContain("/some/other/worktree");
+  }, 15_000);
+
+  test("cleanup handles worktree not found gracefully", async () => {
+    const mockWorktrees: WorktreeInfo[] = [
+      { path: "/project/.aad/worktrees/run-1/task-1", branch: "aad/task-1", head: "abc123" },
+    ];
+
+    let errorThrown = false;
+
+    const app = {
+      logger: createMockLogger(),
+      worktreeManager: {
+        async listWorktrees() {
+          return mockWorktrees;
+        },
+        async removeWorktree() {
+          throw new Error("worktree not found");
+        },
+        async pruneWorktrees() {},
+      },
+      branchManager: {
+        async cleanupOrphanBranches() {
+          return [];
+        },
+      },
+    } as unknown as App;
+
+    try {
+      await cleanupWorktrees(app);
+    } catch {
+      errorThrown = true;
+    }
+
+    // Should not throw - errors are caught and logged
+    expect(errorThrown).toBe(false);
+  }, 15_000);
+});