agile-context-engineering 0.2.2 → 0.5.0

package/commands/ace/plan-story.md

@@ -1,145 +0,0 @@
----
-name: ace:plan-story
-description: Plan a story through deep questioning to create CRYSTAL-CLEAR acceptance criteria with ZERO assumptions, then dispatch wiki research, external analysis, integration analysis, and technical solution design
-argument-hint: "story=<file-path|github-url> [external-codebase=<source-path|github-url>] [external-docs=<weblink|filepath>]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Edit
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - Agent
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-feature — once a feature's story breakdown exists with stub story files</trigger>
-            <trigger>Anytime — to create or refine a story specification from a description or GitHub issue</trigger>
-        </runs-after>
-        <use-when>
-            <condition>A story stub exists (from plan-feature) and needs formal specification</condition>
-            <condition>A GitHub issue describes work that needs INVEST-compliant acceptance criteria</condition>
-            <condition>An existing story needs refinement — scope changed, AC gaps found</condition>
-            <condition>You want to create a complete story specification from any text description</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a markdown file containing the story seed
-                      (typically a stub from plan-feature, or any markdown with a description)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    Contains the story description that will be refined through deep questioning.
-                    If not valid, stop and prompt the user.
-                </param>
-            </required>
-
-            <optional>
-                <param name="external-codebase" type="filepath | github-url">
-                    Path or GitHub repo to an external industry-standard system to analyze.
-                    When provided, pass 3 (external analysis) runs automatically.
-                    When NOT provided, the user is offered the option to provide it or skip.
-                </param>
-                <param name="external-docs" type="weblink | filepath">
-                    Link or path to external system documentation.
-                    Only used when external-codebase is also provided.
-                    Provides supplementary context for external analysis.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <plan-story-workflow>@~/.claude/agile-context-engineering/workflows/plan-story.xml</plan-story-workflow>
-        <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
-        <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>
-            Take a story seed (stub file, GitHub issue, or any text description) and produce
-            a COMPLETE story specification through deep questioning that ensures:
-            - ZERO ASSUMPTIONS — every behavior is explicitly specified
-            - CRYSTAL-CLEAR acceptance criteria with exact triggers, preconditions, outcomes
-            - INVEST compliance — Independent, Negotiable, Valuable, Estimable, Small, Testable
-            - Gherkin scenarios cover happy paths, edge cases, AND error paths
-
-            After story requirements are defined (pass 1), dispatch research passes 2-5
-            as background agents:
-            - Pass 2: Wiki research (updates story file with Relevant Wiki section)
-            - Pass 3: External analysis (OPTIONAL — creates external-analysis.md)
-            - Pass 4: Integration analysis (creates integration-analysis.md)
-            - Pass 5: Technical solution (appends to story file)
-
-            Each research pass writes directly to disk. The orchestrator context window
-            contains ONLY story requirements — research outputs do NOT flow back.
-        </objective>
-
-        <artifacts>
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/&lt;id-story_name&gt;.md
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/external-analysis.md (OPTIONAL)
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/integration-analysis.md
-        </artifacts>
-    </output>
-
-    <process>
-        For this command use the `ace-product-owner` agent
-        that's specialized in requirements gathering, deep questioning, and story specification.
-
-        Execute the plan-story workflow from
-        `@~/.claude/agile-context-engineering/workflows/plan-story.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-
-        **CRITICAL — Context Window Protection:**
-        Passes 2-5 run as background agents. Each agent writes output directly to files.
-        The orchestrator MUST NOT call TaskOutput on any background agent.
-        The orchestrator only needs to know when each pass finishes to start the next one.
-
-        **Pass execution order:**
-        Pass 2 + Pass 3 (if applicable) → wait → Pass 4 → wait → Pass 5 → wait → done
-    </process>
-
-    <example-usage>
-        ```
-        # From a plan-feature stub file
-        /ace:plan-story \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-        # From a GitHub issue
-        /ace:plan-story \
-          story=https://github.com/owner/repo/issues/95
-
-        # With external system analysis
-        /ace:plan-story \
-          story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
-          external-codebase=src/external/lightweight-charts/ \
-          external-docs=https://tradingview.github.io/lightweight-charts/
-
-        # With just an issue number (uses configured repo)
-        /ace:plan-story story=#95
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:execute-story story=...` — Execute the story implementation
-        - `/ace:plan-story story=...` — Plan the next story in the feature
-        - `/ace:verify-story story=...` — Verify a completed story
-        - `/ace:help` — Check project initialization status
-    </next-steps>
-
-</command>
-```

