agile-context-engineering 0.3.0 → 0.5.1

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

@@ -1,178 +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>
+    <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>