@su-record/vibe 2.16.4 → 3.1.0

package/hooks/scripts/code-check.js

@@ -2,14 +2,18 @@
  * PostToolUse Hook - Write/Edit 후 코드 품질 검사 + 관찰 자동 캡처
  *
  * findings를 console.log가 아닌 반환값으로 전달 — 디스패처가 수집해 additionalContext에 주입.
- * P1 이슈 발견 시 run-ledger에 verifyRequired 상태 기록.
+ *
+ * 범위 (harness-review-2026-07-01 P1-4):
+ * 오탐률이 낮은 결정론적 하드룰(any/@ts-ignore, console.log)만 탐지한다.
+ * 함수 길이·중첩 깊이·매직 넘버 같은 휴리스틱은 모델이 컨텍스트 안에서 더
+ * 정확히 판단하므로 주입하지 않으며, 정규식 발견은 커밋 게이트
+ * (run-ledger verifyRequired)를 태우지 않는다 — 그 게이트는 결정론적
+ * 검증 흐름(vibe.verify) 전용이다.
  */
 import { getToolsBaseUrl, PROJECT_DIR, readProjectConfig } from './utils.js';
-import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { readFileSync } from 'fs';
 import path from 'path';
-import os from 'os';
 import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
-import { recordVerifyRequired } from './lib/run-ledger.js';
 
 const BASE_URL = getToolsBaseUrl();
 
