agile-context-engineering 0.1.0 → 0.2.1

package/agile-context-engineering/templates/wiki/system-architecture.xml

@@ -0,0 +1,254 @@
+<system-architecture>
+    <purpose>
+        Template for `.docs/wiki/system-wide/system-architecture.md` — the living high-level
+        architecture document. Captures L1/L2 views (C4 model), core runtime flows, and tech stack.
+
+        Complements per-subsystem docs (which cover L3 Component and L4 Code levels).
+        Complements STRUCTURE.md (which shows physical file/folder layout).
+
+        A "subsystem" is any cohesive code unit with a clear responsibility boundary —
+        whether deployed as a microservice, a monolith module, or a library package.
+    </purpose>
+
+    <template>
+        <system-overview>
+            ## System Overview
+
+            [2-3 sentences. What does this system do and who uses it? Product language, not jargon.
+            This orients the reader before they look at any diagrams.]
+        </system-overview>
+
+        <c4-l1-system-context>
+            <diagram lang="mermaid" type="C4Context">
+                ## L1: System Context
+
+                ```mermaid
+                C4Context
+                title System Context - [System Name]
+
+                Person(user1, "[Primary User Role]", "[What they do with the system]")
+                Person(user2, "[Secondary User Role]", "[What they do]")
+
+                System(system, "[System Name]", "[Core purpose - one line]")
+
+                System_Ext(ext1, "[External System 1]", "[What it provides/consumes]")
+                System_Ext(ext2, "[External System 2]", "[What it provides/consumes]")
+
+                Rel(user1, system, "[Uses]", "[HTTPS/WebSocket]")
+                Rel(system, ext1, "[Fetches/Sends]", "[REST/WebSocket]")
+                Rel(ext2, system, "[Pushes]", "[Protocol]")
+                ```
+            </diagram>
+
+            <external-integrations-overview>
+                ### External Integrations
+
+                | External System | Direction | What Flows | Protocol |
+                |----------------|-----------|------------|----------|
+                | [System 1] | Inbound | [Data/events description] | [REST/WS/gRPC] |
+                | [System 2] | Outbound | [Data/events description] | [Protocol] |
+                | [System 3] | Bidirectional | [Data/events description] | [Protocol] |
+            </external-integrations-overview>
+        </c4-l1-system-context>
+
+        <c4-l2-container>
+            <diagram lang="mermaid" type="flowchart LR">
+                ## L2: Subsystem Overview
+
+                ```mermaid
+                flowchart LR
+                    subgraph Users
+                        user([fa:fa-user User Role])
+                    end
+
+                    subgraph Core["Core Services"]
+                        sub1["Subsystem 1<br/><small>Tech · One-line responsibility</small>"]
+                        sub2["Subsystem 2<br/><small>Tech · One-line responsibility</small>"]
+                    end
+
+                    subgraph Workers["Background Workers"]
+                        sub3["Subsystem 3<br/><small>Tech · One-line responsibility</small>"]
+                    end
+
+                    subgraph Data["Data Stores"]
+                        db1[(Data Store<br/><small>Tech</small>)]
+                        cache1[(Cache<br/><small>Tech</small>)]
+                    end
+
+                    subgraph Messaging["Messaging"]
+                        mq1>Message Broker<br/><small>Tech</small>]
+                    end
+
+                    subgraph External["External Systems"]
+                        ext1["External System<br/><small>From L1</small>"]
+                    end
+
+                    user -->|"HTTPS"| sub1
+                    sub1 -->|"HTTP/gRPC"| sub2
+                    sub2 -->|"SQL"| db1
+                    sub2 -->|"Publishes"| mq1
+                    mq1 -->|"Consumes"| sub3
+                    sub3 -->|"R/W"| cache1
+                    sub1 -->|"REST"| ext1
+                ```
+            </diagram>
+
+            <subsystem-responsibility-matrix>
+                ### Subsystem Responsibility Matrix
+
+                | Subsystem | Responsibility | Owns (Data) | Publishes | Consumes | Tech |
+                |-----------|---------------|-------------|-----------|----------|------|
+                | [Sub 1] | [One-line purpose] | [Tables/schemas] | [Events/APIs exposed] | [Events/APIs called] | [Lang + framework] |
+                | [Sub 2] | [One-line purpose] | [Tables/schemas] | [Events/APIs exposed] | [Events/APIs called] | [Lang + framework] |
+            </subsystem-responsibility-matrix>
+
+            <communication-patterns>
+                ### Communication Patterns
+
+                | From | To | Pattern | Protocol | Purpose |
+                |------|----|---------|----------|---------|
+                | [Sub 1] | [Sub 2] | Sync request-response | [HTTP/gRPC] | [Why this call exists] |
+                | [Sub 2] | [Sub 3] | Async event | [Kafka/Redis pub-sub] | [Why async over sync] |
+                | [Sub 3] | [Sub 1] | Real-time push | [SignalR/WebSocket] | [Why push over poll] |
+            </communication-patterns>
+        </c4-l2-container>
+
+        <main-flows>
+            ## Core Flows
+
+            The flows that define this system's core value. Subsystem-to-subsystem level only —
+            internal class-level details belong in per-subsystem docs.
+
+            <diagram lang="mermaid" type="sequenceDiagram">
+                ### Flow: [Flow Name]
+
+                [One sentence: what this achieves and when it triggers.]
+
+                ```mermaid
+                sequenceDiagram
+                participant Actor as [User/External]
+                participant S1 as [Subsystem 1]
+                participant S2 as [Subsystem 2]
+                participant MQ as [Broker]
+                participant S3 as [Subsystem 3]
+                participant DB as [Data Store]
+
+                Actor->>S1: [Trigger]
+                S1->>S2: [What passes]
+                S2->>DB: [Operation]
+                DB-->>S2: [Result]
+                S2->>MQ: [Publish event]
+                MQ-->>S3: [Consume]
+                S3-->>S1: [Push update]
+                S1-->>Actor: [Outcome]
+                ```
+            </diagram>
+        </main-flows>
+
+        <tech-stack>
+            ## Tech Stack
+
+            | Category | Technology | Version | Purpose |
+            |----------|-----------|---------|---------|
+            | Backend | [e.g., .NET] | [8.0] | [API services] |
+            | Frontend | [e.g., Next.js] | [15] | [Web application] |
+            | Database | [e.g., PostgreSQL] | [16] | [Primary store] |
+            | Cache | [e.g., Redis] | [7] | [Caching, pub/sub] |
+            | Messaging | [e.g., Kafka] | [3.x] | [Event streaming] |
+            | Real-time | [e.g., SignalR] | [-] | [Client push] |
+        </tech-stack>
+
+        <key-system-wide-architectural-decisions>
+            ## Key System Wide Architectural Decisions
+
+            System-wide decisions only. Per-subsystem decisions live in per-subsystem docs.
+
+            | Decision | Rationale |
+            |----------|-----------|
+            | [e.g., Clean Architecture per service] | [Consistent boundaries, testability] |
+            | [e.g., Kafka over RabbitMQ] | [Need replay, ordering, high throughput] |
+        </key-system-wide-architectural-decisions>
+    </template>
+
+    <guidelines>
+
+        **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.**
+
+        **System Overview:**
+        - 2-3 sentences maximum. Orients the AI before it reads diagrams
+        - Product language — a PM should understand it
+        - NOT a product vision or mission statement. Just "what this system does and who uses it"
+
+        **L1 System Context (`c4-l1-system-context`):**
+        - The ENTIRE system is ONE box — do NOT show internal subsystems
+        - Show ALL user roles (human actors) and ALL external systems (third-party)
+        - Diagram arrows: label with WHAT flows and WHICH protocol
+        - External = anything your team does NOT deploy. If you deploy it, it's a subsystem in L2
+        - Integrations table: one row per external system. Keep it simple — direction, data, protocol
+
+        **L2 Container (`c4-l2-container`):**
+        - Use `flowchart LR` with small focused subgraphs — data pipeline reads naturally left-to-right
+        - Group related nodes into subgraphs (e.g., "Core Services", "Data Stores", "External Systems")
+        - Keep subgraphs small (2-4 nodes each) — split large groups rather than making one big subgraph
+        - One node per subsystem (see "subsystem" definition in purpose)
+        - Data stores and message brokers are SEPARATE nodes — they are NOT subsystems
+        - Subsystem matrix is the quick-reference — agents scan this FIRST to find "who does what"
+        - Communication patterns table explains WHY each link exists and whether it's sync/async.
+        The diagram shows topology; the table explains rationale
+        - Do NOT show components within subsystems — that's L3, handled by per-subsystem docs
+
+        **Subsystem examples by project type:**
+        - Microservices: each service = one subsystem
+        - Monolith: each bounded context/module = one subsystem
+        - Monorepo packages: each publishable package = one subsystem
+        - Hybrid: mix of all three — anything with a clear boundary is a subsystem
+
+        **Core Flows (`main-flows`):**
+        - Generate however many flows define the system's core value (usually 1-2)
+        - Subsystem-to-subsystem only — NO classes, NO method names, NO file references
+        - If a flow needs internal detail, that belongs in the subsystem's `systems/*.md` doc
+        - These are C4 Dynamic Diagrams at the Container level
+        - Choose flows a NEW TEAM MEMBER must understand to work on the system
+
+        **Tech Stack:**
+        - List what's ACTUALLY in use, not aspirational
+        - One row per technology. Group by category
+        - If a technology is used by only one subsystem, mention it in Purpose
+
+        **Key System Wide Architectural Decisions:**
+        - System-wide only (e.g., "all services use Clean Architecture")
+        - Per-subsystem decisions go in per-subsystem docs
+        - Keep under 10 rows. This is a bird's eye view, not a decision log
+        - Decision + Rationale only. No tracking, no status, no dates
+
+    </guidelines>
+
+    <evolution>
+
+        This document evolves at STRUCTURAL changes only — not every story or bugfix.
+
+        **Update triggers:**
+        - New subsystem added, or existing one split/merged
+        - New external integration added or removed
+        - Core flow fundamentally changed (not just a step added)
+        - Tech stack changed (new database, new framework, migration)
+        - Communication pattern between subsystems changed
+        - New system-wide architectural decision made
+
+        **NOT an update trigger:**
+        - New feature within an existing subsystem (per-subsystem docs)
+        - Bug fixes or internal refactoring
+        - New API endpoints within existing subsystem
+        - New tables within existing subsystem's database
+
+        **After structural change:**
+        1. L1 still accurate? (new external system? removed integration?)
+        2. L2 still accurate? (new subsystem? new data store? new broker?)
+        3. Subsystem matrix need a new row or updated cell?
+        4. Core flow shape changed? (rare)
+        5. Tech stack changed?
+        6. New system-wide decision to log?
+
+    </evolution>
+
+</system-architecture>

