@ronkovic/aad 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronkovic/aad",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Autonomous Agent Development Orchestrator - Multi-agent TDD pipeline powered by Claude",
   "module": "src/main.ts",
   "type": "module",
@@ -38,11 +38,12 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.34",
+    "@inquirer/prompts": "^8.2.0",
+    "chokidar": "^4.0",
+    "commander": "^13.0",
     "hono": "^4.6",
     "pino": "^9.6",
     "pino-pretty": "^13.0",
-    "chokidar": "^4.0",
-    "commander": "^13.0",
     "zod": "^3.24"
   },
   "devDependencies": {

package/src/main.ts

@@ -11,9 +11,11 @@ import {
   createResumeCommand,
   createStatusCommand,
   createCleanupCommand,
+  createUpdateCommand,
   type App,
   type AppOptions,
 } from "./modules/cli";
+import { registerInteractiveCommand } from "./modules/cli/commands/interactive.js";
 import packageJson from "../package.json" with { type: "json" };
 
 const program = new Command()
@@ -47,6 +49,12 @@ program.addCommand(createRunCommand(getApp));
 program.addCommand(createResumeCommand(getApp));
 program.addCommand(createStatusCommand(getApp));
 program.addCommand(createCleanupCommand(getApp));
+program.addCommand(createUpdateCommand());
+registerInteractiveCommand(program);
 
-// Parse CLI args
-program.parse();
+// Default to interactive mode when no command is given
+if (process.argv.length <= 2) {
+  program.parse(["node", "aad", "interactive"]);
+} else {
+  program.parse();
+}

package/src/modules/cli/__tests__/interactive/auth-step.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { runAuthStep } from "../../commands/interactive/auth-step";
+
+// Mock @inquirer/prompts by testing the env detection logic directly
+describe("Auth Step", () => {
+  let origApiKey: string | undefined;
+  let origOauth: string | undefined;
+
+  beforeEach(() => {
+    origApiKey = process.env.ANTHROPIC_API_KEY;
+    origOauth = process.env.CLAUDE_CODE_OAUTH_TOKEN;
+  });
+
+  afterEach(() => {
+    if (origApiKey !== undefined) process.env.ANTHROPIC_API_KEY = origApiKey;
+    else delete process.env.ANTHROPIC_API_KEY;
+    if (origOauth !== undefined) process.env.CLAUDE_CODE_OAUTH_TOKEN = origOauth;
+    else delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
+  });
+
+  it("module exports runAuthStep function", () => {
+    expect(typeof runAuthStep).toBe("function");
+  });
+});

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

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "bun:test";
+import { registerInteractiveCommand } from "../../commands/interactive";
+import { Command } from "commander";
+
+describe("Interactive Command Registration", () => {
+  it("registers interactive command on program", () => {
+    const program = new Command();
+    registerInteractiveCommand(program);
+
+    const cmd = program.commands.find((c) => c.name() === "interactive");
+    expect(cmd).toBeDefined();
+    expect(cmd?.description()).toContain("Interactive");
+  });
+});

package/src/modules/cli/__tests__/interactive/process-supervisor.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "bun:test";
+import { spawnProject, killAll } from "../../commands/interactive/process-supervisor";
+import type { ProjectConfig } from "../../commands/interactive/project-step";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+
+describe("Process Supervisor", () => {
+  it("exports spawnProject and killAll functions", () => {
+    expect(typeof spawnProject).toBe("function");
+    expect(typeof killAll).toBe("function");
+  });
+
+  it("spawns a simple process and returns ManagedProcess", async () => {
+    const tmpDir = mkdtempSync(resolve(tmpdir(), "aad-test-"));
+    const project: ProjectConfig = {
+      directory: tmpDir,
+      branch: "main",
+      requirementsPath: "/dev/null",
+      workers: 1,
+    };
+
+    const mp = spawnProject(project, 0);
+    expect(mp.dashboardPort).toBe(7333);
+    expect(mp.project).toBe(project);
+    expect(mp.proc).toBeDefined();
+
+    // Kill immediately
+    await killAll([mp]);
+  });
+
+  it("increments dashboard port by index", async () => {
+    const tmpDir = mkdtempSync(resolve(tmpdir(), "aad-test-"));
+    const project: ProjectConfig = {
+      directory: tmpDir,
+      branch: "main",
+      requirementsPath: "/dev/null",
+      workers: 1,
+    };
+
+    const mp = spawnProject(project, 3);
+    expect(mp.dashboardPort).toBe(7336);
+    await killAll([mp]);
+  });
+});

package/src/modules/cli/__tests__/interactive/prompts.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "bun:test";
+import { printBox, success, warn, error } from "../../commands/interactive/prompts";
+
+describe("Interactive Prompts Utilities", () => {
+  describe("printBox", () => {
+    it("prints a box with lines", () => {
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => logs.push(args.join(" "));
+      try {
+        printBox(["line 1", "line 2"]);
+        expect(logs.length).toBe(4); // top + 2 lines + bottom
+        expect(logs[0]).toContain("┌");
+        expect(logs[3]).toContain("└");
+      } finally {
+        console.log = origLog;
+      }
+    });
+
+    it("prints a box with title", () => {
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => logs.push(args.join(" "));
+      try {
+        printBox(["content"], "Title");
+        expect(logs.length).toBe(5); // top + title + separator + content + bottom
+        expect(logs[1]).toContain("Title");
+        expect(logs[2]).toContain("├");
+      } finally {
+        console.log = origLog;
+      }
+    });
+  });
+
+  describe("status helpers", () => {
+    it("success prints green check", () => {
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => logs.push(args.join(" "));
+      try {
+        success("done");
+        expect(logs[0]).toContain("✓");
+        expect(logs[0]).toContain("done");
+      } finally {
+        console.log = origLog;
+      }
+    });
+
+    it("warn prints yellow warning", () => {
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => logs.push(args.join(" "));
+      try {
+        warn("caution");
+        expect(logs[0]).toContain("⚠");
+        expect(logs[0]).toContain("caution");
+      } finally {
+        console.log = origLog;
+      }
+    });
+
+    it("error prints red cross", () => {
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => logs.push(args.join(" "));
+      try {
+        error("fail");
+        expect(logs[0]).toContain("✗");
+        expect(logs[0]).toContain("fail");
+      } finally {
+        console.log = origLog;
+      }
+    });
+  });
+});

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

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "bun:test";
+import { createUpdateCommand } from "../commands/update";
+
+describe("Update Command", () => {
+  it("creates a command named 'update'", () => {
+    const cmd = createUpdateCommand();
+    expect(cmd.name()).toBe("update");
+  });
+
+  it("has --check option", () => {
+    const cmd = createUpdateCommand();
+    const checkOpt = cmd.options.find((o) => o.long === "--check");
+    expect(checkOpt).toBeDefined();
+  });
+
+  it("has description", () => {
+    const cmd = createUpdateCommand();
+    expect(cmd.description()).toContain("Update");
+  });
+});

package/src/modules/cli/commands/cleanup.ts

@@ -102,10 +102,10 @@ export async function cleanupWorktrees(
   await worktreeManager.pruneWorktrees();
   logger.info("Pruned orphaned worktrees");
 
-  // 4. Cleanup orphaned branches
+  // 4. Cleanup orphaned branches (always force-delete — AAD branches are safe to remove)
   const deletedBranches = runId
-    ? await branchManager.cleanupOrphanBranches(runId)
-    : await branchManager.cleanupOrphanBranches();
+    ? await branchManager.cleanupOrphanBranches(runId, true)
+    : await branchManager.cleanupOrphanBranches(undefined, true);
 
   if (deletedBranches.length > 0) {
     console.log(`\nDeleted ${deletedBranches.length} orphan branch(es):`);

package/src/modules/cli/commands/interactive/auth-step.ts

@@ -0,0 +1,61 @@
+/**
+ * Auth check / input step for interactive mode
+ */
+import { askConfirm, askSelect, askPassword, success, warn } from "./prompts.js";
+
+export interface AuthResult {
+  method: "api-key" | "oauth";
+  token: string;
+}
+
+function maskToken(token: string): string {
+  if (token.length <= 8) return "••••••••";
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+export async function runAuthStep(): Promise<AuthResult> {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const oauthToken = process.env.CLAUDE_CODE_OAUTH_TOKEN;
+
+  // Existing API key detected
+  if (apiKey) {
+    console.log(`\n  API Key検出: ${maskToken(apiKey)}`);
+    const useExisting = await askConfirm("この設定を使用しますか？", true);
+    if (useExisting) {
+      success("API Key認証を使用");
+      return { method: "api-key", token: apiKey };
+    }
+  }
+
+  // Existing OAuth token detected
+  if (oauthToken) {
+    console.log(`\n  OAuth Token検出: ${maskToken(oauthToken)}`);
+    const useExisting = await askConfirm("この設定を使用しますか？", true);
+    if (useExisting) {
+      success("OAuth認証を使用");
+      return { method: "oauth", token: oauthToken };
+    }
+  }
+
+  // Manual input
+  if (!apiKey && !oauthToken) {
+    warn("認証トークンが未設定です");
+  }
+
+  const method = await askSelect<"api-key" | "oauth">("認証方式を選択:", [
+    { name: "API Key (ANTHROPIC_API_KEY)", value: "api-key" },
+    { name: "OAuth Token (CLAUDE_CODE_OAUTH_TOKEN)", value: "oauth" },
+  ]);
+
+  const token = await askPassword("トークンを入力:");
+
+  // Set in process env for this session
+  if (method === "api-key") {
+    process.env.ANTHROPIC_API_KEY = token;
+  } else {
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = token;
+  }
+
+  success(`${method === "api-key" ? "API Key" : "OAuth"}認証を設定（セッション限定）`);
+  return { method, token };
+}

package/src/modules/cli/commands/interactive/launch-step.ts

@@ -0,0 +1,76 @@
+/**
+ * Launch confirmation + execution step
+ */
+import { basename } from "node:path";
+import { getMemoryStatus } from "@aad/shared/memory-check";
+import type { ProjectConfig } from "./project-step.js";
+import {
+  type ManagedProcess,
+  spawnAll,
+  setupSignalHandler,
+} from "./process-supervisor.js";
+import { askConfirm, printBox, success } from "./prompts.js";
+
+function formatPlanLines(projects: ProjectConfig[]): string[] {
+  const lines: string[] = [];
+  for (let i = 0; i < projects.length; i++) {
+    const p = projects[i]!;
+    lines.push(`#${i + 1} ${p.directory}`);
+    lines.push(`   ブランチ: ${p.branch}`);
+    lines.push(`   要件: ${p.requirementsPath}`);
+    lines.push(`   ワーカー: ${p.workers}`);
+    if (i < projects.length - 1) lines.push("");
+  }
+  return lines;
+}
+
+export async function runLaunchStep(
+  projects: ProjectConfig[],
+): Promise<ManagedProcess[] | null> {
+  const memStatus = await getMemoryStatus();
+  const availableGB = memStatus.freeGB;
+  const totalWorkers = projects.reduce((sum, p) => sum + p.workers, 0);
+
+  const planLines = formatPlanLines(projects);
+  planLines.push("");
+  planLines.push(
+    `合計ワーカー: ${totalWorkers}  メモリ: ${availableGB.toFixed(1)}GB free`,
+  );
+
+  printBox(planLines, "実行プラン");
+  console.log();
+
+  const confirmed = await askConfirm("実行しますか？", true);
+  if (!confirmed) {
+    console.log("\n  実行をキャンセルしました\n");
+    return null;
+  }
+
+  console.log();
+  const managed = spawnAll(projects);
+
+  for (const mp of managed) {
+    const name = basename(mp.project.directory);
+    success(`${name} 起動 — Dashboard: http://localhost:${mp.dashboardPort}`);
+  }
+
+  setupSignalHandler(managed);
+
+  console.log("\n  全プロジェクト起動完了。ダッシュボードで進捗を確認できます。");
+  console.log("  終了: Ctrl+C (全プロジェクト停止)\n");
+
+  // Wait for all processes to complete
+  const exitCodes = await Promise.all(managed.map((mp) => mp.proc.exited));
+  for (let i = 0; i < exitCodes.length; i++) {
+    const mp = managed[i]!;
+    const code = exitCodes[i]!;
+    const name = basename(mp.project.directory);
+    if (code === 0) {
+      success(`${name} 完了 (exit: 0)`);
+    } else {
+      console.log(`  \x1b[31m✗\x1b[0m ${name} 終了 (exit: ${code})`);
+    }
+  }
+
+  return managed;
+}

package/src/modules/cli/commands/interactive/process-supervisor.ts

@@ -0,0 +1,105 @@
+/**
+ * Child process management — spawn, monitor, and terminate AAD runs
+ */
+import { resolve } from "node:path";
+import { mkdirSync, existsSync, openSync } from "node:fs";
+import type { ProjectConfig } from "./project-step.js";
+
+const BASE_DASHBOARD_PORT = 7333;
+
+export interface ManagedProcess {
+  project: ProjectConfig;
+  proc: ReturnType<typeof Bun.spawn>;
+  dashboardPort: number;
+  logDir: string;
+}
+
+function ensureLogDir(directory: string, runId: string): string {
+  const logDir = resolve(directory, ".aad", "logs", runId);
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+  return logDir;
+}
+
+function generateRunId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+}
+
+export function spawnProject(
+  project: ProjectConfig,
+  index: number,
+): ManagedProcess {
+  const runId = generateRunId();
+  const logDir = ensureLogDir(project.directory, runId);
+  const dashboardPort = BASE_DASHBOARD_PORT + index;
+
+  const stdoutFd = openSync(resolve(logDir, "stdout.log"), "w");
+  const stderrFd = openSync(resolve(logDir, "stderr.log"), "w");
+
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "run",
+      resolve(import.meta.dir, "../../../../main.ts"),
+      "run",
+      project.requirementsPath,
+      "--branch",
+      project.branch,
+      "--workers",
+      String(project.workers),
+    ],
+    {
+      cwd: project.directory,
+      stdout: stdoutFd,
+      stderr: stderrFd,
+      env: {
+        ...process.env,
+        AAD_DASHBOARD_PORT: String(dashboardPort),
+      },
+    },
+  );
+
+  return { project, proc, dashboardPort, logDir };
+}
+
+export function spawnAll(projects: ProjectConfig[]): ManagedProcess[] {
+  return projects.map((project, i) => spawnProject(project, i));
+}
+
+export async function killAll(processes: ManagedProcess[]): Promise<void> {
+  for (const mp of processes) {
+    try {
+      mp.proc.kill("SIGTERM");
+    } catch {
+      // Process may have already exited
+    }
+  }
+
+  // Wait for all to exit (with timeout)
+  const timeout = setTimeout(() => {
+    for (const mp of processes) {
+      try {
+        mp.proc.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+    }
+  }, 5000);
+
+  await Promise.allSettled(processes.map((mp) => mp.proc.exited));
+  clearTimeout(timeout);
+}
+
+export function setupSignalHandler(processes: ManagedProcess[]): void {
+  const handler = (): void => {
+    console.log("\n\n  全プロセスを停止中...");
+    void killAll(processes).then(() => {
+      console.log("  停止完了\n");
+      process.exit(0);
+    });
+  };
+
+  process.on("SIGINT", handler);
+  process.on("SIGTERM", handler);
+}

package/src/modules/cli/commands/interactive/project-step.ts

@@ -0,0 +1,157 @@
+/**
+ * Project configuration step — repeatable loop
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { gitExec } from "@aad/git-workspace/git-exec";
+import { getMemoryStatus } from "@aad/shared/memory-check";
+import {
+  askConfirm,
+  askInput,
+  askSelect,
+  success,
+  warn,
+  error,
+} from "./prompts.js";
+
+export interface ProjectConfig {
+  directory: string;
+  branch: string;
+  requirementsPath: string;
+  workers: number;
+}
+
+async function isGitRepo(dir: string): Promise<boolean> {
+  try {
+    await gitExec(["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listBranches(dir: string): Promise<string[]> {
+  const result = await gitExec(["branch", "--format=%(refname:short)"], {
+    cwd: dir,
+  });
+  return result.stdout
+    .split("\n")
+    .map((b: string) => b.trim())
+    .filter(Boolean);
+}
+
+async function getCurrentBranch(dir: string): Promise<string> {
+  const result = await gitExec(["branch", "--show-current"], { cwd: dir });
+  return result.stdout.trim();
+}
+
+async function pullBranch(dir: string, branch: string): Promise<boolean> {
+  try {
+    await gitExec(["checkout", branch], { cwd: dir });
+    await gitExec(["pull", "--ff-only"], { cwd: dir });
+    success(`${branch} を最新に更新`);
+    return true;
+  } catch (e) {
+    warn(`git pull失敗: ${e instanceof Error ? e.message : String(e)}`);
+    return false;
+  }
+}
+
+function suggestWorkers(availableGB: number): number {
+  if (availableGB >= 12) return 3;
+  if (availableGB >= 8) return 2;
+  return 1;
+}
+
+async function configureProject(index: number): Promise<ProjectConfig> {
+  console.log(`\n── プロジェクト #${index + 1} ──\n`);
+
+  // Directory
+  const directory = await askInput("プロジェクトディレクトリパス:", {
+    validate: (v) => {
+      const resolved = resolve(v);
+      if (!existsSync(resolved)) return "ディレクトリが存在しません";
+      if (!statSync(resolved).isDirectory()) return "ディレクトリではありません";
+      return true;
+    },
+  });
+
+  const resolvedDir = resolve(directory);
+
+  if (!(await isGitRepo(resolvedDir))) {
+    error("gitリポジトリが検出されませんでした");
+    throw new Error(`Not a git repository: ${resolvedDir}`);
+  }
+  success("gitリポジトリ検出");
+
+  // Branch selection
+  const branches = await listBranches(resolvedDir);
+  const currentBranch = await getCurrentBranch(resolvedDir);
+  const branchChoices = branches.map((b) => ({
+    name: b === currentBranch ? `${b} (現在)` : b,
+    value: b,
+  }));
+
+  const branch = await askSelect("worktree元ブランチ:", branchChoices);
+
+  // Pull
+  const doPull = await askConfirm("ブランチを最新にしますか？ (git pull)", true);
+  if (doPull) {
+    await pullBranch(resolvedDir, branch);
+  }
+
+  // Requirements file
+  const requirementsPath = await askInput("要件定義ドキュメントパス:", {
+    validate: (v) => {
+      const absPath = resolve(resolvedDir, v);
+      if (!existsSync(absPath)) return `ファイルが存在しません: ${absPath}`;
+      return true;
+    },
+  });
+  success("ファイル存在確認");
+
+  // Workers
+  const memStatus = await getMemoryStatus();
+  const availableGB = memStatus.freeGB;
+  const suggested = suggestWorkers(availableGB);
+
+  const workersStr = await askInput(
+    `並行ワーカー数 (推奨: ${suggested}, 空きメモリ: ${availableGB.toFixed(1)}GB):`,
+    {
+      default: String(suggested),
+      validate: (v) => {
+        const n = parseInt(v, 10);
+        if (isNaN(n) || n < 1) return "1以上の整数を入力してください";
+        if (n > 8) return "最大8ワーカーまでです";
+        return true;
+      },
+    },
+  );
+
+  const workers = parseInt(workersStr, 10);
+
+  console.log(`\n────────────────────────────`);
+  console.log(`  プロジェクト #${index + 1} 設定完了`);
+  console.log(`────────────────────────────`);
+
+  return {
+    directory: resolvedDir,
+    branch,
+    requirementsPath: resolve(resolvedDir, requirementsPath),
+    workers,
+  };
+}
+
+export async function runProjectStep(): Promise<ProjectConfig[]> {
+  const projects: ProjectConfig[] = [];
+
+  // At least one project
+  projects.push(await configureProject(0));
+
+  // Additional projects
+  while (await askConfirm("別のプロジェクトを追加しますか？", false)) {
+    projects.push(await configureProject(projects.length));
+  }
+
+  return projects;
+}

package/src/modules/cli/commands/interactive/prompts.ts

@@ -0,0 +1,75 @@
+/**
+ * Interactive UI utility wrappers around @inquirer/prompts
+ */
+import { confirm, input, select, password } from "@inquirer/prompts";
+
+export interface Choice<T> {
+  name: string;
+  value: T;
+  description?: string;
+}
+
+export async function askConfirm(
+  message: string,
+  defaultValue = true,
+): Promise<boolean> {
+  return confirm({ message, default: defaultValue });
+}
+
+export async function askInput(
+  message: string,
+  opts?: { default?: string; validate?: (v: string) => string | true },
+): Promise<string> {
+  return input({
+    message,
+    default: opts?.default,
+    validate: opts?.validate,
+  });
+}
+
+export async function askSelect<T>(
+  message: string,
+  choices: Array<Choice<T>>,
+): Promise<T> {
+  return select({ message, choices });
+}
+
+export async function askPassword(message: string): Promise<string> {
+  return password({ message, mask: "•" });
+}
+
+export function printBox(lines: string[], title?: string): void {
+  const maxLen = Math.max(
+    title?.length ?? 0,
+    ...lines.map((l) => stripAnsi(l).length),
+  );
+  const width = maxLen + 2;
+  const border = "─".repeat(width);
+
+  console.log(`┌${border}┐`);
+  if (title) {
+    console.log(`│ ${title.padEnd(width - 1)}│`);
+    console.log(`├${border}┤`);
+  }
+  for (const line of lines) {
+    const pad = width - 1 - stripAnsi(line).length;
+    console.log(`│ ${line}${" ".repeat(Math.max(0, pad))}│`);
+  }
+  console.log(`└${border}┘`);
+}
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function success(msg: string): void {
+  console.log(`  \x1b[32m✓\x1b[0m ${msg}`);
+}
+
+export function warn(msg: string): void {
+  console.log(`  \x1b[33m⚠\x1b[0m ${msg}`);
+}
+
+export function error(msg: string): void {
+  console.log(`  \x1b[31m✗\x1b[0m ${msg}`);
+}

package/src/modules/cli/commands/interactive.ts

@@ -0,0 +1,38 @@
+/**
+ * Interactive mode — main entry point
+ * Launched when `aad` is run with no arguments
+ */
+import type { Command } from "commander";
+import { runAuthStep } from "./interactive/auth-step.js";
+import { runProjectStep } from "./interactive/project-step.js";
+import { runLaunchStep } from "./interactive/launch-step.js";
+
+export function registerInteractiveCommand(program: Command): void {
+  program
+    .command("interactive")
+    .description("Interactive setup wizard for multi-project AAD execution")
+    .action(async () => {
+      console.log();
+      console.log("  ┌─────────────────────────────────────┐");
+      console.log("  │  AAD Interactive Mode                │");
+      console.log("  └─────────────────────────────────────┘");
+      console.log();
+
+      // Phase 1: Auth
+      console.log("  ── Step 1: 認証設定 ──\n");
+      await runAuthStep();
+
+      // Phase 2: Project setup
+      console.log("\n  ── Step 2: プロジェクト設定 ──");
+      const projects = await runProjectStep();
+
+      if (projects.length === 0) {
+        console.log("\n  プロジェクトが設定されていません。終了します。\n");
+        return;
+      }
+
+      // Phase 3: Launch
+      console.log("\n  ── Step 3: 実行 ──\n");
+      await runLaunchStep(projects);
+    });
+}

package/src/modules/cli/commands/resume.ts

@@ -122,7 +122,31 @@ export async function resumeRun(app: App, runIdStr: string): Promise<void> {
     stores: { runStore: stores.runStore, taskStore: stores.taskStore },
     logger,
   });
-  registerTaskDispatchHandler({ app, runId, parentBranch: runState.parentBranch });
+  // Check if parent worktree exists from a previous run
+  const parentWorktreePath = `${process.cwd()}/.aad/worktrees/parent-${runId}`;
+  const parentWorktreeExists = await Bun.file(`${parentWorktreePath}/.git`).exists();
+  // Detect feature branch name from parent worktree
+  let featureBranchName: string | undefined;
+  if (parentWorktreeExists) {
+    try {
+      const branchResult = await import("../../git-workspace").then(
+        (m) => m.getCurrentBranch(parentWorktreePath),
+      );
+      if (branchResult?.startsWith("aad/")) {
+        featureBranchName = branchResult;
+      }
+    } catch {
+      // Fallback: no feature branch detection
+    }
+  }
+
+  registerTaskDispatchHandler({
+    app,
+    runId,
+    parentBranch: runState.parentBranch,
+    parentWorktreePath: parentWorktreeExists ? parentWorktreePath : undefined,
+    featureBranchName,
+  });
 
   // 6. Dispatcher.start()
   dispatcher.start();

package/src/modules/cli/commands/run.ts

@@ -12,6 +12,7 @@ import { getCurrentBranch, cleanupOrphanedFromPreviousRuns } from "../../git-wor
 import { checkMemoryAndWarn } from "../../../shared/memory-check";
 import { installShutdownHandler } from "../../../shared/shutdown-handler";
 import { registerTaskDispatchHandler } from "./task-dispatch-handler";
+import { generateFeatureName } from "../../planning/feature-name-generator";
 
 export function createRunCommand(getApp: () => App): Command {
   const command = new Command("run")
@@ -44,7 +45,7 @@ export function createRunCommand(getApp: () => App): Command {
  * メインパイプライン実行
  */
 export async function runPipeline(app: App, requirementsPath: string, keepWorktrees = false): Promise<void> {
-  const { config, logger, eventBus, planningService, dispatcher, processManager, worktreeManager, stores, branchManager } = app;
+  const { config, logger, eventBus, planningService, dispatcher, processManager, worktreeManager, stores, branchManager, providerRegistry } = app;
 
   // Validate requirements file exists
   const reqFile = Bun.file(requirementsPath);
@@ -144,8 +145,27 @@ export async function runPipeline(app: App, requirementsPath: string, keepWorktr
     logger,
   });
 
-  // 5. Register task dispatch handler (shared with resume)
-  registerTaskDispatchHandler({ app, runId, parentBranch });
+  // 5. Generate feature name and create parent worktree with real branch
+  let parentWorktreePath: string | undefined;
+  let featureBranchName: string | undefined;
+  try {
+    const featureName = await generateFeatureName(
+      requirementsPath,
+      providerRegistry.getProvider("implementer"),
+      logger,
+    );
+    featureBranchName = `aad/${featureName}/parent`;
+    const result = await worktreeManager.createParentWorktree(runId, parentBranch, featureBranchName);
+    parentWorktreePath = result.worktreePath;
+    featureBranchName = result.branch;
+    logger.info({ parentWorktreePath, featureBranchName }, "Parent worktree created for merging");
+    console.log(`🌿 Feature Branch: ${featureBranchName}`);
+  } catch (error) {
+    logger.warn({ error }, "Failed to create parent worktree, using repo root as fallback");
+  }
+
+  // 5.5. Register task dispatch handler (shared with resume)
+  registerTaskDispatchHandler({ app, runId, parentBranch, parentWorktreePath, featureBranchName });
 
   // 6. 進捗表示
   const progressSpinner = createSpinner("Executing tasks...");
@@ -210,7 +230,7 @@ export async function runPipeline(app: App, requirementsPath: string, keepWorktr
       const worktreeBase = `${process.cwd()}/.aad/worktrees`;
       const runWorktrees = worktrees.filter(
         (wt) => wt.path.startsWith(worktreeBase) 
-             && wt.branch.includes(runId)  // Check branch name for runId
+             && (wt.branch.includes(runId) || (featureBranchName && wt.branch.startsWith(featureBranchName.replace(/\/parent$/, ""))))  // Match by runId or feature name
              && !wt.path.includes(`parent-${runId}`)  // Keep parent worktree (contains merge results)
       );
 
@@ -230,7 +250,17 @@ export async function runPipeline(app: App, requirementsPath: string, keepWorktr
       await worktreeManager.pruneWorktrees();
 
       // Cleanup orphaned branches for this run (force delete merged branches)
-      const deletedBranches = await branchManager.cleanupOrphanBranches(runId, true);
+      let deletedBranches = await branchManager.cleanupOrphanBranches(runId, true);
+
+      // Also cleanup feature-named branches if applicable
+      if (featureBranchName) {
+        const featurePrefix = featureBranchName.replace(/\/parent$/, "");
+        const featureBranches = await branchManager.cleanupOrphanBranches(
+          createRunId(featurePrefix.replace("aad/", "")),
+          true,
+        );
+        deletedBranches = [...deletedBranches, ...featureBranches];
+      }
 
       console.log(`  Removed ${removed} worktree(s)`);
       console.log(`  Deleted ${deletedBranches.length} branch(es)`);

package/src/modules/cli/commands/task-dispatch-handler.ts

@@ -25,6 +25,12 @@ export interface TaskDispatchContext {
   app: App;
   runId: RunId;
   parentBranch: string;
+  /** Path to the parent worktree where task branches are merged into.
+   *  If not provided, falls back to process.cwd() (repo root). */
+  parentWorktreePath?: string;
+  /** Feature branch name (e.g. aad/auth-feature/parent).
+   *  Task branches are created from this branch. */
+  featureBranchName?: string;
 }
 
 /**
@@ -32,7 +38,8 @@ export interface TaskDispatchContext {
  * Handles memory gate, worker state, worktree creation, and TDD pipeline execution.
  */
 export function registerTaskDispatchHandler(ctx: TaskDispatchContext): void {
-  const { app, runId, parentBranch } = ctx;
+  const { app, runId, parentBranch, parentWorktreePath, featureBranchName } = ctx;
+  const mergeTarget = parentWorktreePath ?? process.cwd();
   const { eventBus, logger, config, processManager, worktreeManager, providerRegistry, stores } = app;
 
   let memoryGateLock: Promise<void> = Promise.resolve();
@@ -53,8 +60,13 @@ export function registerTaskDispatchHandler(ctx: TaskDispatchContext): void {
         throw new Error(`Task not found: ${taskId}`);
       }
 
-      const branchName = `aad/${runId}/${taskId}`;
-      const worktreePath = await worktreeManager.createTaskWorktree(taskId, branchName);
+      // Derive task branch name from feature branch or runId
+      // e.g. aad/auth-feature/task-001 (from aad/auth-feature/parent)
+      const branchPrefix = featureBranchName
+        ? featureBranchName.replace(/\/parent$/, "")
+        : `aad/${runId}`;
+      const branchName = `${branchPrefix}/${taskId}`;
+      const worktreePath = await worktreeManager.createTaskWorktree(taskId, branchName, featureBranchName);
       logger.info({ taskId, worktreePath, branchName }, "Worktree created");
 
       const workspace = await detectWorkspace(worktreePath, logger);
@@ -63,7 +75,7 @@ export function registerTaskDispatchHandler(ctx: TaskDispatchContext): void {
 
       const provider = providerRegistry.getProvider("implementer");
       const result = await executeTddPipeline(
-        task, workspace, branchName, parentBranch, process.cwd(),
+        task, workspace, branchName, parentBranch, mergeTarget,
         runId, app.config, provider, app.mergeService, eventBus,
       );
 

package/src/modules/cli/commands/update.ts

@@ -0,0 +1,119 @@
+/**
+ * `aad update` — Self-update AAD to the latest version
+ */
+import { Command } from "commander";
+import packageJson from "../../../../package.json" with { type: "json" };
+
+interface UpdateOptions {
+  check: boolean;
+}
+
+async function exec(
+  cmd: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(cmd, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+}
+
+async function getLatestVersion(): Promise<string | null> {
+  try {
+    const result = await exec(["npm", "view", "@ronkovic/aad", "version"]);
+    if (result.exitCode === 0 && result.stdout) {
+      return result.stdout;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function compareVersions(current: string, latest: string): number {
+  const c = current.split(".").map(Number);
+  const l = latest.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((c[i] ?? 0) < (l[i] ?? 0)) return -1;
+    if ((c[i] ?? 0) > (l[i] ?? 0)) return 1;
+  }
+  return 0;
+}
+
+function detectPackageManager(): "bun" | "npm" {
+  if (process.env.BUN_INSTALL || process.argv[0]?.includes("bun")) {
+    return "bun";
+  }
+  return "npm";
+}
+
+async function clearBunxCache(): Promise<boolean> {
+  const cacheDir = `/private/tmp/bunx-${process.getuid?.() ?? 502}-@ronkovic/`;
+  try {
+    const result = await exec(["rm", "-rf", cacheDir]);
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function createUpdateCommand(): Command {
+  return new Command("update")
+    .description("Update AAD to the latest version")
+    .option("--check", "Check for updates without installing", false)
+    .action(async (opts: UpdateOptions) => {
+      const currentVersion = packageJson.version;
+      console.log(`\n  現在のバージョン: v${currentVersion}`);
+
+      console.log("  最新バージョンを確認中...");
+      const latestVersion = await getLatestVersion();
+
+      if (!latestVersion) {
+        console.log("  \x1b[31m✗\x1b[0m レジストリからバージョン情報を取得できませんでした\n");
+        process.exit(1);
+      }
+
+      console.log(`  最新バージョン:   v${latestVersion}`);
+
+      const cmp = compareVersions(currentVersion, latestVersion);
+      if (cmp >= 0) {
+        console.log("  \x1b[32m✓\x1b[0m 最新バージョンです\n");
+        return;
+      }
+
+      if (opts.check) {
+        console.log(`  \x1b[33m⚠\x1b[0m 更新可能: v${currentVersion} → v${latestVersion}\n`);
+        return;
+      }
+
+      // Perform update
+      const pm = await detectPackageManager();
+      console.log(`\n  パッケージマネージャ: ${pm}`);
+
+      if (pm === "bun") {
+        console.log("  bunxキャッシュをクリア中...");
+        await clearBunxCache();
+        console.log("  \x1b[32m✓\x1b[0m キャッシュクリア完了");
+        console.log(`\n  次回 \`bunx @ronkovic/aad\` 実行時にv${latestVersion}が使用されます\n`);
+      } else {
+        console.log("  npm install中...");
+        const result = await exec([
+          "npm",
+          "install",
+          "-g",
+          `@ronkovic/aad@${latestVersion}`,
+        ]);
+        if (result.exitCode === 0) {
+          console.log(`  \x1b[32m✓\x1b[0m v${latestVersion}にアップデートしました\n`);
+        } else {
+          console.log(`  \x1b[31m✗\x1b[0m アップデート失敗: ${result.stderr}\n`);
+          process.exit(1);
+        }
+      }
+    });
+}

package/src/modules/cli/index.ts

@@ -21,6 +21,7 @@ export { createRunCommand, runPipeline } from "./commands/run";
 export { createResumeCommand, resumeRun } from "./commands/resume";
 export { createStatusCommand, displayStatus } from "./commands/status";
 export { createCleanupCommand, cleanupWorktrees } from "./commands/cleanup";
+export { createUpdateCommand } from "./commands/update";
 
 export {
   createShutdownManager,

package/src/modules/git-workspace/__tests__/worktree-manager.test.ts

@@ -71,15 +71,30 @@ describe("WorktreeManager", () => {
   });
 
   describe("createParentWorktree", () => {
-    test("creates worktree on existing branch", async () => {
+    test("creates worktree with feature branch", async () => {
       const runId = createRunId("run-001");
       const parentBranch = "main";
+      const featureBranch = "aad/auth-feature/parent";
 
-      const worktreePath = await worktreeManager.createParentWorktree(runId, parentBranch);
+      const result = await worktreeManager.createParentWorktree(runId, parentBranch, featureBranch);
 
-      expect(worktreePath).toBe("/test/worktrees/parent-run-001");
+      expect(result.worktreePath).toBe("/test/worktrees/parent-run-001");
+      expect(result.branch).toBe(featureBranch);
       expect(mockGitOps.gitExec).toHaveBeenCalledWith(
-        ["worktree", "add", "/test/worktrees/parent-run-001", parentBranch],
+        ["worktree", "add", "-b", featureBranch, "/test/worktrees/parent-run-001", parentBranch],
+        expect.objectContaining({ cwd: repoRoot })
+      );
+    });
+
+    test("uses default branch name when featureBranch not provided", async () => {
+      const runId = createRunId("run-001");
+      const parentBranch = "main";
+
+      const result = await worktreeManager.createParentWorktree(runId, parentBranch);
+
+      expect(result.branch).toBe("aad/run-001/parent");
+      expect(mockGitOps.gitExec).toHaveBeenCalledWith(
+        ["worktree", "add", "-b", "aad/run-001/parent", "/test/worktrees/parent-run-001", parentBranch],
         expect.objectContaining({ cwd: repoRoot })
       );
     });

package/src/modules/git-workspace/worktree-manager.ts

@@ -41,10 +41,11 @@ export class WorktreeManager {
   /**
    * Create worktree for a task
    */
-  async createTaskWorktree(taskId: TaskId, branch: string): Promise<string> {
+  async createTaskWorktree(taskId: TaskId, branch: string, baseBranch?: string): Promise<string> {
     const worktreePath = join(this.worktreeBase, taskId as string);
+    const startPoint = baseBranch ?? "HEAD";
 
-    this.logger?.info({ taskId, branch, worktreePath }, "Creating task worktree");
+    this.logger?.info({ taskId, branch, baseBranch: startPoint, worktreePath }, "Creating task worktree");
 
     try {
       // Ensure worktree base directory exists
@@ -53,9 +54,9 @@ export class WorktreeManager {
       // Clean up stale worktree/branch if they already exist
       await this.cleanupStaleWorktree(worktreePath, branch);
 
-      // Create worktree with new branch
+      // Create worktree with new branch from baseBranch (parent feature branch)
       await this.gitOps.gitExec(
-        ["worktree", "add", "-b", branch, worktreePath, "HEAD"],
+        ["worktree", "add", "-b", branch, worktreePath, startPoint],
         { cwd: this.repoRoot, logger: this.logger }
       );
 
@@ -113,25 +114,32 @@ export class WorktreeManager {
   /**
    * Create worktree for parent branch (used for merging)
    */
-  async createParentWorktree(runId: RunId, parentBranch: string): Promise<string> {
+  async createParentWorktree(
+    runId: RunId,
+    parentBranch: string,
+    featureBranch?: string,
+  ): Promise<{ worktreePath: string; branch: string }> {
     const worktreePath = join(this.worktreeBase, `parent-${runId as string}`);
+    const branch = featureBranch ?? `aad/${runId as string}/parent`;
 
-    this.logger?.info({ runId, parentBranch, worktreePath }, "Creating parent worktree");
+    this.logger?.info({ runId, parentBranch, branch, worktreePath }, "Creating parent worktree");
 
     try {
       await this.fsOps.mkdir(this.worktreeBase, { recursive: true });
 
-      // Create worktree on existing branch (no -b flag)
+      // Create worktree with a new branch based on parentBranch
+      // e.g. git worktree add -b aad/auth-feature/parent <path> main
       await this.gitOps.gitExec(
-        ["worktree", "add", worktreePath, parentBranch],
+        ["worktree", "add", "-b", branch, worktreePath, parentBranch],
         { cwd: this.repoRoot, logger: this.logger }
       );
 
-      return worktreePath;
+      return { worktreePath, branch };
     } catch (error) {
       throw new GitWorkspaceError("Failed to create parent worktree", {
         runId: runId as string,
         parentBranch,
+        branch,
         worktreePath,
         error: error instanceof Error ? error.message : String(error),
       });

package/src/modules/planning/__tests__/feature-name-generator.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "bun:test";
+import { sanitizeBranchName, generateFeatureName } from "../feature-name-generator";
+import type { ClaudeProvider } from "../../claude-provider";
+
+describe("Feature Name Generator", () => {
+  describe("sanitizeBranchName", () => {
+    it("converts to lowercase", () => {
+      expect(sanitizeBranchName("Auth-Feature")).toBe("auth-feature");
+    });
+
+    it("removes invalid characters", () => {
+      expect(sanitizeBranchName("hello world!@#")).toBe("hello-world");
+    });
+
+    it("collapses multiple hyphens", () => {
+      expect(sanitizeBranchName("a--b---c")).toBe("a-b-c");
+    });
+
+    it("removes leading/trailing hyphens", () => {
+      expect(sanitizeBranchName("-hello-")).toBe("hello");
+    });
+
+    it("truncates to 20 characters", () => {
+      expect(sanitizeBranchName("this-is-a-very-long-branch-name-that-exceeds-limit").length).toBeLessThanOrEqual(20);
+    });
+
+    it("handles empty string", () => {
+      expect(sanitizeBranchName("")).toBe("");
+    });
+
+    it("handles Japanese characters (fallback)", () => {
+      expect(sanitizeBranchName("認証機能")).toBe("");
+    });
+  });
+
+  describe("generateFeatureName", () => {
+    it("uses Claude result when successful", async () => {
+      const mockProvider: ClaudeProvider = {
+        call: async () => ({
+          result: "  auth-login  \n",
+          exitCode: 0,
+          model: "claude-haiku-4-5",
+          effortLevel: "low" as const,
+          duration: 100,
+        }),
+      };
+
+      const name = await generateFeatureName("/dev/null", mockProvider);
+      expect(name).toBe("auth-login");
+    });
+
+    it("falls back to filename on provider error", async () => {
+      const mockProvider: ClaudeProvider = {
+        call: async () => { throw new Error("API error"); },
+      };
+
+      const name = await generateFeatureName("/some/path/auth-feature.md", mockProvider);
+      expect(name).toBe("auth-feature");
+    });
+
+    it("falls back to filename when result too short", async () => {
+      const mockProvider: ClaudeProvider = {
+        call: async () => ({
+          result: "ab",
+          exitCode: 0,
+          model: "claude-haiku-4-5",
+          effortLevel: "low" as const,
+          duration: 100,
+        }),
+      };
+
+      const name = await generateFeatureName("/path/user-signup.md", mockProvider);
+      expect(name).toBe("user-signup");
+    });
+  });
+});

package/src/modules/planning/feature-name-generator.ts

@@ -0,0 +1,71 @@
+/**
+ * Feature Name Generator
+ * Generates a short English feature name from a requirements document.
+ * Used for branch naming: aad/{featureName}/parent, aad/{featureName}/task-001
+ *
+ * Ported from .aad/scripts/run-parallel.sh extract_requirement_title()
+ */
+import type { ClaudeProvider } from "../claude-provider";
+import type pino from "pino";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const FEATURE_NAME_PROMPT = `You are a branch name generator. Given the requirements below, output ONLY a short English identifier suitable for a git branch name.
+
+Rules:
+- Lowercase alphanumeric and hyphens only
+- 20 characters max
+- No explanation, no decoration, just the identifier
+
+Requirements:
+`;
+
+/**
+ * Sanitize a string to be a valid git branch name component
+ */
+export function sanitizeBranchName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 20);
+}
+
+/**
+ * Generate a feature name from requirements file using Claude
+ * Falls back to filename-based name on failure
+ */
+export async function generateFeatureName(
+  requirementsPath: string,
+  provider: ClaudeProvider,
+  logger?: pino.Logger,
+): Promise<string> {
+  try {
+    // Read first 20 lines of requirements
+    const fullContent = await readFile(requirementsPath, "utf-8");
+    const content = fullContent.split("\n").slice(0, 20).join("\n");
+
+    const result = await provider.call({
+      prompt: FEATURE_NAME_PROMPT + content,
+      model: "claude-haiku-4-5",
+    });
+
+    const rawName = result.result.trim();
+
+    const sanitized = sanitizeBranchName(rawName);
+
+    if (sanitized.length >= 3) {
+      logger?.info({ featureName: sanitized, raw: rawName }, "Feature name generated");
+      return sanitized;
+    }
+  } catch (error) {
+    logger?.warn({ error }, "Feature name generation failed, using fallback");
+  }
+
+  // Fallback: filename-based
+  const fallback = sanitizeBranchName(
+    basename(requirementsPath).replace(/\.[^.]*$/, ""),
+  );
+  return fallback || "default";
+}