agile-context-engineering 0.3.0 → 0.5.1

package/skills/map-subsystem/templates/guide.xml

@@ -0,0 +1,137 @@
+<guide>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/guides/<task-name>.md` — a step-by-step
+        recipe for a common implementation task. Answers "How do I add/create/implement X?"
+
+        Each guide combines knowledge from multiple systems, patterns, and cross-cutting concerns
+        into one actionable recipe. It is the document an AI agent follows when performing a
+        recurring task end-to-end.
+
+        A "guide" is a task recipe for something developers do repeatedly:
+        e.g., "How to Add a New Drawing Tool", "How to Add a New CRUD Endpoint",
+        "How to Add a New Indicator", "How to Add a New Repository".
+
+        Complements:
+        - patterns/ docs (the structural patterns that guides reference)
+        - systems/ docs (the domain systems where guide steps take place)
+        - cross-cutting/ docs (the registrations and setup that guides include as steps)
+    </purpose>
+
+    <template>
+        <title>
+            # How to [Task]
+        </title>
+
+        <prerequisites>
+            ## Prerequisites
+
+            What you need to know or have in place before starting.
+            - Read: [Pattern Doc](../patterns/relevant-pattern.md) — understand the structural pattern
+            - Read: [System Doc](../systems/relevant-system.md) — understand the domain context
+            - Read: [Cross-Cutting Doc](../cross-cutting/relevant-concern.md) — understand registrations
+        </prerequisites>
+
+        <steps>
+            ## Steps
+
+            ### 1. [First Step]
+
+            What to do, where to do it, reference implementation to copy from.
+            - Create file: `[path]`
+            - Copy from: `file:ExistingImplementation` (closest reference)
+            - Key changes: [what to modify from the reference]
+
+            ### 2. [Second Step]
+
+            ...
+
+            ### 3. [Third Step]
+
+            ...
+        </steps>
+
+        <verification>
+            ## Verification
+
+            How to verify the implementation works.
+            - [ ] [Check 1]: [What to verify and how]
+            - [ ] [Check 2]: [What to verify and how]
+            - [ ] [Check 3]: [What to verify and how]
+        </verification>
+
+        <common-mistakes>
+            ## Common Mistakes
+
+            What people typically get wrong.
+            - [Mistake 1]: [Why it happens and how to avoid it]
+            - [Mistake 2]: [Why it happens and how to avoid it]
+        </common-mistakes>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — every word must add value
+        - NO FLUFF — direct, actionable information only
+        - Numbered steps — the agent follows these in order
+        - Code references as `file-path:ClassName.methodName` (not line numbers)
+        - Inline snippets ONLY for non-obvious configuration or registration code
+        - Every step must have a clear deliverable (a file created, a registration added, etc.)
+
+        **Prerequisites:**
+        - Link to the docs an agent should read BEFORE starting.
+        - Don't repeat content from those docs — just link.
+        - List any tools, dependencies, or environment requirements.
+
+        **Steps:**
+        - NUMBERED, ORDERED steps. An agent follows these sequentially.
+        - Each step has: WHAT to do, WHERE to do it, WHAT to copy from.
+        - Reference existing implementations as "copy from" targets — agents copy patterns, not invent.
+        - Include ALL steps: file creation, registration, configuration, wiring.
+        - Don't skip "obvious" steps — agents don't infer implicit requirements.
+
+        **Verification:**
+        - Checklist format. Agent runs through these after completing all steps.
+        - Include compilation check, runtime check, and behavioral check.
+        - Reference specific files or commands for verification.
+
+        **Common Mistakes:**
+        - Things agents (and developers) typically get wrong on first attempt.
+        - Each mistake should include WHY it happens and HOW to avoid it.
+        - Drawn from actual experience (gotchas from pattern and system docs).
+
+        **What does NOT belong here:**
+        - Detailed pattern explanations (link to patterns/ docs instead)
+        - System domain knowledge (link to systems/ docs instead)
+        - Cross-cutting mechanism details (link to cross-cutting/ docs instead)
+        - Story numbers, sprint context, revision history
+        - Testing strategy or test code (verification section covers basic checks only)
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the recipe changes.
+
+        **Update triggers:**
+        - New step required (new registration, new file to create)
+        - Step removed (registration no longer needed)
+        - Step order changed
+        - New common mistake discovered
+        - Reference implementation changed (new "copy from" target)
+        - Prerequisite docs added or removed
+
+        **NOT an update trigger:**
+        - New feature that follows the existing recipe without changes
+        - Bug fix in one implementation that followed the guide
+        - Internal refactoring that doesn't change the steps
+
+        **Update rules:**
+        - UPDATE steps when the recipe changes
+        - ADD new common mistakes as they are discovered
+        - UPDATE "copy from" references when better examples exist
+        - Keep the guide current — an agent should be able to follow it TODAY
+
+    </evolution>
+
+</guide>

package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/module-discovery.xml

@@ -1,174 +1,174 @@
-<module-discovery>
-    <purpose>
-        Template for `.ace/artifacts/[subsystem_name]/module-discovery.md` — the discovery
-        artifact that groups subsystem files into logical documentation modules.
-
-        This document is consumed by Step 8.7 of map-subsystem to determine which map-story
-        calls to make and what files to pass to each call.
-
-        Each module is a coherent group of related files that together represent one concern.
-        map-story receives the files and autonomously decides what documentation to produce —
-        it may create systems/ docs, patterns/ docs, cross-cutting/ docs, guides/ docs,
-        walkthroughs/ docs, and decisions/ docs, all from a single call. Discovery does NOT pre-categorize modules
-        by document type.
-
-        Files CAN appear in multiple modules. A domain model shared by two systems legitimately
-        belongs in both — map-story will document it from each system's perspective.
-    </purpose>
-
-    <template>
-        # Module Discovery: [subsystem_name]
-
-        ## Modules
-
-        Each row is one coherent group of related files. map-story receives these files
-        and autonomously decides what docs to create or update (systems/, patterns/,
-        cross-cutting/, guides/, walkthroughs/, decisions/).
-
-        | # | Module Name | Files | Relevant Docs |
-        |---|-------------|-------|---------------|
-        | 1 | [e.g., User Management] | [comma-separated absolute paths — full E2E flow] | [comma-separated doc paths, or `none`] |
-        | 2 | [e.g., Order Processing] | [comma-separated absolute paths — full E2E flow] | [comma-separated doc paths, or `none`] |
-        | 3 | [e.g., Repository Pattern] | [2-4 representative files that demonstrate the pattern] | [docs, or `none`] |
-        | 4 | [e.g., Dependency Injection] | [all DI/registration files] | [docs, or `none`] |
-
-        ## Existing Documentation Inventory
-
-        All documentation files found within the subsystem, with their curation status.
-
-        | # | Doc Path | Type | Curated To Module |
-        |---|----------|------|-------------------|
-        | 1 | [absolute path to .md file] | [README / architecture / implementation-doc / planning / cross-cutting / other] | [module name, or `unmatched`] |
-
-        ## File Coverage
-
-        **Total files in subsystem:** N
-        **Files covered by at least one module:** M
-        **Uncovered files:** [list any files intentionally excluded]
-
-        Intentionally excluded (trivial):
-        - `[path]` — [reason: index re-export / empty stub / generated code / test file]
-    </template>
-
-    <guidelines>
-
-        **What makes a good module:**
-
-        A module is a coherent group of files that together represent ONE concern worth
-        documenting. Discovery groups files by concern — map-story decides what doc types
-        to produce from each group. There are three kinds of modules to discover:
-
-        **E2E Domain Flows (most important):**
-
-        A vertical slice traced from entry point through all architectural layers.
-
-        How to discover:
-        - Identify entry points: HTTP controllers, CLI handlers, event consumers, background jobs
-        - Trace DOWNWARD through every layer:
-          controller -> mapper -> service/use-case -> domain entity + value objects
-                     -> repository interface -> repository implementation -> DB scripts / migrations
-        - Collect EVERY file that participates — including DTOs, mappers, constants
-        - Group related entry points when they share the same domain concern:
-          CreateUser + GetUser + UpdateUser + DeleteUser = "User Management" (not 4 modules)
-
-        Key rule: a domain model shared across flows appears in EVERY module that uses it.
-        Do NOT exclude a file because it is shared — duplication in the file list is CORRECT.
-
-        **Recurring Implementation Patterns:**
-
-        A group of similarly structured files that follow a common template.
-
-        How to discover:
-        - Find groups of similar files (3+ repositories, 3+ mappers, 3+ handlers)
-        - Read them — if they follow the same structural template, that's a pattern
-        - Use 2-4 representative files (not all implementations — map-story will discover the rest)
-        - Examples: Repository Pattern, CQRS, Template Method, Factory/Registry, Mapper Pattern
-
-        **Shared Infrastructure / Cross-Cutting Concerns:**
-
-        Infrastructure files that multiple domain flows depend on.
-
-        How to discover:
-        - DI container / service registration files
-        - Event bus, message broker, pub/sub infrastructure
-        - Cache / invalidation infrastructure
-        - Authentication / authorization middleware
-        - Shared abstract base classes
-        - Error handling or logging infrastructure
-        - Registry / factory lookup tables
-
-        **Existing Documentation (Relevant Docs column):**
-
-        Subsystems often contain pre-existing documentation: READMEs, architecture notes,
-        legacy implementation docs, feature planning docs, cross-cutting docs. These are
-        valuable context for map-story — they describe intent, decisions, and history that
-        the code alone doesn't convey.
-
-        How to discover existing docs:
-        - Scan the subsystem directory recursively for *.md files
-        - Scan common documentation locations: `docs/`, `documentation/`, `README.md`,
-          `ARCHITECTURE.md`, `.docs/` (if legacy docs exist there)
-        - Include legacy implementation docs (`*-implementation-doc.md`) — they contain
-          detailed knowledge about what was built and why
-
-        How to curate (assign docs to modules):
-        - Read each doc's title and first few lines to understand its subject
-        - Match to the module whose domain it describes:
-          e.g., `drawing-visibility-implementation-doc.md` -> Drawing System module
-        - A doc can be relevant to multiple modules — list it in each
-        - Architecture docs and READMEs are typically relevant to ALL system modules
-        - Feature planning docs are relevant to the system they planned
-        - Cross-cutting docs match cross-cutting modules
-
-        The Existing Documentation Inventory table lists ALL docs found with their curation status.
-        Docs marked `unmatched` were found but don't clearly belong to any module — the
-        synthesis agent should decide if a new module is needed or if the doc is obsolete.
-
-        **File Coverage:**
-
-        Every non-trivial file must appear in at least one module. Exclude ONLY:
-        - Index / barrel re-exports (files that only re-export from other files, no logic)
-        - Empty stubs or placeholder files
-        - Auto-generated files (never manually edited)
-        - Build output
-        - Test files (*.test.ts, *.spec.ts, *Tests.cs, etc.)
-
-        If a file has meaningful logic and fits no existing module, create a new module for it.
-
-    </guidelines>
-
-    <what-not-to-do>
-
-        DO NOT group files by architectural layer:
-        - WRONG: { module: "Controllers", files: [UserController, OrderController, ProductController] }
-        - RIGHT: { module: "User Management", files: [UserController, CreateUserDto, UserMapper, UserService, IUserRepository, UserRepository, User, 20240101_CreateUsers.sql] }
-
-        DO NOT exclude domain models because they are shared:
-        - WRONG: Put the User model in zero modules or only one
-        - RIGHT: User model appears in every system that uses it (User Management, Authentication, etc.)
-
-        DO NOT create a module per file:
-        - WRONG: { module: "UserController", files: [UserController.ts] }
-        - RIGHT: { module: "User Management", files: [UserController.ts, ...all related files] }
-
-        DO NOT infer modules from the structure doc or architecture doc summaries alone:
-        - WRONG: Read structure.md, see folder names, create one module per folder
-        - RIGHT: Read the ACTUAL SOURCE CODE — trace E2E flows, read multiple similar files to find patterns
-
-        DO NOT treat all files as equally important:
-        - Index re-exports, empty stubs, and test files are excluded from modules
-        - Focus on files that contain real logic a developer would need to understand
-
-    </what-not-to-do>
-
-    <evolution>
-
-        module-discovery.md is a single-use artifact created per map-subsystem run.
-        It is NOT maintained over time — it is regenerated each time map-subsystem runs.
-
-        It lives in `.ace/artifacts/[subsystem_name]/module-discovery.md` (ephemeral tier).
-        It is committed to git as a record of what this map-subsystem run documented.
-
-    </evolution>
-
-</module-discovery>
+<module-discovery>
+    <purpose>
+        Template for `.ace/artifacts/[subsystem_name]/module-discovery.md` — the discovery
+        artifact that groups subsystem files into logical documentation modules.
+
+        This document is consumed by Step 8.7 of map-subsystem to determine which map-story
+        calls to make and what files to pass to each call.
+
+        Each module is a coherent group of related files that together represent one concern.
+        map-story receives the files and autonomously decides what documentation to produce —
+        it may create systems/ docs, patterns/ docs, cross-cutting/ docs, guides/ docs,
+        walkthroughs/ docs, and decisions/ docs, all from a single call. Discovery does NOT pre-categorize modules
+        by document type.
+
+        Files CAN appear in multiple modules. A domain model shared by two systems legitimately
+        belongs in both — map-story will document it from each system's perspective.
+    </purpose>
+
+    <template>
+        # Module Discovery: [subsystem_name]
+
+        ## Modules
+
+        Each row is one coherent group of related files. map-story receives these files
+        and autonomously decides what docs to create or update (systems/, patterns/,
+        cross-cutting/, guides/, walkthroughs/, decisions/).
+
+        | # | Module Name | Files | Relevant Docs |
+        |---|-------------|-------|---------------|
+        | 1 | [e.g., User Management] | [comma-separated absolute paths — full E2E flow] | [comma-separated doc paths, or `none`] |
+        | 2 | [e.g., Order Processing] | [comma-separated absolute paths — full E2E flow] | [comma-separated doc paths, or `none`] |
+        | 3 | [e.g., Repository Pattern] | [2-4 representative files that demonstrate the pattern] | [docs, or `none`] |
+        | 4 | [e.g., Dependency Injection] | [all DI/registration files] | [docs, or `none`] |
+
+        ## Existing Documentation Inventory
+
+        All documentation files found within the subsystem, with their curation status.
+
+        | # | Doc Path | Type | Curated To Module |
+        |---|----------|------|-------------------|
+        | 1 | [absolute path to .md file] | [README / architecture / implementation-doc / planning / cross-cutting / other] | [module name, or `unmatched`] |
+
+        ## File Coverage
+
+        **Total files in subsystem:** N
+        **Files covered by at least one module:** M
+        **Uncovered files:** [list any files intentionally excluded]
+
+        Intentionally excluded (trivial):
+        - `[path]` — [reason: index re-export / empty stub / generated code / test file]
+    </template>
+
+    <guidelines>
+
+        **What makes a good module:**
+
+        A module is a coherent group of files that together represent ONE concern worth
+        documenting. Discovery groups files by concern — map-story decides what doc types
+        to produce from each group. There are three kinds of modules to discover:
+
+        **E2E Domain Flows (most important):**
+
+        A vertical slice traced from entry point through all architectural layers.
+
+        How to discover:
+        - Identify entry points: HTTP controllers, CLI handlers, event consumers, background jobs
+        - Trace DOWNWARD through every layer:
+          controller -> mapper -> service/use-case -> domain entity + value objects
+                     -> repository interface -> repository implementation -> DB scripts / migrations
+        - Collect EVERY file that participates — including DTOs, mappers, constants
+        - Group related entry points when they share the same domain concern:
+          CreateUser + GetUser + UpdateUser + DeleteUser = "User Management" (not 4 modules)
+
+        Key rule: a domain model shared across flows appears in EVERY module that uses it.
+        Do NOT exclude a file because it is shared — duplication in the file list is CORRECT.
+
+        **Recurring Implementation Patterns:**
+
+        A group of similarly structured files that follow a common template.
+
+        How to discover:
+        - Find groups of similar files (3+ repositories, 3+ mappers, 3+ handlers)
+        - Read them — if they follow the same structural template, that's a pattern
+        - Use 2-4 representative files (not all implementations — map-story will discover the rest)
+        - Examples: Repository Pattern, CQRS, Template Method, Factory/Registry, Mapper Pattern
+
+        **Shared Infrastructure / Cross-Cutting Concerns:**
+
+        Infrastructure files that multiple domain flows depend on.
+
+        How to discover:
+        - DI container / service registration files
+        - Event bus, message broker, pub/sub infrastructure
+        - Cache / invalidation infrastructure
+        - Authentication / authorization middleware
+        - Shared abstract base classes
+        - Error handling or logging infrastructure
+        - Registry / factory lookup tables
+
+        **Existing Documentation (Relevant Docs column):**
+
+        Subsystems often contain pre-existing documentation: READMEs, architecture notes,
+        legacy implementation docs, feature planning docs, cross-cutting docs. These are
+        valuable context for map-story — they describe intent, decisions, and history that
+        the code alone doesn't convey.
+
+        How to discover existing docs:
+        - Scan the subsystem directory recursively for *.md files
+        - Scan common documentation locations: `docs/`, `documentation/`, `README.md`,
+          `ARCHITECTURE.md`, `.docs/` (if legacy docs exist there)
+        - Include legacy implementation docs (`*-implementation-doc.md`) — they contain
+          detailed knowledge about what was built and why
+
+        How to curate (assign docs to modules):
+        - Read each doc's title and first few lines to understand its subject
+        - Match to the module whose domain it describes:
+          e.g., `drawing-visibility-implementation-doc.md` -> Drawing System module
+        - A doc can be relevant to multiple modules — list it in each
+        - Architecture docs and READMEs are typically relevant to ALL system modules
+        - Feature planning docs are relevant to the system they planned
+        - Cross-cutting docs match cross-cutting modules
+
+        The Existing Documentation Inventory table lists ALL docs found with their curation status.
+        Docs marked `unmatched` were found but don't clearly belong to any module — the
+        synthesis agent should decide if a new module is needed or if the doc is obsolete.
+
+        **File Coverage:**
+
+        Every non-trivial file must appear in at least one module. Exclude ONLY:
+        - Index / barrel re-exports (files that only re-export from other files, no logic)
+        - Empty stubs or placeholder files
+        - Auto-generated files (never manually edited)
+        - Build output
+        - Test files (*.test.ts, *.spec.ts, *Tests.cs, etc.)
+
+        If a file has meaningful logic and fits no existing module, create a new module for it.
+
+    </guidelines>
+
+    <what-not-to-do>
+
+        DO NOT group files by architectural layer:
+        - WRONG: { module: "Controllers", files: [UserController, OrderController, ProductController] }
+        - RIGHT: { module: "User Management", files: [UserController, CreateUserDto, UserMapper, UserService, IUserRepository, UserRepository, User, 20240101_CreateUsers.sql] }
+
+        DO NOT exclude domain models because they are shared:
+        - WRONG: Put the User model in zero modules or only one
+        - RIGHT: User model appears in every system that uses it (User Management, Authentication, etc.)
+
+        DO NOT create a module per file:
+        - WRONG: { module: "UserController", files: [UserController.ts] }
+        - RIGHT: { module: "User Management", files: [UserController.ts, ...all related files] }
+
+        DO NOT infer modules from the structure doc or architecture doc summaries alone:
+        - WRONG: Read structure.md, see folder names, create one module per folder
+        - RIGHT: Read the ACTUAL SOURCE CODE — trace E2E flows, read multiple similar files to find patterns
+
+        DO NOT treat all files as equally important:
+        - Index re-exports, empty stubs, and test files are excluded from modules
+        - Focus on files that contain real logic a developer would need to understand
+
+    </what-not-to-do>
+
+    <evolution>
+
+        module-discovery.md is a single-use artifact created per map-subsystem run.
+        It is NOT maintained over time — it is regenerated each time map-subsystem runs.
+
+        It lives in `.ace/artifacts/[subsystem_name]/module-discovery.md` (ephemeral tier).
+        It is committed to git as a record of what this map-subsystem run documented.
+
+    </evolution>
+
+</module-discovery>

package/skills/map-subsystem/templates/pattern.xml

@@ -0,0 +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>