@kmgeon/taskflow 0.1.3

package/src/core/project/claude-setup.ts

@@ -0,0 +1,224 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DOCS_NAMES } from "./docs-setup.js";
+
+const TASKFLOW_DIR = ".taskflow";
+const CLAUDE_MD = "CLAUDE.md";
+const MCP_JSON = ".mcp.json";
+const IMPORT_LINE = "@./.taskflow/CLAUDE.md";
+const DOCS_SECTION_MARKER = "<!-- docs-reference -->";
+
+export interface ClaudeMdContext {
+  projectName: string;
+  summary?: string;
+  stack?: string[];
+}
+
+export async function generateClaudeMd(
+  projectRoot: string,
+  ctx: ClaudeMdContext,
+): Promise<void> {
+  const date = new Date().toISOString().split("T")[0];
+  const stackLine = ctx.stack?.length ? ctx.stack.join(", ") : "N/A";
+
+  const content = `# TaskFlow — ${ctx.projectName} 개발 가이드
+
+## 프로젝트 정보
+- 이름: ${ctx.projectName}
+- 설명: ${ctx.summary ?? "N/A"}
+- 기술 스택: ${stackLine}
+- 생성일: ${date}
+
+## TaskFlow MCP 도구
+
+이 프로젝트는 TaskFlow로 태스크를 관리합니다.
+아래 MCP 도구를 사용하여 태스크를 조회하고 관리하세요.
+
+### 태스크 관리
+- \`list_tasks\` — 태스크 목록 조회 (필터: status, priority)
+- \`read_task\` — 태스크 상세 조회
+- \`create_task\` — 새 태스크 생성
+- \`update_task\` — 태스크 수정
+- \`delete_task\` — 태스크 삭제
+- \`set_task_status\` — 상태 변경
+- \`get_next_task\` — 의존성/우선순위 기반 다음 태스크 추천
+- \`expand_subtasks\` — 서브태스크 파일 생성
+
+### PRD & 코드베이스
+- \`scan_codebase\` — 코드베이스 파일 목록/시그니처 스캔
+- \`save_prd\` — PRD 마크다운 저장
+- \`read_prd\` — PRD 읽기
+
+### 프로젝트
+- \`initialize_project\` — 프로젝트 초기화
+- \`generate_claude_md\` — CLAUDE.md 재생성
+
+## Claude Code 스킬
+
+다음 스킬 커맨드를 사용하여 워크플로우를 실행할 수 있습니다:
+- \`/prd\` — PRD 대화형 생성
+- \`/trd\` — PRD 기반 TRD 생성
+- \`/parse-prd\` — PRD → 태스크 분해
+- \`/brainstorm\` — 태스크 서브태스크 분해
+- \`/refine\` — 요구사항 변경 영향 분석
+- \`/next\` — 다음 작업할 태스크 추천
+- \`/task-status\` — 진행 상황 요약
+
+## 워크플로우
+
+### 새 기능 구현 시
+1. \`/next\`로 다음 태스크 확인
+2. \`set_task_status\` → in-progress
+3. 구현 완료 후 \`set_task_status\` → done
+
+### PRD → 태스크 생성
+1. \`/prd\`로 PRD 대화형 생성
+2. \`/trd\`로 구현 계획 작성
+3. \`/parse-prd\`로 태스크 분해
+
+### 요구사항 변경 시
+1. \`/refine\`으로 영향 받는 태스크 분석
+2. 영향 받는 태스크 확인 및 수정
+
+## 파일 구조
+- \`.taskflow/config.json\` — 프로젝트 설정
+- \`.taskflow/prd.md\` — PRD 문서
+- \`.taskflow/trd.md\` — TRD 문서
+- \`.taskflow/tasks/task-{NNN}.md\` — 개별 태스크 파일
+`;
+
+  const filePath = path.join(projectRoot, TASKFLOW_DIR, CLAUDE_MD);
+  await fs.writeFile(filePath, content, "utf-8");
+}
+
+export async function generateMcpJson(projectRoot: string): Promise<void> {
+  const filePath = path.join(projectRoot, MCP_JSON);
+
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    existing = JSON.parse(raw);
+  } catch {
+    // file does not exist or invalid JSON
+  }
+
+  const mcpServers = (existing.mcpServers as Record<string, unknown>) ?? {};
+  mcpServers.taskflow = {
+    type: "stdio",
+    command: "node",
+    args: ["./bin/task-mcp.mjs"],
+    env: {},
+  };
+
+  const merged = { ...existing, mcpServers };
+  await fs.writeFile(filePath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+
+export async function appendClaudeImport(projectRoot: string): Promise<void> {
+  const filePath = path.join(projectRoot, CLAUDE_MD);
+
+  let existing = "";
+  try {
+    existing = await fs.readFile(filePath, "utf-8");
+  } catch {
+    // file does not exist
+  }
+
+  if (existing.includes(IMPORT_LINE)) {
+    return;
+  }
+
+  const importBlock = `\n## TaskFlow\n${IMPORT_LINE}\n`;
+
+  if (existing.trim()) {
+    const content = existing.endsWith("\n") ? existing + importBlock : existing + "\n" + importBlock;
+    await fs.writeFile(filePath, content, "utf-8");
+  } else {
+    const content = `# Claude Code Instructions\n${importBlock}`;
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+}
+
+const DEFAULT_PLUGINS: Record<string, boolean> = {
+  "superpowers@claude-plugins-official": true,
+  "ralph-loop@claude-plugins-official": true,
+};
+
+/**
+ * .claude/settings.local.json에 enabledPlugins를 추가한다.
+ * 이미 설정된 플러그인은 덮어쓰지 않는다.
+ */
+export async function setupPlugins(projectRoot: string): Promise<void> {
+  const settingsPath = path.join(projectRoot, ".claude", "settings.local.json");
+
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = await fs.readFile(settingsPath, "utf-8");
+    existing = JSON.parse(raw);
+  } catch {
+    // file does not exist or invalid JSON
+  }
+
+  const enabledPlugins = (existing.enabledPlugins as Record<string, boolean>) ?? {};
+
+  for (const [plugin, enabled] of Object.entries(DEFAULT_PLUGINS)) {
+    if (!(plugin in enabledPlugins)) {
+      enabledPlugins[plugin] = enabled;
+    }
+  }
+
+  const merged = { ...existing, enabledPlugins };
+
+  await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+  await fs.writeFile(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+
+export async function appendDocsReference(projectRoot: string): Promise<void> {
+  const filePath = path.join(projectRoot, CLAUDE_MD);
+
+  let existing = "";
+  try {
+    existing = await fs.readFile(filePath, "utf-8");
+  } catch {
+    // file does not exist
+  }
+
+  if (existing.includes(DOCS_SECTION_MARKER)) {
+    return;
+  }
+
+  const docsList = DOCS_NAMES.map((name) => `- ${name}.md: ./docs/${name}.md`).join("\n");
+
+  const docsBlock = `
+${DOCS_SECTION_MARKER}
+For every request:
+
+1. Always refer to the documentation files stored under \`/docs\`:
+<docs>
+${docsList}
+</docs>
+
+2. Use the relevant file(s) depending on the context of the request.
+3. Never ignore these files. Consider them for:
+    - Providing accurate information
+    - Ensuring consistency
+    - Following documented guidelines
+    - Making decisions or generating content
+`;
+
+  if (existing.trim()) {
+    // Insert docs reference at the top, after the first heading line
+    const lines = existing.split("\n");
+    const headingIndex = lines.findIndex((l) => l.startsWith("# "));
+    if (headingIndex >= 0) {
+      lines.splice(headingIndex + 1, 0, docsBlock);
+      await fs.writeFile(filePath, lines.join("\n"), "utf-8");
+    } else {
+      const content = docsBlock + "\n" + existing;
+      await fs.writeFile(filePath, content, "utf-8");
+    }
+  } else {
+    const content = `# Claude Code Instructions\n${docsBlock}`;
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+}

package/src/core/project/config.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { TaskFlowConfig } from "../types.js";
+
+const CONFIG_FILE = "config.json";
+const TASKFLOW_DIR = ".taskflow";
+
+export const DEFAULT_CONFIG: TaskFlowConfig = {
+  version: "1.0",
+  project: {
+    name: "",
+  },
+  tasks: {
+    statusFlow: ["pending", "in-progress", "blocked", "done"],
+  },
+};
+
+export async function readConfig(projectRoot: string): Promise<TaskFlowConfig> {
+  const configPath = path.join(projectRoot, TASKFLOW_DIR, CONFIG_FILE);
+  try {
+    const raw = await fs.readFile(configPath, "utf-8");
+    return JSON.parse(raw) as TaskFlowConfig;
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export async function writeConfig(
+  projectRoot: string,
+  config: TaskFlowConfig,
+): Promise<void> {
+  const configPath = path.join(projectRoot, TASKFLOW_DIR, CONFIG_FILE);
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}

package/src/core/project/docs-setup.ts

@@ -0,0 +1,26 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DOCS_TEMPLATES } from "./docs-templates.js";
+
+const DOCS_DIR = "docs";
+
+export const DOCS_NAMES = Object.keys(DOCS_TEMPLATES);
+
+export async function installDocs(projectRoot: string): Promise<void> {
+  const docsDir = path.join(projectRoot, DOCS_DIR);
+  await fs.mkdir(docsDir, { recursive: true });
+
+  for (const [name, content] of Object.entries(DOCS_TEMPLATES)) {
+    const filePath = path.join(docsDir, `${name}.md`);
+
+    // Don't overwrite existing docs (user may have customized them)
+    try {
+      await fs.access(filePath);
+      continue;
+    } catch {
+      // File doesn't exist — create it
+    }
+
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+}

package/src/core/project/docs-templates.ts

@@ -0,0 +1,205 @@
+export const DOCS_TEMPLATES: Record<string, string> = {
+  guideline: `# Project Guideline
+
+## Naming Conventions
+- **Files**: kebab-case (\`parse-prd-flow.ts\`)
+- **Components**: PascalCase (\`TaskCard.tsx\`)
+- **Functions/Variables**: camelCase
+- **Types/Interfaces**: PascalCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Test files**: \`*.test.ts\` or \`__tests__/*.test.ts\` (co-located)
+
+## Import Conventions
+- Use path alias (\`@/*\` etc.) when available — avoid deep relative paths
+- Group imports: external → internal → relative
+- No circular imports between modules/features
+
+## Module Structure
+- Keep modules self-contained: co-locate related code (logic, types, tests)
+- Separate concerns by layer (API, UI, business logic)
+- Shared code belongs in \`lib/\` or \`utils/\` — not inside a feature module
+
+## General Principles
+- Prefer composition over inheritance
+- Keep public API surface small — export only what's needed
+- Avoid god files (>300 lines) — split by responsibility
+- Configuration and constants belong in dedicated files, not scattered inline
+`,
+
+  "clean-code": `# Clean Code Guidelines
+
+## Principles
+- **Single Responsibility**: One function/module = one job
+- **DRY**: Extract only when duplicated 3+ times. Premature abstraction is worse than duplication
+- **KISS**: Simplest solution that works. No over-engineering
+- **YAGNI**: Don't build what you don't need yet
+
+## Functions
+- Max 20 lines per function (guideline, not hard rule)
+- Max 3 parameters. Use an options object for more
+- Name functions with verbs: \`createTask\`, \`parseMarkdown\`, \`validateInput\`
+- Early return over nested conditionals
+
+## Error Handling
+- Use custom error classes per domain
+- Let errors bubble up — catch only at boundaries (API routes, CLI commands)
+- Never swallow errors silently
+
+## Types
+- Prefer \`type\` over \`interface\` for consistency (unless extending)
+- Use schema-first approach (Zod, etc.); derive types from schemas
+- Avoid \`any\` — use \`unknown\` and narrow
+
+## Code Smells to Avoid
+- God files (>300 lines) — split by responsibility
+- Boolean parameters — use named options or separate functions
+- Magic strings/numbers — use constants or enums
+- Commented-out code — delete it, git has history
+`,
+
+  git: `# Git Conventions
+
+## Branch Naming
+\`\`\`
+feat/{description}      # New feature
+fix/{description}       # Bug fix
+refactor/{description}  # Refactoring
+docs/{description}      # Documentation
+chore/{description}     # Maintenance
+\`\`\`
+
+## Commit Messages
+Follow Conventional Commits:
+\`\`\`
+type(scope): description
+
+feat(kanban): add drag-and-drop task reordering
+fix(cli): handle missing config file gracefully
+refactor(core): extract task validation logic
+test(prd): add parser edge case coverage
+\`\`\`
+
+### Types
+- \`feat\` — new feature
+- \`fix\` — bug fix
+- \`refactor\` — code restructuring (no behavior change)
+- \`test\` — adding/updating tests
+- \`docs\` — documentation only
+- \`chore\` — build, deps, config changes
+- \`style\` — formatting (no logic change)
+
+## Rules
+- Commit small, atomic changes
+- Never commit secrets, \`.env\` files, or credentials
+- Keep commits buildable — don't break the build mid-branch
+- Squash WIP commits before PR
+`,
+
+  tdd: `# Test-Driven Development
+
+## Philosophy
+- Write tests first for new features and bug fixes
+- Tests document behavior — they are living specifications
+- Fast feedback: unit tests should run in <1s per file
+
+## Test Pyramid
+1. **Unit tests** — core logic, utils, schemas (most coverage)
+2. **Integration tests** — API routes, database queries (moderate)
+3. **E2E tests** — critical user flows only (fewest)
+
+## Conventions
+- Co-locate tests: \`*.test.ts\` next to source or in \`__tests__/\`
+- Use \`describe\` blocks to group by function/scenario
+- Test names: \`it('should {expected behavior} when {condition}')\`
+- One assertion concept per test
+
+## Patterns
+\`\`\`typescript
+// Arrange
+const input = createMockTask({ status: 'todo' });
+
+// Act
+const result = updateTaskStatus(input, 'in-progress');
+
+// Assert
+expect(result.status).toBe('in-progress');
+\`\`\`
+
+## What to Test
+- Business logic and transformations
+- Edge cases and error paths
+- Schema validation
+- API response shapes
+
+## What NOT to Test
+- Framework internals (routing, rendering)
+- Third-party library behavior
+- Implementation details (private functions, internal state)
+- Trivial getters/setters
+`,
+
+  "step-by-step": `# Step-by-Step Development Workflow
+
+## Before Writing Code
+1. **Understand the requirement** — Read the task/PRD thoroughly
+2. **Check existing code** — Search for related implementations before creating new ones
+3. **Plan the approach** — Identify which files to modify and what tests to write
+
+## Implementation Flow
+1. **Write the test** — Define expected behavior first
+2. **Write minimal code** — Just enough to pass the test
+3. **Refactor** — Clean up while tests stay green
+4. **Verify** — Run full test suite
+5. **Type check** — Run type checker
+6. **Lint** — Run linter
+
+## PR Checklist
+- [ ] Tests pass
+- [ ] Type check passes
+- [ ] No lint errors
+- [ ] New code has test coverage
+- [ ] Commit messages follow conventions
+- [ ] No secrets or .env files committed
+
+## Debugging
+1. Read the error message carefully
+2. Reproduce the issue with a test
+3. Identify root cause (don't just patch symptoms)
+4. Fix and verify the test passes
+5. Check for similar issues elsewhere
+`,
+
+  security: `# Security Guidelines
+
+## Authentication & Authorization
+- All API routes must verify authentication
+- Validate user session on every request — never trust client-side auth state
+- Use row-level or resource-level access control for data isolation
+
+## Input Validation
+- Validate ALL external input with schemas at the boundary
+- Never trust query params, request bodies, or URL params directly
+- Sanitize user-generated content before rendering (XSS prevention)
+
+## Secrets Management
+- Store secrets in environment variables only
+- Never commit \`.env\`, API keys, or credentials
+- Use \`.env.local\` for local development (ensure it's in \`.gitignore\`)
+
+## API Security
+- Use parameterized queries — never concatenate user input into queries
+- Rate limit public endpoints
+- Return generic error messages to clients — log details server-side
+
+## Dependencies
+- Keep dependencies up to date
+- Review new dependencies before adding (check maintenance, size, security)
+- Run security audits periodically
+
+## What to Never Do
+- Expose internal error stacks to clients
+- Store passwords in plain text
+- Use \`eval()\` or dynamic code execution with user input
+- Disable strict type checks for convenience
+`,
+};

package/src/core/project/init.ts

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeConfig, DEFAULT_CONFIG } from "./config.js";
+
+const TASKFLOW_DIR = ".taskflow";
+
+export interface InitResult {
+  created: boolean;
+  alreadyExists: boolean;
+  projectRoot: string;
+}
+
+export async function initProject(projectRoot: string, projectName?: string): Promise<InitResult> {
+  const taskflowDir = path.join(projectRoot, TASKFLOW_DIR);
+
+  let alreadyExists = false;
+  try {
+    await fs.access(taskflowDir);
+    alreadyExists = true;
+  } catch {
+    // directory does not exist
+  }
+
+  if (alreadyExists) {
+    return { created: false, alreadyExists: true, projectRoot };
+  }
+
+  await fs.mkdir(path.join(taskflowDir, "tasks"), { recursive: true });
+  await fs.mkdir(path.join(taskflowDir, "index"), { recursive: true });
+  await fs.mkdir(path.join(taskflowDir, "logs"), { recursive: true });
+  await fs.mkdir(path.join(taskflowDir, "cache"), { recursive: true });
+
+  const config = {
+    ...DEFAULT_CONFIG,
+    project: { ...DEFAULT_CONFIG.project, name: projectName ?? "" },
+  };
+  await writeConfig(projectRoot, config);
+
+  return { created: true, alreadyExists: false, projectRoot };
+}

package/src/core/project/skill-setup.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SKILL_TEMPLATES } from "./skill-templates.js";
+
+export const SKILL_NAMES = Object.keys(SKILL_TEMPLATES);
+
+export async function installSkills(projectRoot: string): Promise<void> {
+  const srcDir = path.join(projectRoot, ".taskflow", ".claude", "commands");
+  const destDir = path.join(projectRoot, ".claude", "commands");
+
+  await fs.mkdir(srcDir, { recursive: true });
+  await fs.mkdir(destDir, { recursive: true });
+
+  for (const [name, content] of Object.entries(SKILL_TEMPLATES)) {
+    const srcFile = path.join(srcDir, `${name}.md`);
+    const destFile = path.join(destDir, `${name}.md`);
+
+    // 원본 스킬 파일 생성 (항상 최신 템플릿으로 덮어쓰기)
+    await fs.writeFile(srcFile, content, "utf-8");
+
+    // 기존 링크/파일이 있으면 심볼릭 링크 스킵
+    try {
+      await fs.lstat(destFile);
+      continue;
+    } catch {
+      // 없으면 생성
+    }
+
+    const relativePath = path.relative(destDir, srcFile);
+    await fs.symlink(relativePath, destFile);
+  }
+}