@jmkim85/dev-flow-mcp/README.md

MCP-based Dev Flow - AI-powered development workflow management with 13 essential tools for TDD and context management

# Dev Flow MCP

**Version v2.3.0** - Advanced MCP-based AI-powered development workflow management with intelligent workflow systems, master plan execution, reward hacking prevention, multi-project management, and enhanced context preservation.

## 🎯 What's New in v2.3.0

### 🏗️ Multi-Project Management
- **Global Configuration**: Manage multiple projects from a single config
- **Project Switching**: Seamlessly switch between different projects
- **Project Initialization**: Set up Dev Flow in any project directory
- **Centralized Settings**: User-level configuration in home directory

### 🧠 Enhanced Context Management
- **Context Frames**: Sophisticated context tracking with frame hierarchy
- **Fact Management**: Add and preserve important facts across sessions
- **Smart Inheritance**: Context frames inherit relevant information
- **Token Optimization**: Intelligent context compression for long conversations

### 🖥️ Command Line Interface
- **Full CLI Support**: Complete command-line interface for all operations
- **Project Visualization**: Visual dependency graphs and progress tracking
- **Status Monitoring**: Real-time project and task status
- **Test Integration**: Built-in test running and validation

### 📊 Improved Project Structure
- **Flexible Paths**: Work with projects anywhere on your system
- **Better Organization**: Enhanced .devflow directory structure
- **Configuration Management**: Robust config file handling

## 🎯 What's New in 2.0

### 🔄 Advanced Workflow System
- **Predefined Workflows**: TDD Strict, General Development
- **Stage-based Instructions**: Detailed LLM guidance for each workflow stage
- **Validation Rules**: Prevent test bypassing and ensure quality
- **Task Definition Integration**: Link external requirement documents

### 📊 Master Plan Management
- **Phased Execution**: Break complex projects into manageable phases
- **Dependency Tracking**: Ensure proper phase progression
- **Progress Monitoring**: Track completion across multiple phases
- **Flexible Planning**: Create custom plans for different project types

### 🛡️ Reward Hacking Prevention
- **Sub-task Validation**: Prevent trivial or procrastination tasks
- **Test Integrity**: Detect and block test bypassing attempts
- **Iteration Limits**: Force proper approach when stuck
- **Quality Gates**: Ensure substantial work before advancement

### 🧠 Enhanced Context Preservation
- **Smart Snapshots**: Maintain context across long conversations
- **Event Tracking**: Record all significant development events
- **Automatic Summarization**: Compress context while preserving key information
- **Token Optimization**: Stay within LLM context limits

### 🚀 13 Essential Tools (Enhanced Architecture)
Dev Flow v2.3.0 provides 13 comprehensive tools for complete single-developer TDD workflow management with advanced workflow control.

### Before (v1)
- 100+ files across multiple packages
- FastAPI server with SQLAlchemy models
- React frontend with complex state management
- SQLite database with Alembic migrations
- Extensive CLI with 20+ commands
- Bridge server for IDE integration

### After (v2)
- Single TypeScript MCP server (~500 lines)
- Simple JSON/YAML state files
- 6 direct LLM tools
- No database, no web UI, no complex CLI
- Direct Claude Desktop integration

## 🚀 Quick Start

### 1. Install from NPM (Recommended)
```bash
# Install globally
npm install -g @jmkim85/dev-flow-mcp
```

### 2. Or install from source
```bash
git clone https://github.com/jmkim-clt/mcp-dev-flow.git
cd mcp-dev-flow
npm install
npm run build
```

### 3. Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "dev-flow": {
      "command": "npx",
      "args": ["-y", "@jmkim85/dev-flow-mcp@latest"],
      "cwd": "/path/to/your/project",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

**Important**: Replace `/path/to/your/project` with your actual project directory path. This ensures Dev Flow creates the `.devflow` folder in your project, not in a random location.

### 4. Initialize Project
```bash
# Create .solo directory structure
node dist/migrate.js
```

## 🛠️ The 13 Essential Tools

### Core Task Management (6 tools)

#### 1. `get_next_task`
Get current task status and what to work on next.

**Usage**: "What should I work on next?"

#### 2. `start_task`
Start working on a specific task at a given stage.

**Parameters**:
- `task_id`: Task identifier
- `stage`: "analyze" | "write_tests" | "implement" | "refactor"

**Usage**: "Start the authentication task at the write_tests stage"

#### 3. `check_progress`
Check current progress and validate readiness for next stage.

