agile-context-engineering 0.5.0 → 0.5.1

package/skills/map-story/SKILL.md

@@ -1,127 +1,180 @@
----
-name: map-story
-description: Update living knowledge docs — either after a story implementation (git-based, with new subsystem detection) or for existing undocumented code (file-based, called by map-subsystem)
-argument-hint: "story-context='.ace/artifacts/...' commits=3  |  files='a.ts,b.ts' module-name='User Management' subsystem-name='api'"
-disable-model-invocation: true
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - Task
-  - AskUserQuestion
-  - Agent
-model: opus
-effort: max
----
-
-# Map Story
-
-Update living knowledge docs after story implementation or for existing undocumented code.
-
-## When to Use
-
-### Story Mode (invoked by user)
-- After a story is implemented and tested
-- Analyzes git changes (diff) to determine what was built
-- Reads story artifacts for intent context
-- Detects affected subsystem(s) from changed file paths
-- Creates or updates living knowledge docs to reflect the CURRENT system state
-- Detects NEW subsystems not yet in system-structure.md and offers full mapping via map-subsystem
-
-### File Mode (invoked by map-subsystem Step 8.7)
-- Called automatically during subsystem mapping
-- Receives a curated file list + module metadata from module-discovery
-- Documents existing undocumented code — no git diff needed
-- Receives pre-curated existing documentation as additional context
-
-## Input
-
-### Mode Detection
-
-- If `files` is provided → file mode
-- If `story-context` is provided → story mode
-- If neither is provided → story mode (staged + unstaged changes)
-
-### Story Mode Parameters
-
-**Optional:**
-
-- **`story-context`** (path) — Path to story artifacts folder (in `.ace/artifacts/` or legacy `documentation/features/`). Used to understand WHAT the story intended to build. If not provided, the agent relies solely on git changes.
-- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze. As a number: analyze the N most recent commits (e.g., commits=3). As commit SHAs: analyze specific commits (e.g., commits='abc123,def456'). When not provided: analyze staged + unstaged changes (git diff + git diff --cached).
-- **`tech-debt`** (text | path) — Tech debt items discovered during code review. Can be plain text, YAML, or a path to a file containing the items. When provided, the wiki mapper integrates these items into the relevant subsystem wiki docs (## Tech Debt sections) AND updates the system-wide tech-debt-index.md.
-
-### File Mode Parameters
-
-**Required:**
-
-- **`files`** (comma-separated paths) — Source code files to document. These are the files discovered by module-discovery (Step 8.5) that together form one coherent module.
-- **`module-name`** (text) — Human-readable name of the module (e.g., "User Management", "Repository Pattern").
-- **`subsystem-name`** (text) — Name of the subsystem this module belongs to.
-
-**Optional:**
-
-- **`existing-docs`** (comma-separated paths or directories) — Pre-existing documentation relevant to this module. Accepts file paths, directory paths, or a mix of both. When a directory is provided, recursively discover all files within it. Read these FIRST for additional context about intent, decisions, and history. The actual source code remains the source of truth; existing docs provide the WHY.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **System template**: Read [templates/system.xml](templates/system.xml) — system document format
-- **Cross-cutting template**: Read [templates/system-cross-cutting.xml](templates/system-cross-cutting.xml) — cross-cutting concern format
-- **Pattern template**: Read [templates/pattern.xml](templates/pattern.xml) — pattern document format
-- **Guide template**: Read [templates/guide.xml](templates/guide.xml) — guide document format
-- **Walkthrough template**: Read [templates/walkthrough.xml](templates/walkthrough.xml) — walkthrough format
-- **Decisions template**: Read [templates/decizions.xml](templates/decizions.xml) — decisions document format
-- **Tech debt index template**: Read [templates/tech-debt-index.xml](templates/tech-debt-index.xml) — tech debt index format
-- **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
-
-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:** Read the provided source code files (and any existing docs for context), then autonomously create or update living knowledge documents. One call may produce multiple docs across different categories (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/).
-
-In story mode: analyze git changes to determine what was built, detect affected subsystem(s), identify NEW subsystems not yet in system-structure.md (offering full map-subsystem mapping with user approval), and update/create docs to reflect the CURRENT system state. Also suggests potential walkthroughs for complex flows discovered in the code — the user can choose to create them.
-
-In file mode: document existing undocumented code from the provided file list.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/systems/[system-name].md
-.docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
-.docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-name].md
-.docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
-.docs/wiki/subsystems/[subsystem-name]/walkthroughs/[flow-name].md (if user approves suggestions)
-.docs/wiki/subsystems/[subsystem-name]/decisions/[decision-name].md
-.docs/wiki/system-wide/system-structure.md (updated if new subsystem mapped)
-.docs/wiki/system-wide/system-architecture.md (updated if new subsystem mapped)
-```
-
-## Example Usage
-
-```
-# After a story implementation (staged + unstaged changes)
-/ace:map-story
-
-# After a story with specific commits
-/ace:map-story story-context='.ace/artifacts/product/e1-auth/f2-login/s1-form/s1-form.md' commits=3
-
-# For existing undocumented code (called by map-subsystem)
-/ace:map-story files='a.ts,b.ts' module-name='User Management' subsystem-name='api'
-
-# With tech debt items from code review
-/ace:map-story story-context='.ace/artifacts/...' tech-debt='Missing error handling in auth flow'
-```
-
-## Next Steps
-
-- `/clear` first for a fresh context window
-- `/ace:map-story` — document another story or module
-- `/ace:map-subsystem [subsystem]` — map or refresh an entire subsystem
-- Review and edit files in `.docs/wiki/subsystems/[subsystem-name]/`
+---
+name: map-story
+description: Update living knowledge docs — either after a story implementation (git-based, with new subsystem detection) or for existing undocumented code (file-based, called by map-subsystem)
+argument-hint: "story-context='.ace/artifacts/...' commits=3  |  files='a.ts,b.ts' module-name='User Management' subsystem-name='api'"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Task
+  - AskUserQuestion
+  - Agent
+model: opus
+effort: max
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/system.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/system-cross-cutting.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/pattern.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/guide.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/walkthrough.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/decizions.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/tech-debt-index.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <mode name="story" invoked-by="user">
+            <trigger>After a story is implemented and tested</trigger>
+            <trigger>Analyzes git changes (diff) to determine what was built</trigger>
+            <trigger>Reads story artifacts for intent context</trigger>
+            <trigger>Detects affected subsystem(s) from changed file paths</trigger>
+            <trigger>Creates or updates living knowledge docs to reflect the CURRENT system state</trigger>
+            <trigger>Detects NEW subsystems not yet in system-structure.md and offers full mapping via map-subsystem</trigger>
+        </mode>
+        <mode name="file" invoked-by="map-subsystem Step 8.7">
+            <trigger>Called automatically during subsystem mapping</trigger>
+            <trigger>Receives a curated file list + module metadata from module-discovery</trigger>
+            <trigger>Documents existing undocumented code — no git diff needed</trigger>
+            <trigger>Receives pre-curated existing documentation as additional context</trigger>
+        </mode>
+        <use-when mode="story">
+            <condition>You just finished implementing and testing a story</condition>
+            <condition>You want to update docs to reflect recent code changes</condition>
+            <condition>You want to capture decisions and patterns from a recent implementation</condition>
+        </use-when>
+        <use-when mode="file">
+            <condition>/ace:map-subsystem — for each module row in module-discovery.md</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <mode-detection>
+                <rule>If `files` is provided -> file mode</rule>
+                <rule>If `story-context` is provided -> story mode</rule>
+                <rule>If neither is provided -> story mode (staged + unstaged changes)</rule>
+            </mode-detection>
+
+            <story-mode>
+                <required></required>
+                <optional>
+                    <param name="story-context" type="path">
+                        Path to story artifacts folder (in `.ace/artifacts/` or legacy `documentation/features/`).
+                        Used to understand WHAT the story intended to build.
+                        If not provided, the agent relies solely on git changes.
+                    </param>
+                    <param name="commits" type="number | comma-separated commit SHAs">
+                        Specifies which commits to analyze.
+                        As a number: analyze the N most recent commits (e.g., commits=3).
+                        As commit SHAs: analyze specific commits (e.g., commits='abc123,def456').
+                        When not provided: analyze staged + unstaged changes (git diff + git diff --cached).
+                    </param>
+                    <param name="tech-debt" type="text | path">
+                        Tech debt items discovered during code review.
+                        Can be plain text, YAML, or a path to a file containing the items.
+                        When provided, the wiki mapper integrates these items into the
+                        relevant subsystem wiki docs (## Tech Debt sections) AND updates
+                        the system-wide tech-debt-index.md.
+                    </param>
+                </optional>
+            </story-mode>
+
+            <file-mode>
+                <required>
+                    <param name="files" type="comma-separated paths">
+                        Source code files to document. These are the files discovered by
+                        module-discovery (Step 8.5) that together form one coherent module.
+                    </param>
+                    <param name="module-name" type="text">
+                        Human-readable name of the module (e.g., "User Management", "Repository Pattern").
+                    </param>
+                    <param name="subsystem-name" type="text">
+                        Name of the subsystem this module belongs to.
+                    </param>
+                </required>
+                <optional>
+                    <param name="existing-docs" type="comma-separated paths or directories">
+                        Pre-existing documentation relevant to this module. Accepts file paths,
+                        directory paths, or a mix of both. When a directory is provided,
+                        recursively discover all files within it (including nested subdirectories).
+                        Typically curated by module-discovery's synthesis agent or passed through
+                        from map-subsystem. Read these FIRST for additional context about intent,
+                        decisions, and history. The actual source code remains the source of truth;
+                        existing docs provide the WHY.
+                    </param>
+                </optional>
+            </file-mode>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <!-- All supporting files are auto-loaded in the Supporting Resources section above.
+             The model does NOT need to Read these files — they are already in context. -->
+    </execution-context>
+
+    <output>
+        <objective>
+            Read the provided source code files (and any existing docs for context),
+            then autonomously create or update living knowledge documents.
+            One call may produce multiple docs across different categories
+            (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/).
+
+            In story mode: analyze git changes to determine what was built, detect
+            affected subsystem(s), identify NEW subsystems not yet in system-structure.md
+            (offering full map-subsystem mapping with user approval), and update/create
+            docs to reflect the CURRENT system state. Also suggests potential walkthroughs
+            for complex flows discovered in the code — the user can choose to create them.
+
+            In file mode: document existing undocumented code from the provided file list.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/systems/[system-name].md
+            .docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
+            .docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-name].md
+            .docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
+            .docs/wiki/subsystems/[subsystem-name]/walkthroughs/[flow-name].md (if user approves suggestions)
+            .docs/wiki/subsystems/[subsystem-name]/decisions/[decision-name].md
+            .docs/wiki/system-wide/system-structure.md (updated if new subsystem mapped)
+            .docs/wiki/system-wide/system-architecture.md (updated if new subsystem mapped)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-story workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        <step>/clear first for a fresh context window</step>
+        <step>/ace:map-story — document another story or module</step>
+        <step>/ace:map-subsystem [subsystem] — map or refresh an entire subsystem</step>
+        <step>Review and edit files in .docs/wiki/subsystems/[subsystem-name]/</step>
+    </next-steps>
+
+</command>
+```

