task-master-agent 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# task-master-agent
+
+Task Master 규칙과 워크플로우를 Antigravity, Cursor 등 AI 코딩 에이전트에 설치하는 CLI 도구입니다.
+
+PRD를 구조화된 태스크로 파싱하고, 태스크 관리·실행·검증을 AI 에이전트가 수행할 수 있도록 설정합니다.
+
+## 설치
+
+```bash
+npx task-master-agent init
+```
+
+`--force` 옵션으로 기존 파일을 덮어쓸 수 있습니다.
+
+## 설치되는 파일
+
+| 경로 | 용도 |
+|------|------|
+| `.agent/rules/task-master.md` | Task Master 역할 정의 (Antigravity) |
+| `.agent/workflows/task-next.md` | 다음 태스크 실행 워크플로우 |
+| `.agent/workflows/verify-task.md` | 태스크 검증 워크플로우 (프로젝트 구조에 맞춤 생성) |
+| `.agent/prompts/task-master-prompt.md` | 프롬프트 예시 모음 |
+| `.cursor/rules/task-master.mdc` | Cursor용 Task Master 룰 |
+
+## 프로젝트 감지
+
+`init` 실행 시 `package.json`, `pnpm-workspace.yaml`, `turbo.json`을 분석하여:
+
+- **pnpm + turbo**: `pnpm typecheck`, `pnpm lint`, `pnpm build` 사용
+- **pnpm workspaces**: `apps/*`, `packages/*` 등 워크스페이스 패키지별 검증 단계 생성
+- **단일 프로젝트**: `npm run build`, `npm run test` 등 기본 스크립트 사용
+
+`verify-task.md`가 프로젝트 구조에 맞게 자동 생성됩니다.
+
+## Antigravity 사용
+
+Antigravity는 `.agent/rules/`, `.agent/workflows/`를 **자동 발견**합니다. 수동 등록 불필요.
+
+| 슬래시 커맨드 | 용도 |
+|---------------|------|
+| `/task-next` | 다음 태스크 찾아서 구현 + 검증 |
+| `/verify-task` | 현재 작업 검증 |
+
+## Cursor 사용
+
+`.cursor/rules/task-master.mdc`는 `prd/`, `TASK_BREAKDOWN.md`, `PRODUCT_REQUIREMENTS.md` 관련 파일을 열었을 때 적용됩니다.
+
+## 필요한 프로젝트 구조
+
+- `PRODUCT_REQUIREMENTS.md` 또는 `prd/` 폴더: PRD 문서
+- `.agent/TASK_BREAKDOWN.md`: 태스크 정의 (직접 작성 또는 AI가 생성)
+- `.agent/PROJECT_CONTEXT.md`: 프로젝트 컨텍스트 (선택)
+
+## 라이선스
+
+MIT

package/bin/task-master-agent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { runInit } from "./init.js";
+const args = process.argv.slice(2);
+const force = args.includes("--force");
+const cwd = process.cwd();
+if (args.includes("init")) {
+    runInit({ cwd, force });
+}
+else {
+    console.log(`
+task-master-agent - Task Master rules for AI coding agents
+
+Usage:
+  npx task-master-agent init [--force]
+
+Options:
+  --force  Overwrite existing files
+
+After init:
+  - Antigravity: .agent/rules, .agent/workflows 자동 인식
+  - Cursor: .cursor/rules/task-master.mdc 적용
+  - Slash: /task-next, /verify-task
+`);
+}

package/dist/detect-project.d.ts

@@ -0,0 +1,9 @@
+export interface ProjectDetect {
+    packageManager: "pnpm" | "npm" | "yarn";
+    runCmd: string;
+    hasTurbo: boolean;
+    workspaces: string[];
+    workspacePackages: string[];
+    scripts: Record<string, string>;
+}
+export declare function detectProject(cwd: string): ProjectDetect;

package/dist/detect-project.js

