npm package: @hangten/waveflow
Description: AI-Enforced Development Methodology for HangTen Venture Studio
Author: HangTen Venture Studio
Latest version: 2.8.13

# 🌊 WaveFlow - AI-Enforced Development Methodology

**Epic-Based Development with Interactive Prototyping for HangTen Venture Studio**

[![npm version](https://img.shields.io/npm/v/@hangten/waveflow.svg)](https://www.npmjs.com/package/@hangten/waveflow)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🎯 What is WaveFlow v2.8?

WaveFlow is an **AI-enforced development methodology** that combines structured documentation with intelligent assistance to deliver enterprise-grade software at startup speed. **Version 2.8** introduces **Epic-Based Development** and **Interactive Prototyping** for scalable team collaboration.

### ✨ **New in v2.8**
- 🏗️ **Epic-Based Development** - Break large projects into manageable, parallel epics
- 🎭 **Interactive Prototyping** - Chat-based prototype development with production tech stack
- 🎨 **Automated Design Reviews** - Playwright MCP integration for comprehensive UI/UX validation
- ♿ **Accessibility Compliance** - Built-in WCAG 2.1 AA validation
- 📱 **Responsive Testing** - Cross-viewport validation (mobile, tablet, desktop)

---

## 🚀 Quick Start

### **Installation**
```bash
# Install WaveFlow globally (recommended)
npm install -g @hangten/waveflow

# Or use directly with npx (always latest)
npx @hangten/waveflow@latest --help
```

### **Initialize in Your Project**
```bash
# Navigate to your project
cd your-project

# Initialize WaveFlow (creates .waveflow/ directory)
npx waveflow init

# Check project status
npx waveflow status
```

### **Update Existing Projects**
```bash
# Update project configuration to latest version
npx waveflow update

# Set up new design review features (optional)
npx waveflow setup-playwright
```

---

## 📋 **WaveFlow v2.8 Methodology**

### **Epic-Based Development Process**
```
🚀 Project Start
    ↓
📋 Master Product Brief → 🎨 Design System → 📊 Master PRD
    ↓
🏗️ Epic Generation (SME-Guided AI Breakdown)
    ↓
📝 Epic PRDs (Parallel Development)
    ↓
🎭 Interactive Prototyping (Chat-Based)
    ↓
🎨 Design Review (Playwright MCP)
    ↓
📊 Data Structures → 🧪 Test Scripts → 📋 Tasks
    ↓
⚡ Implementation → 🔗 Integration → 🎉 Delivery
```

### **Key Benefits**
- ✅ **Divide & Conquer**: Large projects broken into manageable epics
- ✅ **Parallel Development**: Multiple developers work simultaneously  
- ✅ **Prototype-First**: Validate interfaces before full implementation
- ✅ **Quality Assurance**: Automated design reviews and accessibility testing
- ✅ **Technology Enforcement**: Approved stack compliance (Next.js, React, TypeScript, etc.)

---

## 📚 **Documentation**

### **📖 Essential Guides**
| Guide | Description | Link |
|-------|-------------|------|
| 📋 **User Manual** | Complete usage guide | [docs/user-manual.md](docs/user-manual.md) |
| 🎯 **v2.8 Methodology** | Epic-based development guide | [.waveflow/docs/methodology-guide-v2.8.md](.waveflow/docs/methodology-guide-v2.8.md) |
| ⚡ **Quick Reference** | Command cheat sheet | [docs/quick-reference.md](docs/quick-reference.md) |
| ❓ **FAQ** | Common questions | [docs/faq.md](docs/faq.md) |

### **🎭 New Features (v2.8)**
| Feature | Description | Link |
|---------|-------------|------|
| 🏗️ **Epic Generation** | SME-guided project breakdown | [docs/methodology-guide-v2.8.md#phase-4-epic-generation](docs/methodology-guide-v2.8.md) |
| 🎭 **Interactive Prototyping** | Chat-based prototype development | [docs/methodology-guide-v2.8.md#phase-6-interactive-prototyping](docs/methodology-guide-v2.8.md) |
| 🎨 **Design Review Integration** | Playwright MCP automation | [docs/design-review-integration-summary.md](docs/design-review-integration-summary.md) |
| 🛠️ **Playwright MCP Setup** | Browser automation setup | [docs/playwright-mcp-integration-guide.md](docs/playwright-mcp-integration-guide.md) |

### **📊 Visual Process Flow**
- 🌐 **[Interactive Flow Diagram](docs/waveflow-flow.html)** - Visual methodology with controls
- 📋 **[Complete Documentation Index](docs/documentation-index.md)** - All documentation organized

---

## 💻 **Core Commands**

### **Project Management**
```bash
npx waveflow init                    # Initialize WaveFlow in project
npx waveflow status                  # Check project status
npx waveflow update                  # Update to latest version
npx waveflow docs                    # Open documentation
```

### **Epic-Based Development (v2.8)**
```bash
npx waveflow generate epic-breakdown      # Generate epic breakdown from Master PRD
npx waveflow generate functional-prd --epic="Epic Name"  # Create epic-specific PRD
npx waveflow setup-playwright            # Set up design review automation
```

### **Design Review (v2.8)**
```bash
# Claude Code - Slash commands
/design-review                           # Comprehensive review
/design-review --focus=accessibility     # Accessibility-focused

# Both IDEs - Template-based (WaveFlow standard approach)
@waveflow-prototype-design-review.yaml   # Prototype validation & iteration
@waveflow-design-review-agent.yaml       # Agent-based comprehensive review
```

### **Template Generation**
```bash
npx waveflow generate master-product-brief    # Strategic project overview
npx waveflow generate master-prd              # Technical specifications
npx waveflow generate functional-brief        # Feature overview
npx waveflow generate functional-prd          # Detailed requirements
npx waveflow generate ui-ux-design           # Design specifications
npx waveflow generate tasks                   # Implementation tasks
```

---

## 🛠️ **Technology Stack Enforcement**

WaveFlow enforces a **curated, high-quality technology stack**:

### ✅ **Required Technologies**
- **Framework**: Next.js 15.3.3+ with App Router
- **Frontend**: React 18.3.1+ with TypeScript
- **UI Components**: ShadCN/UI + Radix UI primitives
- **Styling**: Tailwind CSS utility-first approach
- **Icons**: Lucide React exclusively
- **Backend**: Supabase + Prisma ORM
- **Authentication**: NextAuth.js
- **Forms**: React Hook Form + Zod validation

### ❌ **Blocked Technologies**
- Material-UI, Ant Design, Bootstrap (use ShadCN/UI instead)
- Redux, Zustand (use React built-in state)
- CSS-in-JS libraries (use Tailwind CSS)
- Other icon libraries (use Lucide React)

---

## 🎨 **Design Review & Quality Assurance**

### **Automated Design Reviews (v2.8)**
- 🎭 **Playwright MCP Integration** - Real browser automation testing
- 🎯 **7-Phase Review Process** - Comprehensive validation
- ♿ **WCAG 2.1 AA Compliance** - Accessibility standards enforcement
- 📱 **Responsive Design Testing** - Cross-viewport validation
- ⚡ **Performance Monitoring** - Loading time and interaction testing

### **Quality Gates**
- **Blocker**: Critical failures requiring immediate fix
- **High-Priority**: Significant issues to address before merge
- **Medium-Priority**: Improvements for follow-up
- **Nitpick**: Minor aesthetic refinements

---

## 🏗️ **Epic-Based Development**

### **How It Works**
1. **Master PRD Analysis** - AI analyzes project requirements
2. **SME-Guided Breakdown** - Subject matter expert answers AI probing questions
3. **Dependency Mapping** - Automatic sequencing based on component relationships
4. **Parallel Development** - Multiple developers work on different epics simultaneously
5. **Integration Planning** - Clear cross-epic integration points

### **Benefits**
- 🎯 **Scalability** - Handle large, complex projects efficiently
- 👥 **Team Coordination** - Clear epic ownership and responsibilities  
- 🔗 **Dependency Management** - Optimal development sequencing
- 🚀 **Faster Delivery** - Parallel development reduces timeline

---

## 🎭 **Interactive Prototyping**

### **Chat-Based Development**
```
Developer: "Help me create an interactive prototype for the User Authentication epic"

AI: "I'll help you set up the prototype environment with the WaveFlow tech stack 
and build the core authentication flows with realistic mock data..."

[Iterative development continues through conversation]
```

### **Key Features**
- 💬 **Conversational Development** - Rapid iteration through chat
- 🛠️ **Production Tech Stack** - Same technologies as final application
- 📊 **Mock Data Integration** - Realistic test data for validation
- 🎨 **Design System Compliance** - Automatic adherence to standards
- ✅ **Prototype Evolution** - Approved prototypes become production reference

---

## 📊 **Project Examples**

### **Epic Breakdown Example**
```
Master PRD: "Project Management Platform"

Generated Epics:
├── Epic 1: User Authentication & Profiles (Phase 1 - Foundation)
├── Epic 2: Project Creation & Management (Phase 2)  
├── Epic 3: Task Management System (Phase 2)
├── Epic 4: Team Collaboration Tools (Phase 3)
└── Epic 5: Reporting & Analytics (Phase 4)
```

### **Development Workflow**
```bash
# 1. Generate epic breakdown
npx waveflow generate epic-breakdown

# 2. Create epic PRDs
npx waveflow generate functional-prd --epic="User Authentication"

# 3. Develop interactive prototype
# [Chat-based development in Cursor/Claude]

# 4. Run design review
/design-review --epic="User Authentication"

# 5. Proceed to production development
```

---

## 🆘 **Support & Resources**

### **Getting Help**
- 📚 **[Complete Documentation](docs/documentation-index.md)** - All guides organized
- ❓ **[FAQ](docs/faq.md)** - Common questions and solutions
- 🎭 **[Playwright MCP Setup](/.waveflow/docs/playwright-mcp-integration-guide.md)** - Design review automation
- 🚀 **[v2.8 Implementation Guide](/.waveflow/docs/waveflow-v2.8-implementation-summary.md)** - New features overview

### **Troubleshooting**
```bash
# Check system status
npx waveflow status

# Verify installation
npx waveflow --version

# Update to latest
npx waveflow update

# Reset if needed
rm -rf .waveflow && npx waveflow init
```

### **Version Information**
- **Current Version**: 2.8.0
- **Node.js**: 18+ required
- **NPM**: 8+ required
- **Compatibility**: Backward compatible with v2.7 projects

---

## 🎉 **Success Stories**

WaveFlow has successfully delivered:
- ✅ **Enterprise Applications** - Complex business systems
- ✅ **SaaS Platforms** - Multi-tenant applications  
- ✅ **E-commerce Solutions** - High-performance retail platforms
- ✅ **Mobile-First Applications** - Responsive, accessible interfaces
- ✅ **AI-Powered Systems** - Modern, intelligent applications

**Key Results:**
- 🚀 **3x Faster Development** - Epic-based parallel development
- 🎯 **95% Quality Score** - Automated design review compliance
- ♿ **100% Accessibility** - WCAG 2.1 AA standard compliance
- 👥 **Seamless Team Collaboration** - Clear epic ownership and integration

---

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

**Created by HangTen Venture Studio** - Empowering teams to build exceptional software with AI-assisted methodologies.

---

*Ready to revolutionize your development process? Start with `npx waveflow init` and experience the power of Epic-Based Development with Interactive Prototyping!* 🌊✨