@haposoft/cafekit 0.3.12 → 0.5.0

package/README.md

@@ -43,6 +43,44 @@ CafeKit is a **multi-platform** CLI tool that installs a structured workflow for
 - **📦 No global install** - Use directly with `npx`
 - **🚀 Future-proof** - Easy to add support for new AI editors
 
+## Claude Code Statusline (Claude Code Only)
+
+CafeKit automatically installs an enhanced statusline for Claude Code that provides real-time session context.
+
+**What it shows:**
+- **Context usage** - Percentage and token count (e.g., `23% 45K/200K`)
+- **Session timer** - Elapsed time since session start
+- **Git status** - Current branch and dirty state indicator
+- **Active agents** - Count of running subagents
+- **Todo items** - Count of pending tasks
+
+**Installation:**
+- Automatically installed when running `npx @haposoft/cafekit` in a Claude Code project
+- Merges with existing `settings.json` configuration without overwriting user settings
+- Safe to re-run - preserves non-CafeKit statusline configurations
+- Upgrade mode (`--upgrade`) refreshes managed runtime files
+
+**Configuration:**
+The statusline is configured via `.claude/settings.json`:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node \"$CLAUDE_PROJECT_DIR/.claude/status.cjs\"",
+    "padding": 0
+  }
+}
+```
+
+**Runtime files installed:**
+- `.claude/status.cjs` - Main statusline script
+- `.claude/hooks/session.cjs` - Session initialization hook
+- `.claude/hooks/agent.cjs` - Subagent context injection hook
+- `.claude/hooks/usage.cjs` - Usage tracking hook
+- `.claude/hooks/lib/*.cjs` - Shared utilities (color, parser, git, config, etc.)
+
+**Note:** This feature is Claude Code exclusive and not available for Antigravity.
+
 ## Installation
 
 ### Prerequisites
@@ -63,7 +101,8 @@ The installer will:
 2. **Prompt** you to select platform if not detected
 3. **Copy** workflow commands to the appropriate directory
 4. **Install** shared skills for spec-driven development
-5. **Ensure dependencies** for `code - test - review` by installing missing command/agent templates
+5. **[Claude Code only]** Install unprefixed skill directories (`spec-init`, `spec-requirements`, `spec-design`, `spec-tasks`, `code`, `test`, `review`) that expose `hapo:`-prefixed skill names
+6. **Ensure dependencies** for `code - test - review` by installing missing command/agent templates
 
 Installer modes:
 - **Default install mode**: `npx @haposoft/cafekit` (skip existing files)
@@ -72,33 +111,40 @@ Installer modes:
 
 **Example output (Claude Code):**
 ```
-CafeKit Spec Installer
-===============================
-
-✓ Detected platforms: claude
-
-Installing for: .claude/
-------------------------
-[.claude/skills] Installed skill: spec-driven-development
-[.claude/commands] Copied: spec-init.md
-[.claude/commands] Copied: spec-requirements.md
-[.claude/commands] Copied: spec-design.md
-[.claude/commands] Copied: spec-tasks.md
-[.claude/commands] Copied: code.md
-[.claude/commands] Copied: spec-status.md
-
-Installation complete!
-   Copied Files: 7
-   Skipped Files: 0
-   Installed Skills: Yes
-   Dependency Checks: 6
-   Installed Deps: 6
-   Missing Deps: 0
-   Targets: .claude/commands
+CafeKit Installer v0.3.12
+========================================
+
+Installing for: Claude Code
+Mode: install (skip existing files)
+
+Claude Code (.claude/)
+----------------------------------------
+✓ Skill installed: specs
+✓ Skill installed: spec-init
+✓ Skill installed: spec-requirements
+✓ Skill installed: spec-design
+✓ Skill installed: spec-tasks
+✓ Skill installed: code
+✓ Skill installed: test
+✓ Skill installed: review
+✓ Copied: spec-init.md
+✓ Copied: spec-requirements.md
+...
+
+╔════════════════════════════════════════════════════════╗
+║         Installation Complete!                         ║
+╚════════════════════════════════════════════════════════╝
+
+  Installed Skills:   Yes ✓
 
 Next steps:
-   1. Run /spec-init <feature-name>
-   2. Follow the spec workflow: requirements - design - tasks - code - test - review
+  1. Start your AI editor
+
+  For Claude Code:
+     Run: /spec-init <feature-name>
+     Or use skill: /hapo:spec-init <feature-description>
+
+  2. Follow the workflow: requirements - design - tasks - code - test - review
 
 Documentation: https://github.com/haposoft/cafekit
 ```
@@ -565,7 +611,15 @@ User clicks -> dispatch action -> update context -> localStorage -> re-render
 │   ├── spec-status.md
 │   └── docs.md               # Docs workflows
 └── skills/
-    └── spec-driven-development/
+    ├── specs/
+    ├── impact-analysis/
+    ├── spec-init/
+    ├── spec-requirements/
+    ├── spec-design/
+    ├── spec-tasks/
+    ├── code/
+    ├── test/
+    └── review/
 ```
 
 **Antigravity** (`.agent/`):
@@ -583,7 +637,8 @@ User clicks -> dispatch action -> update context -> localStorage -> re-render
 │   ├── docs-init.md            # Docs workflows
 │   └── docs-update.md
 ├── skills/
-│   └── spec-driven-development/
+│   ├── specs/
+│   └── impact-analysis/
 └── rules/
     └── GEMINI.md               # System rules (always_on)
 ```

package/bin/install.js

@@ -17,8 +17,16 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync } = require('child_process');
 const packageJson = require('../package.json');
 
+function validateManifestV2(manifest) {
+  if (!manifest || manifest.version !== 2) return false;
+  if (!manifest.runtime?.files || !Array.isArray(manifest.runtime.files)) return false;
+  if (!manifest.settings?.template) return false;
+  return true;
+}
+
 function loadClaudeMigrationManifest() {
   const manifestPath = path.join(__dirname, '../src/claude/migration-manifest.json');
 
@@ -27,7 +35,15 @@ function loadClaudeMigrationManifest() {
   }
 
   try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+    if (!validateManifestV2(manifest)) {
+      console.error('✗ Invalid manifest v2 schema - missing required fields');
+      console.error('  Expected: version=2, runtime.files[], settings.template');
+      process.exit(1);
+    }
+
+    return manifest;
   } catch (error) {
     console.warn(`⚠ Failed to parse Claude migration manifest: ${error.message}`);
     return null;
@@ -472,8 +488,8 @@ function copyPlatformFiles(platformKey, results, options = {}) {
     if (platformKey === 'claude') {
       requiredSkills = CLAUDE_MIGRATION_MANIFEST?.skills?.required || [];
     } else if (platformKey === 'antigravity') {
-      // Antigravity also needs impact-analysis skill
-      requiredSkills = ['impact-analysis'];
+      // Antigravity also needs shared investigation and impact-analysis skills
+      requiredSkills = ['impact-analysis', 'debug'];
     }
 
     requiredSkills
@@ -649,6 +665,224 @@ function copyGeminiFile(platformKey, results, options = {}) {
   }
 }
 
+// Copy Claude runtime files (statusline bundle)
+function copyClaudeRuntimeFiles(platformKey, results, options = {}) {
+  if (platformKey !== 'claude') return;
+
+  const manifest = CLAUDE_MIGRATION_MANIFEST;
+  if (!manifest?.runtime?.files) return;
+
+  const shouldOverwriteManagedFiles = Boolean(options.upgrade);
+  const srcBase = path.join(__dirname, '../src/claude');
+  const targetBase = path.join(PLATFORMS.claude.folder);
+
+  manifest.runtime.files.forEach(relPath => {
+    const srcPath = path.join(srcBase, relPath);
+    const targetPath = path.join(targetBase, relPath);
+
+    if (!fs.existsSync(srcPath)) {
+      console.log(`  ⚠ Runtime file not found: ${relPath}`);
+      results.missingDependencies++;
+      return;
+    }
+
+    const targetExists = fs.existsSync(targetPath);
+    const shouldCopy = shouldOverwriteManagedFiles || !targetExists;
+
+    if (shouldCopy) {
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(srcPath, targetPath);
+
+      if (targetExists) {
+        console.log(`  ↻ Runtime updated: ${relPath}`);
+        results.updated++;
+      } else {
+        console.log(`  ✓ Runtime installed: ${relPath}`);
+        results.copied++;
+      }
+    } else {
+      results.skipped++;
+    }
+  });
+}
+
+// Merge Claude settings.json
+function mergeClaudeSettings(platformKey, results, options = {}) {
+  if (platformKey !== 'claude') return;
+
+  const manifest = CLAUDE_MIGRATION_MANIFEST;
+  if (!manifest?.settings?.template) return;
+
+  const templatePath = path.join(__dirname, '../src/claude', manifest.settings.template);
+  const targetPath = path.join(PLATFORMS.claude.folder, 'settings.json');
+
+  if (!fs.existsSync(templatePath)) {
+    console.log(`  ⚠ Settings template not found: ${manifest.settings.template}`);
+    return;
+  }
+
+  const managedSettings = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  let existingSettings = {};
+
+  if (fs.existsSync(targetPath)) {
+    existingSettings = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  }
+
+  const mergedSettings = { ...existingSettings };
+
+  // Merge statusLine
+  if (managedSettings.statusLine) {
+    const existingCommand = existingSettings.statusLine?.command || '';
+    const isCafeKitOwned = existingCommand.includes('status.cjs') || existingCommand.includes('statusline.cjs');
+
+    if (options.upgrade || !existingSettings.statusLine || isCafeKitOwned) {
+      mergedSettings.statusLine = managedSettings.statusLine;
+      console.log(`  ✓ Settings: statusLine merged`);
+    }
+  }
+
+  // Merge hooks
+  if (managedSettings.hooks) {
+    mergedSettings.hooks = mergedSettings.hooks || {};
+
+    Object.keys(managedSettings.hooks).forEach(eventName => {
+      const managedHooks = managedSettings.hooks[eventName];
+      const existingHooks = mergedSettings.hooks[eventName] || [];
+      const mergedHooks = [...existingHooks];
+
+      managedHooks.forEach(managedHook => {
+        const managedCommand = managedHook.hooks?.[0]?.command || '';
+        const isDuplicate = mergedHooks.some(existingHook => {
+          return existingHook.hooks?.some(h => h.command === managedCommand);
+        });
+
+        if (!isDuplicate) {
+          mergedHooks.push(managedHook);
+          console.log(`  ✓ Settings: hook ${eventName} merged`);
+        }
+      });
+
+      mergedSettings.hooks[eventName] = mergedHooks;
+    });
+  }
+
+  fs.writeFileSync(targetPath, JSON.stringify(mergedSettings, null, 2), 'utf8');
+}
+
+// ═══════════════════════════════════════════════════════════
+// GEMINI CLI SETUP
+// ═══════════════════════════════════════════════════════════
+
+function checkGeminiCLI() {
+  try {
+    execSync('which gemini', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installGeminiCLI() {
+  console.log('\n⚙ Installing gemini-cli...');
+  try {
+    execSync('npm install -g @google/generative-ai-cli', { stdio: 'inherit' });
+    console.log('  ✓ gemini-cli installed successfully');
+    return true;
+  } catch (error) {
+    console.log('  ✗ Failed to install gemini-cli automatically');
+    console.log('  Please run manually: npm install -g @google/generative-ai-cli');
+    return false;
+  }
+}
+
+async function promptInstallGemini() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log('\n📦 Optional: Gemini CLI Installation');
+  console.log('  hapo:inspect with ext mode requires gemini-cli');
+  console.log('  • Install now: Auto-install and configure API key');
+  console.log('  • Skip: You can still use hapo:inspect in internal mode');
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question('Install gemini-cli? (Y/n): ', (answer) => {
+      rl.close();
+      const response = answer.trim().toLowerCase();
+      resolve(response === '' || response === 'y' || response === 'yes');
+    });
+  });
+}
+
+async function promptGeminiAPIKey() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log('\n📝 Gemini API Key Configuration');
+  console.log('  Get your API key: https://aistudio.google.com/apikey');
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question('Enter your Gemini API key (or press Enter to skip): ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function configureGeminiKey(apiKey) {
+  try {
+    execSync(`gemini config set-key ${apiKey}`, { stdio: 'inherit' });
+    console.log('  ✓ Gemini API key configured successfully');
+    return true;
+  } catch (error) {
+    console.log('  ✗ Failed to configure Gemini API key');
+    console.log('  Please run manually: gemini config set-key YOUR_API_KEY');
+    return false;
+  }
+}
+
+async function setupGeminiCLI() {
+  const hasGemini = checkGeminiCLI();
+
+  if (hasGemini) {
+    console.log('  ✓ gemini-cli already installed');
+    return;
+  }
+
+  const shouldInstall = await promptInstallGemini();
+
+  if (!shouldInstall) {
+    console.log('\n  ℹ Skipped gemini-cli installation');
+    console.log('  • hapo:inspect will work in internal mode (default)');
+    console.log('  • To install later: npm install -g @google/generative-ai-cli');
+    return;
+  }
+
+  console.log('\n⚙ Installing gemini-cli...');
+  const installed = installGeminiCLI();
+
+  if (installed) {
+    const apiKey = await promptGeminiAPIKey();
+
+    if (apiKey) {
+      configureGeminiKey(apiKey);
+    } else {
+      console.log('\n📝 Skipped API key configuration');
+      console.log('  Configure later with: gemini config set-key YOUR_API_KEY');
+    }
+  } else {
+    console.log('\n📝 Manual installation steps:');
+    console.log('  1. npm install -g @google/generative-ai-cli');
+    console.log('  2. Get API key: https://aistudio.google.com/apikey');
+    console.log('  3. gemini config set-key YOUR_API_KEY');
+  }
+}
+
 // ═══════════════════════════════════════════════════════════
 // MAIN
 // ═══════════════════════════════════════════════════════════
@@ -718,6 +952,8 @@ async function main() {
       // Copy ROUTING.md for Claude Code platform
       if (platformKey === 'claude') {
         copyRoutingFile(platformKey, results, installerOptions);
+        copyClaudeRuntimeFiles(platformKey, results, installerOptions);
+        mergeClaudeSettings(platformKey, results, installerOptions);
       }
 
       // Copy GEMINI.md for Antigravity platform
@@ -729,6 +965,9 @@ async function main() {
       console.log();
     }
 
+    // Setup Gemini CLI for hapo:inspect ext mode
+    setupGeminiCLI();
+
     // Note: CLAUDE.md and docs/ are generated via /docs init command
 
     // Summary
@@ -756,6 +995,9 @@ async function main() {
       const platform = PLATFORMS[platformKey];
       console.log(`\n  For ${platform.name}:`);
       console.log(`     Run: ${platform.commandPrefix}spec-init <feature-name>`);
+      if (platformKey === 'claude') {
+        console.log('     Or use skill: /hapo:spec-init <feature-description>');
+      }
     }
 
     console.log('\n  2. Follow the workflow: requirements - design - tasks - code - test - review');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.3.12",
-  "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first and code-test-review workflows.",
+  "version": "0.5.0",
+  "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first workflows plus Claude Code hapo: skills.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
   "private": false,
@@ -32,7 +32,9 @@
     "ai-coding",
     "specification",
     "requirements",
-    "sdd"
+    "sdd",
+    "skills",
+    "hapo"
   ],
   "engines": {
     "node": ">=18.0.0"

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

@@ -1,11 +1,11 @@
 ---
 name: code-reviewer
-description: "Comprehensive code review with scout-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization."
+description: "Comprehensive code review with inspect-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization."
 ---
 
 Senior software engineer specializing in code quality assessment. Expertise in TypeScript, JavaScript, Dart (Flutter), security, and performance.
 
-**IMPORTANT**: Ensure token efficiency. Use `scout` and `code-review` skills for protocols.
+**IMPORTANT**: Ensure token efficiency. Use `hapo:inspector` and `code-review` protocols for edge-case discovery before review.
 
 ## Core Responsibilities
 
@@ -18,36 +18,37 @@ Senior software engineer specializing in code quality assessment. Expertise in T
 
 ## Review Process
 
-### 1. Edge Case Scouting (NEW - Do First)
+### 1. Edge Case Inspection (NEW - Do First)
 
-Before reviewing, scout for edge cases the diff doesn't show:
+Before reviewing, inspect for edge cases the diff doesn't show:
 
 ```bash
 git diff --name-only HEAD~1  # Get changed files
 ```
 
-Use `/scout` with edge-case-focused prompt:
+Use `/hapo:inspector` with an edge-case-focused prompt:
 ```
-Scout edge cases for recent changes.
+Inspect edge cases for recent changes.
+Scope: {directories around changed files}
 Changed: {files}
 Find: affected dependents, data flow risks, boundary conditions, async races, state mutations
 ```
 
-Document scout findings for inclusion in review.
+Document inspect findings for inclusion in review.
 
 ### 2. Initial Analysis
 
 - Read `.specs/<feature>/tasks.md` and related changed files
 - Focus on recently changed files (use `git diff`)
 - For full codebase: use `repomix` to compact, then analyze
-- Wait for scout results before proceeding
+- Wait for inspect results before proceeding
 
 ### 3. Systematic Review
 
 | Area | Focus |
 |------|-------|
 | Structure | Organization, modularity |
-| Logic | Correctness, edge cases from scout |
+| Logic | Correctness, edge cases from inspect |
 | Types | Safety, error handling |
 | Performance | Bottlenecks, inefficiencies |
 | Security | Vulnerabilities, data exposure |
@@ -79,7 +80,7 @@ Mark reviewed task status and add next steps in workflow handoff.
 - Files: [list]
 - LOC: [count]
 - Focus: [recent/specific/full]
-- Scout findings: [edge cases discovered]
+- Inspect findings: [edge cases discovered]
 
 ### Overall Assessment
 [Brief quality overview]
@@ -96,8 +97,8 @@ Mark reviewed task status and add next steps in workflow handoff.
 ### Low Priority
 [Style, minor opts]
 
-### Edge Cases Found by Scout
-[List issues from scouting phase]
+### Edge Cases Found by Inspect
+[List issues from inspection phase]
 
 ### Positive Observations
 [Good practices noted]
@@ -122,7 +123,7 @@ Mark reviewed task status and add next steps in workflow handoff.
 - No AI attribution in code/commits
 - Security best practices priority
 - **Verify spec task checklist completion**
-- **Scout edge cases BEFORE reviewing**
+- **Inspect edge cases BEFORE reviewing**
 
 ## Report Output
 

package/src/claude/agents/debugger.md

@@ -41,7 +41,7 @@ When investigating issues, you will:
    - **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 `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/hapo:inspector ext` for scoped Gemini discovery or `/hapo:inspector` 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>

package/src/claude/commands/review/codebase/parallel.md

@@ -13,7 +13,7 @@ argument-hint: [scope-or-prompt]
 
 Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
 - Read `codebase-summary.md` for context
-- Use `/scout:ext` to find relevant files
+- Use `/hapo:inspector ext` for scoped Gemini discovery; if external mode is unavailable or not appropriate, fall back to `/hapo:inspector` for scoped internal discovery
 - **Think exhaustively** about what could go wrong:
   - Null/undefined scenarios
   - Boundary conditions (off-by-one, empty, max values)

package/src/claude/commands/review/codebase.md

@@ -24,7 +24,7 @@ Think harder to scan the codebase and analyze it follow the Orchestration Protoc
 
 * Use 2 `researcher` subagents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
 * Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
-* Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+* Use `/hapo:inspector ext` for scoped Gemini discovery or `/hapo:inspector` for scoped internal discovery to search the codebase for files needed to complete the task
 
 ### Code Review
 
@@ -34,7 +34,7 @@ Think harder to scan the codebase and analyze it follow the Orchestration Protoc
 * **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
 
 ### Plan
-* Use `planner` subagent to analyze reports from `researcher` and `scout` subagents to create an improvement plan following the progressive disclosure structure:
+* Use `planner` subagent to analyze reports from `researcher` and `hapo:inspector` discovery runs to create an improvement plan following the progressive disclosure structure:
   - Create a directory using naming pattern from `## Naming` section.
   - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
   - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).