agile-context-engineering 0.5.0 → 0.5.1

package/skills/plan-story/SKILL.md

@@ -8,109 +8,132 @@ model: opus
 effort: high
 ---
 
-# Plan Story
-
-Orchestrate story specification through deep questioning and multi-pass research.
-
-## When to Use
-
-- After `/ace:plan-feature` — when a feature's story breakdown exists with stub story files
-- To create or refine a story specification from a description or GitHub issue
-- When a story stub needs formal INVEST-compliant specification
-- When an existing story needs refinement due to scope changes or AC gaps
-- When you have a new story idea (text or no input) and need it placed in the backlog
-
-## Input
-
-### Optional
-
-- **`story`** — Story source:
-  - **File path**: Path to a markdown file containing the story seed (typically from plan-feature, or any markdown with a description)
-  - **GitHub URL or issue number**: e.g., `story=#95` or `story=https://github.com/owner/repo/issues/95`
-  - When omitted, enters "new story" mode and guides the user through backlog placement.
-
-- **`text`** — Inline story description to seed the planning session. Used when no story file exists yet — the text becomes the initial description and the workflow asks where in the backlog this story belongs. Ignored if `story` is provided.
-
-- **`external-codebase`** — Path or GitHub repo to an external system to analyze. Triggers pass 3 automatically.
-
-- **`external-docs`** — Link or filepath to external system documentation. Only used with external-codebase.
-
-- **`lib-docs`** — Space-separated weblinks and/or filepaths to library/API documentation. Injected into the Relevant Wiki section after pass 2.
-
 ## Environment Context (preprocessed)
 
 !`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
 
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **Story template**: Read [story-template.xml](story-template.xml) — output format for the story specification
-- **Questioning guide**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml` — deep questioning techniques
-- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` — ACE output formatting rules
-
-## Process
-
-Use the `ace-product-owner` agent for requirements gathering, deep questioning, and story specification.
-
-The Environment Context above contains the preprocessed INIT JSON — use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
-
-Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
-
-**Context Window Protection:**
-Passes 2-5 run as background agents. Each agent writes output directly to files.
-The orchestrator MUST NOT call TaskOutput on any background agent.
-Only track when each pass finishes to start the next one.
-
-**Pass execution order:**
-Pass 2 + Pass 3 (if applicable) → wait → Pass 4 → wait → Pass 5 → wait → done
-
-## Artifacts
-
-```
-.ace/artifacts/product/<epic>/<feature>/<story>/
-├── <story>.md                    # Story specification (passes 1, 2, 5)
-├── external-analysis.md          # OPTIONAL (pass 3)
-└── integration-analysis.md       # Integration analysis (pass 4)
-```
-
-## Example Usage
-
-```
-# New story from inline text — workflow asks for backlog placement
-/ace:plan-story text="User can reset their password via email link"
-
-# New story with no input — workflow asks title then placement
-/ace:plan-story
-
-# From a plan-feature stub file
-/ace:plan-story story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-# From a loose markdown file (no ACE structure yet — triggers placement flow)
-/ace:plan-story story=notes/password-reset-idea.md
-
-# From a GitHub issue
-/ace:plan-story story=https://github.com/owner/repo/issues/95
-
-# With external system analysis
-/ace:plan-story \
-  story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
-  external-codebase=src/external/lightweight-charts/ \
-  external-docs=https://tradingview.github.io/lightweight-charts/
-
-# With library documentation
-/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
-/ace:plan-story story=#95
-```
-
-## Next Steps
-
-- `/ace:execute-story story=...` — Execute the story implementation
-- `/ace:plan-story story=...` — Plan the next story in the feature
-- `/ace:verify-story story=...` — Verify a completed story
-- `/ace:help` — Check project initialization status
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/story-template.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-feature — once a feature's story breakdown exists with stub story files</trigger>
+            <trigger>Anytime — to create or refine a story specification from a description or GitHub issue</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A story stub exists (from plan-feature) and needs formal specification</condition>
+            <condition>A GitHub issue describes work that needs INVEST-compliant acceptance criteria</condition>
+            <condition>An existing story needs refinement — scope changed, AC gaps found</condition>
+            <condition>You want to create a complete story specification from any text description</condition>
+            <condition>You have a new story idea (text or no input) and need it placed in the backlog</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="story" type="file | github-url">
+                    Story source — can be either:
+                    - **File path**: Path to an existing markdown file containing the story seed
+                      (typically a stub from plan-feature, or any markdown with a description)
+                    - **GitHub URL or issue number**: GitHub story reference
+                    When omitted, the workflow enters "new story" mode and guides the user
+                    through backlog placement before proceeding to specification.
+                    If provided but invalid, stop and prompt the user.
+                </param>
+                <param name="text" type="text">
+                    Inline story description to seed the planning session.
+                    Used when no story file exists yet — the text becomes the initial description
+                    and the workflow asks where in the backlog this story belongs.
+                    Ignored if `story` is provided.
+                </param>
+                <param name="external-codebase" type="filepath | github-url">
+                    Path or GitHub repo to an external industry-standard system to analyze.
+                    When provided, pass 3 (external analysis) runs automatically.
+                    When NOT provided, the user is offered the option to provide it or skip.
+                </param>
+                <param name="external-docs" type="weblink | filepath">
+                    Link or path to external system documentation.
+                    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>
+
+    <execution-context>
+        <!-- All supporting files are auto-loaded in the Supporting Resources section above.
+             The model does NOT need to Read these files — they are already in context. -->
+    </execution-context>
+
+    <output>
+        <objective>
+            Take a story seed (stub file, GitHub issue, or any text description) and produce
+            a COMPLETE story specification through deep questioning that ensures:
+            - ZERO ASSUMPTIONS — every behavior is explicitly specified
+            - CRYSTAL-CLEAR acceptance criteria with exact triggers, preconditions, outcomes
+            - INVEST compliance — Independent, Negotiable, Valuable, Estimable, Small, Testable
+            - Gherkin scenarios cover happy paths, edge cases, AND error paths
+
+            After story requirements are defined (pass 1), dispatch research passes 2-5
+            as background agents:
+            - Pass 2: Wiki research (updates story file with Relevant Wiki section)
+            - Pass 3: External analysis (OPTIONAL — creates external-analysis.md)
+            - Pass 4: Integration analysis (creates integration-analysis.md)
+            - Pass 5: Technical solution (appends to story file)
+
+            Each research pass writes directly to disk. The orchestrator context window
+            contains ONLY story requirements — research outputs do NOT flow back.
+        </objective>
+
+        <artifacts>
+            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/&lt;id-story_name&gt;.md
+            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/external-analysis.md (OPTIONAL)
+            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/integration-analysis.md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-product-owner` agent
+        that's specialized in requirements gathering, deep questioning, and story specification.
+
+        Execute the plan-story workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+
+        **CRITICAL — Context Window Protection:**
+        Passes 2-5 run as background agents. Each agent writes output directly to files.
+        The orchestrator MUST NOT call TaskOutput on any background agent.
+        The orchestrator only needs to know when each pass finishes to start the next one.
+
+        **Pass execution order:**
+        Pass 2 + Pass 3 (if applicable) → wait → Pass 4 → wait → Pass 5 → wait → done
+    </process>
+
+    <example-usage>
+        ```

package/skills/plan-story/script.js

@@ -19,7 +19,7 @@ const path = require('path');
 const {
   loadConfig, pathExists, safeReadFile, generateSlug, resolveModel,
   detectBrownfieldStatus, loadSettings, execCommand,
-  output, error, parseKeyValueArgs,
+  output, error, runSkillScript,
 } = require('../../shared/lib/ace-core');
 
 const {
@@ -32,44 +32,25 @@ const { syncStory, resolveFields, createIssue } = require('../../shared/lib/ace-
 
 // ─── CLI Dispatch ────────────────────────────────────────────────────────────
 
-const cwd = process.cwd();
-const args = process.argv.slice(2);
-const raw = args.includes('--raw');
-const cmd = args[0];
-
-switch (cmd) {
-  case 'init':
-    cmdInit(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'update-state':
-    updateState(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'sync-github':
-    syncStory(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'resolve-model': {
-    const agentType = args[1];
+runSkillScript({
+  init: cmdInit,
+  'update-state': (cwd, raw, args) => updateState(cwd, raw, args),
+  'sync-github': (cwd, raw, args) => syncStory(cwd, raw, args),
+  'resolve-model': (cwd, raw, args, parsed) => {
+    const agentType = parsed._positional || args[0];
     if (!agentType) error('resolve-model requires agent-type argument');
     const model = resolveModel(cwd, agentType);
     output({ model, agent: agentType }, raw, model);
-    break;
-  }
-  case 'generate-slug': {
-    const text = args.slice(1).filter(a => a !== '--raw').join(' ');
+  },
+  'generate-slug': (cwd, raw, args, parsed) => {
+    const text = parsed._positional || args.join(' ');
     if (!text) error('generate-slug requires text argument');
     const slug = generateSlug(text);
     output({ slug }, raw, slug);
-    break;
-  }
-  case 'resolve-fields':
-    resolveFields(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'create-issue':
-    createIssue(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  default:
-    error(`Unknown command: ${cmd}\nAvailable: init, update-state, sync-github, resolve-model, generate-slug, resolve-fields, create-issue`);
-}
+  },
+  'resolve-fields': (cwd, raw, args) => resolveFields(cwd, raw, args),
+  'create-issue': (cwd, raw, args) => createIssue(cwd, raw, args),
+});
 
 // ─── Init: Plan Story ────────────────────────────────────────────────────────
 
@@ -87,7 +68,7 @@ switch (cmd) {
  * initArgs: array of arguments — either a single positional path/URL,
  *           or key=value pairs (story=X text=Y)
  */
-function cmdInit(cwd, raw, initArgs) {
+function cmdInit(cwd, raw, args, parsed) {
   const config = loadConfig(cwd);
   const brownfield = detectBrownfieldStatus(cwd);
 
@@ -116,21 +97,9 @@ function cmdInit(cwd, raw, initArgs) {
   }
   const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
 
-  // ── Parse input: support both positional and key=value forms ──
-  // Positional: script.js init path/to/story.md
-  // Key-value:  script.js init story=path/to/story.md text="some description"
-  const hasKeyValue = initArgs.some(a => a.includes('='));
-  let resolvedStoryParam = null;
-  let textParam = null;
-
-  if (hasKeyValue) {
-    const kvArgs = parseKeyValueArgs(initArgs);
-    resolvedStoryParam = kvArgs.story || null;
-    textParam = kvArgs.text || null;
-  } else if (initArgs.length > 0) {
-    // Positional: treat entire arg list as the story param
-    resolvedStoryParam = initArgs.join(' ');
-  }
+  // ── Parse input from shared parsed args ──
+  const resolvedStoryParam = parsed.story || parsed._positional || null;
+  const textParam = parsed.text || null;
 
   // ── Base result (shared across all modes) ──
   const baseResult = {

package/skills/plan-story/story-template.xml

@@ -125,7 +125,11 @@
 
                  Minimum coverage: happy path + at least one edge case + at least one error path.
                  Each scenario must be independent — no scenario depends on another's state.
-                 If more than 6-8 scenarios are needed, the story is likely too large — split it. -->
+                 If more than 6-8 scenarios are needed, the story is likely too large — split it.
+
+                 FORMAT: Use ### H3 headers for scenario names and **bold** for Given/When/Then.
+                 Do NOT wrap scenarios in fenced code blocks (no ```gherkin).
+                 This format renders cleanly in both markdown files and GitHub issue bodies. -->
 
             ### Scenario: [Short descriptive name]
 