@@ -176,180 +180,22 @@ function detectConsoleLogs(lines, filePath) {
 }
 
 /**
- * P2: 함수 길이 초과 탐지.
- * @param {string[]} lines
- * @returns {Array<{ line: number, match: string, severity: 'P2' }>}
- */
-function detectLongFunctions(lines) {
-  const findings = [];
-  let fnStart = -1;
-  let fnName = '';
-  let depth = 0;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const fnMatch = line.match(/(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()/);
-    if (fnMatch && depth === 0) {
-      fnStart = i;
-      fnName = fnMatch[1] || fnMatch[2] || 'anonymous';
-    }
-    depth += (line.match(/\{/g) || []).length - (line.match(/\}/g) || []).length;
-    if (fnStart !== -1 && depth <= 0) {
-      const length = i - fnStart + 1;
-      if (length > 50) {
-        findings.push({
-          line: fnStart + 1,
-          match: `function '${fnName}' is ${length} lines`,
-          severity: 'P2',
-          suggestion: `Extract lines ${fnStart + 20}–${i + 1} into a separate helper function`,
-        });
-      }
-      fnStart = -1;
-      depth = 0;
-    }
-  }
-  return findings;
-}
-
-/**
- * P2: 중첩 깊이 초과 탐지.
- * @param {string[]} lines
- * @returns {Array<{ line: number, match: string, severity: 'P2' }>}
- */
-function detectDeepNesting(lines) {
-  const findings = [];
-  let depth = 0;
-  let reported = false;
-
-  lines.forEach((line, i) => {
-    depth += (line.match(/\{/g) || []).length - (line.match(/\}/g) || []).length;
-    if (depth > 3 && !reported) {
-      findings.push({
-        line: i + 1,
-        match: `nesting depth ${depth} at line ${i + 1}`,
-        severity: 'P2',
-        suggestion: 'Use early return pattern: if (!condition) return; — instead of wrapping in else',
-      });
-      reported = true;
-    }
-    if (depth <= 3) reported = false;
-  });
-  return findings;
-}
-
-// magic number 무시 값 목록 (0, 1, -1, 2, 10, 100, 1000)
-const MAGIC_NUMBER_IGNORE = new Set(['10', '100', '1000']);
-
-/**
- * advisory: 매직 넘버 탐지 (P3, 스팸 방지 적용).
- * 무시 조건: 0/1/-1/2 (단일 digit), ALLCAPS const 선언, 테스트 파일, 배열 인덱스
- * @param {string[]} lines
- * @param {string} filePath
- * @returns {Array<{ line: number, match: string, severity: 'P3' }>}
- */
-function detectMagicNumbers(lines, filePath) {
-  // 테스트 파일은 스킵
-  if (/\.(test|spec)\.[jt]sx?$/.test(filePath) || /\/__tests__\//.test(filePath)) {
-    return [];
-  }
-
-  const findings = [];
-  lines.forEach((line, i) => {
-    // ALL_CAPS const 선언 줄은 스킵 (예: const LIMIT = 500)
-    if (/^\s*(?:export\s+)?const\s+[A-Z][A-Z0-9_]+\s*=/.test(line)) return;
-
-    const stripped = line.replace(/\/\/.*$/, '').replace(/(['"`]).*?\1/g, '""');
-    const nums = (stripped.match(/\b\d{2,}\b/g) || []).filter(n => MAGIC_NUMBER_IGNORE.has(n));
-    // 배열 인덱스: [NN] 패턴 제외
-    const nonIndexNums = (stripped.match(/\b\d{2,}\b/g) || []).filter(n => {
-      if (MAGIC_NUMBER_IGNORE.has(n)) return false;
-      // 배열 인덱스 [NN] 체크
-      const idx = stripped.indexOf(n);
-      if (idx > 0 && stripped[idx - 1] === '[') return false;
-      return true;
-    });
-
-    if (nonIndexNums.length > 0) {
-      findings.push({
-        line: i + 1,
-        match: `magic number(s): ${nonIndexNums.join(', ')}`,
-        severity: 'P3',
-        suggestion: `Extract to named constant: const LIMIT = ${nonIndexNums[0]};`,
-      });
-    }
-  });
-  return findings;
-}
-
-// ─── Failure Escalation Tracking ───
-
-const ESCALATION_THRESHOLD = 3;
-const ESCALATION_FILE = path.join(os.homedir(), '.vibe', 'failure-tracker.json');
-
-function loadFailureTracker() {
-  try {
-    if (existsSync(ESCALATION_FILE)) {
-      return JSON.parse(readFileSync(ESCALATION_FILE, 'utf8'));
-    }
-  } catch { /* ignore */ }
-  return {};
-}
-
-function saveFailureTracker(tracker) {
-  try {
-    writeFileSync(ESCALATION_FILE, JSON.stringify(tracker));
-  } catch { /* ignore */ }
-}
-
-/**
- * 실패 추적 — 동일 파일에 P1 이슈가 반복되면 에스컬레이션 메시지 반환.
+ * 하드룰 탐지기 실행. findings 배열 반환.
  * @param {string} filePath
- * @param {string[]} issues
- * @returns {string|null} 에스컬레이션 메시지 (없으면 null)
- */
-function trackFailure(filePath, issues) {
-  const tracker = loadFailureTracker();
-  const key = filePath;
-  const entry = tracker[key] || { count: 0, issues: [] };
-  entry.count += 1;
-  entry.issues = issues.slice(0, 3);
-  entry.lastSeen = new Date().toISOString();
-  tracker[key] = entry;
-  saveFailureTracker(tracker);
-
-  if (entry.count >= ESCALATION_THRESHOLD) {
-    const msg = `[ESCALATION] ${path.basename(filePath)}: 동일 이슈 ${entry.count}회 반복 — 수동 개입 필요`;
-    entry.count = 0;
-    saveFailureTracker(tracker);
-    return msg;
-  }
-  return null;
-}
-
-function clearFailure(filePath) {
-  const tracker = loadFailureTracker();
-  delete tracker[filePath];
-  saveFailureTracker(tracker);
-}
-
-/**
- * 모든 self-heal 탐지기 실행. findings 배열 반환.
- * @param {string} filePath
- * @returns {{ p1: string[], advisory: string[], escalation: string|null }}
+ * @returns {{ p1: string[] }}
  */
 function runDetectors(filePath) {
   let content;
   try {
     content = readFileSync(filePath, 'utf-8');
   } catch {
-    return { p1: [], advisory: [], escalation: null };
+    return { p1: [] };
   }
 
   const lines = content.split('\n');
   const isTs = TS_EXT_RE.test(filePath);
 
   const p1Findings = [];
-  const advisoryFindings = [];
 
   // P1: any 탐지 — TS 파일만
   if (isTs) {
@@ -365,32 +211,7 @@ function runDetectors(filePath) {
     p1Findings.push(`P1 console.log line ${f.line}: ${f.match.substring(0, 60)}`);
   }
 
-  // P2: 함수 길이
-  const fnHits = detectLongFunctions(lines).slice(0, 1);
-  for (const f of fnHits) {
-    advisoryFindings.push(`P2 ${f.match}`);
-  }
-
-  // P2: 중첩 깊이
-  const nestHits = detectDeepNesting(lines).slice(0, 1);
-  for (const f of nestHits) {
-    advisoryFindings.push(`P2 ${f.match}`);
-  }
-
-  // P3: 매직 넘버 (advisory, 스팸 방지)
-  const magicHits = detectMagicNumbers(lines, filePath).slice(0, 1);
-  for (const f of magicHits) {
-    advisoryFindings.push(`P3 ${f.match}`);
-  }
-
-  let escalation = null;
-  if (p1Findings.length > 0) {
-    escalation = trackFailure(filePath, p1Findings);
-  } else {
-    clearFailure(filePath);
-  }
-
-  return { p1: p1Findings, advisory: advisoryFindings, escalation };
+  return { p1: p1Findings };
 }
 
 /**
@@ -404,20 +225,12 @@ export async function run(ctx) {
   const files = getModifiedFiles(ctx);
   if (files.length === 0) return { exitCode: 0, findings };
 
-  // 1. Self-heal 탐지기 실행 (changed file only)
+  // 1. 하드룰 탐지기 실행 (changed file only) — additionalContext 주입만.
+  //    커밋 게이트(verifyRequired)는 태우지 않는다: 정규식 오탐 하나가
+  //    auto-commit을 차단하는 결합은 제거됨 (harness-review-2026-07-01).
   try {
-    const { p1, advisory, escalation } = runDetectors(files[0]);
-
+    const { p1 } = runDetectors(files[0]);
     for (const msg of p1) findings.push(msg);
-    for (const msg of advisory) findings.push(msg);
-    if (escalation) findings.push(escalation);
-
-    // P1 이슈 → run-ledger에 verifyRequired 기록
-    if (p1.length > 0) {
-      try {
-        recordVerifyRequired(PROJECT_DIR, p1[0]);
-      } catch { /* fail-open */ }
-    }
   } catch {
     // 탐지기 실패 → fail-open, 계속 진행
   }

package/hooks/scripts/context-save.js

@@ -162,17 +162,6 @@ async function main() {
     // Mark this urgency level as recently saved
     setDebounceLock(urgency);
 
-    // Sync TokenBudgetTracker with current context usage
-    try {
-      const { TokenBudgetTracker } = await import(`${LIB_URL}TokenBudgetTracker.js`);
-      const tracker = TokenBudgetTracker.getInstance(PROJECT_DIR);
-      const numPercent = Number(percent);
-      if (!isNaN(numPercent)) {
-        tracker.syncToPercent(numPercent);
-      }
-    } catch {
-      // TokenBudgetTracker sync is non-critical
-    }
   } catch {
     // 무시
   }

package/hooks/scripts/lib/scope-from-spec.js

@@ -28,10 +28,13 @@ function isRecentlyModified(file) {
 /**
  * scope-guard auto-derive 활성 여부.
  *
- * 기본값은 **on**. `.vibe/config.json` 의 `scopeGuard.enabled = false` 로
- * 명시적으로 끌 때만 SPEC → scope.json 자동 합성을 건너뛴다.
- * 노이즈 가드: SPEC 파일이 존재할 때만 scope.json 을 생성하며,
- * SPEC 없이 scope.json 생성이 필요한 경우 수동 작성(auto:false)을 사용한다.
+ * 기본값은 **off** — `.vibe/config.json` 의 `scopeGuard.enabled = true` 로
+ * 명시적 opt-in 했을 때만 SPEC → scope.json 자동 합성을 실행한다.
+ * (자동 ON 은 SPEC 외 편집에 노이즈 경고 회귀를 유발해 CLI 쪽에서 이미
+ * 기본 off 로 수정됐다. 이 훅이 기본 on 으로 남아 init/update 와
+ * SessionStart 가 서로 다른 scope 상태를 만들던 불일치를 통일 —
+ * harness-review-2026-07-01 P1-6. SSOT: src/cli/utils.ts `isScopeGuardOptedIn`
+ * 과 반드시 같은 기본값 유지.)
  *
  * 이미 `auto: false` scope.json 을 직접 만들어 둔 사용자는 영향 없음 — scope-guard.js
  * 자체는 scope.json 존재 여부만 본다.
@@ -45,10 +48,10 @@ export function isScopeGuardEnabled(projectDir) {
     for (const p of candidates) {
       if (!fs.existsSync(p)) continue;
       const cfg = JSON.parse(fs.readFileSync(p, 'utf-8'));
-      if (cfg && cfg.scopeGuard && cfg.scopeGuard.enabled === false) return false;
+      if (cfg && cfg.scopeGuard && cfg.scopeGuard.enabled === true) return true;
     }
   } catch { /* ignore */ }
-  return true;
+  return false;
 }
 
 /**

package/hooks/scripts/post-edit-dispatcher.js

@@ -8,7 +8,7 @@
  *
  * 실행 step (모두 비차단, config.hooks.{name}.enabled로 개별 토글):
  *   auto-format — 코드 스타일 정규화 (변경 시 finding 반환)
- *   code-check  — 린트/품질 검사 + P1 이슈 verifyRequired 기록
+ *   code-check  — 하드룰(any/console.log) 탐지 (additionalContext 주입만, 커밋 게이트 미연동)
  *   auto-test   — 관련 테스트 실행 (debounce 지원)
  *   post-edit   — console.log 감지
  *

package/hooks/scripts/prompt-dispatcher.js

@@ -69,21 +69,9 @@ if (/^\s*\/vibe\b/i.test(prompt)) {
 
 // 패턴 → 실행할 스크립트 매핑
 // 각 항목: { pattern, script, args, label }
+// (참고: 매직 키워드 배너 주입(keyword-detector)은 제거됨 — deprecated 별칭
+//  매핑은 CLAUDE.md 의 "Deprecated aliases" 표가 SSOT이며 모델이 직접 해석한다.)
 const DISPATCH_RULES = [
-  // 항상 실행 (경량 스크립트)
-  {
-    pattern: null, // always
-    script: 'keyword-detector.js',
-    args: [prompt],
-    label: 'keyword',
-  },
-
-  // 패턴 매칭이 필요한 스크립트
-  {
-    pattern: /ultrawork|ulw|울트라워크|ralph|ralplan/i,
-    script: null, // keyword-detector가 이미 처리
-    label: 'skip',
-  },
   // echo 전용 (stdout으로 직접 출력)
   {
     pattern: /e2e.*테스트|e2e.*test|playwright|브라우저.*테스트|browser.*test/i,
@@ -176,7 +164,7 @@ for (const rule of DISPATCH_RULES) {
   // 외부 LLM 호출(llm-orchestrate)은 부모/자식 timeout 을 정합시킨다 (B-2):
   // 자식은 hook 모드(primary 45s, fallback 없음, retry 없음)로 단일 시도 후 스스로
   // 정리하고, 부모는 그보다 약간 긴 50s 로 감싸 hard-kill 을 피한다.
-  // 경량 스크립트(keyword-detector 등)는 기존 30s 유지.
+  // 경량 스크립트는 기존 30s 유지.
   const isLlm = rule.script === 'llm-orchestrate.js';
   const execTimeout = isLlm ? 50000 : 30000;
   const childEnv = isLlm
@@ -207,7 +195,6 @@ await Promise.all(execPromises);
 
 // Evolution: Gap detection — log unmatched prompts for skill gap analysis
 const matched = DISPATCH_RULES.some(r =>
-  r.label !== 'skip' && r.label !== 'keyword' &&
   r.pattern !== null && r.pattern.test(prompt) &&
   (r.script || r.echo)
 );
@@ -218,12 +205,14 @@ if (!matched) {
       const utils = await import('./utils.js');
       const projectDir = process.env.CLAUDE_PROJECT_DIR || '.';
       const configPath = utils.projectVibePath(projectDir, 'config.json');
-      let gapEnabled = true;
+      // Evolution 은 동결(opt-in) — evolution.enabled === true 로 명시했을 때만
+      // gap 로깅을 수행한다 (기본 OFF, P3-3).
+      let gapEnabled = false;
       try {
         const fs = await import('fs');
         if (fs.existsSync(configPath)) {
           const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-          gapEnabled = config.evolution?.gapDetection !== false && config.evolution?.enabled !== false;
+          gapEnabled = config.evolution?.enabled === true && config.evolution?.gapDetection !== false;
         }
       } catch { /* ignore */ }
 

