agile-context-engineering 0.2.1 → 0.3.0

package/commands/ace/plan-feature.md

@@ -1,89 +1,89 @@
----
-name: ace:plan-feature
-description: Plan a feature through backlog-aware questioning, story decomposition, and guided feature specification
-argument-hint: "[feature-id] [optional: context='text or file with feature description prompt']"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Task
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-backlog — once the backlog exists, plan individual features</trigger>
-            <trigger>Anytime — to create or refine a feature and its story breakdown</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Product backlog exists and you want to break a feature into stories</condition>
-            <condition>Starting feature-level planning and need to decompose into stories</condition>
-            <condition>Refining an existing feature with updated acceptance criteria or scope</condition>
-            <condition>Adding a new feature to an existing epic</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-                <param name="feature-id" type="text">
-                    Feature identifier from the product backlog (e.g., F3, #78).
-                    If provided, locates existing feature for planning or refinement.
-                    If omitted, presents the backlog for selection or allows creating
-                    a new feature.
-                </param>
-                <param name="context" type="file | text">
-                    Feature description, acceptance criteria, user stories, or any
-                    context to seed the feature planning process. Will be absorbed and
-                    refined through questioning, not used as-is.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <plan-feature-workflow>@~/.claude/agile-context-engineering/workflows/plan-feature.xml</plan-feature-workflow>
-        <feature-template>@~/.claude/agile-context-engineering/templates/product/feature.xml</feature-template>
-        <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 the project environment, load the product backlog and epic context,
-            absorb any user-provided feature description, conduct deep questioning to
-            define feature scope and acceptance criteria, decompose the feature into
-            stories, and generate feature and story artifact files.
-            Optionally create GitHub issues if github-project.enabled=true.
-        </objective>
-
-        <artifacts>
-            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-feature_name>.md
-            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/<id-story_name>.md
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the plan-feature workflow from
-        `@~/.claude/agile-context-engineering/workflows/plan-feature.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:plan-story story-id` — Plan a story
-        - `/ace:plan-feature feature-id` — Plan another feature
-        - `/ace:help` — Check project initialization status
-    </next-steps>
-
-</command>
-```
+---
+name: ace:plan-feature
+description: Plan a feature through backlog-aware questioning, story decomposition, and guided feature specification
+argument-hint: "[feature-id] [optional: context='text or file with feature description prompt']"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-backlog — once the backlog exists, plan individual features</trigger>
+            <trigger>Anytime — to create or refine a feature and its story breakdown</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Product backlog exists and you want to break a feature into stories</condition>
+            <condition>Starting feature-level planning and need to decompose into stories</condition>
+            <condition>Refining an existing feature with updated acceptance criteria or scope</condition>
+            <condition>Adding a new feature to an existing epic</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="feature-id" type="text">
+                    Feature identifier from the product backlog (e.g., F3, #78).
+                    If provided, locates existing feature for planning or refinement.
+                    If omitted, presents the backlog for selection or allows creating
+                    a new feature.
+                </param>
+                <param name="context" type="file | text">
+                    Feature description, acceptance criteria, user stories, or any
+                    context to seed the feature planning process. Will be absorbed and
+                    refined through questioning, not used as-is.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <plan-feature-workflow>@~/.claude/agile-context-engineering/workflows/plan-feature.xml</plan-feature-workflow>
+        <feature-template>@~/.claude/agile-context-engineering/templates/product/feature.xml</feature-template>
+        <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 the project environment, load the product backlog and epic context,
+            absorb any user-provided feature description, conduct deep questioning to
+            define feature scope and acceptance criteria, decompose the feature into
+            stories, and generate feature and story artifact files.
+            Optionally create GitHub issues if github-project.enabled=true.
+        </objective>
+
+        <artifacts>
+            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-feature_name>.md
+            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/<id-story_name>.md
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the plan-feature workflow from
+        `@~/.claude/agile-context-engineering/workflows/plan-feature.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:plan-story story-id` — Plan a story
+        - `/ace:plan-feature feature-id` — Plan another feature
+        - `/ace:help` — Check project initialization status
+    </next-steps>
+
+</command>
+```

package/commands/ace/plan-story.md

@@ -1,7 +1,7 @@
 ---
 name: ace:plan-story
 description: Plan a story through deep questioning to create CRYSTAL-CLEAR acceptance criteria with ZERO assumptions, then dispatch wiki research, external analysis, integration analysis, and technical solution design
-argument-hint: "story=<file-path|github-url> [external-codebase=<source-path|github-url>] [external-docs=<weblink|filepath>]"
+argument-hint: "story=<file-path|github-url> [external-codebase=<source-path|github-url>] [external-docs=<weblink|filepath>] [lib-docs=<weblinks-and-filepaths>]"
 allowed-tools:
   - Read
   - Bash
@@ -57,6 +57,15 @@ allowed-tools:
                     Only used when external-codebase is also provided.
                     Provides supplementary context for external analysis.
                 </param>
+                <param name="lib-docs" type="weblinks and/or filepaths">
+                    Space-separated string of weblinks and/or file paths to library or API documentation.
+                    These are injected into the story's Relevant Wiki section as a
+                    `### Library Documentation` subsection after pass 2 completes,
+                    so that passes 4-5 (integration analysis, technical solution) can
+                    reference them when designing the implementation.
+                    Useful for third-party libraries, SDK docs, or API references
+                    that inform how the story should be built.
+                </param>
             </optional>
         </parameters>
     </input>
@@ -128,6 +137,11 @@ allowed-tools:
           external-codebase=src/external/lightweight-charts/ \
           external-docs=https://tradingview.github.io/lightweight-charts/
 
+        # With library documentation references
+        /ace:plan-story \
+          story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
+          lib-docs="https://docs.some-lib.io/api src/vendor/some-lib/README.md"
+
         # With just an issue number (uses configured repo)
         /ace:plan-story story=#95
         ```

package/commands/ace/review-story.md

@@ -1,109 +1,109 @@
----
-name: ace:review-story
-description: Standalone code review — performs 3-level artifact verification, anti-pattern detection, coding standards enforcement, and tech debt discovery against a story's implementation
-argument-hint: "story=<file-path|github-url>"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:execute-story — to re-run code review after manual changes</trigger>
-            <trigger>Anytime — to review a story implementation standalone</trigger>
-        </runs-after>
-        <use-when>
-            <condition>A story has been implemented and needs code review</condition>
-            <condition>Re-checking after manual changes post-execution</condition>
-            <condition>Verifying stories implemented outside ACE</condition>
-            <condition>Pre-merge quality gate</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a fully-planned story markdown file
-                      (must have AC + Technical Solution sections)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    The story MUST have Acceptance Criteria and Technical Solution.
-                </param>
-            </required>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <review-story-workflow>@~/.claude/agile-context-engineering/workflows/review-story.xml</review-story-workflow>
-        <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Review a story's implementation directly (the session IS the reviewer):
-            1. Load story context (AC, Technical Solution, Out of Scope)
-            2. Identify changed/created files related to the story
-            3. Run 3-level artifact verification (EXISTS → SUBSTANTIVE → WIRED)
-            4. Detect anti-patterns (dead code, stubs, TODOs, hardcoded values)
-            5. Enforce coding standards (mandatory, blocker-level)
-            6. Check AC coverage (all Gherkin scenarios implemented)
-            7. Discover pre-existing tech debt in touched files
-            8. Report results with structured format
-        </objective>
-
-        <artifacts>
-            No files modified — this command is read-only.
-            Outputs a structured review report to the conversation.
-        </artifacts>
-    </output>
-
-    <process>
-        For this command use the `ace-code-reviewer` agent
-        that's specialized in code review.
-
-        Execute the review-story workflow from
-        `@~/.claude/agile-context-engineering/workflows/review-story.xml` end-to-end.
-
-        **CRITICAL REQUIREMENTS:**
-        - Story MUST have Acceptance Criteria — STOP if missing
-        - Story MUST have Technical Solution — STOP if missing
-        - This is a READ-ONLY command — do NOT modify any code
-        - Coding standards violations are BLOCKERS, not warnings
-        - Dead code and backwards-compatible shims must be flagged for DELETION
-    </process>
-
-    <example-usage>
-        ```
-        # Review a story from a file path
-        /ace:review-story \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-        # Review from a GitHub issue
-        /ace:review-story \
-          story=https://github.com/owner/repo/issues/95
-
-        # With just an issue number
-        /ace:review-story story=#95
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:execute-story story=...` — Re-execute to fix reported issues
-        - `/ace:review-story story=...` — Re-run review after fixes
-        - `/ace:help` — Check project status
-    </next-steps>
-
-</command>
-```
+---
+name: ace:review-story
+description: Standalone code review — performs 3-level artifact verification, anti-pattern detection, coding standards enforcement, and tech debt discovery against a story's implementation
+argument-hint: "story=<file-path|github-url>"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:execute-story — to re-run code review after manual changes</trigger>
+            <trigger>Anytime — to review a story implementation standalone</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A story has been implemented and needs code review</condition>
+            <condition>Re-checking after manual changes post-execution</condition>
+            <condition>Verifying stories implemented outside ACE</condition>
+            <condition>Pre-merge quality gate</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="story" type="file | github-url">
+                    Story source — can be either:
+                    - **File path**: Path to a fully-planned story markdown file
+                      (must have AC + Technical Solution sections)
+                    - **GitHub URL or issue number**: GitHub story reference
+                    Must be a valid, accessible file or GitHub issue.
+                    The story MUST have Acceptance Criteria and Technical Solution.
+                </param>
+            </required>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <review-story-workflow>@~/.claude/agile-context-engineering/workflows/review-story.xml</review-story-workflow>
+        <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
+        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
+    </execution-context>
+
+    <output>
+        <objective>
+            Review a story's implementation directly (the session IS the reviewer):
+            1. Load story context (AC, Technical Solution, Out of Scope)
+            2. Identify changed/created files related to the story
+            3. Run 3-level artifact verification (EXISTS → SUBSTANTIVE → WIRED)
+            4. Detect anti-patterns (dead code, stubs, TODOs, hardcoded values)
+            5. Enforce coding standards (mandatory, blocker-level)
+            6. Check AC coverage (all Gherkin scenarios implemented)
+            7. Discover pre-existing tech debt in touched files
+            8. Report results with structured format
+        </objective>
+
+        <artifacts>
+            No files modified — this command is read-only.
+            Outputs a structured review report to the conversation.
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-code-reviewer` agent
+        that's specialized in code review.
+
+        Execute the review-story workflow from
+        `@~/.claude/agile-context-engineering/workflows/review-story.xml` end-to-end.
+
+        **CRITICAL REQUIREMENTS:**
+        - Story MUST have Acceptance Criteria — STOP if missing
+        - Story MUST have Technical Solution — STOP if missing
+        - This is a READ-ONLY command — do NOT modify any code
+        - Coding standards violations are BLOCKERS, not warnings
+        - Dead code and backwards-compatible shims must be flagged for DELETION
+    </process>
+
+    <example-usage>
+        ```
+        # Review a story from a file path
+        /ace:review-story \
+          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
+
+        # Review from a GitHub issue
+        /ace:review-story \
+          story=https://github.com/owner/repo/issues/95
+
+        # With just an issue number
+        /ace:review-story story=#95
+        ```
+    </example-usage>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:execute-story story=...` — Re-execute to fix reported issues
+        - `/ace:review-story story=...` — Re-run review after fixes
+        - `/ace:help` — Check project status
+    </next-steps>
+
+</command>
+```

package/commands/ace/update.md

@@ -0,0 +1,56 @@
+---
+name: ace:update
+description: Update ACE to latest version with changelog display
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+  - WebFetch
+---
+
+```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, and display what changed.
+            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. Changelog fetching and display
+        5. Clean install warning display
+        6. User confirmation
+        7. Update execution
+        8. 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
+  }
+});