npm package: @ronkovic/aad
Description: Autonomous Agent Development Orchestrator - Multi-agent TDD pipeline powered by Claude
Author: ronkovic
Latest version: 0.6.3

# 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/)
[![npm](https://img.shields.io/npm/v/@ronkovic/aad)](https://www.npmjs.com/package/@ronkovic/aad)
[![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)*
- **適応的エフォート調整**: タスク複雑度に応じてClaudeのeffort levelを自動調整
- **マルチリポジトリ対応**: 複数リポジトリにまたがるタスクの統合管理
- **プラグインシステム**: カスタムアダプター・パイプラインステップの拡張
- **Git Workspace管理**: タスクごとに独立したworktreeを自動作成・管理
- **依存関係解決**: タスク間の依存関係を自動検出し、適切な順序で実行
- **リアルタイム監視**: 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**です:

```
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 @ronkovic/aad run requirements.md
```

### グローバルインストール

```bash
bun install -g @ronkovic/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
```

## システム要件

| | RAM | 推奨ワーカー数 |
|---|---|---|
| **最小** | 8GB | 1（シングルワーカー） |
| **推奨** | 16GB | 2（並列ワーカー） |

**メモリ安全機能:**
- **自動メモリゲート** — 空きメモリが閾値を下回ると新規ワーカーの起動を抑制
- **シーケンシャルフォールバック** — メモリ不足時に並列実行から逐次実行へ自動切替
- **グレースフルシャットダウン** — メモリ圧迫時に安全にプロセスを終了
- **ランタイム監視** — 実行中のメモリ使用量をリアルタイムで監視

> **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. 要件ファイルの作成

`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

# ワーカー数を指定
aad run requirements.md --workers 4

# インタラクティブモード（対話型ウィザード）
aad
```

AADが自動的に:
1. 要件ドキュメントからfeature名を生成（例: `feat/user-auth-impl`）
2. タスクを分解・依存関係を解析
3. 親ブランチ + タスクブランチをworktreeで作成
4. ワーカーで並列実行 (TDD: テスト作成 → 実装 → 検証 → レビュー)
5. 親ブランチへのマージ

**よく使うオプション:**
- `--workers <数>`: 並列ワーカー数（デフォルト: 2）
- `--provider cli`: Claude CLIを使用（デフォルトは SDK）
- `--dry-run`: タスク一覧のみ表示（実行しない）
- `--keep-worktrees`: 完了後もworktreeを削除しない
- `--debug`: デバッグログを有効化

詳細は [コマンドリファレンス](#コマンドリファレンス) をご覧ください。

### 3. 進捗確認・管理

```bash
# ステータス確認（最新の実行）
aad status

# 特定の実行のステータス確認
aad status <run_id>

# 中断された実行の再開
aad resume <run_id>

# worktreeのクリーンアップ（parentは保護）
aad cleanup

# 特定のrunのクリーンアップ
aad cleanup <run_id>

# 強制クリーンアップ（parentも削除）
aad cleanup --force

# バージョン確認・アップデート
aad update
aad update --check
```

すべてのコマンドとオプションの詳細は [コマンドリファレンス](#コマンドリファレンス) をご覧ください。

### 4. Webダッシュボード

ダッシュボードはデフォルトで有効です。`http://localhost:7333` でリアルタイムの進捗・ログ・依存グラフを確認できます。

**ダッシュボード機能:**
- タスク進捗のリアルタイム可視化
- ワーカーステータス監視
- タスク依存グラフ (DAG)
- 構造化ログのストリーミング表示
- タスクタイムライン (Gantt)

**無効にする場合:**
```bash
aad run requirements.md --no-dashboard
```

**ポート変更:**
設定ファイル `.aad/config.json` で `dashboard.port` を変更できます。

## 開発ガイド

### 環境セットアップ

```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
  },
  "skipCompleted": true,
  "strictTdd": false
}
```

### 利用可能なモデル

`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`)またはフルネームが使用できます。

## ブランチフロー

AADは要件ドキュメントからconventional commit prefix付きのfeature名を自動生成し、以下のブランチ構造を作成します:

```
main (ソースブランチ)
  └─ feat/user-auth-impl/parent      ← 親ブランチ + worktree
       ├─ feat/user-auth-impl/task-001  ← タスクブランチ（parentから分岐）
       ├─ feat/user-auth-impl/task-002
       └─ feat/user-auth-impl/task-003
```

各タスクはparentブランチから分岐し、完了後にparentへマージされます。prefix（`feat/`, `fix/`, `refactor/`等）は要件の内容から自動判定されます。

## 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経由、重いファイル操作に最適

サービスごとに使い分け可能:

デフォルトは `sdk` です。CLIに変更する場合:

```bash
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をクリーンアップ（parentは保護）
aad cleanup

# 特定のrunのみ
aad cleanup <run_id>

# parentも含めて強制削除
aad cleanup --force
```

### タスクがスタックした

```bash
# ステータス確認
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)

## 貢献

コントリビューションを歓迎します! 詳細は [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を作成

## リンク

- [npm Package](https://www.npmjs.com/package/@ronkovic/aad)
- [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)