**Parameters**:
- `run_tests`: Whether to run tests (boolean)

**Usage**: "Check my progress and run tests"

#### 4. `save_checkpoint`
Save current progress as a checkpoint.

**Parameters**:
- `message`: Description of what was accomplished
- `files`: Array of changed files

**Usage**: "Save checkpoint: implemented user login"

#### 5. `record_mistake`
Record a mistake pattern for future learning.

**Parameters**:
- `pattern`: Description of the mistake
- `context`: Where it occurred
- `solution`: How to avoid it

**Usage**: "Record mistake: forgot to hash passwords"

#### 6. `complete_task`
Mark current task as complete (validates tests pass first).

**Parameters**:
- `summary`: What was accomplished

**Usage**: "Complete this task - authentication is working"

### Context Management (3 tools)

#### 7. `create_context_frame`
Create a new context frame for better context management.

**Parameters**:
- `task_id`: Task identifier
- `stage`: Current stage
- `summary`: Brief summary of current context

**Usage**: "Create context frame for the authentication task"

#### 8. `add_context_fact`
Add an important fact to the current context frame.

**Parameters**:
- `fact`: The fact to record
- `is_global`: Whether this fact applies globally

**Usage**: "Add fact: using JWT for authentication"

#### 9. `get_context`
Get current context summary for the active task.

**Usage**: "Show me the current context"

### Workflow Management (1 tool)

#### 10. `load_workflow`
Load a predefined workflow with stage-by-stage instructions.

**Parameters**:
- `workflow_id`: "tdd_strict" | "general_dev"

**Usage**: "Load the TDD workflow for this task"

### Project Maintenance (2 tools)

#### 11. `clean_temp_files`
Clean temporary files and IDE artifacts from the project.

**Usage**: "Clean up temporary files"

#### 12. `initialize_project_file`
Initialize a project file from a template.

**Parameters**:
- `template_type`: "project_overview" | "tasklist" | "readme"

**Usage**: "Initialize a project overview template"

### Workflow Control (1 tool) - NEW in v2.3.0

#### 13. `advance_stage`
Advance to the next stage in the current workflow for the active task.

**Parameters**:
- `summary`: Optional summary of completed stage

**Usage**: "Advance to the next stage - analysis complete"

#### 11. `advance_phase`
Move to the next phase in the master plan.

**Parameters**:
- `completion_summary`: Summary of completed phase

**Usage**: "Advance to next phase - planning is complete"

#### 12. `create_master_plan`
Create a new master plan for complex projects.

**Parameters**:
- `title`: Plan title
- `overview`: Project overview
- `phases`: Array of phase definitions

**Usage**: "Create a master plan for the e-commerce platform"

### Project & Context Management (5 new tools)

#### 13. `set_project`
Set the current working project for all operations.

**Parameters**:
- `project_path`: Path to the project directory

**Usage**: "Set the current project to /path/to/my-project"

#### 14. `init_project`
Initialize Dev Flow in a new project directory.

**Parameters**:
- `project_path`: Optional path to initialize (defaults to current directory)

**Usage**: "Initialize Dev Flow in this project"

#### 15. `create_context_frame`
Create a new context frame for sophisticated context management.

**Parameters**:
- `task_id`: Task identifier
- `stage`: Current stage
- `summary`: Optional brief summary

**Usage**: "Create a context frame for the authentication task"

#### 16. `add_context_fact`
Add an important fact to the current context frame.

**Parameters**:
- `fact`: The fact to remember
- `is_global`: Whether this applies globally (default: false)

**Usage**: "Remember that we're using JWT tokens for authentication"

#### 17. `get_enhanced_context`
Get enhanced context summary with frame management.

**Usage**: "Show me the current context"

## 🎯 Simplified Architecture (v2.3.0)

Based on user feedback, Dev Flow v2.3.0 has been **significantly simplified**:

### ✅ What We Fixed
- **Directory Confusion**: `.solo` / `.devflow` mixed usage → **Unified to `.devflow`**
- **Tool Overload**: 17 tools → **9 essential tools** for single developer workflow
- **Context Complexity**: 3 different context managers → **1 unified context manager**
- **Runtime Bugs**: Fixed YAML parsing errors and path issues
- **Over-engineering**: Removed master plans, complex workflows → **Focus on TDD essentials**

### 🎯 Core Philosophy
**"Single developer, TDD-focused, minimal complexity"**

The 9 tools are organized into 3 logical groups:
1. **Task Management** (3): get_next_task, start_task, complete_task
2. **Progress & Validation** (3): check_progress, save_checkpoint, record_mistake
3. **Context Management** (3): create_context_frame, add_context_fact, get_context

