agile-context-engineering 0.1.0 → 0.2.1

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

@@ -0,0 +1,343 @@
+<subsystem-architecture>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/architecture.md` — the internal
+        architecture view of a single subsystem. Captures component structure (C4 L3), internal
+        flows, dependency contracts, data ownership, and subsystem-specific decisions.
+
+        Complements system-architecture.md (which shows system-wide L1/L2 views).
+        Complements subsystem-structure.md (which shows physical file/folder layout).
+
+        One instance per subsystem — each gets its own architecture 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.
+    </purpose>
+
+    <template>
+        <subsystem-context>
+            ## [Subsystem Name]
+
+            **Responsibility:** [One-line — what this subsystem owns and does]
+            **Root:** `[path from project root]`
+
+            ### System Context
+
+            How this subsystem connects to the rest of the system:
+
+            | Relationship | Counterpart | Pattern | What Flows |
+            |-------------|-------------|---------|------------|
+            | Inbound | [Caller subsystem / external] | [Sync/Async, HTTP/gRPC/event] | [Data/command description] |
+            | Outbound | [Callee subsystem / external] | [Sync/Async, HTTP/gRPC/event] | [Data/command description] |
+        </subsystem-context>
+
+        <architectural-pattern>
+            ## Architectural Pattern
+
+            **Pattern:** [N-Tier / Clean Architecture / Onion / Hexagonal / Vertical Slice / CQRS / MVC / Simple Layered / Other]
+            **Detected from:** [e.g., "Domain/, Application/, Infrastructure/ folder hierarchy", "IRepository interfaces in core project", "Feature-first directory layout with per-slice handlers"]
+
+            [1-2 sentences: how the pattern manifests in this subsystem — what the layers are called,
+            how dependencies flow, and any notable deviations from the canonical pattern.]
+        </architectural-pattern>
+
+        <c4-l3-component>
+            ## L3: Internal Components
+
+            Shape this diagram to match the detected architectural pattern. Use the reference diagrams
+            in the guidelines section. Below is the Clean Architecture default — replace with the
+            appropriate structure for the actual pattern.
+
+            ```mermaid
+            flowchart TD
+                subgraph Entry["Entry Point(s)"]
+                    api["[API Layer]<br/><small>[Router/Controller/Handler]</small>"]
+                end
+
+                subgraph App["Application Layer"]
+                    svc["[Service / Use Case]<br/><small>[Orchestrates domain]</small>"]
+                end
+
+                subgraph Domain["Domain"]
+                    entity["[Domain Entity / Aggregate]<br/><small>[Core business logic]</small>"]
+                end
+
+                subgraph Infra["Infrastructure"]
+                    repo["[Repository]<br/><small>[Data access]</small>"]
+                    client["[External Client]<br/><small>[3rd-party / other subsystem]</small>"]
+                end
+
+                subgraph Data["Data"]
+                    db[("Data Store")]
+                end
+
+                api --> svc
+                svc --> entity
+                svc --> repo
+                svc --> client
+                repo --> db
+            ```
+
+            ### Component Responsibilities
+
+            | Component | Responsibility | Key Files |
+            |-----------|---------------|-----------|
+            | [API Layer] | [Receives and validates requests, maps to use cases] | `[path]` |
+            | [Service] | [Orchestrates domain logic and infrastructure] | `[path]` |
+            | [Domain] | [Business rules, entities, value objects] | `[path]` |
+            | [Repository] | [Persists and retrieves domain objects] | `[path]` |
+            | [External Client] | [Communicates with external system/subsystem] | `[path]` |
+        </c4-l3-component>
+
+        <internal-flows>
+            ## Key Internal Flows
+
+            The flows that define this subsystem's core operations.
+
+            ### Flow: [Flow Name]
+
+            [One sentence: what this achieves and when it triggers.]
+
+            ```mermaid
+            sequenceDiagram
+            participant Caller as [Caller / Entry]
+            participant Svc as [Service]
+            participant Domain as [Domain]
+            participant Repo as [Repository]
+            participant DB as [Data Store]
+
+            Caller->>Svc: [Request / command]
+            Svc->>Domain: [What is passed]
+            Domain-->>Svc: [Result / validated object]
+            Svc->>Repo: [Persist / query]
+            Repo->>DB: [SQL / query]
+            DB-->>Repo: [Result]
+            Repo-->>Svc: [Domain object]
+            Svc-->>Caller: [Response]
+            ```
+        </internal-flows>
+
+        <dependency-inventory>
+            ## Dependency Inventory
+
+            ### Inbound (Who calls this subsystem)
+
+            | Caller | Call Type | Contract | Notes |
+            |--------|-----------|----------|-------|
+            | [Subsystem / External] | [HTTP GET /path, Event: topic-name] | [OpenAPI / schema / event type] | [e.g., "authenticated calls only"] |
+
+            ### Outbound (What this subsystem calls)
+
+            | Dependency | Call Type | Contract | Failure Handling |
+            |------------|-----------|----------|-----------------|
+            | [Subsystem / External] | [HTTP / gRPC / SQL / event publish] | [OpenAPI / schema / event type] | [Retry, fallback, fail fast] |
+        </dependency-inventory>
+
+        <data-ownership>
+            ## Data Ownership
+
+            This subsystem owns the following data stores and schemas. Other subsystems MUST NOT
+            write directly — they interact through this subsystem's API or events.
+
+            | Store | Type | Schema / Namespace | Key Entities |
+            |-------|------|--------------------|--------------|
+            | [Table/collection/topic] | [Postgres/Mongo/Kafka] | [Schema name or prefix] | [Primary entities stored] |
+
+            **Data NOT owned here:** [Any data this subsystem reads but doesn't own, with note of true owner]
+        </data-ownership>
+
+        <subsystem-architectural-decisions>
+            ## Subsystem Architectural Decisions
+
+            Decisions specific to this subsystem. System-wide decisions live in system-architecture.md.
+
+            | Decision | Rationale |
+            |----------|-----------|
+            | [e.g., CQRS for this service] | [High read/write asymmetry — separate models] |
+            | [e.g., Repository pattern over direct ORM] | [Testability, ability to swap data store] |
+        </subsystem-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.**
+
+        **Architectural Pattern — How to Detect:**
+
+        Examine folder structure, namespaces, class names, and dependency directions. Match against
+        these signals — the first clear match wins. When signals overlap, note the hybrid.
+
+        - **N-Tier / Simple Layered** — Folders named `Controllers/`, `Services/` (or `BLL/`),
+          `Repositories/` (or `DAL/`). Direct downward dependencies: controller → service → repo.
+          No interface inversion — concrete classes reference each other directly.
+
+        - **MVC** — Framework-scaffolded `Models/`, `Views/`, `Controllers/` (or `Pages/` for
+          Razor Pages). Route handlers return views or JSON directly. Thin or no service layer.
+
+        - **Clean Architecture** — Explicit `Domain/`, `Application/`, `Infrastructure/`,
+          `Presentation/` (or `Web/`, `API/`) projects or folders. Domain has zero outgoing
+          dependencies. Application references Domain only. Infrastructure implements interfaces
+          defined in Application or Domain. Dependency rule strictly inward.
+
+        - **Onion Architecture** — Similar signals to Clean but layered as concentric rings:
+          `Core/` (domain model + domain services + application services), `Infrastructure/`,
+          optional `UI/`. Interfaces (ports) defined in Core; implementations in outer rings.
+
+        - **Hexagonal / Ports & Adapters** — Explicit `ports/` or `interfaces/` alongside
+          `adapters/` or `infrastructure/`. Primary adapters (HTTP, CLI) on one side; secondary
+          adapters (DB, messaging) on the other. Domain core has no framework imports.
+
+        - **Vertical Slice / Feature-First** — Feature-named top-level folders:
+          `Features/CreateOrder/`, `Features/ListOrders/`. Each slice contains its own handler,
+          validator, model, and tests. No shared service layer across features. Often uses a
+          mediator (MediatR, similar) — look for `IRequest`/`IRequestHandler` or equivalent.
+
+        - **CQRS** — Separate `Commands/` and `Queries/` (or `Read/` and `Write/`) directories.
+          Distinct models for reads vs. writes. May be combined with Event Sourcing
+          (`Events/`, `EventStore`, `Projections/`).
+
+        **Architectural Pattern — Diagram shapes per pattern:**
+
+        Use the reference below to choose the right diagram structure. Replace the default
+        Clean Architecture diagram in the template with the one matching the detected pattern.
+
+        *N-Tier:*
+        ```
+        flowchart TD
+            ctrl["Controller / Presenter"] --> svc["Service / Business Logic"]
+            svc --> repo["Repository / DAO"]
+            repo --> db[("Data Store")]
+        ```
+
+        *Clean Architecture / Onion:*
+        ```
+        flowchart TD
+            subgraph Presentation; api["Controller / Handler"]; end
+            subgraph Application; uc["Use Case / App Service"]; end
+            subgraph Domain; ent["Entity / Aggregate"]; port["Port Interface"]; end
+            subgraph Infrastructure; impl["Repository Impl"]; adapter["External Adapter"]; end
+            api --> uc
+            uc --> ent
+            uc --> port
+            impl -.->|implements| port
+            adapter -.->|implements| port
+        ```
+
+        *Hexagonal / Ports & Adapters:*
+        ```
+        flowchart LR
+            subgraph Primary["Primary Adapters (Driving)"]
+                http["HTTP Controller"]
+                cli["CLI Handler"]
+            end
+            subgraph Core["Domain Core"]
+                domain["Domain Logic"]
+                inport["Input Port"]
+                outport["Output Port"]
+            end
+            subgraph Secondary["Secondary Adapters (Driven)"]
+                dbrepo["DB Repository"]
+                msgclient["Messaging Client"]
+            end
+            http --> inport
+            cli --> inport
+            inport --> domain
+            domain --> outport
+            outport -.->|implements| dbrepo
+            outport -.->|implements| msgclient
+        ```
+
+        *Vertical Slice / Feature-First:*
+        ```
+        flowchart LR
+            subgraph SliceA["Feature: [Name A]"]
+                ha["Handler A"] --> va["Validator A"]
+                ha --> dba[("DB")]
+            end
+            subgraph SliceB["Feature: [Name B]"]
+                hb["Handler B"] --> vb["Validator B"]
+                hb --> dbb[("DB")]
+            end
+            entry["Entry / Mediator"] --> ha
+            entry --> hb
+        ```
+
+        *CQRS:*
+        ```
+        flowchart TD
+            entry["Entry / Mediator"]
+            subgraph Commands
+                ch["Command Handler"] --> domain["Domain / Aggregate"]
+                domain --> writedb[("Write Store")]
+            end
+            subgraph Queries
+                qh["Query Handler"] --> readdb[("Read Store / Projection")]
+            end
+            entry --> ch
+            entry --> qh
+        ```
+
+        **Subsystem Context:**
+        - One-line responsibility — NOT a paragraph. If you need more words, the boundary is wrong
+        - System context table: only show DIRECT inbound/outbound. No transitive dependencies
+        - Keep it brief — the full system view is in system-architecture.md
+
+        **L3 Component Diagram:**
+        - Layered top-to-bottom (entry → application → domain → infrastructure → data)
+        - Each box = a logical component, NOT a file or class
+        - Use `flowchart TD` for layered architectures (Clean Architecture, DDD) or `flowchart LR`
+          for pipeline/stream-processing subsystems
+        - Do NOT show method calls — this is component-level, not code-level
+        - Component table: key files must be actual paths within the subsystem
+
+        **Internal Flows:**
+        - 1-3 flows maximum. Choose flows a NEW DEVELOPER must understand to add a feature
+        - Component-level only — no method names, no line numbers, no class details
+        - Sequence diagram participants = components from the L3 diagram, not files
+        - If more than 3 flows are needed, this subsystem likely has multiple bounded operations —
+          consider separate docs per operation or split the subsystem
+
+        **Dependency Inventory:**
+        - Inbound: every caller of this subsystem, even if it's just one other subsystem
+        - Outbound: every dependency this subsystem calls — including data stores, caches, queues
+        - "Failure Handling" for outbound: what happens when that dependency is unavailable?
+
+        **Data Ownership:**
+        - Strict — document who OWNS the data, not just who reads it
+        - Include ALL data stores: relational tables, document collections, cache keys, message topics
+        - "Data NOT owned here" prevents confusion when a subsystem reads across ownership boundaries
+
+        **Subsystem Architectural Decisions:**
+        - Only decisions that deviate from system-wide defaults or are significant within the subsystem
+        - Skip obvious choices (e.g., don't document "we use async/await" in a Node.js service)
+        - Decision + Rationale only. No status tracking, no dates
+
+        **What does NOT belong here:**
+        - Physical file layout (that's subsystem-structure.md)
+        - System-wide tech stack (that's system-architecture.md)
+        - L1/L2 diagrams (that's system-architecture.md)
+        - Code-level detail like class signatures, method contracts (L4 — in code comments/docs)
+
+    </guidelines>
+
+    <evolution>
+
+        Update when this subsystem's internal architecture changes.
+
+        **Update triggers:**
+        - Architectural pattern changed (e.g., N-Tier refactored to Clean Architecture)
+        - New component layer added (e.g., adding CQRS, adding a cache layer)
+        - New inbound integration (new caller, new event type consumed)
+        - New outbound dependency (new API called, new data store added)
+        - Data ownership changes (new table, new schema, new topic)
+        - New subsystem-specific architectural decision made
+        - Core internal flow fundamentally changed (not just a new step in an existing flow)
+
+        **NOT an update trigger:**
+        - New feature following existing patterns
+        - Bug fixes or refactoring within existing components
+        - New API endpoint within existing handler
+        - New fields on existing entities
+
+    </evolution>
+
+</subsystem-architecture>

package/agile-context-engineering/templates/wiki/subsystem-structure.xml

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