agile-context-engineering 0.3.0 → 0.5.0

package/agile-context-engineering/templates/_command.md

@@ -1,54 +0,0 @@
----
-name: ace:COMMAND_NAME
-description: COMMAND_DESCRIPTION
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-```xml
-<command>
-	
-	<execution-time>
-	</execution-time>
-	
-    <input>
-        <flags>
-		</flags>
-        
-        <parameters>
-            <required>
-			</required>
-			
-            <optional>
-			</optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-    </execution-context>
-
-    <output>
-        <objective>
-        </objective>
-        
-        <artifacts>
-        </artifacts>
-    </output>
-    
-    <process>
-    </process>
-
-    <success_criteria>
-    </success_criteria>
-    
-    <next-steps>
-    </next-steps>
-
-</command>
-```

package/agile-context-engineering/templates/_workflow.xml

@@ -1,17 +0,0 @@
-<workflow>
-
-    <purpose>
-    </purpose>
-
-    <mandatory-context>
-        [TODO] Read all files referenced by the invoking prompt's execution-context before starting. Also Read any document or text passed as parameter in the invoking command that called this template.
-    </mandatory-context>
-
-    <process>
-        <step name="1">
-        </step>
-
-        <step name="2">
-        </step>
-    </process>
-</workflow>

package/commands/ace/execute-story.md

@@ -1,138 +0,0 @@
----
-name: ace:execute-story
-description: Execute a fully-planned story — loads AC + Technical Solution, creates execution plan via Plan Mode, implements (solo or agent teams), runs code review, updates state, and triggers wiki mapping
-argument-hint: "story=<file-path|github-url> [--agent-teams-off]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Edit
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - Agent
-  - EnterPlanMode
-  - ExitPlanMode
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-story — once a story has AC + Technical Solution</trigger>
-            <trigger>Anytime — to execute a fully-planned story specification</trigger>
-        </runs-after>
-        <use-when>
-            <condition>A story has both Acceptance Criteria AND Technical Solution sections</condition>
-            <condition>Story status is "Refined" (ready for implementation)</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-            <flag name="--agent-teams-off">
-                Force solo execution mode regardless of agent_teams setting.
-                Overrides the agent_teams flag in settings.json.
-                Use when you want single-context execution even if teams are enabled.
-            </flag>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **File path**: Path to a fully-planned story markdown file
-                      (must have AC + Technical Solution sections)
-                    - **GitHub URL or issue number**: GitHub story reference
-                    Must be a valid, accessible file or GitHub issue.
-                    The story MUST have been through /ace:plan-story (has AC + Technical Solution).
-                </param>
-            </required>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <execute-story-workflow>@~/.claude/agile-context-engineering/workflows/execute-story.xml</execute-story-workflow>
-        <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
-        <walkthrough-template>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough-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 fully-planned story (with AC + Technical Solution) and:
-            1. Create an execution plan via Claude Code Plan Mode
-            2. Execute the plan — solo or with Agent Teams
-            3. Run code review (3-level verification, anti-pattern detection, coding standards)
-            4. Present results to user for verification/approval
-            5. Commit implementation (single commit after approval)
-            6. Update state: story file, feature file, product backlog, GitHub
-            7. Trigger wiki mapping (background) with tech debt integration
-
-            Two execution modes:
-            - **Solo Mode** (default or --agent-teams-off): Single context, plan mode → execute
-            - **Agent Teams Mode** (when enabled + plan recommends): Lead + teammates for parallel work
-        </objective>
-
-        <artifacts>
-            Story file updated with Summary &amp; State section and Wiki Updates section.
-            Feature file updated with story status.
-            Product backlog updated with story (and possibly feature) status.
-            Wiki documents updated/created based on implementation changes.
-        </artifacts>
-    </output>
-
-    <process>
-        **STRICT WORKFLOW EXECUTION — Follow the execute-story workflow STEP BY STEP.
-        Do NOT skip steps. Do NOT improvise. Do NOT start reading code or planning
-        until step 1 (init &amp; validate) is fully complete with the init command output parsed.**
-
-        Execute the execute-story workflow from
-        `@~/.claude/agile-context-engineering/workflows/execute-story.xml` end-to-end.
-
-        **MANDATORY FIRST ACTION: Run the init command (step 1.2) BEFORE doing anything else.
-        Do NOT read the story file manually. Do NOT explore the codebase. Do NOT start planning.
-        The init command validates the story and provides all paths and context needed.**
-
-        **CRITICAL REQUIREMENTS:**
-        - Story MUST have Acceptance Criteria — STOP if missing
-        - Story MUST have Technical Solution — STOP if missing
-        - NO intermediary commits during implementation
-        - ONE single commit per story after user approval (code + state + docs)
-        - Code review is MANDATORY — blockers must be fixed before approval
-        - Coding standards violations are BLOCKERS, not warnings
-        - Dead code and backwards-compatible shims must be DELETED
-    </process>
-
-    <example-usage>
-        ```
-        # Execute a story from a file path
-        /ace:execute-story \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-        # Execute from a GitHub issue
-        /ace:execute-story \
-          story=https://github.com/owner/repo/issues/95
-
-        # Force solo mode (no agent teams)
-        /ace:execute-story \
-          story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md \
-          --agent-teams-off
-
-        # With just an issue number
-        /ace:execute-story story=#95
-        ```
-    </example-usage>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:execute-story story=...` — Execute the next story in the feature
-        - `/ace:review-story story=...` — Re-run code review (standalone)
-        - `/ace:plan-story story=...` — Plan the next story
-        - `/ace:help` — Check project status
-    </next-steps>
-
-</command>
-```

