@ronkovic/aad 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AAD Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# AAD - Autonomous Agent Development Orchestrator
+
+TypeScript/Bun製マルチエージェント開発オーケストレーター。Claude CLIを活用し、TDDパイプラインによる並列タスク実行を自動化します。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![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/)
+[![Tests](https://img.shields.io/badge/tests-738%2B%20passing-brightgreen)]()
+[![Version](https://img.shields.io/badge/version-0.3.0-orange)]()
+
+## 主要機能
+
+- **マルチエージェント並列実行**: 複数のClaudeエージェントが独立したタスクを並列処理
+- **TDDパイプライン**: Red → Green → Verify → Review → Merge の自動化されたテスト駆動開発
+- **マルチリポジトリ対応**: 複数リポジトリにまたがるタスクの統合管理 *(v0.3.0)*
+- **プラグインシステム**: カスタムアダプター・パイプラインステップの拡張 *(v0.3.0)*
+- **Git Workspace管理**: タスクごとに独立したworktreeを自動作成・管理
+- **依存関係解決**: タスク間の依存関係を自動検出し、適切な順序で実行
+- **リアルタイム監視**: Webダッシュボードで進捗・ログをリアルタイム表示
+- **構造化ログ**: pinoによる構造化ログで詳細なトレーシングが可能
+
+## アーキテクチャ
+
+AADは12個のモジュールで構成された**Hexagonal-flavored Modular Monolith**です:
+
+```
+cli (エントリポイント)
+├── planning (要件→タスク分解) ★
+├── task-queue (タスクライフサイクル管理)
+├── task-execution (TDDパイプライン実行) ★
+├── process-manager (ワーカープロセス管理)
+├── git-workspace (worktree/branch管理)
+├── claude-provider (SDK/CLI抽象化) ★
+├── persistence (状態永続化) ★
+├── logging (構造化ログ)
+├── dashboard (Web UI)
+├── multi-repo (マルチリポジトリ統合) ★
+└── plugin (プラグインシステム) ★
+
+★ = Ports & Adapters パターン適用
+```
+
+### 技術スタック
+
+- **言語**: TypeScript (strict mode)
+- **ランタイム**: Bun v1.2+
+- **テストフレームワーク**: bun:test (Jest互換API)
+- **Web Framework**: Hono
+- **ロガー**: pino v9
+- **バリデーション**: Zod
+- **CLI**: Commander.js
+
+## インストール
+
+> ⚠️ **Bun専用** — AADはBunランタイムが必要です。Node.jsでは動作しません。
+
+### 前提条件
+
+- [Bun](https://bun.sh/) v1.2 以上
+- Git
+- Claude CLI (オプション: CLI adapter使用時)
+
+### インストール不要で実行 (推奨)
+
+```bash
+bunx aad run requirements.md
+```
+
+### グローバルインストール
+
+```bash
+bun install -g aad
+aad run requirements.md
+```
+
+### スタンドアロンバイナリ
+
+```bash
+git clone https://github.com/ronkovic/aad.git
+cd aad && bun install
+bun run build    # → ./aad バイナリを生成
+./aad --version
+```
+
+### ローカル開発
+
+```bash
+git clone https://github.com/ronkovic/aad.git
+cd aad
+bun install
+bun run dev
+```
+
+## クイックスタート
+
+### 1. 要件ファイルの作成
+
+`requirements.md` を作成してタスクを記述:
+
+```markdown
+# タスク一覧
+
+## Task 1: ユーザー認証機能の実装
+- ファイル: src/auth/login.ts
+- テスト: src/auth/__tests__/login.test.ts
+- 依存: なし
+
+## Task 2: ダッシュボードUI作成
+- ファイル: src/ui/dashboard.tsx
+- テスト: src/ui/__tests__/dashboard.test.tsx
+- 依存: Task 1
+```
+
+### 2. タスク実行
+
+```bash
+aad run requirements.md --workers 4
+```
+
+AADが自動的に:
+1. タスクを分解・依存関係を解析
+2. 各タスク用のworktreeを作成
+3. 4つのワーカーで並列実行 (TDD: テスト作成 → 実装 → 検証 → レビュー)
+4. 親ブランチへのマージ
+
+### 3. 進捗確認
+
+```bash
+# ステータス確認
+aad status
+
+# 実行の再開
+aad resume <run_id>
+
+# worktreeのクリーンアップ
+aad cleanup
+```
+
+### 4. Webダッシュボード (オプション)
+
+```bash
+aad run requirements.md --workers 4 --dashboard
+```
+
+ブラウザで `http://localhost:7333` を開くと、リアルタイムで進捗・ログ・依存グラフを確認できます。
+
+## 開発ガイド
+
+### 環境セットアップ
+
+```bash
+# 依存関係のインストール
+bun install
+
+# 型チェック
+bun run typecheck
+
+# テスト実行
+bun test
+
+# ウォッチモード
+bun test --watch
+
+# Lint
+bun run lint
+```
+
+### ビルド & 配布
+
+```bash
+# 単一バイナリのビルド (self-contained実行ファイル)
+bun build --compile ./src/main.ts --outfile aad
+
+# 実行
+./aad --version
+```
+
+### モジュール境界ルール
+
+各モジュールは `index.ts` でのみ公開APIをエクスポートします:
+
+```typescript
+// ✅ Good
+import { TaskQueue } from "@aad/task-queue";
+
+// ❌ Bad: モジュール内部へのアクセス
+import { Dispatcher } from "@aad/task-queue/dispatcher";
+```
+
+### テストの書き方
+
+```typescript
+import { describe, test, expect } from "bun:test";
+
+describe("MyModule", () => {
+  test("should do something", () => {
+    expect(true).toBe(true);
+  });
+});
+```
+
+## 設定
+
+`.aad/config.json` で動作をカスタマイズできます:
+
+```json
+{
+  "workers": {
+    "num": 4,
+    "max": 8
+  },
+  "models": {
+    "default": "sonnet",
+    "splitter": "sonnet",
+    "tester": "sonnet",
+    "implementer": "sonnet",
+    "reviewer": "sonnet",
+    "mergeResolver": "haiku"
+  },
+  "timeouts": {
+    "claude": 1200,
+    "test": 600
+  },
+  "dashboard": {
+    "enabled": true,
+    "port": 7333
+  }
+}
+```
+
+### 利用可能なモデル
+
+`models`設定で指定できるモデル名:
+
+| フルネーム | 短縮名 | 説明 |
+|-----------|--------|------|
+| claude-sonnet-4-5-20250929 | sonnet | Sonnet 4.5 - バランス型、推奨デフォルト |
+| claude-opus-4-6 | opus | Opus 4.6 - 最高性能、高コスト |
+| claude-haiku-4-5-20251001 | haiku | Haiku 4.5 - 高速・低コスト |
+
+設定では短縮名(`sonnet`、`opus`、`haiku`)またはフルネームが使用できます。
+
+## Claude Provider: SDK vs CLI
+
+AADはClaudeとの通信に2つのadapterを提供:
+
+- **SDK Adapter** (`claude-sdk.adapter.ts`): Agent SDK経由、構造化出力に最適
+- **CLI Adapter** (`claude-cli.adapter.ts`): Claude CLI経由、重いファイル操作に最適
+
+サービスごとに使い分け可能:
+
+```typescript
+const providerConfig = {
+  default: 'cli',
+  overrides: {
+    splitter: 'sdk',    // 構造化JSON出力
+    reviewer: 'sdk',    // 構造化レビュー結果
+  }
+};
+```
+
+## トラブルシューティング
+
+### ログの確認
+
+```bash
+# 構造化ログの確認
+cat .aad/docs/<run_id>/logs/structured.jsonl | bunx pino-pretty
+```
+
+### Worktreeが残っている
+
+```bash
+aad cleanup --all
+```
+
+### タスクがスタックした
+
+```bash
+# ステータス確認
+aad status <run_id>
+
+# 強制クリーンアップ
+aad cleanup --run <run_id> --force
+```
+
+## ライセンス
+
+[MIT License](LICENSE)
+
+## 貢献
+
+コントリビューションを歓迎します! 詳細は [CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。
+
+### 開発の流れ
+
+1. このリポジトリをfork
+2. feature branchを作成 (`git checkout -b feature/amazing-feature`)
+3. 変更をcommit (`git commit -m 'feat: add amazing feature'`)
+4. branchをpush (`git push origin feature/amazing-feature`)
+5. Pull Requestを作成
+
+## リンク
+
+- [Architecture Documentation](docs/architecture.md)
+- [Rewrite Plan (Internal)](docs/rewrite-plan/README.md)
+- [Project Guidelines](CLAUDE.md)
+- [Issue Tracker](https://github.com/ronkovic/aad/issues)
+
+---
+
+Built with ❤️ using [Bun](https://bun.sh/) and [Claude](https://www.anthropic.com/claude)

package/bin/aad.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/main.ts";

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ronkovic/aad",
+  "version": "0.3.0",
+  "description": "Autonomous Agent Development Orchestrator - Multi-agent TDD pipeline powered by Claude",
+  "module": "src/main.ts",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "aad": "./bin/aad.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/main.ts",
+      "import": "./src/main.ts",
+      "types": "./src/main.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun build --compile ./src/main.ts --outfile aad",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:coverage:report": "bun test --coverage --coverage-reporter=html",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun test"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.34",
+    "hono": "^4.6",
+    "pino": "^9.6",
+    "pino-pretty": "^13.0",
+    "chokidar": "^4.0",
+    "commander": "^13.0",
+    "zod": "^3.24"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^10.0.0",
+    "typescript": "^5.7"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ronkovic/aad.git"
+  },
+  "homepage": "https://github.com/ronkovic/aad#readme",
+  "bugs": {
+    "url": "https://github.com/ronkovic/aad/issues"
+  },
+  "author": "ronkovic",
+  "keywords": [
+    "claude",
+    "agent",
+    "tdd",
+    "orchestrator",
+    "multi-agent",
+    "autonomous",
+    "development",
+    "bun"
+  ],
+  "license": "MIT"
+}

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

@@ -0,0 +1,279 @@
+/**
+ * E2E Pipeline Test — lightweight, mock-based
+ * Tests the full planning → dispatch → completion flow without real Claude API or git.
+ */
+import { describe, test, expect, beforeEach } from "bun:test";
+import { EventBus, type AADEvent } from "@aad/shared/events";
+import { PlanningService } from "@aad/planning/planning.service";
+import { Dispatcher } from "@aad/task-queue/dispatcher";
+import { createStores } from "@aad/persistence/index";
+import {
+  createRunId,
+  createTaskId,
+  createWorkerId,
+  type TaskId,
+} from "@aad/shared/types";
+import type { Config } from "@aad/shared/config";
+import type {
+  ClaudeProvider,
+  ClaudeRequest,
+  ClaudeResponse,
+} from "@aad/claude-provider/claude-provider.port";
+import type { FileChecker } from "@aad/planning/project-detection";
+import type pino from "pino";
+
+// ── Helpers ──────────────────────────────────────────────
+
+class MockClaudeProvider implements ClaudeProvider {
+  mockResponse: ClaudeResponse = {
+    result: "",
+    exitCode: 0,
+    model: "claude-sonnet-4-5",
+    effortLevel: "medium",
+    duration: 100,
+  };
+
+  async call(_req: ClaudeRequest): Promise<ClaudeResponse> {
+    return this.mockResponse;
+  }
+}
+
+function createMockLogger(): pino.Logger {
+  const noop = () => {};
+  return {
+    info: noop, warn: noop, error: noop, debug: noop, trace: noop, fatal: noop,
+    child: () => createMockLogger(),
+  } as unknown as pino.Logger;
+}
+
+function createMockConfig(): Config {
+  return {
+    workers: { num: 2, max: 4 },
+    models: {},
+    timeouts: { claude: 1200, test: 600, staleTask: 5400 },
+    retry: { maxRetries: 2 },
+    debug: false,
+    adaptiveEffort: false,
+    teams: { splitter: false, reviewer: false },
+    memorySync: false,
+    dashboard: { enabled: false, port: 7333, host: "localhost" },
+  };
+}
+
+const mockFileChecker: FileChecker = {
+  exists: async () => false,
+  readText: async () => "",
+  glob: async () => [],
+};
+
+/** Collect specific event types into an array */
+function collectEvents(eventBus: EventBus, ...types: string[]) {
+  const collected: AADEvent[] = [];
+  for (const t of types) {
+    eventBus.on(t as AADEvent["type"], (e: AADEvent) => collected.push(e));
+  }
+  return collected;
+}
+
+/** Wait until predicate is true (polling) */
+function waitFor(predicate: () => boolean, timeoutMs = 5000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      if (predicate()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error("waitFor timeout"));
+      setTimeout(check, 20);
+    };
+    check();
+  });
+}
+
+// ── Tests ────────────────────────────────────────────────
+
+describe("E2E Pipeline", () => {
+  let eventBus: EventBus;
+  let mockProvider: MockClaudeProvider;
+  let logger: pino.Logger;
+
+  beforeEach(() => {
+    eventBus = new EventBus();
+    mockProvider = new MockClaudeProvider();
+    logger = createMockLogger();
+  });
+
+  test("basic pipeline: plan → dispatch → complete", async () => {
+    const config = createMockConfig();
+    const stores = createStores("memory");
+    const runId = createRunId("e2e-run-1");
+
+    // 1) Planning — mock Claude to return a 2-task plan
+    mockProvider.mockResponse = {
+      result: JSON.stringify({
+        run_id: "e2e-run-1",
+        parent_branch: "main",
+        tasks: [
+          { task_id: "task-1", title: "Task 1", description: "First", files_to_modify: ["a.ts"], depends_on: [], priority: 1 },
+          { task_id: "task-2", title: "Task 2", description: "Second", files_to_modify: ["b.ts"], depends_on: [], priority: 2 },
+        ],
+      }),
+      exitCode: 0,
+      model: "claude-sonnet-4-5",
+      effortLevel: "medium",
+      duration: 100,
+    };
+
+    const planningService = new PlanningService(mockProvider, eventBus, config, logger, { fileChecker: mockFileChecker });
+
+    const events = collectEvents(eventBus,
+      "planning:started", "planning:completed", "task:dispatched", "run:completed",
+    );
+
+    const taskPlan = await planningService.planTasks({
+      runId,
+      parentBranch: "main",
+      requirementsPath: "/fake/requirements.md",
+      targetDocsDir: "/fake/docs",
+    });
+
+    expect(taskPlan.tasks).toHaveLength(2);
+
+    // 2) Dispatch
+    // Register idle workers
+    const w1 = createWorkerId("worker-1");
+    const w2 = createWorkerId("worker-2");
+    await stores.workerStore.save({ workerId: w1, status: "idle", currentTask: null });
+    await stores.workerStore.save({ workerId: w2, status: "idle", currentTask: null });
+
+    const dispatcher = new Dispatcher({
+      taskStore: stores.taskStore,
+      workerStore: stores.workerStore,
+      runStore: stores.runStore,
+      eventBus,
+      config: { maxRetries: 2 },
+      logger,
+    });
+
+    await dispatcher.initialize(taskPlan);
+    dispatcher.start();
+
+    // Wait for tasks to be dispatched
+    await waitFor(() => events.some(e => e.type === "task:dispatched"), 3000);
+
+    // 3) Simulate task completion
+    eventBus.emit({ type: "task:completed", taskId: createTaskId("task-1"), result: { taskId: createTaskId("task-1"), status: "completed", duration: 50 } });
+    eventBus.emit({ type: "task:completed", taskId: createTaskId("task-2"), result: { taskId: createTaskId("task-2"), status: "completed", duration: 60 } });
+
+    await waitFor(() => events.some(e => e.type === "run:completed"), 3000);
+
+    // Verify event flow
+    const types = events.map(e => e.type);
+    expect(types).toContain("planning:started");
+    expect(types).toContain("planning:completed");
+    expect(types).toContain("task:dispatched");
+    expect(types).toContain("run:completed");
+
+    dispatcher.stop();
+  }, 15_000);
+
+  test("error handling: Claude failure emits planning:failed", async () => {
+    const config = createMockConfig();
+
+    mockProvider.mockResponse = {
+      result: "API Error",
+      exitCode: 1,
+      model: "claude-sonnet-4-5",
+      effortLevel: "medium",
+      duration: 50,
+    };
+
+    const planningService = new PlanningService(mockProvider, eventBus, config, logger, { fileChecker: mockFileChecker });
+
+    const events = collectEvents(eventBus, "planning:started", "planning:failed");
+
+    await expect(
+      planningService.planTasks({
+        runId: createRunId("e2e-err"),
+        parentBranch: "main",
+        requirementsPath: "/fake/req.md",
+        targetDocsDir: "/fake/docs",
+      })
+    ).rejects.toThrow();
+
+    expect(events.some(e => e.type === "planning:failed")).toBe(true);
+    const failedEvent = events.find(e => e.type === "planning:failed") as Extract<AADEvent, { type: "planning:failed" }>;
+    expect(failedEvent.error).toContain("exit code 1");
+  }, 15_000);
+
+  test("task dependency: task-2 dispatched only after task-1 completes", async () => {
+    const config = createMockConfig();
+    const stores = createStores("memory");
+
+    // Plan with dependency: task-2 depends on task-1
+    mockProvider.mockResponse = {
+      result: JSON.stringify({
+        run_id: "e2e-dep",
+        parent_branch: "main",
+        tasks: [
+          { task_id: "task-1", title: "Task 1", description: "First", files_to_modify: ["a.ts"], depends_on: [], priority: 1 },
+          { task_id: "task-2", title: "Task 2", description: "Second", files_to_modify: ["b.ts"], depends_on: ["task-1"], priority: 2 },
+        ],
+      }),
+      exitCode: 0,
+      model: "claude-sonnet-4-5",
+      effortLevel: "medium",
+      duration: 100,
+    };
+
+    const planningService = new PlanningService(mockProvider, eventBus, config, logger, { fileChecker: mockFileChecker });
+    const taskPlan = await planningService.planTasks({
+      runId: createRunId("e2e-dep"),
+      parentBranch: "main",
+      requirementsPath: "/fake/req.md",
+      targetDocsDir: "/fake/docs",
+    });
+
+    // Set up workers
+    await stores.workerStore.save({ workerId: createWorkerId("w-1"), status: "idle", currentTask: null });
+    await stores.workerStore.save({ workerId: createWorkerId("w-2"), status: "idle", currentTask: null });
+
+    const dispatchedTasks: TaskId[] = [];
+    eventBus.on("task:dispatched", (e: AADEvent) => {
+      if (e.type === "task:dispatched") dispatchedTasks.push(e.taskId);
+    });
+
+    const dispatcher = new Dispatcher({
+      taskStore: stores.taskStore,
+      workerStore: stores.workerStore,
+      runStore: stores.runStore,
+      eventBus,
+      config: { maxRetries: 0 },
+      logger,
+    });
+
+    await dispatcher.initialize(taskPlan);
+    dispatcher.start();
+
+    // Wait for first dispatch
+    await waitFor(() => dispatchedTasks.length >= 1, 3000);
+
+    // Only task-1 should be dispatched (task-2 blocked by dependency)
+    expect(dispatchedTasks).toHaveLength(1);
+    expect(dispatchedTasks[0]).toBe(createTaskId("task-1"));
+
+    // Re-add worker as idle (it was marked busy)
+    await stores.workerStore.save({ workerId: createWorkerId("w-1"), status: "idle", currentTask: null });
+
+    // Complete task-1 → should unblock task-2
+    eventBus.emit({
+      type: "task:completed",
+      taskId: createTaskId("task-1"),
+      result: { taskId: createTaskId("task-1"), status: "completed", duration: 50 },
+    });
+
+    await waitFor(() => dispatchedTasks.length >= 2, 3000);
+
+    expect(dispatchedTasks[1]).toBe(createTaskId("task-2"));
+
+    dispatcher.stop();
+  }, 15_000);
+});