@haposoft/cafekit 0.8.11 → 0.8.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/docs-sync.cjs

@@ -15,13 +15,15 @@ try {
   const fs = require('fs');
   const path = require('path');
   const { execSync } = require('child_process');
+  const { loadConfig } = require('./lib/config.cjs');
 
   // Đọc stdin theo chuẩn hook
   const stdin = fs.readFileSync(0, 'utf8').trim();
   const payload = stdin ? JSON.parse(stdin) : {};
   const cwd = payload.cwd || process.cwd();
+  const config = loadConfig({ cwd, includeProject: false, includeAssertions: false, includeLocale: false });
 
-  const docsDir = path.join(cwd, 'docs');
+  const docsDir = path.join(cwd, config.paths?.docs || 'docs');
   
   // Xác định dự án đã có cốt lõi code hay chưa?
   const hasCode = fs.existsSync(path.join(cwd, 'src')) ||

package/src/claude/hooks/lib/color.cjs

@@ -16,14 +16,20 @@ const YELLOW = '\x1b[33m';
 const MAGENTA = '\x1b[35m';
 const CYAN = '\x1b[36m';
 
-// Detect color support at module load (cached)
-// Claude Code statusline runs via pipe but output displays in TTY - default to true
-const shouldUseColor = (() => {
+function detectColorDefault() {
   if (process.env.NO_COLOR) return false;
   if (process.env.FORCE_COLOR) return true;
   // Default true for statusline context (Claude Code handles TTY display)
   return true;
-})();
+}
+
+// Detect color support at module load (cached)
+// Claude Code statusline runs via pipe but output displays in TTY - default to true
+let shouldUseColor = detectColorDefault();
+
+function setColorEnabled(enabled) {
+  shouldUseColor = enabled === false ? false : detectColorDefault();
+}
 
 // Detect 256-color support via COLORTERM
 const has256Color = (() => {
@@ -90,6 +96,7 @@ module.exports = {
   dim,
   getContextColor,
   coloredBar,
-  shouldUseColor,
+  get shouldUseColor() { return shouldUseColor; },
+  setColorEnabled,
   has256Color
 };

package/src/claude/hooks/lib/config.cjs

@@ -9,11 +9,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const LOCAL_CONFIG_PATH = '.claude/.ck.json';
-const GLOBAL_CONFIG_PATH = path.join(os.homedir(), '.claude', '.ck.json');
+const RUNTIME_CONFIG_PATH = '.claude/runtime.json';
 
-// Legacy export for backward compatibility
-const CONFIG_PATH = LOCAL_CONFIG_PATH;
+const CONFIG_PATH = RUNTIME_CONFIG_PATH;
 
 const DEFAULT_CONFIG = {
   plan: {
@@ -61,10 +59,12 @@ const DEFAULT_CONFIG = {
   },
   assertions: [],
   statusline: 'full',
+  statuslineColors: true,
   hooks: {
     'session-init': true,
     'subagent-init': true,
     'dev-rules-reminder': true,
+    'skill-router': true,
     'usage': true,
     'context-tracking': true,
     'scout-block': true,
@@ -80,8 +80,8 @@ const DEFAULT_CONFIG = {
  * Arrays are replaced entirely (not concatenated) to avoid duplicate entries
  *
  * IMPORTANT: Empty objects {} are treated as "inherit from parent", not "replace with empty".
- * This allows global config to set hooks.foo: false and have it persist even when
- * local config has hooks: {} (empty = inherit, not reset to defaults).
+ * This allows runtime config to leave hooks as {} (inherit defaults)
+ * without resetting all default hook toggles.
  *
  * @param {Object} target - Base object
  * @param {Object} source - Object to merge (takes precedence)
@@ -463,36 +463,39 @@ function sanitizeConfig(config, projectRoot) {
 }
 
 /**
- * Load config with cascading resolution: DEFAULT → global → local
+ * Load config with cascading resolution: DEFAULT → runtime
  *
  * Resolution order (each layer overrides the previous):
  *   1. DEFAULT_CONFIG (hardcoded defaults)
- *   2. Global config (~/.claude/.ck.json) - user preferences
- *   3. Local config (./.claude/.ck.json) - project-specific overrides
+ *   2. Runtime config (./.claude/runtime.json) - installed CafeKit runtime config
  *
  * @param {Object} options - Options for config loading
  * @param {boolean} options.includeProject - Include project section (default: true)
  * @param {boolean} options.includeAssertions - Include assertions (default: true)
  * @param {boolean} options.includeLocale - Include locale section (default: true)
+ * @param {string} options.cwd - Project root for local config lookup (default: process.cwd())
  */
 function loadConfig(options = {}) {
-  const { includeProject = true, includeAssertions = true, includeLocale = true } = options;
-  const projectRoot = process.cwd();
+  const {
+    includeProject = true,
+    includeAssertions = true,
+    includeLocale = true,
+    cwd = process.cwd()
+  } = options;
+  const projectRoot = cwd;
 
-  // Load configs from both locations
-  const globalConfig = loadConfigFromPath(GLOBAL_CONFIG_PATH);
-  const localConfig = loadConfigFromPath(LOCAL_CONFIG_PATH);
+  // Load config from the installed CafeKit runtime config.
+  const runtimeConfig = loadConfigFromPath(path.join(projectRoot, RUNTIME_CONFIG_PATH));
 
   // No config files found - use defaults
-  if (!globalConfig && !localConfig) {
+  if (!runtimeConfig) {
     return getDefaultConfig(includeProject, includeAssertions, includeLocale);
   }
 
   try {
-    // Deep merge: DEFAULT → global → local (local wins)
+    // Deep merge: DEFAULT → runtime (runtime wins)
     let merged = deepMerge({}, DEFAULT_CONFIG);
-    if (globalConfig) merged = deepMerge(merged, globalConfig);
-    if (localConfig) merged = deepMerge(merged, localConfig);
+    if (runtimeConfig) merged = deepMerge(merged, runtimeConfig);
 
     // Build result with optional sections
     const result = {
@@ -522,6 +525,7 @@ function loadConfig(options = {}) {
     result.hooks = merged.hooks || DEFAULT_CONFIG.hooks;
     // Statusline mode
     result.statusline = merged.statusline || 'full';
+    result.statuslineColors = merged.statuslineColors !== false;
 
     return sanitizeConfig(result, projectRoot);
   } catch (e) {
@@ -540,7 +544,8 @@ function getDefaultConfig(includeProject = true, includeAssertions = true, inclu
     codingLevel: -1,  // Default: disabled (no injection, saves tokens)
     skills: { ...DEFAULT_CONFIG.skills },
     hooks: { ...DEFAULT_CONFIG.hooks },
-    statusline: 'full'
+    statusline: 'full',
+    statuslineColors: true
   };
   if (includeLocale) {
     result.locale = { ...DEFAULT_CONFIG.locale };
@@ -789,8 +794,13 @@ function extractTaskListId(resolved) {
  * @param {string} hookName - Hook name (script basename without .cjs)
  * @returns {boolean} Whether hook is enabled
  */
-function isHookEnabled(hookName) {
-  const config = loadConfig({ includeProject: false, includeAssertions: false, includeLocale: false });
+function isHookEnabled(hookName, options = {}) {
+  const config = loadConfig({
+    includeProject: false,
+    includeAssertions: false,
+    includeLocale: false,
+    cwd: options.cwd
+  });
   const hooks = config.hooks || {};
   // Return true if undefined (default enabled), otherwise return the boolean value
   return hooks[hookName] !== false;
@@ -798,8 +808,7 @@ function isHookEnabled(hookName) {
 
 module.exports = {
   CONFIG_PATH,
-  LOCAL_CONFIG_PATH,
-  GLOBAL_CONFIG_PATH,
+  RUNTIME_CONFIG_PATH,
   DEFAULT_CONFIG,
   INVALID_FILENAME_CHARS,
   deepMerge,

package/src/claude/hooks/lib/skill-router-routes.cjs

@@ -0,0 +1,190 @@
+const MIN_SCORE = 4;
+const WEIGHTS = { strong: 6, medium: 3, weak: 1, negative: -5 };
+
+const ROUTES = [
+  route('hapo:hotfix', 'urgent fix or production regression', 100, {
+    strong: ['hotfix', 'fix bug', 'fix lỗi', 'fix loi', 'sửa lỗi', 'sua loi', 'production bug', 'prod bug', 'regression', 'lỗi production', 'loi production', 'sửa gấp', 'sua gap', 'バグ修正', '不具合修正', '本番障害', '本番バグ', '緊急修正', '至急修正', 'リグレッション'],
+    medium: ['khẩn cấp', 'khan cap', 'production', 'critical bug', 'rollback', '修正して', '直して', '緊急', '本番', '重大バグ', 'ロールバック', '障害対応'],
+    weak: ['fix', 'fixing', 'sửa', 'sua', 'urgent', 'emergency', 'release is broken', '修正', '直す', '至急', 'リリースが壊れた'],
+    negative: ['slide', 'pptx', 'spec', 'brainstorm'],
+  }),
+  route('hapo:debug', 'bug investigation or failure diagnosis', 90, {
+    strong: ['debug', 'root cause', 'diagnose', 'stack trace', 'không chạy', 'khong chay', 'デバッグ', '原因調査', '根本原因', 'スタックトレース', '動かない'],
+    medium: ['bug', 'error', 'exception', 'failing', 'failed', 'failure', 'broken', 'lỗi', 'loi', 'tại sao', 'tai sao', 'vì sao', 'vi sao', 'nguyên nhân', 'nguyen nhan', 'ci fail', 'build fail', 'バグ', 'エラー', '例外', '失敗', '壊れている', 'なぜ', '原因', 'ci失敗', 'ビルド失敗'],
+    weak: ['sai', 'fail', 'issue', 'problem', '問題', '不具合'],
+    negative: ['commit', 'push', 'slide', 'pptx'],
+  }),
+  route('hapo:specs', 'specification, requirements, design, tasks, or spec validation', 80, {
+    strong: ['spec', 'specs', 'requirements', 'acceptance criteria', 'task breakdown', 'đặc tả', 'dac ta', '仕様', '仕様書', '要件', '受け入れ条件', 'タスク分解', '仕様を作って', '仕様を作成'],
+    medium: ['requirement', 'ears', 'design doc', 'scope', '--validate', 'yêu cầu', 'yeu cau', 'phạm vi', 'pham vi', 'validate spec', 'kiểm tra spec', 'kiem tra spec', '要求', '設計書', 'スコープ', '検証', '仕様を確認'],
+    weak: ['tính năng mới', 'tinh nang moi', 'feature idea', 'user story', 'criteria', 'task list', '新機能', 'ユーザーストーリー', '基準', 'タスクリスト'],
+    negative: ['commit', 'push', 'bug', 'error', 'production', 'pptx', 'pdf'],
+  }),
+  route('hapo:develop', 'implementation from an approved spec or task list', 75, {
+    strong: ['develop', 'implement', 'implementation', 'theo spec', 'theo specs', 'approved spec', 'làm theo spec', 'lam theo spec', '実装', '開発', '仕様に沿って', '仕様どおり', '承認済み仕様'],
+    medium: ['build this', 'code this', 'start task', 'run task', 'thực hiện task', 'thuc hien task', 'phát triển', 'phat trien', 'bắt đầu implement', 'bat dau implement', 'vào code', 'vao code', '作って', 'コードを書いて', 'タスクを開始', 'タスクを実行', '開発して', '実装して'],
+    weak: ['triển khai', 'trien khai', 'đưa vào code', 'dua vao code', 'code feature', 'コード化', '機能を作る'],
+    negative: ['bug', 'debug', 'review', 'test only', 'commit'],
+  }),
+  route('hapo:test', 'test, verification, QA, or runtime validation', 70, {
+    strong: ['unit test', 'integration test', 'e2e', 'playwright', 'coverage', 'test all', 'run all tests', 'test toàn bộ', 'test toan bo', 'kiểm thử', 'kiem thu', 'kiểm tra toàn bộ', 'kiem tra toan bo', '単体テスト', '結合テスト', '全体テスト', 'カバレッジ', 'テストして'],
+    medium: ['test', 'tests', 'testing', 'qa', 'verify', 'verification', 'kiểm tra chạy', 'kiem tra chay', 'xác minh', 'xac minh', 'テスト', '検証', '確認', '動作確認', '全体確認'],
+    weak: ['assert', 'runtime proof', 'manual qa', 'end to end', 'smoke test', 'アサート', 'スモークテスト'],
+    negative: ['spec', 'requirements', 'commit', 'push'],
+  }),
+  route('hapo:code-review', 'code review, audit, security, or quality assessment', 68, {
+    strong: ['code review', 'security review', 'performance review', 'đánh giá code', 'danh gia code', 'コードレビュー', 'セキュリティレビュー', '性能レビュー'],
+    medium: ['review', 'audit', 'quality', 'đánh giá', 'danh gia', 'kiểm tra chất lượng', 'kiem tra chat luong', 'レビュー', '監査', '品質', '品質確認'],
+    weak: ['risk', 'maintainability', 'readability', 'vulnerability', 'lỗ hổng', 'lo hong', 'リスク', '保守性', '可読性', '脆弱性'],
+    negative: ['slide', 'pptx', 'commit and push'],
+  }),
+  route('hapo:git', 'git, commit, push, branch, tag, or pull request workflow', 65, {
+    strong: ['commit', 'push', 'pull request', 'git', 'đẩy lên', 'day len', 'コミット', 'プッシュ', 'プルリク', 'リリースして'],
+    medium: ['pr ', 'branch', 'tag', 'release', 'publish', 'merge', 'rebase', 'ブランチ', 'タグ', 'リリース', '公開', 'マージ', 'リベース'],
+    weak: ['origin', 'remote', 'checkout', 'stash', 'version bump', 'リモート', 'チェックアウト', 'スタッシュ', 'バージョン更新'],
+    negative: ['deploy', 'test', 'review only'],
+  }),
+  route('hapo:inspect', 'codebase discovery, file search, structure scan, or locating implementation areas', 64, {
+    strong: ['inspect', 'codebase scan', 'scan codebase', 'scan source', 'file discovery', 'find files', 'locate files', 'xem source', 'xem codebase', 'kiểm tra source', 'kiem tra source', 'kiểm tra source code', 'kiem tra source code', 'quét source', 'quet source', 'quét codebase', 'quet codebase', 'kiểm tra cấu trúc', 'kiem tra cau truc', 'コード構造', 'ソース確認', 'コードベース確認', 'ファイル探索', '構造を確認'],
+    medium: ['search files', 'find where', 'where is', 'project structure', 'code structure', 'repo structure', 'source code', 'tìm file', 'tim file', 'tìm trong source', 'tim trong source', 'cấu trúc project', 'cau truc project', 'ở đâu', 'o dau', 'nằm đâu', 'nam dau', '関連ファイル', 'どこにある', 'プロジェクト構造', 'リポジトリ構造', '探して'],
+    weak: ['scan', 'inspect code', 'explore code', 'xem qua', 'xem giúp', '調べて', '確認して'],
+    negative: ['bug', 'error', 'lỗi', 'loi', 'fail', 'failure', 'production', 'hotfix', 'fix', 'sửa', 'sua', 'debug', 'develop', 'implement', 'test', 'commit', 'push', 'slide', 'pptx'],
+  }),
+  route('hapo:impact-analysis', 'impact analysis before changing existing behavior', 64, {
+    strong: ['impact analysis', 'blast radius', 'ảnh hưởng', 'anh huong', 'tác động', 'tac dong', '影響分析', '影響範囲', '影響', '副作用'],
+    medium: ['impact', 'liên quan những đâu', 'lien quan nhung dau', 'affected files', 'dependency impact', '関連箇所', '影響ファイル', '依存関係'],
+    weak: ['before changing', 'risk area', 'downstream', 'upstream', 'side effect', '変更前', 'リスク範囲', '下流', '上流'],
+    negative: ['slide', 'pptx'],
+  }),
+  route('hapo:frontend-design', 'UI/UX design, visual style, layout, or color system', 62, {
+    strong: ['ui design', 'visual style', 'color system', 'thiết kế giao diện', 'thiet ke giao dien', 'màu sắc', 'mau sac', 'uiデザイン', '画面デザイン', 'ビジュアルスタイル', '配色'],
+    medium: ['ux', 'layout', 'style', 'theme', 'responsive design', 'giao diện', 'giao dien', 'wireframe', 'レイアウト', 'スタイル', 'テーマ', 'レスポンシブデザイン', '画面', 'ワイヤーフレーム', '色'],
+    weak: ['palette', 'typography', 'spacing', 'polish ui', 'mockup', 'prototype', 'パレット', 'タイポグラフィ', '余白', 'モックアップ', 'プロトタイプ'],
+    negative: ['backend', 'api', 'database'],
+  }),
+  route('hapo:react-best-practices', 'React and Next.js performance patterns, rerender optimization, and Vercel best practices', 60, {
+    strong: ['react best practices', 'next.js best practices', 'vercel react best practices', 'react performance', 'next.js performance', 'optimize react', 'optimize next.js', 'rerender nhiều', 'rerender nhieu', 'nhiều rerender', 'nhieu rerender', 'tối ưu react', 'toi uu react', 'tối ưu next.js', 'toi uu next.js', 'reactベストプラクティス', 'next.jsベストプラクティス', 'react最適化', 'next.js最適化', 'react性能'],
+    medium: ['bundle optimization', 'bundle size', 'rerender optimization', 're-render optimization', 'data fetching', 'server component', 'client component', 'suspense', 'hydration', 'waterfall', 'usememo', 'usecallback', 'react cache', 'optimize', 'optimization', 'tối ưu', 'toi uu', 'tối ưu rerender', 'toi uu rerender', 'tối ưu bundle', 'toi uu bundle', 'バンドル最適化', '再レンダー最適化', '最適化', 'データ取得', 'サーバーコンポーネント', 'クライアントコンポーネント', 'ハイドレーション'],
+    weak: ['react', 'next.js', 'memo', 'rerender', 're-render', 'render performance', 'component performance', 'waterfalls', 'lazy state', 'dynamic import', 'react pattern', 'next.js pattern', 'レンダー性能', 'コンポーネント性能', '動的インポート'],
+    negative: ['backend', 'api', 'database', 'slide', 'pptx', 'commit', 'push'],
+  }),
+  route('hapo:frontend-development', 'frontend implementation work', 58, {
+    strong: ['react', 'next.js', 'vite', 'frontend', 'tailwind', 'web app', 'フロントエンド', 'webアプリ'],
+    medium: ['component', 'css', 'html', 'browser ui', 'client side', 'giao diện react', 'コンポーネント', 'ブラウザui', 'クライアント側', 'react画面'],
+    weak: ['state management', 'hook', 'form', 'table', 'dashboard ui', '状態管理', 'フック', 'フォーム', 'テーブル', 'ダッシュボードui'],
+    negative: ['best practices', 'performance', 'optimize', 'optimization', 'rerender', 're-render', 'tối ưu', 'toi uu', '再レンダー', '最適化', '性能', 'backend only', 'database only', 'slide', 'pptx'],
+  }),
+  route('hapo:backend-development', 'backend, API, database, or service implementation', 58, {
+    strong: ['backend', 'api', 'database', 'endpoint', 'server', 'service', 'バックエンド', 'データベース', 'エンドポイント', 'サーバー', 'サービス'],
+    medium: ['db', 'sql', 'postgres', 'mysql', 'migration', 'schema', 'worker', 'queue', 'マイグレーション', 'スキーマ', 'ワーカー', 'キュー'],
+    weak: ['controller', 'route handler', 'repository', 'model', 'auth service', 'コントローラ', 'ルートハンドラ', 'リポジトリ', 'モデル', '認証サービス'],
+    negative: ['frontend only', 'slide', 'pptx'],
+  }),
+  route('hapo:mobile-development', 'mobile app implementation', 56, {
+    strong: ['mobile', 'ios', 'android', 'react native', 'flutter', 'モバイル'],
+    medium: ['app store', 'play store', 'native app', 'mobile screen', 'アプリストア', 'playストア', 'ネイティブアプリ', 'モバイル画面'],
+    weak: ['gesture', 'push notification', 'offline sync', 'ジェスチャー', 'プッシュ通知', 'オフライン同期'],
+    negative: ['web only', 'desktop only'],
+  }),
+  route('hapo:devops', 'deployment, infrastructure, CI/CD, or operations work', 54, {
+    strong: ['deploy', 'deployment', 'docker', 'kubernetes', 'ci/cd', 'github actions', 'デプロイ', 'デプロイメント'],
+    medium: ['vercel', 'infra', 'infrastructure', 'devops', 'pipeline', 'environment variable', 'インフラ', 'パイプライン', '環境変数'],
+    weak: ['build server', 'container', 'helm', 'terraform', 'monitoring', 'ビルドサーバー', 'コンテナ', '監視'],
+    negative: ['slide', 'pptx', 'spec only'],
+  }),
+  route('hapo:generate-graph', 'diagram, graph, architecture map, or flow visualization', 52, {
+    strong: ['diagram', 'graph', 'mermaid', 'flowchart', 'architecture diagram', 'sơ đồ', 'so do', '図', '図解', 'ダイアグラム', 'グラフ', 'フローチャート', '構成図'],
+    medium: ['biểu đồ', 'bieu do', 'visualize', 'sequence diagram', 'data flow', '可視化', 'シーケンス図', 'データフロー'],
+    weak: ['mind map', 'dependency map', 'system map', 'マインドマップ', '依存関係図', 'システム図'],
+    negative: ['pptx', 'slide deck'],
+  }),
+  route('hapo:brainstorm', 'early ideation or unclear solution direction', 50, {
+    strong: ['brainstorm', 'ý tưởng', 'y tuong', 'phương án', 'phuong an', 'gợi ý', 'goi y', 'ブレスト', 'アイデア', '案', '提案して', '相談'],
+    medium: ['idea', 'ideas', 'approach', 'options', 'tradeoff', 'chủ đề', 'chu de', 'cần làm gì', 'can lam gi', 'アプローチ', '選択肢', 'トレードオフ', 'テーマ', '何をすれば'],
+    weak: ['proposal', 'strategy', 'plan options', 'explore', 'direction', 'seminar topic', '提案', '戦略', '方向性', '検討'],
+    negative: ['commit', 'push', 'bug', 'error'],
+  }),
+  route('hapo:research', 'technical research or best-practice lookup', 48, {
+    strong: ['research', 'best practice', 'tìm hiểu', 'tim hieu', 'nghiên cứu', 'nghien cuu', '調査', 'リサーチ', 'ベストプラクティス'],
+    medium: ['documentation', 'docs', 'compare tools', 'latest docs', 'official docs', 'ドキュメント', '比較', '最新ドキュメント', '公式ドキュメント'],
+    weak: ['investigate options', 'market scan', 'reference', 'source material', '選択肢を調べる', '参考資料', '資料'],
+    negative: ['commit', 'push'],
+  }),
+  route('hapo:pptx', 'presentation or PowerPoint work', 46, {
+    strong: ['pptx', 'powerpoint', 'slide deck', 'presentation deck', 'スライド資料', 'プレゼン資料'],
+    medium: ['slide', 'slides', 'deck', 'presentation', 'seminar slides', 'スライド', 'プレゼン', 'セミナー資料'],
+    weak: ['speaker notes', 'appendix', 'mục lục slide', 'muc luc slide', '発表ノート', '付録', '目次'],
+    negative: ['source code', 'api', 'database'],
+  }),
+  route('hapo:agent-browser', 'browser automation with snapshot refs, web interaction, recording, or Browserbase cloud browser workflows', 45, {
+    strong: ['agent-browser', 'browser automation', 'web automation', 'browserbase', 'cloud browser', 'snapshot refs', 'browser snapshot', 'automate browser', 'tự động trình duyệt', 'tu dong trinh duyet', 'tự động thao tác trình duyệt', 'tu dong thao tac trinh duyet', 'ブラウザ自動化', 'クラウドブラウザ', 'ブラウザ操作', 'ブラウザスナップショット'],
+    medium: ['open url', 'navigate site', 'click in browser', 'fill form in browser', 'record browser', 'browser session', 'multi tab', 'browser test session', 'mở website', 'mo website', 'truy cập website', 'truy cap website', 'click trên web', 'click tren web', 'điền form web', 'dien form web', 'サイトを開く', 'ブラウザで開く', 'ブラウザで', 'フォーム入力', 'フォーム入力を自動化', '自動化して', 'クリック操作', '録画'],
+    weak: ['click button', 'fill form', 'open site', 'web session', 'browser ref', 'viewport', 'cookies', 'localstorage', 'ボタンをクリック', 'ビューポート', 'クッキー'],
+    negative: ['attached screenshot', 'ảnh đính kèm', 'anh dinh kem', '画像添付', 'source code', 'codebase', 'commit', 'push', 'pptx', 'pdf'],
+  }),
+  route('hapo:pdf', 'PDF reading, extraction, or generation', 44, {
+    strong: ['pdf'], medium: ['export pdf', 'read pdf', 'extract pdf', 'pdf出力', 'pdfを読む', 'pdf抽出'], weak: ['page render', 'ページレンダー'], negative: [],
+  }),
+  route('hapo:docx', 'Word document work', 42, {
+    strong: ['docx', 'word document', 'word file', 'word文書', 'wordファイル'], medium: ['word'], weak: ['tracked changes', 'document file', '変更履歴', '文書ファイル'], negative: [],
+  }),
+  route('hapo:xlsx', 'spreadsheet or Excel work', 42, {
+    strong: ['xlsx', 'excel', 'spreadsheet', 'スプレッドシート'], medium: ['csv', 'sheet', 'workbook', 'シート', 'ワークブック'], weak: ['formula', 'pivot table', '数式', 'ピボットテーブル'], negative: [],
+  }),
+  route('hapo:ai-multimodal', 'image, video, audio, or multimodal artifact analysis', 40, {
+    strong: ['screenshot', 'video', 'audio', 'multimodal', 'ảnh', 'anh', 'hình', 'hinh', 'スクリーンショット', '動画', '音声', '画像', '写真'],
+    medium: ['image', 'screen capture', 'recording', 'file attached', 'イメージ', '画面キャプチャ', '録画', '添付ファイル'],
+    weak: ['visual', 'describe image', 'ocr', 'ビジュアル', '画像説明'],
+    negative: ['pptx', 'pdf export'],
+  }),
+];
+
+function route(skill, reason, priority, signals) {
+  return { skill, reason, priority, signals };
+}
+
+function normalize(value) {
+  return String(value || '')
+    .normalize('NFKC')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .normalize('NFC')
+    .toLowerCase();
+}
+
+function scoreRoute(prompt, routeItem) {
+  const normalized = normalize(prompt);
+  const matched = [];
+  let score = 0;
+  for (const [bucket, weight] of Object.entries(WEIGHTS)) {
+    for (const term of routeItem.signals[bucket] || []) {
+      if (!normalized.includes(normalize(term))) continue;
+      score += weight;
+      matched.push({ bucket, term, weight });
+    }
+  }
+  return { ...routeItem, score, matched, confidence: confidence(score) };
+}
+
+function confidence(score) {
+  if (score >= 12) return 'high';
+  if (score >= 7) return 'medium';
+  if (score >= MIN_SCORE) return 'low';
+  return 'none';
+}
+
+function findRoute(prompt) {
+  const candidates = ROUTES
+    .map((routeItem, index) => ({ ...scoreRoute(prompt, routeItem), index }))
+    .filter((routeItem) => routeItem.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score || b.priority - a.priority || a.index - b.index);
+  return candidates[0] || null;
+}
+
+module.exports = {
+  MIN_SCORE,
+  ROUTES,
+  findRoute,
+  normalize,
+  scoreRoute,
+};

package/src/claude/hooks/skill-router.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * UserPromptSubmit Hook - skill-router.cjs
+ *
+ * Adds a deterministic CafeKit skill suggestion for natural-language prompts.
+ * It never overrides explicit slash commands; it only injects a short routing hint.
+ *
+ * Exit: 0 always (fail-open)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function logCrash(error) {
+  try {
+    const dir = path.join(__dirname, '.logs');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: 'skill-router',
+        status: 'crash',
+        error: error.message,
+      }) + '\n'
+    );
+  } catch (_) {}
+}
+
+try {
+  const { isHookEnabled } = require('./lib/config.cjs');
+  const { findRoute } = require('./lib/skill-router-routes.cjs');
+
+  function isExplicitCommand(prompt) {
+    const trimmed = prompt.trim();
+    return trimmed.startsWith('/') || /^hapo:[a-z-]+/i.test(trimmed);
+  }
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const cwd = payload.cwd || process.cwd();
+  const prompt = payload.prompt || '';
+  if (!isHookEnabled('skill-router', { cwd })) process.exit(0);
+  if (!prompt || isExplicitCommand(prompt)) process.exit(0);
+
+  const route = findRoute(prompt);
+  if (!route) process.exit(0);
+
+  const skillDir = route.skill.replace(/^hapo:/, '');
+  const lines = [
+    '## CafeKit Skill Router',
+    `- Suggested skill: \`${route.skill}\``,
+    `- Why: ${route.reason}.`,
+    `- Confidence: ${route.confidence} (score ${route.score}).`,
+    `- Action: before acting, read \`.claude/skills/${skillDir}/SKILL.md\` and follow that workflow.`,
+    '- If the user explicitly names another workflow or asks for direct answering only, follow the user request.',
+  ];
+
+  console.log(lines.join('\n'));
+  process.exit(0);
+} catch (error) {
+  try { logCrash(error); } catch (_) {}
+  process.exit(0);
+}

package/src/claude/hooks/usage.cjs

@@ -21,14 +21,15 @@ try {
   const os = require("os");
   const { execSync } = require("child_process");
 
-  // Check if usage tracking is disabled in runtime.json
-  try {
-    const runtimePath = path.join(process.cwd(), '.claude', 'runtime.json');
-    if (fs.existsSync(runtimePath)) {
-      const runtime = JSON.parse(fs.readFileSync(runtimePath, 'utf-8'));
-      if (runtime.usage?.enabled === false) process.exit(0);
-    }
-  } catch { /* fail-open */ }
+  function readRuntime(cwd) {
+    try {
+      const runtimePath = path.join(cwd, '.claude', 'runtime.json');
+      if (fs.existsSync(runtimePath)) {
+        return JSON.parse(fs.readFileSync(runtimePath, 'utf-8'));
+      }
+    } catch { /* fail-open */ }
+    return {};
+  }
 
 // Cache configuration
 const USAGE_CACHE_FILE = path.join(os.tmpdir(), "ck-usage-limits-cache.json");
@@ -151,6 +152,12 @@ async function main() {
 		} catch {}
 
 		const input = JSON.parse(inputStr || "{}");
+		const cwd = input.cwd || process.cwd();
+		const runtime = readRuntime(cwd);
+		if (runtime.usage?.enabled === false) {
+			console.log(JSON.stringify(result));
+			return;
+		}
 
 		// Detect hook type
 		const isUserPrompt = typeof input.prompt === "string";

package/src/claude/migration-manifest.json

@@ -78,6 +78,7 @@
       "hooks/privacy-block.cjs",
       "hooks/inspect-block.cjs",
       "hooks/rules.cjs",
+      "hooks/skill-router.cjs",
       "hooks/spec-state.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
@@ -86,7 +87,8 @@
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs"
+      "hooks/lib/detect.cjs",
+      "hooks/lib/skill-router-routes.cjs"
     ]
   },
   "settings": {

package/src/claude/settings/settings.json

@@ -42,6 +42,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules.cjs\""
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""

package/src/claude/skills/ai-multimodal/SKILL.md

@@ -35,7 +35,7 @@ export GEMINI_API_KEY_2="key2"  # auto-rotates on rate limit
 
 **Verify setup**: `python scripts/check_setup.py`
 **Analyze media**: `python scripts/gemini_batch_process.py --files <file> --task <analyze|transcribe|extract>`
-  - TIP: When you're asked to analyze an image, check if `gemini` command is available, then use `echo "<prompt to analyze image>" | gemini -y -m <gemini.model>` command (read model from `$HOME/packages/spec/src/claude/.ck.json`: `gemini.model`). If `gemini` command is not available, use `python scripts/gemini_batch_process.py --files <file> --task analyze` command.
+  - TIP: When you're asked to analyze an image, check if `gemini` command is available, then use `echo "<prompt to analyze image>" | gemini -y -m <gemini.model>` command (read model from `.claude/runtime.json`: `gemini.model`). If `gemini` command is not available, use `python scripts/gemini_batch_process.py --files <file> --task analyze` command.
 
 > **Stdin support**: Pipe files via stdin for Gemini analysis (auto-detects PNG/JPG/PDF/WAV/MP3).