@@ -0,0 +1,74 @@
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join } from "path";
+const DEFAULT_SCRIPTS = ["typecheck", "lint", "build", "test"];
+export function detectProject(cwd) {
+    const pkgPath = join(cwd, "package.json");
+    const pkg = existsSync(pkgPath)
+        ? JSON.parse(readFileSync(pkgPath, "utf-8"))
+        : {};
+    const pnpmWorkspacePath = join(cwd, "pnpm-workspace.yaml");
+    const hasPnpmWorkspace = existsSync(pnpmWorkspacePath);
+    const hasTurbo = existsSync(join(cwd, "turbo.json"));
+    const hasYarnWorkspace = Array.isArray(pkg.workspaces) || typeof pkg.workspaces === "object";
+    let packageManager = "npm";
+    let runCmd = "npm run";
+    let workspaces = [];
+    let workspacePackages = [];
+    if (hasPnpmWorkspace) {
+        packageManager = "pnpm";
+        runCmd = "pnpm";
+        try {
+            const content = readFileSync(pnpmWorkspacePath, "utf-8");
+            const match = content.match(/packages:\s*\n([\s\S]*?)(?=\n[A-Za-z]|\n$)/);
+            if (match) {
+                workspaces = match[1]
+                    .split("\n")
+                    .map((s) => s.trim().replace(/['"]/g, "").replace(/^-\s*/, ""))
+                    .filter((s) => s && !s.startsWith("#"));
+            }
+        }
+        catch {
+            workspaces = ["apps/*", "packages/*"];
+        }
+        workspacePackages = expandWorkspaceGlobs(cwd, workspaces);
+    }
+    else if (hasYarnWorkspace) {
+        packageManager = "yarn";
+        runCmd = "yarn";
+        const ws = pkg.workspaces;
+        workspaces = Array.isArray(ws) ? ws : ws?.packages ?? [];
+        workspacePackages = expandWorkspaceGlobs(cwd, workspaces);
+    }
+    const scripts = pkg.scripts ?? {};
+    return {
+        packageManager,
+        runCmd,
+        hasTurbo,
+        workspaces,
+        workspacePackages,
+        scripts,
+    };
+}
+function expandWorkspaceGlobs(cwd, patterns) {
+    const packages = [];
+    for (const pattern of patterns) {
+        if (pattern.includes("*")) {
+            const [base, glob] = pattern.split("/");
+            const basePath = join(cwd, base);
+            if (existsSync(basePath)) {
+                try {
+                    const entries = readdirSync(basePath, { withFileTypes: true });
+                    for (const e of entries) {
+                        if (e.isDirectory() && !e.name.startsWith(".")) {
+                            packages.push(e.name);
+                        }
+                    }
+                }
+                catch {
+                    packages.push(base.replace("*", "app"));
+                }
+            }
+        }
+    }
+    return [...new Set(packages)];
+}

package/dist/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitOptions {
+    cwd: string;
+    force?: boolean;
+}
+export declare function runInit(options: InitOptions): void;

package/dist/init.js

@@ -0,0 +1,67 @@
+import { mkdirSync, copyFileSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { render } from "ejs";
+import { detectProject } from "./detect-project.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, "..");
+const TEMPLATES = join(PKG_ROOT, "templates");
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function copyIfNotExists(src, dest, force) {
+    if (!existsSync(dest) || force) {
+        ensureDir(dirname(dest));
+        copyFileSync(src, dest);
+        return true;
+    }
+    return false;
+}
+export function runInit(options) {
+    const { cwd, force = false } = options;
+    const project = detectProject(cwd);
+    const agentRules = join(cwd, ".agent", "rules");
+    const agentWorkflows = join(cwd, ".agent", "workflows");
+    const agentPrompts = join(cwd, ".agent", "prompts");
+    const cursorRules = join(cwd, ".cursor", "rules");
+    ensureDir(agentRules);
+    ensureDir(agentWorkflows);
+    ensureDir(agentPrompts);
+    ensureDir(cursorRules);
+    const copied = [];
+    if (copyIfNotExists(join(TEMPLATES, "rules", "task-master.md"), join(agentRules, "task-master.md"), force)) {
+        copied.push(".agent/rules/task-master.md");
+    }
+    if (copyIfNotExists(join(TEMPLATES, "workflows", "task-next.md"), join(agentWorkflows, "task-next.md"), force)) {
+        copied.push(".agent/workflows/task-next.md");
+    }
+    if (copyIfNotExists(join(TEMPLATES, "cursor", "task-master.mdc"), join(cursorRules, "task-master.mdc"), force)) {
+        copied.push(".cursor/rules/task-master.mdc");
+    }
+    if (copyIfNotExists(join(TEMPLATES, "prompts", "task-master-prompt.md"), join(agentPrompts, "task-master-prompt.md"), force)) {
+        copied.push(".agent/prompts/task-master-prompt.md");
+    }
+    const verifyTaskDest = join(agentWorkflows, "verify-task.md");
+    const verifyTaskTemplate = readFileSync(join(TEMPLATES, "workflows", "verify-task.ejs"), "utf-8");
+    const verifyTaskRendered = render(verifyTaskTemplate, {
+        packageManager: project.packageManager,
+        runCmd: project.runCmd,
+        hasTurbo: project.hasTurbo,
+        workspacePackages: project.workspacePackages,
+    });
+    if (!existsSync(verifyTaskDest) || force) {
+        writeFileSync(verifyTaskDest, verifyTaskRendered);
+        copied.push(".agent/workflows/verify-task.md");
+    }
+    if (copied.length > 0) {
+        console.log("✅ task-master-agent initialized:");
+        copied.forEach((f) => console.log(`   - ${f}`));
+        console.log("\n📌 Antigravity: .agent/rules, .agent/workflows 자동 인식");
+        console.log("📌 Cursor: .cursor/rules/task-master.mdc 적용");
+    }
+    else {
+        console.log("ℹ️  task-master-agent: 이미 설치됨. --force 로 덮어쓰기 가능");
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "task-master-agent",
+  "version": "0.1.0",
+  "description": "Task Master rules and workflows for AI coding agents (Antigravity, Cursor)",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "task-master-agent": "./bin/task-master-agent.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "task-master",
+    "antigravity",
+    "cursor",
+    "ai-agent",
+    "prd",
+    "task-management"
+  ],
+  "author": "Minikanko",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Minikanko/task-master-agent.git"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "ejs": "^3.1.10"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@9.1.0"
+}

package/templates/cursor/task-master.mdc

@@ -0,0 +1,39 @@
+---
+description: Task Master 역할 - PRD 파싱, 태스크 생성/관리, 복잡도 분석
+globs: "**/prd/**","**/TASK_BREAKDOWN.md","**/PRODUCT_REQUIREMENTS.md"
+alwaysApply: false
+---
+
+# Task Master 역할
+
+PRD/태스크 관련 파일이 열려 있거나, 사용자가 태스크 관리 관련 요청을 하면 **Task Master** 역할로 동작한다.
+
+## 핵심 동작
+
+1. **PRD 파싱 → 태스크 생성**: `PRODUCT_REQUIREMENTS.md`, `prd/*.md`를 분석해 구조화된 태스크 목록 생성
+2. **태스크 확장**: 개별 태스크를 서브태스크로 세분화 (구현 상세, 완료 기준 포함)
+3. **태스크 목록/상세**: `TASK_BREAKDOWN.md` 형식으로 목록 제공 또는 특정 태스크 상세 표시
+4. **태스크 업데이트**: 사용자 요청에 따라 태스크 내용 수정
+5. **복잡도 분석**: 태스크별 난이도·예상 시간·의존성 분석 제안
+6. **태스크 실행**: `TASK_BREAKDOWN.md`의 완료 기준에 따라 구현 후 `.agent/workflows/verify-task.md` 검증 수행
+
+## 출력 형식 (TASK_BREAKDOWN.md 준수)
+
+```markdown
+### N.N 태스크 제목 [우선순위]
+**예상 시간**: Xh | **난이도**: ⭐~⭐⭐⭐
+
+#### 수행 작업
+- 항목 1
+- 항목 2
+
+#### 완료 기준
+- [ ] 기준 1
+- [ ] 기준 2
+```
+
+## 참조 문서
+
+- `.agent/TASK_BREAKDOWN.md` - 기존 태스크 정의
+- `.agent/PROJECT_CONTEXT.md` - 프로젝트 컨텍스트
+- `.agent/workflows/verify-task.md` - 태스크 완료 검증

package/templates/prompts/task-master-prompt.md

@@ -0,0 +1,46 @@
+# Task Master 모드 활성화 프롬프트
+
+> `npx task-master-agent init` 실행 후, Antigravity/Cursor에서 `.agent/rules/`와 `.agent/workflows/`가 자동으로 인식됩니다.
+
+---
+
+## Antigravity 사용
+
+파일이 `.agent/`에 있으면 Antigravity가 **자동 발견**합니다. 수동 등록 불필요.
+
+| 슬래시 커맨드 | 용도 |
+|---------------|------|
+| `/task-next` | 다음 태스크 찾아서 구현 + 검증 |
+| `/verify-task` | 현재 작업 검증 |
+
+---
+
+## 기본 활성화 (간단)
+
+```
+태스크 마스터 역할로 동작해줘. [원하는 작업]
+```
+
+---
+
+## 작업별 프롬프트 예시
+
+### PRD → 태스크 파싱
+```
+PRD(PRODUCT_REQUIREMENTS.md 또는 prd/파일)를 분석해서 구조화된 태스크 목록을 만들어줘. TASK_BREAKDOWN.md 형식으로 작성해.
+```
+
+### 다음 태스크 실행
+```
+다음 수행할 태스크를 찾아서 구현해줘. TASK_BREAKDOWN.md와 verify-task 워크플로우를 따라 검증까지 완료해.
+```
+
+### 태스크 목록 조회
+```
+대기 중인 태스크 목록을 보여줘. 우선순위와 난이도 순으로 정렬해.
+```
+
+### 복잡도 분석
+```
+현재 태스크들의 복잡도를 분석해줘. 더 세분화가 필요한 태스크가 있으면 알려줘.
+```

package/templates/rules/task-master.md

@@ -0,0 +1,24 @@
+# Task Master 역할
+
+PRD/태스크 관련 요청 시 **Task Master** 역할로 동작한다.
+
+## 핵심 동작
+
+1. **PRD 파싱** → `PRODUCT_REQUIREMENTS.md`, `prd/*.md` 분석 후 구조화된 태스크 목록 생성
+2. **태스크 확장** → 개별 태스크를 서브태스크로 세분화 (구현 상세, 완료 기준 포함)
+3. **태스크 목록/상세** → `TASK_BREAKDOWN.md` 형식으로 목록 또는 특정 태스크 상세 제공
+4. **태스크 업데이트** → 사용자 요청에 따라 태스크 내용 수정
+5. **복잡도 분석** → 태스크별 난이도·예상 시간·의존성 분석
+6. **태스크 실행** → `TASK_BREAKDOWN.md` 완료 기준에 따라 구현 후 `verify-task` 워크플로우로 검증
+
+## 출력 형식 (TASK_BREAKDOWN.md 준수)
+
+- 마커: 🔴 필수 / 🟡 권장 / 🟢 선택
+- 난이도: ⭐~⭐⭐⭐
+- 완료 기준: `- [ ]` 체크리스트
+
+## 참조 문서
+
+- @.agent/TASK_BREAKDOWN.md
+- @.agent/PROJECT_CONTEXT.md
+- @.agent/workflows/verify-task.md

package/templates/workflows/task-next.md

@@ -0,0 +1,16 @@
+---
+description: 다음 수행할 태스크를 찾아 구현하고 검증까지 완료
+---
+
+# 다음 태스크 실행
+
+1. `TASK_BREAKDOWN.md`에서 미완료 태스크 중 **가장 우선순위가 높은 것**을 선택한다.
+2. 해당 태스크의 **수행 작업**과 **완료 기준**을 확인한다.
+3. 요구사항에 따라 코드를 구현한다.
+4. 구현 완료 후 **verify-task** 워크플로우를 호출하여 검증한다.
+5. 검증 통과 시 해당 태스크의 완료 기준을 체크하고, 다음 태스크로 진행한다.
+
+## 참조
+
+- @.agent/TASK_BREAKDOWN.md
+- @.agent/workflows/verify-task.md

package/templates/workflows/verify-task.ejs

@@ -0,0 +1,66 @@
+---
+description: 태스크 완료 후 자동 검증 워크플로우
+---
+
+# 태스크 완료 후 검증 워크플로우
+
+이 워크플로우는 모든 태스크 완료 시 **반드시** 수행해야 하는 검증 단계입니다.
+
+> ⚠️ **중요**: 검증은 단순 빌드/린트 체크가 아닌, **구현된 기능과 UI가 요구사항에 부합하는지**까지 포함합니다.
+
+---
+
+## 1단계: 코드 품질 검증
+<% if (hasTurbo) { %>// turbo
+<% } %>```bash
+<%= runCmd %> typecheck
+```
+
+<% if (hasTurbo) { %>// turbo
+<% } %>```bash
+<%= runCmd %> lint
+```
+
+## 2단계: 빌드 검증
+<% if (hasTurbo) { %>// turbo
+<% } %>```bash
+<%= runCmd %> build
+```
+
+<% if (workspacePackages.length > 0) { %>## 3단계: 앱별 런타임 검증
+
+<% workspacePackages.forEach(function(pkg) { %>### <%= pkg %> 변경 시
+<% if (hasTurbo) { %>// turbo
+<% } %>```bash
+<%= packageManager === 'pnpm' ? 'pnpm --filter ' + pkg + ' dev' : runCmd + ' --workspace=' + pkg + ' dev' %>
+```
+- 변경된 화면/기능 동작 확인
+
+<% }); %>
+<% } %>## <%= workspacePackages.length > 0 ? '4' : '3' %>단계: 요구사항 충족 검증 ⭐ 핵심
+
+> 💡 **이 단계가 가장 중요합니다.** 코드가 빌드되더라도 요구사항을 충족하지 않으면 태스크 미완료입니다.
+
+### 기능 요구사항 검증
+| 검증 항목 | 확인 방법 |
+|----------|----------|
+| **명세된 기능 동작** | 태스크에 정의된 모든 기능이 실제로 동작하는가? |
+| **엣지 케이스 처리** | 빈 값, 잘못된 입력 등 예외 상황 처리가 되는가? |
+| **에러 핸들링** | 에러 발생 시 적절한 피드백이 표시되는가? |
+
+### 검증 방법
+1. **브라우저 도구 활용** - 실제 화면 캡처 및 동작 테스트
+2. **PRD 문서 대조** - `prd/*.md` 파일의 요구사항과 구현 내용 비교
+3. **TASK_BREAKDOWN.md 체크** - 완료 기준 항목 하나씩 확인
+
+---
+
+## 검증 결과 처리
+
+### ✅ 모든 검증 통과 시
+1. `TASK_BREAKDOWN.md`에서 완료 기준 항목 체크
+2. 다음 태스크로 진행
+
+### ❌ 검증 실패 시
+1. **실패 원인 분석** → 수정 → 재검증
+2. 모든 검증 통과 시까지 반복