devin-orchestrator

A generic, harness-agnostic framework for AI-assisted software development, built on top of Windsurf Cascade and inspired by obra/superpowers.

See Also:

• DEPLOY.md - One-click cross-platform deployment (recommended)
• TROUBLESHOOTING.md - Common install and runtime issues
• MCP-CLIENTS.md - MCP client configuration
• CONTRIBUTING.md - Tests, lint, build, and release process
• ARCHITECTURE.md - Core abstractions and design
• ORCHESTRATION-RUNBOOK.md - Agent-facing orchestration protocol
• skills/README.md - Skills library documentation

Quick Start

The fastest way to install devin-orchestrator and register it with every local MCP agent:

Linux / macOS

./deploy.sh

or directly with Python:

python3 deploy.py

Windows

py deploy.py

This installs the package to ~/.devin-orchestrator/ and updates all known agent MCP configs to use the launcher. Then restart your agent/IDE.

You can also install from PyPI and register manually:

pip install devin-orchestrator
devin-orchestrator --version
python3 -m devin_orchestrator.mcp_server --version
python3 -m devin_orchestrator.register_mcp

• DEPLOY.md — dry-run mode, manual steps, Windows/macOS notes.
• MCP-CLIENTS.md — per-agent configuration examples.

Vision

Separate process disciplines (skills, workflows, contracts) from harness mechanisms (transport adapters), enabling the same methodology to work across Windsurf Cascade, Claude Code, Devin CLI, and future platforms.

Architecture

Core Abstractions

1. Skills - Process disciplines with Iron Laws and checklists
2. Workflows - Step sequences with gates, artifacts, and skill assignments
3. Dispatch Contracts - Role-specific input/output contracts with quality bars
4. Transport Adapters - Harness-specific mechanisms (Windsurf, Claude Code, Devin CLI, etc.)
5. MCP Server - stdio JSON-RPC server exposing skills, workflows, and dispatch to any MCP-compatible client

Layer Stack

MCP-Compatible Client (Claude, Cursor, Cascade, etc.)
       ↓
MCP Server Layer (stdio JSON-RPC)
       ↓
Workflow Orchestration Layer
       ↓
Skills Invocation Layer
       ↓
Dispatch Contract Layer
       ↓
Transport Adapter Layer
       ↓
Platform Layer (Windsurf, Claude Code, Devin CLI, etc.)

Model Selection

• Architect: Cascade (SWE-1.6)
• Sub-agents (Coder, Test-Author, Reviewer): SWE-1.6 (default)
• Rationale: SWE-1.6 is free and allows parallelization up to 10 instances; target 8 parallel dispatches to leave headroom for Architect

Status

Early prototype phase. Design documented in ARCHITECTURE.md.

CLI and MCP Server

After installation, the devin-orchestrator command is the main entry point. See DEPLOY.md for install, uninstall, and service management.

python -m devin_orchestrator.mcp_server runs a stateless stdio MCP server that exposes skills, workflows, and Devin dispatch as JSON-RPC tools. Any MCP-compatible client (Claude Desktop, Cursor, OpenClaw, etc.) can connect and run the orchestrator without learning bash paths or local file layouts.

Primary MCP tools include:

• execute, implement, review, investigate, plan, run_workflow, run_skill - high-level intent routing and workflow execution
• dispatch_devin, dispatch_skill - low-level Devin worker dispatch
• list_skills, get_skill, list_workflows, get_workflow - discovery helpers
• read_artifact, list_directory, list_artifacts, write_artifact, apply_patch - workspace artifact helpers
• gate_decision, continue_workflow, query_workflow_status - gate control and status polling
• list_sessions, cancel_session, health - session and health helpers

See MCP-CLIENTS.md for client configuration examples. For the fastest setup, run the deployment script first — it writes the correct configuration for every supported client.

Directory Structure

devin-orchestrator/
├── MCP-CLIENTS.md   # MCP client configuration
├── skills/          # Skill definitions (YAML + markdown)
├── workflows/       # Workflow definitions (YAML manifests + markdown)
├── devin_orchestrator/  # Orchestration engine and tools
│   └── mcp_server.py    # MCP server entry point (stdio JSON-RPC)
├── adapters/        # Transport adapter implementations
├── contracts/       # Dispatch contract definitions
└── .windsurf/
    └── workflows/   # Windsurf slash command stubs

Attribution

Portions adapted from obra/superpowers, Copyright © 2025 Jesse Vincent, MIT License.