### 🚀 Performance Benefits
- **20-30% less code** through context manager consolidation
- **Faster startup** with fewer components
- **Clearer mental model** for LLM agents
- **Reduced token usage** with focused context

## 🖥️ Command Line Interface

Dev Flow v2.3.0 includes a comprehensive CLI for direct interaction:

### Installation & Setup
```bash
# Install globally (after building)
npm install -g .

# Or use directly
node dist/cli.js --help
```

### CLI Commands

#### Project Management
```bash
# Initialize Dev Flow in current directory
devflow init

# Initialize in specific directory
devflow init /path/to/project

# Set current project
devflow use /path/to/project

# List all registered projects
devflow projects
```

#### Status & Monitoring
```bash
# Show project status
devflow status

# List all tasks
devflow tasks

# List tasks by status
devflow tasks --status pending

# Visualize project structure
devflow visualize
```

#### Task Operations
```bash
# Start a task
devflow start task_id

# Start at specific stage
devflow start task_id --stage implement

# Run tests for current task
devflow test
```

## 📁 Project Structure

```
your-project/
├── .devflow/                # Dev Flow data
│   ├── state.json           # Current state
│   ├── tasks.yaml           # Task definitions
│   ├── mistakes.json        # Mistake patterns
│   ├── context/             # Context snapshots & events
│   ├── workflows/           # Workflow definitions
│   │   ├── tdd_strict.yaml  # TDD workflow
│   │   └── general_dev.yaml # General development workflow
│   └── plans/               # Master plans
│       └── master.yaml      # Current master plan
├── dev-flow-mcp/            # MCP server
│   ├── src/                 # TypeScript source
│   ├── dist/                # Compiled JavaScript
│   └── package.json         # Dependencies
├── task-definitions/        # External task requirements
│   ├── auth-requirements.md
│   └── api-spec.md
└── your-code/               # Your actual project
```

## 🔄 TDD Workflow Enforcement

The system enforces Test-Driven Development:

1. **analyze** → **write_tests**: No restrictions
2. **write_tests** → **implement**: Tests MUST fail
3. **implement** → **refactor**: Tests MUST pass
4. **Any stage** → **complete**: Tests MUST pass

## 🧠 Mistake Learning

The system learns from mistakes and warns about patterns:

```typescript
// Example mistake pattern
{
  "pattern": "Storing passwords without hashing",
  "frequency": 3,
  "solutions": ["Use bcrypt", "Use argon2"],
  "last_occurred": "2024-01-15T10:30:00Z"
}
```

## 📋 Example Tasks File

```yaml
# .devflow/tasks.yaml
tasks:
  - id: implement_auth
    title: User Authentication
    description: JWT-based authentication system
    success_criteria: All auth tests pass
    test_command: pytest tests/test_auth.py
    dependencies: []
    phases: [setup]
    status: pending
    priority: high
    
  - id: create_api
    title: REST API Endpoints
    description: FastAPI endpoints for user management
    success_criteria: API tests pass and docs are complete
    test_command: pytest tests/test_api.py
    dependencies: [implement_auth]
    phases: [api]
    status: pending
    priority: medium
```

## 🔧 Development

### Run in Development Mode
```bash
npm run dev  # Watches for changes
```

### Run Tests
```bash
npm test
```

### Migration from v1
```bash
# Migrate existing Dev Flow project
node dist/migrate.js
```

## 🎯 Usage Examples

### Using Workflows for Structured Development
```
Human: I want to implement user authentication using strict TDD

Claude: Perfect! Let me load the TDD workflow to guide us through this process.

[Uses load_workflow tool with workflow_id="tdd_strict"]

I've loaded the Strict TDD Workflow with 4 stages:

1. **Understand Requirements** - Analyze task without writing code
2. **Design Test Cases** - Write failing tests first
3. **Implement Solution** - Minimal code to pass tests
4. **Refactor Code** - Improve quality while keeping tests green

Let me start the authentication task at the understand stage.

[Uses start_task tool with task_id="implement_auth", stage="understand"]

Now I'm following the TDD workflow instructions:
1. Reading task requirements thoroughly
2. Identifying acceptance criteria
3. Listing edge cases
4. Creating mental model of solution
5. NOT writing any implementation code yet

The workflow prevents me from jumping ahead - I must complete each stage properly.
```