@@ -322,6 +326,9 @@
 
             Bad: "Given the user clicks login" (action, not state)
             Good: "Given the user is on the login page"
+
+            **Formatting**: Use `### Scenario:` H3 headers and `**Given**`/`**When**`/`**Then**` bold markdown.
+            Do NOT use fenced code blocks (no ```gherkin). The markdown format renders in GitHub issues.
         </guideline>
 
         <guideline name="story-sizing">

package/skills/plan-story/workflow.xml

@@ -25,7 +25,7 @@
     </purpose>
 
     <mandatory-context>
-        Read all supporting resource files listed in the skill before starting.
+        All supporting resource files are auto-loaded in the skill prompt above. Do NOT re-read them.
         Also read any document or text passed as parameter ($ARGUMENTS).
     </mandatory-context>
 
@@ -808,6 +808,13 @@
 
         <step name="dispatch-research" order="8">
 
+            **YOU (the product owner) DO NOT WRITE passes 2-5 yourself.**
+            Your job in this step is ONLY to dispatch background agents and wait for them.
+            You MUST NOT write the `## Relevant Wiki` section — the wiki-mapper agent does that.
+            You MUST NOT write the `## Technical Solution` section — the technical-architect agent does that.
+            You MUST NOT create any files not specified below (no wiki-research.md, no notes.md).
+            If you skip a dispatch or write these sections yourself, the workflow has FAILED.
+
             Display:
             ```
             ┌──────────────────────────────────────────────────┐
@@ -1130,6 +1137,15 @@
             ```
               +  Pass 5 complete. Technical solution appended to story file.
             ```
+
+            <!-- ── 8i: Verification — confirm all passes ran ────────────── -->
+
+            Read the story file and verify it contains BOTH:
+            1. A `## Relevant Wiki` section with actual wiki references (not just a placeholder)
+            2. A `## Technical Solution` section with actual technical design (not just a placeholder or reference to another file)
+
+            If either section is missing or still a placeholder, the pass dispatch FAILED.
+            Display an error and re-dispatch the missing pass(es).
         </step>
 
         <!-- ══════════════════════════════════════════════════════════════════ -->

package/skills/research-external-solution/SKILL.md

@@ -1,107 +1,120 @@
----
-name: research-external-solution
-description: COMPREHENSIVE, IN-DEPTH, CODE-LEVEL Analysis of User Story Implementation in External Repository
-argument-hint: "story=<file-path|github-url> external-codebase=<source-path|github-url> [external-docs=<weblink|filepath>]"
-disable-model-invocation: true
-allowed-tools: Read, Bash, Write, AskUserQuestion, Glob, Grep, WebFetch
-model: opus
-effort: max
-context: fork
-agent: ace-code-discovery-analyst
----
-
-# Research External Solution
-
-Perform a COMPREHENSIVE, IN-DEPTH, CODE-LEVEL ANALYSIS of how a specific story's functionality is implemented in an external reference system.
-
-## When to Use
-
-- After `/ace:plan-story` -- once story requirements (pass 1-2) are complete
-- Anytime a story references an external system or reference implementation
-- When a story or feature references an external codebase to learn from
-- When you need to understand how an industry-standard system implements specific functionality
-- When you want to extract algorithms, patterns, and implementation details from reference code
-
-## Input
-
-### Required
-
-- **`story`** -- Story source:
-  - **File path**: Path to a markdown file containing the story (from plan-story command)
-  - **GitHub URL or issue number**: GitHub story reference
-  - Must be a valid, accessible file or GitHub issue.
-  - Contains the user story and acceptance criteria that define what to analyze.
-  - **Requirements for the analysis are extracted from this story.**
-  - If not valid, stop and prompt the user.
-
-- **`external-codebase`** -- Path or GitHub repo to the external industry-standard system to analyze:
-  - If local path: Confirm folder exists and contains source code
-  - If GitHub URL: Verify repository accessibility
-
-### Optional
-
-- **`external-docs`** -- Link or path to external system documentation:
-  - If weblink: Verify URL is accessible
-  - If filepath: Verify file exists and is readable
-  - **PREFER using context7 MCP server** when installed -- it provides up-to-date library documentation automatically.
-
-## Environment Context (preprocessed)
-
-!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
-- **External solution template**: Read [external-solution-template.xml](external-solution-template.xml) -- output format for the analysis
-- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
-
-## Process
-
-Use the `ace-code-discovery-analyst` agent for code discovery.
-
-The Environment Context above contains the preprocessed INIT JSON -- use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
-
-Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
-
-This is NOT a high-level overview -- it's a DEEP DIVE into:
-- EXACT code implementations with line-by-line analysis
-- COMPLETE algorithms and formulas extracted verbatim from code
-- ALL design patterns with actual code examples
-- EVERY file, function, and constant involved in the story
-- FULL execution paths traced 5+ levels deep minimum
-
-All output is written ONLY to the analysis file -- no GitHub updates, no modifications to the story file.
-
-## Artifacts
-
-```
-.ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/external-analysis.md
-```
-
-## Example Usage
-
-```
-# Example with file path story and GitHub external repo
-/ace:research-external-solution \
-  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md \
-  external-codebase=https://github.com/tradingview/lightweight-charts \
-  external-docs=https://tradingview.github.io/lightweight-charts/
-
-# Example with GitHub story and local external repo
-/ace:research-external-solution \
-  story=https://github.com/owner/repo/issues/83 \
-  external-codebase=src/external/lightweight-charts/
-
-# Example with context7 (no external-docs needed)
-/ace:research-external-solution \
-  story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
-  external-codebase=https://github.com/tradingview/lightweight-charts
-```
-
-## Next Steps
-
-- Continue with story refinement -- integration analysis (pass 4) and technical solution (pass 5)
-- `/ace:research-external-solution story=... external-codebase=...` -- Analyze another story
-- `/ace:help` -- Check project initialization status
+---
+name: research-external-solution
+description: COMPREHENSIVE, IN-DEPTH, CODE-LEVEL Analysis of User Story Implementation in External Repository
+argument-hint: "story=<file-path|github-url> external-codebase=<source-path|github-url> [external-docs=<weblink|filepath>]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, AskUserQuestion, Glob, Grep, WebFetch
+model: opus
+effort: max
+context: fork
+agent: ace-code-discovery-analyst
+---
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/external-solution-template.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-story — once story requirements (pass 1-2) are complete</trigger>
+            <trigger>Anytime — when a story references an external system or reference implementation</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Story or feature references an external codebase to learn from</condition>
+            <condition>Need to understand how an industry-standard system implements specific functionality</condition>
+            <condition>Want to extract algorithms, patterns, and implementation details from reference code</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 markdown file containing the story (from plan-story command)
+                    - **GitHub URL or issue number**: GitHub story reference
+                    Must be a valid, accessible file or GitHub issue.
+                    Contains the user story and acceptance criteria that define what to analyze.
+                    **Requirements for the analysis are extracted from this story.**
+                    If not valid, stop and prompt the user.
+                </param>
+                <param name="external-codebase" type="filepath | github-url">
+                    Path or GitHub repo to the external industry-standard system to analyze.
+                    - If local path: Confirm folder exists and contains source code
+                    - If GitHub URL: Verify repository accessibility
+                    The external repository to analyze for implementation patterns,
+                    algorithms, formulas, and architectural decisions.
+                    If not valid, stop and prompt the user.
+                </param>
+            </required>
+
+            <optional>
+                <param name="external-docs" type="weblink | filepath">
+                    Link or path to external industry-standard system documentation.
+                    Provides supplementary context when available.
+                    - If weblink: Verify URL is accessible
+                    - If filepath: Verify file exists and is readable
+                    **PREFER using context7 MCP server** when installed — it provides
+                    up-to-date library documentation automatically. Use context7 whenever
+                    the external system is a known library/framework.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <!-- All supporting files are auto-loaded in the Supporting Resources section above.
+             The model does NOT need to Read these files — they are already in context. -->
+    </execution-context>
+
+    <output>
+        <objective>
+            Perform a COMPREHENSIVE, IN-DEPTH, CODE-LEVEL ANALYSIS of how a specific
+            story's functionality is implemented in an external reference system.
+            This is NOT a high-level overview — it's a DEEP DIVE into:
+            - EXACT code implementations with line-by-line analysis
+            - COMPLETE algorithms and formulas extracted verbatim from code
+            - ALL design patterns with actual code examples
+            - EVERY file, function, and constant involved in the story
+            - FULL execution paths traced 5+ levels deep minimum
+
+            The analysis ensures our implementation:
+            - Follows established patterns and best practices (with code proof)
+            - Uses exact algorithms and formulas (copied from their code)
+            - Maintains compatibility with industry standards (matching their APIs)
+
+            All output is written ONLY to the analysis file — no GitHub updates,
+            no modifications to the story file. This artifact is consumed by
+            pass 5 (technical solution) of the story specification pipeline.
+        </objective>
+
+        <artifacts>
+            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/external-analysis.md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-code-discovery-analyst` agent
+        that's specialized in code discovery.
+
+        Execute the research-external-solution workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <example-usage>
+        ```