agile-context-engineering 0.3.0 → 0.5.1

package/{commands/ace/map-story.md → skills/map-story/SKILL.md}

@@ -1,165 +1,180 @@
----
-name: ace: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'"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - Task
-  - AskUserQuestion
-  - Agent
----
-
-```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>
-        <map-story-workflow>@~/.claude/agile-context-engineering/workflows/map-story.xml</map-story-workflow>
-
-        <system>@~/.claude/agile-context-engineering/templates/wiki/system.xml</system>
-        <system-cross-cutting>@~/.claude/agile-context-engineering/templates/wiki/system-cross-cutting.xml</system-cross-cutting>
-        <pattern>@~/.claude/agile-context-engineering/templates/wiki/pattern.xml</pattern>
-        <guide>@~/.claude/agile-context-engineering/templates/wiki/guide.xml</guide>
-        <walkthrough>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough>
-        <decizions>@~/.claude/agile-context-engineering/templates/wiki/decizions.xml</decizions>
-        <tech-debt-index>@~/.claude/agile-context-engineering/templates/wiki/tech-debt-index.xml</tech-debt-index>
-
-        <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </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
-        `@~/.claude/agile-context-engineering/workflows/map-story.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>
-```
+---
+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/{agile-context-engineering/templates/wiki → skills/map-story/templates}/decizions.xml

@@ -1,115 +1,115 @@
-<decisions>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
-        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
-        Answers "Why did we choose X over Y?"
-
-        Each decision doc captures one significant technical decision with its context and
-        trade-offs. It is the document an AI agent reads to understand WHY things are built
-        a certain way, preventing it from making the wrong choice.
-
-        Create an ADR ONLY when a significant "why" decision was made:
-        - Choosing one approach over another with meaningful trade-offs
-        - Deviating from an established pattern for a specific reason
-        - Adopting a new technology, pattern, or architectural approach
-        - Rejecting a seemingly obvious solution for non-obvious reasons
-
-        Do NOT create ADRs for trivial or obvious decisions.
-
-        Complements:
-        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
-        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
-        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
-    </purpose>
-
-    <template>
-        <decision-record>
-            # ADR-NNN: [Decision Title]
-
-            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
-            **Date**: YYYY-MM-DD
-            **Story**: [story reference, if applicable]
-
-            ## Context
-            What situation prompted this decision. 2-3 sentences max.
-
-            ## Decision
-            What was decided. 2-3 sentences max.
-
-            ## Alternatives Considered
-            - **[Alternative A]**: [Why rejected — 1 sentence]
-            - **[Alternative B]**: [Why rejected — 1 sentence]
-
-            ## Consequences
-            - Pro: [positive outcome]
-            - Pro: [positive outcome]
-            - Con: [trade-off accepted]
-        </decision-record>
-    </template>
-
-    <guidelines>
-
-        **Documentation Style:**
-        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
-        - NO FLUFF — every sentence must convey a decision, reason, or consequence
-        - Bullet points for alternatives and consequences
-        - Code references as `file-path:ClassName` only when the decision is about specific code
-
-        **ADR Numbering:**
-        - Sequential within the subsystem: ADR-001, ADR-002, etc.
-        - Filename format: `ADR-NNN-kebab-case-slug.md`
-        - To find the next number, read existing ADRs in the decisions/ directory.
-
-        **Status:**
-        - `Accepted` — the decision is in effect
-        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
-        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
-
-        **Context:**
-        - 2-3 sentences. What problem or situation forced a choice.
-        - Reference the system or pattern this decision affects.
-
-        **Decision:**
-        - 2-3 sentences. What was chosen and at what scope.
-        - Be specific — "We use X for Y" not "We decided to improve things."
-
-        **Alternatives Considered:**
-        - List each rejected alternative with ONE sentence explaining why.
-        - If there were no meaningful alternatives, omit this section.
-
-        **Consequences:**
-        - Bullet list of pros and cons.
-        - Be honest about trade-offs — future agents need to know the downsides.
-        - Include migration/compatibility consequences if applicable.
-
-        **What does NOT belong here:**
-        - Implementation details (that's in systems/ and patterns/ docs)
-        - Step-by-step instructions (that's in guides/)
-        - Full analysis or research documents (those are in .ace/artifacts/)
-        - Revision history or meeting notes
-
-    </guidelines>
-
-    <evolution>
-
-        ADRs are IMMUTABLE once accepted. They are historical records.
-
-        **When to create a new ADR:**
-        - A significant architectural or pattern choice is made during a story
-        - An existing decision is reversed or significantly modified (supersede the old one)
-        - A new technology, pattern, or approach is adopted
-
-        **When NOT to create an ADR:**
-        - Routine implementation following existing patterns
-        - Bug fixes or refactoring that don't change architectural direction
-        - Trivial decisions with no meaningful trade-offs
-        - Decisions already captured in an existing ADR
-
-        **Superseding:**
-        - Create the new ADR with its own number
-        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
-        - This is the ONLY edit allowed on an accepted ADR
-
-    </evolution>
-
-</decisions>
+<decisions>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
+        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
+        Answers "Why did we choose X over Y?"
+
+        Each decision doc captures one significant technical decision with its context and
+        trade-offs. It is the document an AI agent reads to understand WHY things are built
+        a certain way, preventing it from making the wrong choice.
+
+        Create an ADR ONLY when a significant "why" decision was made:
+        - Choosing one approach over another with meaningful trade-offs
+        - Deviating from an established pattern for a specific reason
+        - Adopting a new technology, pattern, or architectural approach
+        - Rejecting a seemingly obvious solution for non-obvious reasons
+
+        Do NOT create ADRs for trivial or obvious decisions.
+
+        Complements:
+        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
+        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
+        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
+    </purpose>
+
+    <template>
+        <decision-record>
+            # ADR-NNN: [Decision Title]
+
+            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
+            **Date**: YYYY-MM-DD
+            **Story**: [story reference, if applicable]
+
+            ## Context
+            What situation prompted this decision. 2-3 sentences max.
+
+            ## Decision
+            What was decided. 2-3 sentences max.
+
+            ## Alternatives Considered
+            - **[Alternative A]**: [Why rejected — 1 sentence]
+            - **[Alternative B]**: [Why rejected — 1 sentence]
+
+            ## Consequences
+            - Pro: [positive outcome]
+            - Pro: [positive outcome]
+            - Con: [trade-off accepted]
+        </decision-record>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
+        - NO FLUFF — every sentence must convey a decision, reason, or consequence
+        - Bullet points for alternatives and consequences
+        - Code references as `file-path:ClassName` only when the decision is about specific code
+
+        **ADR Numbering:**
+        - Sequential within the subsystem: ADR-001, ADR-002, etc.
+        - Filename format: `ADR-NNN-kebab-case-slug.md`
+        - To find the next number, read existing ADRs in the decisions/ directory.
+
+        **Status:**
+        - `Accepted` — the decision is in effect
+        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
+        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
+
+        **Context:**
+        - 2-3 sentences. What problem or situation forced a choice.
+        - Reference the system or pattern this decision affects.
+
+        **Decision:**
+        - 2-3 sentences. What was chosen and at what scope.
+        - Be specific — "We use X for Y" not "We decided to improve things."
+
+        **Alternatives Considered:**
+        - List each rejected alternative with ONE sentence explaining why.
+        - If there were no meaningful alternatives, omit this section.
+
+        **Consequences:**
+        - Bullet list of pros and cons.
+        - Be honest about trade-offs — future agents need to know the downsides.
+        - Include migration/compatibility consequences if applicable.
+
+        **What does NOT belong here:**
+        - Implementation details (that's in systems/ and patterns/ docs)
+        - Step-by-step instructions (that's in guides/)
+        - Full analysis or research documents (those are in .ace/artifacts/)
+        - Revision history or meeting notes
+
+    </guidelines>
+
+    <evolution>
+
+        ADRs are IMMUTABLE once accepted. They are historical records.
+
+        **When to create a new ADR:**
+        - A significant architectural or pattern choice is made during a story
+        - An existing decision is reversed or significantly modified (supersede the old one)
+        - A new technology, pattern, or approach is adopted
+
+        **When NOT to create an ADR:**
+        - Routine implementation following existing patterns
+        - Bug fixes or refactoring that don't change architectural direction
+        - Trivial decisions with no meaningful trade-offs
+        - Decisions already captured in an existing ADR
+
+        **Superseding:**
+        - Create the new ADR with its own number
+        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
+        - This is the ONLY edit allowed on an accepted ADR
+
+    </evolution>
+
+</decisions>