claude-flow-depth/README.md

DEPTH Methodology Installer - Ousterhout-First Development for Claude Code

# claude-flow-depth

🎯 **DEPTH Methodology Installer for Claude Code**

An npm package that initializes new projects with the DEPTH (Design-Twice, Eliminate complexity, Pull complexity down, Trade-off documentation, Hide implementation) methodology - an Ousterhout-first development approach.

## 🚀 Quick Start

### Global Installation
```bash
npm install -g claude-flow-depth@alpha
```

### Initialize New Project
```bash
# Interactive setup
npx claude-flow-depth@alpha init my-project

# Quick setup with defaults
npx claude-flow-depth@alpha init my-project --yes

# Force overwrite existing directory
npx claude-flow-depth@alpha init my-project --force

# With MCP integration
npx claude-flow-depth@alpha init my-project \
  --frontend-mcp https://your-project.supabase.co/functions/v1/frontend-mcp \
  --backend-mcp https://your-project.supabase.co/functions/v1/backend-mcp \
  --api-key your-supabase-key
```

### Test MCP Connections
```bash
npx claude-flow-depth@alpha test-mcp \
  --frontend https://your-project.supabase.co/functions/v1/frontend-mcp \
  --backend https://your-project.supabase.co/functions/v1/backend-mcp \
  --api-key your-api-key
```

## 🎯 What Gets Installed

### Project Structure
```
my-project/
├── .depth                    # Global DEPTH configuration
├── .depthmodes              # Phase-specific settings
├── .claude/
│   ├── commands/depth/      # DEPTH methodology commands
│   └── settings.json        # Claude Code + MCP configuration
├── depth-sessions/          # Session history
├── depth-reports/           # Generated reports
├── depth-memory/            # Persistent memory
├── examples/                # Sample DEPTH workflows
├── docs/                    # Methodology guides
├── CLAUDE.md               # Project overview
└── package.json            # Pre-configured scripts
```

### DEPTH Commands Available
```bash
/depth orchestrator "Build feature"        # Complete methodology
/depth design-twice "Create API"           # Design alternatives  
/depth interface-simplify "Optimize API"   # Interface optimization
/depth complexity-allocate "Design modules" # Complexity distribution
/depth strategic-invest "Plan improvements" # Strategic planning
/depth implementation-hide "Generate code"  # Code generation
```

### Quality Gates Enforced
- ✅ **Module Depth Ratio** > 0.6 (deep modules)
- ✅ **Interface Complexity** < 0.4 (simple interfaces)  
- ✅ **Strategic Investment** 10-20% (Ousterhout's rule)
- ✅ **Information Hiding** > 80% (encapsulation)

## 🔧 CLI Options

### `init` Command
```bash
npx claude-flow-depth init [directory] [options]

Options:
  -f, --force                 Force overwrite existing directory
  -y, --yes                   Skip prompts, use defaults
  --frontend-mcp <url>        Frontend MCP URL
  --backend-mcp <url>         Backend MCP URL  
  --api-key <key>            Supabase API key
```

### `test-mcp` Command
```bash
npx claude-flow-depth test-mcp [options]

Options:
  --frontend <url>           Frontend MCP URL to test
  --backend <url>            Backend MCP URL to test
  --api-key <key>           API key for authentication
```

## 🎓 DEPTH Methodology

### What is DEPTH?
**D**esign-Twice • **E**liminate complexity • **P**ull complexity down • **T**rade-off documentation • **H**ide implementation

DEPTH follows John Ousterhout's principles from "A Philosophy of Software Design" to create maintainable, scalable software.

### Methodology Phases
1. **Design-Twice**: Create two design alternatives, choose the superior approach
2. **Interface-Simplification**: Minimize cognitive load while maintaining functionality  
3. **Complexity-Allocation**: Push complexity into modules, away from interfaces
4. **Strategic-Investment**: Enforce 10-20% time on long-term improvements
5. **Implementation-Hiding**: Generate well-commented code with maximum encapsulation

### vs Other Methodologies
- **SPARC**: Context-first, rapid iteration, pattern-based
- **DEPTH**: Design-first, strategic thinking, principle-based
- **Agile**: Sprint-focused, adaptive, team-based

## 🔗 MCP Integration

DEPTH automatically integrates with:
- **Frontend MCP**: Pattern recommendations, best practices
- **Backend MCP**: Architecture guidance, system design
- **Claude Flow Swarm**: Parallel execution, coordination

### Pre-configured MCP Endpoints
The installer comes pre-configured with working MCP endpoints:
```
Frontend: https://plwgqygbzreiogubsaui.supabase.co/functions/v1/frontend-mcp
Backend:  https://plwgqygbzreiogubsaui.supabase.co/functions/v1/backend-mcp
```

## 📊 Session Tracking

DEPTH automatically tracks:
- **Quality Metrics**: Module depth, interface complexity, strategic investment
- **Phase Progress**: Completion status, quality gate validation
- **Decisions**: Design choices and rationale documentation  
- **Reports**: Comprehensive session summaries

## 🤝 Development

### Build from Source
```bash
git clone https://github.com/your-username/claude-flow-depth.git
cd claude-flow-depth
npm install
npm run build
npm link
```

### Test Locally
```bash
npm run dev init test-project --yes
```

## 📄 License

MIT License - see LICENSE file for details.

## 🌟 Examples

### Initialize Todo App with DEPTH
```bash
npx claude-flow-depth@alpha init todo-app-depth --yes
cd todo-app-depth
# Open in Claude Code
/depth orchestrator "Build todo application with CRUD operations"
```

### Initialize E-commerce API  
```bash
npx claude-flow-depth@alpha init ecommerce-api \
  --frontend-mcp https://your-project.supabase.co/functions/v1/frontend-mcp \
  --backend-mcp https://your-project.supabase.co/functions/v1/backend-mcp
cd ecommerce-api
/depth design-twice "Design product catalog API"
```

---

Built with ❤️ using the DEPTH Methodology  
*Ousterhout-first development for Claude Code*