agile-context-engineering 0.3.0 → 0.5.1

package/{commands/ace/plan-product-vision.md → skills/plan-product-vision/SKILL.md}

@@ -1,81 +1,91 @@
----
-name: ace:plan-product-vision
-description: Create or update the product vision through architecture-aware questioning and guided writing
-argument-hint: "[optional: context='PRD, specs, or notes to build on']"
-allowed-tools:
-  - Read
-  - Bash
-  - 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, leverage architecture context</trigger>
-            <trigger>Anytime — to create or refresh the product vision for a project</trigger>
-        </runs-after>
-        <use-when>
-            <condition>Starting a new project and want to define the product vision (greenfield or brownfield)</condition>
-            <condition>Existing product vision is outdated or missing</condition>
-            <condition>System architecture has been mapped and you want to align vision with subsystem capabilities</condition>
-            <condition>Pivoting the product direction and need to rewrite the vision</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-        </flags>
-
-        <parameters>
-            <required>
-            </required>
-
-            <optional>
-                <param name="context" type="file | text">
-                    Existing PRD, specs, or notes to use as a starting point.
-                    Will be refined through the interview process, not used as-is.
-                </param>
-            </optional>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <plan-product-vision-workflow>@~/.claude/agile-context-engineering/workflows/plan-product-vision.xml</plan-product-vision-workflow>
-        <product-vision-template>@~/.claude/agile-context-engineering/templates/product/product-vision.xml</product-vision-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 brownfield/greenfield status and architecture context.
-            If brownfield with system architecture, use the Subsystem Responsibility Matrix
-            to inform high-level capabilities. Interview the user about their product vision,
-            goals, and audience. Generate a comprehensive product-vision.md.
-        </objective>
-
-        <artifacts>
-            .docs/product/product-vision.md
-        </artifacts>
-    </output>
-
-    <process>
-        Execute the plan-product-vision workflow from
-        `@~/.claude/agile-context-engineering/workflows/plan-product-vision.xml` end-to-end.
-        Preserve all workflow gates (validation, approvals, commits).
-    </process>
-
-    <next-steps>
-        **After this command:**
-        - `/ace:init-coding-standards` — Establish coding standards for the project
-        - `/ace:map-system` — Map codebase structure and architecture
-        - `/ace:help` — Check project initialization status and next steps
-    </next-steps>
-
-</command>
-```
+---
+name: plan-product-vision
+description: Create or update the product vision through architecture-aware questioning and guided writing
+argument-hint: "[optional: context='PRD, specs, or notes to build on']"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Task, AskUserQuestion
+model: opus
+effort: high
+---
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init 2>/dev/null`
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/product-vision-template.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>During /ace:help — as part of initial project setup</trigger>
+            <trigger>After /ace:map-system — once codebase is mapped, leverage architecture context</trigger>
+            <trigger>Anytime — to create or refresh the product vision for a project</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Starting a new project and want to define the product vision (greenfield or brownfield)</condition>
+            <condition>Existing product vision is outdated or missing</condition>
+            <condition>System architecture has been mapped and you want to align vision with subsystem capabilities</condition>
+            <condition>Pivoting the product direction and need to rewrite the vision</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="context" type="file | text">
+                    Existing PRD, specs, or notes to use as a starting point.
+                    Will be refined through the interview process, not used as-is.
+                </param>
+            </optional>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <!-- All supporting files are auto-loaded in the Supporting Resources section above.
+             The model does NOT need to Read these files — they are already in context. -->
+    </execution-context>
+
+    <output>
+        <objective>
+            Detect the project's brownfield/greenfield status and architecture context.
+            If brownfield with system architecture, use the Subsystem Responsibility Matrix
+            to inform high-level capabilities. Interview the user about their product vision,
+            goals, and audience. Generate a comprehensive product-vision.md.
+        </objective>
+
+        <artifacts>
+            .docs/product/product-vision.md
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the plan-product-vision workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:init-coding-standards` — Establish coding standards for the project
+        - `/ace:map-system` — Map codebase structure and architecture
+        - `/ace:help` — Check project initialization status and next steps
+    </next-steps>
+
+</command>
+```

