@angar2/taskery 0.3.1 → 0.5.0

package/README.md

@@ -110,7 +110,7 @@ my-app/
 ├─ .gitignore
 ├─ .claude/
 │   ├─ settings.json                      # hook 등록 (PreToolUse 매칭)
-│   ├─ skills/<skill-name>/SKILL.md       # 9 skill
+│   ├─ skills/<skill-name>/SKILL.md       # 9 skill (+ Claude 전용 run-team)
 │   └─ hooks/<hook-name>.sh               # 2 hook
 └─ .project/
     ├─ PROJECT.md                         # 프로젝트 개요
@@ -192,9 +192,12 @@ my-app/
 | `/task-close` | task | 최종 검증 후 git 커밋 + dev 브랜치 `--no-ff` 병합 |
 | `/add-backlog` | meta | 사용자 발화로 plan(기능 그룹)별 `tasks/<NNN_slug>/BACKLOG.md`에 task 후보 1건씩 추가 (0.1.2+) |
 | `/log-friction` | meta | 사용자 불편을 `.project/FRICTION_LOG.md`에 한 행 기록 |
+| `/run-team` | meta | 여러 작업을 묶을 수 있는 단위로 task로 나눠 자동 병렬 처리 — 리더 세션이 팀원(독립 세션)에게 task를 1건씩 분배하고 흐름을 관리 (Claude 전용 · 실험 기능 전제 · 0.3.x+) |
 
 각 스킬은 슬래시로 직접 호출하거나, 사용자 발화의 의미가 스킬의 frontmatter description과 매칭되면 메인 세션이 자동으로 발동시킨다.
 
