@angar2/taskery 0.4.0 → 0.5.0

package/bin/mcp.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// taskery MCP 서버 — lib.js core 함수를 구조화 도구로 노출 (CLI와 동일 단일 홈, 로직 중복 0)
+/**
+ * bin/mcp.js
+ * `npx @angar2/taskery mcp` — stdio MCP 서버. Claude(.mcp.json) / Codex(codex mcp add) 등록.
+ *
+ * 도구 8종 = CLI 명령과 동일한 lib.js 함수의 다른 입구(네이티브 구조화 인자/반환).
+ *   backlog_add / backlog_get / backlog_mark — 활성 plan BACKLOG.md 조작
+ *   set_status   — task 헤더 상태 전이 (7×7 유효전이 검증, closed 거부)
+ *   plan_init    — plan 생성 (채번+골격+AGENT-GUIDE 갱신)
+ *   task_init    — task 분기 (fork 원자 채번 + §1.3 골격 자동 생성)
+ *   task_close   — close 결정적 준비만 (Phase커밋·status=closed·마커). 비가역 머지/정리는 스킬.
+ *   status       — 멀티세션 현황 + 활성 plan
+ *
+ * SDK(@modelcontextprotocol/sdk)는 dual CJS/ESM — require 조건으로 CJS 빌드 해결(검증 완료).
+ */
+
+const path = require('path');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+const lib = require('./lib');
+
+const VALID_TYPES = ['feature', 'bug', 'improve', 'refactor', 'docs', 'chore'];
+const VALID_SIZES = ['micro', 'small', 'medium', 'large'];
+
+// 메인 워크트리 검출 + manifest 확인. 실패 시 throw(핸들러 래퍼가 isError 응답으로 변환).
+function resolveMainWt() {
+  const mainWt = lib.getMainWorktreePath();
+  if (!lib.readManifest(path.join(mainWt, lib.MANIFEST_NAME))) {
+    throw new Error(`${lib.MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+  }
+  return mainWt;
+}
+
+// 'TASK-007' | 'TASK-7' | 7 | '7' → 7 (CLI 관용성 미러링)
+function parseTaskNum(token) {
+  const m = String(token).match(/(\d+)/);
+  return m ? parseInt(m[1], 10) : NaN;
+}
+
+// 미등록 케이스 문서는 task 워크트리에 있음 — 서버 cwd 고정이라 SSoT로 워크트리 유도.
+function resolveTaskDoc(mainWt, taskNum) {
+  const active = lib.getActiveTasks(mainWt).find((t) => t.taskNum === taskNum);
+  const wtPath = active
+    ? lib.getWorktreePath(lib.getProjectId(mainWt), {
+        taskNum,
+        src: active.src,
+        slug: active.slug,
+      })
+    : mainWt;
+  return lib.resolveTaskDocPath(mainWt, wtPath, { taskNum });
+}
+
+// 구조화 결과(JSON) + 선택 가이드 → MCP content.
+function ok(data, guide) {
+  const text = guide ? `${JSON.stringify(data)}\n\n${guide}` : JSON.stringify(data);
+  return { content: [{ type: 'text', text }] };
+}
+function fail(message) {
+  return { content: [{ type: 'text', text: `오류: ${message}` }], isError: true };
+}
+
+// 핸들러 공통 래퍼 — 예외를 isError 응답으로 변환(서버 크래시 방지).
+function handler(fn) {
+  return async (args) => {
+    try {
+      return await fn(args || {});
+    } catch (e) {
+      return fail(e.message);
+    }
+  };
+}
+
+const server = new McpServer({ name: 'taskery', version: lib.getPackageVersion() });
+
+server.registerTool(
+  'backlog_add',
+  {
+    description:
+      '활성 plan BACKLOG.md에 task 후보 1건 추가 (BL-NNN 채번 + withMetaLock 직렬화). 얕은 분석 메타를 인자로 받는다.',
+    inputSchema: {
+      type: z.enum(VALID_TYPES),
+      title: z.string().describe('한 줄 제목(한국어)'),
+      slug: z.string().describe('영어 kebab-case 슬러그'),
+      summary: z.string().describe('한 줄 개요'),
+      target: z.string().describe('한 줄 대상 영역'),
+    },
+  },
+  handler(async (a) => {
+    const mainWt = resolveMainWt();
+    const blNum = await lib.appendBacklogItem(mainWt, a);
+    const blId = `BL-${String(blNum).padStart(3, '0')}`;
+    return ok({ blNum, blId }, `${blId} 추가됨. 진행 의향이면 task_init이 이 메타로 워크트리를 분기한다.`);
+  }),
+);
+
+server.registerTool(
+  'backlog_get',
+  {
+    description:
+      '활성 plan BACKLOG.md에서 BL-NNN 항목 메타 조회 → { blId, status, type, title, slug, summary, target, taskNums }.',
+    inputSchema: { blId: z.string().regex(/^BL-\d+$/, 'BL-NNN 형식') },
+  },
+  handler(async (a) => {
+    const mainWt = resolveMainWt();
+    const item = lib.parseBacklogItem(mainWt, a.blId);
+    if (!item) throw new Error(`${a.blId} 항목 없음.`);
+    return ok(item);
+  }),
+);
+
+server.registerTool(
+  'backlog_mark',
+  {
+    description: 'BL-NNN을 [x] 확인 마킹 + TASK-NNN 연결 (withMetaLock). task_init 직후 호출.',
+    inputSchema: {
+      blId: z.string().regex(/^BL-\d+$/, 'BL-NNN 형식'),
+      task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호'),
+    },
+  },
+  handler(async (a) => {
+    const taskNum = parseTaskNum(a.task);
+    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
+    const mainWt = resolveMainWt();
+    await lib.markBacklogChecked(mainWt, a.blId, taskNum);
+    return ok({ blId: a.blId, taskNum });
+  }),
+);
+
+server.registerTool(
+  'set_status',
+  {
+    description:
+      'task 헤더 상태 전이 (TASK_DOC_RULE §1.2 7×7 유효전이 검증). 잘못된 전이 거부. closed 전이는 task_close가 담당하므로 여기선 거부.',
+    inputSchema: {
+      task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호'),
+      state: z.string().describe('전이 목표 상태'),
+    },
+  },
+  handler(async (a) => {
+    const taskNum = parseTaskNum(a.task);
+    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
+    if (!Object.prototype.hasOwnProperty.call(lib.TRANSITIONS, a.state)) {
+      throw new Error(`알 수 없는 상태: ${a.state} (유효: ${Object.keys(lib.TRANSITIONS).join(', ')})`);
+    }
+    if (a.state === 'closed') {
+      throw new Error(`closed 전이는 set_status가 아니라 task_close(close 파이프라인)가 담당.`);
+    }
+    const mainWt = resolveMainWt();
+    const resolved = resolveTaskDoc(mainWt, taskNum);
+    if (!resolved) throw new Error(`TASK-${String(taskNum).padStart(3, '0')} 문서를 찾지 못함.`);
+    const result = await lib.setStatus(resolved.file, a.state);
+    return ok({ taskNum, ...result });
+  }),
+);
+
+server.registerTool(
+  'plan_init',
+  {
+    description:
+      'plan(기능 그룹) 생성 — 채번 + 폴더 + ROADMAP/PLAN/BACKLOG 골격 + AGENT-GUIDE 활성plan 갱신. 이후 골격 내용은 LLM이 채움. legacy 폴더 잔존 시 gated 반환(force로 재호출).',
+    inputSchema: {
+      slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
+      force: z.boolean().optional().describe('legacy 게이트 무시'),
+    },
+  },
+  handler(async (a) => {
+    const mainWt = resolveMainWt();
+    const result = lib.initPlan(mainWt, a.slug, { force: !!a.force });
+    if (result.gated) {
+      return ok(
+        { gated: true, legacyDirs: result.legacyDirs },
+        `plans/에 NNN 채번 아닌 폴더(${result.legacyDirs.join(', ')}) 잔존 — 사용자 confirm 후 force:true로 재호출.`,
+      );
+    }
+    return ok(
+      { plan: result.plan, nnn: result.nnn, planDir: result.planDir, tasksDir: result.tasksDir },
+      `골격 생성됨. ROADMAP Stage 내용·PLAN 링크·FEATURES/UX-UI delta는 placeholder를 채운다.`,
+    );
+  }),
+);
+
+server.registerTool(
+  'task_init',
+  {
+    description:
+      'task 분기 — 채번+워크트리+브랜치 생성을 init 락으로 원자 실행. size·title 주면 §1.3 골격 task.md도 자동 생성(생성일·status=draft 자동). 통상 /task-init 경유.',
+    inputSchema: {
+      type: z.enum(VALID_TYPES),
+      dev: z.string().describe('개발자 식별자 (claude / angar2 등)'),
+      src: z.string().regex(/^(BL-\d+|RM-\d+|DR)$/, 'BL-NNN | RM-NNN | DR'),
+      slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
+      size: z.enum(VALID_SIZES).optional(),
+      title: z.string().optional().describe('한국어 제목 (size와 함께 주면 골격 생성)'),
+      promote: z.boolean().optional(),
+    },
+  },
+  handler(async (a) => {
+    const mainWt = resolveMainWt();
+    const result = await lib.forkTask(mainWt, {
+      type: a.type,
+      dev: a.dev,
+      src: a.src,
+      slug: a.slug,
+    });
+    let out = result;
+    if (a.size && a.title) {
+      try {
+        const doc = lib.scaffoldTaskDoc(mainWt, result.wtPath, {
+          taskNum: result.taskNum,
+          slug: a.slug,
+          title: a.title,
+          type: a.type,
+          size: a.size,
+          promoted: !!a.promote,
+        });
+        out = { ...result, docPath: doc.file, registered: doc.registered, promoted: doc.promoted };
+      } catch (e) {
+        out = { ...result, scaffoldError: e.message };
+      }
+    }
+    return ok(out, `워크트리 생성됨. 제목 확인 후 /task-plan으로 진행.`);
+  }),
+);
+
+server.registerTool(
+  'task_close',
+  {
+    description:
+      'close 결정적 준비만 — Phase 커밋·status=closed·문서 커밋·추적마커. 게이트(status=tested)·매핑 모호 시 blocked 반환. 비가역(dev --no-ff 머지·worktree/branch 정리·충돌 해결)은 스킬(task-close)이 후속 수행.',
+    inputSchema: { task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호') },
+  },
+  handler(async (a) => {
+    const taskNum = parseTaskNum(a.task);
+    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
+    const mainWt = resolveMainWt();
+    const result = await lib.closeTask(mainWt, { taskNum });
+    if (result.blocked === 'status') {
+      return ok(result, `게이트 차단 — status=${result.current} (tested 아님). /task-test 통과 후 재호출.`);
+    }
+    if (result.blocked === 'mapping') {
+      return ok(
+        result,
+        `Phase↔파일 매핑 모호 (${result.reason}) — Dev Plan '파일' 필드 확인 후 수동 Phase 커밋 → task_close 재호출.`,
+      );
+    }
+    return ok(result, `prep 완료. 비가역(사전 rebase·충돌해결·머지 락·dev 머지·정리)은 task-close 스킬이 후속 수행.`);
+  }),
+);
+
+server.registerTool(
+  'status',
+  {
+    description: '멀티세션 현황 — 진행중 task + 워크트리 + 활성 plan 버전.',
+    inputSchema: {},
+  },
+  handler(async () => {
+    const mainWt = resolveMainWt();
+    const activeTasks = lib.getActiveTasks(mainWt);
+    let activePlan = null;
+    try {
+      activePlan = lib.getActiveVersion(mainWt);
+    } catch (e) {
+      activePlan = null;
+    }
+    return ok({ activePlan, activeTasks });
+  }),
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((e) => {
+  console.error(`taskery mcp 실패: ${e.message}`);
+  process.exit(1);
+});

package/bin/plan.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// plan(기능 그룹) 생성 CLI — 채번+폴더+ROADMAP/PLAN/BACKLOG 골격+AGENT-GUIDE 갱신 원자 실행
+/**
+ * bin/plan.js
+ * `npx @angar2/taskery plan-init <slug> [--force]` — plan 생성.
+ *
+ * 채번(NNN) + legacy 게이트 + 폴더 mkdir(plans/<NNN_slug> + tasks/<NNN_slug>/{spec-diffs,screenshots,mockup})
+ * + ROADMAP/PLAN/BACKLOG 골격 Write + AGENT-GUIDE 활성 plan 갱신을 코드가 수행.
+ * 성공 시 JSON 한 줄 — { plan, nnn, planDir, tasksDir }. 이후 ROADMAP Stage 내용·PLAN 링크·
+ * FEATURES/UX-UI delta는 LLM(plan-init 스킬)이 골격 placeholder를 채운다.
+ *
+ * legacy 폴더(NNN_ 아닌 plan 폴더) 잔존 + --force 없음 → exit 2 + { gated:true, legacyDirs }
+ *   (스킬이 사용자 confirm 후 --force로 재호출). 그 외 실패 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  initPlan,
+} = require('./lib');
+
+function main() {
+  const argv = process.argv.slice(2);
+  const positional = [];
+  let force = false;
+  for (const a of argv) {
+    if (a === '--force') force = true;
+    else if (!a.startsWith('--')) positional.push(a);
+  }
+  const slug = positional[0];
+
+  if (!slug) {
+    console.error('사용법: npx @angar2/taskery plan-init <slug> [--force]');
+    console.error('예: npx @angar2/taskery plan-init compare-products');
+    process.exit(1);
+  }
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+    console.error(`slug은 영어 kebab-case (받음: ${slug})`);
+    process.exit(1);
+  }
+
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery plan-init 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = initPlan(mainWt, slug, { force });
+  } catch (e) {
+    console.error(`taskery plan-init 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (result.gated) {
+    // legacy 폴더 잔존 — 사용자 confirm 전 생성 금지. 스킬이 경고 + confirm 후 --force 재호출.
+    console.error(
+      `plans/에 NNN 채번이 아닌 폴더(${result.legacyDirs.join(', ')})가 있어 활성 plan이 갈릴 위험. ` +
+        `수동 이전 후 진행하거나, 그대로 진행하려면 --force 추가.`,
+    );
+    process.stdout.write(JSON.stringify({ gated: true, legacyDirs: result.legacyDirs }) + '\n');
+    process.exit(2);
+  }
+
+  process.stdout.write(
+    JSON.stringify({
+      plan: result.plan,
+      nnn: result.nnn,
+      planDir: result.planDir,
+      tasksDir: result.tasksDir,
+    }) + '\n',
+  );
+}
+
+main();

package/bin/set-status.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// task 상태 전이 CLI — 7×7 유효전이 검증 후 헤더 상태 컬럼 치환 (잘못된 전이 거부)
+/**
+ * bin/set-status.js
+ * `npx @angar2/taskery set-status <TASK-NNN> <state>` — task 헤더 상태 전이.
+ *
+ * 현재 상태를 코드로 읽고 TASK_DOC_RULE §1.2 유효전이표로 검증 → 통과 시 헤더 치환.
+ * 잘못된 전이(예: draft→closed)는 거부. 같은 상태 재지정은 idempotent no-op.
+ * task 문서 위치는 resolveTaskDocPath가 .gitignore 케이스로 단일 판정.
+ *
+ * closed 전이는 본 CLI가 거부 — `/task-close`(close 파이프라인)가 내부 setStatus로 처리.
+ * stdout: { taskNum, from, to, changed, path }. 실패 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  gitCapture,
+  resolveTaskDocPath,
+  setStatus,
+  TRANSITIONS,
+} = require('./lib');
+
+async function main() {
+  const [taskArg, state] = process.argv.slice(2);
+
+  if (!taskArg || !state) {
+    console.error('사용법: npx @angar2/taskery set-status <TASK-NNN> <state>');
+    console.error(`state: ${Object.keys(TRANSITIONS).join(' | ')}`);
+    process.exit(1);
+  }
+  const m = String(taskArg).match(/(\d+)/);
+  if (!m) {
+    console.error(`TASK 번호 파싱 실패 (받음: ${taskArg}). 예: TASK-007`);
+    process.exit(1);
+  }
+  const taskNum = parseInt(m[1], 10);
+
+  if (!Object.prototype.hasOwnProperty.call(TRANSITIONS, state)) {
+    console.error(`알 수 없는 상태: ${state} (유효: ${Object.keys(TRANSITIONS).join(', ')})`);
+    process.exit(1);
+  }
+  if (state === 'closed') {
+    console.error(`closed 전이는 set-status가 아니라 '/task-close'(close 파이프라인)가 담당.`);
+    process.exit(1);
+  }
+
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery set-status 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+
+  // 현재 작업트리 toplevel = 미등록 케이스의 문서 base (호출 위치 = 해당 워크트리).
+  const wtPath = gitCapture(process.cwd(), ['rev-parse', '--show-toplevel'], { allowFail: true }) || mainWt;
+
+  const resolved = resolveTaskDocPath(mainWt, wtPath, { taskNum });
+  if (!resolved) {
+    console.error(
+      `TASK-${String(taskNum).padStart(3, '0')} 문서를 찾지 못함 (.project/tasks/*/ 아래 단일 파일/폴더 승격 모두 탐색).`,
+    );
+    process.exit(1);
+  }
+
+  try {
+    const result = await setStatus(resolved.file, state);
+    process.stdout.write(JSON.stringify({ taskNum, ...result }) + '\n');
+  } catch (e) {
+    console.error(`taskery set-status 실패: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/taskery.js

@@ -9,7 +9,12 @@
  *   update  — 최신 버전 fetch + manifest 비교 + 머지 갱신
  *   status  — 멀티세션 현황 요약 (진행중 태스크 / 워크트리 / 머지 락, 0.1.2+)
  *   prune   — stale 워크트리 / 브랜치 대화형 정리 (0.1.2+)
- *   fork    — task 분기 (채번+워크트리+브랜치 생성을 init 락으로 원자 실행, 0.3.2+)
+ *   fork    — task 분기 (채번+워크트리+브랜치 생성 init 락 원자 실행, 0.3.2+) + 골격 task.md 자동 생성(--size/--title)
+ *   backlog-add/get/mark — 활성 plan BACKLOG.md 조작 (채번/조회/확인 마킹, 코드화)
+ *   set-status — task 헤더 상태 전이 (7×7 유효전이 검증, 코드화)
+ *   plan-init — plan 생성 (채번+폴더+ROADMAP/PLAN/BACKLOG 골격+AGENT-GUIDE 갱신, 코드화)
+ *   close   — close 결정적 준비 (Phase커밋+status=closed+문서커밋+추적마커; 비가역 머지/정리는 스킬, 코드화)
+ *   mcp     — stdio MCP 서버 기동 (lib core를 도구 8종으로 노출; Claude/Codex 등록)
  *   help    — 사용법 출력
  */
 
@@ -18,9 +23,10 @@ const path = require('path');
 
 const sub = process.argv[2];
 
-function runScript(scriptName) {
+function runScript(scriptName, injectArgs = []) {
+  // injectArgs: dispatcher가 스크립트에 주입하는 선행 인자(예: backlog 서브op). 그 뒤로 사용자 인자.
   const scriptPath = path.resolve(__dirname, scriptName);
-  const r = spawnSync(process.execPath, [scriptPath, ...process.argv.slice(3)], {
+  const r = spawnSync(process.execPath, [scriptPath, ...injectArgs, ...process.argv.slice(3)], {
     stdio: 'inherit',
   });
   process.exit(r.status ?? 1);
@@ -35,7 +41,14 @@ function help() {
   npx @angar2/taskery update    최신 버전 fetch + 머지 갱신
   npx @angar2/taskery status    멀티세션 현황 (진행중 태스크 / 워크트리 / 머지 락)
   npx @angar2/taskery prune     stale 워크트리 / 브랜치 대화형 정리
-  npx @angar2/taskery fork <type> <dev> <src> <slug>   task 분기 (통상 /task-init 경유)
+  npx @angar2/taskery fork <type> <dev> <src> <slug> [--size <s> --title "<제목>" --promote]   task 분기 + 골격 생성 (통상 /task-init 경유)
+  npx @angar2/taskery backlog-add --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>   백로그 추가
+  npx @angar2/taskery backlog-get <BL-NNN>             백로그 항목 조회 (JSON)
+  npx @angar2/taskery backlog-mark <BL-NNN> <TASK-NNN> 백로그 확인 마킹
+  npx @angar2/taskery set-status <TASK-NNN> <state>    task 상태 전이 (유효전이 검증)
+  npx @angar2/taskery plan-init <slug> [--force]       plan 생성 (채번+폴더+골격+활성plan 갱신)
+  npx @angar2/taskery close <TASK-NNN>                 close 결정적 준비 (Phase커밋+status=closed+추적마커)
+  npx @angar2/taskery mcp                              MCP stdio 서버 기동 (Claude .mcp.json / Codex codex mcp add 등록)
   npx @angar2/taskery help      도움말
 
 새 프로젝트 시작:
@@ -79,6 +92,27 @@ switch (sub) {
   case 'fork':
     runScript('fork.js');
     break;
+  case 'backlog-add':
+    runScript('backlog.js', ['add']);
+    break;
+  case 'backlog-get':
+    runScript('backlog.js', ['get']);
+    break;
+  case 'backlog-mark':
+    runScript('backlog.js', ['mark']);
+    break;
+  case 'set-status':
+    runScript('set-status.js');
+    break;
+  case 'plan-init':
+    runScript('plan.js');
+    break;
+  case 'close':
+    runScript('close.js');
+    break;
+  case 'mcp':
+    runScript('mcp.js');
+    break;
   case 'help':
   case '--help':
   case '-h':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angar2/taskery",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Lightweight task system for Claude Code & Codex — 1 메인 세션(또는 멀티세션) + 스킬 9종 + catastrophic hook 안전망 2종",
   "bin": {
     "taskery": "bin/taskery.js",
@@ -43,6 +43,8 @@
     "git": ">=2.31.0"
   },
   "dependencies": {
-    "proper-lockfile": "^4.1.2"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^4.4.3"
   }
 }

package/template/shared/skills/add-backlog/SKILL.md

@@ -5,81 +5,31 @@ description: 사용자 발화로 *plan(기능 그룹)별* tasks/<NNN_slug>/BACKL
 
 # /add-backlog
 
-## 개요
-
-`/add-backlog`는 사용자 발화를 받아 *plan(기능 그룹)별 백로그* `.project/tasks/<NNN_slug>/BACKLOG.md`에 task 후보를 1건씩 누적한다. 멀티세션 환경에서 `withMetaLock`으로 동시 쓰기 직렬화. **얕은 분석**만 — 코드 직접 탐색 X, 추정 수준. 본격 분석은 다음 단계 `/task-plan`에서.
-
-글로벌 `.project/BACKLOG.md` (plan 기획 후보 카탈로그) 는 `/plan-init` 영역으로 본 스킬 무관.
+사용자 발화를 받아 *활성 plan별 백로그* `.project/tasks/<NNN_slug>/BACKLOG.md`에 task 후보를 1건씩 누적한다. **얕은 분석**만 — 코드 직접 탐색 X, 추정 수준. 본격 분석은 다음 단계 `/task-plan`.
 
 ## 호출 시점
 
-- 사용자 명시 호출: `/add-backlog 로그인 빈 화면 떠`
-- 발화 캐치: *"~ 백로그에 추가해 줘"* / *"백로그에 ~"* 등 백로그 추가 의도 발화 description 매칭으로 메인이 자동 발동
-
-## 입력 처리
-
-- 무인자 호출: 사용자가 *"백로그 추가"*만 말한 경우 — 어떤 항목인지 한 줄 인터뷰
-- 인자 호출: 인자에 백로그 후보 주제. 1건 기본. 다건 명시 시 순차 처리
-
-## 단계 (Step 1~6)
+- 명시 호출: `/add-backlog 로그인 빈 화면 떠`
+- 발화 캐치: *"~ 백로그에 추가해 줘"* 등 백로그 추가 의도 발화
+- 무인자 호출 시 *"어떤 항목? 한 줄로 알려줘"* 인터뷰. 다건 명시 시 1건씩 순차 처리.
 
-### Step 1 — 사전 검증
+## 판단 (LLM, 코드 탐색 X)
 
-- 메인 워크트리 검출:
-  ```sh
-  MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
-  ```
-- 메인 워크트리 dev 체크아웃 검증 — 위배 시 사용자 호출 + 중단
-- 활성 plan 검출 — `$MAIN_WT/.project/AGENT-GUIDE.md` `## 활성 plan 버전` 섹션 다음 비어 있지 않은 첫 줄에서 활성 plan 식별자(첫 토큰 — `NNN_slug` 폴더명) 추출
-- BACKLOG.md 경로 = `$MAIN_WT/.project/tasks/<NNN_slug>/BACKLOG.md`. 부재 시 사용자 호출: *"`/plan-init` 먼저 호출해 활성 plan 디렉토리 + 빈 BACKLOG.md 생성 필요"* + 중단
+발화에서 후보 1건을 뽑아 추정 수준의 메타를 산출한다:
 
-### Step 2 — 백로그 항목 후보 추출
-
-- 사용자 발화에서 1건 추출. 다건 명시 시 순차 처리 (각 1건씩 본 흐름 반복)
-- 입력이 비어 있으면 사용자에게 *"어떤 항목? 한 줄로 알려줘"* 인터뷰
-
-### Step 3 — 얕은 분석 (LLM, 코드 탐색 X)
-
-추정 수준의 메타 산출:
-- **유형** (`feature` / `bug` / `improve` / `refactor` / `docs` / `chore`) — 자동 추정, 모호 시 사용자 confirm
+- **유형** (`feature` / `bug` / `improve` / `refactor` / `docs` / `chore`) — 자동 추정, *모호 시 사용자 confirm* (예: *"메뉴 검색 개선"* = feature/improve 모호)
 - **제목** — 한 줄, 간결, 한국어
 - **개요** — 한 줄. bug → 원인 추정 / feature → 구상 / improve → 개선 방향
-- **대상 영역** — 한 줄. 이 파일 / 모듈일 거다 — 추정 수준
+- **대상 영역** — 한 줄. 추정 수준 (이 파일 / 모듈일 거다)
+- **슬러그** — 한국어 제목 → 영어 *의미 변환* → kebab-case (3 단어 이내, 음역 X). 예: *"로그인 빈 화면"* → `login-empty-page`
 
-> *코드 직접 탐색 금지*. 본격 분석은 다음 단계 `/task-plan`에서. 본 스킬은 *메모지 누적*만.
+> *코드 직접 탐색 금지*. 본 스킬은 *메모지 누적*만. 자동 추정 진행 X — 메타는 사용자 OK 또는 명백한 발화 매칭 후에만 추가.
 
-### Step 4 — 결정적 슬러그 산출
+## 추가 + 보고
 
-- 한국어 제목 → 영어 *의미 변환* → kebab-case (3 단어 이내, 음역 X)
-- 예: *"로그인 페이지 빈 화면"* → `login-empty-page` / *"다크모드 토글"* → `dark-mode-toggle`
+`backlog_add` 도구로 추가한다 (MCP 도구 `backlog_add` 또는 동일 `npx @angar2/taskery backlog-add --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>`). 채번(BL-NNN)·서식·placeholder 치환·`withMetaLock` 직렬화·메인 워크트리 위치는 코드가 보장한다. 활성 plan BACKLOG.md 부재 시 도구가 에러를 반환한다 → *"`/plan-init` 먼저 호출해 활성 plan 디렉토리 + BACKLOG.md 생성 필요"* 안내 후 중단.
 
-### Step 5 — BL-NNN 채번 + append (withMetaLock 직렬화)
-
-`bin/lib.js`의 `appendBacklogItem(mainWtPath, meta)` 호출.
-
-```js
-const lib = require('@angar2/taskery/bin/lib'); // 또는 패키지 내부 경로
-const blNum = await lib.appendBacklogItem(MAIN_WT, {
-  type: '<유형>',
-  title: '<제목>',
-  slug: '<슬러그>',
-  summary: '<개요>',
-  target: '<대상 영역>',
-});
-```
-
-내부 흐름:
-1. `withMetaLock(backlogPath)` 안에서:
-   - BACKLOG.md 전체에서 `BL-(\d+)` 패턴 grep → 최대값 + 1. 빈 파일 → BL-001 시작
-   - 항목 블록 포맷팅:
-     ```
-     - [ ] **BL-NNN** [유형] 제목 `slug`
-       - 개요: ...
-       - 대상 영역: ...
-     ```
-   - plan-init 빈 골격의 placeholder 라인 (`(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)`) 발견 시 → 그 자리에 치환. 미발견 시 → 파일 끝 빈 줄 + 블록 append
-
-### Step 6 — 결과 보고
+성공 반환 `{ blNum, blId }`로 보고한다:
 
 ```
 ✅ BL-<NNN> [<유형>] <제목> — <NNN_slug> 백로그 추가됐어.
@@ -89,29 +39,8 @@ const blNum = await lib.appendBacklogItem(MAIN_WT, {
 다음: 진행 의향이면 *"BL-<NNN> 진행"*이라고 말해. `/task-init`이 메타 그대로 받아 워크트리를 분기하고 항목을 `[x]` 확인 마킹할게.
 ```
 
-## 도구 가이드
-
-- **Bash**: 메인 워크트리 검출 / dev 체크아웃 검증
-- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` (활성 plan 검출) / 기존 BACKLOG.md 정독 (중복 / 유사 항목 사전 확인)
-- **bin/lib.js**: `getActiveVersion` / `getBacklogPath` / `appendBacklogItem` 호출
-- **AskUserQuestion**: 유형 모호 시 confirm — 한 번에 한 질문
-
 ## 주의사항
 
-- **얕은 분석만** — 본 스킬에서 도메인 코드 Read · Grep 금지. 본격 분석은 `/task-plan`
-- **유형 자동 추정 + 모호 시 confirm** — *"메뉴 검색 개선"* 같이 feature/improve 모호 시 사용자 결정 받기
-- **메인 워크트리 dev 검증 누락 X** — 위배 시 즉시 중단. 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md에 쓰기
-- **활성 plan 부재 시 즉시 중단** — `AGENT-GUIDE.md` 부재 / `## 활성 plan 버전` 섹션 부재 / plan 식별자 미설정(`<예: …>` 자리표시자) 모두 명확한 에러 메시지 후 사용자 호출
-- **결정적 슬러그 best-effort** — LLM 비결정성 수용. race 차단 본체는 SSoT 2층(`/task-init` §4.4)이 담당. 슬러그 변형 발생 시 사용자 confirm
-- **글로벌 BACKLOG.md (plan 기획 후보)** 와 혼동 X — 본 스킬은 *활성 plan(기능 그룹)별*만 다룸. 글로벌은 `/plan-init` 영역
-- **자동 추정 진행 X** — 유형 / 제목 / 개요 / 대상 영역 모두 사용자 OK 또는 명백한 발화 매칭 후에만 BACKLOG.md 쓰기
-
-## 상태 전이
-
-해당 없음 (백로그 메모지 누적 — task 상태 X).
-
-## 멀티세션 정합
-
-- **위치 = 메인 워크트리 절대 경로** — 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md를 단일 소스로 사용
-- **`withMetaLock` 직렬화** — 두 메인 세션이 동시 `/add-backlog` 호출 시 락으로 직렬화 (proper-lockfile, stale=30s, retries=5). 한 세션 `/add-backlog` + 다른 세션 `/task-init` (BL 마킹) 동시 시도 시 락 정합
-- **체크박스 의미** — `[ ]` = 미확인 (task로 옮기지 않은 메모) / `[x]` = 확인 완료 (task로 옮김). **dev 머지 완료 의미 X** — 완료 추적은 `git log dev --grep 'BL-NNN'` + 브랜치명 + `taskery status`
+- **얕은 분석만** — 도메인 코드 Read · Grep 금지. 본격 분석은 `/task-plan`.
+- **글로벌 `.project/BACKLOG.md`(plan 기획 후보)와 혼동 X** — 본 스킬은 *활성 plan별*만. 글로벌은 `/plan-init` 영역.
+- **체크박스 의미** — `[ ]` = 미확인(메모) / `[x]` = 확인(task로 옮김). dev 머지·완료 여부와 무관 — 완료 추적은 `taskery status` + dev 머지커밋.