package/commands/ace/research-external-solution.md

@@ -1,138 +0,0 @@
----
-name: ace:research-external-solution
-description: COMPREHENSIVE, IN-DEPTH, CODE-LEVEL Analysis of User Story Implementation in External Repository
-argument-hint: "story=<file-path|github-url> external-codebase=<source-path|github-url> [external-docs=<weblink|filepath>]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - WebFetch
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-story — once story requirements (pass 1-2) are complete</trigger>
-            <trigger>Anytime — when a story references an external system or reference implementation</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Story or feature references an external codebase to learn from</condition>
-            <condition>Need to understand how an industry-standard system implements specific functionality</condition>
-            <condition>Want to extract algorithms, patterns, and implementation details from reference code</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a markdown file containing the story (from plan-story command)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    Contains the user story and acceptance criteria that define what to analyze.
-                    **Requirements for the analysis are extracted from this story.**
-                    If not valid, stop and prompt the user.
-                </param>
-                <param name="external-codebase" type="filepath | github-url">
-                    Path or GitHub repo to the external industry-standard system to analyze.
-                    - If local path: Confirm folder exists and contains source code
-                    - If GitHub URL: Verify repository accessibility
-                    The external repository to analyze for implementation patterns,
-                    algorithms, formulas, and architectural decisions.
-                    If not valid, stop and prompt the user.
-                </param>
-            </required>
-
-            <optional>
-                <param name="external-docs" type="weblink | filepath">
-                    Link or path to external industry-standard system documentation.
-                    Provides supplementary context when available.
-                    - If weblink: Verify URL is accessible
-                    - If filepath: Verify file exists and is readable
-                    **PREFER using context7 MCP server** when installed — it provides
-                    up-to-date library documentation automatically. Use context7 whenever
-                    the external system is a known library/framework.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <research-external-workflow>@~/.claude/agile-context-engineering/workflows/research-external-solution.xml</research-external-workflow>
-        <external-solution-template>@~/.claude/agile-context-engineering/templates/product/external-solution.xml</external-solution-template>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Perform a COMPREHENSIVE, IN-DEPTH, CODE-LEVEL ANALYSIS of how a specific
-            story's functionality is implemented in an external reference system.
-            This is NOT a high-level overview — it's a DEEP DIVE into:
-            - EXACT code implementations with line-by-line analysis
-            - COMPLETE algorithms and formulas extracted verbatim from code
-            - ALL design patterns with actual code examples
-            - EVERY file, function, and constant involved in the story
-            - FULL execution paths traced 5+ levels deep minimum
-
-            The analysis ensures our implementation:
-            - Follows established patterns and best practices (with code proof)
-            - Uses exact algorithms and formulas (copied from their code)
-            - Maintains compatibility with industry standards (matching their APIs)
-
-            All output is written ONLY to the analysis file — no GitHub updates,
-            no modifications to the story file. This artifact is consumed by
-            pass 5 (technical solution) of the story specification pipeline.
-        </objective>
-
-        <artifacts>
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/external-analysis.md
-        </artifacts>
-    </output>
-
-    <process>
-        For this command use the `ace-code-discovery-analyst` agent
-        that's specialized in code discovery.
-
-        Execute the research-external-solution workflow from
-        `@~/.claude/agile-context-engineering/workflows/research-external-solution.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <example-usage>
-        ```
-        # Example with file path story and GitHub external repo
-        /ace:research-external-solution \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md \
-          external-codebase=https://github.com/tradingview/lightweight-charts \
-          external-docs=https://tradingview.github.io/lightweight-charts/
-
-        # Example with GitHub story and local external repo
-        /ace:research-external-solution \
-          story=https://github.com/owner/repo/issues/83 \
-          external-codebase=src/external/lightweight-charts/
-
-        # Example with context7 (no external-docs needed)
-        /ace:research-external-solution \
-          story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
-          external-codebase=https://github.com/tradingview/lightweight-charts
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - Continue with story refinement — integration analysis (pass 4) and technical solution (pass 5)
-        - `/ace:research-external-solution story=... external-codebase=...` — Analyze another story
-        - `/ace:help` — Check project initialization status
-    </next-steps>
-
-</command>
-```

package/commands/ace/research-integration-solution.md

@@ -1,135 +0,0 @@
----
-name: ace:research-integration-solution
-description: COMPREHENSIVE, IN-DEPTH System Integration Analysis for Integrating a New Story into the Existing Codebase
-argument-hint: "story=<file-path|github-url>"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - Agent
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-story — once story requirements (pass 1-2) are complete</trigger>
-            <trigger>After /ace:research-external-solution — if external analysis was performed (pass 3)</trigger>
-            <trigger>Anytime — when you need to understand how a story integrates with the existing codebase</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Story requirements and wiki references are available (passes 1-2 complete)</condition>
-            <condition>Need to understand how new functionality integrates with existing codebase</condition>
-            <condition>Want to identify refactoring needs, integration points, and hardcoded values to replace</condition>
-            <condition>Need a comprehensive analysis to guide AI agents implementing the story</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a markdown file containing the story (from plan-story command)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    Contains the user story, acceptance criteria, and Relevant Wiki references
-                    that define what to analyze and which wiki docs to load.
-                    **Requirements and wiki references are extracted from this story.**
-                    If not valid, stop and prompt the user.
-                </param>
-            </required>
-
-            <optional>
-                <!-- No optional parameters.
-                     All context is extracted from the story document:
-                     - Feature file (from story description/metadata)
-                     - Story requirements (User Story, Description, AC)
-                     - Wiki references (from Relevant Wiki section — pass 2)
-                     - External analysis (auto-detected in story directory)
-                -->
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <research-integration-workflow>@~/.claude/agile-context-engineering/workflows/research-integration-solution.xml</research-integration-workflow>
-        <integration-solution-template>@~/.claude/agile-context-engineering/templates/product/story-integration-solution.xml</integration-solution-template>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Perform a COMPREHENSIVE, IN-DEPTH System Integration Analysis that ensures new
-            story implementations integrate seamlessly with existing systems without breaking
-            functionality or violating architectural principles.
-
-            **[MANDATORY]** Identify how a new story would PROPERLY integrate with the existing
-            codebase while maintaining architectural integrity, maintainability, and extensibility
-            while strictly following CODING STANDARDS.
-
-            You are operating within a PRODUCTION-GRADE, CLEAN, COMPLEX CODEBASE — new code
-            must be added thoughtfully and systematically. The purpose is to analyze HOW TO ADD
-            NEW FUNCTIONALITY WHILE KEEPING THE CODE MAINTAINABLE AND EXTENSIBLE.
-
-            The analysis covers:
-            - Architecture compatibility with Clean Architecture layers
-            - Existing patterns to follow (with specific file references)
-            - Required refactoring (with justification)
-            - CRITICAL: Hardcoded values and placeholder code that MUST be replaced
-            - Integration points across all architectural layers
-            - Impact analysis on existing code flows
-            - Implementation guidelines and testing strategy
-            - Complete AI implementation context for the executing agent
-
-            All output is written ONLY to the analysis file — no GitHub updates,
-            no modifications to the story file. This artifact is consumed by
-            pass 5 (technical solution) of the story specification pipeline.
-        </objective>
-
-        <artifacts>
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/integration-analysis.md
-        </artifacts>
-    </output>
-
-    <process>
-        For this command use the `ace-code-integration-analyst` agent
-        that's specialized in code integration.
-
-        Execute the research-integration-solution workflow from
-        `@~/.claude/agile-context-engineering/workflows/research-integration-solution.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <example-usage>
-        ```
-        # Example with file path story
-        /ace:research-integration-solution \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-        # Example with GitHub story
-        /ace:research-integration-solution \
-          story=https://github.com/owner/repo/issues/83
-
-        # Example with just issue number (uses current repo)
-        /ace:research-integration-solution \
-          story=83
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - Continue with story refinement — technical solution (pass 5)
-        - `/ace:research-integration-solution story=...` — Analyze another story
-        - `/ace:help` — Check project initialization status
-    </next-steps>
-
-</command>
-```

