@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/src/modules/xmc/workflows/2-plan-workflows/prd/steps/step-11-complete.md

@@ -0,0 +1,210 @@
+# Step 11: Workflow Completion
+
+**Final Step - Complete the PRD**
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ THIS IS A FINAL STEP - Workflow completion required
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- 🛑 NO content generation - this is a wrap-up step
+- 📋 FINALIZE document and update workflow status
+- 💬 FOCUS on completion, next steps, and suggestions
+- 🎯 UPDATE workflow status files with completion information
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Update the main workflow status file with completion information
+- 📖 Suggest potential next workflow steps for the user
+- 🚫 DO NOT load additional steps after this one
+
+## TERMINATION STEP PROTOCOLS:
+
+- This is a FINAL step - workflow completion required
+- Output any remaining content if needed (none for this step)
+- Update the main workflow status file with finalized document
+- Suggest potential next steps for the user
+- Mark workflow as complete in status tracking
+
+## CONTEXT BOUNDARIES:
+
+- Complete PRD document is available from all previous steps
+- Workflow frontmatter shows all completed steps
+- All collaborative content has been generated and saved
+- Focus on completion, validation, and next steps
+
+## YOUR TASK:
+
+Complete the PRD workflow, update status files, and suggest next steps for the project.
+
+## WORKFLOW COMPLETION SEQUENCE:
+
+### 1. Announce Workflow Completion
+
+Inform user that the PRD is complete:
+"🎉 **PRD Complete, {{user_name}}!**
+
+I've successfully collaborated with you to create a comprehensive Product Requirements Document for {{project_name}}.
+
+**What we've accomplished:**
+
+- ✅ Executive Summary with vision and product differentiator
+- ✅ Success Criteria with measurable outcomes and scope definition
+- ✅ User Journeys covering all interaction patterns
+- ✅ Domain-specific requirements (if applicable)
+- ✅ Innovation analysis (if applicable)
+- ✅ Project-type specific technical requirements
+- ✅ Comprehensive Functional Requirements (capability contract)
+- ✅ Non-Functional Requirements for quality attributes
+
+**The complete PRD is now available at:** `{output_folder}/prd.md`
+
+This document is now ready to guide UX design, technical architecture, and development planning."
+
+### 2. Workflow Status Update
+
+Update the main workflow status file:
+
+- Load `{status_file}` from workflow configuration (if exists)
+- Update workflow_status["prd"] = "{default_output_file}"
+- Save file, preserving all comments and structure
+- Mark current timestamp as completion time
+
+### 3. Suggest Next Steps
+
+Provide guidance on logical next workflows:
+
+**Typical Next Workflows:**
+
+**Immediate Next Steps:**
+
+1. `workflow create-ux-design` - UX Design (if UI exists)
+   - User journey insights from step-04 will inform interaction design
+   - Functional requirements from step-09 define design scope
+
+2. `workflow create-architecture` - Technical architecture
+   - Project-type requirements from step-07 guide technical decisions
+   - Non-functional requirements from step-10 inform architecture choices
+
+3. `workflow create-epics-and-stories` - Epic breakdown
+   - Functional requirements from step-09 become epics and stories
+   - Scope definition from step-03 guides sprint planning
+
+**Strategic Considerations:**
+
+- UX design and architecture can happen in parallel
+- Epics/stories are richer when created after UX/architecture
+- Consider your team's capacity and priorities
+
+**What would be most valuable to tackle next?**
+
+### 4. Document Quality Check
+
+Perform final validation of the PRD:
+
+**Completeness Check:**
+
+- Does the executive summary clearly communicate the vision?
+- Are success criteria specific and measurable?
+- Do user journeys cover all major user types?
+- Are functional requirements comprehensive and testable?
+- Are non-functional requirements relevant and specific?
+
+**Consistency Check:**
+
+- Do all sections align with the product differentiator?
+- Is scope consistent across all sections?
+- Are requirements traceable to user needs and success criteria?
+
+### 5. Final Completion Confirmation
+
+Confirm completion with user:
+"**Your PRD for {{project_name}} is now complete and ready for the next phase!**
+
+The document contains everything needed to guide:
+
+- UX/UI design decisions
+- Technical architecture planning
+- Development prioritization and sprint planning
+
+**Ready to continue with:**
+
+- UX design workflow?
+- Architecture workflow?
+- Epic and story creation?
+
+**Or would you like to review the complete PRD first?**
+
+[Workflow Complete]"
+
+## SUCCESS METRICS:
+
+✅ PRD document contains all required sections
+✅ All collaborative content properly saved to document
+✅ Workflow status file updated with completion information
+✅ Clear next step guidance provided to user
+✅ Document quality validation completed
+✅ User acknowledges completion and understands next options
+
+## FAILURE MODES:
+
+❌ Not updating workflow status file with completion information
+❌ Missing clear next step guidance for user
+❌ Not confirming document completeness with user
+❌ Workflow not properly marked as complete in status tracking
+❌ User unclear about what happens next
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## WORKFLOW COMPLETION CHECKLIST:
+
+### Document Structure Complete:
+
+- [ ] Executive Summary with vision and differentiator
+- [ ] Success Criteria with measurable outcomes
+- [ ] Product Scope (MVP, Growth, Vision)
+- [ ] User Journeys (comprehensive coverage)
+- [ ] Domain Requirements (if applicable)
+- [ ] Innovation Analysis (if applicable)
+- [ ] Project-Type Requirements
+- [ ] Functional Requirements (capability contract)
+- [ ] Non-Functional Requirements
+
+### Process Complete:
+
+- [ ] All steps completed with user confirmation
+- [ ] All content saved to document
+- [ ] Frontmatter properly updated
+- [ ] Workflow status file updated
+- [ ] Next steps clearly communicated
+
+## NEXT STEPS GUIDANCE:
+
+**Immediate Options:**
+
+1. **UX Design** - If product has UI components
+2. **Technical Architecture** - System design and technology choices
+3. **Epic Creation** - Break down FRs into implementable stories
+4. **Review** - Validate PRD with stakeholders before proceeding
+
+**Recommended Sequence:**
+For products with UI: UX → Architecture → Epics
+For API/backend products: Architecture → Epics
+Consider team capacity and timeline constraints
+
+## WORKFLOW FINALIZATION:
+
+- Set `lastStep = 11` in document frontmatter
+- Update workflow status file with completion timestamp
+- Provide completion summary to user
+- Do NOT load any additional steps
+
+## FINAL REMINDER:
+
+This workflow is now complete. The PRD serves as the foundation for all subsequent product development activities. All design, architecture, and development work should trace back to the requirements and vision documented in this PRD.
+
+**Congratulations on completing the Product Requirements Document for {{project_name}}!** 🎉

