triflux 10.0.0-alpha.1 → 10.0.0

package/bin/triflux.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, readSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, statSync, openSync, closeSync } from "fs";
-import { join, dirname, basename } from "path";
+import { join, dirname, basename, resolve } from "path";
 import { homedir, tmpdir } from "os";
 import { execSync, execFileSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
@@ -11,14 +11,17 @@ import { detectMultiplexer, getSessionAttachedCount, killSession, listSessions,
 import { forceCleanupTeam } from "../hub/team/nativeProxy.mjs";
 import { cleanupStaleOmcTeams, inspectStaleOmcTeams } from "../hub/team/staleState.mjs";
 import { getPipelineStateDbPath } from "../hub/pipeline/state.mjs";
+import { serializeHandoff } from "../scripts/lib/handoff.mjs";
 import { ensureGeminiProfiles } from "../scripts/lib/gemini-profiles.mjs";
 import { probePsmuxSupport, formatPsmuxInstallGuidance, formatPsmuxUpdateGuidance } from "../scripts/lib/psmux-info.mjs";
 import {
   addRegistryServer,
+  createDefaultRegistry,
   inspectRegistry,
   inspectRegistryStatus,
   removeRegistryServer,
   removeServerFromTargets,
+  saveRegistry,
   syncRegistryTargets,
 } from "../scripts/lib/mcp-guard-engine.mjs";
 import {
@@ -28,7 +31,13 @@ import {
   extractManagedHookFilename, getManagedRegistryHooks, ensureHooksInSettings,
   ensureCodexHubServerConfig,
 } from "../scripts/setup.mjs";
+import {
+  ensureGlobalClaudeRoutingSection,
+  ensureTfxSection,
+  getLatestRoutingTable,
+} from "../scripts/claudemd-sync.mjs";
 import { cleanupTmpFiles } from "../scripts/tmp-cleanup.mjs";
+import { checkNetworkAvailability, validateRuntimeCachePaths } from "../hub/lib/cache-guard.mjs";
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CLAUDE_DIR = join(homedir(), ".claude");
@@ -98,6 +107,17 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
       { name: "--json", type: "boolean", description: "버전 정보를 JSON으로 출력" },
     ],
   },
+  handoff: {
+    usage: "tfx handoff [--target local|remote] [--decision <text>] [--decision-file <path>] [--output <path>] [--json]",
+    description: "현재 작업 컨텍스트를 세션 핸드오프 프롬프트로 직렬화",
+    options: [
+      { name: "--target", type: "string", description: "주입 대상 (local|remote, 기본값 remote)" },
+      { name: "--decision", type: "string", description: "핸드오프 결정사항 (반복 지정 가능)" },
+      { name: "--decision-file", type: "string", description: "결정사항 파일 (라인/불릿 단위)" },
+      { name: "--output", type: "string", description: "생성한 핸드오프 프롬프트 저장 경로" },
+      { name: "--json", type: "boolean", description: "핸드오프 결과를 JSON으로 출력" },
+    ],
+  },
   list: {
     usage: "tfx list [--json]",
     description: "패키지 스킬과 사용자 스킬 목록 표시",
@@ -522,6 +542,26 @@ function describeSyncAction(src, dst, label) {
   };
 }
 
+function syncClaudeRoutingSectionsForCli() {
+  try {
+    const routingTable = getLatestRoutingTable();
+    return [
+      ensureTfxSection(join(PKG_ROOT, "CLAUDE.md"), routingTable),
+      ensureGlobalClaudeRoutingSection(CLAUDE_DIR),
+    ];
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "routing_sync_failed";
+    return [{ action: "unchanged", path: join(PKG_ROOT, "CLAUDE.md"), skipped: true, reason }];
+  }
+}
+
+function getClaudeRoutingSyncSummary(results) {
+  return results.reduce((summary, result) => ({
+    changed: summary.changed + (result.action === "created" || result.action === "updated" ? 1 : 0),
+    skipped: summary.skipped + (result.skipped ? 1 : 0),
+  }), { changed: 0, skipped: 0 });
+}
+
 // ── 크로스 셸 진단 ──
 
 function checkCliCrossShell(cmd, installHint) {
@@ -691,7 +731,7 @@ function buildSetupDryRunPlan() {
 }
 
 function cmdSetup(options = {}) {
-  const { dryRun = false, overrideVersion } = options;
+  const { dryRun = false, overrideVersion, skipClaudeMdSync = false } = options;
   if (dryRun) {
     printJson(buildSetupDryRunPlan());
     return;
@@ -781,6 +821,21 @@ function cmdSetup(options = {}) {
   // ── 결과 추적 ──
   const summary = [];
 
+  if (!skipClaudeMdSync) {
+    const claudeRoutingResults = syncClaudeRoutingSectionsForCli();
+    const claudeRoutingSummary = getClaudeRoutingSyncSummary(claudeRoutingResults);
+    if (claudeRoutingSummary.changed > 0) {
+      ok(`CLAUDE.md 라우팅: ${claudeRoutingSummary.changed}개 파일 반영`);
+      summary.push({ item: "CLAUDE.md 라우팅", status: "✅", detail: `${claudeRoutingSummary.changed}개 파일 반영` });
+    } else if (claudeRoutingSummary.skipped > 0) {
+      ok("CLAUDE.md 라우팅: 대상 파일 없음 (건너뜀)");
+      summary.push({ item: "CLAUDE.md 라우팅", status: "⏭️", detail: "대상 파일 없음" });
+    } else {
+      ok("CLAUDE.md 라우팅: 최신 상태");
+      summary.push({ item: "CLAUDE.md 라우팅", status: "✅", detail: "최신 상태" });
+    }
+  }
+
   const codexProfileResult = ensureCodexProfiles();
   if (!codexProfileResult.ok) {
     warn(`Codex profiles 설정 실패: ${codexProfileResult.message}`);
@@ -1128,13 +1183,10 @@ function buildMcpStatusRows(statusInfo) {
 }
 
 function ensureValidRegistryState() {
-  const registryState = inspectRegistry();
+  let registryState = inspectRegistry();
   if (!registryState.exists) {
-    throw createCliError(`MCP registry missing: ${registryState.path}`, {
-      exitCode: EXIT_CONFIG_ERROR,
-      reason: "configError",
-      fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`로 다시 생성하세요.",
-    });
+    saveRegistry(createDefaultRegistry());
+    registryState = inspectRegistry();
   }
   if (!registryState.valid) {
     throw createCliError(`MCP registry invalid: ${registryState.errors.join("; ")}`, {
@@ -1335,9 +1387,13 @@ async function cmdDoctor(options = {}) {
         warn(`MCP registry 자동 동기화 실패: ${error.message}`);
       }
     } else if (registryStateForFix.exists) {
-      warn("MCP registry invalid — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-reset", status: "ok" });
+      ok("MCP registry 손상 → 기본값으로 재생성됨");
     } else {
-      info("MCP registry 없음 — auto sync 건너뜀");
+      saveRegistry(createDefaultRegistry());
+      report.actions.push({ type: "mcp-registry-create", status: "ok" });
+      ok("MCP registry 없음 → 기본값으로 자동 생성됨");
     }
     console.log(`\n  ${LINE}`);
     info("수정 완료 — 아래 진단 결과를 확인하세요");
@@ -2157,28 +2213,27 @@ async function cmdDoctor(options = {}) {
   // ── MCP 중앙 레지스트리 ──
   section("MCP Registry");
   {
-    const registryState = inspectRegistry();
+    let registryState = inspectRegistry();
     if (!registryState.exists) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "missing",
+        status: "fixed",
         path: registryState.path,
-        fix: "config/mcp-registry.json을 복원하거나 `tfx mcp add <name> --url <url>`를 실행하세요.",
+        action: "기본값으로 자동 생성됨",
       });
-      warn("mcp-registry.json 없음");
-      info(`path: ${registryState.path}`);
-      issues++;
+      ok("mcp-registry.json 없음 → 기본값으로 자동 생성됨");
     } else if (!registryState.valid) {
+      saveRegistry(createDefaultRegistry());
+      registryState = inspectRegistry();
       addDoctorCheck(report, {
         name: "mcp-registry",
-        status: "invalid",
+        status: "fixed",
         path: registryState.path,
-        errors: registryState.errors,
-        fix: "config/mcp-registry.json 구조를 수정하세요.",
+        action: "손상 감지 → 기본값으로 재생성됨",
       });
-      fail("mcp-registry.json invalid");
-      for (const entry of registryState.errors) info(entry);
-      issues++;
+      warn("mcp-registry.json 손상 → 기본값으로 재생성됨");
     } else {
       const statusInfo = inspectRegistryStatus(registryState.registry);
       const invalidConfigs = statusInfo.configs.filter((config) => config.parseError);
@@ -2434,7 +2489,56 @@ async function cmdDoctor(options = {}) {
   });
 }
 
-function cmdUpdate() {
+function normalizeRemoteReachabilityUrl(remoteUrl) {
+  if (!remoteUrl) return null;
+  if (/^https?:\/\//iu.test(remoteUrl)) {
+    try {
+      return new URL(remoteUrl).origin;
+    } catch {
+      return null;
+    }
+  }
+  const scpMatch = /^git@([^:]+):/iu.exec(remoteUrl);
+  if (scpMatch) return `https://${scpMatch[1]}`;
+  if (/^ssh:\/\//iu.test(remoteUrl)) {
+    try {
+      return `https://${new URL(remoteUrl).hostname}`;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function resolveGitUpdateUrl(repoDir) {
+  try {
+    const remoteUrl = execSync("git remote get-url origin", {
+      encoding: "utf8",
+      timeout: 10_000,
+      cwd: repoDir,
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    }).trim();
+    return normalizeRemoteReachabilityUrl(remoteUrl);
+  } catch {
+    return null;
+  }
+}
+
+function resolveUpdateTargets({ installMode, pluginPath }) {
+  const repoDir = installMode === "plugin" ? (pluginPath || PKG_ROOT) : PKG_ROOT;
+  const gitUrl = resolveGitUpdateUrl(repoDir);
+
+  if (installMode === "npm-global" || installMode === "npm-local") {
+    return ["https://registry.npmjs.org/triflux"];
+  }
+  if (installMode === "plugin" || installMode === "git-local") {
+    return gitUrl ? [gitUrl] : ["https://github.com"];
+  }
+  return [];
+}
+
+async function cmdUpdate() {
   const isDev = isDevUpdateRequested(NORMALIZED_ARGS);
   const tagLabel = isDev ? ` ${YELLOW}--dev${RESET}` : "";
   console.log(`\n${BOLD}triflux update${RESET}${tagLabel}\n`);
@@ -2490,6 +2594,27 @@ function cmdUpdate() {
 
   info(`검색: ${installMode === "plugin" ? "플러그인" : installMode === "npm-global" ? "npm global" : installMode === "npm-local" ? "npm local" : installMode === "git-local" ? "git 로컬 저장소" : "알 수 없음"} 설치 감지`);
 
+  const networkTargets = resolveUpdateTargets({ installMode, pluginPath });
+  if (networkTargets.length > 0) {
+    const networkStatus = await checkNetworkAvailability(networkTargets);
+    if (!networkStatus.online) {
+      fail(`네트워크 확인 실패: ${networkStatus.unreachable.join(", ")}`);
+      info("네트워크 연결을 확인한 뒤 다시 시도하세요.");
+      return;
+    }
+    ok(`네트워크 확인 완료 (${networkStatus.reachable.join(", ")})`);
+  }
+
+  const cacheValidation = validateRuntimeCachePaths(join(CLAUDE_DIR, "cache"));
+  if (!cacheValidation.ok) {
+    warn(`런타임 캐시 검증 이슈 ${cacheValidation.issues.length}건 발견`);
+    for (const issue of cacheValidation.issues) {
+      info(`${issue.file}: ${issue.error}`);
+    }
+  } else {
+    ok("런타임 캐시 검증 완료");
+  }
+
   // 2. 설치 방식에 따라 업데이트
   const oldVer = PKG.version;
   let updated = false;
@@ -2654,9 +2779,23 @@ function cmdUpdate() {
       }
     }
 
+    // ── Post-update: CLAUDE.md 라우팅 동기화 ──
+    console.log(`\n${CYAN}── CLAUDE.md 라우팅 동기화 ──${RESET}`);
+    {
+      const claudeRoutingResults = syncClaudeRoutingSectionsForCli();
+      const claudeRoutingSummary = getClaudeRoutingSyncSummary(claudeRoutingResults);
+      if (claudeRoutingSummary.changed > 0) {
+        ok(`CLAUDE.md 라우팅 ${claudeRoutingSummary.changed}개 파일 반영`);
+      } else if (claudeRoutingSummary.skipped > 0) {
+        ok("CLAUDE.md 라우팅 대상 파일 없음 (건너뜀)");
+      } else {
+        ok("CLAUDE.md 라우팅 최신 상태");
+      }
+    }
+
     // ── Post-update: 설정 동기화 ──
     console.log(`\n${CYAN}── 설정 동기화 ──${RESET}`);
-    cmdSetup({ fromUpdate: true, overrideVersion: newVer });
+    cmdSetup({ fromUpdate: true, overrideVersion: newVer, skipClaudeMdSync: true });
 
     // ── Post-update: 훅 오케스트레이터 적용 ──
     {
@@ -2783,6 +2922,128 @@ function cmdVersion(options = {}) {
   console.log("");
 }
 
+function cmdHandoff(args = [], options = {}) {
+  const { json = false } = options;
+  const parsed = {
+    target: "remote",
+    decisions: [],
+    decisionFile: null,
+    output: null,
+    cwd: process.cwd(),
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const next = args[index + 1];
+
+    if (arg === "--target") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--target 값이 필요합니다 (local|remote)", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --target remote",
+        });
+      }
+      if (!["local", "remote"].includes(next)) {
+        throw createCliError(`지원하지 않는 --target 값: ${next}`, {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --target local|remote",
+        });
+      }
+      parsed.target = next;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--decision") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--decision 값이 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --decision \"결정사항\"",
+        });
+      }
+      parsed.decisions.push(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--decision-file") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--decision-file 경로가 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --decision-file .omx/notepad.md",
+        });
+      }
+      parsed.decisionFile = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--output" || arg === "--out") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError(`${arg} 경로가 필요합니다`, {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --output .omx/handoff.md",
+        });
+      }
+      parsed.output = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--cwd") {
+      if (!next || next.startsWith("-")) {
+        throw createCliError("--cwd 경로가 필요합니다", {
+          exitCode: EXIT_ARG_ERROR,
+          reason: "argError",
+          fix: "tfx handoff --cwd <project-path>",
+        });
+      }
+      parsed.cwd = resolve(next);
+      index += 1;
+      continue;
+    }
+
+    throw createCliError(`알 수 없는 handoff 옵션: ${arg}`, {
+      exitCode: EXIT_ARG_ERROR,
+      reason: "argError",
+      fix: "tfx handoff --target remote --output .omx/handoff.md",
+    });
+  }
+
+  const result = serializeHandoff({
+    target: parsed.target,
+    decisions: parsed.decisions,
+    decisionFile: parsed.decisionFile,
+    cwd: parsed.cwd,
+  });
+
+  if (parsed.output) {
+    const outputDir = dirname(parsed.output);
+    if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+    writeFileSync(parsed.output, `${result.prompt}\n`, "utf8");
+  }
+
+  if (json) {
+    printJson({
+      handoff: {
+        ...result,
+        ...(parsed.output ? { output: parsed.output } : {}),
+      },
+    });
+    return;
+  }
+
+  console.log(result.prompt);
+  if (parsed.output) {
+    console.log(`\n${DIM}saved:${RESET} ${parsed.output}`);
+  }
+}
+
 function cmdSchema(args = []) {
   const bundle = loadDelegatorSchemaBundle();
   const selector = String(args[0] || "").trim();
@@ -3054,6 +3315,7 @@ ${updateNotice}
     ${WHITE_BRIGHT}tfx update${RESET}     ${GRAY}최신 안정 버전으로 업데이트${RESET}
     ${DIM}  --dev / dev${RESET}   ${GRAY}dev 태그로 업데이트${RESET}
     ${WHITE_BRIGHT}tfx list${RESET}       ${GRAY}설치된 스킬 목록${RESET}
+    ${WHITE_BRIGHT}tfx handoff${RESET}    ${GRAY}현재 컨텍스트를 원격/로컬 핸드오프 프롬프트로 생성${RESET}
     ${WHITE_BRIGHT}tfx schema${RESET}     ${GRAY}CLI/Hub schema JSON 출력${RESET}
     ${WHITE_BRIGHT}tfx hub${RESET}        ${GRAY}MCP 메시지 버스 관리 (start/stop/status)${RESET}
     ${WHITE_BRIGHT}tfx tray${RESET}       ${GRAY}Windows 시스템 트레이 실행${RESET}
@@ -3553,12 +3815,15 @@ async function main() {
       cmdSchema(cmdArgs);
       return;
     case "update":
-      cmdUpdate();
+      await cmdUpdate();
       return;
     case "list":
     case "ls":
       cmdList({ json: JSON_OUTPUT });
       return;
+    case "handoff":
+      cmdHandoff(cmdArgs, { json: JSON_OUTPUT });
+      return;
     case "hub":
       await cmdHub(cmdArgs, { json: JSON_OUTPUT && (cmdArgs[0] || "status") === "status" });
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.0.0-alpha.1",
+  "version": "10.0.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/skills/_templates/base.md

@@ -0,0 +1,9 @@
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
+
+> **Telemetry**
+>
+> - Skill: `{{SKILL_NAME}}`
+> - Description: `{{SKILL_DESCRIPTION}}`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.

package/skills/_templates/deep.md

@@ -0,0 +1,6 @@
+## Deep Consensus Protocol
+
+1. Planner / Architect / Critic 역할을 분리해 독립적으로 초안을 만든다.
+2. 교차 검토로 충돌 항목을 수집하고 합의 가능한 변경을 우선 반영한다.
+3. 남은 불일치는 근거(리스크/비용/검증 가능성)와 함께 명시한다.
+4. 합의된 결과만 최종 실행 입력으로 승격한다.

package/skills/merge-worktree/SKILL.md.tmpl

@@ -0,0 +1,144 @@
+---
+name: merge-worktree
+description: "워크트리 브랜치를 main으로 squash-merge + conventional commit 자동 생성. codex-swarm 워크트리 자동 인식. '머지해', 'merge worktree', '워크트리 머지', '결과 수집', 'squash merge' 요청에 사용."
+argument-hint: "[target-branch]"
+disable-model-invocation: true
+---
+
+# Merge Worktree
+
+워크트리 브랜치를 대상 브랜치로 squash-merge하고 conventional commit 메시지를 자동 작성한다.
+
+## Current context
+
+* Git dir: `!git rev-parse --git-dir`
+* Current branch: `!git branch --show-current`
+* Recent commits: `!git log --oneline -20`
+* Working tree status: `!git status --short`
+
+## Instructions
+
+### Phase 1: Validation
+
+1. **Worktree 확인**: `git rev-parse --git-dir` 출력에 `/worktrees/`가 포함되어야 한다. 아니면 중지.
+
+2. **현재 브랜치 확인**: `git branch --show-current`
+
+3. **대상 브랜치 결정**:
+   * `$ARGUMENTS`가 있으면 해당 브랜치 사용
+   * 없으면 `main` 존재 확인, 없으면 `master`
+
+4. **원본 레포 경로 확인**: `git rev-parse --git-common-dir`의 부모 디렉토리
+
+5. **클린 상태 확인**: `git status --porcelain`이 비어있어야 한다. 미커밋 변경이 있으면 먼저 커밋/스태시 안내.
+
+### Phase 2: Research
+
+1. **커밋 이력**: `git log --oneline <target>..HEAD`
+
+2. **변경 파일 요약**: `git diff <target>...HEAD --stat`
+
+3. **전체 diff**: `git diff <target>...HEAD` — 꼼꼼히 읽는다.
+
+4. **핵심 파일 읽기**: 가장 큰 변경, 신규 파일, 삭제 파일을 Read로 확인.
+
+5. **변경 분류**:
+   * Features (신규 기능)
+   * Fixes (버그 수정)
+   * Refactors (구조 변경)
+   * Tests (테스트)
+   * Docs (문서)
+   * Config/Chore (빌드, CI, 의존성)
+
+6. **dominant type 결정**: `feat`, `fix`, `refactor`, `docs`, `chore`, `test` 중 하나
+
+### Phase 3: 대상 브랜치 준비
+
+1. **대상 브랜치 최근 커밋 확인**: `git -C <원본레포> log --oneline -10 <target>`
+
+2. **WIP 커밋 감지**: `wip:`, `auto-commit`, `WIP` 시작 커밋이 있으면 사용자에게 경고.
+
+3. **최신 fetch**: `git -C <원본레포> fetch origin <target> 2>/dev/null`
+
+### Phase 4: Squash Merge
+
+1. **대상 브랜치 checkout**:
+   ```
+   git -C <원본레포> checkout <target>
+   ```
+
+2. **squash merge 실행**:
+   ```
+   git -C <원본레포> merge --squash <워크트리브랜치>
+   ```
+
+3. **충돌 처리**: 충돌 발생 시 충돌 파일 목록 + 마커를 보여주고 **중지**. 자동 해결 시도 금지.
+
+### Phase 5: 커밋 메시지 작성 + 커밋
+
+Phase 2 분석 기반으로 아래 구조의 커밋 메시지를 작성한다:
+
+```
+<type>: <명령형 요약, 72자 이내, 마침표 없음>
+
+<무엇을 왜 했는지 2-4문장. 동기와 접근 방식 중심.>
+
+Changes:
+* <그룹별 변경 사항>
+* <하위 항목은 서브 불릿>
+```
+
+**규칙:**
+* `<type>`은 `feat`, `fix`, `refactor`, `docs`, `chore`, `test` 중 하나
+* 여러 유형이 섞이면 dominant 사용
+* 요약: 명령형 ("add", "fix", "refactor"), 마침표 없음, 72자 제한
+* 본문: *왜*와 *맥락*, *무엇*만이 아님
+* Changes: 관련 항목 그룹핑, 중요한 것 먼저
+* Co-Authored-By 푸터 **절대 추가 금지** (글로벌 설정 `includeCoAuthoredBy: false`)
+
+**커밋 실행**:
+```bash
+git -C <원본레포> commit -m "$(cat <<'EOF'
+<커밋 메시지>
+EOF
+)"
+```
+
+### Phase 6: 정리 + 검증
+
+1. **커밋 확인**: `git -C <원본레포> log --oneline -3`
+
+2. **워크트리 자동 정리**:
+   ```bash
+   git -C <원본레포> worktree remove <워크트리경로>
+   git -C <원본레포> branch -d <워크트리브랜치>
+   ```
+
+3. **codex-swarm 정리 감지**: 워크트리 경로가 `.codex-swarm/wt-*` 패턴이면:
+   * 같은 `.codex-swarm/` 디렉토리에 다른 워크트리가 남아있는지 확인
+   * 모든 워크트리가 머지 완료되었으면 `.codex-swarm/` 전체 정리 제안
+   * `git worktree prune` 실행
+
+4. **결과 보고**:
+   * 커밋 해시 + 요약
+   * 머지 대상 브랜치
+   * 워크트리 정리 완료 여부
+   * push 안내 (`git push`)
+
+## codex-swarm 연동
+
+이 스킬은 `tfx-codex-swarm`의 Step 10 "결과 수집"에서 자동으로 호출된다.
+codex-swarm이 완료한 각 워크트리에 대해 순차적으로 실행:
+
+```
+각 워크트리에 대해:
+  1. 워크트리로 cd
+  2. /merge-worktree main
+  3. 다음 워크트리로 이동
+```
+
+## 주의사항
+
+* force-push, destructive 연산은 사용자 확인 없이 절대 실행 금지
+* pre-commit hook 건너뛰기(`--no-verify`) 금지
+* 예상치 못한 상황이면 추측하지 말고 **중지 후 설명**

package/skills/shared/arguments-processing.md

@@ -0,0 +1,2 @@
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
+> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.

package/skills/shared/mandatory-rules.md

@@ -0,0 +1,6 @@
+> headless-guard가 이 규칙 위반을 **자동 차단**한다. 우회 불가.
+
+1. **`codex exec` / `gemini -p` 직접 호출 절대 금지**
+2. Codex·Gemini 작업은 직접 CLI 대신 반드시 TFX 래퍼(이 계열 스킬에서는 `Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:프롬프트:역할' --timeout 600")`)로만 실행
+3. Claude 작업은 `Agent(run_in_background=true)`
+4. 교차 검토/병렬 단계에서는 Bash + Agent를 같은 메시지에서 동시 호출

package/skills/shared/telemetry-segment.md

@@ -0,0 +1,6 @@
+> **Telemetry**
+>
+> - Skill: `{{SKILL_NAME}}`
+> - Description: `{{SKILL_DESCRIPTION}}`
+> - Session: 요청별 식별자를 유지해 단계별 실행 로그를 추적한다.
+> - Errors: 실패 시 원인/복구/재시도 여부를 구조화해 기록한다.