package/skills/map-story/templates/tech-debt-index.xml

@@ -1,125 +1,125 @@
-<tech-debt-index>
-    <purpose>
-        Template for `.docs/wiki/system-wide/tech-debt-index.md` — a cross-cutting index of all
-        known tech debt across the entire codebase. Answers "What quality issues exist, where,
-        and how severe are they?"
-
-        This is a roll-up document maintained by the wiki mapper after each story execution.
-        The ace-code-reviewer discovers tech debt during review; the wiki mapper records it here
-        AND in the relevant subsystem/system wiki docs.
-
-        Complements:
-        - Subsystem wiki docs (each has its own ## Tech Debt section with local items)
-        - coding-standards.md (defines what IS a violation; this doc tracks EXISTING violations)
-    </purpose>
-
-    <template>
-        <header>
-            # Tech Debt Index
-
-            **Last updated**: [YYYY-MM-DD]
-            **Total items**: [N] ([high] high, [medium] medium, [low] low)
-        </header>
-
-        <summary-table>
-            ## Summary by Subsystem
-
-            | Subsystem | High | Medium | Low | Total | Wiki Doc |
-            |-----------|------|--------|-----|-------|----------|
-            | [name]    | [n]  | [n]    | [n] | [n]   | [link to wiki doc] |
-            | **Total** | [n]  | [n]    | [n] | [n]   | |
-        </summary-table>
-
-        <by-subsystem>
-            ## By Subsystem
-
-            ### [subsystem-name] ([N] items)
-            **Wiki doc**: `.docs/wiki/subsystems/[name]/[relevant-doc].md`
-
-            | # | Severity | Description | File | Discovered |
-            |---|----------|-------------|------|------------|
-            | 1 | high     | [description] | `[file-path]` | [story-id] |
-            | 2 | medium   | [description] | `[file-path]` | [story-id] |
-
-            ### [subsystem-name] ([N] items)
-            ...
-        </by-subsystem>
-
-        <by-severity>
-            ## By Severity
-
-            ### High ([N] items)
-            Items that pose security risk, data loss risk, or production instability.
-
-            | # | Subsystem | Description | File | Discovered |
-            |---|-----------|-------------|------|------------|
-            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
-
-            ### Medium ([N] items)
-            Quality issues, maintainability concerns, missing safeguards.
-
-            | # | Subsystem | Description | File | Discovered |
-            |---|-----------|-------------|------|------------|
-            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
-
-            ### Low ([N] items)
-            Cosmetic issues, minor inefficiencies, style inconsistencies.
-
-            | # | Subsystem | Description | File | Discovered |
-            |---|-----------|-------------|------|------------|
-            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
-        </by-severity>
-    </template>
-
-    <guidelines>
-
-        **Header:**
-        - Last updated date changes on every update
-        - Summary counts must be accurate — recalculate on every update
-
-        **Summary Table:**
-        - One row per subsystem that has tech debt
-        - Wiki doc link points to the subsystem wiki doc containing the local ## Tech Debt section
-        - Totals row at the bottom
-
-        **By Subsystem:**
-        - Grouped by subsystem, sorted alphabetically
-        - Within each subsystem, sorted by severity (high → medium → low)
-        - Each item has: severity, short description, file path, discovering story ID
-        - File paths are relative to project root
-
-        **By Severity:**
-        - Same items as By Subsystem, but grouped by severity level
-        - Provides a quick view of highest-priority debt across the codebase
-
-        **Severity Definitions:**
-        - `high` — security risk, data loss risk, production instability
-        - `medium` — quality issue, maintainability concern, missing safeguards
-        - `low` — cosmetic, minor inefficiency, style inconsistency
-
-        **What does NOT belong here:**
-        - Tech debt that has been fixed (remove it when fixed by a future story)
-        - Planned work or feature requests (those are stories/features in the backlog)
-        - Code that violates standards but was just written (that's a blocker, not tech debt)
-
-    </guidelines>
-
-    <evolution>
-
-        This is a LIVING document — updated by the wiki mapper after each story execution.
-
-        **Update triggers:**
-        - ace-code-reviewer discovers new tech debt during story review
-        - A story implementation fixes existing tech debt (remove the item)
-
-        **Update rules:**
-        - ADD new items discovered during code review
-        - REMOVE items that were fixed by a story
-        - RECALCULATE summary counts on every update
-        - PRESERVE item ordering: by subsystem alphabetically, then by severity
-        - Each item always linked to the discovering story for traceability
-        - When a subsystem has zero remaining items, remove its section
-
-    </evolution>
-
-</tech-debt-index>
+<tech-debt-index>
+    <purpose>
+        Template for `.docs/wiki/system-wide/tech-debt-index.md` — a cross-cutting index of all
+        known tech debt across the entire codebase. Answers "What quality issues exist, where,
+        and how severe are they?"
+
+        This is a roll-up document maintained by the wiki mapper after each story execution.
+        The ace-code-reviewer discovers tech debt during review; the wiki mapper records it here
+        AND in the relevant subsystem/system wiki docs.
+
+        Complements:
+        - Subsystem wiki docs (each has its own ## Tech Debt section with local items)
+        - coding-standards.md (defines what IS a violation; this doc tracks EXISTING violations)
+    </purpose>
+
+    <template>
+        <header>
+            # Tech Debt Index
+
+            **Last updated**: [YYYY-MM-DD]
+            **Total items**: [N] ([high] high, [medium] medium, [low] low)
+        </header>
+
+        <summary-table>
+            ## Summary by Subsystem
+
+            | Subsystem | High | Medium | Low | Total | Wiki Doc |
+            |-----------|------|--------|-----|-------|----------|
+            | [name]    | [n]  | [n]    | [n] | [n]   | [link to wiki doc] |
+            | **Total** | [n]  | [n]    | [n] | [n]   | |
+        </summary-table>
+
+        <by-subsystem>
+            ## By Subsystem
+
+            ### [subsystem-name] ([N] items)
+            **Wiki doc**: `.docs/wiki/subsystems/[name]/[relevant-doc].md`
+
+            | # | Severity | Description | File | Discovered |
+            |---|----------|-------------|------|------------|
+            | 1 | high     | [description] | `[file-path]` | [story-id] |
+            | 2 | medium   | [description] | `[file-path]` | [story-id] |
+
+            ### [subsystem-name] ([N] items)
+            ...
+        </by-subsystem>
+
+        <by-severity>
+            ## By Severity
+
+            ### High ([N] items)
+            Items that pose security risk, data loss risk, or production instability.
+
+            | # | Subsystem | Description | File | Discovered |
+            |---|-----------|-------------|------|------------|
+            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
+
+            ### Medium ([N] items)
+            Quality issues, maintainability concerns, missing safeguards.
+
+            | # | Subsystem | Description | File | Discovered |
+            |---|-----------|-------------|------|------------|
+            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
+
+            ### Low ([N] items)
+            Cosmetic issues, minor inefficiencies, style inconsistencies.
+
+            | # | Subsystem | Description | File | Discovered |
+            |---|-----------|-------------|------|------------|
+            | 1 | [name]    | [description] | `[file-path]` | [story-id] |
+        </by-severity>
+    </template>
+
+    <guidelines>
+
+        **Header:**
+        - Last updated date changes on every update
+        - Summary counts must be accurate — recalculate on every update
+
+        **Summary Table:**
+        - One row per subsystem that has tech debt
+        - Wiki doc link points to the subsystem wiki doc containing the local ## Tech Debt section
+        - Totals row at the bottom
+
+        **By Subsystem:**
+        - Grouped by subsystem, sorted alphabetically
+        - Within each subsystem, sorted by severity (high → medium → low)
+        - Each item has: severity, short description, file path, discovering story ID
+        - File paths are relative to project root
+
+        **By Severity:**
+        - Same items as By Subsystem, but grouped by severity level
+        - Provides a quick view of highest-priority debt across the codebase
+
+        **Severity Definitions:**
+        - `high` — security risk, data loss risk, production instability
+        - `medium` — quality issue, maintainability concern, missing safeguards
+        - `low` — cosmetic, minor inefficiency, style inconsistency
+
+        **What does NOT belong here:**
+        - Tech debt that has been fixed (remove it when fixed by a future story)
+        - Planned work or feature requests (those are stories/features in the backlog)
+        - Code that violates standards but was just written (that's a blocker, not tech debt)
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated by the wiki mapper after each story execution.
+
+        **Update triggers:**
+        - ace-code-reviewer discovers new tech debt during story review
+        - A story implementation fixes existing tech debt (remove the item)
+
+        **Update rules:**
+        - ADD new items discovered during code review
+        - REMOVE items that were fixed by a story
+        - RECALCULATE summary counts on every update
+        - PRESERVE item ordering: by subsystem alphabetically, then by severity
+        - Each item always linked to the discovering story for traceability
+        - When a subsystem has zero remaining items, remove its section
+
+    </evolution>
+
+</tech-debt-index>

package/skills/map-story/workflow.xml

@@ -25,8 +25,8 @@
     </purpose>
 
     <mandatory-context>
-        The orchestrator reads ONLY this workflow — it stays lightweight.
-        Each sub-agent reads the five document templates itself before writing.
+        All supporting resource files are auto-loaded in the skill prompt above. Do NOT re-read them.
+        Each sub-agent reads the document templates itself before writing.
         Also read any parameters passed as $ARGUMENTS in the invoking command.
     </mandatory-context>