@su-record/vibe 2.9.38 → 2.10.0

package/hooks/scripts/recipe-extractor.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * Phase 3 — Recipe extractor (post-task curation)
+ *
+ * `/vibe.verify` 마지막 단계에서 호출됨. PostToolUse hot-path 가 아니라
+ * 명시적 1회 호출이므로 LLM 호출 허용.
+ *
+ * 동작:
+ *   1) `.vibe/metrics/current-run.jsonl` 읽기 (Phase 1 의 산출)
+ *   2) 휴리스틱 게이트: total_tools ≥ 8 AND fail_count ≥ 3 (= 어렵게 푼 task)
+ *   3) Haiku 로 3줄 요약 (When/Recipe/Anti-tip)
+ *   4) `.vibe/recipes/<slug>.md` 작성 (frontmatter 강제)
+ *
+ * 안전성:
+ *   - 모든 실패 silent — recipe 가 없는 게 잘못된 recipe 보다 낫다.
+ *   - LLM 호출 재귀 가드: VIBE_HOOK_DEPTH (다른 hook 와 동일 패턴).
+ *   - 테스트 모드: VIBE_RECIPE_LLM=mock 이면 LLM 스킵, 결정적 stub 사용.
+ *
+ * 사용:
+ *   node hooks/scripts/recipe-extractor.js
+ */
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { PROJECT_DIR, projectVibePath, projectVibeRoot } from './utils.js';
+
+const METRICS_DIR = projectVibePath(PROJECT_DIR, 'metrics');
+const CURRENT_RUN_JSONL = path.join(METRICS_DIR, 'current-run.jsonl');
+const CURRENT_RUN_JSON = path.join(METRICS_DIR, 'current-run.json');
+
+// 휴리스틱 게이트 — SPEC 의 "Risk #1: LLM 호출 비용" 대응
+const MIN_TOOLS = 8;
+const MIN_FAILS = 3;
+
+const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+
+// ─────────────────────────────────────────────────────
+// 재귀 가드
+// ─────────────────────────────────────────────────────
+function isRecursive() {
+  const depth = parseInt(process.env.VIBE_HOOK_DEPTH || '0', 10);
+  return depth >= 1;
+}
+
+// ─────────────────────────────────────────────────────
+// jsonl 로드 + 게이트 평가
+// ─────────────────────────────────────────────────────
+function loadJsonl() {
+  if (!fs.existsSync(CURRENT_RUN_JSONL)) return [];
+  return fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8')
+    .split('\n').filter(Boolean)
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+}
+
+function loadCurrentRunMeta() {
+  try { return JSON.parse(fs.readFileSync(CURRENT_RUN_JSON, 'utf-8')); }
+  catch { return { feature: null, startedAt: null, steps: 0 }; }
+}
+
+function evaluateGate(records) {
+  const total = records.length;
+  const fails = records.filter((r) => r.ok === false).length;
+  const lastIsSuccess = records.length > 0 && records[records.length - 1].ok === true;
+  const passes = total >= MIN_TOOLS && fails >= MIN_FAILS && lastIsSuccess;
+  return { passes, total, fails };
+}
+
+// ─────────────────────────────────────────────────────
+// LLM 프롬프트 빌드
+// ─────────────────────────────────────────────────────
+function buildPrompt(records, meta) {
+  const tools = [...new Set(records.map((r) => r.tool))].join(', ');
+  const failsByCategory = {};
+  for (const r of records) {
+    if (r.ok === false && r.error_category) {
+      failsByCategory[r.error_category] = (failsByCategory[r.error_category] || 0) + 1;
+    }
+  }
+  const failSummary = Object.entries(failsByCategory)
+    .map(([cat, n]) => `${cat}×${n}`).join(', ') || 'none';
+
+  // 최근 12개 호출만 — 토큰 절약
+  const tail = records.slice(-12).map((r, i) => {
+    const mark = r.ok ? '✓' : '✗';
+    const cat = r.error_category ? ` [${r.error_category}]` : '';
+    const file = r.target_file ? ` ${r.target_file}` : '';
+    return `${i + 1}. ${mark} ${r.tool}${file}${cat}`;
+  }).join('\n');
+
+  return `You are summarizing a successfully completed task into a 3-line reusable recipe.
+
+Task feature: ${meta.feature || 'unknown'}
+Tool calls: ${records.length} total, ${failSummary}
+Tools used: ${tools}
+
+Last 12 calls (chronological):
+${tail}
+
+Output EXACTLY 3 lines of plain text, no markdown, no preamble:
+LINE 1 — When to use this recipe (1 sentence, the situation/context)
+LINE 2 — The working approach (1-2 sentences, what actually worked)
+LINE 3 — Anti-tip: one thing to avoid (1 sentence)
+
+Be specific — name the tools, the file types, the error categories. Do not output anything else.`;
+}
+
+// ─────────────────────────────────────────────────────
+// claude CLI 호출 — --model 우선, fallback 가능
+// ─────────────────────────────────────────────────────
+let _modelFlagSupported = null;
+
+function detectModelFlag() {
+  if (_modelFlagSupported !== null) return _modelFlagSupported;
+  try {
+    const help = spawnSync('claude', ['--help'], { encoding: 'utf-8', timeout: 3000 });
+    const out = (help.stdout || '') + (help.stderr || '');
+    _modelFlagSupported = /--model\b/.test(out);
+  } catch {
+    _modelFlagSupported = false;
+  }
+  return _modelFlagSupported;
+}
+
+function callClaude(prompt) {
+  if (process.env.VIBE_RECIPE_LLM === 'mock') {
+    // 테스트용 결정적 stub
+    return {
+      ok: true,
+      text: 'When auth + integration retries pile up.\nUse claude CLI with explicit model + retry on transient failures.\nAvoid swallowing stderr; surface error_category for downstream classification.',
+    };
+  }
+
+  const args = ['--print', '--dangerously-skip-permissions'];
+  if (detectModelFlag()) {
+    args.unshift('--model', HAIKU_MODEL);
+  }
+
+  const env = { ...process.env, VIBE_HOOK_DEPTH: '1' };
+  try {
+    const r = spawnSync('claude', args, {
+      input: prompt,
+      encoding: 'utf-8',
+      timeout: 60_000,
+      env,
+    });
+    if (r.status !== 0) return { ok: false, text: '' };
+    const text = (r.stdout || '').trim();
+    if (!text) return { ok: false, text: '' };
+    return { ok: true, text };
+  } catch {
+    return { ok: false, text: '' };
+  }
+}
+
+// ─────────────────────────────────────────────────────
+// Recipe md 작성
+// ─────────────────────────────────────────────────────
+function timestampSlug() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function safeFeature(name) {
+  if (!name) return 'anon';
+  return String(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'anon';
+}
+
+function writeRecipe({ records, meta, summary }) {
+  const vibeRoot = projectVibeRoot(PROJECT_DIR);
+  const dir = path.join(vibeRoot, 'recipes');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const slug = `${safeFeature(meta.feature)}__${timestampSlug()}`;
+  const file = path.join(dir, `${slug}.md`);
+  if (fs.existsSync(file)) return null; // 동시 호출 dedup
+
+  const today = new Date().toISOString().slice(0, 10);
+  const tools = [...new Set(records.map((r) => r.tool))];
+  const failCount = records.filter((r) => r.ok === false).length;
+
+  // summary 가 3줄 보장 안 되면 채워서 안전화
+  const lines = summary.split('\n').map((l) => l.trim()).filter(Boolean);
+  while (lines.length < 3) lines.push('—');
+  const [whenLine, recipeLine, antiTip] = lines.slice(0, 3);
+
+  const body =
+`---
+slug: ${slug}
+type: recipe
+symptom-context: "${(meta.feature || 'unknown').replace(/"/g, '\\"')}"
+recipe: "${recipeLine.replace(/"/g, '\\"')}"
+tools-touched: [${tools.map((t) => JSON.stringify(t)).join(', ')}]
+retry-count-saved: ${failCount}
+created: ${today}
+source-run: "${meta.startedAt || 'unknown'}"
+confidence: low
+---
+
+# Recipe: ${meta.feature || 'unknown'}
+
+## When to use
+${whenLine}
+
+## What worked
+${recipeLine}
+
+## Avoid
+${antiTip}
+
+## Stats
+- Total tool calls: ${records.length}
+- Failures before success: ${failCount}
+- Tools touched: ${tools.join(', ')}
+- Source run started: ${meta.startedAt || 'unknown'}
+
+> Auto-generated by \`recipe-extractor.js\` from \`.vibe/metrics/current-run.jsonl\`. \
+Confidence \`low\` — single observation. Increment to \`medium\`/\`high\` when the same recipe is seen multiple times across runs.
+`;
+
+  fs.writeFileSync(file, body);
+  return file;
+}
+
+// ─────────────────────────────────────────────────────
+// 메인
+// ─────────────────────────────────────────────────────
+function main() {
+  if (isRecursive()) return; // claude CLI 가 다시 우리 hook 을 트리거하는 것 방지
+
+  let records;
+  try { records = loadJsonl(); } catch { return; }
+  if (records.length === 0) return;
+
+  const gate = evaluateGate(records);
+  if (!gate.passes) return;
+
+  const meta = loadCurrentRunMeta();
+  const prompt = buildPrompt(records, meta);
+  const llm = callClaude(prompt);
+  if (!llm.ok) return;
+
+  try { writeRecipe({ records, meta, summary: llm.text }); }
+  catch { /* silent */ }
+}
+
+try { main(); } catch { /* never throw */ }
+process.exit(0);

package/hooks/scripts/session-start.js

@@ -85,6 +85,25 @@ async function main() {
     console.log('\n[Recent Memories]');
     console.log(memories.content[0].text);
 
+    // Phase 3 — Recipes + anti-patterns 인덱스 (post-task curation)
+    // 본문이 아닌 1줄 요약만. session-context 가 비대해지지 않도록 N=5 상한.
+    try {
+      const { loadCurationIndex } = await import('./lib/curation-index.js');
+      const index = loadCurationIndex(PROJECT_DIR, { recipeLimit: 5, antiPatternLimit: 5 });
+      if (index.recipes.length > 0) {
+        console.log('\n[Recipes — succeeded patterns]');
+        for (const r of index.recipes) {
+          console.log(`  • ${r.slug} — ${r.summary}`);
+        }
+      }
+      if (index.antiPatterns.length > 0) {
+        console.log('\n[Anti-patterns — known pitfalls]');
+        for (const a of index.antiPatterns) {
+          console.log(`  ⚠ ${a.tag}: ${a.summary}`);
+        }
+      }
+    } catch { /* curation is best-effort */ }
+
     // Version check
     if (latestVersion) {
       const currentVersion = getCurrentVersion();

package/hooks/scripts/step-counter.js

@@ -1,44 +1,253 @@
 #!/usr/bin/env node
 /**
- * PostToolUse Hook - 툴콜 스텝 카운터
+ * PostToolUse Hook — 툴콜 스텝 카운터 + 패턴 로거 + 3-fail 감지기
  *
- * 목적: vibe 멀티-오케스트레이션의 "목표 달성까지 몇 스텝" 측정.
- *       모든 성공 툴콜을 1 스텝으로 집계하여 `/vibe.verify` 리포트에 노출.
+ * 책임 1) 모든 성공 툴콜을 1 스텝으로 집계 → `current-run.json`
+ *        ↳ /vibe.verify 가 history.jsonl에 append 후 출력
+ * 책임 2) 각 툴콜 한 줄을 `current-run.jsonl` 에 append (post-task-curation SPEC)
+ *        ↳ Phase 3 의 recipe extractor 가 소비
+ * 책임 3) (Phase 2) 실패 메시지 분류 + 같은 (file, category) 3회 반복 감지 →
+ *        `.vibe/anti-patterns/<slug>.md` 로 자동 저장.
  *
- * 저장 위치: .claude/vibe/metrics/current-run.json
- *   - /vibe.run 시작 시 overwrite (feature, startedAt, steps=0)
- *   - 이후 툴콜마다 steps += 1
- *   - /vibe.verify가 읽어서 history.jsonl에 append 후 출력
- *
- * 실패 시 조용히 통과 (차단 금지).
+ * 세 책임은 독립 — 어느 한쪽 실패가 다른 쪽을 막지 않는다.
+ * PostToolUse 는 hot path 이므로 LLM 호출/외부 spawn 금지, fs 만 사용.
  */
 import fs from 'fs';
 import path from 'path';
 import { PROJECT_DIR, projectVibePath } from './utils.js';
 
 const METRICS_DIR = projectVibePath(PROJECT_DIR, 'metrics');
-const CURRENT_RUN = path.join(METRICS_DIR, 'current-run.json');
+const ANTI_PATTERNS_DIR = projectVibePath(PROJECT_DIR, 'anti-patterns');
+const CURRENT_RUN_JSON = path.join(METRICS_DIR, 'current-run.json');
+const CURRENT_RUN_JSONL = path.join(METRICS_DIR, 'current-run.jsonl');
+const MAX_JSONL_LINES = 5000;
+const FAIL_WINDOW = 10;
+const FAIL_THRESHOLD = 3;
 
-try {
-  if (!fs.existsSync(METRICS_DIR)) {
-    fs.mkdirSync(METRICS_DIR, { recursive: true });
+// ─────────────────────────────────────────────────────
+// stdin / env 에서 PostToolUse payload 추출
+// ─────────────────────────────────────────────────────
+function readStdinSync() {
+  try {
+    if (process.stdin.isTTY) return null;
+    const buf = Buffer.alloc(65536);
+    const bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+    if (bytesRead > 0) return JSON.parse(buf.toString('utf-8', 0, bytesRead));
+  } catch { /* ignore */ }
+  return null;
+}
+
+function parseToolInput(raw) {
+  if (!raw) return {};
+  if (typeof raw === 'string') {
+    try { return JSON.parse(raw); } catch { return {}; }
   }
+  return raw;
+}
+
+function extractTargetFile(toolInput) {
+  const fp = toolInput.file_path || toolInput.notebook_path || toolInput.path || null;
+  if (!fp) return null;
+  try {
+    const abs = path.isAbsolute(fp) ? fp : path.resolve(PROJECT_DIR, fp);
+    const rel = path.relative(path.resolve(PROJECT_DIR), abs).replace(/\\/g, '/');
+    return rel || path.basename(fp);
+  } catch {
+    return fp;
+  }
+}
+
+function isResponseError(toolResponse) {
+  if (!toolResponse) return false;
+  if (typeof toolResponse === 'object') {
+    if (toolResponse.is_error === true) return true;
+    if (toolResponse.error) return true;
+    if (Array.isArray(toolResponse.errors) && toolResponse.errors.length > 0) return true;
+  }
+  return false;
+}
 
+// ─────────────────────────────────────────────────────
+// 책임 3a: error_category 분류 (regex 만 — regress tag enum 일부)
+// ─────────────────────────────────────────────────────
+const ERROR_CATEGORIES = [
+  { tag: 'nullability', re: /Cannot read propert(?:y|ies) of (?:undefined|null)|TypeError[^\n]*(?:undefined|null)/i },
+  { tag: 'type-narrow', re: /\bTS2345\b|not assignable to (?:parameter|type)/i },
+  { tag: 'compilation', re: /\bTS\d{4}\b|cannot find name|build failed|compilation (?:error|failed)/i },
+  { tag: 'syntax', re: /SyntaxError|Unexpected token/i },
+  { tag: 'integration', re: /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|connect failed/i },
+  { tag: 'auth', re: /\b(?:401|403)\b|unauthori[sz]ed|forbidden|invalid (?:token|credentials)/i },
+  { tag: 'permission', re: /EACCES|permission denied/i },
+  { tag: 'not-found', re: /ENOENT|no such file|not found/i },
+];
+
+function classifyError(toolResponse) {
+  if (!toolResponse) return null;
+  let text;
+  if (typeof toolResponse === 'string') text = toolResponse;
+  else if (toolResponse.error) text = String(toolResponse.error);
+  else if (Array.isArray(toolResponse.errors)) text = JSON.stringify(toolResponse.errors);
+  else if (toolResponse.content) text = JSON.stringify(toolResponse.content);
+  else text = JSON.stringify(toolResponse);
+
+  for (const { tag, re } of ERROR_CATEGORIES) {
+    if (re.test(text)) return tag;
+  }
+  return 'other';
+}
+
+// ─────────────────────────────────────────────────────
+// 책임 1: current-run.json 카운터
+// ─────────────────────────────────────────────────────
+function bumpCounter() {
   let data = { feature: null, startedAt: null, steps: 0 };
-  if (fs.existsSync(CURRENT_RUN)) {
+  if (fs.existsSync(CURRENT_RUN_JSON)) {
     try {
-      data = JSON.parse(fs.readFileSync(CURRENT_RUN, 'utf-8'));
-    } catch {
-      // 손상 파일 무시, 새로 시작
+      data = JSON.parse(fs.readFileSync(CURRENT_RUN_JSON, 'utf-8'));
+    } catch { /* 손상 → 새로 시작 */ }
+  }
+  if (!data.startedAt) data.startedAt = new Date().toISOString();
+  data.steps = (data.steps || 0) + 1;
+  fs.writeFileSync(CURRENT_RUN_JSON, JSON.stringify(data, null, 2));
+}
+
+// ─────────────────────────────────────────────────────
+// 책임 2: current-run.jsonl append + error_category 채움
+// ─────────────────────────────────────────────────────
+function appendJsonl(stdinPayload) {
+  const toolName = stdinPayload?.tool_name || process.argv[2] || '';
+  if (!toolName) return null;
+
+  const toolInput = parseToolInput(stdinPayload?.tool_input ?? process.env.TOOL_INPUT);
+  const ok = !isResponseError(stdinPayload?.tool_response);
+  const errorCategory = ok ? null : classifyError(stdinPayload?.tool_response);
+
+  const record = {
+    ts: new Date().toISOString(),
+    tool: toolName,
+    ok,
+    target_file: extractTargetFile(toolInput),
+    error_category: errorCategory,
+  };
+
+  fs.appendFileSync(CURRENT_RUN_JSONL, JSON.stringify(record) + '\n');
+
+  // 회전: 라인 수가 상한 초과 시 마지막 절반만 남김.
+  try {
+    const stat = fs.statSync(CURRENT_RUN_JSONL);
+    if (stat.size > 2 * 1024 * 1024) {
+      const lines = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8').split('\n').filter(Boolean);
+      if (lines.length > MAX_JSONL_LINES) {
+        const keep = lines.slice(-Math.floor(MAX_JSONL_LINES / 2));
+        fs.writeFileSync(CURRENT_RUN_JSONL, keep.join('\n') + '\n');
+      }
+    }
+  } catch { /* 회전 실패는 무시 */ }
+
+  return record;
+}
+
+// ─────────────────────────────────────────────────────
+// 책임 3b: 3-fail detector → anti-pattern md
+// ─────────────────────────────────────────────────────
+const SUGGESTED_STOPS = {
+  nullability: '같은 위치 null/undefined 처리 반복 — 타입 가드 또는 옵셔널 체이닝 필요',
+  'type-narrow': '같은 위치 타입 좁히기 반복 — 타입 정의 점검 필요',
+  compilation: '컴파일 실패 반복 — 타입/임포트 정의 확인 필요',
+  syntax: '구문 오류 반복 — 파서 호환성/버전 확인 필요',
+  integration: '외부 서비스 연결 실패 반복 — endpoint/포트/네트워크 점검 필요',
+  auth: '인증 실패 반복 — 토큰/자격증명 점검 필요',
+  permission: '권한 실패 반복 — 파일/디렉토리 권한 점검 필요',
+  'not-found': '리소스 부재 반복 — 경로/존재 확인 필요',
+  other: '같은 패턴 실패 반복 — 접근 방식 재검토 필요',
+};
+
+function fileSlug(targetFile) {
+  if (!targetFile) return 'global';
+  return targetFile.replace(/[\/\.]/g, '-');
+}
+
+function readTailWindow() {
+  if (!fs.existsSync(CURRENT_RUN_JSONL)) return [];
+  const raw = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8').split('\n').filter(Boolean);
+  return raw.slice(-FAIL_WINDOW).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+}
+
+function detectThreeFail() {
+  const window = readTailWindow();
+  const groups = new Map();
+  for (const r of window) {
+    if (r.ok || !r.error_category) continue;
+    const key = `${r.target_file ?? 'null'}::${r.error_category}`;
+    const cur = groups.get(key) ?? 0;
+    groups.set(key, cur + 1);
+  }
+  for (const [key, count] of groups) {
+    if (count >= FAIL_THRESHOLD) {
+      const sep = key.indexOf('::');
+      const file = key.slice(0, sep);
+      const cat = key.slice(sep + 2);
+      return { category: cat, targetFile: file === 'null' ? null : file, count };
     }
   }
+  return null;
+}
 
-  if (!data.startedAt) {
-    data.startedAt = new Date().toISOString();
+function writeAntiPattern({ category, targetFile, count }) {
+  if (!fs.existsSync(ANTI_PATTERNS_DIR)) {
+    fs.mkdirSync(ANTI_PATTERNS_DIR, { recursive: true });
   }
-  data.steps = (data.steps || 0) + 1;
+  const today = new Date().toISOString().slice(0, 10);
+  const dateSlug = today.replace(/-/g, '');
+  const fSlug = fileSlug(targetFile);
+  const slug = `${category}__${fSlug}__${dateSlug}`;
+  const filePath = path.join(ANTI_PATTERNS_DIR, `${slug}.md`);
+  if (fs.existsSync(filePath)) return; // dedup
 
-  fs.writeFileSync(CURRENT_RUN, JSON.stringify(data, null, 2));
+  const trigger = `(file=${targetFile ?? 'null'}, category=${category})`;
+  const stop = SUGGESTED_STOPS[category] ?? SUGGESTED_STOPS.other;
+  const content = `---
+slug: ${slug}
+type: anti-pattern
+root-cause-tag: ${category}
+trigger-signature: "${trigger}"
+fail-count: ${count}
+suggested-stop: "${stop}"
+created: ${today}
+---
+
+## Trigger
+${trigger} 이 ${FAIL_WINDOW} 툴콜 윈도우 내 ${count} 회 발생.
+
+## Suggested Stop
+${stop}
+
+> 자동 생성 — 같은 패턴 반복 시 다른 접근법을 고려하거나 사용자에게 조언을 구할 것.
+`;
+  fs.writeFileSync(filePath, content);
+}
+
+// ─────────────────────────────────────────────────────
+// 메인 — 세 책임을 독립적으로 try
+// ─────────────────────────────────────────────────────
+try {
+  if (!fs.existsSync(METRICS_DIR)) {
+    fs.mkdirSync(METRICS_DIR, { recursive: true });
+  }
+
+  const stdinPayload = readStdinSync();
+
+  try { bumpCounter(); } catch { /* 카운터 실패 무시 */ }
+  let lastRecord = null;
+  try { lastRecord = appendJsonl(stdinPayload); } catch { /* 로깅 실패 무시 */ }
+  try {
+    if (lastRecord && !lastRecord.ok && lastRecord.error_category) {
+      const trip = detectThreeFail();
+      if (trip) writeAntiPattern(trip);
+    }
+  } catch { /* anti-pattern 작성 실패 무시 */ }
 } catch {
   // Never block on counter failure
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.9.38",
+  "version": "2.10.0",
   "description": "AI Coding Framework for Claude Code — 56 agents, 45 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -27,6 +27,7 @@
     "dev": "tsc --watch",
     "gen:skill-docs": "npx tsx scripts/gen-skill-docs.ts",
     "gen:skill-docs:check": "npx tsx scripts/gen-skill-docs.ts --check",
+    "validate:skill-invocation": "npx tsx scripts/validate-skill-invocation.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",

package/skills/agents-md/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: agents-md
+user-invocable: false
+invocation: [auto, chain]
 tier: standard
 description: "Optimize AGENTS.md / CLAUDE.md by removing discoverable info and keeping only gotchas. Based on Addy Osmani's AGENTS.md principles. Activates on agents.md, claude.md, context file optimization."
 triggers: [agents.md, claude.md, context file, optimize agents, optimize claude]

package/skills/arch-guard/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: arch-guard
+user-invocable: false
+invocation: [auto]
 tier: core
 description: "Generate architecture boundary tests that mechanically enforce layer constraints. Use when adding new modules, refactoring layers, or after detecting circular dependencies. Creates import-rule tests (e.g., 'UI must not import DB') that fail CI on violation. Must use this skill when user mentions layer enforcement, dependency rules, or architectural boundaries — even casually like 'make sure services don't import controllers'."
 triggers: [arch guard, architecture test, layer test, boundary test, structural test, arch validation]

package/skills/brand-assets/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: brand-assets
+invocation: [auto]
 tier: standard
 description: "Auto-generate app icons (iOS/Android/PWA), favicons, and OG images from SPEC brand information using Gemini Image API. Use when the project needs visual brand assets, when user mentions 'icon', 'favicon', 'logo', or 'brand assets', or when a SPEC defines brand colors/identity but no assets exist yet. Outputs multiple sizes and formats ready for deployment. Not for complex illustration or marketing graphics — focused on app identity assets."
 triggers: [icon, favicon, brand, logo, app icon, branding, assets]

package/skills/capability-loop/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: capability-loop
+user-invocable: false
+invocation: [auto]
 tier: standard
 description: "When an agent fails, diagnose which capability is missing and build it into the repo. Activates after repeated agent failures, tool errors, or when a task keeps failing in the same way. Analyzes failure transcripts, identifies the missing guardrail/tool/abstraction/doc, and creates it permanently. Use this skill whenever you see 3+ similar failures, an agent hitting the same wall repeatedly, or the user asking 'why does this keep failing'."
 triggers: [capability loop, failure loop, build capability, missing capability, agent failed, why did it fail]

package/skills/characterization-test/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: characterization-test
+user-invocable: false
+invocation: [auto]
 tier: core
 description: "Lock existing behavior with characterization tests before modifying code. Use BEFORE any refactor, rewrite, or large-scale modification of existing code — especially legacy code without tests. Captures current input/output behavior as test cases so regressions are caught immediately. Must use this skill when touching files >200 lines with no existing tests, when user says 'refactor', 'rewrite', 'modernize', or 'clean up' existing code."
 triggers: [legacy, characterization test, lock behavior, regression prevention, before refactor, large file]

package/skills/chub-usage/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: chub-usage
+invocation: [auto]
 tier: optional
 description: "Context Hub (chub) — fetch vetted, up-to-date API documentation. Write accurate code based on the latest docs instead of training data when working with external APIs/SDKs."
 triggers: [chub, context hub, API docs, latest API, deprecated API, SDK documentation, api reference, 최신 문서]

package/skills/claude-md-guide/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: claude-md-guide
+user-invocable: false
+invocation: [auto]
 tier: standard
 description: "Guide for writing effective CLAUDE.md files from scratch. Evidence-based methodology from 40+ sources including research papers, official docs, and real-world examples. Covers 3-layer architecture, Curse of Instructions mitigation, progressive disclosure, and maintenance. Use when creating new CLAUDE.md, improving existing ones, or teaching team members how to write project instructions for AI agents."
 triggers: [claude-md guide, write claude.md, create claude.md, claude.md 작성, 클로드 문서, project instructions, claude-md]