agile-context-engineering 0.1.0 → 0.2.1

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

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

@@ -0,0 +1,156 @@
+---
+name: ace:map-story
+description: Update living knowledge docs — either after a story implementation (git-based) 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
+---
+
+```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>
+        </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>
+        <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/, decisions/).
+
+            In story mode: analyze git changes to determine what was built, detect
+            affected subsystem(s), and update/create docs to reflect the CURRENT system state.
+
+            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]/decisions/[decision-name].md
+        </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>
+```

package/commands/ace/map-subsystem.md

@@ -0,0 +1,138 @@
+---
+name: ace:map-subsystem
+description: Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/
+argument-hint: "subsystem='src/api' (or subsystem name) existing-docs=comma separated paths | directory"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:map-system — drill into individual subsystems</trigger>
+            <trigger>Anytime to refresh an existing subsystem's wiki documents</trigger>
+            <trigger>When a new subsystem is added and needs to be documented</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A subsystem has not yet been documented in `.docs/wiki/subsystems/`</condition>
+            <condition>An existing subsystem's docs are stale after a significant refactor</condition>
+            <condition>You want a deep-dive view of a specific subsystem's internals (components, flows, data)</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="subsystem" type="path | text">
+                    Path to the subsystem (e.g., `src/api`) or its name.
+                    If not provided, pause execution and ask the user for it.
+                    If provided but ambiguous, or not found in the codebase, ask clarifying questions.
+                </param>
+            </required>
+
+            <optional>
+                <param name="existing-docs" type="comma-separated paths or directories">
+                    Pre-existing documentation relevant to this subsystem. Accepts file paths,
+                    directory paths, or a mix of both. When a directory is provided, recursively
+                    discover all files within it (including nested subdirectories).
+                    All resolved file paths are passed through to every map-story invocation
+                    (file mode) alongside any per-module docs discovered during module-discovery.
+                    Use this when the caller already knows about documentation that should
+                    inform knowledge-doc generation.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <map-subsystem-workflow>@~/.claude/agile-context-engineering/workflows/map-subsystem.xml</map-subsystem-workflow>
+        <subsystem-structure-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-structure.xml</subsystem-structure-template>
+        <subsystem-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-architecture.xml</subsystem-architecture-template>
+        <module-discovery-template>@~/.claude/agile-context-engineering/templates/wiki/module-discovery.xml</module-discovery-template>
+        <map-story-workflow>@~/.claude/agile-context-engineering/workflows/map-story.xml</map-story-workflow>
+        <system-template>@~/.claude/agile-context-engineering/templates/wiki/system.xml</system-template>
+        <pattern-template>@~/.claude/agile-context-engineering/templates/wiki/pattern.xml</pattern-template>
+        <cross-cutting-template>@~/.claude/agile-context-engineering/templates/wiki/system-cross-cutting.xml</cross-cutting-template>
+        <guide-template>@~/.claude/agile-context-engineering/templates/wiki/guide.xml</guide-template>
+        <decisions-template>@~/.claude/agile-context-engineering/templates/wiki/decizions.xml</decisions-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>
+            Resolve the target subsystem, load system-wide wiki context, and determine whether
+            to create, update, or recreate per-subsystem wiki documents. Then:
+
+            1. Spawn ace-wiki-mapper agents to produce structure and architecture documents.
+            2. Update system-structure.md if this subsystem was not previously listed there.
+            3. Update the subsystem responsibility matrix in system-architecture.md if missing.
+            4. Run module discovery — trace E2E flows, identify patterns, find cross-cutting
+               concerns by reading actual source code. Produce module-discovery.md artifact.
+            5. For EACH discovered module, run map-story in file mode to create or update
+               knowledge documentation (systems/, patterns/, cross-cutting/, guides/, decisions/).
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/subsystems/[subsystem-name]/structure.md
+            - .docs/wiki/subsystems/[subsystem-name]/architecture.md
+            - .docs/wiki/subsystems/[subsystem-name]/systems/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/patterns/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/cross-cutting/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/guides/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/decisions/*.md (created/updated by map-story)
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/module-discovery.md
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/existing-docs-inventory.md (if existing-docs directory provided)
+            - .docs/wiki/system-wide/system-structure.md (subsystem entry added if new)
+            - .docs/wiki/system-wide/system-architecture.md (subsystem responsibility matrix updated if missing)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-subsystem workflow from
+        `@~/.claude/agile-context-engineering/workflows/map-subsystem.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+
+        The workflow has 13 steps:
+        1-5: Setup, context loading, subsystem resolution, document triage, directory creation
+        6-8: Structure + architecture agents (parallel) + collect results
+        9: Update system-wide docs (system-structure.md, system-architecture.md)
+        10: Module discovery (3 parallel discovery agents + 1 synthesis agent)
+        11: Knowledge documentation — run map-story for EACH discovered module (sequential)
+        12: Verify and commit all documents
+        13: Completion report
+
+        Steps 10-11 are CRITICAL — they produce the knowledge docs (systems/, patterns/,
+        cross-cutting/, guides/, decisions/) that AI agents need for future implementations.
+        Do NOT skip them.
+    </process>
+
+     <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+
+        For each subsystem found and defined in the Subsystem Responsibility Matrix,
+        suggest a `/ace:map-subsystem` command. Example:
+        - `/ace:map-subsystem subsystem="src/api"` — Map the API subsystem
+        - `/ace:map-subsystem subsystem="src/auth"` — Map the Auth subsystem
+        - `/ace:map-subsystem subsystem="src/db"` — Map the DB subsystem
+        (list one per subsystem discovered during this command's execution)
+
+        Also suggest:
+        - `/ace:init-coding-standards` — Define prescriptive coding standards
+        - `/ace:help` — Check project initialization status and next steps
+        - Review and edit files in `.docs/wiki/system-wide/` anytime
+    </next-steps>
+
+</command>
+```

package/commands/ace/map-system.md

@@ -0,0 +1,92 @@
+---
+name: ace:map-system
+description: Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/
+argument-hint: "[optional: references='existing artifacts and documents to be considered alongside the codebase']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>Before /ace:help (brownfield codebases) — understand existing code first</trigger>
+            <trigger>After /ace:help (greenfield codebases) — document architecture decisions</trigger>
+            <trigger>Anytime to refresh system-wide wiki documents</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Onboarding to an existing codebase (brownfield — analyzes code automatically)</condition>
+            <condition>Starting a new project and need to document architecture decisions (greenfield — interviews you)</condition>
+            <condition>System-wide documents are stale or missing</condition>
+            <condition>After major refactoring that changed subsystem boundaries or tech stack</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="references" type="file | text">
+                    Existing architecture docs, ADRs, or design notes
+                    to consider alongside the codebase analysis. Absorbed before analysis begins.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <map-system-workflow>@~/.claude/agile-context-engineering/workflows/map-system.xml</map-system-workflow>
+        <system-structure-template>@~/.claude/agile-context-engineering/templates/wiki/system-structure.xml</system-structure-template>
+        <system-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml</system-architecture-template>
+        <testing-framework-template>@~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml</testing-framework-template>
+        <wiki-readme-template>@~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml</wiki-readme-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 brownfield/greenfield status and existing wiki state. For each system-wide
+            document (structure, architecture, testing), determine whether to create, update,
+            recreate, scaffold, or skip. Spawn ace-wiki-mapper agents to produce documents.
+            For greenfield architecture, conduct deep questioning before generating.
+            Add CLAUDE.md instructions to keep wiki current with future code changes.
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/wiki-readme.md (created if not already present)
+            - .docs/wiki/system-wide/system-structure.md
+            - .docs/wiki/system-wide/system-architecture.md
+            - .docs/wiki/system-wide/testing-framework.md
+            - CLAUDE.md (wiki maintenance instructions appended)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-system workflow from
+        `@~/.claude/agile-context-engineering/workflows/map-system.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+        - `/ace:map-subsystems` — Map individual subsystem internals (structure, dependencies)
+        - `/ace:init-coding-standards` — Define prescriptive coding standards
+        - `/ace:help` — Check project initialization status and next steps
+        - Review and edit files in `.docs/wiki/system-wide/` anytime
+    </next-steps>
+
+</command>
+```

package/commands/ace/plan-backlog.md

@@ -0,0 +1,83 @@
+---
+name: ace:plan-backlog
+description: Create or refine the product backlog through vision-aware questioning, wiki analysis, and guided epic/feature planning
+argument-hint: "[optional: context='text, file, or URL with product description and suggested epics/features']"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-product-vision — once the vision exists, plan what to build</trigger>
+            <trigger>After /ace:map-system — once architecture is mapped, leverage wiki context for richer backlog</trigger>
+            <trigger>Anytime — to create or refresh the product backlog</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Product vision exists and you want to break it into epics and features</condition>
+            <condition>Starting implementation planning and need a structured backlog</condition>
+            <condition>Brownfield project where features need to be inventoried from existing code</condition>
+            <condition>Updating the backlog after scope changes or new discoveries</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="context" type="file | text">
+                    Product description, suggested epics/features, PRD excerpts, or any
+                    context to seed the backlog planning process. Will be absorbed and
+                    refined through questioning, not used as-is.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <plan-backlog-workflow>@~/.claude/agile-context-engineering/workflows/plan-backlog.xml</plan-backlog-workflow>
+        <product-backlog-template>@~/.claude/agile-context-engineering/templates/product/product-backlog.xml</product-backlog-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 environment, load the product vision as the north-star input,
+            optionally analyze the wiki for existing capabilities and feature status,
+            optionally research the domain ecosystem for standard features,
+            absorb any user-provided context, conduct deep questioning to discover all
+            epics and features, and generate a comprehensive product-backlog.md.
+        </objective>
+
+        <artifacts>
+            .ace/artifacts/product/product-backlog.md
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the plan-backlog workflow from
+        `@~/.claude/agile-context-engineering/workflows/plan-backlog.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:plan-feature E1` — Break an feature into detailed stories
+        - `/ace:help` — Check project initialization status
+        - `/ace:plan-product-vision` — Update the product vision if priorities shifted
+    </next-steps>
+
+</command>
+```

package/commands/ace/plan-feature.md

@@ -0,0 +1,89 @@
+---
+name: ace:plan-feature
+description: Plan a feature through backlog-aware questioning, story decomposition, and guided feature specification
+argument-hint: "[feature-id] [optional: context='text or file with feature description prompt']"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-backlog — once the backlog exists, plan individual features</trigger>
+            <trigger>Anytime — to create or refine a feature and its story breakdown</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Product backlog exists and you want to break a feature into stories</condition>
+            <condition>Starting feature-level planning and need to decompose into stories</condition>
+            <condition>Refining an existing feature with updated acceptance criteria or scope</condition>
+            <condition>Adding a new feature to an existing epic</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="feature-id" type="text">
+                    Feature identifier from the product backlog (e.g., F3, #78).
+                    If provided, locates existing feature for planning or refinement.
+                    If omitted, presents the backlog for selection or allows creating
+                    a new feature.
+                </param>
+                <param name="context" type="file | text">
+                    Feature description, acceptance criteria, user stories, or any
+                    context to seed the feature planning process. Will be absorbed and
+                    refined through questioning, not used as-is.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <plan-feature-workflow>@~/.claude/agile-context-engineering/workflows/plan-feature.xml</plan-feature-workflow>
+        <feature-template>@~/.claude/agile-context-engineering/templates/product/feature.xml</feature-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 environment, load the product backlog and epic context,
+            absorb any user-provided feature description, conduct deep questioning to
+            define feature scope and acceptance criteria, decompose the feature into
+            stories, and generate feature and story artifact files.
+            Optionally create GitHub issues if github-project.enabled=true.
+        </objective>
+
+        <artifacts>
+            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-feature_name>.md
+            .ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/<id-story_name>.md
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the plan-feature workflow from
+        `@~/.claude/agile-context-engineering/workflows/plan-feature.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:plan-story story-id` — Plan a story
+        - `/ace:plan-feature feature-id` — Plan another feature
+        - `/ace:help` — Check project initialization status
+    </next-steps>
+
+</command>
+```