agile-context-engineering 0.3.0 → 0.5.0

package/skills/map-pattern/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: map-pattern
+description: Create or update a pattern document in .docs/wiki/subsystems/[name]/patterns/ — reusable implementation patterns
+argument-hint: "text='Template Method pattern used by all drawing paths' 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 Pattern
+
+Create or update a pattern document describing reusable implementation patterns.
+
+## When to Use
+
+- When a reusable structural pattern needs documentation
+- After identifying a recurring approach used by 2+ implementations
+- When agents need to understand HOW to implement something following an established pattern
+- A structural approach appears across 2+ implementations
+- New code must follow the same pattern for consistency
+- An agent needs to know the abstract structure + concrete steps to add a new implementation
+
+## Input
+
+### Required
+
+- **`text`** (text) — Natural language description of the pattern to document. Describes WHAT the pattern is and WHERE it appears in the codebase. E.g.: "Template Method pattern used by all drawing paths", "Repository pattern for all database access", "CQRS command/query handler pattern". If not provided, pause and ask the user.
+
+- **`subsystem`** (path | text) — Subsystem where this pattern doc belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/patterns/`. 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 pattern. When not provided, the agent discovers the pattern from codebase analysis.
+
+- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding pattern changes. 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 all implementations and extract the pattern structure.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Pattern template**: Read [pattern.xml](pattern.xml) — output format for the pattern document
+- **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 pattern document that describes a reusable structural approach — structure diagram (mermaid classDiagram), how it works step-by-step, how to apply it for new implementations, current implementations list, and gotchas. The document an AI agent reads to ensure new code follows established conventions.
+
+## Artifacts
+
+```
+.docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
+```
+
+## Example Usage
+
+```
+# Basic pattern
+/ace:map-pattern text='Template Method pattern used by all drawing paths' subsystem='qarc-charts-v2'
+
+# With recent commits
+/ace:map-pattern text='Repository pattern for all database access' subsystem='api' commits=3
+
+# With story context
+/ace:map-pattern text='CQRS command/query handler pattern' subsystem='api' story-context='.ace/artifacts/product/e1-api/f2-cqrs/s1-setup/s1-setup.md'
+```
+
+## Next Steps
+
+- `/clear` first for a fresh context window
+- `/ace:map-pattern` — create another pattern document
+- `/ace:map-guide` — create a guide that uses this pattern
+- `/ace:map-sys-doc` — document a system that uses this pattern
+- Review file at `.docs/wiki/subsystems/[subsystem-name]/patterns/`

package/{agile-context-engineering/templates/wiki → skills/map-pattern}/pattern.xml

@@ -1,159 +1,159 @@
-<pattern>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/patterns/<pattern-name>.md` — a reusable
-        implementation pattern within a codebase subsystem. Answers "HOW do I implement something
-        that follows this pattern?"
-
-        Each pattern doc describes a structural template that appears across multiple implementations.
-        It is the document an AI agent reads to ensure new code follows established conventions.
-
-        A "pattern" is a recurring structural approach used by 2+ implementations:
-        e.g., Template Method (Path base class with 5 factory methods), Repository Pattern,
-        Mapper Pattern, Factory/Registry, CQRS Command/Query handlers.
-
-        Complements:
-        - systems/ docs (WHAT exists — the domain subsystems that USE these patterns)
-        - guides/ docs (step-by-step recipes that COMBINE multiple patterns into a task)
-        - cross-cutting/ docs (shared infrastructure that patterns depend on)
-    </purpose>
-
-    <template>
-        <the-pattern>
-            # [Pattern Name]
-
-            ## The Pattern
-            What it is, when to use it. One paragraph max.
-        </the-pattern>
-
-        <structure>
-            ## Structure
-
-            Class/interface diagram showing the pattern's structure.
-
-            ```mermaid
-            classDiagram
-                class IContract {
-                    &lt;&lt;interface&gt;&gt;
-                    +method() ReturnType
-                }
-                class AbstractBase {
-                    &lt;&lt;abstract&gt;&gt;
-                    +templateMethod()
-                    #factoryMethod()* ReturnType
-                }
-                IContract &lt;|.. AbstractBase
-                AbstractBase &lt;|-- ConcreteA
-                AbstractBase &lt;|-- ConcreteB
-            ```
-        </structure>
-
-        <how-it-works>
-            ## How It Works
-
-            Step-by-step of the pattern mechanics. 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>
-
-        <how-to-apply>
-            ## How to Apply
-
-            When implementing something new that uses this pattern:
-
-            1. [First step] (reference: `file:ClassName.method`)
-            2. [Second step]
-            3. [Third step]
-            ...
-        </how-to-apply>
-
-        <current-implementations>
-            ## Current Implementations
-
-            Where this pattern is currently used:
-            - `TrendLine` at `src/infrastructure/primitives/trend-line/TrendLine.ts`
-            - `ParallelChannel` at `src/infrastructure/primitives/parallel-channel/ParallelChannel.ts`
-            - ...
-        </current-implementations>
-
-        <gotchas>
-            ## Gotchas
-
-            Things that commonly go wrong or are easy to forget when applying this pattern.
-            - [Common mistake 1]
-            - [Common mistake 2]
-        </gotchas>
-    </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 interface contracts and pattern structure definitions
-        - **ALL visual representations of architecture, dependencies, flows, or relationships MUST be ```mermaid fenced code blocks (use `classDiagram` for structure). NO ASCII arrows (->), NO dependency trees, NO PlantUML. Only mermaid. The ONLY ASCII exception is file trees.**
-
-        **The Pattern:**
-        - ONE paragraph. Name the GoF/industry pattern if applicable, then explain how it
-          manifests in THIS codebase. Not a textbook definition — the codebase-specific version.
-
-        **Structure:**
-        - Mermaid classDiagram showing the abstract/interface hierarchy.
-        - Show the pattern skeleton only — not every concrete implementation.
-        - Include key method signatures that define the contract.
-
-        **How It Works:**
-        - Numbered steps tracing the pattern's execution flow.
-        - Every step references actual code with `file:ClassName.method`.
-        - Focus on the mechanics an agent needs to understand to add a new implementation.
-
-        **How to Apply:**
-        - The MOST ACTIONABLE section. An agent follows these steps to create a new instance.
-        - Reference existing implementations as "copy from" targets.
-        - Include which files to create, which registrations to add, which factories to update.
-
-        **Current Implementations:**
-        - Complete list of all known implementations with file paths.
-        - Agent uses this as a reference gallery — "pick the closest one and copy its structure."
-        - Update when new implementations are added.
-
-        **Gotchas:**
-        - Timing issues, naming conventions, registration requirements, common mistakes.
-        - Anything an agent would get wrong on first attempt without being told.
-
-        **What does NOT belong here:**
-        - System-specific domain logic (that's in systems/ docs)
-        - Step-by-step task recipes that combine multiple patterns (that's in guides/)
-        - Cross-cutting infrastructure details (that's in cross-cutting/)
-        - Story numbers, sprint context, revision history
-        - Testing instructions, performance benchmarks
-
-    </guidelines>
-
-    <evolution>
-
-        This is a LIVING document — updated when the pattern itself evolves.
-
-        **Update triggers:**
-        - New implementation added (update Current Implementations list)
-        - Pattern structure changed (new factory method, new interface method)
-        - How to Apply steps changed (new registration requirement, new file to create)
-        - New gotcha discovered during implementation
-
-        **NOT an update trigger:**
-        - New feature that follows the existing pattern without changing it
-        - Bug fix in one implementation
-        - Internal refactoring that doesn't change the pattern contract
-
-        **Update rules:**
-        - ADD new implementations to the list
-        - UPDATE How to Apply if the recipe changed
-        - ADD new gotchas as they are discovered
-        - Do NOT remove historical gotchas unless they are no longer relevant
-
-    </evolution>
-
-</pattern>
+<pattern>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/patterns/<pattern-name>.md` — a reusable
+        implementation pattern within a codebase subsystem. Answers "HOW do I implement something
+        that follows this pattern?"
+
+        Each pattern doc describes a structural template that appears across multiple implementations.
+        It is the document an AI agent reads to ensure new code follows established conventions.
+
+        A "pattern" is a recurring structural approach used by 2+ implementations:
+        e.g., Template Method (Path base class with 5 factory methods), Repository Pattern,
+        Mapper Pattern, Factory/Registry, CQRS Command/Query handlers.
+
+        Complements:
+        - systems/ docs (WHAT exists — the domain subsystems that USE these patterns)
+        - guides/ docs (step-by-step recipes that COMBINE multiple patterns into a task)
+        - cross-cutting/ docs (shared infrastructure that patterns depend on)
+    </purpose>
+
+    <template>
+        <the-pattern>
+            # [Pattern Name]
+
+            ## The Pattern
+            What it is, when to use it. One paragraph max.
+        </the-pattern>
+
+        <structure>
+            ## Structure
+
+            Class/interface diagram showing the pattern's structure.
+
+            ```mermaid
+            classDiagram
+                class IContract {
+                    &lt;&lt;interface&gt;&gt;
+                    +method() ReturnType
+                }
+                class AbstractBase {
+                    &lt;&lt;abstract&gt;&gt;
+                    +templateMethod()
+                    #factoryMethod()* ReturnType
+                }
+                IContract &lt;|.. AbstractBase
+                AbstractBase &lt;|-- ConcreteA
+                AbstractBase &lt;|-- ConcreteB
+            ```
+        </structure>
+
+        <how-it-works>
+            ## How It Works
+
+            Step-by-step of the pattern mechanics. 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>
+
+        <how-to-apply>
+            ## How to Apply
+
+            When implementing something new that uses this pattern:
+
+            1. [First step] (reference: `file:ClassName.method`)
+            2. [Second step]
+            3. [Third step]
+            ...
+        </how-to-apply>
+
+        <current-implementations>
+            ## Current Implementations
+
+            Where this pattern is currently used:
+            - `TrendLine` at `src/infrastructure/primitives/trend-line/TrendLine.ts`
+            - `ParallelChannel` at `src/infrastructure/primitives/parallel-channel/ParallelChannel.ts`
+            - ...
+        </current-implementations>
+
+        <gotchas>
+            ## Gotchas
+
+            Things that commonly go wrong or are easy to forget when applying this pattern.
+            - [Common mistake 1]
+            - [Common mistake 2]
+        </gotchas>
+    </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 interface contracts and pattern structure definitions
+        - **ALL visual representations of architecture, dependencies, flows, or relationships MUST be ```mermaid fenced code blocks (use `classDiagram` for structure). NO ASCII arrows (->), NO dependency trees, NO PlantUML. Only mermaid. The ONLY ASCII exception is file trees.**
+
+        **The Pattern:**
+        - ONE paragraph. Name the GoF/industry pattern if applicable, then explain how it
+          manifests in THIS codebase. Not a textbook definition — the codebase-specific version.
+
+        **Structure:**
+        - Mermaid classDiagram showing the abstract/interface hierarchy.
+        - Show the pattern skeleton only — not every concrete implementation.
+        - Include key method signatures that define the contract.
+
+        **How It Works:**
+        - Numbered steps tracing the pattern's execution flow.
+        - Every step references actual code with `file:ClassName.method`.
+        - Focus on the mechanics an agent needs to understand to add a new implementation.
+
+        **How to Apply:**
+        - The MOST ACTIONABLE section. An agent follows these steps to create a new instance.
+        - Reference existing implementations as "copy from" targets.
+        - Include which files to create, which registrations to add, which factories to update.
+
+        **Current Implementations:**
+        - Complete list of all known implementations with file paths.
+        - Agent uses this as a reference gallery — "pick the closest one and copy its structure."
+        - Update when new implementations are added.
+
+        **Gotchas:**
+        - Timing issues, naming conventions, registration requirements, common mistakes.
+        - Anything an agent would get wrong on first attempt without being told.
+
+        **What does NOT belong here:**
+        - System-specific domain logic (that's in systems/ docs)
+        - Step-by-step task recipes that combine multiple patterns (that's in guides/)
+        - Cross-cutting infrastructure details (that's in cross-cutting/)
+        - Story numbers, sprint context, revision history
+        - Testing instructions, performance benchmarks
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the pattern itself evolves.
+
+        **Update triggers:**
+        - New implementation added (update Current Implementations list)
+        - Pattern structure changed (new factory method, new interface method)
+        - How to Apply steps changed (new registration requirement, new file to create)
+        - New gotcha discovered during implementation
+
+        **NOT an update trigger:**
+        - New feature that follows the existing pattern without changing it
+        - Bug fix in one implementation
+        - Internal refactoring that doesn't change the pattern contract
+
+        **Update rules:**
+        - ADD new implementations to the list
+        - UPDATE How to Apply if the recipe changed
+        - ADD new gotchas as they are discovered
+        - Do NOT remove historical gotchas unless they are no longer relevant
+
+    </evolution>
+
+</pattern>