package/hooks/scripts/session-start.js

@@ -86,16 +86,29 @@ async function main() {
       import(`${BASE_URL}time/index.js`),
     ]);
 
-    const [session, time, memories, latestVersion] = await Promise.all([
-      memoryModule.startSession({ projectPath: PROJECT_DIR }),
+    // 인덱스만 주입 (harness-review-2026-07-01 P1-5):
+    // 이전에는 startSession 전체 요약(git log·테스트 상태·관찰·리플렉션·RAG
+    // goals/constraints/decisions)을 매 세션 덤프했다. 이제는 1줄 인덱스만
+    // 주입하고, 전체 컨텍스트 복원은 명시적 `/vibe.utils --continue` 전용.
+    const [time, memories, latestVersion] = await Promise.all([
       timeModule.getCurrentTime({ format: 'human', timezone: 'Asia/Seoul' }),
       memoryModule.listMemories({ limit: 5, projectPath: PROJECT_DIR }),
       getLatestVersionCached(),
     ]);
 
-    console.log(session.content[0].text);
-    console.log('\n' + time.content[0].text);
-    console.log('\n[Recent Memories]');
+    console.log(time.content[0].text);
+
+    // Active feature 1줄 인덱스
+    try {
+      const LIB_BASE_P = (await import('./utils.js')).getLibBaseUrl();
+      const iterMod = await import(`${LIB_BASE_P}IterationTracker.js`);
+      const progressLine = iterMod.getProgressSummary(PROJECT_DIR);
+      if (progressLine) {
+        console.log(`\n📋 ${progressLine} — resume full context: /vibe.utils --continue`);
+      }
+    } catch { /* progress index is best-effort */ }
+
+    console.log('\n[Memory Index — bodies on demand via recall_memory]');
     console.log(memories.content[0].text);
 
     // Phase 3 — Recipes + anti-patterns 인덱스 (post-task curation)
@@ -126,16 +139,17 @@ async function main() {
       }
     }
 
-    // Scope sync — 기본 ON. scopeGuard.enabled=false 로 명시적 opt-out 가능.
+    // Scope sync — 기본 OFF (opt-in: scopeGuard.enabled=true). SSOT: scope-from-spec.js.
     try {
       const { syncScopeFile, isScopeGuardEnabled } = await import('./lib/scope-from-spec.js');
-      if (isScopeGuardEnabled(PROJECT_DIR)) {
+      const guardOn = isScopeGuardEnabled(PROJECT_DIR);
+      if (guardOn) {
         const result = syncScopeFile(PROJECT_DIR);
         if (result.action === 'created' || result.action === 'updated' || result.action === 'removed') {
           console.log(`\n🚧 Scope ${result.action} from active SPECs (${path.relative(PROJECT_DIR, path.join(projectVibeRoot(PROJECT_DIR), 'scope.json'))})`);
         }
       }
-      // scope 상태 1줄 알림 — 컨텍스트에 주입되어 모델이 현재 scope 범위를 인지한다
+      // scope 상태 1줄 알림 — 활성 scope.json 이 있을 때만 (opt-out 사용자에게 노이즈 금지)
       const scopeJsonPath = path.join(projectVibeRoot(PROJECT_DIR), 'scope.json');
       if (fs.existsSync(scopeJsonPath)) {
         try {
@@ -144,7 +158,7 @@ async function main() {
           const modeLabel = scopeData.mode || 'warn';
           console.log(`\nscope-guard: ${featureLabel} (${modeLabel})`);
         } catch { /* ignore */ }
-      } else {
+      } else if (guardOn) {
         console.log('\nscope-guard: no active scope (no active SPEC or no derivable paths) — out-of-scope edits are not monitored');
       }
     } catch { /* scope sync is best-effort */ }
@@ -198,32 +212,8 @@ async function main() {
       storageA.close();
     } catch { /* autonomy not yet initialized, skip */ }
 
-    // Evolution status summary
-    try {
-      const LIB_BASE = (await import('./utils.js')).getLibBaseUrl();
-      const [memMod, regMod, insMod] = await Promise.all([
-        import(`${LIB_BASE}memory/MemoryStorage.js`),
-        import(`${LIB_BASE}evolution/GenerationRegistry.js`),
-        import(`${LIB_BASE}evolution/InsightStore.js`),
-      ]);
-      const storage = new memMod.MemoryStorage(PROJECT_DIR);
-      const registry = new regMod.GenerationRegistry(storage);
-      const insightStore = new insMod.InsightStore(storage);
-
-      const genStats = registry.getStats();
-      const active = genStats.byStatus?.active || 0;
-      const drafts = genStats.byStatus?.draft || 0;
-      const gaps = insightStore.getByType('skill_gap').length;
-
-      if (active > 0 || drafts > 0 || gaps > 0) {
-        const parts = [];
-        if (active > 0) parts.push(`${active} active skills`);
-        if (drafts > 0) parts.push(`${drafts} pending approval`);
-        if (gaps > 0) parts.push(`${gaps} gaps detected`);
-        console.log(`\n🧬 Evolution: ${parts.join(', ')}`);
-      }
-      storage.close();
-    } catch { /* evolution not yet initialized, skip */ }
+    // Evolution 상태 요약은 제거 — evolution 은 동결(opt-in) 상태이며
+    // 사용자는 `vibe evolution` CLI 로 명시적으로 조회한다 (P3-3).
   } catch (e) {
     console.log('[Session] Error:', e.message);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.16.4",
-  "description": "AI Coding Framework for Claude Code — 42+ agents, 73 skills, multi-LLM orchestration",
+  "version": "3.1.0",
+  "description": "AI Coding Framework for Claude Code — 10+ agents, 59 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
   "exports": {
@@ -9,11 +9,9 @@
     "./tools": "./dist/tools/index.js",
     "./tools/memory": "./dist/tools/memory/index.js",
     "./tools/convention": "./dist/tools/convention/index.js",
-    "./tools/semantic": "./dist/tools/semantic/index.js",
     "./tools/ui": "./dist/tools/ui/index.js",
     "./tools/time": "./dist/tools/time/index.js",
     "./tools/interaction": "./dist/tools/interaction/index.js",
-    "./orchestrator": "./dist/infra/orchestrator/index.js",
     "./memory": {
       "types": "./dist/infra/lib/memory/index.d.ts",
       "default": "./dist/infra/lib/memory/index.js"
@@ -35,7 +33,7 @@
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",
     "postinstall": "node -e \"import('./dist/cli/postinstall/main.js').then(m=>m.main()).catch(()=>{})\"",
-    "release": "pnpm version patch && npm publish --access public"
+    "release": "pnpm version patch && git push origin main --follow-tags"
   },
   "keywords": [
     "ai",
@@ -60,6 +58,9 @@
     "type": "git",
     "url": "git+https://github.com/su-record/vibe.git"
   },
+  "bugs": {
+    "url": "https://github.com/su-record/vibe/issues"
+  },
   "homepage": "https://github.com/su-record/vibe#readme",
   "publishConfig": {
     "access": "public"

package/skills/agents-md/SKILL.md

@@ -3,20 +3,29 @@ 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]
+description: "Author and optimize AGENTS.md / CLAUDE.md (same doctrine, different filenames): write new context files from scratch, or strip discoverable info and keep only gotchas. Based on Addy Osmani's AGENTS.md principles + Curse of Instructions research. Activates on agents.md, claude.md, context file authoring/optimization."
+triggers: [agents.md, claude.md, context file, optimize agents, optimize claude, write claude.md, create claude.md, project instructions]
 priority: 50
 ---
 
-# agents-md — Context File Optimizer
+# agents-md — Context File Author & Optimizer
 
-Optimize AGENTS.md / CLAUDE.md files.
+Author and optimize AGENTS.md / CLAUDE.md files. They are the **same doctrine
+under different filenames** — everything below applies to both.
 Reference: https://addyosmani.com/blog/agents-md/
 
-## Core Principle
+## Core Principles
 
 **One-line test**: "Can the agent discover this by reading the code?" → Yes = delete.
 
+**Every line has a cost** (Curse of Instructions): LLM compliance drops
+exponentially with instruction count — roughly 90% at 1 instruction, ~59% at 5,
+~44% at 10, ~15% at 15+. A short, precise file beats a long, comprehensive one.
+
+**Lost in the Middle**: LLMs attend to the beginning and end of a document and
+under-weight the middle. Most important rules → top. Frequently violated rules
+→ bottom. Background context → middle (OK if ignored).
+
 ## Step 1: Find Target Files
 
 Search project root for these files:
@@ -29,7 +38,32 @@ Glob: pattern=".github/copilot-instructions.md"
 Glob: pattern=".windsurfrules"
 ```
 
-If no target files exist, ask the user whether to create one.
+If a target exists → optimize it (Steps 2–3). If none exists and the user wants
+one → author it (Step 1b), then run the same optimization pass on the draft.
+
+## Step 1b: Authoring From Scratch
+
+Explore before writing: `package.json` (stack, scripts), `*.config.*`,
+`tsconfig.json`, `.env.example`, `Makefile`, `docker-compose.*`. Everything
+found this way is **discoverable — leave it out**.
+
+Then interview for what exploration cannot reveal (one question at a time,
+multiple-choice when possible):
+
+1. **Runtime traps** — differences invisible in code (Bun vs Node, ESM vs CJS)
+2. **Forbidden patterns** — libraries/approaches that burned the team before
+3. **Non-standard conventions** — naming/structure rules that differ from defaults
+4. **Architecture decisions** — business context the code can't explain
+5. **Boundaries** — files never to touch, changes requiring approval first
+
+Draft using `templates/claude-md.md`. Keep per-feature detail out — that
+belongs in SPEC files (`.vibe/specs/`), loaded only when relevant, not in the
+always-loaded context file. For large monorepos: one shared root file plus a
+small per-package file, instead of one giant root.
+
+Don't aim for perfect on day one: start minimal (30–50 lines), observe where
+the agent actually errs, add one line per *recurring* mistake. If the root
+cause is code structure, fix the code instead of adding a rule.
 
 ## Step 2: Classify Current Content
 
@@ -48,6 +82,7 @@ Information the agent can find by exploring the code:
 | API endpoint lists | "POST /api/users" | Router code |
 | Feature descriptions | "Phase 3 implements circuit breaker" | Readable from the code itself |
 | Architecture diagrams | ASCII box diagrams | Conceptual only, no mistake prevention |
+| Code style rules | Indentation, semicolons | Linter/formatter enforces them |
 
 ### Keep (Non-discoverable)
 
@@ -67,7 +102,13 @@ Traps and rules the agent cannot know from code alone:
 
 ### Anchoring Warning
 
-Mentioning a technology name anchors the agent toward it. "Don't use X" is useful, but "We use X" is unnecessary if already visible in code.
+Mentioning a technology name anchors the agent toward it. "Don't use X" is
+useful, but "We use X" is unnecessary if already visible in code.
+
+### Emphasis Budget
+
+`**IMPORTANT**` / `**MUST**` / `**NEVER**` work only while rare. Reserve them
+for P1 rules; emphasis on every line nullifies all of it.
 
 ## Step 3: Restructure
 
@@ -92,17 +133,15 @@ Rules:
 - Maximum 3 sections (Intro, Gotchas, Naming)
 - Each gotcha has **bold title + specific do/don't**
 - "Don't use X" is more useful than "We use X"
-- Target under 50 lines total
+- Target under 50 lines total; 60–150 acceptable for complex projects; at 300+ the agent ignores half of it
+- Don't inline everything — Claude Code follows `@docs/FILE.md` references and loads them on demand (progressive disclosure)
 
 ## Step 4: CLAUDE.md Separation (if applicable)
 
-If CLAUDE.md exists, keep only Claude-specific directives:
-
-```markdown
-{Claude-specific directives. e.g., "Always respond in Korean."}
-```
-
-Put common rules in AGENTS.md. Claude Code reads both.
+If both files exist, put common rules in AGENTS.md and keep only
+Claude-specific directives (e.g., "Always respond in Korean") in CLAUDE.md.
+Claude Code reads both. If only one file exists, it carries everything —
+same content rules apply.
 
 ## Step 5: Report Results
 
@@ -121,3 +160,11 @@ Put common rules in AGENTS.md. Claude Code reads both.
 ### Kept/Added Items
 - {Item}: {Reason for keeping}
 ```
+
+## Maintenance Signals
+
+| Signal | Meaning | Response |
+|--------|---------|----------|
+| Over 300 lines | Information overload | Split or trim |
+| Same mistake repeats | Rule is lost in noise | Emphasize or consolidate |
+| Adding rules has no effect | File is too long | Fix root cause |

package/skills/arch-guard/SKILL.md

@@ -180,4 +180,4 @@ The test generator reads this file and adds custom rules to the test suite.
 - `vibe init` → auto-detect and generate initial arch-guard tests
 - `vibe update` → refresh rules if directory structure changed
 - Pre-commit hook → run arch-guard tests before commit
-- `vibe.review` (skill) → architecture-reviewer checks against arch-rules.json
+- `vibe.review` (skill) → code-reviewer (focus: architecture) checks against arch-rules.json

package/skills/brand-assets/SKILL.md

@@ -3,8 +3,8 @@ name: brand-assets
 invocation: [auto]
 tier: standard
 description: "Auto-generate app icons (iOS/Android/PWA), favicons, and OG images from SPEC brand information using the Antigravity image backend. 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]
-priority: 65
+triggers: [favicon, logo, app icon, brand assets, branding, og image]
+priority: 60
 ---
 # Brand Assets Generation Skill