agile-context-engineering 0.2.2 → 0.3.0

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

@@ -1,207 +1,238 @@
-<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>
+<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

@@ -318,6 +318,14 @@ function installForRuntime(runtime, scope, packageDir) {
   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;
 }
 

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>