agile-context-engineering 0.2.2 → 0.5.0

package/skills/init-coding-standards/script.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * init-coding-standards skill script — Entry point for ace-tools operations
+ * needed by the init-coding-standards skill.
+ *
+ * Subcommands:
+ *   init [args]        Environment detection for init-coding-standards workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const {
+  loadConfig, pathExists,
+  detectBrownfieldStatus, output, error,
+} = require('../../shared/lib/ace-core');
+
+// ─── 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;
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init`);
+}
+
+// ─── Init: Coding Standards ─────────────────────────────────────────────────
+
+function cmdInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const result = {
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Brownfield detection
+    ...brownfield,
+
+    // Existing coding standards
+    has_coding_standards: pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md'),
+    wiki_dir_exists: pathExists(cwd, '.docs/wiki/system-wide'),
+
+    // Existing wiki context (useful for cross-referencing)
+    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
+    has_system_structure: pathExists(cwd, '.docs/wiki/system-wide/system-structure.md'),
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+  };
+
+  output(result, raw);
+}

package/skills/init-coding-standards/script.test.js

@@ -0,0 +1,70 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+describe('init-coding-standards script', () => {
+  it('errors on unknown command', () => {
+    assert.throws(() => {
+      execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+    });
+  });
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('init returns valid JSON', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.ok(typeof result === 'object');
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.has_coding_standards, 'boolean');
+      assert.strictEqual(typeof result.wiki_dir_exists, 'boolean');
+      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
+      assert.strictEqual(typeof result.has_system_structure, 'boolean');
+    });
+
+    it('returns brownfield detection fields', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+});

package/{agile-context-engineering/workflows/init-coding-standards.xml → skills/init-coding-standards/workflow.xml}

@@ -23,18 +23,13 @@
         <step name="setup" order="1">
             **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
 
-            ```bash
-            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init coding-standards)
-            ```
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
 
-            Parse JSON for: `commit_docs`, `is_brownfield`, `is_greenfield`, `has_existing_code`,
+            Parse INIT JSON for: `commit_docs`, `is_brownfield`, `is_greenfield`, `has_existing_code`,
             `has_package_file`, `has_coding_standards`, `wiki_dir_exists`, `has_system_architecture`,
             `has_system_structure`, `has_git`.
 
-            Also resolve the mapper model for spawning the wiki-mapper agent:
-            ```bash
-            MAPPER_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-wiki-mapper --raw)
-            ```
+            MAPPER_MODEL is available from INIT.mapper_model — do NOT re-run resolve-model.
 
             Display stage banner:
 
@@ -275,7 +270,7 @@
 
                 **Instructions:**
                 1. Read the coding standards template:
-                   ~/.claude/agile-context-engineering/templates/wiki/coding-standards.xml
+                   ${CLAUDE_SKILL_DIR}/coding-standards-template.xml
                 2. Assemble the document following the template's assembly guidelines:
                    - ALWAYS include universal-standards (adapt placeholders to the project's language)
                    - Include paradigm modules based on context brief (OOP, functional, systems, or multiple)

package/skills/map-cross-cutting/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: map-cross-cutting
+description: Create or update a cross-cutting concern doc in .docs/wiki/subsystems/[name]/cross-cutting/ — shared infrastructure spanning multiple systems
+argument-hint: "text='Event system used across all drawing components' subsystem='qarc-charts-v2' commits=3"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+# Map Cross-Cutting
+
+Create or update a cross-cutting concern document for shared infrastructure spanning multiple systems.
+
+## When to Use
+
+- When a cross-cutting concern needs dedicated documentation
+- After implementing shared infrastructure that multiple systems depend on
+- When agents need to understand how to register with or plug into shared concerns
+- A concern spans multiple domain systems within a subsystem
+- Multiple systems register with or depend on this infrastructure
+- An agent needs to know WHERE to register and HOW to interact with the concern
+
+## Input
+
+### Required
+
+- **`text`** (text) — Natural language description of the cross-cutting concern to document. Describes WHAT the concern addresses, which systems it spans. E.g.: "Event system used across all drawing components", "Dependency injection container and service registration", "Authentication middleware and authorization pipeline". If not provided, pause and ask the user.
+
+- **`subsystem`** (path | text) — Subsystem where this cross-cutting doc belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/cross-cutting/`. If not provided, pause and ask the user.
+
+### Optional
+
+- **`story-context`** (path | GitHub issue) — Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue number/URL. Provides context about a story that introduced or modified this cross-cutting concern. When not provided, the agent discovers the concern from codebase analysis.
+
+- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding what was built/changed. As a number: analyze the N most recent commits (e.g., commits=3). As commit SHAs: analyze specific commits (e.g., commits='abc123,def456'). When not provided: search the codebase directly using the text description to find all registration points, usages, and integration points.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Cross-cutting template**: Read [system-cross-cutting.xml](system-cross-cutting.xml) — output format for the cross-cutting concern doc
+- **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-wiki-mapper` agent that's specialized in wiki exploration and documentation writing.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, user questions, commits).
+
+**Objective:** Create or update a cross-cutting concern document that describes shared infrastructure spanning multiple systems — how it works, registration/setup points, usage patterns, current registrations, integration points, and gotchas. The document an AI agent reads to understand how to register with or plug into shared concerns when implementing new features.
+
+## Artifacts
+
+```
+.docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-name].md
+```
+
+## Example Usage
+
+```
+# Basic cross-cutting concern
+/ace:map-cross-cutting text='Event system used across all drawing components' subsystem='qarc-charts-v2'
+
+# With recent commits for context
+/ace:map-cross-cutting text='Dependency injection container' subsystem='api' commits=3
+
+# With story context
+/ace:map-cross-cutting text='Authentication middleware' subsystem='api' story-context='.ace/artifacts/product/e1-auth/f1-middleware/s1-setup/s1-setup.md'
+```
+
+## Next Steps
+
+- `/clear` first for a fresh context window
+- `/ace:map-cross-cutting` — create another cross-cutting concern doc
+- `/ace:map-sys-doc` — document a system that uses this concern
+- `/ace:map-guide` — create a guide that includes registration steps
+- Review file at `.docs/wiki/subsystems/[subsystem-name]/cross-cutting/`

package/skills/map-cross-cutting/workflow.xml

@@ -0,0 +1,330 @@
+<workflow>
+
+    <purpose>
+        Create or update a cross-cutting concern document in
+        `.docs/wiki/subsystems/[subsystem-name]/cross-cutting/`.
+
+        A cross-cutting doc describes shared infrastructure or mechanisms that multiple
+        domain systems depend on — DI registration, event systems, factory/registry,
+        serialization, error handling, auth middleware, caching.
+
+        The document an AI agent reads to understand how to register with or plug into
+        shared concerns.
+
+        This workflow is executed directly — NO sub-agents are spawned.
+        The executing agent does everything: finding registration points, tracing
+        usages, and writing the document.
+    </purpose>
+
+    <mandatory-context>
+        Read all files referenced by the invoking command's execution-context before starting.
+        Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
+    </mandatory-context>
+
+    <process>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 1: SETUP AND VALIDATE                                        -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="setup" order="1">
+
+            <substep order="1.1" name="display-banner">
+                Display stage banner:
+
+                ```
+                ╔══════════════════════════════════════════════════╗
+                ║  ACE > Map Cross-Cutting                           ║
+                ╚══════════════════════════════════════════════════╝
+                ```
+            </substep>
+
+            <substep order="1.2" name="parse-and-validate">
+                Parse $ARGUMENTS for: `text`, `subsystem`, `story-context`, `commits`.
+
+                **If `text` is missing:** Ask the user:
+                - header: "Cross-Cutting"
+                - question: "Describe the cross-cutting concern to document — what shared infrastructure spans multiple systems?\nE.g., 'Event system used across all drawing components'"
+
+                **If `subsystem` is missing:** Ask the user:
+                - header: "Cross-Cutting"
+                - question: "Which subsystem does this concern belong to?"
+            </substep>
+
+            <substep order="1.3" name="resolve-subsystem">
+                Resolve the subsystem. Check if `.docs/wiki/subsystems/[subsystem-name]/` exists.
+
+                **If not found:**
+                ```
+                  !  No wiki found for subsystem "[subsystem]".
+                     Run /ace:map-subsystem first to create the subsystem wiki.
+                ```
+                Exit.
+
+                Ensure cross-cutting directory exists:
+                ```bash
+                mkdir -p .docs/wiki/subsystems/[subsystem_name]/cross-cutting
+                ```
+            </substep>
+
+            Display:
+            ```
+              i  Concern: [text description]
+                 Subsystem: [subsystem-name]
+                 Story context: [path/issue, or "none"]
+                 Commits: [value, or "search codebase directly"]
+            ```
+
+            Continue to step 2.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 2: CHECK FOR EXISTING CROSS-CUTTING DOC                      -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="check-existing" order="2">
+
+            Scan for existing cross-cutting docs:
+
+            ```
+            Glob(pattern='*.md', path='.docs/wiki/subsystems/[subsystem_name]/cross-cutting')
+            ```
+
+            **If existing cross-cutting docs found:**
+            Read their titles and overview sections. Check if any covers the same
+            or overlapping concern.
+
+            **If overlap detected:**
+            Use AskUserQuestion:
+            - header: "Cross-Cutting"
+            - question: "An existing cross-cutting doc may cover a similar concern:\n\n- `[existing-file]`: [title]\n\nShould I update the existing doc or create a new one?"
+            - options:
+              - "Update existing" — set MODE = update, set TARGET_FILE = existing path
+              - "Create new" — set MODE = create
+
+            **If no overlap or no existing docs:** Set MODE = create.
+
+            **If MODE = create:**
+            Derive file name from concern name in kebab-case.
+            Set TARGET_FILE = `.docs/wiki/subsystems/[subsystem_name]/cross-cutting/[concern-name].md`
+
+            Continue to step 3.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 3: GATHER CODE CONTEXT                                       -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="gather-context" order="3">
+
+            <substep order="3.1" name="read-story-context">
+                <variant condition="story-context is a path">
+                    Read all markdown files in the story artifacts folder.
+                    Extract: what shared infrastructure was built/changed.
+                </variant>
+
+                <variant condition="story-context is a GitHub issue">
+                    ```bash
+                    gh issue view [issue-number] --json title,body,labels,comments
+                    ```
+                    Extract context about the cross-cutting concern.
+                </variant>
+
+                <variant condition="no story-context">
+                    Skip — discover concern from codebase only.
+                </variant>
+            </substep>
+
+            <substep order="3.2" name="find-concern-code">
+                <variant condition="commits provided as number N">
+                    ```bash
+                    git diff --name-only HEAD~[N]..HEAD
+                    ```
+                    Filter to files within the subsystem. Read each file.
+                    Then search for all other usages/registrations of this concern.
+                </variant>
+
+                <variant condition="commits provided as SHAs">
+                    ```bash
+                    git diff --name-only [first-sha]^..[last-sha]
+                    ```
+                    Filter to files within the subsystem. Read each file.
+                    Then search for all other usages/registrations.
+                </variant>
+
+                <variant condition="no commits — search codebase directly">
+                    Use the `text` description to find the cross-cutting concern:
+
+                    1. Read the subsystem's structure.md and architecture.md for orientation
+                    2. Grep for keywords from the text description (event, registry, factory,
+                       container, middleware, etc.)
+                    3. Find the core infrastructure files (the concern itself)
+                    4. Find ALL registration points (where systems plug in)
+                    5. Find ALL usages (how consuming code interacts)
+                    6. Read each file to understand the mechanism
+                </variant>
+            </substep>
+
+            <substep order="3.3" name="analyze-concern">
+                From the code, understand:
+
+                1. **How It Works**: The mechanism/pattern (event dispatch, DI resolution, etc.)
+                2. **Registration / Setup**: WHERE and HOW components register
+                3. **Usage**: How consuming code interacts with this concern
+                4. **Current Registrations**: Complete list of everything registered
+                5. **Integration Points**: Which systems depend on this concern
+                6. **Gotchas**: Registration order, naming conventions, timing issues
+
+                Build a complete mental model of the concern.
+            </substep>
+
+            Continue to step 4.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 4: WRITE THE CROSS-CUTTING DOC                               -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="write-doc" order="4">
+
+            Read ALL existing wiki docs under `.docs/wiki/subsystems/[subsystem_name]/`
+            for cross-referencing in Integration Points.
+
+            Follow the system-cross-cutting template structure exactly.
+
+            <substep order="4.1" name="write-overview">
+                - Title: "# [Cross-Cutting Concern]"
+                - Overview: ONE paragraph — what the concern addresses, why it exists
+            </substep>
+
+            <substep order="4.2" name="write-how-it-works">
+                Numbered steps explaining the mechanism.
+                Reference actual code locations — not theoretical descriptions.
+                If the mechanism has a flow (event dispatching, DI resolution),
+                show a mermaid sequence diagram.
+            </substep>
+
+            <substep order="4.3" name="write-registration">
+                The MOST CRITICAL section for AI agents.
+                List every registration point with exact file paths.
+                Show the registration pattern (inline code only if non-obvious).
+            </substep>
+
+            <substep order="4.4" name="write-usage">
+                How consuming code interacts with this concern.
+                Inline code snippet ONLY if usage pattern is non-obvious.
+                If straightforward (inject via constructor), a one-liner suffices.
+            </substep>
+
+            <substep order="4.5" name="write-current-registrations">
+                Complete list of everything currently registered/using this concern.
+                Agent uses this to verify consistency of new registrations.
+            </substep>
+
+            <substep order="4.6" name="write-integration-and-gotchas">
+                - Integration Points: cross-reference with markdown links to system docs
+                - Gotchas: registration order, naming conventions, initialization timing,
+                  anything that silently fails if done wrong
+            </substep>
+
+            <substep order="4.7" name="write-or-update">
+                **If MODE = create:** Write the complete document to TARGET_FILE.
+                **If MODE = update:** Read the existing doc, add new registrations,
+                update mechanism if changed, add new gotchas. Write to TARGET_FILE.
+            </substep>
+
+            Continue to step 5.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5: VERIFY, COMMIT, AND REPORT                               -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="verify-and-report" order="5">
+
+            <substep order="5.1" name="quality-check">
+                Re-read TARGET_FILE and verify:
+
+                <verification-checklist>
+                    <check>50+ lines of substantial content</check>
+                    <check>Overview present (ONE paragraph)</check>
+                    <check>"How It Works" has numbered steps with code references</check>
+                    <check>"Registration / Setup" lists ALL registration points with exact file paths</check>
+                    <check>"Current Registrations" lists ALL known registrations</check>
+                    <check>"Integration Points" cross-references system docs with markdown links</check>
+                    <check>"Gotchas" section present with practical warnings</check>
+                    <check>Code references use `file:Symbol` format, not line numbers</check>
+                    <check>If mechanism has a flow, mermaid diagram present</check>
+                    <check>No filler phrases, no generic advice</check>
+                    <check>No ASCII arrows for flows (all mermaid)</check>
+                </verification-checklist>
+
+                Fix any failures by editing the document directly.
+            </substep>
+
+            <substep order="5.2" name="security-scan">
+                ```
+                Grep(
+                    pattern="(sk-[a-zA-Z0-9]{20,}|sk_live_|sk_test_|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|-----BEGIN.*PRIVATE KEY)",
+                    path="[TARGET_FILE]",
+                    output_mode="content"
+                )
+                ```
+
+                <variant condition="matches found">SECRETS_FOUND — alert user, do NOT commit.</variant>
+                <variant condition="no matches">CLEAN.</variant>
+            </substep>
+
+            <substep order="5.3" name="commit">
+                ```bash
+                git add [TARGET_FILE]
+                git commit -m "docs([subsystem_name]): add cross-cutting — [concern-name]"
+                ```
+            </substep>
+
+            <substep order="5.4" name="report">
+                Display:
+
+                ```
+                ╔══════════════════════════════════════════════════╗
+                ║  ACE > Map Cross-Cutting > Complete                ║
+                ╚══════════════════════════════════════════════════╝
+
+                  +  [TARGET_FILE] ([line count] lines)
+
+                     Concern: [text description]
+                     Registrations found: [count]
+                     Integration points: [count]
+                     Gotchas: [count]
+
+                  Next > /clear first for a fresh context window, then:
+
+                         /ace:map-cross-cutting — create another cross-cutting doc
+                         /ace:map-sys-doc — document a system that uses this concern
+                         /ace:map-guide — create a guide with registration steps
+                         Review file at [TARGET_FILE]
+                ```
+            </substep>
+
+            End workflow.
+        </step>
+
+    </process>
+
+    <success_criteria>
+        <criterion>Concern description parsed and subsystem validated</criterion>
+        <criterion>Core infrastructure files discovered (from commits or codebase search)</criterion>
+        <criterion>All registration points found and documented</criterion>
+        <criterion>All current registrations listed</criterion>
+        <criterion>Existing cross-cutting docs checked to avoid duplication (create vs update)</criterion>
+        <criterion>Cross-cutting doc follows template structure from system-cross-cutting.xml</criterion>
+        <criterion>Registration / Setup section lists exact file paths</criterion>
+        <criterion>Integration Points cross-reference system docs with markdown links</criterion>
+        <criterion>Gotchas section present with practical warnings</criterion>
+        <criterion>Code references use file:Symbol format, no line numbers</criterion>
+        <criterion>If mechanism has a flow, mermaid diagram present</criterion>
+        <criterion>No filler, no generic advice, no pseudocode</criterion>
+        <criterion>Security scan passed, document committed</criterion>
+    </success_criteria>
+
+</workflow>

package/skills/map-guide/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: map-guide
+description: Create or update a step-by-step guide in .docs/wiki/subsystems/[name]/guides/ — recipes for common implementation tasks
+argument-hint: "text='How to add a new drawing tool' subsystem='qarc-charts-v2' commits=3"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+# Map Guide
+
+Create or update a step-by-step guide — recipes for common implementation tasks.
+
+## When to Use
+
+- When a recurring implementation task needs a step-by-step recipe
+- After discovering a repeatable process that combines multiple patterns/systems
+- When onboarding developers who need to perform common tasks
+- A task is done repeatedly (add new endpoint, add new tool, add new entity)
+- The task spans multiple files, registrations, and configuration steps
+- An agent following the guide can complete the task end-to-end without guessing
+
+## Input
+
+### Required
+
+- **`text`** (text) — Natural language description of the guide to create. Describes the recurring task and what the guide should teach. E.g.: "How to add a new drawing tool", "How to add a new CRUD endpoint with validation", "How to add a new indicator to the chart". If not provided, pause and ask the user.
+
+- **`subsystem`** (path | text) — Subsystem where this guide belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/guides/`. If not provided, pause and ask the user.
+
+### Optional
+
+- **`story-context`** (path | GitHub issue) — Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue number/URL. Provides context about a specific implementation that exemplifies the task this guide describes. When not provided, the agent discovers the recipe from codebase patterns.
+
+- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding an example implementation. As a number: analyze the N most recent commits (e.g., commits=3). As commit SHAs: analyze specific commits (e.g., commits='abc123,def456'). When not provided: search the codebase directly to find existing implementations and derive the recipe from them.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Guide template**: Read [guide.xml](guide.xml) — output format for the guide
+- **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-wiki-mapper` agent that's specialized in wiki exploration and documentation writing.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, user questions, commits).
+
+**Objective:** Create or update a step-by-step guide that combines knowledge from multiple systems, patterns, and cross-cutting concerns into one actionable recipe. Includes prerequisites, numbered ordered steps with "copy from" references, verification checklist, and common mistakes. The document an AI agent follows when performing a recurring task end-to-end.
+
+## Artifacts
+
+```
+.docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
+```
+
+## Example Usage
+
+```
+# Basic guide
+/ace:map-guide text='How to add a new drawing tool' subsystem='qarc-charts-v2'
+
+# With recent commits as example
+/ace:map-guide text='How to add a new CRUD endpoint with validation' subsystem='api' commits=3
+
+# With story context as example implementation
+/ace:map-guide text='How to add a new indicator to the chart' subsystem='qarc-charts-v2' story-context='.ace/artifacts/product/e2-charts/f1-indicators/s1-rsi/s1-rsi.md'
+```
+
+## Next Steps
+
+- `/clear` first for a fresh context window
+- `/ace:map-guide` — create another guide
+- `/ace:map-pattern` — document a pattern referenced by this guide
+- `/ace:map-sys-doc` — document a system referenced by this guide
+- Review file at `.docs/wiki/subsystems/[subsystem-name]/guides/`