agile-context-engineering 0.2.2 → 0.3.0

package/commands/ace/map-subsystem.md

@@ -1,138 +1,140 @@
----
-name: ace:map-subsystem
-description: Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/
-argument-hint: "subsystem='src/api' (or subsystem name) existing-docs=comma separated paths | directory"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:map-system — drill into individual subsystems</trigger>
-            <trigger>Anytime to refresh an existing subsystem's wiki documents</trigger>
-            <trigger>When a new subsystem is added and needs to be documented</trigger>
-        </runs-after>
-        <use-when>
-            <condition>A subsystem has not yet been documented in `.docs/wiki/subsystems/`</condition>
-            <condition>An existing subsystem's docs are stale after a significant refactor</condition>
-            <condition>You want a deep-dive view of a specific subsystem's internals (components, flows, data)</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="subsystem" type="path | text">
-                    Path to the subsystem (e.g., `src/api`) or its name.
-                    If not provided, pause execution and ask the user for it.
-                    If provided but ambiguous, or not found in the codebase, ask clarifying questions.
-                </param>
-            </required>
-
-            <optional>
-                <param name="existing-docs" type="comma-separated paths or directories">
-                    Pre-existing documentation relevant to this subsystem. Accepts file paths,
-                    directory paths, or a mix of both. When a directory is provided, recursively
-                    discover all files within it (including nested subdirectories).
-                    All resolved file paths are passed through to every map-story invocation
-                    (file mode) alongside any per-module docs discovered during module-discovery.
-                    Use this when the caller already knows about documentation that should
-                    inform knowledge-doc generation.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <map-subsystem-workflow>@~/.claude/agile-context-engineering/workflows/map-subsystem.xml</map-subsystem-workflow>
-        <subsystem-structure-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-structure.xml</subsystem-structure-template>
-        <subsystem-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-architecture.xml</subsystem-architecture-template>
-        <module-discovery-template>@~/.claude/agile-context-engineering/templates/wiki/module-discovery.xml</module-discovery-template>
-        <map-story-workflow>@~/.claude/agile-context-engineering/workflows/map-story.xml</map-story-workflow>
-        <system-template>@~/.claude/agile-context-engineering/templates/wiki/system.xml</system-template>
-        <pattern-template>@~/.claude/agile-context-engineering/templates/wiki/pattern.xml</pattern-template>
-        <cross-cutting-template>@~/.claude/agile-context-engineering/templates/wiki/system-cross-cutting.xml</cross-cutting-template>
-        <guide-template>@~/.claude/agile-context-engineering/templates/wiki/guide.xml</guide-template>
-        <decisions-template>@~/.claude/agile-context-engineering/templates/wiki/decizions.xml</decisions-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>
-            Resolve the target subsystem, load system-wide wiki context, and determine whether
-            to create, update, or recreate per-subsystem wiki documents. Then:
-
-            1. Spawn ace-wiki-mapper agents to produce structure and architecture documents.
-            2. Update system-structure.md if this subsystem was not previously listed there.
-            3. Update the subsystem responsibility matrix in system-architecture.md if missing.
-            4. Run module discovery — trace E2E flows, identify patterns, find cross-cutting
-               concerns by reading actual source code. Produce module-discovery.md artifact.
-            5. For EACH discovered module, run map-story in file mode to create or update
-               knowledge documentation (systems/, patterns/, cross-cutting/, guides/, decisions/).
-        </objective>
-
-        <artifacts>
-            - .docs/wiki/subsystems/[subsystem-name]/structure.md
-            - .docs/wiki/subsystems/[subsystem-name]/architecture.md
-            - .docs/wiki/subsystems/[subsystem-name]/systems/*.md (created/updated by map-story)
-            - .docs/wiki/subsystems/[subsystem-name]/patterns/*.md (created/updated by map-story)
-            - .docs/wiki/subsystems/[subsystem-name]/cross-cutting/*.md (created/updated by map-story)
-            - .docs/wiki/subsystems/[subsystem-name]/guides/*.md (created/updated by map-story)
-            - .docs/wiki/subsystems/[subsystem-name]/decisions/*.md (created/updated by map-story)
-            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/module-discovery.md
-            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/existing-docs-inventory.md (if existing-docs directory provided)
-            - .docs/wiki/system-wide/system-structure.md (subsystem entry added if new)
-            - .docs/wiki/system-wide/system-architecture.md (subsystem responsibility matrix updated if missing)
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the map-subsystem workflow from
-        `@~/.claude/agile-context-engineering/workflows/map-subsystem.xml` end-to-end.
-        Preserve all workflow gates (validation, user questions, commits).
-
-        The workflow has 13 steps:
-        1-5: Setup, context loading, subsystem resolution, document triage, directory creation
-        6-8: Structure + architecture agents (parallel) + collect results
-        9: Update system-wide docs (system-structure.md, system-architecture.md)
-        10: Module discovery (3 parallel discovery agents + 1 synthesis agent)
-        11: Knowledge documentation — run map-story for EACH discovered module (sequential)
-        12: Verify and commit all documents
-        13: Completion report
-
-        Steps 10-11 are CRITICAL — they produce the knowledge docs (systems/, patterns/,
-        cross-cutting/, guides/, decisions/) that AI agents need for future implementations.
-        Do NOT skip them.
-    </process>
-
-     <next-steps>
-        **After this command, `/clear` first for a fresh context window, then:**
-
-        For each subsystem found and defined in the Subsystem Responsibility Matrix,
-        suggest a `/ace:map-subsystem` command. Example:
-        - `/ace:map-subsystem subsystem="src/api"` — Map the API subsystem
-        - `/ace:map-subsystem subsystem="src/auth"` — Map the Auth subsystem
-        - `/ace:map-subsystem subsystem="src/db"` — Map the DB subsystem
-        (list one per subsystem discovered during this command's execution)
-
-        Also suggest:
-        - `/ace:init-coding-standards` — Define prescriptive coding standards
-        - `/ace:help` — Check project initialization status and next steps
-        - Review and edit files in `.docs/wiki/system-wide/` anytime
-    </next-steps>
-
-</command>
-```
+---
+name: ace:map-subsystem
+description: Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/
+argument-hint: "subsystem='src/api' (or subsystem name) existing-docs=comma separated paths | directory"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:map-system — drill into individual subsystems</trigger>
+            <trigger>Anytime to refresh an existing subsystem's wiki documents</trigger>
+            <trigger>When a new subsystem is added and needs to be documented</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A subsystem has not yet been documented in `.docs/wiki/subsystems/`</condition>
+            <condition>An existing subsystem's docs are stale after a significant refactor</condition>
+            <condition>You want a deep-dive view of a specific subsystem's internals (components, flows, data)</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="subsystem" type="path | text">
+                    Path to the subsystem (e.g., `src/api`) or its name.
+                    If not provided, pause execution and ask the user for it.
+                    If provided but ambiguous, or not found in the codebase, ask clarifying questions.
+                </param>
+            </required>
+
+            <optional>
+                <param name="existing-docs" type="comma-separated paths or directories">
+                    Pre-existing documentation relevant to this subsystem. Accepts file paths,
+                    directory paths, or a mix of both. When a directory is provided, recursively
+                    discover all files within it (including nested subdirectories).
+                    All resolved file paths are passed through to every map-story invocation
+                    (file mode) alongside any per-module docs discovered during module-discovery.
+                    Use this when the caller already knows about documentation that should
+                    inform knowledge-doc generation.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <map-subsystem-workflow>@~/.claude/agile-context-engineering/workflows/map-subsystem.xml</map-subsystem-workflow>
+        <subsystem-structure-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-structure.xml</subsystem-structure-template>
+        <subsystem-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-architecture.xml</subsystem-architecture-template>
+        <module-discovery-template>@~/.claude/agile-context-engineering/templates/wiki/module-discovery.xml</module-discovery-template>
+        <map-story-workflow>@~/.claude/agile-context-engineering/workflows/map-story.xml</map-story-workflow>
+        <system-template>@~/.claude/agile-context-engineering/templates/wiki/system.xml</system-template>
+        <pattern-template>@~/.claude/agile-context-engineering/templates/wiki/pattern.xml</pattern-template>
+        <cross-cutting-template>@~/.claude/agile-context-engineering/templates/wiki/system-cross-cutting.xml</cross-cutting-template>
+        <guide-template>@~/.claude/agile-context-engineering/templates/wiki/guide.xml</guide-template>
+        <walkthrough-template>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough-template>
+        <decisions-template>@~/.claude/agile-context-engineering/templates/wiki/decizions.xml</decisions-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>
+            Resolve the target subsystem, load system-wide wiki context, and determine whether
+            to create, update, or recreate per-subsystem wiki documents. Then:
+
+            1. Spawn ace-wiki-mapper agents to produce structure and architecture documents.
+            2. Update system-structure.md if this subsystem was not previously listed there.
+            3. Update the subsystem responsibility matrix in system-architecture.md if missing.
+            4. Run module discovery — trace E2E flows, identify patterns, find cross-cutting
+               concerns by reading actual source code. Produce module-discovery.md artifact.
+            5. For EACH discovered module, run map-story in file mode to create or update
+               knowledge documentation (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/).
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/subsystems/[subsystem-name]/structure.md
+            - .docs/wiki/subsystems/[subsystem-name]/architecture.md
+            - .docs/wiki/subsystems/[subsystem-name]/systems/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/patterns/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/cross-cutting/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/guides/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/walkthroughs/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/decisions/*.md (created/updated by map-story)
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/module-discovery.md
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/existing-docs-inventory.md (if existing-docs directory provided)
+            - .docs/wiki/system-wide/system-structure.md (subsystem entry added if new)
+            - .docs/wiki/system-wide/system-architecture.md (subsystem responsibility matrix updated if missing)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-subsystem workflow from
+        `@~/.claude/agile-context-engineering/workflows/map-subsystem.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+
+        The workflow has 13 steps:
+        1-5: Setup, context loading, subsystem resolution, document triage, directory creation
+        6-8: Structure + architecture agents (parallel) + collect results
+        9: Update system-wide docs (system-structure.md, system-architecture.md)
+        10: Module discovery (3 parallel discovery agents + 1 synthesis agent)
+        11: Knowledge documentation — run map-story for EACH discovered module (sequential)
+        12: Verify and commit all documents
+        13: Completion report
+
+        Steps 10-11 are CRITICAL — they produce the knowledge docs (systems/, patterns/,
+        cross-cutting/, guides/, walkthroughs/, decisions/) that AI agents need for future implementations.
+        Do NOT skip them.
+    </process>
+
+     <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+
+        For each subsystem found and defined in the Subsystem Responsibility Matrix,
+        suggest a `/ace:map-subsystem` command. Example:
+        - `/ace:map-subsystem subsystem="src/api"` — Map the API subsystem
+        - `/ace:map-subsystem subsystem="src/auth"` — Map the Auth subsystem
+        - `/ace:map-subsystem subsystem="src/db"` — Map the DB subsystem
+        (list one per subsystem discovered during this command's execution)
+
+        Also suggest:
+        - `/ace:init-coding-standards` — Define prescriptive coding standards
+        - `/ace:help` — Check project initialization status and next steps
+        - Review and edit files in `.docs/wiki/system-wide/` anytime
+    </next-steps>
+
+</command>
+```

package/commands/ace/map-system.md

@@ -1,92 +1,92 @@
----
-name: ace:map-system
-description: Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/
-argument-hint: "[optional: references='existing artifacts and documents to be considered alongside the codebase']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>Before /ace:help (brownfield codebases) — understand existing code first</trigger>
-            <trigger>After /ace:help (greenfield codebases) — document architecture decisions</trigger>
-            <trigger>Anytime to refresh system-wide wiki documents</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Onboarding to an existing codebase (brownfield — analyzes code automatically)</condition>
-            <condition>Starting a new project and need to document architecture decisions (greenfield — interviews you)</condition>
-            <condition>System-wide documents are stale or missing</condition>
-            <condition>After major refactoring that changed subsystem boundaries or tech stack</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-                <param name="references" type="file | text">
-                    Existing architecture docs, ADRs, or design notes
-                    to consider alongside the codebase analysis. Absorbed before analysis begins.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <map-system-workflow>@~/.claude/agile-context-engineering/workflows/map-system.xml</map-system-workflow>
-        <system-structure-template>@~/.claude/agile-context-engineering/templates/wiki/system-structure.xml</system-structure-template>
-        <system-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml</system-architecture-template>
-        <testing-framework-template>@~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml</testing-framework-template>
-        <wiki-readme-template>@~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml</wiki-readme-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 brownfield/greenfield status and existing wiki state. For each system-wide
-            document (structure, architecture, testing), determine whether to create, update,
-            recreate, scaffold, or skip. Spawn ace-wiki-mapper agents to produce documents.
-            For greenfield architecture, conduct deep questioning before generating.
-            Add CLAUDE.md instructions to keep wiki current with future code changes.
-        </objective>
-
-        <artifacts>
-            - .docs/wiki/wiki-readme.md (created if not already present)
-            - .docs/wiki/system-wide/system-structure.md
-            - .docs/wiki/system-wide/system-architecture.md
-            - .docs/wiki/system-wide/testing-framework.md
-            - CLAUDE.md (wiki maintenance instructions appended)
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the map-system workflow from
-        `@~/.claude/agile-context-engineering/workflows/map-system.xml` end-to-end.
-        Preserve all workflow gates (validation, user questions, commits).
-    </process>
-
-    <next-steps>
-        **After this command, `/clear` first for a fresh context window, then:**
-        - `/ace:map-subsystems` — Map individual subsystem internals (structure, dependencies)
-        - `/ace:init-coding-standards` — Define prescriptive coding standards
-        - `/ace:help` — Check project initialization status and next steps
-        - Review and edit files in `.docs/wiki/system-wide/` anytime
-    </next-steps>
-
-</command>
-```
+---
+name: ace:map-system
+description: Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/
+argument-hint: "[optional: references='existing artifacts and documents to be considered alongside the codebase']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>Before /ace:help (brownfield codebases) — understand existing code first</trigger>
+            <trigger>After /ace:help (greenfield codebases) — document architecture decisions</trigger>
+            <trigger>Anytime to refresh system-wide wiki documents</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Onboarding to an existing codebase (brownfield — analyzes code automatically)</condition>
+            <condition>Starting a new project and need to document architecture decisions (greenfield — interviews you)</condition>
+            <condition>System-wide documents are stale or missing</condition>
+            <condition>After major refactoring that changed subsystem boundaries or tech stack</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="references" type="file | text">
+                    Existing architecture docs, ADRs, or design notes
+                    to consider alongside the codebase analysis. Absorbed before analysis begins.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <map-system-workflow>@~/.claude/agile-context-engineering/workflows/map-system.xml</map-system-workflow>
+        <system-structure-template>@~/.claude/agile-context-engineering/templates/wiki/system-structure.xml</system-structure-template>
+        <system-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml</system-architecture-template>
+        <testing-framework-template>@~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml</testing-framework-template>
+        <wiki-readme-template>@~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml</wiki-readme-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 brownfield/greenfield status and existing wiki state. For each system-wide
+            document (structure, architecture, testing), determine whether to create, update,
+            recreate, scaffold, or skip. Spawn ace-wiki-mapper agents to produce documents.
+            For greenfield architecture, conduct deep questioning before generating.
+            Add CLAUDE.md instructions to keep wiki current with future code changes.
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/wiki-readme.md (created if not already present)
+            - .docs/wiki/system-wide/system-structure.md
+            - .docs/wiki/system-wide/system-architecture.md
+            - .docs/wiki/system-wide/testing-framework.md
+            - CLAUDE.md (wiki maintenance instructions appended)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-system workflow from
+        `@~/.claude/agile-context-engineering/workflows/map-system.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+        - `/ace:map-subsystems` — Map individual subsystem internals (structure, dependencies)
+        - `/ace:init-coding-standards` — Define prescriptive coding standards
+        - `/ace:help` — Check project initialization status and next steps
+        - Review and edit files in `.docs/wiki/system-wide/` anytime
+    </next-steps>
+
+</command>
+```

package/commands/ace/map-walkthrough.md

@@ -0,0 +1,127 @@
+---
+name: ace:map-walkthrough
+description: Create deep tutorial-style flow walkthroughs in .docs/wiki/subsystems/[name]/walkthroughs/
+argument-hint: "flow='tick data from bybit websocket to timescaledb' subsystem='data-ingestion' emphasis-frameworks='SignalR,Redis Streams'"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - LSP
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:map-subsystem — to create deep walkthroughs for complex flows</trigger>
+            <trigger>Anytime a complex multi-class flow needs human-readable documentation</trigger>
+            <trigger>When onboarding new developers who need to understand specific flows</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A flow spans 3+ classes across multiple architectural layers</condition>
+            <condition>External frameworks/libraries are involved that need explanation</condition>
+            <condition>An intern reading the code alone would not understand what's happening</condition>
+            <condition>A system doc would need paragraphs of explanation with code snippets</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="flow" type="text">
+                    Natural language description of the end-to-end flow — WHERE it starts
+                    and WHERE it ends. The agent finds the entry point, follows every call
+                    through the entire code, and traces it to the exit point.
+
+                    E.g.:
+                    - "tick data from bybit websocket to timescaledb"
+                    - "user message from SignalR hub until LLM response is sent back"
+                    - "order placement from API endpoint to payment confirmation"
+
+                    If not provided, pause and ask the user.
+                </param>
+                <param name="subsystem" type="path | text">
+                    Subsystem where the walkthrough wiki file is placed.
+                    The flow itself may span MULTIPLE subsystems — the agent follows
+                    the code wherever it goes. This parameter only determines the
+                    wiki location: `.docs/wiki/subsystems/[subsystem]/walkthroughs/`.
+                    If not provided, pause and ask the user.
+                </param>
+            </required>
+
+            <optional>
+                <param name="emphasis-frameworks" type="csv">
+                    Comma-separated frameworks/libraries/APIs/SDKs that should receive deep
+                    explanation throughout the walkthrough. When specified:
+                    - EVERY step touching the framework gets a framework info box
+                    - ALL code interacting with the framework is shown and explained
+                    - The Framework Concepts Reference table becomes MANDATORY
+
+                    Each entry is EITHER:
+                    - A name (agent researches via WebSearch/context7):
+                      "SignalR" or "SignalR,EF Core"
+                    - A file path or URL to documentation (agent reads the page, follows
+                      internal links to find pages covering the specific concepts used in
+                      the code, and infers the framework name from content):
+                      "https://learn.microsoft.com/aspnet/signalr/overview" or "docs/signalr-guide.md"
+                    - A mix of both:
+                      "SignalR,docs/custom-redis-wrapper.md,EF Core"
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <map-walkthrough-workflow>@~/.claude/agile-context-engineering/workflows/map-walkthrough.xml</map-walkthrough-workflow>
+        <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>
+
+    <output>
+        <objective>
+            Create or update a deep tutorial-style walkthrough that traces a flow end-to-end.
+
+            The agent reads the flow description, finds the entry point in the codebase,
+            then follows EVERY SINGLE CALL through the entire code — handler to service
+            to repository to database (or whatever the flow touches) — using LSP and code
+            reading. It discovers all files automatically, extracts emphasis framework
+            usages from the actual code, researches those specific concepts, and writes
+            the walkthrough with real code snippets and framework info boxes.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/walkthroughs/[flow-name].md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-wiki-mapper` agent
+        that's specialized in wiki exploration and documentation writing.
+
+        Execute the map-walkthrough workflow from
+        `@~/.claude/agile-context-engineering/workflows/map-walkthrough.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        <step>/clear first for a fresh context window</step>
+        <step>/ace:map-walkthrough — create another walkthrough</step>
+        <step>/ace:map-subsystem [subsystem] — map or refresh an entire subsystem</step>
+        <step>Review and edit files in .docs/wiki/subsystems/[subsystem-name]/walkthroughs/</step>
+    </next-steps>
+
+</command>
+```