### Creating and Managing Master Plans
```
Human: I'm starting a complex e-commerce project. Can you help me plan it?

Claude: I'll create a comprehensive master plan for your e-commerce project.

[Uses create_master_plan tool with structured phases]

I've created a 4-phase master plan:

**Phase 1: Planning & Analysis** (Current)
- Requirements gathering
- Technical architecture design
- Database schema planning

**Phase 2: Core Implementation**
- User authentication system
- Product catalog
- Shopping cart functionality

**Phase 3: Advanced Features**
- Payment processing
- Order management
- Admin dashboard

**Phase 4: Launch Preparation**
- Testing & QA
- Performance optimization
- Deployment setup

Each phase has specific completion criteria and dependencies. We'll advance phases only when all criteria are met.
```

### Smart Sub-task Creation with Validation
```
Human: This authentication task is complex. Can I break it down?

Claude: I'll help you create meaningful sub-tasks. Let me break down the authentication work.

[Uses create_subtask tool with parent_task_id="implement_auth"]

I've created these validated sub-tasks:

1. **Database Schema Design** - Design user tables and relationships
2. **Password Security Implementation** - Implement hashing and validation
3. **JWT Token Management** - Create and verify tokens
4. **API Endpoint Development** - Login/logout/register endpoints

The system prevented me from creating trivial sub-tasks like "fix typos" or "add comments" - it ensures each sub-task represents substantial work that moves the project forward.
```

### Multi-Project Management with Enhanced Context
```
Human: I'm working on multiple projects. Can you help me manage them?

Claude: I'll help you set up multi-project management with Dev Flow v2.3.0.

[Uses init_project tool for each project]

I've initialized Dev Flow in both projects:
- E-commerce Platform: /home/user/projects/ecommerce
- Mobile App: /home/user/projects/mobile-app

[Uses set_project tool to switch between projects]

Now I'm switching to the e-commerce project to continue our authentication work.

[Uses create_context_frame tool]

I've created a context frame for the authentication task. This will track our progress and important decisions across our conversation.

[Uses add_context_fact tool]

I'm recording that we decided to use JWT tokens with 24-hour expiration. This fact will be preserved even if our conversation gets long.

When you switch projects or return to this task later, I can use `get_enhanced_context` to quickly recall where we left off.
```

### CLI Integration for LLM Agents
```
Human: Can you check the status of my project using the CLI?

Claude: I'll check your project status using the Dev Flow CLI.

[Uses CLI through execute_command]

$ devflow status

📊 Project Status

Project: /home/user/projects/ecommerce
Current Task: implement_auth
Current Stage: implement
Context Files: 3

📋 Tasks Summary
┌─────────────┬───────┐
│ Status      │ Count │
├─────────────┼───────┤
│ Pending     │ 2     │
│ In Progress │ 1     │
│ Completed   │ 3     │
│ Total       │ 6     │
└─────────────┴───────┘

Great! You have 1 task in progress (authentication) and 2 pending tasks. Let me visualize the project structure:

$ devflow visualize

🗺️ Project Visualization

Master Plan: E-commerce Platform
✅ Planning & Analysis
🔄 Core Implementation (Current)
⏳ Testing & Refinement
⏳ Launch Preparation

The CLI shows you're in the Core Implementation phase with authentication work in progress.
```

## 🚀 Benefits of MCP Architecture

1. **90% Less Code**: 500 lines vs 5000+ lines
2. **Direct LLM Integration**: No copy/paste commands
3. **Real-time State Access**: LLM can read current status
4. **Simplified Deployment**: Single Node.js process
5. **Better Context**: Structured information for LLM
6. **Faster Development**: No web UI or database setup

## 🔮 Future Enhancements

### 2.3 Planned Features
- **Custom Workflow Designer**: Create workflows via YAML configuration
- **Team Collaboration**: Multi-developer project coordination
- **Advanced Analytics**: Development velocity and quality metrics
- **Integration Hub**: GitHub Actions, CI/CD, and notification systems

### 2.4 Advanced Features
- **AI Code Review**: Automated code quality assessment
- **Predictive Planning**: ML-based effort estimation
- **Multi-language Templates**: Support for more project types
- **Real-time Collaboration**: Live development session sharing

### Long-term Vision
- **Enterprise Features**: Role-based access, audit trails
- **Plugin Ecosystem**: Community-contributed workflows and tools
- **Advanced AI Integration**: GPT-4 code generation with quality gates
- **Cross-platform IDE Support**: VS Code, IntelliJ, Vim integrations

## 📄 License

MIT License - see LICENSE file for details.