agile-context-engineering 0.1.0 → 0.2.0

package/agile-context-engineering/workflows/plan-product-vision.xml

@@ -0,0 +1,342 @@
+<workflow>
+
+    <purpose>
+        Orchestrate product vision creation or update through environment detection, architecture-aware
+        questioning, and document writing. Produces `.docs/product/product-vision.md` — the north star
+        document that aligns the team on what the product is, who it's for, and why it matters.
+
+        Brownfield projects with system architecture: use the Subsystem Responsibility Matrix to
+        pre-populate suggested capabilities. Without architecture: suggest /ace:map-system first.
+        Greenfield projects: gather everything from user interview directly.
+    </purpose>
+
+    <mandatory-context>
+        Read all files referenced by the invoking command's execution-context before starting.
+        Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
+    </mandatory-context>
+
+    <process>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 1: SETUP                                                     -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="setup" order="1">
+            **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
+
+            ```bash
+            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init product-vision)
+            ```
+
+            Parse JSON for: `product_owner_model`, `commit_docs`, `has_product_vision`,
+            `is_brownfield`, `is_greenfield`, `has_existing_code`, `has_package_file`,
+            `has_system_architecture`, `has_git`.
+
+            Also resolve the product owner model for spawning the writing agent:
+            ```bash
+            PO_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-product-owner --raw)
+            ```
+
+            Display stage banner:
+
+            ```
+            ╔══════════════════════════════════════════════════╗
+            ║  ACE > Product Vision                            ║
+            ╚══════════════════════════════════════════════════╝
+            ```
+
+            **If `has_product_vision` is true:**
+
+            Use AskUserQuestion:
+            - header: "Vision exists"
+            - question: "A product vision already exists at `.docs/product/product-vision.md`. What would you like to do?"
+            - options:
+              - "Update it" — Review and refine the existing vision
+              - "Start fresh" — Discard and create a new vision from scratch
+              - "Skip" — Keep the current vision as-is
+
+            If "Update": Read existing file, hold as seed context, continue to step 2
+            If "Start fresh": Ignore existing file, continue to step 2
+            If "Skip": Exit workflow
+
+            **If `has_git` is false:** Initialize git:
+            ```bash
+            git init
+            ```
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 2: PREREQUISITE CHECK + ARCHITECTURE CONTEXT                 -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="prerequisite-check" order="2">
+
+            **If `is_brownfield` AND `has_system_architecture` is false:**
+
+            Inform the user:
+            "Your project has code but no system architecture document yet. The architecture
+            analysis helps me understand your subsystems and infer capabilities for the product vision."
+
+            Use AskUserQuestion:
+            - header: "Architecture"
+            - question: "Would you like to map your system architecture first? This helps me infer capabilities from your codebase."
+            - options:
+              - "Run /ace:map-system first" — Exit and map architecture before creating the vision
+              - "Skip — I'll describe capabilities myself" — Continue without architecture context
+
+            If "Run /ace:map-system first":
+            - Display:
+              ```
+              ┌──────────────────────────────────────────────────┐
+              │  Next > /ace:map-system                           │
+              │         Then re-run /ace:plan-product-vision       │
+              └──────────────────────────────────────────────────┘
+              ```
+            - Exit workflow.
+
+            If "Skip — I'll describe capabilities myself":
+            - Hold architecture context as: `ARCHITECTURE = null`
+            - Continue to step 3.
+
+            **If `is_brownfield` AND `has_system_architecture` is true:**
+
+            Read `.docs/wiki/system-wide/system-architecture.md`.
+
+            Extract and hold as architecture context:
+            - **System Overview** — what the system is and does
+            - **Subsystem Responsibility Matrix** — subsystem names and their responsibilities
+              (the "Responsibility" column maps directly to capability areas for the product vision)
+            - **Tech Stack** — languages, frameworks, infrastructure
+
+            Hold as `ARCHITECTURE` for use in step 3 questioning.
+
+            **If `is_greenfield`:**
+
+            No architecture context available.
+            Hold architecture context as: `ARCHITECTURE = null`
+            Continue to step 3.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 3: DEEP QUESTIONING                                          -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="deep-questioning" order="3">
+            Follow the questioning guide from `questioning.xml`. You are a thinking partner,
+            not an interviewer.
+
+            **Opening — adapt based on available context:**
+
+            If greenfield (no architecture, no existing code):
+            - Open with: "What do you want to build?"
+            - Wait for their response. This gives you context for intelligent follow-ups.
+
+            If brownfield WITH architecture context:
+            - Acknowledge what you see: "I see your system [overview from ARCHITECTURE].
+              Your subsystems handle: [list responsibilities from Subsystem Responsibility Matrix].
+              Let's define the product vision around these capabilities."
+            - Use the Subsystem Responsibility Matrix to pre-populate suggested high-level
+              capabilities — the "Responsibility" column maps directly to capability areas.
+            - Probe: what's the product's purpose beyond the technical capabilities?
+              Who uses it? What problems does it solve?
+
+            If brownfield WITHOUT architecture context:
+            - Acknowledge existing code: "You have an existing codebase. Tell me about the product —
+              what does it do and who is it for?"
+            - Proceed with standard questioning.
+
+            If user provided a document/text ($ARGUMENTS):
+            - Absorb it first (do NOT summarize it back)
+            - Use it as seed context, probe gaps and ambiguities
+
+            **Follow the thread:**
+
+            Based on what they said (and what you absorbed), ask follow-up questions that dig
+            into their response. Use AskUserQuestion with options that probe what they mentioned —
+            interpretations, clarifications, concrete examples.
+
+            Keep following threads. Each answer opens new threads to explore:
+            - What excited them
+            - What problem sparked this
+            - What they mean by vague terms
+            - What it would actually look like
+            - What's already decided vs open
+            - Who specifically will use this
+
+            **Map answers to product-vision template sections (background, not out loud):**
+
+            As you question, mentally track coverage against the template:
+            - [ ] Vision — why does this product exist? (1-2 sentence elevator pitch)
+            - [ ] Target Audience — who specifically is this for?
+            - [ ] Problem Statement — what pain or unmet need?
+            - [ ] Value Proposition — why this over alternatives?
+            - [ ] Key Objectives — measurable outcomes (3-5)
+            - [ ] High-Level Capabilities — broad capability areas
+            - [ ] Constraints — tech, timeline, budget, platform
+            - [ ] Competitive Landscape — what alternatives exist?
+
+            If architecture context exists, the High-Level Capabilities checklist item gets
+            pre-populated from the Subsystem Responsibility Matrix. Confirm with the user
+            rather than asking from scratch.
+
+            Don't walk through this as a checklist. Weave questions naturally based on the
+            conversation. If gaps remain after the conversation feels complete, probe those
+            specific areas.
+
+            **Decision gate:**
+
+            When you could write a clear product-vision.md, use AskUserQuestion:
+            - header: "Ready?"
+            - question: "I think I understand what you're after. Ready to create the product vision?"
+            - options:
+              - "Create product vision" — Let's move forward
+              - "Keep exploring" — I want to share more / ask me more
+
+            If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
+
+            Loop until "Create product vision" selected.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 4: WRITE PRODUCT VISION                                      -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="write" order="4">
+            **Step 1 — Create directory structure:**
+            ```bash
+            mkdir -p .docs/product
+            ```
+
+            **Step 2 — Prepare a context brief (200-400 words max) that distills:**
+            - What the product is, who it's for, what problem it solves
+            - Key capabilities, constraints, competitive landscape discussed
+            - If architecture context exists: subsystem-derived capabilities, tech stack constraints
+            - Brownfield summary (if any existing product context was gathered)
+
+            **Step 3 — Spawn the vision-writing agent:**
+
+            ```
+            Task(
+                prompt="You are an Agile Product Owner writing a product vision document.
+
+                **Context brief from questioning session:**
+                {paste the context brief here}
+
+                **Instructions:**
+                1. Read the product vision template: ~/.claude/agile-context-engineering/templates/product/product-vision.xml
+                2. Write `.docs/product/product-vision.md` following the template structure and guidelines
+                3. Do not compress — capture everything from the context brief
+                4. Write the file using the Write tool
+
+                **Template guidelines:**
+                - **Vision Statement:** Concise, inspiring, 1-2 sentences. Answers 'why does this product exist?'
+                - **Target Audience:** Specific personas defined by behavior and need
+                - **Problem Statement:** Framed from user's perspective. Specific pain, not vague descriptions.
+                - **Value Proposition:** What differentiates this from alternatives. Use Geoffrey Moore's format if it fits.
+                - **Key Objectives:** 3-5 measurable outcomes. 'Users can do X' not 'Build feature Y'.
+                - **High-Level Capabilities:** Broad capability areas that define the product's shape. These inform epic planning downstream.
+                - **Success Metrics:** Quantifiable indicators with targets and measurement method.
+                - **Competitive Landscape:** Honest assessment of alternatives and gaps this product fills.
+                - **Constraints and Assumptions:** Hard limits with rationale. Tech stack, timeline, budget, platform, dependencies.
+                - **Risks:** Key uncertainties with likelihood, impact, and mitigation.
+                - **Last updated:** 'after initialization'
+
+                Do not compress. Capture everything gathered. If the user said it, it should be reflected somewhere in the document.
+
+                **Return format — ONLY this, nothing else:**
+                DONE
+                - [Vision statement in one line]
+                - [Target audience in one line]
+                - [Core problem in one line]
+                - [Number of capabilities listed]
+                - [Number of objectives listed]",
+                subagent_type="ace-product-owner",
+                model="{PO_MODEL}",
+                description="Write product vision document"
+            )
+            ```
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5: REVIEW AND APPROVE                                        -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="review" order="5">
+            Show the agent's returned summary to the user. Then:
+
+            - header: "Vision"
+            - question: "Product vision written to `.docs/product/product-vision.md`. Does this summary look right? Review the full file in your editor for details."
+            - options:
+              - "Approve" — Looks good, commit it
+              - "Adjust" — I want to change some things
+              - "Redo questioning" — Let's go back and explore more
+
+            **If "Adjust":**
+            - Ask what they want to change
+            - Spawn a Task agent to edit:
+              ```
+              Task(
+                  prompt="Read `.docs/product/product-vision.md` and make these changes:
+                  {user's requested changes}.
+                  Use the Edit tool to modify in place. Return only a confirmation of what changed.",
+                  subagent_type="general-purpose",
+                  model="haiku",
+                  description="Adjust product vision"
+              )
+              ```
+            - Present for review again. Loop until approved.
+
+            **If "Redo questioning":**
+            - Return to step 3 (deep-questioning), preserve architecture context
+            - Hold previous answers as context
+
+            **If "Approve":**
+            Continue to commit step.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 6: COMMIT                                                    -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="commit" order="6">
+            Commit the product vision:
+
+            ```bash
+            git add .docs/product/product-vision.md
+            git commit -m "docs: initialize product vision"
+            ```
+
+            Display completion:
+
+            ```
+            ╔══════════════════════════════════════════════════╗
+            ║  ACE > Product Vision Created                    ║
+            ╚══════════════════════════════════════════════════╝
+
+              +  .docs/product/product-vision.md committed.
+
+              i  This vision will be used as context by ACE commands
+                 when planning epics, features, and stories.
+
+              Next > /ace:init-coding-standards
+                     Establish coding standards for the project.
+                   > /ace:map-system
+                     Map your codebase structure and architecture.
+            ```
+        </step>
+
+    </process>
+
+    <success_criteria>
+        - Init function executed (brownfield/greenfield detected, architecture checked)
+        - Brownfield with architecture: subsystem responsibilities used to suggest capabilities
+        - Brownfield without architecture: user offered /ace:map-system or continued manually
+        - Greenfield: all context gathered from user interview
+        - User interviewed about product vision, goals, audience, capabilities
+        - product-vision.md written following template structure
+        - Document captures everything discussed, not compressed
+        - User reviewed and approved the document
+        - Document committed to .docs/product/
+    </success_criteria>
+
+</workflow>