agile-context-engineering 0.2.1 → 0.3.0

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

@@ -0,0 +1,238 @@
+<workflow>
+
+    <purpose>
+        Check for ACE updates via npm, display changelog for versions between installed and latest,
+        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: FETCH AND SHOW CHANGELOG                                 -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="show-changelog-and-confirm" order="4">
+            If update is available, fetch the changelog and show what's new BEFORE updating.
+
+            1. **Try local changelog first** — check if CHANGELOG.md exists in the installation:
+
+               For SCOPE=local: `./.claude/agile-context-engineering/CHANGELOG.md`
+               For SCOPE=global: `~/.claude/agile-context-engineering/CHANGELOG.md`
+               (substitute `.opencode` for Crush runtime)
+
+               If found, read it directly.
+
+            2. **Fall back to GitHub** — if local file not found, use WebFetch to fetch:
+               `https://raw.githubusercontent.com/Quantarcane/ACE/main/CHANGELOG.md`
+
+               If fetch fails, skip changelog display and proceed without it.
+
+            3. **Extract relevant entries** — from the fetched/read content, extract all
+               changelog sections between the installed version and the latest version.
+
+               Look for lines matching `## [X.Y.Z]` and extract everything from
+               `## [{latest_version}]` down to (but not including) `## [{installed_version}]`.
+
+            4. **Display preview and ask for confirmation:**
+
+            ```
+            ## ACE Update Available
+
+            **Installed:** {installed_version}
+            **Latest:** {latest_version}
+
+            ### What's New
+            ────────────────────────────────────────────────────────────
+
+            {extracted changelog entries}
+
+            ────────────────────────────────────────────────────────────
+
+            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 (changelog was already shown in confirmation step):
+
+            ```
+            ============================================================
+              ACE Updated: v{old} -> v{new}
+            ============================================================
+
+            Restart Claude Code to pick up the new commands.
+
+            View full changelog: https://github.com/Quantarcane/ACE/blob/main/CHANGELOG.md
+            ```
+        </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>Changelog fetched and displayed BEFORE update</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,34 @@ 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');
+
+  // Copy CHANGELOG.md
+  const changelogSrc = path.join(packageDir, 'CHANGELOG.md');
+  const changelogDest = path.join(acePath, 'CHANGELOG.md');
+  if (fs.existsSync(changelogSrc)) {
+    fs.copyFileSync(changelogSrc, changelogDest);
+    log(`  ✓ CHANGELOG.md installed`, colors.green);
+  }
+
   return basePath;
 }
 
@@ -355,21 +403,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/execute-story.md

@@ -55,6 +55,7 @@ allowed-tools:
     <execution-context>
         <execute-story-workflow>@~/.claude/agile-context-engineering/workflows/execute-story.xml</execute-story-workflow>
         <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
+        <walkthrough-template>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough-template>
         <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
         <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
     </execution-context>

package/commands/ace/help.md

@@ -1,93 +1,93 @@
----
-name: ace:help
-description: Check project initialization status and suggest next steps
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>At any time — to check which ACE documents exist and what to do next</trigger>
-            <trigger>At the start of a new project — to see the initialization checklist</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Starting a new project and want to see what needs to be set up</condition>
-            <condition>Returning to a project and want to check initialization status</condition>
-            <condition>Unsure which ACE command to run next</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <help-workflow>@~/.claude/agile-context-engineering/workflows/help.xml</help-workflow>
-        <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Detect which ACE documents exist (product vision, system architecture, system structure,
-            coding standards, testing framework). Display a status dashboard showing what's done
-            and what's missing. Suggest the next command to run based on gaps.
-        </objective>
-
-        <artifacts>
-            - .ace/settings.json (created on first run if missing)
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the help workflow from
-        `@~/.claude/agile-context-engineering/workflows/help.xml` end-to-end.
-        This is a lightweight state-check and routing workflow.
-
-        CRITICAL MANDATORY STEP — DO NOT SKIP:
-        Before displaying the status dashboard, you MUST run:
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js sync-agent-teams --raw
-        ```
-        Then you MUST use `AskUserQuestion` to ask the user whether they want to
-        enable or disable Claude Code Agent Teams (experimental feature).
-        This step is NOT optional. You MUST present this question every time.
-
-        When the user chooses to enable or disable Agent Teams, you MUST run the
-        bash command — NEVER directly edit .ace/settings.json or .claude/settings.json:
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams true
-        ```
-        or
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams false
-        ```
-        The write-agent-teams command updates BOTH .ace/settings.json AND .claude/settings.json.
-        Direct file edits will cause the two files to go out of sync.
-    </process>
-
-    <next-steps>
-        **Specialized commands for each document:**
-        - `/ace:plan-product-vision` — Create or update the product vision
-        - `/ace:map-system` — Map codebase structure, architecture, and testing framework
-        - `/ace:init-coding-standards` — Generate tailored coding standards
-    </next-steps>
-
-</command>
-```
+---
+name: ace:help
+description: Check project initialization status and suggest next steps
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>At any time — to check which ACE documents exist and what to do next</trigger>
+            <trigger>At the start of a new project — to see the initialization checklist</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Starting a new project and want to see what needs to be set up</condition>
+            <condition>Returning to a project and want to check initialization status</condition>
+            <condition>Unsure which ACE command to run next</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <help-workflow>@~/.claude/agile-context-engineering/workflows/help.xml</help-workflow>
+        <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
+        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
+    </execution-context>
+
+    <output>
+        <objective>
+            Detect which ACE documents exist (product vision, system architecture, system structure,
+            coding standards, testing framework). Display a status dashboard showing what's done
+            and what's missing. Suggest the next command to run based on gaps.
+        </objective>
+
+        <artifacts>
+            - .ace/settings.json (created on first run if missing)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the help workflow from
+        `@~/.claude/agile-context-engineering/workflows/help.xml` end-to-end.
+        This is a lightweight state-check and routing workflow.
+
+        CRITICAL MANDATORY STEP — DO NOT SKIP:
+        Before displaying the status dashboard, you MUST run:
+        ```bash
+        node ~/.claude/agile-context-engineering/src/ace-tools.js sync-agent-teams --raw
+        ```
+        Then you MUST use `AskUserQuestion` to ask the user whether they want to
+        enable or disable Claude Code Agent Teams (experimental feature).
+        This step is NOT optional. You MUST present this question every time.
+
+        When the user chooses to enable or disable Agent Teams, you MUST run the
+        bash command — NEVER directly edit .ace/settings.json or .claude/settings.json:
+        ```bash
+        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams true
+        ```
+        or
+        ```bash
+        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams false
+        ```
+        The write-agent-teams command updates BOTH .ace/settings.json AND .claude/settings.json.
+        Direct file edits will cause the two files to go out of sync.
+    </process>
+
+    <next-steps>
+        **Specialized commands for each document:**
+        - `/ace:plan-product-vision` — Create or update the product vision
+        - `/ace:map-system` — Map codebase structure, architecture, and testing framework
+        - `/ace:init-coding-standards` — Generate tailored coding standards
+    </next-steps>
+
+</command>
+```