@haposoft/cafekit 0.11.2 → 0.11.4

package/bin/install.js

@@ -122,7 +122,7 @@ async function main() {
 
   try {
     ctx = buildContext(process.argv, `${Date.now()}`);
-    ctx.ui.intro(`${ctx.ui.pc.bgCyan(ctx.ui.pc.black(' CafeKit '))}Installer v${packageJson.version} · Multi-platform SDD`);
+    ctx.ui.intro(`${ctx.ui.pc.bgCyan(ctx.ui.pc.black(' CafeKit '))}${ctx.ui.pc.gray(' Installer')} v${packageJson.version}\n  ${ctx.ui.pc.dim('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}\n  ${ctx.ui.pc.blue('📦 ' + (ctx.t ? ctx.t('introDesc') : 'AI-native development workflow'))}`);
     if (got.reclaimed) ctx.ui.info(ctx.t('reclaimed'));
 
     await selectLanguage(ctx);

package/bin/lib/i18n.js

@@ -37,6 +37,9 @@ const MESSAGES = {
     modeDryRun:   'Mode: dry-run  •  no changes will be written',
     modeInstall:  'Mode: install / update  •  your customisations are preserved',
 
+    // Intro
+    introDesc:    'AI-native development workflow for Claude Code',
+
     // Platform install spinner
     installingPlatform:    'Installing {name}',
     platformInstalled:     '{name} — {files} file(s), {skills} skill(s)',
@@ -94,8 +97,15 @@ const MESSAGES = {
     outroDone:       'Done!  docs: https://github.com/haposoft/cafekit',
 
     // Version check
-    versionUpToDate:  'Already up to date ({v}). Use --force-overwrite to reinstall.',
-    versionDowngrade: 'Downgrading {from} → {to}. Features may be removed. Continue?'
+    versionUpToDate:      'Already up to date ({v}). Use --force-overwrite to reinstall.',
+    versionDowngrade:     'Downgrading {from} → {to}. Features may be removed. Continue?',
+    versionSamePrompt:    'CafeKit {v} is already installed. What would you like to do?',
+    versionForceReinstall: 'Reinstalling CafeKit {v} (--force-overwrite)...',
+    versionUpgradePrompt: 'CafeKit {from} → {to}: Update available!',
+    updateOption:         'Update to {v}',
+    reinstallOption:      'Reinstall (overwrite managed files)',
+    reinstallCurrentOption: 'Reinstall {v}',
+    skipOption:           'Skip (exit)'
   },
 
   // ─── 日本語 ─────────────────────────────────────────────────────────────────
@@ -118,6 +128,9 @@ const MESSAGES = {
     modeDryRun:   'モード: ドライラン  •  ファイルへの変更はありません',
     modeInstall:  'モード: インストール / 更新  •  カスタマイズは保持されます',
 
+    // Intro
+    introDesc:    'Claude Code 向け AI ネイティブ開発ワークフロー',
+
     installingPlatform:    '{name} をインストール中',
     platformInstalled:     '{name} — {files} ファイル、{skills} スキル',
     platformDryInstalled:  '{name} — {files} ファイル、{skills} スキル  [ドライラン]',
@@ -169,8 +182,15 @@ const MESSAGES = {
     dryRunOnly:      'ドライラン完了 — ファイルへの変更はありませんでした。\n  変更を適用するには --dry-run なしで再実行してください。',
     outroDone:       '完了！  ドキュメント: https://github.com/haposoft/cafekit',
 
-    versionUpToDate:  '最新バージョンです（{v}）。再インストールするには --force-overwrite を使用してください。',
-    versionDowngrade: '{from} → {to} へのダウングレードです。機能が削除される可能性があります。続けますか？'
+    versionUpToDate:      '最新バージョンです（{v}）。再インストールするには --force-overwrite を使用してください。',
+    versionDowngrade:     '{from} → {to} へのダウングレードです。機能が削除される可能性があります。続けますか？',
+    versionSamePrompt:    'CafeKit {v} は既にインストールされています。何をしますか？',
+    versionForceReinstall: 'CafeKit {v} を再インストール中 (--force-overwrite)...',
+    versionUpgradePrompt: 'CafeKit {from} → {to}: アップデートが利用可能です！',
+    updateOption:         '{v} にアップデート',
+    reinstallOption:      '再インストール（管理対象ファイルを上書き）',
+    reinstallCurrentOption: '{v} を再インストール',
+    skipOption:           'スキップ（終了）'
   },
 
   // ─── Tiếng Việt ─────────────────────────────────────────────────────────────
@@ -193,6 +213,9 @@ const MESSAGES = {
     modeDryRun:   'Chế độ: dry-run  •  sẽ không thay đổi bất kỳ tệp nào',
     modeInstall:  'Chế độ: cài / cập nhật  •  nội dung bạn tuỳ chỉnh được giữ nguyên',
 
+    // Intro
+    introDesc:    'Quy trình phát triển AI-native cho Claude Code',
+
     installingPlatform:    'Đang cài {name}',
     platformInstalled:     '{name} — {files} tệp, {skills} skill',
     platformDryInstalled:  '{name} — {files} tệp, {skills} skill  [dry-run]',
@@ -244,8 +267,15 @@ const MESSAGES = {
     dryRunOnly:      'Dry-run hoàn tất — không có tệp nào thay đổi.\n  Chạy lại không có --dry-run để áp dụng.',
     outroDone:       'Xong!  Tài liệu: https://github.com/haposoft/cafekit',
 
-    versionUpToDate:  'Đã là phiên bản mới nhất ({v}). Dùng --force-overwrite để cài lại.',
-    versionDowngrade: 'Đang hạ cấp {from} → {to}. Một số tính năng có thể bị xoá. Tiếp tục?'
+    versionUpToDate:      'Đã là phiên bản mới nhất ({v}). Dùng --force-overwrite để cài lại.',
+    versionDowngrade:     'Đang hạ cấp {from} → {to}. Một số tính năng có thể bị xoá. Tiếp tục?',
+    versionSamePrompt:    'CafeKit {v} đã được cài đặt. Bạn muốn làm gì?',
+    versionForceReinstall: 'Đang cài lại CafeKit {v} (--force-overwrite)...',
+    versionUpgradePrompt: 'CafeKit {from} → {to}: Có bản cập nhật mới!',
+    updateOption:         'Cập nhật lên {v}',
+    reinstallOption:      'Cài lại (ghi đè file được quản lý)',
+    reinstallCurrentOption: 'Cài lại {v}',
+    skipOption:           'Bỏ qua (thoát)'
   }
 };
 

package/bin/lib/version-check.js

@@ -43,46 +43,129 @@ function getInstalledVersion(platformKey) {
 /**
  * Check versions for all selected platforms and decide whether to proceed.
  * Sets ctx.cancelled on same-version (without --force) or unconfirmed downgrade.
+ * Shows interactive prompt when version differs, asking user what to do.
  */
 async function checkVersions(ctx) {
   if (ctx.dryRun) return ctx;
 
   const incoming = packageJson.version;
+  const platformsWithInstall = [];
 
   for (const key of ctx.platforms) {
     const installed = getInstalledVersion(key);
-    if (!installed) continue; // fresh install — no check needed
+    if (installed) {
+      platformsWithInstall.push({ key, installed });
+    }
+  }
+
+  // All fresh installs - skip version check, proceed normally
+  if (platformsWithInstall.length === 0) {
+    return ctx;
+  }
+
+  // Get unique versions across all platforms
+  const uniqueVersions = [...new Set(platformsWithInstall.map(p => p.installed))];
+  const installedVersion = uniqueVersions.length === 1 ? uniqueVersions[0] : `${uniqueVersions.join(', ')}`;
+
+  // Determine overall comparison (assuming same version across platforms)
+  const firstPlatform = platformsWithInstall[0];
+  const cmp = cmpVersion(firstPlatform.installed, incoming);
+
+  // ── Same version ───────────────────────────────────────────────────────────
+  if (cmp === 0) {
+    if (ctx.options.forceOverwrite) {
+      ctx.ui.info(ctx.t ? ctx.t('versionForceReinstall', { v: installedVersion }) : `Reinstalling CafeKit ${installedVersion} (--force-overwrite)...`);
+      return ctx;
+    }
+
+    if (!ctx.interactive) {
+      ctx.ui.info(ctx.t ? ctx.t('versionUpToDate', { v: installedVersion }) : `CafeKit ${installedVersion} is already up to date. Use --force-overwrite to reinstall.`);
+      ctx.cancelled = true;
+      return ctx;
+    }
+
+    // Show current vs new and ask what to do
+    const { isCancel } = await import('@clack/prompts');
+    const { default: select } = await import('@clack/prompts');
+
+    const options = [
+      { value: 'reinstall', label: ctx.t ? ctx.t('reinstallOption') : 'Reinstall (overwrite managed files)' },
+      { value: 'skip', label: ctx.t ? ctx.t('skipOption') : 'Skip (exit)' }
+    ];
 
-    const cmp = cmpVersion(installed, incoming);
+    const answer = await select({
+      message: ctx.t
+        ? ctx.t('versionSamePrompt', { v: installedVersion })
+        : `CafeKit ${installedVersion} is already installed. What do you want to do?`,
+      options
+    });
 
-    // ── Same version ─────────────────────────────────────────────────────────
-    if (cmp === 0) {
-      if (ctx.options.forceOverwrite) continue; // --force-overwrite overrides
-      ctx.ui.info(ctx.t ? ctx.t('versionUpToDate', { v: installed }) : `Already up to date (${installed}). Use --force-overwrite to reinstall.`);
+    if (isCancel(answer) || answer === 'skip') {
       ctx.cancelled = true;
       return ctx;
     }
 
-    // ── Downgrade ─────────────────────────────────────────────────────────────
-    if (cmp > 0) {
-      const msg = ctx.t
-        ? ctx.t('versionDowngrade', { from: installed, to: incoming })
-        : `Downgrading ${installed} → ${incoming}. This may remove features. Continue?`;
-
-      if (!ctx.interactive) {
-        ctx.ui.warn ? ctx.ui.warn(`Downgrade detected (${installed} → ${incoming}). Aborted in non-interactive mode. Use --force-overwrite to proceed.`) : console.warn(msg);
-        ctx.cancelled = true;
-        return ctx;
-      }
-
-      const yes = await ctx.ui.confirm({ message: msg, initialValue: false }, false);
-      if (!yes || ctx.ui.isCancel(yes)) {
-        ctx.cancelled = true;
-        return ctx;
-      }
+    if (answer === 'reinstall') {
+      ctx.options.forceOverwrite = true;
+    }
+
+    return ctx;
+  }
+
+  // ── Upgrade available ───────────────────────────────────────────────────────
+  if (cmp < 0) {
+    if (!ctx.interactive) {
+      // Non-interactive: proceed with upgrade automatically
+      return ctx;
     }
 
-    // cmp < 0 → upgrade, proceed normally
+    // Show current vs new and ask what to do
+    const { isCancel } = await import('@clack/prompts');
+    const { default: select } = await import('@clack/prompts');
+
+    const options = [
+      { value: 'update', label: ctx.t ? ctx.t('updateOption') : `Update to ${incoming}` },
+      { value: 'reinstall', label: ctx.t ? ctx.t('reinstallCurrentOption', { v: firstPlatform.installed }) : `Reinstall ${firstPlatform.installed}` },
+      { value: 'skip', label: ctx.t ? ctx.t('skipOption') : 'Skip (exit)' }
+    ];
+
+    const answer = await select({
+      message: ctx.t
+        ? ctx.t('versionUpgradePrompt', { from: firstPlatform.installed, to: incoming })
+        : `CafeKit ${firstPlatform.installed} → ${incoming}: Update available!`,
+      options
+    });
+
+    if (isCancel(answer) || answer === 'skip') {
+      ctx.cancelled = true;
+      return ctx;
+    }
+
+    if (answer === 'reinstall') {
+      ctx.options.forceOverwrite = true;
+    }
+
+    // 'update' proceeds normally (no special flag needed)
+    return ctx;
+  }
+
+  // ── Downgrade ──────────────────────────────────────────────────────────────
+  if (cmp > 0) {
+    const msg = ctx.t
+      ? ctx.t('versionDowngrade', { from: firstPlatform.installed, to: incoming })
+      : `Downgrading ${firstPlatform.installed} → ${incoming}. This may remove features.`;
+
+    if (!ctx.interactive) {
+      ctx.ui.warn ? ctx.ui.warn(msg + ' Downgrade aborted in non-interactive mode. Use --force-overwrite to proceed.') : console.warn(msg);
+      ctx.cancelled = true;
+      return ctx;
+    }
+
+    const yes = await ctx.ui.confirm({ message: msg + ' Continue?', initialValue: false });
+    if (!yes || ctx.ui.isCancel(yes)) {
+      ctx.cancelled = true;
+      return ctx;
+    }
   }
 
   return ctx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "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/CLAUDE.md

@@ -15,7 +15,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - Do not assume silently. State assumptions when they affect the work.
 - If multiple interpretations are plausible, surface them before implementation.
 - If the simpler option is likely better, say so and push back.
-- If the user asks a question about the project, use `/hapo:question` to answer from source evidence before planning.
+- If the user asks a question about the project, use `/question` to answer from source evidence before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -46,7 +46,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 Use this loop for non-trivial work:
 
 1. **Understand** — read README, relevant docs, active spec/task, and existing code.
-2. **Plan** — choose the smallest coherent path; use `/hapo:question` for evidence-backed project questions and `/hapo:specs` for feature specs when ready.
+2. **Plan** — choose the smallest coherent path; use `/question` for evidence-backed project questions and `/specs` for feature specs when ready.
 3. **Execute** — implement only the active task/scope; no placeholder completion.
 4. **Verify** — run exact task commands first, then repo-level lint/test/build as needed.
 5. **Sync** — mark task state only after proof exists.
@@ -98,11 +98,9 @@ Consult these when the task touches the relevant area:
 
 ## Skill And Script Use
 
-- Evaluate the available skills catalog before work and activate the relevant skill(s).
-- Use `./.claude/rules/skill-workflow-routing.md` and `./.claude/rules/skill-domain-routing.md` to choose skills. CafeKit does not auto-route prompts through a scoring hook.
-- When needed, run `node .claude/scripts/generate-skill-catalog.cjs --skills` to inspect the installed skill catalog.
-- If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
-- If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
+- **IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+- **IMPORTANT:** DO NOT modify skills in `~/.claude/skills` directly. **MUST** modify skills in this current working directory, unless asked to do so.
+- Use `./.claude/rules/skill-workflow-routing.md` and `./.claude/rules/skill-domain-routing.md` as advisory routing when choosing a skill.
 - Run Python skill scripts with the skill venv:
   - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
   - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`

package/src/claude/agents/brainstormer.md

@@ -33,7 +33,7 @@ description: >-
 
 # Brainstormer — Solution Architect
 
-You are a **Pragmatic Solution Architect** called by `hapo:brainstorm` when a design choice needs deeper architectural pressure-testing. You do not replace the `hapo:brainstorm` workflow. You supply sharp analysis, alternatives, risks, and recommendation material that the controller can fold back into the main brainstorm.
+You are a **Pragmatic Solution Architect** called by `brainstorm` when a design choice needs deeper architectural pressure-testing. You do not replace the `brainstorm` workflow. You supply sharp analysis, alternatives, risks, and recommendation material that the controller can fold back into the main brainstorm.
 
 Your goal is to help turn a raw idea into a viable, spec-ready design without touching code.
 
@@ -46,7 +46,7 @@ Before concluding any brainstorm session, verify each measurement metric:
 - [ ] **Domino Effect Analysis**: Are downstream impacts (e.g., database bloat, CI/CD delays) explicitly warned about?
 - [ ] **Occam's Razor Selection**: Have I forcefully recommended the simplest, lowest-friction solution?
 - [ ] **Documentation Locked**: Is the agreed architecture written down in a formalized summary block?
-- [ ] **Workflow Fit**: Did my output preserve the `hapo:brainstorm -> hapo:specs` handoff instead of drifting into implementation?
+- [ ] **Workflow Fit**: Did my output preserve the `brainstorm -> hapo:specs` handoff instead of drifting into implementation?
 
 ## Core Principles
 1. **Engineering Trinity:** YAGNI, KISS, and DRY.
@@ -60,7 +60,7 @@ Do not operate in a vacuum. You are equipped to utilize `SendMessage` to summon
 - **Need Best Practices/Examples?** Summon the `researcher` agent to scrape the web and extract contemporary tech patterns.
 - **Need Global Codebase Context?** Inquire with the `docs-keeper` agent to retrieve the latest `./docs/codebase-summary.md` before you design inter-connected systems.
 - **Need to synthesize massive outputs or split heavy tasks?** Defer the aggregation step to the `project-manager` agent.
-- **Final Design Handoff:** Return a concise summary to the `hapo:brainstorm` controller. The controller handles `/hapo:specs`.
+- **Final Design Handoff:** Return a concise summary to the `brainstorm` controller. The controller handles `/specs`.
 
 ## Collaborative Process
 
@@ -72,7 +72,7 @@ Do not operate in a vacuum. You are equipped to utilize `SendMessage` to summon
 6. **Return Summary**: End with a compact design advisory block the controller can paste into the brainstorm report.
 
 <HARD-GATE>
-Do NOT invoke any implementation skill, write code, scaffold a project, modify files, or call `/hapo:develop`. You brainstorm and advise only.
+Do NOT invoke any implementation skill, write code, scaffold a project, modify files, or call `/develop`. You brainstorm and advise only.
 </HARD-GATE>
 
 ## Output Shape
@@ -83,4 +83,4 @@ Return:
 - **Options compared**
 - **Recommended option**
 - **Risks and mitigations**
-- **Suggested handoff notes for `/hapo:specs`**
+- **Suggested handoff notes for `/specs`**

package/src/claude/agents/code-auditor.md

@@ -128,7 +128,7 @@ Classify each issue:
 
 ## Pass/Fail Thresholds (Used in Quality Gate)
 
-When called from `hapo:develop` Step 4 (Quality Gate Auto-Fix):
+When called from `develop` Step 4 (Quality Gate Auto-Fix):
 
 | Condition | Result |
 |-----------|--------|
@@ -153,4 +153,4 @@ When called from `hapo:develop` Step 4 (Quality Gate Auto-Fix):
 - Focus on issues with production impact — skip trivial style nitpicks.
 - Respect project conventions if `docs/code-standards.md` exists.
 - DO NOT modify any files. Read and report only.
-- Integrate with `hapo:code-review` skill for full protocol.
+- Integrate with `code-review` skill for full protocol.

package/src/claude/agents/debugger.md

@@ -44,11 +44,11 @@ When investigating issues, you will:
    - Retrieve CI/CD pipeline logs from GitHub Actions by using `gh` command
    - Examine application logs and error traces
    - Capture system metrics and performance data
-   - Use `hapo:inspect ext` or native CLI (e.g. `curl`) to fetch and read the latest docs of the packages/plugins
+   - Use `inspect ext` or native CLI (e.g. `curl`) to fetch and read the latest docs of the packages/plugins
    - **When you need to understand the project structure:** 
      - Read `docs/codebase-summary.md` if it exists & up-to-date (less than 2 days old)
      - Otherwise, only use the `repomix` command to generate comprehensive codebase summary of the current project at `./repomix-output.xml` and create/update a codebase summary file at `./codebase-summary.md`
-     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/hapo:inspect ext` for scoped Gemini discovery or `/hapo:inspect` for scoped internal discovery to inspect only the relevant codebase scopes and find the files needed to complete the task
+     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/inspect ext` for scoped Gemini discovery or `/inspect` for scoped internal discovery to inspect only the relevant codebase scopes and find the files needed to complete the task
    - When you are given a Github repository URL, use `repomix --remote <github-repo-url>` bash command to generate a fresh codebase summary:
       ```bash
       # usage: repomix --remote <github-repo-url>
@@ -90,8 +90,8 @@ You will utilize:
 - **Performance Tools**: Profilers, APM tools, system monitoring utilities
 - **Testing Frameworks**: Run unit tests, integration tests, and diagnostic scripts
 - **CI/CD Tools**: GitHub Actions log analysis, pipeline debugging, `gh` command
-- **Package/Plugin Docs**: Use `hapo:inspect ext` or bash tools to read the latest docs of the packages/plugins
-- **Browser Tools**: `hapo:agent-browser`, `hapo:chrome-devtools`, or project-native browser tests for UI evidence
+- **Package/Plugin Docs**: Use `inspect ext` or bash tools to read the latest docs of the packages/plugins
+- **Browser Tools**: `agent-browser`, `chrome-devtools`, or project-native browser tests for UI evidence
 - **Codebase Analysis**: 
   - If `./docs/codebase-summary.md` exists & up-to-date (less than 2 days old), read it to understand the codebase.
   - If `./docs/codebase-summary.md` doesn't exist or outdated >2 days, use `repomix` command to generate/update a comprehensive codebase summary when you need to understand the project structure

package/src/claude/agents/deployer.md

@@ -13,7 +13,7 @@ You are a deployment engineer who treats every release as a controlled explosion
 
 Before ANY deployment, verify:
 
-- [ ] Engage the `hapo:devops` skill to audit infrastructure configurations, CI/CD pipelines, and runtime constraints.
+- [ ] Engage the `devops` skill to audit infrastructure configurations, CI/CD pipelines, and runtime constraints.
 - [ ] All tests pass (`test-runner` has given a PASS verdict).
 - [ ] Code review score ≥ 9.5 (`code-auditor` verdict: PASS).
 - [ ] No unresolved blockers in `spec.json`.
@@ -97,6 +97,6 @@ docker compose down && docker compose -f docker-compose.prev.yml up -d
 
 ## Integration
 
-- Triggered after `hapo:sync phase <feature> deploy` advances a feature.
+- Triggered after `sync phase <feature> deploy` advances a feature.
 - Reads deployment config from project root (`vercel.json`, `railway.json`, `docker-compose.yml`).
 - Reports deployment status back to orchestrator for `spec.json` state update.

package/src/claude/agents/docs-keeper.md

@@ -11,12 +11,12 @@ You are the authoritative **Documentation Guardian** for this repository.
 Stale docs and phantom specs are worse than no docs — they waste developer hours. 
 Your core operational rule: **Read the code FIRST, verify it WORKS, THEN write the words.**
 
-You juggle two parallel universes defined by the `hapo:specs` ecosystem: The agile feature specification lifecycle (`specs/`) and the global project documentation (`docs/`).
+You juggle two parallel universes defined by the `specs` ecosystem: The agile feature specification lifecycle (`specs/`) and the global project documentation (`docs/`).
 
 ## Core Responsibilities
 
 ### 1. Specs Lifecycle Guardian (`specs/`)
-You enforce integrity across the `hapo:specs` architecture:
+You enforce integrity across the `specs` architecture:
 - Monitor and maintain feature specs explicitly stored in `specs/<feature-name>/`.
 - Validate that `spec.json` states match the reality of `requirements.md` and `design.md`.
 - Track cross-spec dependencies. Connect the dots between overlapping tasks to prevent collisions across multiple active spec tickets.
@@ -47,7 +47,7 @@ Generate the project's technical DNA map:
 - This file acts as the single source of truth for all other agents to quickly grasp the project landscape.
 
 ### 4b. Task Closeout Mode
-When called from `hapo:develop` after a verified task is complete:
+When called from `develop` after a verified task is complete:
 - Treat the job as a **lightweight task-closeout sync**
 - Update only the existing docs affected by that task
 - Start by classifying `Docs impact: none | minor | major`
@@ -68,7 +68,7 @@ If any doc file exceeds **800 LOC**, enforce modularity:
 - Always use relative paths for internal linking: `[text](./path.md)`.
 
 ## Integration Points & Hooks
-- Integrate seamlessly when called by `hapo:specs` or other team components to validate specifications.
+- Integrate seamlessly when called by `specs` or other team components to validate specifications.
 - **No Hallucinated Tools**: Only execute valid Node/Bash scripts that you have verified exist in the project tree.
 
 ## Report Format

package/src/claude/agents/git-ops.md

@@ -5,7 +5,7 @@ model: haiku
 tools: Glob, Grep, Read, Bash, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
 ---
 
-You are the Git Operations Specialist (Chief of the Git Station). You must execute operations with EXTREME SPEED, typically finishing within 2-4 tool calls. Do not perform lengthy explorations. Simply activate the `hapo:git` skill and finalize the operation.
+You are the Git Operations Specialist (Chief of the Git Station). You must execute operations with EXTREME SPEED, typically finishing within 2-4 tool calls. Do not perform lengthy explorations. Simply activate the `git` skill and finalize the operation.
 
 **CRITICAL REQUIREMENT**: Strictly optimize for token efficiency and operational speed, yet maintain high-quality conventional git histories.
 
@@ -14,7 +14,7 @@ You are the Git Operations Specialist (Chief of the Git Station). You must execu
 When instantiated as a team member, you must:
 1. Upon start: call `TaskList` and claim an available task using `TaskUpdate`.
 2. Read the task description via `TaskGet` before executing commands.
-3. Utilize Native Bash Commands (as guided by `hapo:git`) to commit, push, or create independent Worktrees — NEVER trigger garbage commits and NEVER arbitrarily use `force push` unless explicitly and securely designated.
+3. Utilize Native Bash Commands (as guided by `git`) to commit, push, or create independent Worktrees — NEVER trigger garbage commits and NEVER arbitrarily use `force push` unless explicitly and securely designated.
 4. Completion protocol: Execute `TaskUpdate(status: "completed")` and send a summary message via `SendMessage` detailing the Git/Worktree outcome to the Team Leader.
 5. In case of a `shutdown_request`: accept it using `SendMessage(type: "shutdown_response")` unless mid-critical-operation or mid-task.
 6. To chat with parallel peers, invoke `SendMessage(type: "message")` to stream inter-agent communications.

package/src/claude/agents/god-developer.md

@@ -36,8 +36,8 @@ Any logic gaps must be clarified BEFORE typing, not discovered after bugs ship.
 
 When activated, you will receive one of two input types:
 - **Task file list** (`tasks/task-R0-01-*.md`, `task-R1-01-*.md`...) with `spec.json`.
-- **Direct description** from the main agent or `hapo:develop` skill. 
-  *(Always apply domain-specific best practices from `hapo:frontend-development`, `hapo:backend-development`, `hapo:mobile-development`, or `hapo:react-best-practices` when that guidance is provided or readable in the installed skills).*
+- **Direct description** from the main agent or `develop` skill. 
+  *(Always apply domain-specific best practices from `frontend-development`, `backend-development`, `mobile-development`, or `react-best-practices` when that guidance is provided or readable in the installed skills).*
 
 First action: Read ALL task files/spec thoroughly. Mentally map out:
 - Which files need to be created?

package/src/claude/agents/inspector.md

@@ -33,7 +33,7 @@ Before packaging your report, verify:
 ## Responsibilities
 - Provide a file list with brief context descriptions — fast and concise.
 - Target the right directories, skip noise.
-- For `hapo:develop`, scout PER ACTIVE TASK. Use the task packet, `scope_lock`, requirement IDs, and design contracts to identify only the code paths relevant to that task.
+- For `develop`, scout PER ACTIVE TASK. Use the task packet, `scope_lock`, requirement IDs, and design contracts to identify only the code paths relevant to that task.
 - Find integration seams: app/page entrypoints, router registration, CLI command dispatch, worker registration, extension manifests, API consumers, provider mounting, service invocation, state/reducer/action wiring.
 - Flag reachability risks clearly: orphan component/export, unmounted UI, unregistered route, uncalled service/loader, disconnected provider/state, unused reducer/action, generated artifact never referenced.
 - Identify blast-radius touchpoints: current importers/callers of modified exports, public contracts that depend on them, tests likely affected.

package/src/claude/agents/project-manager.md

@@ -31,7 +31,7 @@ Before you declare any phase complete or issue a final status report, you must i
 
 ## Collaborative Interlocking (Swarm Protocol)
 
-- You govern the final phase of `/hapo:specs`. If a spec is prematurely abandoned by `brainstormer`, you drag it back to alignment.
+- You govern the final phase of `/specs`. If a spec is prematurely abandoned by `brainstormer`, you drag it back to alignment.
 - When triggered as an active teammate within multi-agent swarms:
   1. **Init:** Execute `TaskList` immediately, then claim idle aggregation blocks via `TaskUpdate`.
   2. **Context Intake:** Pull strict operational boundaries using `TaskGet`.

package/src/claude/agents/spec-maker.md

@@ -17,7 +17,7 @@ You DO NOT write implementation code. You produce Specifications that downstream
 
 ## Artifact Contract (MANDATORY)
 
-Generate only the CafeKit spec artifacts defined by `hapo:specs`:
+Generate only the CafeKit spec artifacts defined by `specs`:
 
 ```
 specs/<feature>/
@@ -59,8 +59,8 @@ Init → Requirements → Design → Tasks
 ### Auto-Approval Behavior
 - When running the full pipeline end-to-end, follow the auto-approval rules defined in `SKILL.md`.
 - When running a single phase, stop and report status after completion.
-- Normal `/hapo:specs <feature-description>` requests are full pipeline requests.
-- If a pause is required after user review, tell the user to continue with `/hapo:specs resume <feature>` or `/hapo:specs <feature>`.
+- Normal `/specs <feature-description>` requests are full pipeline requests.
+- If a pause is required after user review, tell the user to continue with `/specs resume <feature>` or `/specs <feature>`.
 
 ## Scope Lock Protocol (MANDATORY)
 
@@ -147,11 +147,11 @@ Each task file MUST be compact but implementation-ready:
 
 ## Research Phase
 
-### Follow the `hapo:specs` Evidence Gate
+### Follow the `specs` Evidence Gate
 
 Use `.claude/skills/specs/SKILL.md` as the source of truth for evidence depth. Do not force external research for trivial/internal specs.
 
-When running as the main controller, delegate to the `researcher` agent BEFORE writing detailed requirements only when `hapo:specs` requires external/current research: third-party APIs, libraries, platform policies, AI providers/models/tooling, security/auth/payment/privacy/delete-data rules, performance/accessibility/SEO/security standards, or explicit "best/latest/recommended/optimal" user intent.
+When running as the main controller, delegate to the `researcher` agent BEFORE writing detailed requirements only when `specs` requires external/current research: third-party APIs, libraries, platform policies, AI providers/models/tooling, security/auth/payment/privacy/delete-data rules, performance/accessibility/SEO/security standards, or explicit "best/latest/recommended/optimal" user intent.
 
 When running as this `spec-maker` subagent, do not spawn another subagent. Use bounded `WebSearch`/`WebFetch` directly when available, or return `NEEDS_RESEARCH` with the exact research question for the controller to delegate.
 
@@ -190,7 +190,7 @@ Before marking the spec ready:
 - **Complex** (multi-module, security, migration) → Full spec with mandatory research phase
 
 ### 2. Evidence Phase
-Capture codebase scout findings and external research when required by `hapo:specs`. Record skip rationale in `specs/<feature>/research.md` for trivial/internal cases.
+Capture codebase scout findings and external research when required by `specs`. Record skip rationale in `specs/<feature>/research.md` for trivial/internal cases.
 
 ### 3. Specification Generation (follows SKILL.md Steps 4-7)
 Produce the following artifacts under `specs/<feature>/`:
@@ -211,12 +211,12 @@ specs/<feature>/
 - Update `spec.json` with `"status": "in_progress"` and `"current_phase": "develop"`
 - Ensure `task_files` + `task_registry` are synchronized and `ready_for_implementation` reflects the finalization audit outcome
 - Report the spec directory path to the orchestrator
-- The only valid implementation handoff is `/hapo:develop <feature>` (or `/hapo:develop <feature> <task-file>` for a single task). Never suggest `/work`, `/code`, or an unnamed "orchestrator dispatch" command.
+- The only valid implementation handoff is `/develop <feature>` (or `/develop <feature> <task-file>` for a single task). Never suggest `/work`, `/code`, or an unnamed "orchestrator dispatch" command.
 - DO NOT begin implementation yourself
 
 ## Integration Points
 
-- Output format follows `hapo:specs` protocol (see `skills/specs/SKILL.md`)
+- Output format follows `specs` protocol (see `skills/specs/SKILL.md`)
 - Task files follow `skills/specs/templates/task.md` template
 - `spec.json` follows the `skills/specs/templates/spec-state.json` schema; the generated file must still be named `spec.json`
 - Research output follows `skills/specs/templates/research.md` template

package/src/claude/agents/test-runner.md

@@ -64,7 +64,7 @@ Run the entire test suite without diff filtering. Use when: first run, major ref
 
 1. **Detect Project Type:** Scan for `package.json`, `pytest.ini`, `Cargo.toml`, `pubspec.yaml` to identify the test runner.
 2. **Pre-flight Check:** Run typecheck/lint/build health checks (`npx tsc --noEmit` or equivalent) to catch syntax and package-boundary failures before wasting time on tests.
-3. **Execute Tests:** Run the appropriate test command for the detected project. Deploy `hapo:web-testing` and `hapo:chrome-devtools` skills for rigorous UI/E2E browser test automation when testing frontends.
+3. **Execute Tests:** Run the appropriate test command for the detected project. Deploy `web-testing` and `chrome-devtools` skills for rigorous UI/E2E browser test automation when testing frontends.
 4. **No-op Detection:** Parse runner output for executed test count. If the command exits 0 but runs 0 tests, report `NO_TESTS` instead of `PASS`.
 5. **Build Verification:** Run the relevant build command when available (or the exact command requested by the task evidence section).
 6. **Task Evidence Audit:** Execute or inspect every verification item provided by the task. If a check cannot run, mark it `UNVERIFIED` with the exact blocker.

package/src/claude/agents/ui-ux-designer.md

@@ -39,7 +39,7 @@ You are an award-caliber UI/UX designer. You merge aesthetic excellence with eng
 - Select fonts strategically (prioritize Vietnamese character support).
 - Apply professional composition and color theory principles.
 - Implement design tokens for consistency.
-- Activate the `hapo:frontend-design` skill to ensure your stylistic choices seamlessly translate into semantic engineering architecture.
+- Activate the `frontend-design` skill to ensure your stylistic choices seamlessly translate into semantic engineering architecture.
 - Consider accessibility at every decision point.
 
 ### Phase 3: Build
@@ -80,7 +80,7 @@ You are an award-caliber UI/UX designer. You merge aesthetic excellence with eng
 
 ## Integration
 
-- Reads design specs from `hapo:specs` task files.
+- Reads design specs from `specs` task files.
 - Reports design deliverables to orchestrator.
 - Requests controller-level research delegation when competitive analysis exceeds local search scope.
 - Updates `docs/design-guidelines.md` as the living design system.

package/src/claude/references/debugger/frontend-verification.md

@@ -32,8 +32,8 @@ Use this when the issue affects rendering, layout, interaction, hydration, brows
 
 ## Preferred Tools
 
-- `hapo:agent-browser` for visual reproduction, screenshots, and exploratory browser checks
-- `hapo:chrome-devtools` for console, network, CDP, screenshots, ARIA snapshots, and WebSocket debugging
+- `agent-browser` for visual reproduction, screenshots, and exploratory browser checks
+- `chrome-devtools` for console, network, CDP, screenshots, ARIA snapshots, and WebSocket debugging
 - Project-native E2E tooling when it already exists
 
 ## Report Snippet

package/src/claude/rules/manage-docs.md

@@ -57,7 +57,7 @@ Use [Keep a Changelog](https://keepachangelog.com/) convention:
 ## Specification & Execution Tracker (Hapo Protocol)
 
 ### Where Specs Live
-Hapo does not use chaotic plan folders. Requirements and architecture are centralized into a machine-readable Specification structure via `hapo:specs`.
+Hapo does not use chaotic plan folders. Requirements and architecture are centralized into a machine-readable Specification structure via `specs`.
 
 All specifications exist strictly in `./specs/<feature-slug>/`.
 

package/src/claude/rules/state-sync.md

@@ -2,7 +2,7 @@
 
 ## Single Source of Truth
 
-In any Spec-driven workflow (`hapo:specs`), the state of the project is physically persisted in **two layers**:
+In any Spec-driven workflow (`specs`), the state of the project is physically persisted in **two layers**:
 1. **Machine Layer (`spec.json`)**: Tracks phase, status, overall completion, and per-task machine state via `task_registry`.
 2. **Human Layer (`tasks/task-*.md`)**: Checkboxes indicating granular execution progress.
 

package/src/claude/rules/workflow.md

@@ -8,11 +8,11 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 - Read the active spec/task file when one exists.
 - Read and activate any CafeKit skill that likely applies before taking action.
 - Inspect only the code needed to understand the affected area.
-- Use `hapo:inspect` or focused search when structure is unclear.
+- Use `inspect` or focused search when structure is unclear.
 
 ## 2. Plan
 
-- For non-trivial features, use `/hapo:specs` to create or validate the spec.
+- For non-trivial features, use `/specs` to create or validate the spec.
 - For approved specs, work one task file at a time.
 - Extract from the active task:
   - `Context`

package/src/claude/skills/agent-browser/SKILL.md

@@ -2,12 +2,15 @@
 name: hapo:agent-browser
 description: AI-optimized browser automation CLI with context-efficient snapshots. Use for long autonomous sessions, self-verifying workflows, video recording, and cloud browser testing (Browserbase).
 license: Apache-2.0
+user-invocable: true
+when_to_use: "Invoke to drive a real browser for navigation, screenshots, or DOM actions."
+category: dev-tools
+keywords: [browser, automation, screenshot, navigation]
 argument-hint: "[url or task]"
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-
 # agent-browser Skill
 
 Browser automation CLI designed for AI agents. Uses "snapshot + refs" paradigm for 93% less context than Playwright MCP.

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

@@ -2,14 +2,15 @@
 name: hapo:ai-multimodal
 description: Analyze images/audio/video/documentation with Gemini API. Use for vision analysis, transcription, OCR, design extraction, and deep multimodal understanding.
 license: MIT
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
+user-invocable: true
+when_to_use: "Invoke to analyze or generate images, audio, or mixed-media content."
+category: utilities
+keywords: [multimodal, image, audio, vision]
 argument-hint: "[file-path] [prompt]"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # AI Multimodal
 
 Process audio, images, videos, documents using Gemini. Purely focused on robust analysis, transcription, and contextual extraction.

package/src/claude/skills/backend-development/SKILL.md

@@ -2,10 +2,15 @@
 name: hapo:backend-development
 description: Build backends with Node.js, Python, Go (NestJS, FastAPI, Django). Use for REST/GraphQL/gRPC APIs, auth (OAuth, JWT), databases, microservices, security (OWASP), Docker/K8s.
 license: MIT
+user-invocable: true
+when_to_use: "Invoke to build or modify server APIs, services, and data layers."
+category: backend
+keywords: [backend, api, server, database]
 argument-hint: "[framework] [task]"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Backend Development Skill
 
 Production-ready backend development with modern technologies, best practices, and proven patterns.

package/src/claude/skills/brainstorm/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:brainstorm
 description: "Scout-first brainstorming for unclear ideas, architectural choices, scope gates, and translating raw intent into a spec-ready design."
+user-invocable: true
+when_to_use: "Invoke before choosing among unclear technical options or scope."
+category: utilities
+keywords: [ideation, tradeoffs, decisions, scope]
 argument-hint: "<idea_or_problem>"
-version: 2.1.0
+metadata:
+  author: haposoft
+  version: "2.1.0"
 ---
-
 # Brainstorming Skill
 
 You execute CafeKit's pre-spec design workflow. Your job is to turn a raw idea into a validated, spec-ready design without writing code or starting implementation.

package/src/claude/skills/chrome-devtools/SKILL.md

@@ -2,10 +2,15 @@
 name: hapo:chrome-devtools
 description: Automate browsers with Puppeteer CLI scripts and persistent sessions. Use for screenshots, performance analysis, network monitoring, web scraping, form automation, JavaScript debugging.
 license: Apache-2.0
+user-invocable: true
+when_to_use: "Invoke to inspect, debug, or profile a page via Chrome DevTools."
+category: dev-tools
+keywords: [devtools, chrome, debug, profiling]
 argument-hint: "[url or task]"
-version: "1.1.0"
+metadata:
+  author: haposoft
+  version: "1.1.0"
 ---
-
 # Chrome DevTools Agent Skill
 
 Browser automation via Puppeteer scripts with persistent sessions. All scripts output JSON.

package/src/claude/skills/code-review/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:code-review
 description: "Adversarial code review with technical rigor. Supports 3-Stage Protocol with ai-multimodal injection for multimodal spec compliance. Red-team analysis finds security holes, logic gaps, and architecture violations."
+user-invocable: true
+when_to_use: "Invoke to review a diff for correctness and quality before merge."
+category: dev-tools
+keywords: [review, diff, quality, correctness]
 argument-hint: "[#PR | COMMIT | --pending | scope]"
-version: 1.0.0
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Code Review
 
 Adversarial code review with technical rigor, evidence-based claims, and visual/document intelligence via the `hapo:ai-multimodal` Hub.

package/src/claude/skills/debug/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:debug
 description: "Use before fixing any bug, failing test, CI/CD failure, production incident, performance issue, UI regression, flaky test, or unexpected behavior. Diagnostic-only root-cause workflow with evidence, hypotheses, blast-radius mapping, and verification plan."
+user-invocable: true
+when_to_use: "Invoke for evidence-first root-cause diagnosis before any fix."
+category: dev-tools
+keywords: [debug, diagnosis, root-cause, evidence]
 argument-hint: "[issue] --quick|--ci|--frontend|--perf"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Debug - Evidence-First Root Cause Analysis
 
 Debugging is diagnosis, not repair. Find the source of the failure before changing product code.

package/src/claude/skills/develop/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: hapo:develop
 description: "Code execution engine: Reads specs and implements code end-to-end with automatic code review, self-healing, and visual implementation notes."
+user-invocable: true
+when_to_use: "Invoke to implement specs and tasks end-to-end after scope is clear."
+category: utilities
+keywords: [implementation, specs, build, orchestration]
 argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--no-notes]"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Develop — Feature Implementation (Task-Orchestrated Build)
 
 Reads the project specification (`hapo:specs`) and implements code through a disciplined task loop. In specific-task mode it behaves like a surgical executor. In full-spec mode it behaves like a sequential orchestrator, processing one unblocked task at a time and syncing state after every verified task.

package/src/claude/skills/devops/SKILL.md

@@ -2,10 +2,15 @@
 name: hapo:devops
 description: Deploy to Cloudflare (Workers, R2, D1), Docker, GCP (Cloud Run, GKE), Kubernetes (kubectl, Helm). Use for serverless, containers, CI/CD, GitOps, security audit.
 license: MIT
+user-invocable: true
+when_to_use: "Invoke to deploy, containerize, or set up CI/CD and infra."
+category: devops
+keywords: [deploy, docker, ci-cd, kubernetes]
 argument-hint: "[platform] [task]"
-version: "2.0.0"
+metadata:
+  author: haposoft
+  version: "2.0.0"
 ---
-
 # DevOps Skill
 
 Deploy and manage cloud infrastructure across Cloudflare, Docker, Google Cloud, and Kubernetes.

package/src/claude/skills/docs/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:docs
 description: "Create, update, summarize, or reconstruct project/system documentation from source code. Use reconstruct mode for as-is documentation of existing or legacy systems with evidence and uncertainty tracking."
-version: 1.0.0
+user-invocable: true
+when_to_use: "Invoke to create, update, or reconstruct project documentation from source."
+category: document-skills
+keywords: [docs, reconstruct, documentation, evidence]
 argument-hint: "[--init|--update|--summarize|--reconstruct] [scope]"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Docs
 
 Project documentation workflow for CafeKit.

package/src/claude/skills/docx/SKILL.md

@@ -2,11 +2,14 @@
 name: hapo:docx
 description: Create, edit, analyze .docx Word documents. Use for document creation, tracked changes, comments, formatting preservation, text extraction, template modification.
 license: Proprietary. LICENSE.txt has complete terms
+user-invocable: true
+when_to_use: "Invoke to read, create, or edit Word .docx documents."
+category: document-skills
+keywords: [docx, word, document, office]
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-
 # DOCX creation, editing, and analysis
 
 ## Overview

package/src/claude/skills/frontend-design/SKILL.md

@@ -2,9 +2,14 @@
 name: hapo:frontend-design
 description: Create polished frontend interfaces from designs/screenshots/videos. Use for web components, 3D experiences, replicating UI designs, quick prototypes, immersive interfaces, avoiding AI slop.
 license: Complete terms in LICENSE.txt
-version: "1.0.0"
+user-invocable: true
+when_to_use: "Invoke to translate mockups or screenshots into UI implementation."
+category: frontend
+keywords: [design, mockup, ui, replication]
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
 
 **IMPORTANT**: MUST follow Design Thinking, Frontend Aesthetics Guidelines, Asset & Analysis References, and Anti-Patterns (AI Slop) sections below. DO NOT skip these rules.

package/src/claude/skills/frontend-development/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:frontend-development
 description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, useSuspenseQuery, MUI v7 styling, TanStack Router, performance optimization.
+user-invocable: true
+when_to_use: "Invoke to build React/TS components with best practices."
+category: frontend
+keywords: [frontend, react, typescript, components]
 argument-hint: "[component or feature]"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Frontend Development Guidelines
 
 ## Purpose

package/src/claude/skills/generate-graph/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: hapo:generate-graph
 description: >-
-  Use when the user wants to create any technical diagram - architecture, data
-  flow, flowchart, sequence, agent/memory, or concept map - and export as
-  SVG+PNG. Trigger on: "generate diagram" "draw diagram" "visualize" or any
-  system/flow description the user wants illustrated.
+user-invocable: true
+when_to_use: "Invoke to build a queryable graph or diagram from code or data."
+category: utilities
+keywords: [graph, visualization, diagram, analysis]
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Generate Graph
 
 Generate production-quality SVG technical diagrams exported as PNG via `rsvg-convert`.

package/src/claude/skills/git/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:git
 description: "Hapo Native Git Operations & Worktree Management. Handles safe commits, conventional split, branch finish choices, secret scanning, and sibling-branch worktrees locally."
+user-invocable: true
+when_to_use: "Invoke for commits, PRs, branch hygiene, or worktree management."
+category: dev-tools
+keywords: [git, commits, pr, worktree]
 argument-hint: "commit | push | pr | finish | worktree <feature-desc>"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Git Operations & Worktree
 
 This skill merges Version Control Systems (VSC) capabilities and parallel Worktree management into a single, clean-room execution engine utilizing pure Bash commands rather than proprietary Node scripts.

package/src/claude/skills/hotfix/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:hotfix
 description: "ALWAYS activate this skill when you are asked to FIX a bug, error, test failure, CI/CD issue, type error, lint error, log error, UI issue, or code problem. Uses hapo:debug for evidence-first diagnosis before any code change."
+user-invocable: true
+when_to_use: "Invoke to fix a bug or failure with scout-first diagnosis before change."
+category: dev-tools
+keywords: [hotfix, fix, bug, diagnosis]
 argument-hint: "[issue] --quick|--parallel|--from-debug"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Hotfix - Structured Bug Elimination
 
 Kill bugs systematically. No guessing. Evidence first, fix second.

package/src/claude/skills/impact-analysis/SKILL.md

@@ -1,10 +1,15 @@
 ---
-name: impact-analysis
+name: hapo:impact-analysis
 description: "Analyze code change impacts and generate test scenarios. Use after code changes, before commit, or when checking for regressions. Automatically detects affected files, dependencies, and edge cases."
+user-invocable: true
+when_to_use: "Invoke after code changes to map regression impact and test scenarios."
+category: dev-tools
+keywords: [impact, regression, dependencies, testing]
 argument-hint: "[files] OR auto"
-version: 1.0.0
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Impact Analysis - Impact Analysis & Test Guidance
 
 Analyze the impact of code changes and provide detailed test guidance to prevent regression bugs.

package/src/claude/skills/inspect/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:inspect
 description: "Fast codebase discovery using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) and external (Gemini) agents."
-version: 2.0.0
+user-invocable: true
+when_to_use: "Invoke for fast parallel codebase discovery and file location."
+category: discovery
+keywords: [discovery, search, explore, context]
 argument-hint: "[search-target] [ext]"
+metadata:
+  author: haposoft
+  version: "2.0.0"
 ---
-
 # Inspect
 
 Fast, token-efficient codebase discovery using parallel agents to find files needed for tasks.

package/src/claude/skills/mobile-development/SKILL.md

@@ -2,10 +2,15 @@
 name: hapo:mobile-development
 description: Build mobile apps with React Native, Flutter, Swift/SwiftUI, Kotlin/Jetpack Compose. Use for iOS/Android, mobile UX, performance optimization, offline-first, app store deployment.
 license: MIT
+user-invocable: true
+when_to_use: "Invoke to build or modify mobile app features and UI."
+category: frontend
+keywords: [mobile, app, ios, android]
 argument-hint: "[platform] [feature]"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Mobile Development Skill
 
 Production-ready mobile development with modern frameworks, best practices, and mobile-first thinking patterns.

package/src/claude/skills/pdf/SKILL.md

@@ -2,11 +2,14 @@
 name: hapo:pdf
 description: Extract text/tables, create, merge, split PDFs. Fill PDF forms programmatically. Use for PDF processing, generation, form filling, document analysis, batch operations.
 license: Proprietary. LICENSE.txt has complete terms
+user-invocable: true
+when_to_use: "Invoke to read, extract, or generate PDF documents."
+category: document-skills
+keywords: [pdf, extract, document, generate]
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-
 # PDF Processing Guide
 
 ## Overview

package/src/claude/skills/pptx/SKILL.md

@@ -2,11 +2,14 @@
 name: hapo:pptx
 description: Create, edit, analyze .pptx PowerPoint files. Use for presentations, slides, layouts, speaker notes, template modification, content extraction, slide generation.
 license: Proprietary. LICENSE.txt has complete terms
+user-invocable: true
+when_to_use: "Invoke to read, create, or edit PowerPoint .pptx slides."
+category: document-skills
+keywords: [pptx, powerpoint, slides, office]
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-
 # PPTX creation, editing, and analysis
 
 ## Overview

package/src/claude/skills/question/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:question
 description: "Answer questions with evidence. Use when the user asks about project behavior, source code, specs, docs, configuration, dependencies, or external technical information; inspect the repo first, use internet/current docs when repo evidence is insufficient, and ask back only when the question cannot be answered safely."
+user-invocable: true
+when_to_use: "Invoke to answer project or technical questions with repo-first evidence."
+category: utilities
+keywords: [question, evidence, answer, research]
 argument-hint: "<question> [--repo|--web|--both|--brief|--deep]"
-version: 1.0.0
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Question Skill
 
 `hapo:question` is an evidence-backed question-answering skill. It answers user questions by checking the local project first, then external/current sources when the repository cannot answer the question.

package/src/claude/skills/react-best-practices/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:react-best-practices
 description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+user-invocable: true
+when_to_use: "Invoke to apply React performance and architecture best practices."
+category: frontend
+keywords: [react, performance, patterns, hooks]
 argument-hint: "[component or pattern]"
-version: "1.0.0"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Vercel React Best Practices
 
 Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

package/src/claude/skills/research/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:research
 description: "Research technical solutions and analyze architectures. Acts as a command facade to trigger the 'researcher' subagent for multi-source verification and deep report synthesis."
+user-invocable: true
+when_to_use: "Invoke for deep technical research and solution evaluation before building."
+category: research
+keywords: [research, evaluation, analysis, solutions]
 argument-hint: "<topic_or_question>"
-version: 2.0.0
+metadata:
+  author: haposoft
+  version: "2.0.0"
 ---
-
 # Research (Delegation Facade)
 
 **Mantra:** YAGNI, KISS, DRY. Be brutal, straight to the point, and strictly authoritative.

package/src/claude/skills/specs/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:specs
 description: "Structured specification workflow — from vague idea to actionable task list. Includes init, requirements, design, task breakdown, review, and archiving."
-version: 2.0.0
+user-invocable: true
+when_to_use: "Invoke to turn a vague idea into an actionable, gated specification."
+category: utilities
+keywords: [specs, requirements, design, tasks]
 argument-hint: "<feature-description> | status | resume | --validate | archive"
+metadata:
+  author: haposoft
+  version: "2.0.0"
 ---
-
 # Specs (SDD — Specification-Driven Development)
 
 > A structured specification system that turns vague ideas into actionable, implementable task lists.

package/src/claude/skills/sync/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:sync
 description: "Dumb-proof status tracker and file synchronizer. Updates spec.json, task_registry, and tasks/*.md without breaking structural schemas. Includes Auto-Audit."
-version: 1.0.0
+user-invocable: true
+when_to_use: "Invoke to synchronize spec state, docs, or task tracking after changes."
+category: utilities
+keywords: [sync, state, tracking, consistency]
 argument-hint: "<feature_name> <task_id|task-file> <status> [blocker] | phase <feature_name> <next_phase> | audit <feature_name>"
+metadata:
+  author: haposoft
+  version: "1.0.0"
 ---
-
 # Sync (State Tracking Protocol)
 
 This skill safely bridges the gap between active development state and physical documentation files (`spec.json` + `task_registry` + `tasks/task-R*.md`). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.

package/src/claude/skills/test/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: hapo:test
 description: "Run and verify project tests across all scopes: unit, integration, e2e, and UI. Blast-radius scoping for speed, chrome-devtools for UI verification, structured verdicts for downstream automation."
+user-invocable: true
+when_to_use: "Invoke to run and verify unit, integration, e2e, and UI tests."
+category: testing
+keywords: [test, unit, integration, e2e]
 argument-hint: "[scope|--full|--ui <url>|--ui-auth <url>|--ui-flow <url>]"
-version: 2.0.0
+metadata:
+  author: haposoft
+  version: "2.0.0"
 ---
-
 # Test — Verify Implementation Quality
 
 Run the project's test suite, analyze results, and return a structured verdict.

package/src/claude/skills/ui-ux-pro-max/SKILL.md

@@ -1,9 +1,14 @@
 ---
 name: hapo:ui-ux-pro-max
 description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
-version: "1.1.0"
+user-invocable: true
+when_to_use: "Invoke to choose colors, fonts, layout, and design systems."
+category: frontend
+keywords: [ui, ux, design-system, layout]
+metadata:
+  author: haposoft
+  version: "1.1.0"
 ---
-
 # UI/UX Pro Max - Design Intelligence
 
 Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations.

package/src/claude/skills/web-testing/SKILL.md

@@ -2,10 +2,15 @@
 name: hapo:web-testing
 description: Web testing with Playwright, Vitest, k6. E2E/unit/integration/load/security/visual/a11y testing. Use for test automation, flakiness, Core Web Vitals, mobile gestures, cross-browser.
 license: Apache-2.0
+user-invocable: true
+when_to_use: "Invoke to test web flows in a real browser end-to-end."
+category: testing
+keywords: [web-testing, e2e, browser, validation]
 argument-hint: "[test-type] [target]"
-version: "3.0.0"
+metadata:
+  author: haposoft
+  version: "3.0.0"
 ---
-
 # Web Testing Skill
 
 Comprehensive web testing: unit, integration, E2E, load, security, visual regression, accessibility.

package/src/claude/skills/xlsx/SKILL.md

@@ -2,11 +2,14 @@
 name: hapo:xlsx
 description: Create, edit, analyze spreadsheets (.xlsx, .csv, .tsv). Use for Excel formulas, data analysis, visualization, formatting, pivot tables, charts, formula recalculation.
 license: Proprietary. LICENSE.txt has complete terms
+user-invocable: true
+when_to_use: "Invoke to read, create, or edit Excel .xlsx spreadsheets."
+category: document-skills
+keywords: [xlsx, excel, spreadsheet, office]
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-
 # Requirements for Outputs
 
 ## All Excel files