Metadata-Version: 2.4
Name: devin-orchestrator
Version: 0.1.9
Summary: Stateless orchestration layer for Devin workflows and skills
Project-URL: Homepage, https://github.com/emiltsoi/devin-orchestrator
Author: Devin Orchestrator Contributors
License: MIT
License-File: LICENSE
Keywords: devin,mcp,orchestrator,skills,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=5.1
Requires-Dist: requests>=2.25.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pip-audit>=2.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Description-Content-Type: text/markdown

# devin-orchestrator

A generic, harness-agnostic framework for AI-assisted software development, built on top of Windsurf Cascade and inspired by [obra/superpowers](https://github.com/obra/superpowers).

**See Also:**
- [DEPLOY.md](DEPLOY.md) - One-click cross-platform deployment (recommended)
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common install and runtime issues
- [MCP-CLIENTS.md](MCP-CLIENTS.md) - MCP client configuration
- [CONTRIBUTING.md](CONTRIBUTING.md) - Tests, lint, build, and release process
- [ARCHITECTURE.md](ARCHITECTURE.md) - Core abstractions and design
- [ORCHESTRATION-RUNBOOK.md](ORCHESTRATION-RUNBOOK.md) - Agent-facing orchestration protocol
- [skills/README.md](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

```bash
./deploy.sh
```

or directly with Python:

```bash
python3 deploy.py
```

### Windows

```powershell
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:

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

- [DEPLOY.md](DEPLOY.md) — dry-run mode, manual steps, Windows/macOS notes.
- [MCP-CLIENTS.md](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](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](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](https://github.com/obra/superpowers), Copyright © 2025 Jesse Vincent, MIT License.
