agile-context-engineering 0.2.1 → 0.2.2

package/README.md

@@ -124,6 +124,10 @@ npx agile-context-engineering --opencode --global # Crush (formerly OpenCode), g
 npx agile-context-engineering --all --global      # All runtimes, global install
 ```
 
+### Updating
+
+When a new version is available, your status bar will show a yellow `/ace:update` indicator. Run the `/ace:update` command inside Claude Code to update — it detects your install type (global/local, Claude/Crush) automatically and runs the correct installer.
+
 ### Prerequisites
 
 | Requirement | Purpose |

package/agile-context-engineering/workflows/update.xml

@@ -0,0 +1,207 @@
+<workflow>
+
+    <purpose>
+        Check for ACE updates via npm, display version comparison, obtain user confirmation,
+        and execute clean installation with cache clearing.
+    </purpose>
+
+    <mandatory-context>
+        Read all files referenced by the invoking prompt's execution-context before starting.
+    </mandatory-context>
+
+    <process>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 1: DETECT INSTALLATION                                       -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="detect-installation" order="1">
+            Detect whether ACE is installed locally or globally, and for which runtime.
+
+            ```bash
+            if [ -f "./.claude/agile-context-engineering/VERSION" ]; then
+              echo "SCOPE=local"
+              echo "RUNTIME=claude"
+              echo "VERSION=$(cat ./.claude/agile-context-engineering/VERSION)"
+            elif [ -f "$HOME/.claude/agile-context-engineering/VERSION" ]; then
+              echo "SCOPE=global"
+              echo "RUNTIME=claude"
+              echo "VERSION=$(cat $HOME/.claude/agile-context-engineering/VERSION)"
+            elif [ -f "./.opencode/agile-context-engineering/VERSION" ]; then
+              echo "SCOPE=local"
+              echo "RUNTIME=opencode"
+              echo "VERSION=$(cat ./.opencode/agile-context-engineering/VERSION)"
+            elif [ -f "$HOME/.opencode/agile-context-engineering/VERSION" ]; then
+              echo "SCOPE=global"
+              echo "RUNTIME=opencode"
+              echo "VERSION=$(cat $HOME/.opencode/agile-context-engineering/VERSION)"
+            else
+              echo "SCOPE=unknown"
+              echo "RUNTIME=claude"
+              echo "VERSION=0.0.0"
+            fi
+            ```
+
+            Parse SCOPE, RUNTIME, and VERSION from the output.
+
+            **If SCOPE is "unknown":**
+            ```
+            ## ACE Update
+
+            **Installed version:** Unknown
+
+            Your installation doesn't include version tracking.
+            Running fresh install...
+            ```
+
+            Proceed with VERSION=0.0.0.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 2: CHECK LATEST VERSION                                      -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="check-latest-version" order="2">
+            Check npm for the latest published version:
+
+            ```bash
+            npm view agile-context-engineering version 2>/dev/null
+            ```
+
+            **If npm check fails:**
+            ```
+            Couldn't check for updates (offline or npm unavailable).
+
+            To update manually: `npx agile-context-engineering --claude --global`
+            ```
+            Exit.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 3: COMPARE VERSIONS                                          -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="compare-versions" order="3">
+            Compare installed vs latest.
+
+            **If installed == latest:**
+            ```
+            ## ACE Update
+
+            **Installed:** X.Y.Z
+            **Latest:** X.Y.Z
+
+            You're already on the latest version.
+            ```
+            Exit.
+
+            **If installed > latest:**
+            ```
+            ## ACE Update
+
+            **Installed:** X.Y.Z
+            **Latest:** A.B.C
+
+            You're ahead of the latest release (development version?).
+            ```
+            Exit.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 4: CONFIRM UPDATE                                            -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="confirm-update" order="4">
+            If update is available, show what will happen and ask for confirmation:
+
+            ```
+            ## ACE Update Available
+
+            **Installed:** {installed_version}
+            **Latest:** {latest_version}
+
+            The installer performs a clean install of ACE folders:
+            - `commands/ace/` will be wiped and replaced
+            - `agile-context-engineering/` will be wiped and replaced
+            - `agents/ace-*` files will be replaced
+
+            Your custom files are preserved:
+            - Custom commands not in `commands/ace/`
+            - Custom agents not prefixed with `ace-`
+            - Your CLAUDE.md files
+            - Your .ace/ project artifacts
+            ```
+
+            Use AskUserQuestion:
+            - Question: "Proceed with update?"
+            - Options:
+              - "Yes, update now"
+              - "No, cancel"
+
+            **If user cancels:** Exit.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5: RUN UPDATE                                                -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="run-update" order="5">
+            Run the update using detected SCOPE and RUNTIME from step 1.
+
+            Build the command: `npx agile-context-engineering --{RUNTIME} --{SCOPE}`
+
+            Examples:
+            - Global Claude:  `npx agile-context-engineering --claude --global`
+            - Local Claude:   `npx agile-context-engineering --claude --local`
+            - Global Crush:   `npx agile-context-engineering --opencode --global`
+            - Local Crush:    `npx agile-context-engineering --opencode --local`
+
+            If SCOPE was "unknown", default to `--claude --global`.
+
+            Capture output. If install fails, show error and exit.
+
+            Clear the update cache so statusline indicator disappears:
+
+            **If SCOPE is "local":**
+            ```bash
+            rm -f ./.claude/cache/ace-update-check.json
+            ```
+
+            **If SCOPE is "global":**
+            ```bash
+            rm -f "$HOME/.claude/cache/ace-update-check.json"
+            ```
+
+            For Crush runtime, substitute `.opencode` for `.claude` in the cache path.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 6: DISPLAY RESULT                                            -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="display-result" order="6">
+            Format completion message:
+
+            ```
+            ============================================================
+              ACE Updated: v{old} -> v{new}
+            ============================================================
+
+            Restart Claude Code to pick up the new commands.
+            ```
+        </step>
+
+    </process>
+
+    <success_criteria>
+        <check>Installed version detected correctly (local/global, claude/crush)</check>
+        <check>Latest version checked via npm</check>
+        <check>Update skipped if already current</check>
+        <check>Clean install warning shown</check>
+        <check>User confirmation obtained before update</check>
+        <check>Update executed with correct --runtime and --scope flags</check>
+        <check>Update cache cleared</check>
+        <check>Restart reminder shown</check>
+    </success_criteria>
+
+</workflow>

package/bin/install.js

@@ -5,7 +5,7 @@ const path = require('path');
 const readline = require('readline');
 const os = require('os');
 
-const VERSION = '0.1.0';
+const VERSION = require('../package.json').version;
 
 // ANSI color codes
 const colors = {
@@ -67,12 +67,31 @@ function parseArgs() {
     all: args.includes('--all'),
     global: args.includes('--global'),
     local: args.includes('--local'),
+    forceStatusline: args.includes('--force-statusline'),
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
   };
   return flags;
 }
 
+// Read or create settings.json
+function readSettings(settingsPath) {
+  if (fs.existsSync(settingsPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      return {};
+    }
+  }
+  return {};
+}
+
+// Build hook command with proper quoting for the target directory
+function buildHookCommand(targetDir, hookFile) {
+  const hookPath = path.join(targetDir, 'hooks', hookFile);
+  return `node "${hookPath.replace(/\\/g, '/')}"`;
+}
+
 function showHelp() {
   log(`
 Usage: npx agile-context-engineering [options]
