agile-context-engineering 0.3.0 → 0.5.0

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/`

package/skills/map-walkthrough/walkthrough.xml

@@ -0,0 +1,255 @@
+<walkthrough>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/walkthroughs/<flow-name>.md` — a deep,
+        tutorial-style explanation of a complex end-to-end flow. Answers "Walk me through EXACTLY
+        what happens when X."
+
+        Each walkthrough traces a single flow from entry point to exit point, showing ACTUAL code
+        from the codebase at every step, explaining what each piece does and WHY, and calling out
+        framework/library concepts with info boxes when external tools are involved.
+
+        Written for humans (especially new developers and interns) who need to UNDERSTAND a flow
+        before they can work with it. Unlike system docs (terse references for AI agents),
+        walkthroughs prioritize completeness of information — but deliver it in minimal words.
+
+        A "walkthrough" is a traced execution flow through multiple classes and layers:
+        e.g., "Message arrives via SignalR until it reaches the LLM", "LLM calls a tool until
+        the drawing appears on the chart", "User places an order until it's confirmed".
+
+        Create a walkthrough when:
+        - A flow spans 3+ classes across multiple architectural layers
+        - External frameworks/libraries are involved that need explanation (MAF, SignalR, EF Core)
+        - A system doc would need paragraphs of explanation with code snippets (that's a walkthrough, not a system doc)
+        - An intern reading the code alone would not understand what's happening without guidance
+
+        **Emphasis Frameworks:**
+        Walkthroughs can specify one or more "emphasis frameworks" — external frameworks,
+        libraries, APIs, or SDKs that deserve deep explanation throughout the walkthrough.
+        When an emphasis framework is specified:
+        - EVERY step where the flow touches that framework MUST have a framework info box
+        - The info box explains the specific framework concept used in that step
+        - ALL code from ALL steps that interact with the emphasis framework is shown and explained
+        - The agent researches the framework (via WebSearch/context7 or provided docs) if needed
+        - The Framework Concepts Reference table at the end is MANDATORY
+
+        Examples of emphasis frameworks: SignalR, EF Core, MAF (Microsoft Agent Framework),
+        React Query, gRPC, MediatR, AutoMapper. Can be specified by name (agent researches)
+        or with documentation paths/URLs (agent reads provided docs).
+
+        Complements:
+        - systems/ docs (terse WHAT reference — walkthroughs explain the HOW in depth)
+        - patterns/ docs (reusable structural patterns — walkthroughs trace specific flows through them)
+        - guides/ docs (procedural recipes for DOING — walkthroughs explain for UNDERSTANDING)
+        - cross-cutting/ docs (shared infrastructure — walkthroughs show how flows pass through them)
+    </purpose>
+
+    <template>
+        <title>
+            # [Flow Name]
+
+            One line: what this flow does and when it triggers.
+        </title>
+
+        <file-map>
+            ## Files Involved
+
+            Every file this flow touches, in execution order.
+
+            ```
+            src/[layer]/[area]/
+            |-- FileA.cs                    # Entry point
+            |-- FileB.cs                    # Orchestrates flow
+            |-- FileC.cs                    # Core logic
+            `-- FileD.cs                    # Sends result
+            ```
+        </file-map>
+
+        <flow-diagram>
+            ## Flow Overview
+
+            ```mermaid
+            sequenceDiagram
+                participant A as ComponentA
+                participant B as ComponentB
+                participant C as ComponentC
+                participant D as ExternalSystem
+
+                A->>B: step description
+                B->>C: step description
+                C->>D: step description
+                D-->>C: response
+                C-->>B: result
+                B-->>A: result
+            ```
+
+            Participants = real classes/components. Arrows = real method calls.
+            Steps below explain each arrow.
+        </flow-diagram>
+
+        <steps>
+            ## Step-by-Step
+
+            ### Step 1: [What happens]
+
+            **File:** `path/to/File.cs:ClassName.MethodName`
+
+            [1-2 sentences: what this step does and WHY. No filler.]
+
+            ```csharp
+            // Actual code from the codebase
+            public async Task MethodName(string param1, string param2)
+            {
+                var result = await _dependency.DoSomething(param1);
+            }
+            ```
+
+            `_dependency` — injected via constructor, does X.
+            `param1` — the Y received from Z.
+            [Only explain what's non-obvious. Skip what the code already says clearly.]
+
+            ---
+
+            ### Step 2: [What happens]
+
+            **File:** `path/to/AnotherFile.cs:ClassName.MethodName`
+
+            [What and why — terse.]
+
+            ```csharp
+            // Actual code...
+            ```
+
+            > **[Framework]: [Concept]**
+            >
+            > [Succinct explanation of the framework concept. What it is, what it does for us.
+            > No history, no alternatives, no "in general" — just what the reader needs to
+            > understand THIS code.]
+            >
+            > *Source: [link to official docs]*
+
+            ---
+
+            ### Step 3: [What happens]
+
+            ...continue for every step in the flow...
+        </steps>
+
+        <framework-concepts>
+            ## Framework Concepts Reference
+
+            Consolidated lookup for framework concepts explained inline above.
+
+            | Concept | Framework | What It Does | First Appearance |
+            |---------|-----------|-------------|------------------|
+            | `AIFunctionFactory.Create()` | MS Agent Framework | C# method -> LLM tool | [Step N](#step-n) |
+            | `ChatClientAgent` | MS Agent Framework | Wraps IChatClient with auto tool loop | [Step M](#step-m) |
+
+            Include ONLY if external frameworks/libraries are involved.
+        </framework-concepts>
+
+        <related-docs>
+            ## Related Documentation
+
+            - [System Doc](../systems/relevant-system.md) — terse reference
+            - [Guide](../guides/relevant-guide.md) — recipe for adding to this flow
+            - [Official Docs](../framework-docs/relevant-page.md) — framework docs
+        </related-docs>
+    </template>
+
+    <guidelines>
+
+        ### Density Over Prose
+        - **EXTREMELY SUCCINCT** — every word must add value. If a word does not add value, remove it.
+        - **NO FLUFF** — no introductions, no summaries of what the section will contain, no transitions
+        - Bullet points over paragraphs. Tables over bullet points when comparing.
+        - If you can say it in 3 words, don't use 10. Then try to say it in 2.
+        - **BUT: ALL needed information MUST be present.** Succinctness means cutting WORDS, not cutting INFORMATION. Every concept, every parameter, every non-obvious behavior must be explained — just in fewer words.
+
+        ### Complete but Dense Explanations
+        - Explain the WHY, not just the WHAT — "X because Y" not "X happens"
+        - After each code snippet: explain ONLY what's non-obvious. If the code says `price > 0`, don't write "checks that price is positive" — the code already says that. DO explain hidden behaviors, framework magic, non-obvious field origins.
+        - Use inline code references for fields/params: `` `_connectionId` — captured from `Context.ConnectionId` in AgentHub ``
+        - One-line explanations preferred. Multi-line only when genuinely complex.
+
+        ### Code Snippets (MANDATORY per step)
+        - ALWAYS from the actual codebase — verified by reading the file
+        - NEVER pseudocode, NEVER summaries, NEVER fabricated
+        - Use correct language tag: ```csharp, ```typescript, ```json
+        - **FOCUSED**: show ONLY the lines relevant to what the step is explaining. If a method has 50 lines but this step is about lines 10-15, show lines 10-15 with a `// ... (validation above)` or `// ... (setup omitted)` comment for context. The snippet serves the step's explanation, not the other way around.
+        - Short methods (under 20 lines) where the ENTIRE method is relevant: show entirely
+        - Long methods: show the relevant portion only. Use `// ...` comments to indicate omitted sections above/below.
+
+        ### Flow Diagram (MANDATORY)
+        - Every walkthrough MUST start with a mermaid sequenceDiagram
+        - Participants = real classes/components, not abstract concepts
+        - Arrows = real method calls, labeled with method name
+        - The diagram is the map; the steps are the guided tour
+
+        ### Framework Info Boxes (when applicable)
+        - Use markdown blockquotes (`>`) with `> **[Framework]: [Concept]**` header
+        - Explain as if the reader has NEVER used this framework — but in minimal words
+        - Place IMMEDIATELY after the first code snippet that uses the concept
+        - Each concept explained ONCE — do not repeat
+        - Link to official docs with `*Source: [link]*`
+        - Keep it dense: what it is, what it does for us, done. No history, no alternatives.
+
+        ### Emphasis Frameworks (when specified)
+        - When emphasis-frameworks are specified, framework info boxes become MANDATORY
+          for EVERY step that touches the emphasis framework — not just the first occurrence
+        - ALL code that interacts with the emphasis framework must be shown in full
+        - The Framework Concepts Reference table is MANDATORY (not optional)
+        - If the agent does not know the framework: use WebSearch or context7 MCP to research it
+        - If framework docs are provided (file paths or URLs): read them BEFORE writing any steps
+
+        ### Minimum Length
+        - At least 300 lines — length comes from code snippets and completeness, not from prose
+        - Complex flows (3+ frameworks, 10+ classes): 500-1000 lines
+        - Under 200 lines = not enough information, add more steps/explanations
+
+        ### Section Inclusion
+        - Title, File Map, Flow Diagram, Step-by-Step: ALWAYS required
+        - Framework Concepts Reference: MANDATORY if emphasis-frameworks specified; otherwise ONLY if external frameworks involved
+        - Related Documentation: ALWAYS required
+
+        ### What Does NOT Belong Here
+        - Terse bullet-point references (that's systems/)
+        - Structural pattern descriptions (that's patterns/)
+        - Procedural "how to add X" recipes (that's guides/)
+        - Architecture decision rationale (that's decisions/)
+        - Story numbers, sprint context, revision history
+        - Testing instructions or test code
+        - Frontend code in a backend walkthrough (or vice versa) — scope to ONE side
+        - Speculation about future changes — document what IS, not what might be
+        - Filler phrases: "Let's look at", "Now we'll examine", "As mentioned above", "It's worth noting"
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the flow it describes changes.
+
+        **Update triggers:**
+        - New step added to the flow
+        - Step removed from the flow
+        - Step logic changed significantly
+        - Framework/library upgraded, APIs changed
+        - Code snippets no longer match codebase
+        - New framework concept introduced
+
+        **NOT an update trigger:**
+        - Bug fixes that don't change flow structure
+        - Internal refactoring within a single step
+        - New feature using a DIFFERENT flow (create a new walkthrough)
+        - Style/formatting changes to the code
+
+        **Update rules:**
+        - UPDATE code snippets to match current codebase — stale snippets are worse than no docs
+        - ADD new steps when the flow gains a stage
+        - REMOVE steps that no longer exist
+        - UPDATE framework info boxes when APIs change
+        - UPDATE mermaid diagram to reflect current flow
+        - Document must always reflect CURRENT code state, not history
+
+    </evolution>
+
+</walkthrough>

package/skills/plan-backlog/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: plan-backlog
+description: Create or refine the product backlog through vision-aware questioning, wiki analysis, and guided epic/feature planning
+argument-hint: "[optional: context='text, file, or URL with product description and suggested epics/features']"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Task, AskUserQuestion
+model: opus
+effort: high
+---
+
+# Plan Backlog
+
+Create or refine the product backlog through vision-aware questioning, wiki analysis, and guided epic/feature planning.
+
+## When to Use
+
+- After `/ace:plan-product-vision` — once the vision exists, plan what to build
+- After `/ace:map-system` — once architecture is mapped, leverage wiki context for richer backlog
+- Anytime — to create or refresh the product backlog
+- Product vision exists and you want to break it into epics and features
+- Starting implementation planning and need a structured backlog
+- Brownfield project where features need to be inventoried from existing code
+- Updating the backlog after scope changes or new discoveries
+
+## Input
+
+### Optional
+
+- **`context`** — Product description, suggested epics/features, PRD excerpts, or any context to seed the backlog planning process. Will be absorbed and refined through questioning, not used as-is.
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **Product backlog template**: Read [product-backlog-template.xml](product-backlog-template.xml) — output format for the product backlog
+- **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-product-owner` agent for requirements gathering, deep questioning, and backlog specification.
+
+The Environment Context above contains the preprocessed INIT JSON — use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
+
+## Artifacts
+
+```
+.ace/artifacts/product/product-backlog.md
+```
+
+## Example Usage
+
+```
+# Create a new product backlog
+/ace:plan-backlog
+
+# Create backlog with seed context
+/ace:plan-backlog context="E-commerce platform with user accounts, product catalog, and checkout"
+
+# Refine existing backlog after scope changes
+/ace:plan-backlog
+```
+
+## Next Steps
+
+- `/ace:plan-feature E1` — Break a feature into detailed stories
+- `/ace:help` — Check project initialization status
+- `/ace:plan-product-vision` — Update the product vision if priorities shifted