@polymorphism-tech/morph-spec 4.3.2 → 4.3.4

package/framework/workflows/README.md

@@ -0,0 +1,1041 @@
+# MORPH-SPEC Workflow Detection System
+
+> Automatic workflow selection based on request analysis and complexity estimation
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Workflow Types](#workflow-types)
+3. [Detection Algorithm](#detection-algorithm)
+4. [Usage Guide](#usage-guide)
+5. [Configuration System](#configuration-system)
+6. [Customization](#customization)
+7. [Examples](#examples)
+8. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+The MORPH-SPEC framework includes an **intelligent workflow detection system** that automatically selects the appropriate development workflow based on analyzing the user's feature request.
+
+### Why Workflows?
+
+Different types of changes require different levels of planning and documentation:
+
+- **Bug fix:** Doesn't need full architectural design
+- **New feature:** Needs spec, contracts, tasks breakdown
+- **Complete system:** Needs all phases (proposal, design, UI/UX, tasks, etc.)
+- **HTML → Code conversion:** Needs prototype analysis, not technical spec
+- **Visual redesign:** Needs design system, not business logic contracts
+
+### Benefits
+
+| Benefit | Impact |
+|---------|--------|
+| **Automatic Selection** | System chooses workflow - user doesn't need framework knowledge |
+| **Optimized Workflows** | Fast-track skips 80% of phases for trivial changes |
+| **Token Efficiency** | Standard workflow uses 60% fewer outputs than full-morph |
+| **Clear Expectations** | Each workflow defines pause points and deliverables |
+| **Guided Experience** | Framework tells user what phases to expect |
+| **Extensible** | Easy to add new workflows (just add JSON config) |
+
+---
+
+## Workflow Types
+
+### 1. fast-track (Trivial Changes)
+
+**Purpose:** Quick fixes, CSS tweaks, small bugs, edge cases
+
+**Criteria:**
+- ≤3 files modified
+- ≤50 lines of code
+- No new components
+- No infrastructure changes
+- No architectural decisions
+
+**Keywords:**
+- `bug`, `fix`, `corrigir`, `ajustar`
+- `hotfix`, `edge case`
+- `cor`, `css`, `typo`
+
+**Phases:**
+1. **Quick Analysis** (combines: proposal + setup + design)
+   - 1 paragraph analysis
+   - No formal spec.md
+2. **Implement**
+   - Direct code changes
+   - Commit message only
+
+**Phases Skipped:**
+- PROPOSAL, SETUP, UIUX, DESIGN, CLARIFY, TASKS, SYNC
+
+**Outputs:**
+- Commit message (no .md files)
+
+**Example Requests:**
+- "fix typo in login button"
+- "change color of primary button to blue"
+- "adjust padding in header component"
+
+---
+
+### 2. standard (Medium Complexity)
+
+**Purpose:** Single features, refactorings, optimizations, simple integrations
+
+**Criteria:**
+- 3-10 files modified
+- 50-500 lines of code
+- 1-2 simple components
+- No infrastructure
+- Tactical decisions only
+
+**Keywords:**
+- `paginação`, `pagination`
+- `filtro`, `filter`, `filtering`
+- `refactor`, `refatorar`
+- `performance`, `otimizar`
+- `export`, `sorting`, `search`
+
+**Phases:**
+1. **PROPOSAL** (simplified)
+   - 1-2 paragraphs
+   - Quick cost estimate
+2. **DESIGN** (concise)
+   - spec.md only (1-2 pages)
+   - No contracts.cs (unless API changes)
+   - decisions.md (if any)
+3. **TASKS** (if >5 tasks)
+   - Task breakdown with dependencies
+4. **IMPLEMENT**
+   - Task-by-task implementation
+
+**Phases Skipped:**
+- SETUP (context already loaded)
+- UIUX (no significant frontend changes)
+- CLARIFY (spec is clear for this type)
+- SYNC (tactical decisions, not strategic)
+
+**Outputs:**
+- proposal.md (minimal)
+- spec.md (concise)
+- tasks.json (if >5 tasks)
+- recap.md
+
+**Example Requests:**
+- "add pagination to users table"
+- "add filtering by date to reports"
+- "export data to CSV"
+- "optimize slow query in dashboard"
+
+---
+
+### 3. full-morph (High Complexity)
+
+**Purpose:** Complete systems, major features, architecture changes, integrations
+
+**Criteria:**
+- >10 files modified
+- >500 lines of code
+- Multiple new components
+- Infrastructure changes (optional)
+- Architectural decisions required
+
+**Keywords:**
+- `sistema`, `system`
+- `autenticação`, `authentication`
+- `integração`, `integration`, `integrate`
+- `pattern`, `cqrs`, `subsistema`, `subsystem`
+- `architecture`, `infraestrutura`, `infrastructure`
+- `complete`, `completo`, `complex`, `complexo`
+
+**Phases:**
+1. **CONTEXT** - Load project context
+2. **PROPOSAL** - ⏸️ Pause for approval
+3. **SETUP** - Activate agents, create feature folder
+4. **UIUX** - ⏸️ Pause for approval (if UI changes)
+5. **DESIGN** - ⏸️ Pause for approval
+6. **CLARIFY** - Resolve ambiguities
+7. **TASKS** - ⏸️ Pause for approval
+8. **IMPLEMENT** - Task-by-task
+9. **SYNC** - ⏸️ Pause for approval (promote decisions to standards)
+
+**Phases Skipped:**
+- None (all phases mandatory)
+
+**Outputs:**
+- proposal.md
+- ui-design-system.md
+- ui-mockups.md
+- ui-components.md
+- ui-flows.md
+- spec.md
+- contracts.cs
+- tasks.json
+- decisions.md
+- recap.md
+
+**Example Requests:**
+- "implement complete authentication system with OAuth"
+- "build user management CRUD with roles and permissions"
+- "integrate Azure Cognitive Search with RAG"
+- "deploy to Azure with Bicep infrastructure"
+
+---
+
+### 4. design-impl (Prototype → Code)
+
+**Purpose:** Convert HTML prototypes, Figma designs, mockups, or screenshots to functional code
+
+**Criteria:**
+- Has existing prototype/mockup/design
+- Prototype formats: HTML, Figma, screenshots, wireframes
+- No business logic design needed (already in prototype)
+
+**Keywords:**
+- `prototipo`, `prototype`
+- `figma`, `html para`, `html to`
+- `convert html`, `converter design`, `convert design`
+- `replicar`, `replicate`
+- `from design`, `from mockup`
+- `mockup`, `screenshot`, `wireframe`
+
+**Phases:**
+1. **PROTOTYPE ANALYSIS** - ⏸️ Pause for confirmation
+   - Analyze HTML/Figma structure
+   - Map components
+   - Identify reusable patterns
+2. **TASKS** - ⏸️ Pause for approval
+   - List screens to implement
+   - Order by dependencies
+3. **IMPLEMENT**
+   - Screen by screen implementation
+
+**Phases Skipped:**
+- PROPOSAL (prototype is the proposal)
+- SETUP, UIUX, DESIGN (already done in prototype)
+- CLARIFY (visual design is clear)
+- SYNC (no strategic decisions)
+
+**Outputs:**
+- recap.md
+- design-system.css (optional - extracted patterns)
+- .razor code (or .tsx for Next.js)
+
+**Example Requests:**
+- "convert HTML prototype to Blazor components"
+- "implement screens from Figma design"
+- "replicate this dashboard mockup in Next.js"
+
+---
+
+### 5. ui-refresh (Visual Redesign)
+
+**Purpose:** Visual-only changes to existing functional pages (no business logic modifications)
+
+**Criteria:**
+- Existing functional pages
+- Only visual changes (colors, spacing, layout, animations)
+- No business logic changes
+- No new features
+- No infrastructure
+
+**Keywords:**
+- `redesign`, `redesenhar`
+- `bonito`, `estetica`, `aesthetic`
+- `modernizar`, `modernize`
+- `restyling`
+- `refresh visual`, `refresh ui`
+- `make prettier`, `look better`
+
+**Phases:**
+1. **VISUAL ANALYSIS** - ⏸️ Pause for aesthetic direction
+   - Analyze current design
+   - Identify improvement opportunities
+   - Propose aesthetic direction
+2. **DESIGN SYSTEM** (simplified) - ⏸️ Pause for approval
+   - CSS components checklist
+   - Color palette
+   - Spacing/typography updates
+3. **IMPLEMENT**
+   - Page by page visual updates
+
+**Phases Skipped:**
+- SETUP (full context not needed)
+- PROPOSAL (visual analysis replaces it)
+- DESIGN (no technical spec needed)
+- CONTRACTS (no API changes)
+- TASKS (page list is simple)
+- CLARIFY, SYNC
+
+**Outputs:**
+- design-refresh-checklist.md
+- design-system.css
+- .razor pages (visual changes only)
+- recap.md
+
+**Example Requests:**
+- "redesign dashboard to look more modern"
+- "make the checkout page more aesthetic"
+- "modernize the landing page design"
+
+---
+
+## Detection Algorithm
+
+### Scoring System
+
+The detector uses a **weighted scoring algorithm** with 4 factors:
+
+| Factor | Weight | What It Analyzes |
+|--------|--------|------------------|
+| **Keywords** | 40% | Matched keywords from workflow configs |
+| **Complexity** | 30% | Estimated files/lines/components needed |
+| **Priority** | 20% | Workflow priority level (specific > generic) |
+| **Context** | 10% | Special conditions (has prototype? existing pages?) |
+
+### Complexity Estimation
+
+The system analyzes the request text to estimate:
+
+**1. Scope Indicators:**
+
+```javascript
+{
+  trivial: ['button', 'cor', 'color', 'css', 'fix', 'typo', 'edge case', 'one'],
+  small: ['add', 'create', 'single', 'simple', 'quick'],
+  medium: ['feature', 'pagination', 'filter', 'export', 'refactor', 'optimize'],
+  large: ['system', 'complete', 'all', 'multiple', 'integration', 'architecture'],
+  huge: ['platform', 'infrastructure', 'subsystem', 'migrate', 'rebuild']
+}
+```
+
+**2. Component Indicators:**
+
+Keywords like: `component`, `page`, `screen`, `form`, `table`, `chart`, `modal`
+
+**3. Entity Indicators:**
+
+Keywords like: `user`, `order`, `product`, `customer`, `invoice`, `report`
+
+**4. Infrastructure Indicators:**
+
+Keywords like: `bicep`, `azure`, `deploy`, `docker`, `kubernetes`, `infrastructure`, `terraform`
+
+**Estimation Output:**
+
+```javascript
+{
+  files: 5,           // Estimated number of files to modify
+  lines: 200,         // Estimated lines of code
+  components: 1,      // Estimated new components
+  hasInfra: false     // Infrastructure changes detected?
+}
+```
+
+### Penalties & Boosts
+
+**Penalties:**
+- **-50%** for workflows with no keyword matches (except full-morph fallback)
+
+**Boosts:**
+- **+20%** for workflows with 3+ keyword matches
+
+### Priority Levels
+
+| Priority | Workflows | Strategy |
+|----------|-----------|----------|
+| **1** (Highest) | fast-track, design-impl | Very specific criteria - match early |
+| **2** (Medium) | standard, ui-refresh | Medium specificity |
+| **3** (Fallback) | full-morph | Catches everything else |
+
+### Selection Logic
+
+1. **Load all workflow configs** from `framework/workflows/configs/*.json`
+2. **Estimate complexity** from user request
+3. **Score each workflow** using weighted algorithm
+4. **Apply penalties/boosts** based on keyword matches
+5. **Sort by score** (highest first)
+6. **Return top result** with confidence level
+7. **Include alternatives** (next 2 workflows with score >0.2)
+
+---
+
+## Usage Guide
+
+### Automatic Detection (Recommended)
+
+```bash
+# When creating a feature
+npx morph-spec feature create user-pagination \
+  --request "add pagination to users table"
+
+# System automatically:
+# 1. Analyzes request
+# 2. Detects workflow (standard in this case)
+# 3. Sets workflow in state.json
+# 4. Shows expected phases and outputs
+```
+
+### Manual Detection
+
+```bash
+# Analyze request without creating feature
+npx morph-spec detect-workflow "implement complete authentication system"
+
+# Output:
+Detected Workflow: full-morph (92% confidence)
+
+Criteria Match:
+  ✓ Keywords: "authentication", "complete", "system"
+  ✓ Estimated: 15 files, ~800 lines
+  ✓ Infrastructure: detected
+
+Phases to Run:
+  1. CONTEXT
+  2. PROPOSAL - ⏸️ Pause for approval
+  ...
+
+Alternative Workflows:
+  - standard (15%): If scope reduced to basic login only
+```
+
+### JSON Output (for automation)
+
+```bash
+npx morph-spec detect-workflow "add pagination" --json
+
+# Output:
+{
+  "workflowId": "standard",
+  "confidence": 0.85,
+  "matchedKeywords": ["paginação"],
+  "estimatedComplexity": {
+    "files": 5,
+    "lines": 200,
+    "components": 1,
+    "hasInfra": false
+  },
+  "reasoning": "Matched keyword 'paginação' + estimated 5 files (3-10 range)",
+  "alternativeWorkflows": [
+    {
+      "workflowId": "fast-track",
+      "confidence": 0.3,
+      "reason": "Could be simple if only UI change"
+    }
+  ]
+}
+```
+
+### Manual Override
+
+```bash
+# Force specific workflow
+npx morph-spec state set user-auth workflow full-morph
+
+# Re-detect after request changes
+npx morph-spec state detect-workflow user-auth \
+  "implement basic login only (no OAuth)"
+```
+
+### View Current Workflow
+
+```bash
+npx morph-spec state get user-auth workflow
+
+# Output:
+Workflow: standard
+Detection: Auto (85% confidence)
+Phases: PROPOSAL, DESIGN, TASKS, IMPLEMENT (4 phases)
+Current Phase: design (2/4)
+```
+
+---
+
+## Configuration System
+
+### File Structure
+
+```
+framework/workflows/
+├── docs/                                   # Documentation
+│   ├── STORY-DRIVEN-DEVELOPMENT.md        # Philosophy
+│   ├── fast-track.md                      # Fast-track workflow details
+│   ├── standard.md                        # Standard workflow details
+│   ├── full-morph.md                      # Full-morph workflow details
+│   ├── design-impl.md                     # Design-impl workflow details
+│   └── ui-refresh.md                      # UI-refresh workflow details
+│
+└── configs/                               # Executable configs
+    ├── fast-track.json                    # Fast-track configuration
+    ├── standard.json                      # Standard configuration
+    ├── full-morph.json                    # Full-morph configuration
+    ├── design-impl.json                   # Design-impl configuration
+    └── ui-refresh.json                    # UI-refresh configuration
+```
+
+### Configuration Schema
+
+```json
+{
+  "id": "workflow-id",
+  "name": "Workflow Display Name",
+  "description": "Brief description",
+
+  "criteria": {
+    "maxFiles": 10,
+    "minFiles": 3,
+    "maxLines": 500,
+    "minLines": 50,
+    "maxComponents": 2,
+    "minComponents": 0,
+    "noInfrastructure": true,
+    "infrastructure": false,
+    "hasPrototype": false,
+    "hasExistingPages": false,
+    "onlyVisualChanges": false,
+    "noBusinessLogic": false,
+    "architecturalDecisions": false
+  },
+
+  "keywords": [
+    "keyword1",
+    "keyword2",
+    "portuguese-keyword",
+    "english-keyword"
+  ],
+
+  "phases": {
+    "run": ["phase1", "phase2"],
+    "skip": ["phase3", "phase4"],
+    "combined": {
+      "quick-analysis": ["proposal", "setup", "design"]
+    }
+  },
+
+  "pausePoints": [
+    {
+      "phase": "design",
+      "question": "Approve design to proceed?",
+      "condition": "hasUIAgents"
+    }
+  ],
+
+  "outputs": {
+    "required": ["spec.md", "recap.md"],
+    "optional": ["design-system.css"],
+    "skip": ["contracts.cs", "tasks.json"]
+  },
+
+  "priority": 2
+}
+```
+
+### Field Descriptions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique workflow identifier (kebab-case) |
+| `name` | string | Display name for UI/logs |
+| `description` | string | Brief explanation of workflow purpose |
+| `criteria` | object | Conditions for workflow match |
+| `keywords` | array | Keywords to match in user request |
+| `phases.run` | array | Phases to execute |
+| `phases.skip` | array | Phases to skip |
+| `phases.combined` | object | Phases to combine (e.g., "quick-analysis") |
+| `pausePoints` | array | Where to pause for user approval |
+| `outputs.required` | array | Required output files |
+| `outputs.optional` | array | Optional output files |
+| `outputs.skip` | array | Output files to skip |
+| `priority` | number | 1 (highest) to 3 (fallback) |
+
+---
+
+## Customization
+
+### Adding a New Workflow
+
+**1. Create Config File:**
+
+Create `framework/workflows/configs/my-workflow.json`:
+
+```json
+{
+  "id": "my-workflow",
+  "name": "My Custom Workflow",
+  "description": "Custom workflow for specific use case",
+  "criteria": {
+    "minFiles": 5,
+    "maxFiles": 15
+  },
+  "keywords": ["custom-keyword", "my-use-case"],
+  "phases": {
+    "run": ["proposal", "design", "implement"],
+    "skip": ["setup", "clarify", "tasks"]
+  },
+  "pausePoints": [
+    { "phase": "design", "question": "Approve custom design?" }
+  ],
+  "outputs": {
+    "required": ["spec.md", "recap.md"]
+  },
+  "priority": 2
+}
+```
+
+**2. Create Documentation:**
+
+Create `framework/workflows/docs/my-workflow.md` explaining the workflow.
+
+**3. Test Detection:**
+
+```bash
+npx morph-spec detect-workflow "request with custom-keyword"
+```
+
+### Modifying Existing Workflows
+
+**Example: Add keywords to standard workflow**
+
+Edit `framework/workflows/configs/standard.json`:
+
+```json
+{
+  "keywords": [
+    "paginação", "pagination",
+    "filtro", "filter", "filtering",
+    "my-new-keyword"  // Added
+  ]
+}
+```
+
+**Example: Change complexity criteria**
+
+```json
+{
+  "criteria": {
+    "minFiles": 5,    // Changed from 3
+    "maxFiles": 15    // Changed from 10
+  }
+}
+```
+
+### Stack-Specific Customization
+
+If you need stack-specific workflow tweaks:
+
+**Option 1: Override in project**
+
+Copy workflow config to project:
+```bash
+cp framework/workflows/configs/standard.json \
+   .morph/config/workflows/standard-override.json
+```
+
+Modify as needed. Project configs take precedence.
+
+**Option 2: Extend with conditions**
+
+Add stack-specific conditions in config:
+
+```json
+{
+  "criteria": {
+    "stackSpecific": {
+      "blazor-azure": {
+        "minFiles": 5
+      },
+      "nextjs-supabase": {
+        "minFiles": 3
+      }
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+### Example 1: Bug Fix (fast-track)
+
+**Request:** "fix typo in login button"
+
+**Detection Result:**
+```
+Workflow: fast-track (95% confidence)
+Keywords: "fix", "typo"
+Estimated: 1 file, ~5 lines
+Phases: Quick Analysis → Implement
+```
+
+**User Experience:**
+```bash
+npx morph-spec feature create login-typo --request "fix typo in login button"
+
+# Output:
+✓ Detected workflow: fast-track
+⚡ Quick workflow - no spec files needed
+📝 Write quick analysis (1 paragraph) and implement
+
+# User writes quick analysis, then:
+npx morph-spec phase advance login-typo
+
+# Output:
+⏩ Skipping: setup, uiux, design, clarify, tasks, sync
+➡️  Next phase: implement
+```
+
+### Example 2: Pagination (standard)
+
+**Request:** "add pagination to users table"
+
+**Detection Result:**
+```
+Workflow: standard (85% confidence)
+Keywords: "paginação"
+Estimated: 5 files, ~200 lines
+Phases: PROPOSAL → DESIGN → TASKS → IMPLEMENT
+```
+
+**User Experience:**
+```bash
+npx morph-spec feature create user-pagination \
+  --request "add pagination to users table"
+
+# Output:
+✓ Detected workflow: standard
+📋 Phases: PROPOSAL (simplified) → DESIGN (concise) → TASKS → IMPLEMENT
+📄 Outputs: proposal.md, spec.md, tasks.json, recap.md
+```
+
+### Example 3: Authentication (full-morph)
+
+**Request:** "implement complete authentication system with OAuth"
+
+**Detection Result:**
+```
+Workflow: full-morph (92% confidence)
+Keywords: "authentication", "complete", "OAuth", "system"
+Estimated: 15 files, ~800 lines
+Phases: ALL (9 phases mandatory)
+```
+
+**User Experience:**
+```bash
+npx morph-spec feature create user-auth \
+  --request "implement complete authentication system with OAuth"
+
+# Output:
+✓ Detected workflow: full-morph
+📋 ALL phases required (9 phases)
+⏸️  5 pause points for approval
+📄 Complete outputs (10+ files)
+```
+
+### Example 4: Figma Conversion (design-impl)
+
+**Request:** "implement screens from Figma design"
+
+**Detection Result:**
+```
+Workflow: design-impl (88% confidence)
+Keywords: "figma", "implement", "screens"
+Phases: PROTOTYPE ANALYSIS → TASKS → IMPLEMENT
+```
+
+**User Experience:**
+```bash
+npx morph-spec feature create dashboard-screens \
+  --request "implement screens from Figma design"
+
+# Output:
+✓ Detected workflow: design-impl
+📋 Phases: PROTOTYPE ANALYSIS → TASKS (screen list) → IMPLEMENT
+⏩ Skipping: PROPOSAL, DESIGN, CLARIFY, SYNC
+📄 Outputs: recap.md, design-system.css (optional)
+```
+
+### Example 5: Redesign (ui-refresh)
+
+**Request:** "redesign dashboard to look more modern"
+
+**Detection Result:**
+```
+Workflow: ui-refresh (82% confidence)
+Keywords: "redesign", "modern"
+Estimated: Visual changes only
+Phases: VISUAL ANALYSIS → DESIGN SYSTEM → IMPLEMENT
+```
+
+**User Experience:**
+```bash
+npx morph-spec feature create dashboard-redesign \
+  --request "redesign dashboard to look more modern"
+
+# Output:
+✓ Detected workflow: ui-refresh
+📋 Phases: VISUAL ANALYSIS → DESIGN SYSTEM (simplified) → IMPLEMENT
+⚠️  Visual changes only - no business logic
+📄 Outputs: design-refresh-checklist.md, CSS
+```
+
+---
+
+## Troubleshooting
+
+### Wrong Workflow Detected
+
+**Problem:** System detected `full-morph` but you know it's a simple change.
+
+**Solution 1: Provide more context**
+```bash
+npx morph-spec feature create simple-fix \
+  --request "add pagination (simple, already have paginator component)"
+```
+
+**Solution 2: Manual override**
+```bash
+npx morph-spec state set my-feature workflow standard
+```
+
+**Solution 3: Improve keywords**
+
+If this happens often, add keywords to workflow config:
+```json
+{
+  "keywords": [
+    "simple",
+    "já temos componente"
+  ]
+}
+```
+
+### Low Confidence Score
+
+**Problem:** Detection confidence <50%
+
+**Possible Causes:**
+- Ambiguous request
+- No keyword matches
+- Complexity unclear
+
+**Solutions:**
+1. Be more specific in request:
+   - ❌ "add feature"
+   - ✅ "add pagination feature to users table"
+
+2. Include scope indicators:
+   - ❌ "authentication"
+   - ✅ "complete authentication system with OAuth"
+
+3. Mention technologies:
+   - ❌ "deploy"
+   - ✅ "deploy to Azure with Bicep"
+
+### Multiple Workflows Seem Valid
+
+**Problem:** standard (60%) vs full-morph (55%) - unclear which is better
+
+**Best Practice:**
+- **If unsure, go with higher complexity** (full-morph)
+- Reason: Better to have extra documentation than missing critical design
+- You can always skip optional phases later with `--force`
+
+**Alternative:**
+Use `detect-workflow` first to see both options:
+```bash
+npx morph-spec detect-workflow "add authentication"
+
+# Review both workflows
+# Decide based on:
+# - Do I have prototype/existing code?
+# - Is this greenfield or adding to existing?
+# - Do I need full architectural design?
+```
+
+### Workflow Doesn't Match Project Needs
+
+**Problem:** Your project always needs certain phases regardless of complexity
+
+**Solution: Create custom workflow**
+
+Example: "Always need UI/UX phase for Blazor projects"
+
+Create `framework/workflows/configs/blazor-standard.json`:
+```json
+{
+  "id": "blazor-standard",
+  "name": "Blazor Standard (with UI/UX)",
+  "criteria": {
+    "minFiles": 3,
+    "maxFiles": 10
+  },
+  "keywords": ["pagination", "filter"],
+  "phases": {
+    "run": ["proposal", "uiux", "design", "tasks", "implement"],
+    "skip": ["setup", "clarify", "sync"]
+  },
+  "priority": 2
+}
+```
+
+### Phases Skipped That You Need
+
+**Problem:** Workflow skipped UIUX but you need it
+
+**Solution 1: Force phase**
+```bash
+# Manually go to UIUX phase
+npx morph-spec phase set my-feature uiux
+```
+
+**Solution 2: Override workflow**
+```bash
+# Use full-morph (includes all phases)
+npx morph-spec state set my-feature workflow full-morph
+```
+
+**Solution 3: Document in decisions.md**
+```markdown
+## ADR: Added UI/UX Phase to Standard Workflow
+
+**Context:** Standard workflow skipped UI/UX but we needed Fluent UI design.
+
+**Decision:** Manually went to UI/UX phase after proposal.
+
+**Consequences:** Workflow became: PROPOSAL → UIUX → DESIGN → TASKS → IMPLEMENT
+```
+
+---
+
+## API Reference
+
+### detectWorkflow(options)
+
+Analyzes a user request and returns the best workflow match.
+
+**Parameters:**
+```javascript
+{
+  userRequest: string,      // Required: User's feature request
+  projectPath?: string,     // Optional: Project path (default: '.')
+  featureName?: string      // Optional: Feature name
+}
+```
+
+**Returns:**
+```javascript
+{
+  workflowId: string,                    // Selected workflow ID
+  confidence: number,                    // 0-1 confidence score
+  matchedKeywords: string[],             // Keywords that matched
+  estimatedComplexity: {
+    files: number,
+    lines: number,
+    components: number,
+    hasInfra: boolean
+  },
+  reasoning: string,                     // Human-readable explanation
+  alternativeWorkflows: Array<{
+    workflowId: string,
+    confidence: number,
+    reason: string
+  }>
+}
+```
+
+**Example:**
+```javascript
+import { detectWorkflow } from './src/lib/workflow-detector.js';
+
+const result = await detectWorkflow({
+  userRequest: "add pagination to users table",
+  projectPath: ".",
+  featureName: "user-pagination"
+});
+
+console.log(result.workflowId);  // "standard"
+console.log(result.confidence);  // 0.85
+```
+
+### getWorkflowConfig(workflowId, projectPath?)
+
+Loads a workflow configuration by ID.
+
+**Parameters:**
+```javascript
+workflowId: string,        // Workflow ID (e.g., "standard")
+projectPath?: string       // Optional: Project path (default: '.')
+```
+
+**Returns:**
+```javascript
+{
+  id: string,
+  name: string,
+  description: string,
+  criteria: object,
+  keywords: string[],
+  phases: object,
+  pausePoints: array,
+  outputs: object,
+  priority: number
+}
+```
+
+**Example:**
+```javascript
+import { getWorkflowConfig } from './src/lib/workflow-detector.js';
+
+const config = getWorkflowConfig('standard');
+console.log(config.phases.skip);  // ["setup", "uiux", "clarify", "sync"]
+```
+
+### listWorkflows(projectPath?)
+
+Lists all available workflows.
+
+**Parameters:**
+```javascript
+projectPath?: string  // Optional: Project path (default: '.')
+```
+
+**Returns:**
+```javascript
+Array<{
+  id: string,
+  name: string,
+  description: string
+}>
+```
+
+**Example:**
+```javascript
+import { listWorkflows } from './src/lib/workflow-detector.js';
+
+const workflows = listWorkflows();
+workflows.forEach(w => {
+  console.log(`${w.id}: ${w.name}`);
+});
+```
+
+---
+
+## See Also
+
+- [STORY-DRIVEN-DEVELOPMENT.md](docs/STORY-DRIVEN-DEVELOPMENT.md) - Philosophy and principles
+- [fast-track.md](docs/fast-track.md) - Fast-track workflow details
+- [standard.md](docs/standard.md) - Standard workflow details
+- [full-morph.md](docs/full-morph.md) - Full-morph workflow details
+- [design-impl.md](docs/design-impl.md) - Design implementation workflow
+- [ui-refresh.md](docs/ui-refresh.md) - UI refresh workflow
+- [Root CLAUDE.md](../../CLAUDE.md) - Main framework instructions
+
+---
+
+*MORPH-SPEC Framework - Polymorphism Tech*