package/commands/ace/help.md

@@ -1,93 +0,0 @@
----
-name: ace:help
-description: Check project initialization status and suggest next steps
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>At any time — to check which ACE documents exist and what to do next</trigger>
-            <trigger>At the start of a new project — to see the initialization checklist</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Starting a new project and want to see what needs to be set up</condition>
-            <condition>Returning to a project and want to check initialization status</condition>
-            <condition>Unsure which ACE command to run next</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <help-workflow>@~/.claude/agile-context-engineering/workflows/help.xml</help-workflow>
-        <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>
-            Detect which ACE documents exist (product vision, system architecture, system structure,
-            coding standards, testing framework). Display a status dashboard showing what's done
-            and what's missing. Suggest the next command to run based on gaps.
-        </objective>
-
-        <artifacts>
-            - .ace/settings.json (created on first run if missing)
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the help workflow from
-        `@~/.claude/agile-context-engineering/workflows/help.xml` end-to-end.
-        This is a lightweight state-check and routing workflow.
-
-        CRITICAL MANDATORY STEP — DO NOT SKIP:
-        Before displaying the status dashboard, you MUST run:
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js sync-agent-teams --raw
-        ```
-        Then you MUST use `AskUserQuestion` to ask the user whether they want to
-        enable or disable Claude Code Agent Teams (experimental feature).
-        This step is NOT optional. You MUST present this question every time.
-
-        When the user chooses to enable or disable Agent Teams, you MUST run the
-        bash command — NEVER directly edit .ace/settings.json or .claude/settings.json:
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams true
-        ```
-        or
-        ```bash
-        node ~/.claude/agile-context-engineering/src/ace-tools.js write-agent-teams false
-        ```
-        The write-agent-teams command updates BOTH .ace/settings.json AND .claude/settings.json.
-        Direct file edits will cause the two files to go out of sync.
-    </process>
-
-    <next-steps>
-        **Specialized commands for each document:**
-        - `/ace:plan-product-vision` — Create or update the product vision
-        - `/ace:map-system` — Map codebase structure, architecture, and testing framework
-        - `/ace:init-coding-standards` — Generate tailored coding standards
-    </next-steps>
-
-</command>
-```

package/commands/ace/init-coding-standards.md

@@ -1,83 +0,0 @@
----
-name: ace:init-coding-standards
-description: Generate a tailored coding-standards.md through codebase detection and user interview
-argument-hint: "[optional: context='existing standards doc or notes to build on']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
-  - AskUserQuestion
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>During /ace:help — as part of initial project setup</trigger>
-            <trigger>After /ace:map-system — once codebase is mapped, add prescriptive standards</trigger>
-            <trigger>Anytime — to create or refresh coding standards for a project</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Starting a new project and want to establish coding standards upfront (greenfield or brownfield)</condition>
-            <condition>Onboarding AI agents to an existing codebase (prevents common AI mistakes)</condition>
-            <condition>Current coding standards are outdated or missing</condition>
-            <condition>Team has pain points with AI-generated code quality</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-                <param name="context" type="file | text">
-                    Existing coding standards document, style guide, or notes
-                    to use as a starting point. Will be refined through the interview process.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <init-coding-standards-workflow>@~/.claude/agile-context-engineering/workflows/init-coding-standards.xml</init-coding-standards-workflow>
-        <coding-standards-template>@~/.claude/agile-context-engineering/templates/wiki/coding-standards.xml</coding-standards-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>
-            Detect the project's language, paradigm, and frameworks (brownfield) or gather
-            this from the user (greenfield). Interview the user about their coding philosophy
-            and pain points. Generate a tailored, prescriptive coding-standards.md that prevents
-            common AI and developer mistakes.
-        </objective>
-
-        <artifacts>
-            .docs/wiki/system-wide/coding-standards.md
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the init-coding-standards workflow from
-        `@~/.claude/agile-context-engineering/workflows/init-coding-standards.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:map-system` — Map codebase structure and architecture
-        - `/ace:help` — Check project initialization status and next steps
-        - Review and edit `.docs/wiki/system-wide/coding-standards.md` anytime
-    </next-steps>
-
-</command>
-```

package/commands/ace/map-story.md

@@ -1,165 +0,0 @@
----
-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>
-```