@@ -82,9 +101,10 @@ Options:
   --opencode    Install for Crush (formerly OpenCode)
   --all         Install for all supported runtimes
   --global      Install globally (~/.claude, ~/.opencode)
-  --local       Install locally (.claude, .opencode)
-  -h, --help    Show this help message
-  -v, --version Show version number
+  --local             Install locally (.claude, .opencode)
+  --force-statusline  Replace existing statusline configuration
+  -h, --help          Show this help message
+  -v, --version       Show version number
 
 Examples:
   npx agile-context-engineering                    # Interactive installation
@@ -278,6 +298,26 @@ function installForRuntime(runtime, scope, packageDir) {
     log(`  ✓ Tools installed`, colors.green);
   }
 
+  // Copy hooks
+  const srcHooks = path.join(packageDir, 'hooks');
+  const hooksPath = path.join(basePath, 'hooks');
+  if (fs.existsSync(srcHooks)) {
+    // Only copy ace-* hook files, preserve non-ACE hooks (e.g. GSD)
+    if (!fs.existsSync(hooksPath)) {
+      fs.mkdirSync(hooksPath, { recursive: true });
+    }
+    for (const f of fs.readdirSync(srcHooks)) {
+      if (f.startsWith('ace-')) {
+        fs.copyFileSync(path.join(srcHooks, f), path.join(hooksPath, f));
+      }
+    }
+    log(`  ✓ Hooks installed`, colors.green);
+  }
+
+  // Write VERSION file for update checking
+  const versionFile = path.join(acePath, 'VERSION');
+  fs.writeFileSync(versionFile, VERSION, 'utf-8');
+
   return basePath;
 }
 
