agile-context-engineering 0.3.0 → 0.5.1

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

@@ -0,0 +1,126 @@
+---
+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: false
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/system-cross-cutting.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>When a cross-cutting concern needs dedicated documentation</trigger>
+            <trigger>After implementing shared infrastructure that multiple systems depend on</trigger>
+            <trigger>When agents need to understand how to register with or plug into shared concerns</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A concern spans multiple domain systems within a subsystem</condition>
+            <condition>Multiple systems register with or depend on this infrastructure</condition>
+            <condition>An agent needs to know WHERE to register and HOW to interact with the concern</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="text" type="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.
+                </param>
+                <param name="subsystem" type="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.
+                </param>
+            </required>
+
+            <optional>
+                <param name="story-context" type="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.
+                </param>
+                <param name="commits" type="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.
+                </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>
+            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.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-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-cross-cutting workflow from
+        `workflow.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-cross-cutting — create another cross-cutting concern doc</step>
+        <step>/ace:map-sys-doc — document a system that uses this concern</step>
+        <step>/ace:map-guide — create a guide that includes registration steps</step>
+        <step>Review file at .docs/wiki/subsystems/[subsystem-name]/cross-cutting/</step>
+    </next-steps>
+
+</command>
+```

package/{agile-context-engineering/templates/wiki → skills/map-cross-cutting}/system-cross-cutting.xml

