agile-context-engineering 0.2.2 → 0.5.0

package/skills/map-system/templates/wiki-readme.xml

@@ -0,0 +1,297 @@
+<wiki-readme>
+      <purpose>
+          Template for `.docs/wiki/wiki-readme.md` — the entry point and usage guide for the
+          engineering wiki. Generated once when the `.docs/wiki/` directory is first created
+          (typically by `/ace:map-system`).
+
+          Serves two audiences:
+          - **Humans** who want to understand, navigate, and contribute to the wiki
+          - **AI agents** who need to know which documents to load for a given task
+
+          This is NOT a documentation template — it is a META-DOCUMENT that describes how the
+          wiki itself works. Think of it as the README for the wiki system.
+      </purpose>
+
+      <template>
+          <header>
+              # Engineering Wiki
+
+              Living knowledge base for this codebase. Maintained by AI agents after each story
+              and by developers when making structural changes.
+
+              **For humans**: browse by subsystem, read system and pattern docs to understand how things work.
+              **For AI agents**: load the minimal set of docs needed for your current task — every token counts.
+          </header>
+
+          <directory-structure>
+              ## Directory Structure
+
+              ```
+              .docs/wiki/
+              |-- wiki-readme.md                          # This file — how to use the wiki
+              |-- system-wide/                            # Documents that span all subsystems
+              |   |-- system-structure.md                 # Physical layout, subsystem index, shared dirs
+              |   |-- system-architecture.md              # L1/L2 C4 views, core flows, tech stack
+              |   |-- testing-framework.md                # Test runner, patterns, conventions
+              |   |-- coding-standards.md                 # Language and paradigm-specific rules
+              |   `-- tech-debt-index.md                  # Roll-up of all known tech debt
+              `-- subsystems/
+                  `-- [subsystem-name]/                    # One folder per subsystem
+                      |-- structure.md                     # File layout, "where to add code"
+                      |-- architecture.md                  # L3 components, internal flows, dependencies
+                      |-- systems/                         # WHAT exists — domain system docs
+                      |   `-- [system-name].md
+                      |-- patterns/                        # HOW to implement — reusable structural patterns
+                      |   `-- [pattern-name].md
+                      |-- cross-cutting/                   # Shared infrastructure spanning systems
+                      |   `-- [concern-name].md
+                      |-- guides/                          # Step-by-step implementation recipes
+                      |   `-- [task-name].md
+                      |-- walkthroughs/                    # Deep tutorial-style flow explanations
+                      |   `-- [flow-name].md
+                      `-- decisions/                       # WHY — Architecture Decision Records
+                          `-- ADR-NNN-[slug].md
+              ```
+          </directory-structure>
+
+          <document-types>
+              ## Document Types
+
+              ### System-Wide Documents
+
+              | Document | Answers | Created By |
+              |----------|---------|------------|
+              | `system-structure.md` | What subsystems exist and where do they live? | `/ace:map-system` |
+              | `system-architecture.md` | What's the system design, tech stack, and core flows? | `/ace:map-system` |
+              | `testing-framework.md` | How do we test? Runner, patterns, conventions. | `/ace:map-system` |
+              | `coding-standards.md` | What are the mandatory code quality rules? | `/ace:init-coding-standards` |
+              | `tech-debt-index.md` | What known quality issues exist across the codebase? | `/ace:map-story` (auto) |
+
+              ### Subsystem Documents
+
+              | Document | Answers | Created By |
+              |----------|---------|------------|
+              | `structure.md` | Where do files live in this subsystem? Where do I add new code? | `/ace:map-subsystem` |
+              | `architecture.md` | What are the internal components, layers, and flows? | `/ace:map-subsystem` |
+
+              ### Knowledge Documents (per subsystem)
+
+              | Category | Answers | Style | When to Create |
+              |----------|---------|-------|----------------|
+              | `systems/` | How does this domain system work RIGHT NOW? | Terse reference (bullet points, component lists) | One doc per coherent domain capability (e.g., drawing system, order processing) |
+              | `patterns/` | How do I implement using this reusable pattern? | Structure + how-to-apply recipe | When a structural pattern appears in 2+ implementations |
+              | `cross-cutting/` | How does this shared infrastructure work? | Terse reference | For concerns spanning multiple domain systems (DI, events, registry) |
+              | `guides/` | How do I perform this recurring task end-to-end? | Numbered steps, procedural | When a task is repeated (adding a new tool, endpoint, entity) |
+              | `walkthroughs/` | Walk me through EXACTLY what happens when X | Tutorial-style, code snippets, framework explanations | When a complex flow spans multiple classes/frameworks and needs deep understanding |
+              | `decisions/` | Why was this significant choice made? | ADR format (context, decision, consequences) | When a meaningful trade-off was evaluated and decided |
+          </document-types>
+
+          <how-to-use>
+              ## How to Use This Wiki
+
+              ### For Humans
+
+              **Understand a subsystem:**
+              1. Read `subsystems/[name]/architecture.md` — components, layers, internal flows
+              2. Read relevant `systems/*.md` — domain systems you care about
+              3. Read `walkthroughs/*.md` — deep explanations of complex flows with code snippets
+              4. Follow cross-references to patterns and cross-cutting concerns
+
+              **Implement a new feature:**
+              1. Read `system-wide/coding-standards.md` — mandatory rules
+              2. Read the subsystem's `structure.md` — where to add files
+              3. Check `guides/` — there may be a step-by-step recipe for your task
+              4. Check `walkthroughs/` — understand the flow you're extending before writing code
+              5. Read relevant `patterns/` — follow established structural patterns
+              6. Check `decisions/` — respect past architectural decisions
+
+              **Onboard a new developer (or intern):**
+              1. Start with `system-wide/system-architecture.md` — the big picture
+              2. Read `walkthroughs/` for the subsystem they'll work on — these are written to teach, not just reference
+              3. Read `coding-standards.md` — non-negotiable rules
+              4. Then dive into `systems/` and `patterns/` for specifics
+
+              **Debug or investigate:**
+              1. Start with the relevant `systems/*.md` — it has entry points, flows, and components
+              2. Read the relevant `walkthroughs/*.md` — trace the exact flow step by step with actual code
+              3. Follow the sequence diagrams to trace data flow
+              4. Check `cross-cutting/` for shared infrastructure behavior
+
+              ### For AI Agents
+
+              **Context loading strategy:**
+              - ALWAYS load system-wide docs first: `system-structure.md`, `system-architecture.md`, `coding-standards.md`, `testing-framework.md`
+              - Then load subsystem docs for the subsystem(s) you are modifying
+              - Load ONLY the `systems/`, `patterns/`, `cross-cutting/`, `guides/`, and `walkthroughs/` docs relevant to your task
+              - Check `decisions/` for ADRs that constrain your design choices
+              - `walkthroughs/` are larger documents — load them only when you need to understand a complex flow in depth
+              - Every token in your context window costs reasoning capacity — load less, reason better
+
+              **Finding the right docs:**
+              - Story files include a `## Relevant Wiki` section with curated doc references
+              - Each doc cross-references related docs via markdown links — follow them as needed
+              - `structure.md` -> where files live; `architecture.md` -> how things connect
+              - `systems/` -> domain behavior; `patterns/` -> structural recipes; `guides/` -> task recipes
+              - `walkthroughs/` -> deep understanding of complex flows (read when you need to UNDERSTAND, not just implement)
+          </how-to-use>
+
+          <how-to-create>
+              ## Creating New Wiki Documents
+
+              Wiki documents are primarily created and updated by AI agents (ace-wiki-mapper) through:
+              - `/ace:map-system` — system-wide documents
+              - `/ace:map-subsystem` — subsystem structure, architecture, and knowledge docs
+              - `/ace:map-story` — updates knowledge docs after story implementation
+
+              ### Manual Creation Guidelines
+
+              If creating a document manually, follow these rules:
+
+              **Naming:**
+              - Use kebab-case for all file names: `drawing-system.md`, `repository-pattern.md`
+              - Systems: name after the domain capability — `drawing-system.md`, `order-processing.md`
+              - Patterns: name after the pattern — `template-method-pattern.md`, `repository-pattern.md`
+              - Cross-cutting: name after the concern — `dependency-injection.md`, `event-system.md`
+              - Guides: name after the task — `adding-drawing-tool.md`, `adding-crud-endpoint.md`
+              - Walkthroughs: name after the flow — `tool-execution-pipeline.md`, `order-lifecycle.md`
+              - Decisions: `ADR-NNN-kebab-slug.md` — sequential numbering within the subsystem
+
+              **Content rules:**
+              - EXTREMELY SUCCINCT — every word must add value (except walkthroughs, which prioritize depth and clarity)
+              - Bullet points over paragraphs
+              - Code references: `file-path:ClassName.methodName` — never line numbers
+              - All architecture diagrams MUST be mermaid (flowchart, classDiagram, sequenceDiagram)
+              - File trees: ASCII only (`|--` and backtick for last item)
+              - Inline code ONLY for interface/type contracts (systems, patterns) or actual implementation snippets (walkthroughs)
+              - Cross-reference related docs with markdown links
+              - Every `systems/*.md` MUST have at least one mermaid sequenceDiagram
+              - Every `walkthroughs/*.md` MUST have at least one mermaid sequenceDiagram AND actual code snippets from the codebase
+
+              **Topic-scoped, not story-scoped:**
+              - Documents describe a CONCERN, not a story or sprint
+              - "How does the drawing system work?" — good
+              - "What story #19 implemented" — wrong (that goes in `.ace/artifacts/`)
+
+              **Create vs update decision:**
+              1. Does an existing doc already cover this topic? -> UPDATE it
+              2. Could this be a new section in an existing doc? -> Add the section
+              3. Any overlap with existing docs? -> Merge into the existing doc
+              4. Genuinely new topic with no overlap? -> CREATE a new doc
+
+              **When to create a walkthrough vs a system doc:**
+              - **System doc**: the domain system is well-bounded, an AI agent needs a quick reference to implement a related story
+              - **Walkthrough**: the flow is complex, spans multiple classes or frameworks, a human needs to UNDERSTAND how it works before they can work with it. If you find yourself writing paragraphs of explanation with code snippets in a system doc, it should be a walkthrough instead
+          </how-to-create>
+
+          <keeping-current>
+              ## Keeping the Wiki Current
+
+              ### Automatic Updates
+
+              After each story implementation, `/ace:map-story` analyzes git changes and updates
+              the relevant knowledge documents. This is the primary mechanism for keeping the wiki
+              current.
+
+              ### Manual Update Triggers
+
+              **Update `system-structure.md` when:**
+              - New subsystem added, removed, or merged
+              - Shared directory added or removed
+              - Workspace configuration changed
+
+              **Update `system-architecture.md` when:**
+              - New subsystem or external integration added
+              - Communication pattern changed
+              - Tech stack changed
+
+              **Update `testing-framework.md` when:**
+              - Test runner or mocking approach changed
+              - Coverage requirements changed
+
+              **Update subsystem `structure.md` when:**
+              - Top-level directory added, renamed, or removed within the subsystem
+
+              **Update subsystem `architecture.md` when:**
+              - New architectural layer or component type introduced
+              - New inbound or outbound dependency added
+
+              **Update knowledge docs when:**
+              - `systems/` — new component, behavior, entry point, or integration point
+              - `patterns/` — new implementation added, pattern structure changed
+              - `cross-cutting/` — new registration, mechanism changed
+              - `guides/` — new step required, step order changed, reference implementation changed
+              - `walkthroughs/` — flow changed (new step, removed step, framework upgrade), new framework concept introduced, code snippets no longer match actual code
+              - `decisions/` — NEVER edit accepted ADRs; create a new one that supersedes
+
+              ### Tech Debt
+
+              Tech debt items are tracked in individual `systems/` and `cross-cutting/` docs (## Tech Debt section)
+              and rolled up in `system-wide/tech-debt-index.md`. Items are removed when fixed.
+          </keeping-current>
+
+          <subsystem-index>
+              ## Subsystems
+
+              [POPULATE FROM system-structure.md — list each subsystem with link to its wiki folder]
+
+              | Subsystem | Wiki Path | Responsibility |
+              |-----------|-----------|----------------|
+              | [name] | [subsystems/name/](subsystems/name/) | [one-line responsibility] |
+          </subsystem-index>
+      </template>
+
+      <guidelines>
+
+          **This is a META-DOCUMENT, not a code documentation template.**
+          It describes the wiki system itself — its structure, conventions, and usage.
+          It does NOT contain code references, mermaid diagrams, or architectural content.
+
+          **Populating the template:**
+          - The Directory Structure section is FIXED — it describes the standard wiki layout.
+            Do NOT customize it per project. It shows the canonical structure.
+          - The Document Types tables are FIXED — they describe what each document type is.
+          - The Subsystems table at the bottom MUST be populated from `system-structure.md`
+            (the subsystem index). If `system-structure.md` doesn't exist yet, leave the table
+            with placeholder rows and a note to populate after `/ace:map-system`.
+          - All wiki paths in the Subsystems table should be relative links from the wiki root.
+
+          **Tone:**
+          - Direct and practical — this is a reference, not a tutorial
+          - Written for two audiences in parallel: humans and AI agents
+          - Short sentences, bullet points, tables over prose
+          - No filler, no motivational text, no history
+
+          **What does NOT belong here:**
+          - Actual code documentation (that lives in the wiki docs themselves)
+          - Project-specific architecture details (that's system-architecture.md)
+          - Process details about ACE workflows (that's internal to the tool)
+          - Story or feature information
+          - Revision history
+
+      </guidelines>
+
+      <evolution>
+
+          This document is MOSTLY STABLE — it describes the wiki system, which rarely changes.
+
+          **Update triggers:**
+          - New document type added to the wiki system (e.g., a new knowledge category)
+          - New subsystem mapped (update the Subsystems table)
+          - Subsystem removed or renamed (update the Subsystems table)
+          - Wiki conventions changed (naming rules, diagram rules, reference format)
+
+          **NOT an update trigger:**
+          - New documents created within existing categories
+          - Content updates to any wiki document
+          - New stories, features, or sprints
+          - Changes to ACE tool internals
+
+          **Update rules:**
+          - UPDATE the Subsystems table when subsystems are added/removed
+          - The rest of the document should rarely need changes
+          - If the wiki structure itself evolves (new folders, new doc types), update the
+            Directory Structure and Document Types sections
+
+      </evolution>
+
+  </wiki-readme>

package/{agile-context-engineering/workflows/map-system.xml → skills/map-system/workflow.xml}

@@ -29,19 +29,14 @@
         <step name="setup" order="1">
             **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
 
-            ```bash
-            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init map-system)
-            ```
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
 
-            Parse JSON for: `mapper_model`, `commit_docs`, `is_brownfield`, `is_greenfield`,
+            Parse INIT JSON for: `mapper_model`, `commit_docs`, `is_brownfield`, `is_greenfield`,
             `has_existing_code`, `has_package_file`, `wiki_dir_exists`, `existing_wiki_files`,
             `has_system_structure`, `has_system_architecture`, `has_testing_framework`,
             `has_coding_standards`, `has_git`.
 
-            Also resolve the mapper model for spawning agents:
-            ```bash
-            MAPPER_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-wiki-mapper --raw)
-            ```
+            MAPPER_MODEL is available from INIT.mapper_model — do NOT re-run resolve-model.
 
             Display stage banner:
 
@@ -178,7 +173,7 @@
             **Generate wiki-readme.md if it does not already exist:**
 
             Check if `.docs/wiki/wiki-readme.md` exists. If it does NOT exist, generate it
-            from the wiki-readme template (`~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml`).
+            from the wiki-readme template (`${CLAUDE_SKILL_DIR}/templates/wiki-readme.xml`).
 
             Read the template's `<template>` section and write the markdown content to
             `.docs/wiki/wiki-readme.md`. This is a mostly-static meta-document — fill it
@@ -223,7 +218,7 @@
 
                 Analyze this codebase and produce the system-wide structure document.
 
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-structure.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-structure.xml
                 **Output:** Write to .docs/wiki/system-wide/system-structure.md
 
                 Follow the template structure. Fill every section with real data from the codebase.
@@ -247,7 +242,7 @@
                 UPDATE the existing system structure document.
 
                 **Current document:** Read .docs/wiki/system-wide/system-structure.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-structure.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-structure.xml
 
                 Compare the current document against the actual codebase state.
                 Update sections that are stale. Add new subsystems or shared directories
@@ -298,7 +293,7 @@
 
                 Analyze this codebase and produce the testing framework document.
 
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/testing-framework.xml
                 **Output:** Write to .docs/wiki/system-wide/testing-framework.md
 
                 Check package.json/config files for test runner and scripts.
@@ -325,7 +320,7 @@
                 UPDATE the existing testing framework document.
 
                 **Current document:** Read .docs/wiki/system-wide/testing-framework.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/testing-framework.xml
 
                 Compare against current codebase state. Update stale sections only.
                 Check for new test runner config, new test patterns, changed coverage settings.
@@ -374,7 +369,7 @@
 
                 Analyze this codebase and produce the system-wide architecture document.
 
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
                 **Output:** Write to .docs/wiki/system-wide/system-architecture.md
 
                 **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
@@ -406,7 +401,7 @@
                 UPDATE the existing system architecture document.
 
                 **Current document:** Read .docs/wiki/system-wide/system-architecture.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
                 **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
 
                 Compare against current codebase state. Check:
@@ -512,7 +507,7 @@
                 **Architecture brief from user interview:**
                 {paste the context brief here}
 
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
                 **Output:** Write to .docs/wiki/system-wide/system-architecture.md
 
                 **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md

package/skills/map-walkthrough/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: map-walkthrough
+description: Create deep tutorial-style flow walkthroughs in .docs/wiki/subsystems/[name]/walkthroughs/
+argument-hint: "flow='tick data from bybit websocket to timescaledb' subsystem='data-ingestion' emphasis-frameworks='SignalR,Redis Streams'"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - LSP
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+# Map Walkthrough
+
+Create deep tutorial-style flow walkthroughs that trace a flow end-to-end through the codebase.
+
+## When to Use
+
+- After `/ace:map-subsystem` — to create deep walkthroughs for complex flows
+- Anytime a complex multi-class flow needs human-readable documentation
+- When onboarding new developers who need to understand specific flows
+- A flow spans 3+ classes across multiple architectural layers
+- External frameworks/libraries are involved that need explanation
+- An intern reading the code alone would not understand what's happening
+- A system doc would need paragraphs of explanation with code snippets
+
+## Input
+
+### Required
+
+- **`flow`** (text) — Natural language description of the end-to-end flow — WHERE it starts and WHERE it ends. The agent finds the entry point, follows every call through the entire code, and traces it to the exit point. E.g.: "tick data from bybit websocket to timescaledb", "user message from SignalR hub until LLM response is sent back", "order placement from API endpoint to payment confirmation". If not provided, pause and ask the user.
+
+- **`subsystem`** (path | text) — Subsystem where the walkthrough wiki file is placed. The flow itself may span MULTIPLE subsystems — the agent follows the code wherever it goes. This parameter only determines the wiki location: `.docs/wiki/subsystems/[subsystem]/walkthroughs/`. If not provided, pause and ask the user.
+
+### Optional
+
+- **`emphasis-frameworks`** (csv) — Comma-separated frameworks/libraries/APIs/SDKs that should receive deep explanation throughout the walkthrough. When specified: EVERY step touching the framework gets a framework info box, ALL code interacting with the framework is shown and explained, the Framework Concepts Reference table becomes MANDATORY. Each entry is EITHER: a name (agent researches via WebSearch/context7) like "SignalR" or "SignalR,EF Core"; a file path or URL to documentation; or a mix of both.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Walkthrough template**: Read [walkthrough.xml](walkthrough.xml) — output format for the walkthrough
+- **Questioning guide**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml` — deep questioning techniques
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` — ACE output formatting rules
+
+## Process
+
+Use the `ace-wiki-mapper` agent that's specialized in wiki exploration and documentation writing.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, user questions, commits).
+
+**Objective:** Create or update a deep tutorial-style walkthrough that traces a flow end-to-end. The agent reads the flow description, finds the entry point in the codebase, then follows EVERY SINGLE CALL through the entire code — handler to service to repository to database (or whatever the flow touches) — using LSP and code reading. It discovers all files automatically, extracts emphasis framework usages from the actual code, researches those specific concepts, and writes the walkthrough with real code snippets and framework info boxes.
+
+## Artifacts
+
+```
+.docs/wiki/subsystems/[subsystem-name]/walkthroughs/[flow-name].md
+```
+
+## Example Usage
+
+```
+# Basic walkthrough
+/ace:map-walkthrough flow='tick data from bybit websocket to timescaledb' subsystem='data-ingestion'
+
+# With emphasis frameworks
+/ace:map-walkthrough flow='user message from SignalR hub until LLM response is sent back' subsystem='chat' emphasis-frameworks='SignalR,Redis Streams'
+
+# With documentation link as emphasis
+/ace:map-walkthrough flow='order placement from API endpoint to payment confirmation' subsystem='orders' emphasis-frameworks='https://learn.microsoft.com/aspnet/signalr/overview,EF Core'
+```
+
+## Next Steps
+
+- `/clear` first for a fresh context window
+- `/ace:map-walkthrough` — create another walkthrough
+- `/ace:map-subsystem [subsystem]` — map or refresh an entire subsystem
+- Review and edit files in `.docs/wiki/subsystems/[subsystem-name]/walkthroughs/`