@shahmarasy/prodo 0.1.3 → 0.1.4

package/templates/commands/prodo-workflow.md

@@ -1,26 +1,209 @@
 ---
-description: Generate workflow artifacts.
+description: >
+  Generate workflow artifacts (Markdown documentation + Mermaid diagrams) from product brief and PRD.
+  Produces detailed process flows, sequence diagrams, and system interaction maps for implementation and QA planning.
+agent-role: "Process Flow Analyst & System Architect"
+agent-profile: |
+  **Character**: Methodical Process Engineer
+  - **Personality**: Logic-focused, sequence-oriented, edge-case-aware
+  - **Specialization**: Process flow design, sequence diagramming, state machine modeling
+  - **Decision Style**: Logic-driven, exception-aware, completeness-focused
+  - **Tolerance**: Intolerant of incomplete workflows; demands all paths documented
+  
+agent-skills: |
+  ✓ **Core Skills**:
+    - Primary user workflow design
+    - System interaction sequencing
+    - Exception path documentation
+    - State machine design & validation
+    - Decision tree articulation
+    - Timeline & async operation planning
+    - Mermaid diagram generation
+  
+  ✓ **Performance Metrics**:
+    - Speed: Moderate (requires deep thinking)
+    - Completeness: 100% workflow coverage (happy path + exceptions)
+    - Clarity: Diagrams are self-explanatory
+    - Coverage: All actors & systems mapped
+  
+  ✓ **Problem-Solving Approach**:
+    - Map user personas to workflows
+    - Document happy paths & exception paths
+    - Visualize system interactions with sequence diagrams
+    - Define state transitions & decision points
+
+agent-decision-strategy: |
+  **Decision Tree**:
+  1. PRD & personas available? → Continue | Request prodo-prd first
+  2. All user workflows defined? → Continue | Identify missing workflows
+  3. Exception paths documented? → Continue | Identify gaps (timeouts, errors, retries)
+  4. System interactions clear? → Continue | Document integration points
+  5. Diagrams valid? → Include | Validate Mermaid syntax
+  
+  **When to Escalate**:
+    - Workflow has circular dependency → Need process re-design
+    - External system interactions ambiguous → Need 3rd-party spec
+    - Async timing requirements unclear → Need performance specs
+    - Exception handling strategy undefined → Need reliability discussion
+
+agent-efficiency-tips: |
+  ⚡ **For Maximum Efficiency**:
+  - Use user stories as workflow basis (stories already decomposed)
+  - Parallel generation: workflows created while wireframes in progress
+  - Template-driven Mermaid syntax (reusable diagram patterns)
+  - Multi-diagram approach: flowchart (user) + sequence (system) + state (complex)
+  - Document timing: explicit about sync/async operations
+  - Exception-first thinking: identify all failure modes upfront
+  - Reusable patterns: document standard error handling once, reference elsewhere
 ---
 
-## User Input
+## Context
+
+**Purpose**: Create process flow documentation and visual diagrams describing how users and systems interact to accomplish product goals.
+
+**Upstream Dependencies**:
+- `.prodo/` configuration directory must exist.
+- `brief.md` must exist and be valid.
+- `.prodo/briefs/normalized-brief.json` must exist (Execute normalize step if missing).
+- Latest PRD artifact must exist under `product-docs/prd/` (Execute PRD generation step if missing).
+
+**Output Format**: Paired artifacts (Markdown + Mermaid)
+- **Workflow.md**: Textual documentation of workflows, process steps, decision points, and system interactions.
+- **Workflow.mmd**: Visual Mermaid diagrams (flowcharts, sequence diagrams, state machines) representing workflows.
+
+**Downstream Impact**: Workflows guide development team on feature implementation sequences, QA test scenarios, integration planning, and user journey validation.
+
+**User Input**
 
 ```text
 $ARGUMENTS
 ```
 
-Execution policy:
+## Execution Policy
+
+**Safety & Integrity**:
 - Execute-first, diagnose-second.
