agile-context-engineering 0.2.2 → 0.5.0

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

@@ -0,0 +1,115 @@
+<decisions>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
+        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
+        Answers "Why did we choose X over Y?"
+
+        Each decision doc captures one significant technical decision with its context and
+        trade-offs. It is the document an AI agent reads to understand WHY things are built
+        a certain way, preventing it from making the wrong choice.
+
+        Create an ADR ONLY when a significant "why" decision was made:
+        - Choosing one approach over another with meaningful trade-offs
+        - Deviating from an established pattern for a specific reason
+        - Adopting a new technology, pattern, or architectural approach
+        - Rejecting a seemingly obvious solution for non-obvious reasons
+
+        Do NOT create ADRs for trivial or obvious decisions.
+
+        Complements:
+        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
+        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
+        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
+    </purpose>
+
+    <template>
+        <decision-record>
+            # ADR-NNN: [Decision Title]
+
+            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
+            **Date**: YYYY-MM-DD
+            **Story**: [story reference, if applicable]
+
+            ## Context
+            What situation prompted this decision. 2-3 sentences max.
+
+            ## Decision
+            What was decided. 2-3 sentences max.
+
+            ## Alternatives Considered
+            - **[Alternative A]**: [Why rejected — 1 sentence]
+            - **[Alternative B]**: [Why rejected — 1 sentence]
+
+            ## Consequences
+            - Pro: [positive outcome]
+            - Pro: [positive outcome]
+            - Con: [trade-off accepted]
+        </decision-record>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
+        - NO FLUFF — every sentence must convey a decision, reason, or consequence
+        - Bullet points for alternatives and consequences
+        - Code references as `file-path:ClassName` only when the decision is about specific code
+
+        **ADR Numbering:**
+        - Sequential within the subsystem: ADR-001, ADR-002, etc.
+        - Filename format: `ADR-NNN-kebab-case-slug.md`
+        - To find the next number, read existing ADRs in the decisions/ directory.
+
+        **Status:**
+        - `Accepted` — the decision is in effect
+        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
+        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
+
+        **Context:**
+        - 2-3 sentences. What problem or situation forced a choice.
+        - Reference the system or pattern this decision affects.
+
+        **Decision:**
+        - 2-3 sentences. What was chosen and at what scope.
+        - Be specific — "We use X for Y" not "We decided to improve things."
+
+        **Alternatives Considered:**
+        - List each rejected alternative with ONE sentence explaining why.
+        - If there were no meaningful alternatives, omit this section.
+
+        **Consequences:**
+        - Bullet list of pros and cons.
+        - Be honest about trade-offs — future agents need to know the downsides.
+        - Include migration/compatibility consequences if applicable.
+
+        **What does NOT belong here:**
+        - Implementation details (that's in systems/ and patterns/ docs)
+        - Step-by-step instructions (that's in guides/)
+        - Full analysis or research documents (those are in .ace/artifacts/)
+        - Revision history or meeting notes
+
+    </guidelines>
+
+    <evolution>
+
+        ADRs are IMMUTABLE once accepted. They are historical records.
+
+        **When to create a new ADR:**
+        - A significant architectural or pattern choice is made during a story
+        - An existing decision is reversed or significantly modified (supersede the old one)
+        - A new technology, pattern, or approach is adopted
+
+        **When NOT to create an ADR:**
+        - Routine implementation following existing patterns
+        - Bug fixes or refactoring that don't change architectural direction
+        - Trivial decisions with no meaningful trade-offs
+        - Decisions already captured in an existing ADR
+
+        **Superseding:**
+        - Create the new ADR with its own number
+        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
+        - This is the ONLY edit allowed on an accepted ADR
+
+    </evolution>
+
+</decisions>

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

@@ -8,8 +8,8 @@
 
         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, and
-        decisions/ docs, all from a single call. Discovery does NOT pre-categorize modules
+        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
@@ -23,7 +23,7 @@
 
         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/, decisions/).
+        cross-cutting/, guides/, walkthroughs/, decisions/).
 
         | # | Module Name | Files | Relevant Docs |
         |---|-------------|-------|---------------|

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>

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