+> `/run-team`은 Claude의 실험적 멀티 세션 기능(agent teams)을 사용하는 Claude 전용 스킬이다. 기본 흐름이 아니라 *"이 작업들 한 번에 팀으로 진행해"* 같은 발화가 있을 때만 발동하며, 활성화에는 환경 변수(`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) 설정이 필요하다. Codex 설치에는 포함되지 않는다.
+
 `/project-init`, `/plan-init`, `/task-init` 세 스킬은 호출 시 다음 문서를 생성한다.
 
 | 스킬 | 생성 위치 | 생성 문서 |

package/bin/backlog.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// 활성 plan별 BACKLOG.md 조작 CLI — add(추가) / get(조회) / mark(확인 마킹) 묶음
+/**
+ * bin/backlog.js
+ * `npx @angar2/taskery backlog-add|backlog-get|backlog-mark ...` — 백로그 조작.
+ *
+ * dispatcher(taskery.js)가 서브op(add|get|mark)를 첫 인자로 주입한다.
+ *   add  --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>
+ *        → withMetaLock + BL-NNN 채번 + append. stdout: { blNum, blId }
+ *   get  <BL-NNN>          → 항목 메타 JSON ({ blId, status, type, title, slug, summary, target, taskNums }). 없으면 exit 1
+ *   mark <BL-NNN> <TASK-NNN> → withMetaLock + [ ]→[x] + TASK 마크. stdout: { blId, taskNum }
+ *
+ * 채번·서식·락은 전부 코드(lib.js)가 보장 — LLM 손 파싱/Edit 제거.
+ * 실패(인자 미달 / 활성 plan 부재 / 항목 없음 등) 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  appendBacklogItem,
+  parseBacklogItem,
+  markBacklogChecked,
+} = require('./lib');
+
+function parseFlags(argv) {
+  // --key value | --key=value 둘 다 지원. 정의된 키만 수집.
+  const KEYS = ['type', 'title', 'slug', 'summary', 'target'];
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const eq = a.indexOf('=');
+    let key;
+    let val;
+    if (eq !== -1) {
+      key = a.slice(2, eq);
+      val = a.slice(eq + 1);
+    } else {
+      key = a.slice(2);
+      val = argv[++i];
+    }
+    if (KEYS.includes(key)) out[key] = val;
+  }
+  return out;
+}
+
+function parseTaskNum(token) {
+  // 'TASK-007' | 'TASK-7' | '7' → 7
+  const m = String(token).match(/(\d+)/);
+  return m ? parseInt(m[1], 10) : NaN;
+}
+
+function resolveMainWt() {
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery backlog 실패: ${e.message}`);
+    process.exit(1);
+  }
+  if (!readManifest(path.join(mainWt, MANIFEST_NAME))) {
+    console.error(`${MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
+    process.exit(1);
+  }
+  return mainWt;
+}
+
+async function doAdd(rest) {
+  const meta = parseFlags(rest);
+  const missing = ['type', 'title', 'slug', 'summary', 'target'].filter((k) => !meta[k]);
+  if (missing.length) {
+    console.error(
+      `사용법: npx @angar2/taskery backlog-add --type <t> --title <제목> --slug <slug> --summary <개요> --target <대상영역>`,
+    );
+    console.error(`누락: ${missing.map((k) => '--' + k).join(', ')}`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  const blNum = await appendBacklogItem(mainWt, meta);
+  const blId = `BL-${String(blNum).padStart(3, '0')}`;
+  process.stdout.write(JSON.stringify({ blNum, blId }) + '\n');
+}
+
+function doGet(rest) {
+  const blId = rest[0];
+  if (!blId || !/^BL-\d+$/.test(blId)) {
+    console.error(`사용법: npx @angar2/taskery backlog-get <BL-NNN>`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  const item = parseBacklogItem(mainWt, blId);
+  if (!item) {
+    console.error(`${blId} 항목 없음.`);
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify(item) + '\n');
+}
+
+async function doMark(rest) {
+  const blId = rest[0];
+  const taskNum = parseTaskNum(rest[1]);
+  if (!blId || !/^BL-\d+$/.test(blId) || !Number.isInteger(taskNum)) {
+    console.error(`사용법: npx @angar2/taskery backlog-mark <BL-NNN> <TASK-NNN>`);
+    process.exit(1);
+  }
+  const mainWt = resolveMainWt();
+  await markBacklogChecked(mainWt, blId, taskNum);
+  process.stdout.write(JSON.stringify({ blId, taskNum }) + '\n');
+}
+
+async function main() {
+  const op = process.argv[2];
+  const rest = process.argv.slice(3);
+  try {
+    if (op === 'add') await doAdd(rest);
+    else if (op === 'get') doGet(rest);
+    else if (op === 'mark') await doMark(rest);
+    else {
+      console.error(`backlog: 알 수 없는 op '${op}' (add | get | mark)`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`taskery backlog-${op} 실패: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/close.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// task close 결정적 준비 CLI — Phase 커밋·status=closed·flows/문서 커밋·추적마커 (비가역 머지/정리는 스킬)
+/**
+ * bin/close.js
+ * `npx @angar2/taskery close <TASK-NNN>` — close 결정적 준비.
+ *
+ * 게이트(status=tested) → Phase 커밋(D2 자동 매핑) → status=closed → flows/문서 커밋 → 추적마커까지
+ * 코드가 수행하고 멈춘다. 이후 비가역(사전 rebase+충돌해결 / 머지 락 / dev --no-ff 머지 /
+ * worktree remove / branch -d)은 스킬(task-close)이 git-guard hook + 복구출력 보호 하에 수행.
+ *
+ * stdout: { prepped, branch, wtPath, registered, commits, aheadOfDev }. exit 0.
+ * 콜백(스킬이 LLM 판단 후 처리):
+ *   - exit 3 + { blocked:'status', current }  — status가 tested 아님 (게이트 차단)
+ *   - exit 2 + { blocked:'mapping', files, phases, reason } — Phase↔파일 매핑 모호 (수동 커밋 필요)
+ * 그 외 실패 시 stderr + exit 1.
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  closeTask,
+} = require('./lib');
+
+async function main() {
+  const arg = process.argv[2];
+  const m = String(arg || '').match(/(\d+)/);
+  if (!m) {
+    console.error('사용법: npx @angar2/taskery close <TASK-NNN>');
+    process.exit(1);
+  }
+  const taskNum = parseInt(m[1], 10);
+
+  let mainWt;
+  try {
+    mainWt = getMainWorktreePath();
+  } catch (e) {
+    console.error(`taskery close 실패: ${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 = await closeTask(mainWt, { taskNum });
+  } catch (e) {
+    console.error(`taskery close 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (result.blocked === 'status') {
+    console.error(
+      `close 게이트 차단 — status=${result.current} (tested 아님). /task-test 통과 후 재호출.`,
+    );
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(3);
+  }
+  if (result.blocked === 'mapping') {
+    console.error(
+      `Phase↔파일 매핑 모호 (${result.reason}) — Dev Plan '파일' 필드 확인 후 수동 Phase 커밋 필요.`,
+    );
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(2);
+  }
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+
+main();

package/bin/fork.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * bin/fork.js
+ * `npx @angar2/taskery fork <type> <dev> <src> <slug> [--size <s> --title "<t>" --promote]` — task 분기.
+ *
+ * [채번 → 워크트리·브랜치 생성]을 init 락으로 원자 실행 (병렬 task-init 번호 충돌 차단).
+ * --size·--title 주면 fork 직후 §1.3 빈 골격 task.md도 코드가 자동 생성(C1, 생성일·status=draft 자동).
+ * 성공 시 결과 JSON 한 줄을 stdout으로 출력 ({ taskNum, nnn, branch, wtPath, projectId, [docPath, registered, promoted | scaffoldError] }).
+ * 실패(정책 위배 / 동일 항목 진행중 / 동일 브랜치명 등) 시 stderr + exit 1.
+ * 골격 생성 실패는 워크트리 생성을 무효화하지 않음 — exit 0 + scaffoldError로 보고(스킬이 폴백 Write).
+ *
+ * 호출 주체: `/task-init` Step 6 (사용자 직접 호출도 가능하나 통상 스킬 경유).
+ */
+
+const path = require('path');
+
+const {
+  MANIFEST_NAME,
+  readManifest,
+  getMainWorktreePath,
+  forkTask,
+  scaffoldTaskDoc,
+} = require('./lib');
+
+const VALID_TYPES = ['feature', 'bug', 'improve', 'refactor', 'docs', 'chore'];
+const VALID_SIZES = ['micro', 'small', 'medium', 'large'];
+
+async function main() {
+  // 위치 인자 4개 + 플래그(--size <s> / --title "<t>" / --promote).
+  const argv = process.argv.slice(2);
+  const positional = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--promote') {
+      opts.promote = true;
+    } else if (a.startsWith('--')) {
+      opts[a.slice(2)] = argv[++i];
+    } else {
+      positional.push(a);
+    }
+  }
+  const [type, dev, src, slug] = positional;
+
+  if (!type || !dev || !src || !slug) {
+    console.error(
+      '사용법: npx @angar2/taskery fork <type> <dev> <src> <slug> [--size <s> --title "<제목>" --promote]',
+    );
+    console.error('예: npx @angar2/taskery fork feature claude BL-003 login --size medium --title "로그인 기능"');
+    process.exit(1);
+  }
+  if (opts.size && !VALID_SIZES.includes(opts.size)) {
+    console.error(`--size는 ${VALID_SIZES.join(' | ')} 중 하나 (받음: ${opts.size})`);
+    process.exit(1);
+  }
+  if (!VALID_TYPES.includes(type)) {
+    console.error(`type은 ${VALID_TYPES.join(' | ')} 중 하나 (받음: ${type})`);
+    process.exit(1);
+  }
+  if (!/^(BL-\d+|RM-\d+|DR)$/.test(src)) {
+    console.error(`src는 BL-NNN | RM-NNN | DR 형식 (받음: ${src})`);
+    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 fork 실패: ${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 = await forkTask(mainWt, { type, dev, src, slug });
+  } catch (e) {
+    console.error(`taskery fork 실패: ${e.message}`);
+    process.exit(1);
+  }
+
+  // 골격 자동 생성 (--size·--title 제공 시). 워크트리는 이미 생성됐으므로 실패해도 exit 1 X.
+  let out = result;
+  if (opts.size && opts.title) {
+    try {
+      const doc = scaffoldTaskDoc(mainWt, result.wtPath, {
+        taskNum: result.taskNum,
+        slug,
+        title: opts.title,
+        type,
+        size: opts.size,
+        promoted: !!opts.promote,
+      });
+      out = { ...result, docPath: doc.file, registered: doc.registered, promoted: doc.promoted };
+    } catch (e) {
+      out = { ...result, scaffoldError: e.message };
+    }
+  }
+  process.stdout.write(JSON.stringify(out) + '\n');
+}
+
+main();

package/bin/init.js

@@ -161,6 +161,29 @@ async function main() {
     console.log(`  .gitignore — 사용자 선택으로 패스`);
   }
 
+  // 4.7. MCP 서버 등록 — Claude는 .mcp.json 생성(첫 세션 승인 게이트), Codex는 명령 안내.
+  //   MCP 도구 8종 = lib core의 구조화 입구(CLI와 동일 함수). 미등록 환경은 npx CLI가 폴백.
+  if (platforms.includes('claude')) {
+    const mcpJsonPath = path.join(cwd, '.mcp.json');
+    let mcpConfig = { mcpServers: {} };
+    if (fs.existsSync(mcpJsonPath)) {
+      // 기존 .mcp.json의 다른 서버 보존 — taskery 항목만 머지.
+      try {
+        mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
+      } catch (e) {
+        mcpConfig = { mcpServers: {} };
+      }
+      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    }
+    if (!mcpConfig.mcpServers.taskery) {
+      mcpConfig.mcpServers.taskery = { command: 'npx', args: ['-y', '@angar2/taskery', 'mcp'] };
+      fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+      console.log(`  .mcp.json — taskery MCP 서버 등록 (첫 세션에서 승인 필요)`);
+    } else {
+      console.log(`  .mcp.json — taskery 서버 이미 등록됨, 스킵`);
+    }
+  }
+
   // 5. 결과 보고
   console.log(`\n✅ taskery init 완료`);
   console.log(`   카피: ${copied}개 / 스킵: ${skipped}개`);
@@ -168,11 +191,16 @@ async function main() {
   console.log(`   manifest: ${MANIFEST_NAME}\n`);
   const entryFile = platforms.includes('claude') ? 'CLAUDE.md' : 'AGENTS.md';
   console.log(`다음 단계:`);
-  console.log(`  1. ${entryFile} 정독 + 프로젝트 메타 + 검증 명령 채우기`);
+  let step = 1;
+  console.log(`  ${step++}. ${entryFile} 정독 + 프로젝트 메타 + 검증 명령 채우기`);
+  if (platforms.includes('claude')) {
+    console.log(`  ${step++}. Claude 첫 세션에서 taskery MCP 서버 승인 (.mcp.json — 구조화 도구 8종; 미승인 시 npx CLI 폴백)`);
+  }
   if (platforms.includes('codex')) {
-    console.log(`  2. Codex 최초 1회 '/hooks'로 hook trust 승인 (.codex/config.toml — git-guard / closed-immutable)`);
+    console.log(`  ${step++}. Codex 최초 1회 '/hooks'로 hook trust 승인 (.codex/config.toml — git-guard / closed-immutable)`);
+    console.log(`     + MCP 등록: codex mcp add taskery -- npx -y @angar2/taskery mcp`);
   }
-  console.log(`  3. 에이전트 진입 → '/project-init' → '/plan-init <기능그룹>' → '/task-init'\n`);
+  console.log(`  ${step++}. 에이전트 진입 → '/project-init' → '/plan-init <기능그룹>' → '/task-init'\n`);
 }
 
 main().catch((e) => {