package/src/modules/xmc/workflows/2-plan-workflows/prd/workflow.md

@@ -0,0 +1,61 @@
+---
+name: PRD Workflow
+description: Creates a comprehensive PRDs through collaborative step-by-step discovery between two product managers working as peers.
+main_config: `{project-root}/{xiaoma_folder}/xmc/config.yaml`
+web_bundle: true
+---
+
+# PRD Workflow
+
+**Goal:** Create comprehensive PRDs through collaborative step-by-step discovery between two product managers working as peers.
+
+**Your Role:** You are a product-focused PM facilitator collaborating with an expert peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision. Work together as equals. You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {main_config} and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `steps/step-01-init.md` to begin the workflow.

package/src/modules/xmc/workflows/3-solutioning/architecture/architecture-decision-template.md

@@ -0,0 +1,13 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'architecture'
+lastStep: 0
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+
+# Architecture Decision Document
+
+_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._

package/src/modules/xmc/workflows/3-solutioning/architecture/data/domain-complexity.csv

@@ -0,0 +1,11 @@
+domain,signals,complexity_level,suggested_workflow,web_searches
+e_commerce,"shopping,cart,checkout,payment,products,store",medium,standard,"ecommerce architecture patterns, payment processing, inventory management"
+fintech,"banking,payment,trading,finance,money,investment",high,enhanced,"financial security, PCI compliance, trading algorithms, fraud detection"
+healthcare,"medical,diagnostic,clinical,patient,hospital,health",high,enhanced,"HIPAA compliance, medical data security, FDA regulations, health tech"
+social,"social network,community,users,friends,posts,sharing",high,advanced,"social graph algorithms, feed ranking, notification systems, privacy"
+education,"learning,course,student,teacher,training,academic",medium,standard,"LMS architecture, progress tracking, assessment systems, video streaming"
+productivity,"productivity,workflow,tasks,management,business,tools",medium,standard,"collaboration patterns, real-time editing, notification systems, integration"
+media,"content,media,video,audio,streaming,broadcast",high,advanced,"CDN architecture, video encoding, streaming protocols, content delivery"
+iot,"IoT,sensors,devices,embedded,smart,connected",high,advanced,"device communication, real-time data processing, edge computing, security"
+government,"government,civic,public,admin,policy,regulation",high,enhanced,"accessibility standards, security clearance, data privacy, audit trails"
+gaming,"game,gaming,multiplayer,real-time,interactive,entertainment",high,advanced,"real-time multiplayer, game engine architecture, matchmaking, leaderboards"