package/agile-context-engineering/templates/wiki/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/agile-context-engineering/templates/wiki/system-structure.xml

@@ -0,0 +1,178 @@
+<system-structure>
+    <purpose>
+        Template for `.docs/wiki/system-wide/system-structure.md` — the physical file organization
+        at the system level. Answers "what subsystems exist and where do they live?"
+
+        Complements system-architecture.md (which shows conceptual design and flows).
+        Complements per-subsystem structure docs (which go deep into each subsystem's internals).
+
+        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>
+        <directory-layout>
+            ## Directory Layout
+
+            [ASCII box-drawing tree of directories with purpose - use ├── └── │ characters for tree structure only]
+
+            Show enough depth to identify subsystems and shared code, but stop at subsystem
+            boundaries — internal detail belongs in per-subsystem docs.
+
+            ```
+            [project-root]/
+            ├── [dir]/          # [Purpose]
+            ├── [dir]/          # [Purpose]
+            │   ├── [subdir]/   # [Purpose]
+            │   └── [subdir]/   # [Purpose]
+            ├── [dir]/          # [Purpose]
+            └── [file]          # [Purpose]
+            ```
+        </directory-layout>
+
+        <subsystem-index>
+            ## Subsystem Index
+
+            Quick reference — which directory is which subsystem.
+
+            | Directory | Subsystem | Purpose |
+            |-----------|-----------|---------|
+            | `[path]` | [Subsystem Name] | [One-line responsibility] |
+            | `[path]` | [Subsystem Name] | [One-line responsibility] |
+
+            Per-subsystem structure docs: `.docs/wiki/subsystems/[subsystem-name]/structure.md`
+        </subsystem-index>
+
+        <shared-directories>
+            ## Shared Directories
+
+            Code, libraries, or infrastructure that spans multiple subsystems.
+
+            **[Directory Name]:**
+            - Path: `[path]`
+            - Purpose: [What it provides across subsystems]
+            - Contains: [Types of files]
+            - Used by: [Which subsystems depend on it]
+
+            **[Directory Name]:**
+            - Path: `[path]`
+            - Purpose: [What it provides]
+            - Contains: [Types of files]
+            - Used by: [Which subsystems]
+        </shared-directories>
+
+        <root-configuration>
+            ## Root Configuration
+
+            Build configs, workspace setup, and infrastructure files at the project root.
+
+            **Workspace / Monorepo:**
+            - [Tool]: `[config file]` — [What it configures]
+
+            **Build / Dev:**
+            - `[path]`: [Purpose]
+            - `[path]`: [Purpose]
+
+            **CI/CD:**
+            - `[path]`: [Purpose]
+
+            **Environment:**
+            - `[path]`: [Purpose — e.g., "env template, actual values not committed"]
+        </root-configuration>
+
+        <naming-conventions>
+            ## System-Wide Naming Conventions
+
+            Patterns that apply across all subsystems.
+
+            **Directories:**
+            - [Pattern]: [Example]
+
+            **Files:**
+            - [Pattern]: [Example]
+
+            **Special Patterns:**
+            - [Pattern]: [Example]
+        </naming-conventions>
+
+        <special-directories>
+            ## Special Directories
+
+            Directories with special meaning — generated, build output, tooling.
+
+            **[Directory]:**
+            - Path: `[path]`
+            - Purpose: [e.g., "Build output", "Generated code", "Package cache"]
+            - Source: [e.g., "Auto-generated by X", "Build artifacts"]
+            - Committed: [Yes/No]
+        </special-directories>
+    </template>
+
+    <guidelines>
+
+        **Directory Layout:**
+        - Go deep enough to show where subsystems and shared code live, but stop at subsystem
+          boundaries. Internal subsystem structure belongs in per-subsystem docs
+        - Every directory gets a `# Purpose` comment
+        - Use ASCII box-drawing characters: `├── └── │`
+        - Do NOT list individual files except at root level (package.json, README, etc.)
+
+        **Subsystem Index:**
+        - One row per subsystem. This is the first thing agents scan
+        - Path should point to the subsystem root directory
+        - Purpose must be one line — if you need more, it goes in the subsystem doc
+        - Link to per-subsystem docs so agents know where to find detail
+
+        **Identifying subsystems by project type:**
+        - Microservices: each service directory = one subsystem
+        - Monolith modules: each bounded context / feature module = one subsystem
+        - Monorepo packages: each publishable package = one subsystem
+        - Hybrid: mix of all three — anything with a clear responsibility boundary
+
+        **Monolith examples:**
+        - Django app with `users/`, `orders/`, `payments/` apps → 3 subsystems
+        - .NET solution with `Auth.Module`, `Billing.Module`, `Notifications.Module` → 3 subsystems
+        - Express app with `src/features/auth/`, `src/features/checkout/` → 2 subsystems
+        - Small CLI tool with no clear modules → 1 subsystem (the whole app)
+
+        **Shared Directories:**
+        - Only list directories used by 2+ subsystems
+        - Common examples: shared libraries, generated clients, design tokens, DB migrations
+        - If a "shared" dir is only used by one subsystem, it belongs in that subsystem's doc
+
+        **Root Configuration:**
+        - Focus on files a developer needs to know about when setting up or building
+        - DO NOT list every dotfile. Focus on the ones that matter
+        - NEVER include contents of .env files — note existence only
+
+        **What does NOT belong here:**
+        - Conceptual architecture (that's system-architecture.md)
+        - Internal subsystem structure (that's subsystem-structure docs)
+        - Technology stack details (that's system-architecture.md tech-stack section)
+        - Code conventions (that's a separate conventions doc)
+
+    </guidelines>
+
+    <evolution>
+
+        Update when the physical organization of the system changes.
+
+        **Update triggers:**
+        - New subsystem added (new service, new module, new package)
+        - Subsystem removed, split, or merged
+        - Shared directory added or removed
+        - Workspace/monorepo configuration changed
+        - Root-level config files added or removed
+
+        **NOT an update trigger:**
+        - New files within an existing subsystem (per-subsystem docs)
+        - New features within existing structure
+        - Internal refactoring that doesn't change directory layout
+
+    </evolution>
+
+</system-structure>