agile-context-engineering 0.5.0 → 0.5.1

package/skills/map-guide/SKILL.md

@@ -1,89 +1,126 @@
----
-name: map-guide
-description: Create or update a step-by-step guide in .docs/wiki/subsystems/[name]/guides/ — recipes for common implementation tasks
-argument-hint: "text='How to add a new drawing tool' subsystem='qarc-charts-v2' commits=3"
-disable-model-invocation: true
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - AskUserQuestion
-model: opus
-effort: max
-context: fork
-agent: ace-wiki-mapper
----
-
-# Map Guide
-
-Create or update a step-by-step guide — recipes for common implementation tasks.
-
-## When to Use
-
-- When a recurring implementation task needs a step-by-step recipe
-- After discovering a repeatable process that combines multiple patterns/systems
-- When onboarding developers who need to perform common tasks
-- A task is done repeatedly (add new endpoint, add new tool, add new entity)
-- The task spans multiple files, registrations, and configuration steps
-- An agent following the guide can complete the task end-to-end without guessing
-
-## Input
-
-### Required
-
-- **`text`** (text) — Natural language description of the guide to create. Describes the recurring task and what the guide should teach. E.g.: "How to add a new drawing tool", "How to add a new CRUD endpoint with validation", "How to add a new indicator to the chart". If not provided, pause and ask the user.
-
-- **`subsystem`** (path | text) — Subsystem where this guide belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/guides/`. If not provided, pause and ask the user.
-
-### Optional
-
-- **`story-context`** (path | GitHub issue) — Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue number/URL. Provides context about a specific implementation that exemplifies the task this guide describes. When not provided, the agent discovers the recipe from codebase patterns.
-
-- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding an example implementation. 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: search the codebase directly to find existing implementations and derive the recipe from them.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **Guide template**: Read [guide.xml](guide.xml) — output format for the guide
-- **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 step-by-step guide that combines knowledge from multiple systems, patterns, and cross-cutting concerns into one actionable recipe. Includes prerequisites, numbered ordered steps with "copy from" references, verification checklist, and common mistakes. The document an AI agent follows when performing a recurring task end-to-end.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
-```
-
-## Example Usage
-
-```
-# Basic guide
-/ace:map-guide text='How to add a new drawing tool' subsystem='qarc-charts-v2'
-
-# With recent commits as example
-/ace:map-guide text='How to add a new CRUD endpoint with validation' subsystem='api' commits=3
-
-# With story context as example implementation
-/ace:map-guide text='How to add a new indicator to the chart' subsystem='qarc-charts-v2' story-context='.ace/artifacts/product/e2-charts/f1-indicators/s1-rsi/s1-rsi.md'
-```
-
-## Next Steps
-
-- `/clear` first for a fresh context window
-- `/ace:map-guide` — create another guide
-- `/ace:map-pattern` — document a pattern referenced by this guide
-- `/ace:map-sys-doc` — document a system referenced by this guide
-- Review file at `.docs/wiki/subsystems/[subsystem-name]/guides/`
+---
+name: map-guide
+description: Create or update a step-by-step guide in .docs/wiki/subsystems/[name]/guides/ — recipes for common implementation tasks
+argument-hint: "text='How to add a new drawing tool' subsystem='qarc-charts-v2' commits=3"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/guide.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>When a recurring implementation task needs a step-by-step recipe</trigger>
+            <trigger>After discovering a repeatable process that combines multiple patterns/systems</trigger>
+            <trigger>When onboarding developers who need to perform common tasks</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A task is done repeatedly (add new endpoint, add new tool, add new entity)</condition>
+            <condition>The task spans multiple files, registrations, and configuration steps</condition>
+            <condition>An agent following the guide can complete the task end-to-end without guessing</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="text" type="text">
+                    Natural language description of the guide to create. Describes the
+                    recurring task and what the guide should teach.
+
+                    E.g.:
+                    - "How to add a new drawing tool"
+                    - "How to add a new CRUD endpoint with validation"
+                    - "How to add a new indicator to the chart"
+
+                    If not provided, pause and ask the user.
+                </param>
+                <param name="subsystem" type="path | text">
+                    Subsystem where this guide belongs.
+                    Wiki location: `.docs/wiki/subsystems/[subsystem]/guides/`.
+                    If not provided, pause and ask the user.
+                </param>
+            </required>
+
+            <optional>
+                <param name="story-context" type="path | GitHub issue">
+                    Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue
+                    number/URL. Provides context about a specific implementation that
+                    exemplifies the task this guide describes.
+                    When not provided, the agent discovers the recipe from codebase patterns.
+                </param>
+                <param name="commits" type="number | comma-separated commit SHAs">
+                    Specifies which commits to analyze for understanding an example implementation.
+                    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: search the codebase directly to find existing implementations
+                    and derive the recipe from them.
+                </param>
+            </optional>
+        </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>
+            Create or update a step-by-step guide that combines knowledge from multiple
+            systems, patterns, and cross-cutting concerns into one actionable recipe.
+            Includes prerequisites, numbered ordered steps with "copy from" references,
+            verification checklist, and common mistakes.
+
+            The document an AI agent follows when performing a recurring task end-to-end.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-wiki-mapper` agent
+        that's specialized in wiki exploration and documentation writing.
+
+        Execute the map-guide 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-guide — create another guide</step>
+        <step>/ace:map-pattern — document a pattern referenced by this guide</step>
+        <step>/ace:map-sys-doc — document a system referenced by this guide</step>
+        <step>Review file at .docs/wiki/subsystems/[subsystem-name]/guides/</step>
+    </next-steps>
+
+</command>
+```