@@ -355,21 +395,92 @@ async function main() {
     installedPaths.push({ runtime, name: RUNTIMES[runtime].name, path: installedPath });
   }
 
+  // Configure hooks and statusline in settings.json (Claude Code only, not Crush)
+  for (const { runtime, path: basePath } of installedPaths) {
+    if (runtime !== 'claude') continue;
+
+    const settingsPath = path.join(basePath, 'settings.json');
+    const settings = readSettings(settingsPath);
+
+    const statuslineCommand = buildHookCommand(basePath, 'ace-statusline.js');
+    const updateCheckCommand = buildHookCommand(basePath, 'ace-check-update.js');
+
+    // Register SessionStart hook for background update checking
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+    const hasAceUpdateHook = settings.hooks.SessionStart.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('ace-check-update'))
+    );
+    if (!hasAceUpdateHook) {
+      settings.hooks.SessionStart.push({
+        hooks: [{ type: 'command', command: updateCheckCommand }]
+      });
+      log(`  ✓ Configured update check hook`, colors.green);
+    }
+
+    // Handle statusline configuration
+    const hasExisting = settings.statusLine != null;
+    const isAceStatusline = hasExisting && settings.statusLine.command &&
+      settings.statusLine.command.includes('ace-statusline');
+
+    if (!hasExisting || flags.forceStatusline) {
+      // No existing statusline or force flag — install ACE statusline
+      settings.statusLine = { type: 'command', command: statuslineCommand };
+      log(`  ✓ Configured statusline`, colors.green);
+    } else if (isAceStatusline) {
+      // Already ACE statusline — update path
+      settings.statusLine = { type: 'command', command: statuslineCommand };
+      log(`  ✓ Updated statusline`, colors.green);
+    } else if (isInteractive) {
+      // Existing non-ACE statusline in interactive mode — ask user
+      const existingCmd = settings.statusLine.command || settings.statusLine.url || '(custom)';
+      log(`\n  ⚠ Existing statusline detected`, colors.yellow);
+      log(`  Current: ${existingCmd}`, colors.dim);
+      log(`\n  ACE statusline shows:`, colors.cyan);
+      log(`    • Model name`, colors.dim);
+      log(`    • Current task (from todo list)`, colors.dim);
+      log(`    • Context window usage (color-coded)`, colors.dim);
+      log(`    • Update notifications`, colors.dim);
+
+      const rl = createPrompt();
+      const choice = await ask(rl, '\n  What would you like to do?', [
+        { label: 'Keep existing statusline', value: 'keep' },
+        { label: 'Replace with ACE statusline', value: 'replace' },
+      ]);
+      rl.close();
+
+      if (choice === 'replace') {
+        settings.statusLine = { type: 'command', command: statuslineCommand };
+        log(`  ✓ Configured statusline`, colors.green);
+      } else {
+        log(`  ⚠ Skipping statusline (kept existing)`, colors.yellow);
+      }
+    } else {
+      // Non-interactive with existing statusline — skip
+      log(`  ⚠ Skipping statusline (already configured, use --force-statusline to replace)`, colors.yellow);
+    }
+
+    // Write settings
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  }
+
   // Show success message
   log(`\n${'═'.repeat(50)}`, colors.green);
   log(`  ACE installed successfully!`, colors.green + colors.bright);
   log(`${'═'.repeat(50)}`, colors.green);
 
   log(`\nInstalled locations:`, colors.cyan);
