agile-context-engineering 0.3.0 → 0.5.1

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

@@ -1,235 +1,235 @@
-<subsystem-structure>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/structure.md` — the physical file
-        organization within a single subsystem. Answers "I'm working in this subsystem, where do I put things?"
-
-        Complements system-structure.md (which shows the system-wide layout and subsystem index).
-        One instance per subsystem — each gets its own structure doc.
-
-        A "subsystem" is any cohesive code unit with a clear responsibility boundary —
-        whether deployed as a microservice, a monolith module, or a library package.
-
-        **Monoliths have subsystems too.** A monolith with bounded contexts, feature modules,
-        or domain packages gets one subsystem-structure doc per module — same as microservices.
-        The only difference is deployment topology, not documentation structure.
-    </purpose>
-
-    <template>
-        <subsystem-overview>
-            ## [Subsystem Name]
-
-            **Root:** `[path from project root]`
-            **Responsibility:** [One-line purpose — what this subsystem owns]
-        </subsystem-overview>
-
-        <directory-layout>
-            ## Directory Layout
-
-            [ASCII box-drawing tree of ALL directories and files with purpose - use ├── └── │ characters for tree structure only]
-
-            Complete file tree of this subsystem. List every file and directory — this is the
-            full inventory. An agent reading this should know exactly what exists without running `ls`.
-
-            ```
-            [subsystem-root]/
-            ├── [dir]/              # [Purpose]
-            │   ├── [subdir]/       # [Purpose]
-            │   │   └── [subdir]/   # [Purpose]
-            │   └── [subdir]/       # [Purpose]
-            ├── [dir]/              # [Purpose]
-            │   ├── [subdir]/       # [Purpose]
-            │   └── [file]          # [Purpose]
-            ├── [dir]/              # [Purpose]
-            └── [file]              # [Purpose]
-            ```
-        </directory-layout>
-
-        <directory-purposes>
-            ## Directory Purposes
-
-            **[Directory Name]:**
-            - Purpose: [What lives here]
-            - Contains: [Types of files: e.g., "*.ts source files", "component directories"]
-            - Key files: `[important files in this directory]`
-            - Subdirectories: [If nested, describe structure]
-
-            **[Directory Name]:**
-            - Purpose: [What lives here]
-            - Contains: [Types of files]
-            - Key files: `[important files]`
-            - Subdirectories: [Structure]
-        </directory-purposes>
-
-        <key-file-locations>
-            ## Key File Locations
-
-            **Entry Points:**
-            - `[path]`: [Purpose — e.g., "HTTP server startup", "CLI entry point"]
-
-            **Configuration:**
-            - `[path]`: [Purpose — e.g., "Module config", "DI container setup"]
-
-            **Core Logic:**
-            - `[path]`: [Purpose — e.g., "Domain services", "Business rules"]
-            - `[path]`: [Purpose — e.g., "Data access", "Repository implementations"]
-
-            **API Surface:**
-            - `[path]`: [Purpose — e.g., "Route definitions", "Controller handlers"]
-            - `[path]`: [Purpose — e.g., "DTOs / request-response types"]
-
-            **Testing:**
-            - `[path]`: [Purpose — e.g., "Unit tests"]
-            - `[path]`: [Purpose — e.g., "Test fixtures / factories"]
-        </key-file-locations>
-
-        <naming-conventions>
-            ## Naming Conventions
-
-            Subsystem-specific patterns. If this subsystem follows system-wide conventions
-            without deviation, state: "Follows system-wide conventions — see system-structure.md"
-
-            **Files:**
-            - [Pattern]: [Example — e.g., "kebab-case.ts for modules"]
-            - [Pattern]: [Example — e.g., "PascalCase.tsx for React components"]
-            - [Pattern]: [Example — e.g., "PascalCase.cs for C# classes"]
-            - [Pattern]: [Example — e.g., "*.test.ts co-located with source"]
-
-            **Directories:**
-            - [Pattern]: [Example — e.g., "kebab-case for feature directories"]
-            - [Pattern]: [Example — e.g., "plural names for collections"]
-
-            **Special Patterns:**
-            - [Pattern]: [Example — e.g., "index.ts barrel exports per directory"]
-            - [Pattern]: [Example — e.g., "__tests__/ for test directories"]
-        </naming-conventions>
-
-        <where-to-add-new-code>
-            ## Where to Add New Code
-
-            **New Feature:**
-            - Primary code: `[directory path]`
-            - Tests: `[directory path]`
-            - Config if needed: `[directory path]`
-
-            **New Component / Module:**
-            - Implementation: `[directory path]`
-            - Types: `[directory path]`
-            - Tests: `[directory path]`
-
-            **New Route / Endpoint / Command:**
-            - Definition: `[directory path]`
-            - Handler: `[directory path]`
-            - Tests: `[directory path]`
-
-            **New Domain Entity / Model:**
-            - Entity: `[directory path]`
-            - Repository: `[directory path]`
-            - Tests: `[directory path]`
-
-            **New Service / Use Case:**
-            - Service: `[directory path]`
-            - Use case / application logic: `[directory path]`
-            - Interface / contract: `[directory path]`
-            - Tests: `[directory path]`
-
-            **New DTO / Request-Response Object:**
-            - DTOs: `[directory path]`
-            - Validators: `[directory path]`
-
-            **New Mapper / Transformer:**
-            - Mappers: `[directory path]`
-
-            **New Constants / Enums:**
-            - Constants: `[directory path]`
-            - Enums: `[directory path]`
-            - Magic values / lookup tables: `[directory path]`
-
-            **New Database Script / Migration:**
-            - Migrations: `[directory path]`
-            - Seeds / fixtures: `[directory path]`
-            - Stored procedures: `[directory path]`
-
-            **Shared Kernel / Cross-Cutting:**
-            - Shared kernel: `[directory path]`
-            - Base classes / interfaces: `[directory path]`
-            - Common exceptions: `[directory path]`
-            - Extension methods / helpers: `[directory path]`
-
-            **Utilities:**
-            - Shared helpers: `[directory path]`
-            - Type definitions: `[directory path]`
-        </where-to-add-new-code>
-
-        <special-directories>
-            ## Special Directories
-
-            Directories with special meaning within this subsystem.
-
-            **[Directory]:**
-            - Purpose: [e.g., "Generated code", "Build output", "Migrations"]
-            - Source: [e.g., "Auto-generated by X", "Manually maintained"]
-            - Committed: [Yes/No]
-        </special-directories>
-    </template>
-
-    <guidelines>
-
-        **Subsystem Overview:**
-        - Root path must be relative to project root — agents use this to navigate
-        - Responsibility is one line. If you need more, it goes in the subsystem architecture doc
-
-        **Directory Layout:**
-        - List EVERY file and directory. This is the complete inventory of the subsystem
-        - Every directory gets a `# Purpose` comment
-        - Every file gets a `# Purpose` comment
-        - Use ASCII box-drawing characters: `├── └── │`
-        - Skip node_modules, build output, and other generated dirs (mention in Special Directories)
-
-        **Directory Purposes:**
-        - One entry per directory that has meaningful content
-        - "Key files" should list the 2-3 most important files a developer would look at first
-        - Skip directories that are obvious from the tree (e.g., don't describe `tests/` if it just has tests)
-
-        **Key File Locations:**
-        - Paths must be relative to subsystem root
-        - Group by role, not by directory
-        - Every entry needs a purpose — `user.service.ts` tells you nothing; "Core user CRUD operations" does
-        - Focus on files a developer touches when working on this subsystem
-
-        **Where to Add New Code:**
-        - This is the most actionable section. An agent reads this when creating new files
-        - Be specific — `src/features/[feature-name]/` not "the features directory"
-        - Cover the common cases for this subsystem's domain
-
-        **Naming Conventions:**
-        - Only document if this subsystem has patterns different from system-wide conventions
-        - If it follows system-wide conventions exactly, say so and link to system-structure.md
-        - Show actual examples from the codebase, not theoretical patterns
-
-        **What does NOT belong here:**
-        - Conceptual architecture (that's the subsystem architecture doc)
-        - Technology stack (that's system-architecture.md)
-        - Code conventions like formatting rules (that's a conventions doc)
-        - Other subsystems' structure (each has its own doc)
-
-    </guidelines>
-
-    <evolution>
-
-        Update when the physical layout of this subsystem changes.
-
-        **Update triggers:**
-        - New top-level directory added within subsystem
-        - Directory renamed, moved, or removed
-        - New entry point or configuration file added
-        - Naming convention changed
-        - "Where to add new code" guidance no longer accurate
-
-        **NOT an update trigger:**
-        - New files added within existing directories
-        - New features that follow existing structure
-        - Bug fixes or internal refactoring
-
-    </evolution>
-
+<subsystem-structure>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/structure.md` — the physical file
+        organization within a single subsystem. Answers "I'm working in this subsystem, where do I put things?"
+
+        Complements system-structure.md (which shows the system-wide layout and subsystem index).
+        One instance per subsystem — each gets its own structure doc.
+
+        A "subsystem" is any cohesive code unit with a clear responsibility boundary —
+        whether deployed as a microservice, a monolith module, or a library package.
+
+        **Monoliths have subsystems too.** A monolith with bounded contexts, feature modules,
+        or domain packages gets one subsystem-structure doc per module — same as microservices.
+        The only difference is deployment topology, not documentation structure.
+    </purpose>
+
+    <template>
+        <subsystem-overview>
+            ## [Subsystem Name]
+
+            **Root:** `[path from project root]`
+            **Responsibility:** [One-line purpose — what this subsystem owns]
+        </subsystem-overview>
+
+        <directory-layout>
+            ## Directory Layout
+
+            [ASCII box-drawing tree of ALL directories and files with purpose - use ├── └── │ characters for tree structure only]
+
+            Complete file tree of this subsystem. List every file and directory — this is the
+            full inventory. An agent reading this should know exactly what exists without running `ls`.
+
+            ```
+            [subsystem-root]/
+            ├── [dir]/              # [Purpose]
+            │   ├── [subdir]/       # [Purpose]
+            │   │   └── [subdir]/   # [Purpose]
+            │   └── [subdir]/       # [Purpose]
+            ├── [dir]/              # [Purpose]
+            │   ├── [subdir]/       # [Purpose]
+            │   └── [file]          # [Purpose]
+            ├── [dir]/              # [Purpose]
+            └── [file]              # [Purpose]
+            ```
+        </directory-layout>
+
+        <directory-purposes>
+            ## Directory Purposes
+
+            **[Directory Name]:**
+            - Purpose: [What lives here]
+            - Contains: [Types of files: e.g., "*.ts source files", "component directories"]
+            - Key files: `[important files in this directory]`
+            - Subdirectories: [If nested, describe structure]
+
+            **[Directory Name]:**
+            - Purpose: [What lives here]
+            - Contains: [Types of files]
+            - Key files: `[important files]`
+            - Subdirectories: [Structure]
+        </directory-purposes>
+
+        <key-file-locations>
+            ## Key File Locations
+
+            **Entry Points:**
+            - `[path]`: [Purpose — e.g., "HTTP server startup", "CLI entry point"]
+
+            **Configuration:**
+            - `[path]`: [Purpose — e.g., "Module config", "DI container setup"]
+
+            **Core Logic:**
+            - `[path]`: [Purpose — e.g., "Domain services", "Business rules"]
+            - `[path]`: [Purpose — e.g., "Data access", "Repository implementations"]
+
+            **API Surface:**
+            - `[path]`: [Purpose — e.g., "Route definitions", "Controller handlers"]
+            - `[path]`: [Purpose — e.g., "DTOs / request-response types"]
+
+            **Testing:**
+            - `[path]`: [Purpose — e.g., "Unit tests"]
+            - `[path]`: [Purpose — e.g., "Test fixtures / factories"]
+        </key-file-locations>
+
+        <naming-conventions>
+            ## Naming Conventions
+
+            Subsystem-specific patterns. If this subsystem follows system-wide conventions
+            without deviation, state: "Follows system-wide conventions — see system-structure.md"
+
+            **Files:**
+            - [Pattern]: [Example — e.g., "kebab-case.ts for modules"]
+            - [Pattern]: [Example — e.g., "PascalCase.tsx for React components"]
+            - [Pattern]: [Example — e.g., "PascalCase.cs for C# classes"]
+            - [Pattern]: [Example — e.g., "*.test.ts co-located with source"]
+
+            **Directories:**
+            - [Pattern]: [Example — e.g., "kebab-case for feature directories"]
+            - [Pattern]: [Example — e.g., "plural names for collections"]
+
+            **Special Patterns:**
+            - [Pattern]: [Example — e.g., "index.ts barrel exports per directory"]
+            - [Pattern]: [Example — e.g., "__tests__/ for test directories"]
+        </naming-conventions>
+
+        <where-to-add-new-code>
+            ## Where to Add New Code
+
+            **New Feature:**
+            - Primary code: `[directory path]`
+            - Tests: `[directory path]`
+            - Config if needed: `[directory path]`
+
+            **New Component / Module:**
+            - Implementation: `[directory path]`
+            - Types: `[directory path]`
+            - Tests: `[directory path]`
+
+            **New Route / Endpoint / Command:**
+            - Definition: `[directory path]`
+            - Handler: `[directory path]`
+            - Tests: `[directory path]`
+
+            **New Domain Entity / Model:**
+            - Entity: `[directory path]`
+            - Repository: `[directory path]`
+            - Tests: `[directory path]`
+
+            **New Service / Use Case:**
+            - Service: `[directory path]`
+            - Use case / application logic: `[directory path]`
+            - Interface / contract: `[directory path]`
+            - Tests: `[directory path]`
+
+            **New DTO / Request-Response Object:**
+            - DTOs: `[directory path]`
+            - Validators: `[directory path]`
+
+            **New Mapper / Transformer:**
+            - Mappers: `[directory path]`
+
+            **New Constants / Enums:**
+            - Constants: `[directory path]`
+            - Enums: `[directory path]`
+            - Magic values / lookup tables: `[directory path]`
+
+            **New Database Script / Migration:**
+            - Migrations: `[directory path]`
+            - Seeds / fixtures: `[directory path]`
+            - Stored procedures: `[directory path]`
+
+            **Shared Kernel / Cross-Cutting:**
+            - Shared kernel: `[directory path]`
+            - Base classes / interfaces: `[directory path]`
+            - Common exceptions: `[directory path]`
+            - Extension methods / helpers: `[directory path]`
+
+            **Utilities:**
+            - Shared helpers: `[directory path]`
+            - Type definitions: `[directory path]`
+        </where-to-add-new-code>
+
+        <special-directories>
+            ## Special Directories
+
+            Directories with special meaning within this subsystem.
+
+            **[Directory]:**
+            - Purpose: [e.g., "Generated code", "Build output", "Migrations"]
+            - Source: [e.g., "Auto-generated by X", "Manually maintained"]
+            - Committed: [Yes/No]
+        </special-directories>
+    </template>
+
+    <guidelines>
+
+        **Subsystem Overview:**
+        - Root path must be relative to project root — agents use this to navigate
+        - Responsibility is one line. If you need more, it goes in the subsystem architecture doc
+
+        **Directory Layout:**
+        - List EVERY file and directory. This is the complete inventory of the subsystem
+        - Every directory gets a `# Purpose` comment
+        - Every file gets a `# Purpose` comment
+        - Use ASCII box-drawing characters: `├── └── │`
+        - Skip node_modules, build output, and other generated dirs (mention in Special Directories)
+
+        **Directory Purposes:**
+        - One entry per directory that has meaningful content
+        - "Key files" should list the 2-3 most important files a developer would look at first
+        - Skip directories that are obvious from the tree (e.g., don't describe `tests/` if it just has tests)
+
+        **Key File Locations:**
+        - Paths must be relative to subsystem root
+        - Group by role, not by directory
+        - Every entry needs a purpose — `user.service.ts` tells you nothing; "Core user CRUD operations" does
+        - Focus on files a developer touches when working on this subsystem
+
+        **Where to Add New Code:**
+        - This is the most actionable section. An agent reads this when creating new files
+        - Be specific — `src/features/[feature-name]/` not "the features directory"
+        - Cover the common cases for this subsystem's domain
+
+        **Naming Conventions:**
+        - Only document if this subsystem has patterns different from system-wide conventions
+        - If it follows system-wide conventions exactly, say so and link to system-structure.md
+        - Show actual examples from the codebase, not theoretical patterns
+
+        **What does NOT belong here:**
+        - Conceptual architecture (that's the subsystem architecture doc)
+        - Technology stack (that's system-architecture.md)
+        - Code conventions like formatting rules (that's a conventions doc)
+        - Other subsystems' structure (each has its own doc)
+
+    </guidelines>
+
+    <evolution>
+
+        Update when the physical layout of this subsystem changes.
+
+        **Update triggers:**
+        - New top-level directory added within subsystem
+        - Directory renamed, moved, or removed
+        - New entry point or configuration file added
+        - Naming convention changed
+        - "Where to add new code" guidance no longer accurate
+
+        **NOT an update trigger:**
+        - New files added within existing directories
+        - New features that follow existing structure
+        - Bug fixes or internal refactoring
+
+    </evolution>
+
 </subsystem-structure>

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>