@kmgeon/taskflow 0.1.3

package/src/cli/commands/__tests__/task-commands.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  createTask,
+  readTask,
+  listTasks,
+  updateTask,
+  ensureRepo,
+} from "@/features/taskflow/lib/repository";
+import { filterTasks, sortTasks } from "@/features/taskflow/lib/filter";
+import type { Task } from "@/features/taskflow/types";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "task-cmd-test-"));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("set-status integration", () => {
+  it("should change task status and update file", async () => {
+    const task = await createTask(tmpDir, { title: "My task", status: "Todo" });
+    const updated = await updateTask(tmpDir, task.id, { status: "InProgress" });
+
+    expect(updated.status).toBe("InProgress");
+    expect(updated.updatedAt).not.toBe(task.updatedAt);
+
+    // Verify file was persisted
+    const reRead = await readTask(tmpDir, task.id);
+    expect(reRead!.status).toBe("InProgress");
+  });
+
+  it("should update TASKS.md index after status change", async () => {
+    const task = await createTask(tmpDir, { title: "Index task" });
+    await updateTask(tmpDir, task.id, { status: "Done" });
+
+    const indexPath = path.join(tmpDir, ".taskflow", "index", "TASKS.md");
+    const content = await fs.readFile(indexPath, "utf-8");
+    expect(content).toContain("Done");
+  });
+
+  it("should reject invalid status", async () => {
+    const task = await createTask(tmpDir, { title: "Invalid" });
+    // updateTask accepts TaskUpdateInput which has TaskStatus type
+    // But we test that the CLI layer validates — here just test the type
+    const reRead = await readTask(tmpDir, task.id);
+    expect(reRead!.status).toBe("Todo");
+  });
+});
+
+describe("filter integration", () => {
+  let tasks: Task[];
+
+  beforeEach(async () => {
+    tasks = [];
+    tasks.push(await createTask(tmpDir, { title: "A", status: "Todo", priority: 3 }));
+    tasks.push(await createTask(tmpDir, { title: "B", status: "InProgress", priority: 7 }));
+    tasks.push(await createTask(tmpDir, { title: "C", status: "Done", priority: 1 }));
+    tasks.push(
+      await createTask(tmpDir, {
+        title: "D",
+        status: "Blocked",
+        priority: 5,
+        dependencies: [tasks[0].id],
+      }),
+    );
+  });
+
+  it("should filter by status", async () => {
+    const result = await listTasks(tmpDir, { filter: { status: "Todo" } });
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("A");
+  });
+
+  it("should filter by multiple statuses", async () => {
+    const result = await listTasks(tmpDir, {
+      filter: { status: ["Todo", "InProgress"] },
+    });
+    expect(result).toHaveLength(2);
+  });
+
+  it("should filter by priority", async () => {
+    const result = await listTasks(tmpDir, { filter: { priority: 7 } });
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("B");
+  });
+
+  it("should filter by hasDependency", async () => {
+    const result = await listTasks(tmpDir, {
+      filter: { hasDependency: tasks[0].id },
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("D");
+  });
+
+  it("should filter by updatedSince", async () => {
+    // All tasks were just created, so they should all pass a past date
+    const yesterday = new Date(Date.now() - 86_400_000).toISOString();
+    const result = await listTasks(tmpDir, {
+      filter: { updatedSince: yesterday },
+    });
+    expect(result).toHaveLength(4);
+
+    // Future date should return none
+    const tomorrow = new Date(Date.now() + 86_400_000).toISOString();
+    const result2 = await listTasks(tmpDir, {
+      filter: { updatedSince: tomorrow },
+    });
+    expect(result2).toHaveLength(0);
+  });
+
+  it("should sort by priority descending", async () => {
+    const result = await listTasks(tmpDir, {
+      sortKey: "priority",
+      sortOrder: "desc",
+    });
+    expect(result.map((t) => t.priority)).toEqual([7, 5, 3, 1]);
+  });
+
+  it("should sort by status order", async () => {
+    const result = await listTasks(tmpDir, {
+      sortKey: "status",
+      sortOrder: "asc",
+    });
+    expect(result.map((t) => t.status)).toEqual([
+      "Todo",
+      "InProgress",
+      "Blocked",
+      "Done",
+    ]);
+  });
+});
+
+describe("performance", () => {
+  it("should list 1000 tasks under 200ms", async () => {
+    await ensureRepo(tmpDir);
+
+    // Batch create 1000 task files directly for speed
+    const tasksDir = path.join(tmpDir, ".taskflow", "tasks");
+    const writes = Array.from({ length: 1000 }, (_, i) => {
+      const id = String(i + 1).padStart(4, "0");
+      const content = [
+        "---",
+        `id: '${id}'`,
+        `title: Task ${id}`,
+        "status: Todo",
+        `priority: ${(i % 10) + 1}`,
+        `createdAt: '2026-03-21T00:00:00.000Z'`,
+        `updatedAt: '2026-03-21T00:00:00.000Z'`,
+        "---",
+        `Description for task ${id}`,
+        "",
+      ].join("\n");
+      return fs.writeFile(path.join(tasksDir, `task-${id}.md`), content, "utf-8");
+    });
+    await Promise.all(writes);
+
+    const start = performance.now();
+    const tasks = await listTasks(tmpDir);
+    const elapsed = performance.now() - start;
+
+    expect(tasks).toHaveLength(1000);
+    expect(elapsed).toBeLessThan(1000);
+  });
+});

package/src/cli/commands/advisor.ts

@@ -0,0 +1,45 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import { ensureRepo } from "@/features/taskflow/lib/repository";
+import { getAdvisorDbPath } from "@/features/taskflow/constants";
+import { AdvisorDb } from "@/features/taskflow/lib/advisor/db";
+
+export function registerAdvisorCommand(program: Command) {
+  program
+    .command("advisor")
+    .description("AI 비서 관리 유틸리티")
+    .option("--cleanup", "만료된 대화 로그를 삭제합니다 (기본: 7일)")
+    .option("--days <n>", "로그 보관 기간 (일)", parseInt, 7)
+    .option("--stats", "DB 통계를 표시합니다")
+    .action(
+      withCliErrorBoundary(async (opts: { cleanup?: boolean; days: number; stats?: boolean }) => {
+        const projectRoot = process.cwd();
+        await ensureRepo(projectRoot);
+
+        const db = await AdvisorDb.open(getAdvisorDbPath(projectRoot));
+
+        if (opts.cleanup) {
+          const deleted = db.deleteExpiredLogs(opts.days);
+          await db.persistToDisk();
+          console.log(chalk.green(`✔ ${deleted}개의 만료된 로그를 삭제했습니다.`));
+        }
+
+        if (opts.stats) {
+          const stats = db.getStats();
+          console.log("");
+          console.log(chalk.bold("📊 Advisor DB 통계"));
+          console.log(`  대화 로그: ${stats.logCount}개`);
+          console.log(`  결정 기록: ${stats.decisionCount}개`);
+          console.log(`  DB 크기: ${(stats.dbSizeBytes / 1024).toFixed(1)} KB`);
+          console.log("");
+        }
+
+        if (!opts.cleanup && !opts.stats) {
+          console.log(chalk.yellow("옵션을 지정해주세요. --help로 사용법을 확인하세요."));
+        }
+
+        db.close();
+      })
+    );
+}

package/src/cli/commands/ask.ts

@@ -0,0 +1,50 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import { ensureRepo } from "@/features/taskflow/lib/repository";
+import { getAdvisorDbPath } from "@/features/taskflow/constants";
+import { AdvisorDb } from "@/features/taskflow/lib/advisor/db";
+import { buildContext } from "@/features/taskflow/lib/advisor/context-builder";
+import { getAnswer } from "@/features/taskflow/lib/advisor/ai-advisor";
+
+export function registerAskCommand(program: Command) {
+  program
+    .command("ask")
+    .description("AI 비서에게 프로젝트에 대해 자유롭게 질문합니다")
+    .argument("<question>", "질문 내용")
+    .action(
+      withCliErrorBoundary(async (question: string) => {
+        const projectRoot = process.cwd();
+        await ensureRepo(projectRoot);
+
+        const spinner = ora("답변 생성 중...").start();
+
+        try {
+          const db = await AdvisorDb.open(getAdvisorDbPath(projectRoot));
+          const context = await buildContext({
+            command: "ask",
+            projectRoot,
+            db,
+            question,
+          });
+
+          const answer = await getAnswer(context, question);
+
+          const sessionId = `ask-${Date.now()}`;
+          db.insertLog("ask", sessionId, "user", question);
+          db.insertLog("ask", sessionId, "assistant", answer);
+          db.persistToDiskAsync();
+          db.close();
+
+          spinner.stop();
+          console.log("");
+          console.log(answer);
+          console.log("");
+        } catch {
+          spinner.stop();
+          console.log(chalk.red("AI 연결 실패. 잠시 후 다시 시도해주세요."));
+        }
+      })
+    );
+}

package/src/cli/commands/board.ts

@@ -0,0 +1,72 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { listTasks } from "@/features/taskflow/lib/repository";
+import { formatKanbanBoard } from "../lib/formatter.js";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import type { Task } from "@/features/taskflow/types";
+import { getTrdGroupNames } from "../lib/trd.js";
+
+function formatGroupBoard(tasks: Task[], trdGroupNames: string[]): void {
+  const groups = new Map<string, Task[]>();
+
+  // TRD 그룹을 먼저 빈 상태로 등록
+  for (const name of trdGroupNames) {
+    groups.set(name, []);
+  }
+
+  for (const task of tasks) {
+    const name = task.group ?? "(그룹 없음)";
+    let list = groups.get(name);
+    if (!list) {
+      list = [];
+      groups.set(name, list);
+    }
+    list.push(task);
+  }
+
+  for (const [name, groupTasks] of groups) {
+    const done = groupTasks.filter((t) => t.status === "Done").length;
+    const total = groupTasks.length;
+    const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+
+    console.log(chalk.bold(`\n── ${name} (${pct}% · ${done}/${total}) ──\n`));
+    console.log(formatKanbanBoard(groupTasks, { compact: true }));
+  }
+}
+
+export function registerBoardCommand(program: Command) {
+  program
+    .command("board")
+    .alias("kb")
+    .description("칸반보드 형태로 태스크를 출력합니다 (그룹별)")
+    .option("--detail [group]", "특정 그룹의 상세 칸반보드")
+    .action(
+      withCliErrorBoundary(
+        async (opts: { detail?: string | boolean }) => {
+          const projectRoot = process.cwd();
+          const tasks = await listTasks(projectRoot);
+          const trdGroups = getTrdGroupNames(projectRoot);
+
+          if (tasks.length === 0 && trdGroups.length === 0) {
+            console.log(chalk.yellow("\n⚠ 태스크가 없습니다.\n"));
+            return;
+          }
+
+          if (opts.detail !== undefined) {
+            const groupFilter = typeof opts.detail === "string" ? opts.detail : undefined;
+            const filtered = groupFilter
+              ? tasks.filter((t) => t.group?.includes(groupFilter))
+              : tasks;
+
+            console.log("");
+            console.log(formatKanbanBoard(filtered, { compact: false }));
+            console.log("");
+            return;
+          }
+
+          formatGroupBoard(tasks, trdGroups);
+          console.log(chalk.gray("\n  상세 보기: task board --detail [그룹명]\n"));
+        },
+      ),
+    );
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,184 @@
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import type { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import { initProject } from "../../core/project/init.js";
+import { readConfig, writeConfig } from "../../core/project/config.js";
+import { generateClaudeMd, generateMcpJson, appendClaudeImport, appendDocsReference, setupPlugins } from "../../core/project/claude-setup.js";
+import { installSkills } from "../../core/project/skill-setup.js";
+import { installDocs } from "../../core/project/docs-setup.js";
+import { SKILL_TEMPLATES } from "../../core/project/skill-templates.js";
+import { scanFiles, sampleFiles } from "../../core/prd/scanner.js";
+import { savePrd } from "../../core/prd/generator.js";
+import { runPrdBrainstorm } from "../../core/ai/claude-client.js";
+
+export function registerInitCommand(program: Command) {
+  program
+    .command("init")
+    .description("Initialize a new TaskFlow project (setup + Claude Code integration)")
+    .action(
+      withCliErrorBoundary(async () => {
+        const cwd = process.cwd();
+        const taskflowDir = join(cwd, ".taskflow");
+        const alreadyExists = existsSync(taskflowDir);
+
+        if (alreadyExists) {
+          await handleReinit(cwd);
+        } else {
+          await handleNewInit(cwd);
+        }
+      }),
+    );
+}
+
+async function handleNewInit(cwd: string): Promise<void> {
+  console.log(chalk.bold("\n🚀 TaskFlow 프로젝트를 초기화합니다.\n"));
+
+  // Step 1: Create directory + config
+  const spinner = ora("프로젝트 구조 생성 중...").start();
+  await initProject(cwd);
+  spinner.succeed("프로젝트 구조 생성 완료");
+
+  // Step 2: .mcp.json
+  const mcpSpinner = ora("Claude Code 연동 설정 중...").start();
+  await generateMcpJson(cwd);
+  mcpSpinner.succeed("Claude Code 연동 설정 완료 (.mcp.json)");
+
+  // Step 3: Generate CLAUDE.md
+  const config = await readConfig(cwd);
+  const claudeSpinner = ora("CLAUDE.md 생성 중...").start();
+  await generateClaudeMd(cwd, { projectName: config.project.name || basename(cwd) });
+  claudeSpinner.succeed("CLAUDE.md 생성 완료");
+
+  // Step 4: Append import to root CLAUDE.md
+  await appendClaudeImport(cwd);
+  console.log(chalk.green("✔ 루트 CLAUDE.md에 TaskFlow import 추가 완료"));
+
+  // Step 5: Install docs
+  const docsSpinner = ora("개발 가이드라인 문서 생성 중...").start();
+  await installDocs(cwd);
+  docsSpinner.succeed("개발 가이드라인 문서 생성 완료 (docs/)");
+
+  // Step 5.1: Append docs reference to root CLAUDE.md
+  await appendDocsReference(cwd);
+  console.log(chalk.green("✔ 루트 CLAUDE.md에 docs 참조 추가 완료"));
+
+  // Step 6: Install skills + symlinks
+  const skillSpinner = ora("Claude Code 스킬 설치 중...").start();
+  await installSkills(cwd);
+  skillSpinner.succeed("Claude Code 스킬 설치 완료");
+
+  // Step 7: Setup plugins (superpowers, ralph-loop)
+  const pluginSpinner = ora("Claude Code 플러그인 설정 중...").start();
+  await setupPlugins(cwd);
+  pluginSpinner.succeed("Claude Code 플러그인 설정 완료 (superpowers, ralph-loop)");
+
+  // Step 6: PRD generation
+  const { generatePrd } = await inquirer.prompt<{ generatePrd: boolean }>([
+    {
+      type: "confirm",
+      name: "generatePrd",
+      message: "PRD를 지금 생성하시겠습니까? (Claude와 대화형으로 진행)",
+      default: true,
+    },
+  ]);
+
+  if (generatePrd) {
+    console.log(chalk.cyan("\n💬 PRD 브레인스토밍을 시작합니다...\n"));
+
+    // Scan codebase for context
+    const scanSpinner = ora("코드베이스 분석 중...").start();
+    let projectContext = "";
+    try {
+      const files = await scanFiles(cwd);
+      if (files.length > 0) {
+        const samples = await sampleFiles(files, cwd);
+        projectContext = JSON.stringify({ files, samples: samples.slice(0, 20) }, null, 2);
+      }
+      scanSpinner.succeed(`코드베이스 분석 완료 (${files.length}개 파일)`);
+    } catch {
+      scanSpinner.warn("코드베이스 분석 스킵");
+    }
+
+    try {
+      const result = await runPrdBrainstorm({
+        projectRoot: cwd,
+        systemPrompt: SKILL_TEMPLATES.prd,
+        projectContext,
+      });
+
+      if (result) {
+        await savePrd(cwd, result.markdown);
+        console.log(chalk.green("\n✔ PRD 저장 완료: .taskflow/prd.md"));
+
+        // Update config with project name
+        const currentConfig = await readConfig(cwd);
+        currentConfig.project.name = result.projectName;
+        await writeConfig(cwd, currentConfig);
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`\n⚠ PRD 생성 스킵: ${error instanceof Error ? error.message : "알 수 없는 오류"}`));
+      console.log(chalk.gray("  나중에 Claude Code에서 /prd 명령어로 생성할 수 있습니다."));
+    }
+  }
+
+  console.log(chalk.bold.green("\n✅ TaskFlow 초기화가 완료되었습니다!\n"));
+  console.log(chalk.gray("  다음 단계 (Claude Code에서):"));
+  console.log(chalk.gray("  /prd              PRD 대화형 생성"));
+  console.log(chalk.gray("  /parse-prd        PRD → 태스크 분해"));
+  console.log(chalk.gray("  /next             다음 태스크 추천\n"));
+}
+
+async function handleReinit(cwd: string): Promise<void> {
+  console.log(chalk.yellow("\n⚠ TaskFlow 프로젝트가 이미 초기화되어 있습니다.\n"));
+
+  // Re-install docs (create missing docs only)
+  const docsSpinner = ora("개발 가이드라인 문서 확인 중...").start();
+  await installDocs(cwd);
+  docsSpinner.succeed("개발 가이드라인 문서 확인 완료");
+
+  // Re-install skills (update to latest templates)
+  const skillSpinner = ora("스킬 업데이트 중...").start();
+  await installSkills(cwd);
+  skillSpinner.succeed("스킬 업데이트 완료");
+
+  const { regeneratePrd } = await inquirer.prompt<{ regeneratePrd: boolean }>([
+    {
+      type: "confirm",
+      name: "regeneratePrd",
+      message: "PRD를 다시 생성하시겠습니까?",
+      default: false,
+    },
+  ]);
+
+  if (regeneratePrd) {
+    console.log(chalk.cyan("\n💬 PRD 브레인스토밍을 시작합니다...\n"));
+
+    try {
+      const files = await scanFiles(cwd);
+      const samples = files.length > 0 ? await sampleFiles(files, cwd) : [];
+      const projectContext =
+        files.length > 0
+          ? JSON.stringify({ files, samples: samples.slice(0, 20) }, null, 2)
+          : "";
+
+      const result = await runPrdBrainstorm({
+        projectRoot: cwd,
+        systemPrompt: SKILL_TEMPLATES.prd,
+        projectContext,
+      });
+
+      if (result) {
+        await savePrd(cwd, result.markdown);
+        console.log(chalk.green("\n✔ PRD 저장 완료: .taskflow/prd.md"));
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`\n⚠ PRD 생성 실패: ${error instanceof Error ? error.message : "알 수 없는 오류"}`));
+    }
+  }
+
+  console.log(chalk.gray("\n  Claude Code에서 /prd 명령어로도 PRD를 생성/재생성할 수 있습니다.\n"));
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,138 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { listTasks } from "@/features/taskflow/lib/repository";
+import { formatTaskTable, formatDashboard } from "../lib/formatter.js";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import type { Task, TaskStatus, TaskSortKey, TaskSortOrder } from "@/features/taskflow/types";
+import { TASK_STATUSES } from "@/features/taskflow/types";
+import { getTrdGroupNames } from "../lib/trd.js";
+
+function parseStatus(value: string): TaskStatus {
+  if (!(TASK_STATUSES as readonly string[]).includes(value)) {
+    throw new Error(
+      `유효하지 않은 상태입니다: ${value}\n  허용: ${TASK_STATUSES.join(", ")}`,
+    );
+  }
+  return value as TaskStatus;
+}
+
+function formatGroupList(tasks: Task[], trdGroupNames: string[]): void {
+  const groups = new Map<string, { total: number; done: number; inProgress: number; blocked: number }>();
+
+  // TRD 그룹을 먼저 빈 상태로 등록
+  for (const name of trdGroupNames) {
+    groups.set(name, { total: 0, done: 0, inProgress: 0, blocked: 0 });
+  }
+
+  for (const task of tasks) {
+    const name = task.group ?? "(그룹 없음)";
+    let g = groups.get(name);
+    if (!g) {
+      g = { total: 0, done: 0, inProgress: 0, blocked: 0 };
+      groups.set(name, g);
+    }
+    g.total++;
+    if (task.status === "Done") g.done++;
+    if (task.status === "InProgress") g.inProgress++;
+    if (task.status === "Blocked") g.blocked++;
+  }
+
+  console.log(chalk.bold("\n📋 요구사항 그룹 목록:\n"));
+
+  for (const [name, g] of groups) {
+    const ratio = g.total > 0 ? g.done / g.total : 0;
+    const barLen = 10;
+    const filled = Math.round(ratio * barLen);
+    const bar = chalk.green("█".repeat(filled)) + chalk.gray("░".repeat(barLen - filled));
+    const pct = Math.round(ratio * 100);
+
+    let status = "";
+    if (g.total === 0) {
+      status = chalk.dim("태스크 없음 — task run으로 시작");
+    } else if (g.done === g.total) {
+      status = chalk.green("완료!");
+    } else {
+      const parts: string[] = [`${g.done}/${g.total}`];
+      if (g.inProgress > 0) parts.push(chalk.hex("#FFA500")(`${g.inProgress} 진행중`));
+      if (g.blocked > 0) parts.push(chalk.red(`${g.blocked} 블로커`));
+      status = parts.join(" · ");
+    }
+
+    console.log(`  ${bar}  ${chalk.bold(name)}  ${chalk.gray(`${pct}%`)}  ${status}`);
+  }
+
+  console.log(chalk.gray(`\n총 ${groups.size}개 그룹, ${tasks.length}개 태스크`));
+}
+
+export function registerListCommand(program: Command) {
+  program
+    .command("list")
+    .alias("ls")
+    .description("태스크 목록을 출력합니다")
+    .option("--detail [group]", "개별 태스크 상세 보기 (그룹명 지정 가능)")
+    .option("--status <status>", "상태로 필터 (Todo, InProgress, Blocked, Done)")
+    .option("--priority <n>", "우선순위로 필터", parseInt)
+    .option("--dep <id>", "특정 태스크에 의존하는 태스크만 표시")
+    .option("--updated-since <date>", "지정 날짜 이후 업데이트된 태스크만 (YYYY-MM-DD)")
+    .option("--sort <key>", "정렬 기준 (priority, status, createdAt, updatedAt, title)", "priority")
+    .option("--order <dir>", "정렬 방향 (asc, desc)", "desc")
+    .action(
+      withCliErrorBoundary(
+        async (opts: {
+          detail?: string | boolean;
+          status?: string;
+          priority?: number;
+          dep?: string;
+          updatedSince?: string;
+          sort?: string;
+          order?: string;
+        }) => {
+          const projectRoot = process.cwd();
+
+          const tasks = await listTasks(projectRoot, {
+            filter: {
+              status: opts.status ? parseStatus(opts.status) : undefined,
+              priority: opts.priority,
+              hasDependency: opts.dep,
+              updatedSince: opts.updatedSince
+                ? new Date(opts.updatedSince).toISOString()
+                : undefined,
+            },
+            sortKey: (opts.sort as TaskSortKey) ?? "priority",
+            sortOrder: (opts.order as TaskSortOrder) ?? "desc",
+          });
+
+          // --detail: 개별 태스크 보기
+          if (opts.detail !== undefined) {
+            const groupFilter = typeof opts.detail === "string" ? opts.detail : undefined;
+            const filtered = groupFilter
+              ? tasks.filter((t) => t.group?.includes(groupFilter))
+              : tasks;
+
+            // Dashboard
+            const dashboard = formatDashboard(filtered);
+            if (dashboard) {
+              console.log("");
+              console.log(dashboard);
+            }
+
+            console.log("");
+            console.log(formatTaskTable(filtered));
+            console.log("");
+            console.log(chalk.gray(`총 ${filtered.length}건`));
+            return;
+          }
+
+          // 기본: 그룹 단위 보기
+          const trdGroups = getTrdGroupNames(projectRoot);
+          if (tasks.length === 0 && trdGroups.length === 0) {
+            console.log(chalk.yellow("\n⚠ 태스크가 없습니다.\n"));
+            return;
+          }
+
+          formatGroupList(tasks, trdGroups);
+          console.log(chalk.gray("\n  개별 태스크 보기: task list --detail [그룹명]\n"));
+        },
+      ),
+    );
+}