-  for (const { name, path: p } of installedPaths) {
-    log(`  ${name}: ${p}`, colors.dim);
+  for (const { name: runtimeName, path: p } of installedPaths) {
+    log(`  ${runtimeName}: ${p}`, colors.dim);
   }
 
   log(`\nInstalled structure:`, colors.cyan);
-  for (const { name, path: p } of installedPaths) {
+  for (const { path: p } of installedPaths) {
     log(`  ${p}/`, colors.dim);
     log(`    commands/ace/       Slash commands`, colors.dim);
     log(`    agents/             Agent definitions`, colors.dim);
+    log(`    hooks/              Statusline & update hooks`, colors.dim);
     log(`    ${ACE_DIR_NAME}/`, colors.dim);
     log(`      templates/        Project & artifact templates`, colors.dim);
     log(`      utils/            Formatting & utility guides`, colors.dim);

package/commands/ace/update.md

@@ -0,0 +1,54 @@
+---
+name: ace:update
+description: Update ACE to latest version
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>When statusline shows the update indicator</trigger>
+            <trigger>When user wants to check for or install ACE updates</trigger>
+        </runs-after>
+    </execution-time>
+
+    <input>
+        <parameters>
+            <required></required>
+            <optional></optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <update-workflow>@~/.claude/agile-context-engineering/workflows/update.xml</update-workflow>
+        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
+    </execution-context>
+
+    <output>
+        <objective>
+            Check for ACE updates, install if available.
+            Automatically detects local vs global installation and Claude vs Crush runtime.
+        </objective>
+    </output>
+
+    <process>
+        Execute the update workflow from
+        `@~/.claude/agile-context-engineering/workflows/update.xml` end-to-end.
+
+        The workflow handles all logic including:
+        1. Installation detection (local/global, Claude/Crush)
+        2. Latest version checking via npm
+        3. Version comparison
+        4. Clean install warning display
+        5. User confirmation
+        6. Update execution
+        7. Cache clearing and restart reminder
+    </process>
+
+</command>
+```

package/hooks/ace-check-update.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Check for ACE updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'ace-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(cwd, '.claude', 'agile-context-engineering', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'agile-context-engineering', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn detached process, windowsHide prevents console flash)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  let installed = '0.0.0';
+  try {
+    if (fs.existsSync(projectVersionFile)) {
+      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    } else if (fs.existsSync(globalVersionFile)) {
+      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    }
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view agile-context-engineering version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true
+});
+
+child.unref();

package/hooks/ace-statusline.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Claude Code Statusline - ACE Edition
+// Shows: update indicator | model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to 80% limit)
+    // Claude Code enforces an 80% context limit, so we scale to show 100% at that point
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const rawUsed = Math.max(0, Math.min(100, 100 - rem));
+      // Scale: 80% real usage = 100% displayed
+      const used = Math.min(100, Math.round((rawUsed / 80) * 100));
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+
+      // Color based on scaled usage
+      if (used < 63) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 81) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 95) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\u{1F480} ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {}
+    }
+
+    // ACE update available?
+    let aceUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'ace-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          aceUpdate = '\x1b[33m\u2B06 /ace:update\x1b[0m \u2502 ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${aceUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${aceUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agile-context-engineering",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "ACE - Agile Context Engineering: A spec-driven development system for Claude Code and Crush (formerly OpenCode) with Agile workflows",
   "main": "index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "bin",
     "commands",
     "agents",
+    "hooks",
     "agile-context-engineering"
   ],
   "scripts": {