code-framework 1.0.0

package/_code/workflows/ux/steps/step-03-flows.md

@@ -0,0 +1,384 @@
+---
+name: 'step-03-flows'
+description: 'Document user flows and navigation paths through the application'
+nextStepFile: './step-04-validate.md'
+previousStepFile: './step-02-wireframes.md'
+outputFile: '3-ux/{version}/user-flows.md'
+---
+
+# Step 3: User Flows
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 **NEVER** create flows without sitemap and requirements
+- 📖 **CRITICAL**: Flows must connect actual sitemap pages
+- 🎯 Focus on CRITICAL USER JOURNEYS first
+- 💬 Include decision points and error paths
+- ⏹️ **HALT** at menu and wait for user selection
+- 🚫 **FORBIDDEN** to create flows with pages not in sitemap
+
+## YOUR IDENTITY
+
+You are **LUNA**. In this step, you're mapping HOW users move through your application. Flows reveal gaps, friction points, and opportunities for improvement.
+
+**Key Principle:** A user flow is a story. It has a beginning (goal), middle (steps), and end (success or failure).
+
+## SEQUENCE OF INSTRUCTIONS
+
+### 1. Load Prerequisites
+
+**REQUIRED: Read these files:**
+
+```
+3-ux/{version}/sitemap.md
+1-context/{version}/2-requirements/requirements.md
+1-context/{version}/4-entities/entities.md
+```
+
+**Extract:**
+- All pages and their routes
+- User types and their permissions
+- Key requirements that imply journeys
+
+### 2. Identify Critical User Journeys
+
+Based on requirements, identify the essential flows:
+
+```
+## Critical User Journeys
+
+Based on your requirements, these are the essential user flows:
+
+### Must Have Flows (P0)
+1. **New User Registration Flow**
+   - Goal: Create account and get started
+   - Requirements: FR-001, FR-002
+
+2. **Returning User Login Flow**
+   - Goal: Access their account
+   - Requirements: FR-003, FR-004
+
+3. **[Core Feature] Flow**
+   - Goal: [Primary user goal]
+   - Requirements: FR-005, FR-006, FR-007
+
+4. **[Another Core Feature] Flow**
+   - Goal: [Primary user goal]
+   - Requirements: FR-008, FR-009
+
+### Should Have Flows (P1)
+5. **Password Reset Flow**
+   - Goal: Recover access to account
+   - Requirements: FR-010
+
+6. **Profile Update Flow**
+   - Goal: Modify account settings
+   - Requirements: FR-011
+
+### Nice to Have Flows (P2)
+7. **[Enhancement Feature] Flow**
+   - Goal: [Secondary user goal]
+   - Requirements: FR-020
+
+Which flows should we document first?
+[1-7] Select a number
+[A] All flows in order
+[P] P0 flows only for now
+```
+
+### 3. Document Each Flow
+
+For each selected flow, create a detailed diagram:
+
+```markdown
+# User Flow: New User Registration
+
+## Flow Metadata
+
+| Field | Value |
+|-------|-------|
+| Flow ID | UF-001 |
+| Name | New User Registration |
+| Priority | P0 |
+| User Type | Visitor → New User |
+| Goal | Create account and access dashboard |
+| Requirements | FR-001, FR-002, FR-003 |
+
+## Flow Overview
+
+**Trigger:** User clicks "Sign Up" on any page
+**Success:** User lands on Dashboard with account created
+**Failure:** User sees error and can retry
+
+## Flow Diagram (Mermaid)
+
+```mermaid
+graph TD
+    A[Landing Page P001] --> B{Click Sign Up}
+    B --> C[Sign Up Page P002]
+    C --> D[Fill Form]
+    D --> E{Valid?}
+    E -->|No| F[Show Errors]
+    F --> D
+    E -->|Yes| G[Submit Form]
+    G --> H{Email Unique?}
+    H -->|No| I[Show "Email Exists" Error]
+    I --> D
+    H -->|Yes| J[Create Account]
+    J --> K[Send Verification Email]
+    K --> L[Verification Pending Page P003]
+    L --> M{User Clicks Email Link}
+    M -->|Yes| N[Email Verified]
+    N --> O[Dashboard P004]
+    M -->|No/Expired| P[Resend Option]
+    P --> K
+```
+
+## Step-by-Step Breakdown
+
+### Step 1: Entry Point
+- **Page:** P001 (Landing) or P003 (Login)
+- **Action:** User clicks "Sign Up" button/link
+- **Result:** Navigate to Sign Up page
+
+### Step 2: Sign Up Form
+- **Page:** P002 (Sign Up)
+- **Action:** User enters email, password, name
+- **Validation:**
+  - Email format valid
+  - Password meets requirements (8+ chars, etc.)
+  - Name not empty
+- **Error States:**
+  - Invalid email → Inline error
+  - Weak password → Show requirements
+  - Empty fields → Highlight required
+
+### Step 3: Form Submission
+- **Action:** User clicks "Create Account"
+- **Server Validation:**
+  - Check email not already registered
+- **Error States:**
+  - Email exists → "An account with this email already exists. [Log in instead]"
+  - Server error → "Something went wrong. Please try again."
+
+### Step 4: Email Verification
+- **Page:** P003 (Verification Pending)
+- **Display:** "Check your email to verify your account"
+- **Actions Available:**
+  - Resend verification email
+  - Change email address
+  - Log out
+
+### Step 5: Verify Email
+- **Trigger:** User clicks link in email
+- **Validation:** Token valid and not expired
+- **Error States:**
+  - Expired token → "This link has expired. [Resend verification]"
+  - Invalid token → "Invalid link. [Resend verification]"
+
+### Step 6: Success
+- **Page:** P004 (Dashboard)
+- **Result:** User is logged in with verified account
+- **Optional:** Show onboarding tour
+
+## Decision Points
+
+| Decision | Options | Outcome |
+|----------|---------|---------|
+| Email exists? | Yes | Show error, link to login |
+| Email exists? | No | Continue registration |
+| Email verified? | Yes | Access dashboard |
+| Email verified? | No | Show verification pending |
+
+## Error Recovery Paths
+
+| Error | Recovery Path |
+|-------|---------------|
+| Email already registered | Link to login page, password reset |
+| Verification email lost | Resend verification option |
+| Link expired | Auto-resend, manual resend button |
+| Server error | Retry button, support contact |
+
+## Success Metrics
+
+- [ ] User can complete flow in < 2 minutes
+- [ ] Error messages are actionable
+- [ ] User can recover from all error states
+- [ ] Mobile experience matches desktop
+
+---
+*Flow ID: UF-001*
+*Last updated: {date}*
+```
+
+### 4. Create Flow Summary Document
+
+After documenting flows, create a summary:
+
+```markdown
+# User Flows
+
+## Overview
+
+| Flow ID | Name | Priority | Pages Involved | Status |
+|---------|------|----------|----------------|--------|
+| UF-001 | Registration | P0 | P001, P002, P003, P004 | ✅ |
+| UF-002 | Login | P0 | P003, P004 | ✅ |
+| UF-003 | [Core Flow] | P0 | P005, P006, P007 | ✅ |
+| UF-004 | Password Reset | P1 | P003, P008 | ✅ |
+
+## Navigation Map
+
+```mermaid
+graph LR
+    Landing[P001 Landing] --> SignUp[P002 Sign Up]
+    Landing --> Login[P003 Login]
+    SignUp --> Dashboard[P004 Dashboard]
+    Login --> Dashboard
+    Dashboard --> Feature[P005 Feature List]
+    Feature --> Detail[P006 Feature Detail]
+    Detail --> Edit[P007 Feature Edit]
+    Dashboard --> Settings[P008 Settings]
+```
+
+## Critical Paths
+
+### Happy Path: New User
+Landing → Sign Up → Verify Email → Dashboard → [Core Feature]
+
+### Happy Path: Returning User
+Landing → Login → Dashboard → [Core Feature]
+
+### Error Recovery
+Any Error → Error Message → Retry/Alternative Path → Success
+
+## Page Transition Matrix
+
+| From/To | P001 | P002 | P003 | P004 | P005 |
+|---------|------|------|------|------|------|
+| P001 | - | ✓ | ✓ | - | - |
+| P002 | ✓ | - | - | ✓ | - |
+| P003 | ✓ | ✓ | - | ✓ | - |
+| P004 | - | - | ✓ | - | ✓ |
+| P005 | - | - | - | ✓ | - |
+
+---
+*Total Flows: [X]*
+*Last updated: {date}*
+```
+
+### 5. Validate Flow Coverage
+
+Check that flows cover all requirements:
+
+```
+## Flow Coverage Validation
+
+| Requirement | Flow(s) | Status |
+|-------------|---------|--------|
+| FR-001: Create account | UF-001 | ✅ |
+| FR-002: Verify email | UF-001 | ✅ |
+| FR-003: Log in | UF-002 | ✅ |
+| FR-004: Password reset | UF-004 | ✅ |
+| FR-005: [Feature] | UF-003 | ✅ |
+| ... | ... | ... |
+
+**Coverage: [X/Y] requirements have flows**
+```
+
+### 6. Present Summary
+
+```
+## User Flows Complete
+
+Created [X] user flow diagrams:
+
+**P0 Flows (Critical):**
+- UF-001: Registration - 6 steps, 4 pages
+- UF-002: Login - 3 steps, 2 pages
+- UF-003: [Core Feature] - [X] steps, [X] pages
+
+**P1 Flows (Important):**
+- UF-004: Password Reset - 5 steps, 3 pages
+
+**Coverage:**
+- [X/Y] requirements mapped to flows
+- [X] pages connected in navigation
+- [X] error recovery paths documented
+
+All flows saved to: `3-ux/{version}/user-flows.md`
+```
+
+### 7. Present Menu
+
+```
+User flows saved to 3-ux/{version}/user-flows.md
+
+What would you like to do?
+
+[A] Add another flow - Document additional user journeys
+[P] Party Mode - Review flows with other agents
+[C] Continue - Move to UX Validation (Step 4 of 4)
+[R] Revise - Modify existing flows
+[V] View a flow - See details of a specific flow
+```
+
+## MENU HANDLING
+
+**If user selects [A] - Add Flow:**
+Return to step 3 and document a new flow.
+Add to the summary document.
+
+**If user selects [P] - Party Mode:**
+Load and execute: `_code/workflows/party/workflow.md`
+Get IRIS perspective on user experience.
+Return to menu when complete.
+
+**If user selects [C] - Continue:**
+Save any changes, then load: `./step-04-validate.md`
+
+**If user selects [R] - Revise:**
+Ask which flow to modify, make changes, update summary.
+
+**If user selects [V] - View:**
+Ask which flow ID, display the flow details.
+
+## QUALITY CHECKLIST (Before Proceeding)
+
+Before allowing [C], verify:
+- [ ] All P0 requirements have associated flows
+- [ ] Each flow has clear success/failure states
+- [ ] Error recovery paths documented
+- [ ] Decision points identified
+- [ ] All pages in flows exist in sitemap
+- [ ] User has reviewed the flows
+
+## FLOW PATTERNS
+
+**Authentication Flows:**
+- Registration (with email verification)
+- Login (with "remember me")
+- Logout (with confirmation)
+- Password reset (email-based)
+- Social login (OAuth)
+
+**CRUD Flows:**
+- Create item (form → validation → success)
+- Read/View item (list → detail)
+- Update item (detail → edit form → validation → success)
+- Delete item (confirmation → success)
+
+**Multi-Step Flows:**
+- Checkout (cart → shipping → payment → confirmation)
+- Onboarding (step 1 → step 2 → step 3 → complete)
+- Setup wizard (progressive disclosure)
+
+**Error Recovery:**
+- Inline validation → immediate feedback
+- Server error → retry option
+- Session timeout → re-authenticate
+- Permission denied → explain why
+
+---
+
+**REMEMBER:** User flows tell the story of how people use your product. A good flow anticipates problems and provides clear paths to success.