package/commands/ace/research-story-wiki.md

@@ -1,116 +0,0 @@
----
-name: ace:research-story-wiki
-description: Research and curate wiki references relevant to a story's technical solution
-argument-hint: "story=<file-path|github-url>"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Edit
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - Agent
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-story pass 1 — once story business requirements (sections 1-8) are complete</trigger>
-            <trigger>Anytime — when a story needs its Relevant Wiki section populated or refreshed</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Story has sections 1-8 complete but no Relevant Wiki section</condition>
-            <condition>Story scope changed and wiki references need re-evaluation</condition>
-            <condition>Called as part of /ace:plan-story pipeline (pass 2)</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a markdown file containing the story (from plan-story command)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    Contains the user story, description, and acceptance criteria.
-                    **The story's requirements define which wiki docs are relevant.**
-                    If not valid, stop and prompt the user.
-                </param>
-            </required>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <research-story-wiki-workflow>@~/.claude/agile-context-engineering/workflows/research-story-wiki.xml</research-story-wiki-workflow>
-        <story-wiki-template>@~/.claude/agile-context-engineering/templates/product/story-wiki.xml</story-wiki-template>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Research the project's engineering wiki to identify documents that are
-            directly relevant to implementing this story. The output is a curated
-            `## Relevant Wiki` section that gets written into the story file
-            (and GitHub issue if applicable).
-
-            This section serves as the implementation context index — when an agent
-            starts implementing this story, it loads every document listed here.
-
-            The research process:
-            1. ALWAYS curates the four system-wide docs with story-specific reasons
-            2. Identifies affected subsystems from story content and feature context
-            3. Spawns parallel ace-wiki-mapper agents to scan subsystem wiki docs
-            4. Compiles a categorized, deduplicated list of relevant references
-
-            All output is written to the story file — populating the Relevant Wiki
-            section placeholder left by pass 1.
-        </objective>
-
-        <artifacts>
-            Modifies in-place: the story file at
-            .ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-story_name&gt;/&lt;id-story_name&gt;.md
-            (adds/replaces the ## Relevant Wiki section)
-        </artifacts>
-    </output>
-
-    <process>
-        For this command use the `ace-wiki-mapper` agent
-        that's specialized in wiki exploration and curation.
-
-        Execute the research-story-wiki workflow from
-        `@~/.claude/agile-context-engineering/workflows/research-story-wiki.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <example-usage>
-        ```
-        # Example with file path story
-        /ace:research-story-wiki \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-        # Example with GitHub issue number
-        /ace:research-story-wiki story=#95
-
-        # Example with full GitHub URL
-        /ace:research-story-wiki \
-          story=https://github.com/owner/repo/issues/95
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - Continue with story refinement — external analysis (pass 3) or technical solution (pass 5)
-        - `/ace:research-external-solution story=... external-codebase=...` — Analyze external reference systems
-        - `/ace:plan-story story=...` — Continue the full story pipeline
-        - `/ace:help` — Check project initialization status
-    </next-steps>
-
-</command>
-```