@@ -1,197 +1,197 @@
-<system-cross-cutting>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/cross-cutting/<concern-name>.md` — a
-        concern that spans multiple systems within a codebase subsystem. Answers "How does this
-        shared infrastructure/concern work, and how do I plug into it?"
-
-        Each cross-cutting doc describes shared infrastructure or mechanisms that multiple domain
-        systems depend on. It is the document an AI agent reads to understand how to register,
-        configure, or interact with shared concerns.
-
-        Examples of cross-cutting concerns:
-        - Dependency injection and container registration
-        - Factory/registry registration patterns
-        - Event systems, invalidation, pub/sub
-        - Serialization/deserialization
-        - Error handling and logging infrastructure
-        - Authentication/authorization middleware
-        - Cache/invalidation infrastructure
-        - Shared abstract base classes
-
-        Complements:
-        - systems/ docs (domain systems that USE these cross-cutting concerns)
-        - patterns/ docs (reusable structural patterns, not shared infrastructure)
-        - guides/ docs (task recipes that reference cross-cutting setup steps)
-    </purpose>
-
-    <template>
-        <overview>
-            # [Cross-Cutting Concern]
-
-            ## Overview
-            What this concern addresses, why it exists. One paragraph.
-        </overview>
-
-        <how-it-works>
-            ## How It Works
-
-            The pattern/mechanism used. Reference actual code locations.
-
-            1. **Step**: Description at `file:ClassName.method`
-            2. **Step**: Description at `file:ClassName.method`
-            3. **Step**: Description at `file:ClassName.method`
-        </how-it-works>
-
-        <registration-and-setup>
-            ## Registration / Setup
-
-            Where and how components register with this concern.
-            - **Container**: `file:container.ts:registerServices`
-            - **Factory**: `file:DrawingFactory.ts:DrawingFactory`
-            - **Registry**: `file:DrawingRegistry.ts:DrawingRegistry`
-        </registration-and-setup>
-
-        <usage>
-            ## Usage
-
-            How other systems interact with this concern.
-
-            ```typescript
-            // Usage pattern (inline only if non-obvious)
-            ```
-        </usage>
-
-        <current-registrations>
-            ## Current Registrations / Implementations
-
-            What is currently registered/using this concern:
-            - `TrendLine` registered at `file:container.ts:registerDrawings`
-            - `ParallelChannel` registered at `file:container.ts:registerDrawings`
-            - ...
-        </current-registrations>
-
-        <integration-points>
-            ## Integration Points
-
-            Where this concern connects to other systems.
-            - [System A](../systems/system-a.md) — uses this for [purpose]
-            - [System B](../systems/system-b.md) — uses this for [purpose]
-        </integration-points>
-
-        <gotchas>
-            ## Gotchas
-
-            Common mistakes when working with this concern.
-            - [Common mistake 1]
-            - [Common mistake 2]
-        </gotchas>
-
-        <tech-debt>
-            ## Tech Debt
-
-            Known quality issues in this cross-cutting concern discovered during story code reviews.
-            Items are added by the wiki mapper and removed when fixed by a future story.
-            Include ONLY if this concern has known tech debt items. Omit section entirely if clean.
-
-            ### [Short descriptive title of the issue]
-            - **Severity:** high | medium | low
-            - **File:** `[file-path:SymbolName]`
-            - **Description:** What the issue is, why it matters, and what could go wrong
-              if left unfixed. For cross-cutting concerns, note which dependent systems are affected.
-            - **Discovered during:** [story-id] — [story title]
-
-            ### [Another issue]
-            - **Severity:** ...
-            - **File:** ...
-            - **Description:** ...
-            - **Discovered during:** ...
-        </tech-debt>
-    </template>
-
-    <guidelines>
-
-        **Documentation Style:**
-        - EXTREMELY SUCCINCT — every word must add value
-        - NO FLUFF — direct, actionable information only
-        - Bullet points over paragraphs
-        - Code references as `file-path:ClassName.methodName` (not line numbers)
-        - Inline snippets ONLY for usage patterns and registration examples
-        - **ALL visual representations of architecture, dependencies, flows, or relationships MUST be ```mermaid fenced code blocks. NO ASCII arrows (->), NO dependency trees, NO PlantUML. Only mermaid. The ONLY ASCII exception is file trees.**
-
-        **Overview:**
-        - ONE paragraph. What the concern does and why it exists.
-        - Focus on what an agent needs to know to interact with this concern.
-
-        **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.
-
-        **Registration / Setup:**
-        - The MOST CRITICAL section for AI agents. They need to know WHERE to register new things.
-        - List every registration point with exact file paths.
-        - Show the registration pattern (inline code only if non-obvious).
-
-        **Usage:**
-        - How consuming code interacts with this concern.
-        - Inline code snippet ONLY if the usage pattern is non-obvious.
-        - If usage is straightforward (e.g., inject via constructor), a one-liner suffices.
-
-        **Current Registrations / Implementations:**
-        - Complete list of everything currently registered/using this concern.
-        - Agent uses this to verify its new registration is consistent with existing ones.
-        - Update when new registrations are added.
-
-        **Integration Points:**
-        - Cross-reference with markdown links to system docs that depend on this concern.
-        - Helps agents understand the blast radius of changes to this concern.
-
-        **Gotchas:**
-        - Registration order dependencies, naming conventions, initialization timing.
-        - Anything that silently fails if done wrong.
-
-        **Tech Debt:**
-        - One `###` subsection per known issue — NOT a table. Each issue needs enough context
-          for an agent to understand the problem without reading the code.
-        - For cross-cutting concerns, always note which dependent systems are affected.
-        - Severity: `high` (security, data loss, production instability), `medium` (quality,
-          maintainability), `low` (cosmetic, minor inefficiency).
-        - Always link to the discovering story for traceability.
-        - REMOVE items when fixed by a future story.
-        - Omit the entire section if no tech debt exists in this concern.
-
-        **What does NOT belong here:**
-        - Domain-specific logic (that's in systems/ docs)
-        - Reusable structural patterns (that's in patterns/ docs)
-        - Step-by-step task recipes (that's in guides/ docs)
-        - Story numbers, sprint context, revision history
-        - Testing instructions, performance benchmarks
-
-    </guidelines>
-
-    <evolution>
-
-        This is a LIVING document — updated when the cross-cutting concern changes.
-
-        **Update triggers:**
-        - New registration added (update Current Registrations list)
-        - Registration mechanism changed (new file, new pattern)
-        - New integration point discovered
-        - New gotcha discovered
-        - Setup/initialization process changed
-        - Tech debt discovered or resolved in this concern's files
-
-        **NOT an update trigger:**
-        - New feature that registers with existing mechanism without changing it
-        - Bug fix in one registered component
-        - Internal refactoring of the mechanism that doesn't change the external API
-
-        **Update rules:**
-        - ADD new registrations to the list
-        - UPDATE Registration / Setup if the process changed
-        - ADD new gotchas as they are discovered
-        - REMOVE registrations for deleted components
-
-    </evolution>
-
-</system-cross-cutting>
+<system-cross-cutting>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/cross-cutting/<concern-name>.md` — a
+        concern that spans multiple systems within a codebase subsystem. Answers "How does this
+        shared infrastructure/concern work, and how do I plug into it?"
+
+        Each cross-cutting doc describes shared infrastructure or mechanisms that multiple domain
+        systems depend on. It is the document an AI agent reads to understand how to register,
+        configure, or interact with shared concerns.
+
+        Examples of cross-cutting concerns:
+        - Dependency injection and container registration
+        - Factory/registry registration patterns
+        - Event systems, invalidation, pub/sub
+        - Serialization/deserialization
+        - Error handling and logging infrastructure
+        - Authentication/authorization middleware
+        - Cache/invalidation infrastructure
+        - Shared abstract base classes
+
+        Complements:
+        - systems/ docs (domain systems that USE these cross-cutting concerns)
+        - patterns/ docs (reusable structural patterns, not shared infrastructure)
+        - guides/ docs (task recipes that reference cross-cutting setup steps)
+    </purpose>
+
+    <template>
+        <overview>
+            # [Cross-Cutting Concern]
+
+            ## Overview
+            What this concern addresses, why it exists. One paragraph.
+        </overview>
+
+        <how-it-works>
+            ## How It Works
+
+            The pattern/mechanism used. Reference actual code locations.
+
+            1. **Step**: Description at `file:ClassName.method`
+            2. **Step**: Description at `file:ClassName.method`
+            3. **Step**: Description at `file:ClassName.method`
+        </how-it-works>
+
+        <registration-and-setup>
+            ## Registration / Setup
+
+            Where and how components register with this concern.
+            - **Container**: `file:container.ts:registerServices`
+            - **Factory**: `file:DrawingFactory.ts:DrawingFactory`
+            - **Registry**: `file:DrawingRegistry.ts:DrawingRegistry`
+        </registration-and-setup>
+
+        <usage>
+            ## Usage
+
+            How other systems interact with this concern.
+
+            ```typescript
+            // Usage pattern (inline only if non-obvious)
+            ```
+        </usage>
+
+        <current-registrations>
+            ## Current Registrations / Implementations
+
+            What is currently registered/using this concern:
+            - `TrendLine` registered at `file:container.ts:registerDrawings`
+            - `ParallelChannel` registered at `file:container.ts:registerDrawings`
+            - ...
+        </current-registrations>
+
+        <integration-points>
+            ## Integration Points
+
+            Where this concern connects to other systems.
+            - [System A](../systems/system-a.md) — uses this for [purpose]
+            - [System B](../systems/system-b.md) — uses this for [purpose]
+        </integration-points>
+
+        <gotchas>
+            ## Gotchas
+
+            Common mistakes when working with this concern.
+            - [Common mistake 1]
+            - [Common mistake 2]
+        </gotchas>
+
+        <tech-debt>
+            ## Tech Debt
+
+            Known quality issues in this cross-cutting concern discovered during story code reviews.
+            Items are added by the wiki mapper and removed when fixed by a future story.
+            Include ONLY if this concern has known tech debt items. Omit section entirely if clean.
+
+            ### [Short descriptive title of the issue]
+            - **Severity:** high | medium | low
+            - **File:** `[file-path:SymbolName]`
+            - **Description:** What the issue is, why it matters, and what could go wrong
+              if left unfixed. For cross-cutting concerns, note which dependent systems are affected.
+            - **Discovered during:** [story-id] — [story title]
+
+            ### [Another issue]
+            - **Severity:** ...
+            - **File:** ...
+            - **Description:** ...
+            - **Discovered during:** ...
+        </tech-debt>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — every word must add value
+        - NO FLUFF — direct, actionable information only
+        - Bullet points over paragraphs
+        - Code references as `file-path:ClassName.methodName` (not line numbers)
+        - Inline snippets ONLY for usage patterns and registration examples
+        - **ALL visual representations of architecture, dependencies, flows, or relationships MUST be ```mermaid fenced code blocks. NO ASCII arrows (->), NO dependency trees, NO PlantUML. Only mermaid. The ONLY ASCII exception is file trees.**
+
+        **Overview:**
+        - ONE paragraph. What the concern does and why it exists.
+        - Focus on what an agent needs to know to interact with this concern.
+
+        **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.
+
+        **Registration / Setup:**
+        - The MOST CRITICAL section for AI agents. They need to know WHERE to register new things.
+        - List every registration point with exact file paths.
+        - Show the registration pattern (inline code only if non-obvious).
+
+        **Usage:**
+        - How consuming code interacts with this concern.
+        - Inline code snippet ONLY if the usage pattern is non-obvious.
+        - If usage is straightforward (e.g., inject via constructor), a one-liner suffices.
+
+        **Current Registrations / Implementations:**
+        - Complete list of everything currently registered/using this concern.
+        - Agent uses this to verify its new registration is consistent with existing ones.
+        - Update when new registrations are added.
+
+        **Integration Points:**
+        - Cross-reference with markdown links to system docs that depend on this concern.
+        - Helps agents understand the blast radius of changes to this concern.
+
+        **Gotchas:**
+        - Registration order dependencies, naming conventions, initialization timing.
+        - Anything that silently fails if done wrong.
+
+        **Tech Debt:**
+        - One `###` subsection per known issue — NOT a table. Each issue needs enough context
+          for an agent to understand the problem without reading the code.
+        - For cross-cutting concerns, always note which dependent systems are affected.
+        - Severity: `high` (security, data loss, production instability), `medium` (quality,
+          maintainability), `low` (cosmetic, minor inefficiency).
+        - Always link to the discovering story for traceability.
+        - REMOVE items when fixed by a future story.
+        - Omit the entire section if no tech debt exists in this concern.
+
+        **What does NOT belong here:**
+        - Domain-specific logic (that's in systems/ docs)
+        - Reusable structural patterns (that's in patterns/ docs)
+        - Step-by-step task recipes (that's in guides/ docs)
+        - Story numbers, sprint context, revision history
+        - Testing instructions, performance benchmarks
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the cross-cutting concern changes.
+
+        **Update triggers:**
+        - New registration added (update Current Registrations list)
+        - Registration mechanism changed (new file, new pattern)
+        - New integration point discovered
+        - New gotcha discovered
+        - Setup/initialization process changed
+        - Tech debt discovered or resolved in this concern's files
+
+        **NOT an update trigger:**
+        - New feature that registers with existing mechanism without changing it
+        - Bug fix in one registered component
+        - Internal refactoring of the mechanism that doesn't change the external API
+
+        **Update rules:**
+        - ADD new registrations to the list
+        - UPDATE Registration / Setup if the process changed
+        - ADD new gotchas as they are discovered
+        - REMOVE registrations for deleted components
+
+    </evolution>
+
+</system-cross-cutting>