package/src/modules/xmc/workflows/3-solutioning/architecture/data/project-types.csv

@@ -0,0 +1,7 @@
+project_type,detection_signals,description,typical_starters
+web_app,"website,web application,browser,frontend,UI,interface",Web-based applications running in browsers,Next.js, Vite, Remix
+mobile_app,"mobile,iOS,Android,app,smartphone,tablet",Native mobile applications,React Native, Expo, Flutter
+api_backend,"API,REST,GraphQL,backend,service,microservice",Backend services and APIs,NestJS, Express, Fastify
+full_stack,"full-stack,complete,web+mobile,frontend+backend",Applications with both frontend and backend,T3 App, RedwoodJS, Blitz
+cli_tool,"CLI,command line,terminal,console,tool",Command-line interface tools,oclif, Commander, Caporal
+desktop_app,"desktop,Electron,Tauri,native app,macOS,Windows",Desktop applications,Electron, Tauri, Flutter Desktop

package/src/modules/xmc/workflows/3-solutioning/architecture/steps/step-01-init.md

@@ -0,0 +1,194 @@
+# Step 1: Architecture Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## YOUR TASK:
+
+Initialize the Architecture workflow by detecting continuation state, discovering input documents, and setting up the document for collaborative architectural decision making.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/architecture.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery:
+
+**PRD Document (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check analysis folder: `{output_folder}/*prd*.md`
+2. If no main files: Check for sharded PRD folder: `{output_folder}/*prd*/**/*.md`
+3. If sharded folder exists: Load EVERY file in that folder completely
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Epics/Stories Document (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check analysis folder: `{output_folder}/analysis/*epic*.md`
+2. If no analysis files: Try main folder: `{output_folder}/*epic*.md`
+3. If no main files: Check for sharded epics folder: `{output_folder}/*epic*/**/*.md`
+4. If sharded folder exists: Load EVERY file in that folder completely
+5. Add discovered files to `inputDocuments` frontmatter
+
+**UX Design Specification (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check folder: `{output_folder}/*ux*.md`
+2. If no main files: Check for sharded UX folder: `{output_folder}/*ux*/**/*.md`
+3. If sharded folder exists: Load EVERY file in that folder completely
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Research Documents (Priority: Analysis → Main):**
+
+1. Check folder: `{output_folder}/research/*research*.md`
+2. If no files: Try folder: `{output_folder}/*research*.md`
+3. Add discovered files to `inputDocuments` frontmatter
+
+**Project Documentation (Existing Projects):**
+
+1. Look for index file: `{output_folder/index.md`
+2. CRITICAL: Load index.md to understand what project files are available
+3. Read available files from index to understand existing project context
+4. This provides essential context for extending existing project with new architecture
+5. Add discovered files to `inputDocuments` frontmatter
+
+**Project Context Rules (Critical for AI Agents):**
+
+1. Check for project context file: `**/project_context.md`
+2. If exists: Load COMPLETE file contents - this contains critical rules for AI agents
+3. Add to frontmatter `hasProjectContext: true` and track file path
+4. Report to user: "Found existing project context with {number_of_rules} agent rules"
+5. This file contains language-specific patterns, testing rules, and implementation guidelines that must be followed
+
+**Loading Rules:**
+
+- Load ALL discovered files completely (no offset/limit)
+- For sharded folders, load ALL files to get complete picture
+- For existing projects, use index.md as guide to what's relevant
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Validate Required Inputs
+
+Before proceeding, verify we have the essential inputs:
+
+**PRD Validation:**
+
+- If no PRD found: "Architecture requires a PRD to work from. Please run the PRD workflow first or provide the PRD file path."
+- Do NOT proceed without PRD
+
+**Other Inputs:**
+
+- UX Spec: "Provides UI/UX architectural requirements" (Optional)
+
+#### C. Create Initial Document
+
+Copy the template from `{installed_path}/architecture-decision-template.md` to `{output_folder}/architecture.md`
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'architecture'
+lastStep: 0
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+```
+
+#### D. Complete Initialization and Report
+
+Complete setup and report to user:
+
+**Document Setup:**
+
+- Created: `{output_folder}/architecture.md` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+Report what was found:
+"Welcome {{user_name}}! I've set up your Architecture workspace for {{project_name}}.
+
+**Documents Found:**
+
+- PRD: {number of PRD files loaded or "None found - REQUIRED"}
+- Epics/Stories: {number of epic files loaded or "None found"}
+- UX Design: {number of UX files loaded or "None found"}
+- Research: {number of research files loaded or "None found"}
+- Project docs: {number of project files loaded or "None found"}
+- Project context: {project_context_rules count of rules for AI agents found}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Ready to begin architectural decision making. Do you have any other documents you'd like me to include?
+
+[C] Continue to project context analysis
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with template and frontmatter
+✅ Input documents discovered and loaded using sharded-first logic
+✅ All discovered files tracked in frontmatter `inputDocuments`
+✅ PRD requirement validated and communicated
+✅ User confirmed document setup and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when existing workflow exists
+❌ Not updating frontmatter with discovered input documents
+❌ Creating document without proper template
+❌ Not checking sharded folders first before whole files
+❌ Not reporting what documents were found to user
+❌ Proceeding without validating PRD requirement
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects [C] to continue, load `./step-02-context.md` to analyze the project context and begin architectural decision making.
+
+Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!

package/src/modules/xmc/workflows/3-solutioning/architecture/steps/step-01b-continue.md

@@ -0,0 +1,163 @@
+# Step 1b: Workflow Continuation Handler
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding current state and getting user confirmation
+- 🚪 HANDLE workflow resumption smoothly and transparently
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📖 Read existing document completely to understand current state
+- 💾 Update frontmatter to reflect continuation
+- 🚫 FORBIDDEN to proceed to next step without user confirmation
+
+## CONTEXT BOUNDARIES:
+
+- Existing document and frontmatter are available
+- Input documents already loaded should be in frontmatter `inputDocuments`
+- Steps already completed are in `stepsCompleted` array
+- Focus on understanding where we left off
+
+## YOUR TASK:
+
+Handle workflow continuation by analyzing existing work and guiding the user to resume at the appropriate step.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current Document State
+
+Read the existing architecture document completely and analyze:
+
+**Frontmatter Analysis:**
+
+- `stepsCompleted`: What steps have been done
+- `inputDocuments`: What documents were loaded
+- `lastStep`: Last step that was executed
+- `project_name`, `user_name`, `date`: Basic context
+
+**Content Analysis:**
+
+- What sections exist in the document
+- What architectural decisions have been made
+- What appears incomplete or in progress
+- Any TODOs or placeholders remaining
+
+### 2. Present Continuation Summary
+
+Show the user their current progress:
+
+"Welcome back {{user_name}}! I found your Architecture work for {{project_name}}.
+
+**Current Progress:**
+
+- Steps completed: {{stepsCompleted list}}
+- Last step worked on: Step {{lastStep}}
+- Input documents loaded: {{number of inputDocuments}} files
+
+**Document Sections Found:**
+{list all H2/H3 sections found in the document}
+
+{if_incomplete_sections}
+**Incomplete Areas:**
+
+- {areas that appear incomplete or have placeholders}
+  {/if_incomplete_sections}
+
+**What would you like to do?**
+[R] Resume from where we left off
+[C] Continue to next logical step
+[O] Overview of all remaining steps
+[X] Start over (will overwrite existing work)
+"
+
+### 3. Handle User Choice
+
+#### If 'R' (Resume from where we left off):
+
+- Identify the next step based on `stepsCompleted`
+- Load the appropriate step file to continue
+- Example: If `stepsCompleted: [1, 2, 3]`, load `step-04-decisions.md`
+
+#### If 'C' (Continue to next logical step):
+
+- Analyze the document content to determine logical next step
+- May need to review content quality and completeness
+- If content seems complete for current step, advance to next
+- If content seems incomplete, suggest staying on current step
+
+#### If 'O' (Overview of all remaining steps):
+
+- Provide brief description of all remaining steps
+- Let user choose which step to work on
+- Don't assume sequential progression is always best
+
+#### If 'X' (Start over):
+
+- Confirm: "This will delete all existing architectural decisions. Are you sure? (y/n)"
+- If confirmed: Delete existing document and return to step-01-init.md
+- If not confirmed: Return to continuation menu
+
+### 4. Navigate to Selected Step
+
+After user makes choice:
+
+**Load the selected step file:**
+
+- Update frontmatter `lastStep` to reflect current navigation
+- Execute the selected step file
+- Let that step handle the detailed continuation logic
+
+**State Preservation:**
+
+- Maintain all existing content in the document
+- Keep `stepsCompleted` accurate
+- Track the resumption in workflow status
+
+### 5. Special Continuation Cases
+
+#### If `stepsCompleted` is empty but document has content:
+
+- This suggests an interrupted workflow
+- Ask user: "I see the document has content but no steps are marked as complete. Should I analyze what's here and set the appropriate step status?"
+
+#### If document appears corrupted or incomplete:
+
+- Ask user: "The document seems incomplete. Would you like me to try to recover what's here, or would you prefer to start fresh?"
+
+#### If document is complete but workflow not marked as done:
+
+- Ask user: "The architecture looks complete! Should I mark this workflow as finished, or is there more you'd like to work on?"
+
+## SUCCESS METRICS:
+
+✅ Existing document state properly analyzed and understood
+✅ User presented with clear continuation options
+✅ User choice handled appropriately and transparently
+✅ Workflow state preserved and updated correctly
+✅ Navigation to appropriate step handled smoothly
+
+## FAILURE MODES:
+
+❌ Not reading the complete existing document before making suggestions
+❌ Losing track of what steps were actually completed
+❌ Automatically proceeding without user confirmation of next steps
+❌ Not checking for incomplete or placeholder content
+❌ Losing existing document content during resumption
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects their continuation option, load the appropriate step file based on their choice. The step file will handle the detailed work from that point forward.
+
+Remember: The goal is smooth, transparent resumption that respects the work already done while giving the user control over how to proceed.