agile-context-engineering 0.5.0 → 0.5.1

package/skills/research-story-wiki/story-wiki-template.xml

@@ -1,194 +1,194 @@
-<story-wiki>
-
-    <purpose>
-        Template for the `## Relevant Wiki` section that gets APPENDED to the story file
-        (`.ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/&lt;id-story_name&gt;.md`)
-        and optionally updated in the GitHub issue body.
-
-        This is pass 2 of the story specification pipeline (see story.xml composition).
-        It runs AFTER sections 1-8 (business requirements) are complete.
-
-        A research agent reads the User Story, Description, and Acceptance Criteria from pass 1,
-        then scans the `.docs/wiki/` directory to select documents that are relevant for
-        designing a good technical solution for this story.
-
-        The output is written directly INTO the story file — replacing or populating the
-        `## Relevant Wiki` section placeholder left by pass 1.
-
-        This section is consumed by pass 5 (technical solution) as the primary reference
-        for which wiki documents to load when designing the implementation approach.
-    </purpose>
-
-    <output-format>
-
-        <section name="relevant-wiki">
-            ## Relevant Wiki
-
-            &lt;!-- Pass 2. Populated by research-story-wiki workflow.
-                 A research agent reads the User Story, Description, and AC,
-                 then scans `.docs/wiki/` to select documents relevant to
-                 designing a good technical solution for this story.
-
-                 Group references by wiki document type. Only include documents that
-                 directly inform implementation — do not list tangentially related docs.
-                 Each entry: relative path + one-line reason why it's relevant. --&gt;
-
-            ### System-Wide
-
-            &lt;!-- MANDATORY — all four system-wide docs are always included.
-                 These are mandatory context for every story — no reason needed. --&gt;
-
-            - `.docs/wiki/system-wide/system-structure.md` — Mandatory system-wide context
-            - `.docs/wiki/system-wide/system-architecture.md` — Mandatory system-wide context
-            - `.docs/wiki/system-wide/coding-standards.md` — Mandatory system-wide context
-            - `.docs/wiki/system-wide/testing-framework.md` — Mandatory system-wide context
-
-            ### Systems
-            - [`.docs/wiki/subsystems/[name]/systems/[system].md`] — [Why this system is relevant to this story]
-
-            ### Patterns
-            - [`.docs/wiki/subsystems/[name]/patterns/[pattern].md`] — [Why this pattern applies to this story]
-
-            ### Cross-Cutting Concerns
-            - [`.docs/wiki/subsystems/[name]/cross-cutting/[concern].md`] — [Why this concern matters for this story]
-
-            ### Guides
-            - [`.docs/wiki/subsystems/[name]/guides/[guide].md`] — [Why this guide is useful for this story]
-
-            ### Walkthroughs
-            - [`.docs/wiki/subsystems/[name]/walkthroughs/[flow].md`] — [Why this flow walkthrough helps understand the implementation context]
-
-            ### Decisions
-            - [`.docs/wiki/subsystems/[name]/decisions/[decision].md`] — [Why this ADR constrains or informs this story]
-
-            ### Architecture
-            - [`.docs/wiki/subsystems/[name]/architecture.md`] — [Why this subsystem's architecture doc is relevant]
-
-            &lt;!-- Omit any subsystem category header that has no relevant documents.
-                 The System-Wide section is NEVER omitted — it is always present.
-
-                 Example:
-
-                 ### System-Wide
-                 - `.docs/wiki/system-wide/system-structure.md` — Locates auth subsystem boundaries and shared middleware
-                 - `.docs/wiki/system-wide/system-architecture.md` — Documents API gateway routing to auth service
-                 - `.docs/wiki/system-wide/coding-standards.md` — Error handling conventions for API responses
-                 - `.docs/wiki/system-wide/testing-framework.md` — Integration test setup for auth endpoints
-
-                 ### Systems
-                 - `.docs/wiki/subsystems/auth/systems/oauth-provider.md` — Implements the provider abstraction this story extends
-                 - `.docs/wiki/subsystems/auth/systems/session-manager.md` — Manages tokens created by the OAuth flow
-
-                 ### Patterns
-                 - `.docs/wiki/subsystems/auth/patterns/strategy-pattern.md` — Each OAuth provider is a strategy; new provider must follow this
-
-                 ### Decisions
-                 - `.docs/wiki/subsystems/auth/decisions/adr-003-jwt-over-sessions.md` — Constrains token format to JWT
-            --&gt;
-        </section>
-
-    </output-format>
-
-    <selection-criteria>
-
-        <include-when>
-            A wiki document should be INCLUDED if it:
-            - Describes a system this story will modify or extend
-            - Documents a pattern this story must follow
-            - Covers a cross-cutting concern this story must respect (auth, logging, error handling, etc.)
-            - Contains a guide for a task this story requires (e.g., "how to add an API endpoint")
-            - Walks through a complex flow this story extends or modifies
-            - Records an ADR that constrains design choices for this story
-            - Describes the structure or architecture of a subsystem this story touches
-        </include-when>
-
-        <exclude-when>
-            A wiki document should be EXCLUDED if it:
-            - Is only tangentially related (same subsystem but different concern)
-            - Describes something the story reads from but does not modify
-            - Would be "nice to know" but does not change the implementation approach
-            - Duplicates information already in a system-wide doc
-        </exclude-when>
-
-        <reason-quality>
-            Each entry MUST have a one-line reason explaining WHY that document is relevant
-            to THIS specific story. Generic reasons like "related to auth" are NOT acceptable.
-            The reason must explain what the implementing agent should look for or learn from
-            that document.
-
-            Good: "Defines the provider strategy interface this story must implement"
-            Bad: "Related to OAuth"
-        </reason-quality>
-
-    </selection-criteria>
-
-    <guidelines>
-
-        <guideline name="system-wide-mandatory">
-            The four system-wide documents are ALWAYS included in the output:
-            - system-structure.md
-            - system-architecture.md
-            - coding-standards.md
-            - testing-framework.md
-
-            These are mandatory context for every story. Do NOT read them during wiki research —
-            the implementing agent (pass 5) will read them directly. Just list them in the output.
-        </guideline>
-
-        <guideline name="subsystem-depth">
-            For each affected subsystem, the research agent must READ the subsystem's wiki
-            documents to assess relevance — not just list them based on directory names.
-            Only include documents that directly inform the implementation of THIS story.
-        </guideline>
-
-        <guideline name="feature-relevant-wiki-hint">
-            If a `relevant-wiki.md` file exists at the feature level
-            (`.ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/relevant-wiki.md`),
-            use it as a STARTING POINT to identify which subsystems to investigate.
-            This file may not exist — proceed without it if missing.
-        </guideline>
-
-        <guideline name="parallel-subsystem-research">
-            When multiple subsystems need investigation, spawn parallel ace-wiki-mapper
-            agents to read and assess each subsystem's docs concurrently. Each agent returns
-            a list of relevant files with reasons — the orchestrator compiles the final section.
-        </guideline>
-
-        <guideline name="conciseness">
-            The Relevant Wiki section should be scannable. No prose paragraphs.
-            Just categorized file references with one-line reasons.
-            Omit empty category headers — if no patterns are relevant, don't show ### Patterns.
-            The System-Wide section is the only exception — it is always present.
-        </guideline>
-
-        <guideline name="github-compatibility">
-            The output must render cleanly in both markdown files and GitHub issue bodies.
-            Use standard markdown — no HTML, no custom formatting.
-            Backtick-formatted file paths for readability.
-        </guideline>
-
-    </guidelines>
-
-    <evolution>
-
-        **Creation (research-story-wiki — pass 2):**
-        This pass runs after sections 1-8 are complete. It reads the story requirements
-        and scans the wiki to populate the Relevant Wiki section. A single run produces
-        the complete section.
-
-        **Consumption (story-technical-solution — pass 5):**
-        The technical solution pass reads this section to know which wiki documents to load
-        as context when designing the implementation approach. Every file listed here
-        will be read by the implementing agent.
-
-        **Re-research (exception, not norm):**
-        Only when story scope changes significantly (AC rewritten, new subsystems involved).
-        Re-running overwrites the existing Relevant Wiki section.
-
-        **This section IS part of the story file.**
-        It replaces the placeholder left by pass 1 in the story.xml template.
-        It is also synced to the GitHub issue body when GitHub integration is enabled.
-
-    </evolution>
-
-</story-wiki>
+<story-wiki>
+
+    <purpose>
+        Template for the `## Relevant Wiki` section that gets APPENDED to the story file
+        (`.ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/&lt;id-story_name&gt;.md`)
+        and optionally updated in the GitHub issue body.
+
+        This is pass 2 of the story specification pipeline (see story.xml composition).
+        It runs AFTER sections 1-8 (business requirements) are complete.
+
+        A research agent reads the User Story, Description, and Acceptance Criteria from pass 1,
+        then scans the `.docs/wiki/` directory to select documents that are relevant for
+        designing a good technical solution for this story.
+
+        The output is written directly INTO the story file — replacing or populating the
+        `## Relevant Wiki` section placeholder left by pass 1.
+
+        This section is consumed by pass 5 (technical solution) as the primary reference
+        for which wiki documents to load when designing the implementation approach.
+    </purpose>
+
+    <output-format>
+
+        <section name="relevant-wiki">
+            ## Relevant Wiki
+
+            &lt;!-- Pass 2. Populated by research-story-wiki workflow.
+                 A research agent reads the User Story, Description, and AC,
+                 then scans `.docs/wiki/` to select documents relevant to
+                 designing a good technical solution for this story.
+
+                 Group references by wiki document type. Only include documents that
+                 directly inform implementation — do not list tangentially related docs.
+                 Each entry: relative path + one-line reason why it's relevant. --&gt;
+
+            ### System-Wide
+
+            &lt;!-- MANDATORY — all four system-wide docs are always included.
+                 These are mandatory context for every story — no reason needed. --&gt;
+
+            - `.docs/wiki/system-wide/system-structure.md` — Mandatory system-wide context
+            - `.docs/wiki/system-wide/system-architecture.md` — Mandatory system-wide context
+            - `.docs/wiki/system-wide/coding-standards.md` — Mandatory system-wide context
+            - `.docs/wiki/system-wide/testing-framework.md` — Mandatory system-wide context
+
+            ### Systems
+            - [`.docs/wiki/subsystems/[name]/systems/[system].md`] — [Why this system is relevant to this story]
+
+            ### Patterns
+            - [`.docs/wiki/subsystems/[name]/patterns/[pattern].md`] — [Why this pattern applies to this story]
+
+            ### Cross-Cutting Concerns
+            - [`.docs/wiki/subsystems/[name]/cross-cutting/[concern].md`] — [Why this concern matters for this story]
+
+            ### Guides
+            - [`.docs/wiki/subsystems/[name]/guides/[guide].md`] — [Why this guide is useful for this story]
+
+            ### Walkthroughs
+            - [`.docs/wiki/subsystems/[name]/walkthroughs/[flow].md`] — [Why this flow walkthrough helps understand the implementation context]
+
+            ### Decisions
+            - [`.docs/wiki/subsystems/[name]/decisions/[decision].md`] — [Why this ADR constrains or informs this story]
+
+            ### Architecture
+            - [`.docs/wiki/subsystems/[name]/architecture.md`] — [Why this subsystem's architecture doc is relevant]
+
+            &lt;!-- Omit any subsystem category header that has no relevant documents.
+                 The System-Wide section is NEVER omitted — it is always present.
+
+                 Example:
+
+                 ### System-Wide
+                 - `.docs/wiki/system-wide/system-structure.md` — Locates auth subsystem boundaries and shared middleware
+                 - `.docs/wiki/system-wide/system-architecture.md` — Documents API gateway routing to auth service
+                 - `.docs/wiki/system-wide/coding-standards.md` — Error handling conventions for API responses
+                 - `.docs/wiki/system-wide/testing-framework.md` — Integration test setup for auth endpoints
+
+                 ### Systems
+                 - `.docs/wiki/subsystems/auth/systems/oauth-provider.md` — Implements the provider abstraction this story extends
+                 - `.docs/wiki/subsystems/auth/systems/session-manager.md` — Manages tokens created by the OAuth flow
+
+                 ### Patterns
+                 - `.docs/wiki/subsystems/auth/patterns/strategy-pattern.md` — Each OAuth provider is a strategy; new provider must follow this
+
+                 ### Decisions
+                 - `.docs/wiki/subsystems/auth/decisions/adr-003-jwt-over-sessions.md` — Constrains token format to JWT
+            --&gt;
+        </section>
+
+    </output-format>
+
+    <selection-criteria>
+
+        <include-when>
+            A wiki document should be INCLUDED if it:
+            - Describes a system this story will modify or extend
+            - Documents a pattern this story must follow
+            - Covers a cross-cutting concern this story must respect (auth, logging, error handling, etc.)
+            - Contains a guide for a task this story requires (e.g., "how to add an API endpoint")
+            - Walks through a complex flow this story extends or modifies
+            - Records an ADR that constrains design choices for this story
+            - Describes the structure or architecture of a subsystem this story touches
+        </include-when>
+
+        <exclude-when>
+            A wiki document should be EXCLUDED if it:
+            - Is only tangentially related (same subsystem but different concern)
+            - Describes something the story reads from but does not modify
+            - Would be "nice to know" but does not change the implementation approach
+            - Duplicates information already in a system-wide doc
+        </exclude-when>
+
+        <reason-quality>
+            Each entry MUST have a one-line reason explaining WHY that document is relevant
+            to THIS specific story. Generic reasons like "related to auth" are NOT acceptable.
+            The reason must explain what the implementing agent should look for or learn from
+            that document.
+
+            Good: "Defines the provider strategy interface this story must implement"
+            Bad: "Related to OAuth"
+        </reason-quality>
+
+    </selection-criteria>
+
+    <guidelines>
+
+        <guideline name="system-wide-mandatory">
+            The four system-wide documents are ALWAYS included in the output:
+            - system-structure.md
+            - system-architecture.md
+            - coding-standards.md
+            - testing-framework.md
+
+            These are mandatory context for every story. Do NOT read them during wiki research —
+            the implementing agent (pass 5) will read them directly. Just list them in the output.
+        </guideline>
+
+        <guideline name="subsystem-depth">
+            For each affected subsystem, the research agent must READ the subsystem's wiki
+            documents to assess relevance — not just list them based on directory names.
+            Only include documents that directly inform the implementation of THIS story.
+        </guideline>
+
+        <guideline name="feature-relevant-wiki-hint">
+            If a `relevant-wiki.md` file exists at the feature level
+            (`.ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/relevant-wiki.md`),
+            use it as a STARTING POINT to identify which subsystems to investigate.
+            This file may not exist — proceed without it if missing.
+        </guideline>
+
+        <guideline name="parallel-subsystem-research">
+            When multiple subsystems need investigation, spawn parallel ace-wiki-mapper
+            agents to read and assess each subsystem's docs concurrently. Each agent returns
+            a list of relevant files with reasons — the orchestrator compiles the final section.
+        </guideline>
+
+        <guideline name="conciseness">
+            The Relevant Wiki section should be scannable. No prose paragraphs.
+            Just categorized file references with one-line reasons.
+            Omit empty category headers — if no patterns are relevant, don't show ### Patterns.
+            The System-Wide section is the only exception — it is always present.
+        </guideline>
+
+        <guideline name="github-compatibility">
+            The output must render cleanly in both markdown files and GitHub issue bodies.
+            Use standard markdown — no HTML, no custom formatting.
+            Backtick-formatted file paths for readability.
+        </guideline>
+
+    </guidelines>
+
+    <evolution>
+
+        **Creation (research-story-wiki — pass 2):**
+        This pass runs after sections 1-8 are complete. It reads the story requirements
+        and scans the wiki to populate the Relevant Wiki section. A single run produces
+        the complete section.
+
+        **Consumption (story-technical-solution — pass 5):**
+        The technical solution pass reads this section to know which wiki documents to load
+        as context when designing the implementation approach. Every file listed here
+        will be read by the implementing agent.
+
+        **Re-research (exception, not norm):**
+        Only when story scope changes significantly (AC rewritten, new subsystems involved).
+        Re-running overwrites the existing Relevant Wiki section.
+
+        **This section IS part of the story file.**
+        It replaces the placeholder left by pass 1 in the story.xml template.
+        It is also synced to the GitHub issue body when GitHub integration is enabled.
+
+    </evolution>
+
+</story-wiki>