-- Do not run shell/CLI commands from inside the agent.
-- Never run `prodo-workflow`, `prodo workflow`, or `prodo ...` in shell.
-- Input files are read-only; never modify or rewrite `brief.md`.
-- Never print full artifact JSON/Markdown in chat.
-- Write outputs to files, then reply with short status + written file path(s).
-
-## Execution
-
-1. Verify minimal prerequisites (`.prodo/`, `brief.md`, normalized brief).
-2. Use normalized brief + latest PRD and apply workflow templates (`.prodo/templates/workflow.md` and `.prodo/templates/workflow.mmd`).
-3. Confirm paired outputs exist under `product-docs/workflows/` (`.md` + `.mmd`).
-4. Confirm `brief.md` content did not change.
-5. Do not create manual fallback files under `.prodo/`.
-6. Diagnose internals only if command fails.
+- Do not execute shell/CLI commands from inside the agent.
+- Never invoke `prodo-workflow`, `prodo workflow`, or `prodo ...` commands in shell.
+- **Input files are read-only**: Never modify brief.md, normalized-brief.json, or upstream artifacts.
+- Never print full workflow code or diagrams to chat; return only status + output file paths.
+- **Write in selected language setting on `.prodo/settings.json`** (default: "en")
+
+**Output Quality**:
+- Write both workflow.md and workflow.mmd to `product-docs/workflows/` directory.
+- Workflows must follow approved templates from `.prodo/templates/workflow.md` and `.prodo/templates/workflow.mmd`.
+- Markdown should focus on detailed process documentation (step descriptions, system interactions, decision criteria, error handling).
+- Mermaid diagrams should visualize workflows clearly (flowcharts for user flows, sequence diagrams for system interactions, state machines for complex states).
+- Maintain consistency with PRD features, user personas, user stories, and business goals.
+
+## Execution Steps
+
+1. **Verify Upstream Dependencies**
+   - Confirm `.prodo/` directory exists.
+   - Confirm `brief.md` exists and is readable.
+   - Confirm `.prodo/briefs/normalized-brief.json` exists and is valid JSON.
+   - Confirm latest PRD exists under `product-docs/prd/`.
+   - If PRD is missing, report error with instruction to execute PRD generation step first.
+   - Check for corrupt or stale artifact state.
+
+2. **Load Product & PRD Context**
+   - Read normalized-brief.json to extract:
+     - Product vision and goals.
+     - User personas and target audience.
+     - Key business processes and workflows.
+     - System integrations and external dependencies.
+     - Success criteria and KPIs.
+   - Read latest PRD to extract:
+     - Core features and feature scope.
+     - User personas and their goals.
+     - Critical user journeys and happy paths.
+     - Business constraints and technical considerations.
+     - Feature priorities and phasing.
+
+3. **Apply Workflow Templates**
+   - Load `.prodo/templates/workflow.md` and `.prodo/templates/workflow.mmd` templates.
+   - Synthesize product context into workflows:
+     - **Primary User Workflows**: Main workflows for each user persona (onboarding, core task, payment, etc.).
+     - **System Workflows**: Backend processes and integrations (data sync, notifications, batch jobs, etc.).
+     - **Exception Workflows**: Error handling, retry logic, fallback scenarios.
+     - **Sequence Diagrams**: Actor interactions (user, frontend, backend, third-party APIs) with detailed step sequence.
+     - **Decision Trees**: Conditional branching based on user input or system state.
+     - **State Machines**: Complex feature states and valid state transitions.
+     - **Performance Considerations**: Steps with expected duration, bottlenecks, optimization areas.
+
+4. **Generate Markdown Workflow Documentation**
+   - Create workflow.md with:
+     - **Executive Summary**: Product vision, primary user personas, key workflows covered.
+     - **User Personas & Goals**: How each persona accomplishes their goals through the product.
+     - **Primary Workflows**: For each major use case:
+       - **Workflow Name**: Descriptive title (e.g., "User Registration & Email Verification").
+       - **Actors**: Who participates (user roles, system components, third-party services).
+       - **Preconditions**: State before workflow starts (prerequisites, required data).
+       - **Happy Path**: Step-by-step process flow (numbered steps with descriptions).
+       - **Decision Points**: Conditional branches with criteria and outcomes.
+       - **Exception Paths**: Error scenarios and recovery steps (e.g., network timeout, invalid input).
+       - **Postconditions**: Expected state after workflow completes.
+       - **Success Criteria**: How to validate workflow completed successfully.
+       - **Performance Notes**: Expected duration, throughput, constraints.
+     - **System Workflows**: Backend processes (data sync, notifications, batch jobs, webhooks).
+     - **Integration Points**: Third-party systems, APIs, and data exchanges.
+     - **Timeline Considerations**: Any time-dependent aspects (rate limiting, async processing, retries).
+     - **Error Handling Strategy**: How errors are detected, logged, and recovered from.
+
+5. **Generate Mermaid Workflow Diagrams**
+   - Create workflow.mmd with visual representations:
+     - **Flowchart (User Workflows)**: For each primary workflow:
+       - Start/end nodes.
+       - Process steps (rectangles).
+       - Decision nodes (diamonds).
+       - System/external action nodes.
+       - Clear labels and flow direction.
+     - **Sequence Diagram (System Interactions)**: For critical workflows:
+       - Participants: user, frontend, backend, database, external services.
+       - Message flows with descriptions.
+       - Synchronous vs. asynchronous interactions.
+       - Error cases and recovery paths.
+     - **State Machine (Complex Features)**: For features with multiple states:
+       - States (circles/rectangles).
+       - Valid transitions with trigger labels.
+       - Initial and final states.
+     - **Timeline Diagram (Optional)**: For workflows with timing constraints (rate limiting, async processing).
+
+6. **Validate Paired Workflow Artifacts**
+   - Confirm both workflow.md and workflow.mmd were created under `product-docs/workflows/`.
+   - Validate markdown structure: proper headings, consistent formatting, complete workflow descriptions.
+   - Validate Mermaid syntax: diagrams parse correctly, no syntax errors.
+   - Render Mermaid diagrams: verify visual clarity and readability.
+   - Verify workflows cover all PRD features and user personas.
+   - Verify workflows do not contradict PRD, brief, or other artifacts.
+   - Verify exception paths and error handling are documented.
+   - Verify system integrations are clearly identified.
+   - Check for workflow completeness (all steps, decision paths, error cases documented).
+   - Include metadata header: generation date, PRD hash, template version.
+
+7. **Audit & Verify Integrity**
+   - Confirm original `brief.md`, normalized-brief.json, and PRD files were not modified.
+   - Log file paths, workflow count, and generation metadata.
+
+8. **Safety Constraints**
+   - Do not create manual fallback files under `.prodo/`.
+   - Do not write outside `product-docs/workflows/` directory.
+   - Do not modify config, template, PRD, or brief files.
+
+9. **Diagnosis & Error Handling**
+   - If PRD is missing: report error with instruction to execute PRD generation step first.
+   - If normalized-brief.json is missing: report error with instruction to execute normalize step first.
+   - If workflows are complex or unclear: flag as warnings and suggest expert review.
+   - If Mermaid syntax is invalid: report syntax error with correction suggestions.
+   - If system integrations are unclear: flag for clarification in brief or PRD.
+   - If file system write fails: report permissions or directory creation error.
+
+## Success Criteria
+
+- ✅ Both workflow.md and workflow.mmd exist under `product-docs/workflows/`.
+- ✅ Markdown includes detailed descriptions of all primary workflows, decision points, and error handling.
+- ✅ Mermaid diagrams are syntactically valid and visually represent workflows clearly.
+- ✅ Workflows cover all PRD features and user personas.
+- ✅ Workflows align with brief goals, constraints, and user personas.
+- ✅ Original brief, normalized-brief, and PRD remain unchanged.
+- ✅ Workflows are ready for development implementation, QA planning, and system integration.