@haposoft/cafekit 0.3.12 → 0.4.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

@@ -19,6 +19,13 @@ const path = require('path');
 const readline = require('readline');
 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 +34,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;
@@ -649,6 +664,110 @@ 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');
+}
+
 // ═══════════════════════════════════════════════════════════
 // MAIN
 // ═══════════════════════════════════════════════════════════
@@ -718,6 +837,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
@@ -756,6 +877,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.4.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/hooks/agent.cjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * SubagentStart Hook - Injects context to subagents (Optimized)
+ *
+ * Fires: When a subagent (Task tool call) is started
+ * Purpose: Inject minimal context using env vars from SessionStart
+ * Target: ~200 tokens (down from ~350)
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking, allows continuation)
+ */
+
+// Crash wrapper
+try {
+  const fs = require('fs');
+  const path = require('path');
+  const {
+    loadConfig,
+    resolveNamingPattern,
+    getGitBranch,
+    getGitRoot,
+    resolvePlanPath,
+    getReportsPath,
+    normalizePath,
+    extractTaskListId,
+    isHookEnabled
+  } = require('./lib/config.cjs');
+  const { resolveSkillsVenv } = require('./lib/context.cjs');
+
+  // Early exit if hook disabled in config
+  if (!isHookEnabled('subagent-init')) {
+    process.exit(0);
+  }
+
+/**
+ * Get agent-specific context from config
+ */
+function getAgentContext(agentType, config) {
+  const agentConfig = config.subagent?.agents?.[agentType];
+  if (!agentConfig?.contextPrefix) return null;
+  return agentConfig.contextPrefix;
+}
+
+/**
+ * Build trust verification section if enabled
+ */
+function buildTrustVerification(config) {
+  if (!config.trust?.enabled || !config.trust?.passphrase) return [];
+  return [
+    ``,
+    `## Trust Verification`,
+    `Passphrase: "${config.trust.passphrase}"`
+  ];
+}
+
+/**
+ * Main hook execution
+ */
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const agentType = payload.agent_type || 'unknown';
+    const agentId = payload.agent_id || 'unknown';
+
+    // Load config for trust verification, naming, and agent-specific context
+    const config = loadConfig({ includeProject: false, includeAssertions: false });
+
+    // Use payload.cwd if provided for git operations (monorepo support)
+    // This ensures subagent resolves paths relative to its own CWD, not process.cwd()
+    // Issue #327: Use trim() to handle empty string edge case
+    const effectiveCwd = payload.cwd?.trim() || process.cwd();
+
+    // Compute naming pattern directly (don't rely on env vars which may not propagate)
+    // Pass effectiveCwd to git commands to support monorepo/submodule scenarios
+    const gitBranch = getGitBranch(effectiveCwd);
+    const gitRoot = getGitRoot(effectiveCwd);
+    // Issue #327: Use CWD as base for subdirectory workflow support
+    // Git root is kept for reference but CWD determines where files are created
+    const baseDir = effectiveCwd;
+
+    // Debug logging for path resolution troubleshooting
+    if (process.env.CK_DEBUG) {
+      console.error(`[subagent-init] effectiveCwd=${effectiveCwd}, gitRoot=${gitRoot}, baseDir=${baseDir}`);
+    }
+    const namePattern = resolveNamingPattern(config.plan, gitBranch);
+
+    // Resolve plan and reports path - use absolute paths based on CWD (Issue #327)
+    // Use session_id from payload to resolve active plan context (Issue #321)
+    const sessionId = payload.session_id || process.env.CK_SESSION_ID || null;
+    const resolved = resolvePlanPath(sessionId, config);
+    const reportsPath = getReportsPath(resolved.path, resolved.resolvedBy, config.plan, config.paths, baseDir);
+    const activePlan = resolved.resolvedBy === 'session' ? resolved.path : '';
+    const suggestedPlan = resolved.resolvedBy === 'branch' ? resolved.path : '';
+
+    // Extract task list ID for Claude Code Tasks coordination (shared helper, DRY)
+    const taskListId = extractTaskListId(resolved);
+    const plansPath = path.join(baseDir, normalizePath(config.paths?.plans) || 'plans');
+    const docsPath = path.join(baseDir, normalizePath(config.paths?.docs) || 'docs');
+    const thinkingLanguage = config.locale?.thinkingLanguage || '';
+    const responseLanguage = config.locale?.responseLanguage || '';
+    // Auto-default thinkingLanguage to 'en' when only responseLanguage is set
+    const effectiveThinking = thinkingLanguage || (responseLanguage ? 'en' : '');
+
+    // Build compact context (~200 tokens)
+    const lines = [];
+
+    // Subagent identification
+    lines.push(`## Subagent: ${agentType}`);
+    lines.push(`ID: ${agentId} | CWD: ${effectiveCwd}`);
+    lines.push(``);
+
+    // Plan context (from env vars)
+    lines.push(`## Context`);
+    if (activePlan) {
+      lines.push(`- Plan: ${activePlan}`);
+      if (taskListId) {
+        lines.push(`- Task List: ${taskListId} (shared with session)`);
+      }
+    } else if (suggestedPlan) {
+      lines.push(`- Plan: none | Suggested: ${suggestedPlan}`);
+    } else {
+      lines.push(`- Plan: none`);
+    }
+    lines.push(`- Reports: ${reportsPath}`);
+    lines.push(`- Paths: ${plansPath}/ | ${docsPath}/`);
+    lines.push(``);
+
+    // Language (thinking + response, if configured)
+    const hasThinking = effectiveThinking && effectiveThinking !== responseLanguage;
+    if (hasThinking || responseLanguage) {
+      lines.push(`## Language`);
+      if (hasThinking) {
+        lines.push(`- Thinking: Use ${effectiveThinking} for reasoning (logic, precision).`);
+      }
+      if (responseLanguage) {
+        lines.push(`- Response: Respond in ${responseLanguage} (natural, fluent).`);
+      }
+      lines.push(``);
+    }
+
+    // Resolve Python venv path for subagent instructions
+    const skillsVenv = resolveSkillsVenv();
+
+    // Core rules (minimal)
+    lines.push(`## Rules`);
+    lines.push(`- Reports → ${reportsPath}`);
+    lines.push(`- YAGNI / KISS / DRY`);
+    lines.push(`- Concise, list unresolved Qs at end`);
+    // Python venv rules (if venv exists)
+    if (skillsVenv) {
+      lines.push(`- Python scripts in .claude/skills/: Use \`${skillsVenv}\``);
+      lines.push(`- Never use global pip install`);
+    }
+
+    // Naming templates (computed directly for reliable injection)
+    lines.push(``);
+    lines.push(`## Naming`);
+    lines.push(`- Report: ${path.join(reportsPath, `${agentType}-${namePattern}.md`)}`);
+    lines.push(`- Plan dir: ${path.join(plansPath, namePattern)}/`);
+
+    // Trust verification (if enabled)
+    lines.push(...buildTrustVerification(config));
+
+    // Agent-specific context (if configured)
+    const agentContext = getAgentContext(agentType, config);
+    if (agentContext) {
+      lines.push(``);
+      lines.push(`## Agent Instructions`);
+      lines.push(agentContext);
+    }
+
+    // CRITICAL: SubagentStart requires hookSpecificOutput.additionalContext format
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "SubagentStart",
+        additionalContext: lines.join('\n')
+      }
+    };
+
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  } catch (error) {
+    console.error(`SubagentStart hook error: ${error.message}`);
+    process.exit(0); // Fail-open
+  }
+  }
+
+  main();
+} catch (e) {
+  // Minimal crash logging (zero deps — only Node builtins)
+  try {
+    const fs = require('fs');
+    const p = require('path');
+    const logDir = p.join(__dirname, '.logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0); // fail-open
+}

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ANSI Terminal Colors - Cross-platform color support for statusline
+ * Supports NO_COLOR, FORCE_COLOR, COLORTERM auto-detection
+ * @module colors
+ */
+
+// ANSI escape codes (8-color basic palette)
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+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 = (() => {
+  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 256-color support via COLORTERM
+const has256Color = (() => {
+  const ct = process.env.COLORTERM;
+  return ct === 'truecolor' || ct === '24bit' || ct === '256color';
+})();
+
+/**
+ * Wrap text with ANSI color code
+ * @param {string} text - Text to colorize
+ * @param {string} code - ANSI escape code
+ * @returns {string} Colorized text or plain text if colors disabled
+ */
+function colorize(text, code) {
+  if (!shouldUseColor) return String(text);
+  return `${code}${text}${RESET}`;
+}
+
+function green(text) { return colorize(text, GREEN); }
+function yellow(text) { return colorize(text, YELLOW); }
+function red(text) { return colorize(text, RED); }
+function cyan(text) { return colorize(text, CYAN); }
+function magenta(text) { return colorize(text, MAGENTA); }
+function dim(text) { return colorize(text, DIM); }
+
+/**
+ * Get color code based on context percentage threshold
+ * @param {number} percent - Context usage percentage (0-100)
+ * @returns {string} ANSI color code
+ */
+function getContextColor(percent) {
+  if (percent >= 85) return RED;
+  if (percent >= 70) return YELLOW;
+  return GREEN;
+}
+
+/**
+ * Generate colored progress bar for context window
+ * Uses ▰▱ characters (smooth horizontal rectangles) for consistent rendering
+ * @param {number} percent - Usage percentage (0-100)
+ * @param {number} width - Bar width in characters (default 12)
+ * @returns {string} Unicode progress bar with threshold-based colors
+ */
+function coloredBar(percent, width = 12) {
+  const clamped = Math.max(0, Math.min(100, percent));
+  const filled = Math.round((clamped / 100) * width);
+  const empty = width - filled;
+
+  if (!shouldUseColor) {
+    return '▰'.repeat(filled) + '▱'.repeat(empty);
+  }
+
+  const color = getContextColor(percent);
+  return `${color}${'▰'.repeat(filled)}${DIM}${'▱'.repeat(empty)}${RESET}`;
+}
+
+module.exports = {
+  RESET,
+  green,
+  yellow,
+  red,
+  cyan,
+  magenta,
+  dim,
+  getContextColor,
+  coloredBar,
+  shouldUseColor,
+  has256Color
+};