Workflow Control

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

Overview

Workflow Control is a unified system that:

Orchestrates multi-agent workflows (phases, sub-agents, coordination)
Tracks everything via MCP tools + SQLite (decisions, progress, files)
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)
pnpm (npm install -g pnpm)
git

Automated Setup

# 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

# 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:

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

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

# Or manually create .mcp.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:

# Create symlinks
./scripts/symlink.sh

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

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

Usage

Start the Web UI

pnpm dev:ui

Opens at http://localhost:3000

Verify MCP Server

./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

# 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

# Rebuild the project
pnpm build:all

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

Database Errors

# Regenerate Prisma client
pnpm db:generate

# Reset and migrate database
pnpm db:migrate

Symlink Issues

# 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

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

Uninstall

# 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

MCP Workflow Tracker