package/skills/map-guide/workflow.xml

@@ -15,7 +15,7 @@
     </purpose>
 
     <mandatory-context>
-        Read all files referenced by the invoking command's execution-context before starting.
+        All supporting resource files are auto-loaded in the skill prompt above. Do NOT re-read them.
         Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
     </mandatory-context>
 

package/skills/map-pattern/SKILL.md

@@ -1,89 +1,125 @@
----
-name: map-pattern
-description: Create or update a pattern document in .docs/wiki/subsystems/[name]/patterns/ — reusable implementation patterns
-argument-hint: "text='Template Method pattern used by all drawing paths' subsystem='qarc-charts-v2' commits=3"
-disable-model-invocation: true
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - AskUserQuestion
-model: opus
-effort: max
-context: fork
-agent: ace-wiki-mapper
----
-
-# Map Pattern
-
-Create or update a pattern document describing reusable implementation patterns.
-
-## When to Use
-
-- When a reusable structural pattern needs documentation
-- After identifying a recurring approach used by 2+ implementations
-- When agents need to understand HOW to implement something following an established pattern
-- A structural approach appears across 2+ implementations
-- New code must follow the same pattern for consistency
-- An agent needs to know the abstract structure + concrete steps to add a new implementation
-
-## Input
-
-### Required
-
-- **`text`** (text) — Natural language description of the pattern to document. Describes WHAT the pattern is and WHERE it appears in the codebase. E.g.: "Template Method pattern used by all drawing paths", "Repository pattern for all database access", "CQRS command/query handler pattern". If not provided, pause and ask the user.
-
-- **`subsystem`** (path | text) — Subsystem where this pattern doc belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/patterns/`. If not provided, pause and ask the user.
-
-### Optional
-
-- **`story-context`** (path | GitHub issue) — Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue number/URL. Provides context about a story that introduced or modified this pattern. When not provided, the agent discovers the pattern from codebase analysis.
-
-- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding pattern changes. 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: search the codebase directly to find all implementations and extract the pattern structure.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **Pattern template**: Read [pattern.xml](pattern.xml) — output format for the pattern document
-- **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 pattern document that describes a reusable structural approach — structure diagram (mermaid classDiagram), how it works step-by-step, how to apply it for new implementations, current implementations list, and gotchas. The document an AI agent reads to ensure new code follows established conventions.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
-```
-
-## Example Usage
-
-```
-# Basic pattern
-/ace:map-pattern text='Template Method pattern used by all drawing paths' subsystem='qarc-charts-v2'
-
-# With recent commits
-/ace:map-pattern text='Repository pattern for all database access' subsystem='api' commits=3
-
-# With story context
-/ace:map-pattern text='CQRS command/query handler pattern' subsystem='api' story-context='.ace/artifacts/product/e1-api/f2-cqrs/s1-setup/s1-setup.md'
-```
-
-## Next Steps
-
-- `/clear` first for a fresh context window
-- `/ace:map-pattern` — create another pattern document
-- `/ace:map-guide` — create a guide that uses this pattern
-- `/ace:map-sys-doc` — document a system that uses this pattern
-- Review file at `.docs/wiki/subsystems/[subsystem-name]/patterns/`
+---
+name: map-pattern
+description: Create or update a pattern document in .docs/wiki/subsystems/[name]/patterns/ — reusable implementation patterns
+argument-hint: "text='Template Method pattern used by all drawing paths' subsystem='qarc-charts-v2' commits=3"
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/pattern.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>When a reusable structural pattern needs documentation</trigger>
+            <trigger>After identifying a recurring approach used by 2+ implementations</trigger>
+            <trigger>When agents need to understand HOW to implement something following an established pattern</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A structural approach appears across 2+ implementations</condition>
+            <condition>New code must follow the same pattern for consistency</condition>
+            <condition>An agent needs to know the abstract structure + concrete steps to add a new implementation</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="text" type="text">
+                    Natural language description of the pattern to document. Describes WHAT
+                    the pattern is and WHERE it appears in the codebase.
+
+                    E.g.:
+                    - "Template Method pattern used by all drawing paths"
+                    - "Repository pattern for all database access"
+                    - "CQRS command/query handler pattern"
+
+                    If not provided, pause and ask the user.
+                </param>
+                <param name="subsystem" type="path | text">
+                    Subsystem where this pattern doc belongs.
+                    Wiki location: `.docs/wiki/subsystems/[subsystem]/patterns/`.
+                    If not provided, pause and ask the user.
+                </param>
+            </required>
+
+            <optional>
+                <param name="story-context" type="path | GitHub issue">
+                    Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue
+                    number/URL. Provides context about a story that introduced or modified
+                    this pattern.
+                    When not provided, the agent discovers the pattern from codebase analysis.
+                </param>
+                <param name="commits" type="number | comma-separated commit SHAs">
+                    Specifies which commits to analyze for understanding pattern changes.
+                    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: search the codebase directly to find all implementations
+                    and extract the pattern structure.
+                </param>
+            </optional>
+        </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>
+            Create or update a pattern document that describes a reusable structural approach —
+            structure diagram (mermaid classDiagram), how it works step-by-step, how to apply
+            it for new implementations, current implementations list, and gotchas.
+
+            The document an AI agent reads to ensure new code follows established conventions.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-wiki-mapper` agent
+        that's specialized in wiki exploration and documentation writing.
+
+        Execute the map-pattern 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-pattern — create another pattern document</step>
+        <step>/ace:map-guide — create a guide that uses this pattern</step>
+        <step>/ace:map-sys-doc — document a system that uses this pattern</step>
+        <step>Review file at .docs/wiki/subsystems/[subsystem-name]/patterns/</step>
+    </next-steps>
+
+</command>
+```

package/skills/map-pattern/workflow.xml

@@ -14,7 +14,7 @@
     </purpose>
 
     <mandatory-context>
-        Read all files referenced by the invoking command's execution-context before starting.
+        All supporting resource files are auto-loaded in the skill prompt above. Do NOT re-read them.
         Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
     </mandatory-context>