# Workflow Control

> Orchestration + Observability for Agentic Workflows - Multi-agent workflow system with MCP tracking.

## Overview

Workflow Control is a unified system that:
1. **Orchestrates** multi-agent workflows (phases, sub-agents, coordination)
2. **Tracks** everything via MCP tools + SQLite (decisions, progress, files)
3. **Visualizes** workflows in real-time (WebUI dashboard)

## Architecture

**Monorepo Structure** (pnpm workspaces)
```
workflow-control/
├── packages/
│   ├── shared/           # Prisma schema + Types (source of truth)
│   ├── mcp-server/       # MCP Server (tools for orchestration & tracking)
│   └── web-ui/           # Next.js Dashboard
├── workflow-system/      # Workflow orchestration docs & templates
│   ├── docs/             # Architecture, templates, profiles
│   └── agents/           # workflow-architect agent
├── scripts/              # Setup & installation scripts
└── .claude/              # Dev config for this project
```

## Installation

### Prerequisites

- **Node.js 20+** ([Download](https://nodejs.org/))
- **pnpm** (`npm install -g pnpm`)
- **git**

### Automated Setup

```bash
# Clone the repository
git clone <repository-url>
cd workflow-control

# Run the setup script
./scripts/setup.sh
```

The setup script will:
- Check prerequisites (Node.js 20+, pnpm, git)
- Install dependencies
- Generate Prisma client
- Run database migrations
- Build the project
- Create symlinks in `~/.claude/` for global access

### Manual Setup

```bash
# Install dependencies
pnpm install

# Generate Prisma client
pnpm db:generate

# Run database migrations
pnpm db:migrate

# Build the project
pnpm build:all
```

## Configuration

### MCP Server Configuration

Add Workflow Control to your project's `.mcp.json`:

```bash
# Interactive mode
./scripts/generate-mcp-config.sh

# Or specify the project path
./scripts/generate-mcp-config.sh ~/my-project

# Or manually create .mcp.json:
```

```json
{
  "mcpServers": {
    "workflow-control": {
      "command": "node",
      "args": ["/path/to/workflow-control/packages/mcp-server/dist/index.js"]
    }
  }
}
```

### Claude Code Symlinks

The setup script creates symlinks for global access:

```
~/.claude/docs/workflow-system/     -> Workflow System documentation
~/.claude/agents/workflow-architect.md -> Workflow Architect agent
```

To manage symlinks manually:

```bash
# Create symlinks
./scripts/symlink.sh

# Force overwrite existing
./scripts/symlink.sh --force

# Remove symlinks
./scripts/symlink.sh --remove
```

## Usage

### Start the Web UI

```bash
pnpm dev:ui
```

Opens at http://localhost:3000

### Verify MCP Server

```bash
./scripts/verify-mcp.sh

# With verbose output
./scripts/verify-mcp.sh --verbose
```

### MCP Tools Available

| Tool | Description |
|------|-------------|
| `start_workflow` | Create a new workflow with phases |
| `complete_workflow` | Finalize a workflow with summary |
| `start_task` | Start a task within a workflow |
| `complete_task` | Complete a task with results |
| `log_decision` | Record an architectural decision |
| `log_issue` | Report a problem or blocker |
| `log_milestone` | Mark a milestone achievement |
| `get_context` | Query workflow state and history |

## Scripts Reference

| Script | Description |
|--------|-------------|
| `./scripts/setup.sh` | Full installation and setup |
| `./scripts/symlink.sh` | Manage Claude symlinks |
| `./scripts/generate-mcp-config.sh` | Generate .mcp.json config |
| `./scripts/verify-mcp.sh` | Test MCP server connection |

### Script Options

```bash
# Setup
./scripts/setup.sh --help
./scripts/setup.sh --silent          # Non-interactive mode
./scripts/setup.sh --skip-build      # Skip building
./scripts/setup.sh --skip-symlinks   # Skip symlink creation

# Symlinks
./scripts/symlink.sh --help
./scripts/symlink.sh --force         # Overwrite existing
./scripts/symlink.sh --remove        # Remove symlinks

# MCP Config
./scripts/generate-mcp-config.sh --help
./scripts/generate-mcp-config.sh --stdout   # Print to stdout
./scripts/generate-mcp-config.sh --force    # Overwrite existing

# Verify
./scripts/verify-mcp.sh --help
./scripts/verify-mcp.sh --verbose    # Detailed output
./scripts/verify-mcp.sh --timeout 30 # Custom timeout
```

## Tech Stack

- **MCP Server**: Node.js + TypeScript + @modelcontextprotocol/sdk
- **Database**: SQLite (local, no external server required)
- **ORM**: Prisma (with TypeScript type-safe enums)
- **Web UI**: Next.js 15 + Socket.io (real-time updates)
- **Git Integration**: simple-git (snapshots/diffs)

## Documentation

Technical documentation is in `.claude/docs/`:
- **architecture.md** - System architecture
- **mcp-tools.md** - MCP tools specifications
- **database.md** - Prisma schema reference
- **standards.md** - Code standards

Workflow System docs are in `workflow-system/docs/`:
- **architecture.md** - Workflow orchestration patterns
- **templates/** - Workflow and agent templates
- **profiles/** - Simple, standard, and complex workflow profiles

## Troubleshooting

### MCP Server Not Found

```bash
# Rebuild the project
pnpm build:all

# Verify the binary exists
ls -la packages/mcp-server/dist/index.js
```

### Database Errors

```bash
# Regenerate Prisma client
pnpm db:generate

# Reset and migrate database
pnpm db:migrate
```

### Symlink Issues

```bash
# Force recreate symlinks
./scripts/symlink.sh --force

# Check symlink targets
ls -la ~/.claude/docs/workflow-system
ls -la ~/.claude/agents/workflow-architect.md
```

### Verify Everything Works

```bash
./scripts/verify-mcp.sh --verbose
```

## Uninstall

```bash
# Remove symlinks
./scripts/symlink.sh --remove

# Remove database
rm packages/shared/prisma/dev.db

# Remove node_modules
rm -rf node_modules packages/*/node_modules
```

---

**License**: MIT