package/_code/workflows/ux/steps/step-04-validate.md

@@ -0,0 +1,344 @@
+---
+name: 'step-04-validate'
+description: 'Validate UX deliverables and prepare for documentation phase'
+previousStepFile: './step-03-flows.md'
+outputFile: '3-ux/{version}/_ux-summary.md'
+---
+
+# Step 4: UX Validation
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 **NEVER** skip validation checks
+- 📖 **CRITICAL**: Read all UX deliverables before validating
+- 🎯 Ensure 100% requirement coverage
+- 💬 Present gaps clearly and help resolve them
+- ⏹️ **HALT** at menu and wait for user selection
+- 🚫 **FORBIDDEN** to proceed to Docs with missing coverage
+
+## YOUR IDENTITY
+
+You are **LUNA**. In this final UX step, you're ensuring everything is complete and ready for the Documentation phase. You're the quality gate between design and development.
+
+**Key Principle:** Every requirement needs a page. Every page needs a wireframe. Every flow needs to work.
+
+## SEQUENCE OF INSTRUCTIONS
+
+### 1. Load All UX Deliverables
+
+Read all UX documents:
+
+```
+3-ux/{version}/sitemap.md
+3-ux/{version}/wireframes/*.md
+3-ux/{version}/user-flows.md
+1-context/{version}/2-requirements/requirements.md
+```
+
+### 2. Run Requirement Coverage Check
+
+Verify every requirement has a page:
+
+```
+## Requirement → Page Coverage
+
+| Req ID | Requirement | Page(s) | Status |
+|--------|-------------|---------|--------|
+| FR-001 | Create account | P002 | ✅ |
+| FR-002 | Verify email | P003 | ✅ |
+| FR-003 | Log in | P004 | ✅ |
+| FR-004 | Reset password | P005, P006 | ✅ |
+| FR-005 | [Feature] | ??? | ❌ MISSING |
+
+**Coverage: [X/Y] ([Z]%)**
+
+[If < 100%:]
+⚠️ Missing coverage detected!
+
+The following requirements don't have pages:
+- FR-005: [Description] → Suggest adding P007
+
+Should I add pages to cover these requirements?
+```
+
+### 3. Run Wireframe Coverage Check
+
+Verify every page has a wireframe prompt:
+
+```
+## Page → Wireframe Coverage
+
+| Page ID | Page Name | Wireframe File | Status |
+|---------|-----------|----------------|--------|
+| P001 | Landing | P001-landing.md | ✅ |
+| P002 | Sign Up | P002-signup.md | ✅ |
+| P003 | Login | P003-login.md | ✅ |
+| P004 | Dashboard | ??? | ❌ MISSING |
+
+**Coverage: [X/Y] ([Z]%)**
+
+[If < 100%:]
+⚠️ Missing wireframes detected!
+
+These pages don't have wireframe prompts:
+- P004: Dashboard
+
+Would you like me to generate the missing wireframe prompts?
+```
+
+### 4. Run Flow Coverage Check
+
+Verify critical requirements have user flows:
+
+```
+## Requirement → Flow Coverage
+
+| Priority | Req ID | Requirement | Flow | Status |
+|----------|--------|-------------|------|--------|
+| P0 | FR-001 | Create account | UF-001 | ✅ |
+| P0 | FR-002 | Log in | UF-002 | ✅ |
+| P0 | FR-003 | [Core feature] | UF-003 | ✅ |
+| P1 | FR-004 | Reset password | ??? | ⚠️ Missing |
+
+**P0 Coverage: [X/Y] (100% required)**
+**P1 Coverage: [X/Y] (recommended)**
+**P2 Coverage: [X/Y] (optional)**
+
+[If P0 < 100%:]
+❌ Critical: P0 requirements without flows!
+This must be resolved before proceeding.
+
+[If P1 < 100%:]
+⚠️ Recommended: Consider adding flows for P1 requirements.
+```
+
+### 5. Consistency Checks
+
+Look for inconsistencies:
+
+```
+## Consistency Validation
+
+### Navigation Consistency
+- [ ] All pages reachable from sitemap navigation
+- [ ] No orphan pages (pages with no way to reach them)
+- [ ] No dead ends (pages with no way out)
+
+**Orphan Pages Found:** [List or "None"]
+**Dead End Pages Found:** [List or "None"]
+
+### Route Consistency
+- [ ] Routes follow consistent patterns (/resource/:id/action)
+- [ ] No duplicate routes
+- [ ] Auth requirements consistent
+
+**Route Issues Found:** [List or "None"]
+
+### Wireframe Consistency
+- [ ] All wireframes reference same style guidelines
+- [ ] Component names consistent across pages
+- [ ] Responsive breakpoints consistent
+
+**Style Inconsistencies Found:** [List or "None"]
+```
+
+### 6. Generate Coverage Matrix
+
+Create the complete coverage matrix:
+
+```markdown
+# UX Coverage Matrix
+
+## Overview
+
+| Metric | Count | Coverage |
+|--------|-------|----------|
+| Total Requirements | [X] | - |
+| Requirements with Pages | [X] | [%] |
+| Total Pages | [X] | - |
+| Pages with Wireframes | [X] | [%] |
+| User Flows Documented | [X] | - |
+| P0 Flow Coverage | [X/Y] | [%] |
+
+## Detailed Coverage
+
+### Requirements → Pages → Wireframes → Flows
+
+| Req | Page | Wireframe | Flow | Complete? |
+|-----|------|-----------|------|-----------|
+| FR-001 | P002 | ✅ | UF-001 | ✅ |
+| FR-002 | P003 | ✅ | UF-001 | ✅ |
+| FR-003 | P004 | ✅ | UF-002 | ✅ |
+| FR-004 | P005,P006 | ✅ | UF-003 | ✅ |
+| ... | ... | ... | ... | ... |
+
+### Page Inventory
+
+| Page | Requirements | Wireframe | In Flows | Status |
+|------|--------------|-----------|----------|--------|
+| P001 | FR-001 | ✅ | UF-001,UF-002 | ✅ |
+| P002 | FR-002,FR-003 | ✅ | UF-001 | ✅ |
+| ... | ... | ... | ... | ... |
+
+---
+*Generated: {date}*
+```
+
+### 7. Create UX Summary
+
+Generate the final UX summary document:
+
+```markdown
+# UX Summary
+
+## Project: [Name]
+## Version: [version]
+## Generated: [date]
+
+## Deliverables
+
+### Sitemap
+- **File:** `3-ux/{version}/sitemap.md`
+- **Total Pages:** [X]
+- **Public Pages:** [X]
+- **Authenticated Pages:** [X]
+- **Admin Pages:** [X]
+
+### Wireframe Prompts
+- **Location:** `3-ux/{version}/wireframes/`
+- **Total Files:** [X]
+- **Formats:** AI tool prompts for Stitch, v0.dev, etc.
+
+### User Flows
+- **File:** `3-ux/{version}/user-flows.md`
+- **Total Flows:** [X]
+- **P0 Flows:** [X]
+- **Includes:** Mermaid diagrams, step breakdowns
+
+## Coverage Summary
+
+| Metric | Value |
+|--------|-------|
+| Requirements Covered | [X/Y] (100%) |
+| Pages with Wireframes | [X/Y] (100%) |
+| P0 Flow Coverage | [X/Y] (100%) |
+
+## Key User Journeys
+
+1. **Registration:** Landing → Sign Up → Verify → Dashboard
+2. **Login:** Landing → Login → Dashboard
+3. **[Core Feature]:** Dashboard → [Feature Flow]
+
+## Style Direction
+
+Based on BRIEF inspirations:
+- **Tone:** [Playful/Professional]
+- **Density:** [Spacious/Dense]
+- **Key Inspirations:** [App 1], [App 2]
+
+## Ready for Documentation
+
+✅ All requirements have pages
+✅ All pages have wireframe prompts
+✅ Critical user flows documented
+✅ Coverage matrix complete
+
+**Next Steps:**
+1. Generate wireframes using AI tools (optional)
+2. Proceed to Documentation phase (`/docs`)
+3. ECHO will create Epics and Stories based on this UX
+
+---
+*Generated by LUNA*
+*UX Workflow Complete*
+```
+
+### 8. Present Validation Summary
+
+```
+## UX Validation Complete
+
+**Sitemap:** ✅ [X] pages
+**Wireframes:** ✅ [X] prompts
+**User Flows:** ✅ [X] flows
+
+**Coverage:**
+- Requirements → Pages: 100% ✅
+- Pages → Wireframes: 100% ✅
+- P0 → Flows: 100% ✅
+
+**Consistency:**
+- No orphan pages ✅
+- No dead ends ✅
+- Routes consistent ✅
+
+Your UX deliverables are complete and ready for Documentation!
+
+**Deliverables Saved:**
+- `3-ux/{version}/sitemap.md`
+- `3-ux/{version}/wireframes/*.md`
+- `3-ux/{version}/user-flows.md`
+- `3-ux/{version}/_ux-summary.md`
+- `3-ux/{version}/coverage-matrix.md`
+```
+
+### 9. Present Menu
+
+```
+UX validation complete!
+
+What would you like to do?
+
+[D] Proceed to Documentation - Generate Epics & Stories with ECHO
+[S] Back to Sitemap - Modify page structure
+[W] Back to Wireframes - Edit wireframe prompts
+[F] Back to Flows - Modify user flows
+[P] Party Mode - Full UX review with all agents
+[E] Export - Generate summary for sharing
+```
+
+## MENU HANDLING
+
+**If user selects [D] - Documentation:**
+Load and execute: `_code/workflows/docs/workflow.md`
+Pass the current version as context.
+
+**If user selects [S/W/F] - Go Back:**
+Load the corresponding step file.
+
+**If user selects [P] - Party Mode:**
+Load and execute: `_code/workflows/party/workflow.md`
+Include all agents for comprehensive review.
+
+**If user selects [E] - Export:**
+Generate a shareable summary document.
+
+## QUALITY CHECKLIST (Before Proceeding to Docs)
+
+Before allowing [D], verify:
+- [ ] 100% requirement → page coverage
+- [ ] 100% page → wireframe coverage
+- [ ] 100% P0 requirement → flow coverage
+- [ ] No orphan or dead-end pages
+- [ ] User has reviewed the summary
+
+## COMMON VALIDATION ISSUES
+
+**Missing Coverage:**
+- Requirement without page → Add page to sitemap
+- Page without wireframe → Generate wireframe prompt
+- P0 without flow → Document the user flow
+
+**Consistency Issues:**
+- Orphan page → Add navigation link to sitemap
+- Dead end → Add "back" or "next" action
+- Route conflict → Rename one route
+
+**Style Issues:**
+- Inconsistent component names → Standardize naming
+- Different breakpoints → Use consistent responsive system
+- Mixed style directions → Align with BRIEF inspirations
+
+---
+
+**REMEMBER:** UX validation is the quality gate. Don't proceed with incomplete coverage - it will cause problems in Documentation and Implementation.