package/{agile-context-engineering/templates/product/product-vision.xml → skills/plan-product-vision/product-vision-template.xml}

@@ -1,227 +1,227 @@
-<product-vision>
-   <purpose>Template for `.docs/product/product-vision.md` — organic document that aligns the team on what the product is, who it's for, and why it matters.</purpose>
-
-   <template>
-
-      ```markdown
-      # [Product Name]
-
-      ## Vision Statement
-
-      [A concise, inspiring statement of what the product aims to achieve and why it exists.
-      1-2 sentences. This is the elevator pitch — if someone reads nothing else, they read this.]
-
-      ## Target Audience
-
-      [Who is this product for? Define key user personas or segments.
-      Be specific — "everyone" is not a target audience.]
-
-      - **[Persona 1]**: [Who they are — what defines them]
-      - **[Persona 2]**: [Who they are — what defines them]
-
-      ## Problem Statement
-
-      [What specific pain points or unmet needs does this product address?
-      Frame from the user's perspective. What's broken, missing, or frustrating today?]
-
-      ## Value Proposition
-
-      [What unique value does the product deliver? Why would users choose this over alternatives?
-      Use Geoffrey Moore's format if helpful:
-      "For [target user] who [need], [product] is a [category] that [key benefit].
-      Unlike [alternative], our product [differentiator]."]
-
-      ## Key Objectives
-
-      <!-- Measurable business and user outcomes the product should achieve. -->
-      <!-- Tie to OKRs where possible. -->
-
-      - [ ] [Objective 1 — measurable outcome]
-      - [ ] [Objective 2 — measurable outcome]
-      - [ ] [Objective 3 — measurable outcome]
-
-      ## High-Level Capabilities
-
-      <!-- Broad capability areas, not detailed requirements. -->
-      <!-- These define the product's shape, not its spec. -->
-
-      - [Capability area 1]
-      - [Capability area 2]
-      - [Capability area 3]
-
-      ## Success Metrics
-
-      <!-- How will you know the product is achieving its vision? -->
-
-      | Metric | Target | Measurement Method |
-      |--------|--------|--------------------|
-      | [KPI 1] | [Target] | [How measured] |
-      | [KPI 2] | [Target] | [How measured] |
-
-      ## Competitive Landscape
-
-      [How does this product differentiate from existing solutions?
-      What alternatives exist and why aren't they sufficient?]
-
-      | Alternative | Strength | Gap We Fill |
-      |-------------|----------|-------------|
-      | [Competitor/Alternative 1] | [What they do well] | [What they miss] |
-      | [Competitor/Alternative 2] | [What they do well] | [What they miss] |
-
-      ## Constraints and Assumptions
-
-      - **[Type]**: [What] — [Why]
-      - **[Type]**: [What] — [Why]
-
-      Common types: Tech stack, Timeline, Budget, Dependencies, Regulatory, Platform
-
-      ## Risks
-
-      <!-- Key uncertainties that could affect the vision. -->
-
-      | Risk | Likelihood | Impact | Mitigation |
-      |------|-----------|--------|------------|
-      | [Risk 1] | [H/M/L] | [H/M/L] | [Strategy] |
-
-      ---
-      *Last updated: [date] after [trigger]*
-      ```
-
-   </template>
-
-   <guidelines>
-
-      **Vision Statement:**
-      - The north star — concise, inspiring, stable
-      - Should fit in one breath; if it takes a paragraph, it's too long
-      - Answers "why does this product exist?"
-      - Changes rarely; when it does, it's a pivot
-
-      **Target Audience:**
-      - Specific user personas or segments, not demographics
-      - Define by behavior and need, not just job title
-      - Primary vs secondary audiences if relevant
-      - Update as you learn who actually uses the product
-
-      **Problem Statement:**
-      - Frame from the user's perspective, not the builder's
-      - Describe the current pain, not your solution
-      - Be specific — vague problems lead to vague products
-      - Validated problems > assumed problems
-
-      **Value Proposition:**
-      - The bridge between problem and product
-      - Must differentiate from alternatives
-      - "Why this, why now, why us?"
-      - Test: could a competitor say the same thing? If yes, it's not specific enough
-
-      **Key Objectives:**
-      - Measurable outcomes, not features
-      - "Users can do X" not "Build feature Y"
-      - Tie to business goals where possible
-      - 3-5 objectives max — more means no focus
-
-      **High-Level Capabilities:**
-      - Broad strokes of what the product does
-      - Think capability areas, not feature lists
-      - These inform epic and feature planning downstream
-      - Should map clearly to objectives
-
-      **Success Metrics:**
-      - Quantifiable indicators of vision achievement
-      - Include target values and how you'll measure them
-      - Leading indicators (adoption, engagement) and lagging (revenue, retention)
-      - Revisit targets as you learn from real usage
-
-      **Competitive Landscape:**
-      - Honest assessment of alternatives (including "do nothing")
-      - Focus on gaps you fill, not feature comparisons
-      - Update as the market evolves
-
-      **Constraints and Assumptions:**
-      - Hard limits on what's possible
-      - Include the "why" — constraints without rationale get challenged
-      - Assumptions are constraints that haven't been validated yet
-      - Revisit assumptions regularly
-
-      **Risks:**
-      - Uncertainties that could derail the vision
-      - Include mitigation strategies, not just identification
-      - High-impact risks need contingency plans
-      - Update as risks materialize or are resolved
-
-      **Last Updated:**
-      - Always note when and why the document was updated
-      - Format: `after Phase 2` or `after user research round 1`
-      - Triggers review of whether content is still accurate
-
-   </guidelines>
-
-   <evolution>
-
-      product-vision.md evolves throughout the product lifecycle, but slower than most artifacts.
-
-      **After user research or discovery:**
-      1. Problem Statement still accurate? → Refine with evidence
-      2. Target Audience validated? → Update personas with real data
-      3. New risks or assumptions surfaced? → Add them
-      4. Value Proposition resonating? → Sharpen or pivot
-
-      **After each major release:**
-      1. Key Objectives met? → Mark achieved, add new ones
-      2. Success Metrics hitting targets? → Adjust targets or strategy
-      3. Competitive Landscape shifted? → Update positioning
-      4. Vision Statement still inspiring and accurate? → Refine if drifted
-
-      **After a pivot or strategic shift:**
-      1. Full review of all sections
-      2. Vision Statement rewrite
-      3. Problem Statement and Value Proposition realignment
-      4. Archive previous version for reference
-
-   </evolution>
-
-   <brownfield>
-
-      For existing products:
-
-      1. **Map current product** — what does it actually do today?
-
-      2. **Infer Vision and Value Proposition** from existing product:
-      - What problem is it currently solving?
-      - Who is actually using it?
-      - What do users say they value most?
-
-      3. **Gather forward-looking input** from stakeholders:
-      - Where should the product go next?
-      - What's missing from the current vision?
-
-      4. **Initialize:**
-      - Vision Statement = articulation of current + aspirational direction
-      - Target Audience = actual current users + desired future users
-      - Problem Statement = validated from real usage patterns
-      - Key Objectives = mix of "maintain what works" + "build what's next"
-      - Constraints = includes existing technical debt and commitments
-
-   </brownfield>
-
-   <state-reference>
-
-      STATE.md references product-vision.md:
-
-      ```markdown
-      ## Product Vision Reference
-
-      See: .artifacts/product-overview/product-vision.md (updated [date])
-
-      **Vision:** [One-liner from Vision Statement]
-      **Core audience:** [Primary persona]
-      **Current focus:** [Current phase or key objective]
-      ```
-
-      This ensures Claude reads the current product vision context.
-
-   </state-reference>
-
-
-</product-vision>
+<product-vision>
+   <purpose>Template for `.docs/product/product-vision.md` — organic document that aligns the team on what the product is, who it's for, and why it matters.</purpose>
+
+   <template>
+
+      ```markdown
+      # [Product Name]
+
+      ## Vision Statement
+
+      [A concise, inspiring statement of what the product aims to achieve and why it exists.
+      1-2 sentences. This is the elevator pitch — if someone reads nothing else, they read this.]
+
+      ## Target Audience
+
+      [Who is this product for? Define key user personas or segments.
+      Be specific — "everyone" is not a target audience.]
+
+      - **[Persona 1]**: [Who they are — what defines them]
+      - **[Persona 2]**: [Who they are — what defines them]
+
+      ## Problem Statement
+
+      [What specific pain points or unmet needs does this product address?
+      Frame from the user's perspective. What's broken, missing, or frustrating today?]
+
+      ## Value Proposition
+
+      [What unique value does the product deliver? Why would users choose this over alternatives?
+      Use Geoffrey Moore's format if helpful:
+      "For [target user] who [need], [product] is a [category] that [key benefit].
+      Unlike [alternative], our product [differentiator]."]
+
+      ## Key Objectives
+
+      <!-- Measurable business and user outcomes the product should achieve. -->
+      <!-- Tie to OKRs where possible. -->
+
+      - [ ] [Objective 1 — measurable outcome]
+      - [ ] [Objective 2 — measurable outcome]
+      - [ ] [Objective 3 — measurable outcome]
+
+      ## High-Level Capabilities
+
+      <!-- Broad capability areas, not detailed requirements. -->
+      <!-- These define the product's shape, not its spec. -->
+
+      - [Capability area 1]
+      - [Capability area 2]
+      - [Capability area 3]
+
+      ## Success Metrics
+
+      <!-- How will you know the product is achieving its vision? -->
+
+      | Metric | Target | Measurement Method |
+      |--------|--------|--------------------|
+      | [KPI 1] | [Target] | [How measured] |
+      | [KPI 2] | [Target] | [How measured] |
+
+      ## Competitive Landscape
+
+      [How does this product differentiate from existing solutions?
+      What alternatives exist and why aren't they sufficient?]
+
+      | Alternative | Strength | Gap We Fill |
+      |-------------|----------|-------------|
+      | [Competitor/Alternative 1] | [What they do well] | [What they miss] |
+      | [Competitor/Alternative 2] | [What they do well] | [What they miss] |
+
+      ## Constraints and Assumptions
+
+      - **[Type]**: [What] — [Why]
+      - **[Type]**: [What] — [Why]
+
+      Common types: Tech stack, Timeline, Budget, Dependencies, Regulatory, Platform
+
+      ## Risks
+
+      <!-- Key uncertainties that could affect the vision. -->
+
+      | Risk | Likelihood | Impact | Mitigation |
+      |------|-----------|--------|------------|
+      | [Risk 1] | [H/M/L] | [H/M/L] | [Strategy] |
+
+      ---
+      *Last updated: [date] after [trigger]*
+      ```
+
+   </template>
+
+   <guidelines>
+
+      **Vision Statement:**
+      - The north star — concise, inspiring, stable
+      - Should fit in one breath; if it takes a paragraph, it's too long
+      - Answers "why does this product exist?"
+      - Changes rarely; when it does, it's a pivot
+
+      **Target Audience:**
+      - Specific user personas or segments, not demographics
+      - Define by behavior and need, not just job title
+      - Primary vs secondary audiences if relevant
+      - Update as you learn who actually uses the product
+
+      **Problem Statement:**
+      - Frame from the user's perspective, not the builder's
+      - Describe the current pain, not your solution
+      - Be specific — vague problems lead to vague products
+      - Validated problems > assumed problems
+
+      **Value Proposition:**
+      - The bridge between problem and product
+      - Must differentiate from alternatives
+      - "Why this, why now, why us?"
+      - Test: could a competitor say the same thing? If yes, it's not specific enough
+
+      **Key Objectives:**
+      - Measurable outcomes, not features
+      - "Users can do X" not "Build feature Y"
+      - Tie to business goals where possible
+      - 3-5 objectives max — more means no focus
+
+      **High-Level Capabilities:**
+      - Broad strokes of what the product does
+      - Think capability areas, not feature lists
+      - These inform epic and feature planning downstream
+      - Should map clearly to objectives
+
+      **Success Metrics:**
+      - Quantifiable indicators of vision achievement
+      - Include target values and how you'll measure them
+      - Leading indicators (adoption, engagement) and lagging (revenue, retention)
+      - Revisit targets as you learn from real usage
+
+      **Competitive Landscape:**
+      - Honest assessment of alternatives (including "do nothing")
+      - Focus on gaps you fill, not feature comparisons
+      - Update as the market evolves
+
+      **Constraints and Assumptions:**
+      - Hard limits on what's possible
+      - Include the "why" — constraints without rationale get challenged
+      - Assumptions are constraints that haven't been validated yet
+      - Revisit assumptions regularly
+
+      **Risks:**
+      - Uncertainties that could derail the vision
+      - Include mitigation strategies, not just identification
+      - High-impact risks need contingency plans
+      - Update as risks materialize or are resolved
+
+      **Last Updated:**
+      - Always note when and why the document was updated
+      - Format: `after Phase 2` or `after user research round 1`
+      - Triggers review of whether content is still accurate
+
+   </guidelines>
+
+   <evolution>
+
+      product-vision.md evolves throughout the product lifecycle, but slower than most artifacts.
+
+      **After user research or discovery:**
+      1. Problem Statement still accurate? → Refine with evidence
+      2. Target Audience validated? → Update personas with real data
+      3. New risks or assumptions surfaced? → Add them
+      4. Value Proposition resonating? → Sharpen or pivot
+
+      **After each major release:**
+      1. Key Objectives met? → Mark achieved, add new ones
+      2. Success Metrics hitting targets? → Adjust targets or strategy
+      3. Competitive Landscape shifted? → Update positioning
+      4. Vision Statement still inspiring and accurate? → Refine if drifted
+
+      **After a pivot or strategic shift:**
+      1. Full review of all sections
+      2. Vision Statement rewrite
+      3. Problem Statement and Value Proposition realignment
+      4. Archive previous version for reference
+
+   </evolution>
+
+   <brownfield>
+
+      For existing products:
+
+      1. **Map current product** — what does it actually do today?
+
+      2. **Infer Vision and Value Proposition** from existing product:
+      - What problem is it currently solving?
+      - Who is actually using it?
+      - What do users say they value most?
+
+      3. **Gather forward-looking input** from stakeholders:
+      - Where should the product go next?
+      - What's missing from the current vision?
+
+      4. **Initialize:**
+      - Vision Statement = articulation of current + aspirational direction
+      - Target Audience = actual current users + desired future users
+      - Problem Statement = validated from real usage patterns
+      - Key Objectives = mix of "maintain what works" + "build what's next"
+      - Constraints = includes existing technical debt and commitments
+
+   </brownfield>
+
+   <state-reference>
+
+      STATE.md references product-vision.md:
+
+      ```markdown
+      ## Product Vision Reference
+
+      See: .artifacts/product-overview/product-vision.md (updated [date])
+
+      **Vision:** [One-liner from Vision Statement]
+      **Core audience:** [Primary persona]
+      **Current focus:** [Current phase or key objective]
+      ```
+
+      This ensures Claude reads the current product vision context.
+
+   </state-reference>
+
+
+</product-vision>