agile-context-engineering 0.2.2 → 0.5.0

package/skills/map-story/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>

package/skills/map-story/templates/system-cross-cutting.xml

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

package/skills/map-story/templates/walkthrough.xml

@@ -0,0 +1,255 @@
+<walkthrough>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/walkthroughs/<flow-name>.md` — a deep,
+        tutorial-style explanation of a complex end-to-end flow. Answers "Walk me through EXACTLY
+        what happens when X."
+
+        Each walkthrough traces a single flow from entry point to exit point, showing ACTUAL code
+        from the codebase at every step, explaining what each piece does and WHY, and calling out
+        framework/library concepts with info boxes when external tools are involved.
+
+        Written for humans (especially new developers and interns) who need to UNDERSTAND a flow
+        before they can work with it. Unlike system docs (terse references for AI agents),
+        walkthroughs prioritize completeness of information — but deliver it in minimal words.
+
+        A "walkthrough" is a traced execution flow through multiple classes and layers:
+        e.g., "Message arrives via SignalR until it reaches the LLM", "LLM calls a tool until
+        the drawing appears on the chart", "User places an order until it's confirmed".
+
+        Create a walkthrough when:
+        - A flow spans 3+ classes across multiple architectural layers
+        - External frameworks/libraries are involved that need explanation (MAF, SignalR, EF Core)
+        - A system doc would need paragraphs of explanation with code snippets (that's a walkthrough, not a system doc)
+        - An intern reading the code alone would not understand what's happening without guidance
+
+        **Emphasis Frameworks:**
+        Walkthroughs can specify one or more "emphasis frameworks" — external frameworks,
+        libraries, APIs, or SDKs that deserve deep explanation throughout the walkthrough.
+        When an emphasis framework is specified:
+        - EVERY step where the flow touches that framework MUST have a framework info box
+        - The info box explains the specific framework concept used in that step
+        - ALL code from ALL steps that interact with the emphasis framework is shown and explained
+        - The agent researches the framework (via WebSearch/context7 or provided docs) if needed
+        - The Framework Concepts Reference table at the end is MANDATORY
+
+        Examples of emphasis frameworks: SignalR, EF Core, MAF (Microsoft Agent Framework),
+        React Query, gRPC, MediatR, AutoMapper. Can be specified by name (agent researches)
+        or with documentation paths/URLs (agent reads provided docs).
+
+        Complements:
+        - systems/ docs (terse WHAT reference — walkthroughs explain the HOW in depth)
+        - patterns/ docs (reusable structural patterns — walkthroughs trace specific flows through them)
+        - guides/ docs (procedural recipes for DOING — walkthroughs explain for UNDERSTANDING)
+        - cross-cutting/ docs (shared infrastructure — walkthroughs show how flows pass through them)
+    </purpose>
+
+    <template>
+        <title>
+            # [Flow Name]
+
+            One line: what this flow does and when it triggers.
+        </title>
+
+        <file-map>
+            ## Files Involved
+
+            Every file this flow touches, in execution order.
+
+            ```
+            src/[layer]/[area]/
+            |-- FileA.cs                    # Entry point
+            |-- FileB.cs                    # Orchestrates flow
+            |-- FileC.cs                    # Core logic
+            `-- FileD.cs                    # Sends result
+            ```
+        </file-map>
+
+        <flow-diagram>
+            ## Flow Overview
+
+            ```mermaid
+            sequenceDiagram
+                participant A as ComponentA
+                participant B as ComponentB
+                participant C as ComponentC
+                participant D as ExternalSystem
+
+                A->>B: step description
+                B->>C: step description
+                C->>D: step description
+                D-->>C: response
+                C-->>B: result
+                B-->>A: result
+            ```
+
+            Participants = real classes/components. Arrows = real method calls.
+            Steps below explain each arrow.
+        </flow-diagram>
+
+        <steps>
+            ## Step-by-Step
+
+            ### Step 1: [What happens]
+
+            **File:** `path/to/File.cs:ClassName.MethodName`
+
+            [1-2 sentences: what this step does and WHY. No filler.]
+
+            ```csharp
+            // Actual code from the codebase
+            public async Task MethodName(string param1, string param2)
+            {
+                var result = await _dependency.DoSomething(param1);
+            }
+            ```
+
+            `_dependency` — injected via constructor, does X.
+            `param1` — the Y received from Z.
+            [Only explain what's non-obvious. Skip what the code already says clearly.]
+
+            ---
+
+            ### Step 2: [What happens]
+
+            **File:** `path/to/AnotherFile.cs:ClassName.MethodName`
+
+            [What and why — terse.]
+
+            ```csharp
+            // Actual code...
+            ```
+
+            > **[Framework]: [Concept]**
+            >
+            > [Succinct explanation of the framework concept. What it is, what it does for us.
+            > No history, no alternatives, no "in general" — just what the reader needs to
+            > understand THIS code.]
+            >
+            > *Source: [link to official docs]*
+
+            ---
+
+            ### Step 3: [What happens]
+
+            ...continue for every step in the flow...
+        </steps>
+
+        <framework-concepts>
+            ## Framework Concepts Reference
+
+            Consolidated lookup for framework concepts explained inline above.
+
+            | Concept | Framework | What It Does | First Appearance |
+            |---------|-----------|-------------|------------------|
+            | `AIFunctionFactory.Create()` | MS Agent Framework | C# method -> LLM tool | [Step N](#step-n) |
+            | `ChatClientAgent` | MS Agent Framework | Wraps IChatClient with auto tool loop | [Step M](#step-m) |
+
+            Include ONLY if external frameworks/libraries are involved.
+        </framework-concepts>
+
+        <related-docs>
+            ## Related Documentation
+
+            - [System Doc](../systems/relevant-system.md) — terse reference
+            - [Guide](../guides/relevant-guide.md) — recipe for adding to this flow
+            - [Official Docs](../framework-docs/relevant-page.md) — framework docs
+        </related-docs>
+    </template>
+
+    <guidelines>
+
+        ### Density Over Prose
+        - **EXTREMELY SUCCINCT** — every word must add value. If a word does not add value, remove it.
+        - **NO FLUFF** — no introductions, no summaries of what the section will contain, no transitions
+        - Bullet points over paragraphs. Tables over bullet points when comparing.
+        - If you can say it in 3 words, don't use 10. Then try to say it in 2.
+        - **BUT: ALL needed information MUST be present.** Succinctness means cutting WORDS, not cutting INFORMATION. Every concept, every parameter, every non-obvious behavior must be explained — just in fewer words.
+
+        ### Complete but Dense Explanations
+        - Explain the WHY, not just the WHAT — "X because Y" not "X happens"
+        - After each code snippet: explain ONLY what's non-obvious. If the code says `price > 0`, don't write "checks that price is positive" — the code already says that. DO explain hidden behaviors, framework magic, non-obvious field origins.
+        - Use inline code references for fields/params: `` `_connectionId` — captured from `Context.ConnectionId` in AgentHub ``
+        - One-line explanations preferred. Multi-line only when genuinely complex.
+
+        ### Code Snippets (MANDATORY per step)
+        - ALWAYS from the actual codebase — verified by reading the file
+        - NEVER pseudocode, NEVER summaries, NEVER fabricated
+        - Use correct language tag: ```csharp, ```typescript, ```json
+        - **FOCUSED**: show ONLY the lines relevant to what the step is explaining. If a method has 50 lines but this step is about lines 10-15, show lines 10-15 with a `// ... (validation above)` or `// ... (setup omitted)` comment for context. The snippet serves the step's explanation, not the other way around.
+        - Short methods (under 20 lines) where the ENTIRE method is relevant: show entirely
+        - Long methods: show the relevant portion only. Use `// ...` comments to indicate omitted sections above/below.
+
+        ### Flow Diagram (MANDATORY)
+        - Every walkthrough MUST start with a mermaid sequenceDiagram
+        - Participants = real classes/components, not abstract concepts
+        - Arrows = real method calls, labeled with method name
+        - The diagram is the map; the steps are the guided tour
+
+        ### Framework Info Boxes (when applicable)
+        - Use markdown blockquotes (`>`) with `> **[Framework]: [Concept]**` header
+        - Explain as if the reader has NEVER used this framework — but in minimal words
+        - Place IMMEDIATELY after the first code snippet that uses the concept
+        - Each concept explained ONCE — do not repeat
+        - Link to official docs with `*Source: [link]*`
+        - Keep it dense: what it is, what it does for us, done. No history, no alternatives.
+
+        ### Emphasis Frameworks (when specified)
+        - When emphasis-frameworks are specified, framework info boxes become MANDATORY
+          for EVERY step that touches the emphasis framework — not just the first occurrence
+        - ALL code that interacts with the emphasis framework must be shown in full
+        - The Framework Concepts Reference table is MANDATORY (not optional)
+        - If the agent does not know the framework: use WebSearch or context7 MCP to research it
+        - If framework docs are provided (file paths or URLs): read them BEFORE writing any steps
+
+        ### Minimum Length
+        - At least 300 lines — length comes from code snippets and completeness, not from prose
+        - Complex flows (3+ frameworks, 10+ classes): 500-1000 lines
+        - Under 200 lines = not enough information, add more steps/explanations
+
+        ### Section Inclusion
+        - Title, File Map, Flow Diagram, Step-by-Step: ALWAYS required
+        - Framework Concepts Reference: MANDATORY if emphasis-frameworks specified; otherwise ONLY if external frameworks involved
+        - Related Documentation: ALWAYS required
+
+        ### What Does NOT Belong Here
+        - Terse bullet-point references (that's systems/)
+        - Structural pattern descriptions (that's patterns/)
+        - Procedural "how to add X" recipes (that's guides/)
+        - Architecture decision rationale (that's decisions/)
+        - Story numbers, sprint context, revision history
+        - Testing instructions or test code
+        - Frontend code in a backend walkthrough (or vice versa) — scope to ONE side
+        - Speculation about future changes — document what IS, not what might be
+        - Filler phrases: "Let's look at", "Now we'll examine", "As mentioned above", "It's worth noting"
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the flow it describes changes.
+
+        **Update triggers:**
+        - New step added to the flow
+        - Step removed from the flow
+        - Step logic changed significantly
+        - Framework/library upgraded, APIs changed
+        - Code snippets no longer match codebase
+        - New framework concept introduced
+
+        **NOT an update trigger:**
+        - Bug fixes that don't change flow structure
+        - Internal refactoring within a single step
+        - New feature using a DIFFERENT flow (create a new walkthrough)
+        - Style/formatting changes to the code
+
+        **Update rules:**
+        - UPDATE code snippets to match current codebase — stale snippets are worse than no docs
+        - ADD new steps when the flow gains a stage
+        - REMOVE steps that no longer exist
+        - UPDATE framework info boxes when APIs change
+        - UPDATE mermaid diagram to reflect current flow
+        - Document must always reflect CURRENT code state, not history
+
+    </evolution>
+
+</walkthrough>