Skill: multi-service-orchestrator

Purpose

Transform the Ralph agent into a "Conductor Agent" that can manage and coordinate work across multiple services in a microservices or monorepo architecture.

When to Use

•When the project consists of multiple services (e.g., api, web, worker, admin).
•When a change in one service requires coordinated changes in others (e.g., updating a shared API contract).

How It Works

Step 1: Define the Service Manifest

Create a services.json file in the project root:

json

{
  "services": [
    {
      "name": "api",
      "path": "./services/api",
      "prd": "./services/api/prd.json",
      "claude_md": "./services/api/CLAUDE.md",
      "contracts": ["./contracts/api.openapi.yaml"]
    },
    {
      "name": "web",
      "path": "./services/web",
      "prd": "./services/web/prd.json",
      "claude_md": "./services/web/CLAUDE.md",
      "depends_on": ["api"]
    },
    {
      "name": "worker",
      "path": "./services/worker",
      "prd": "./services/worker/prd.json",
      "claude_md": "./services/worker/CLAUDE.md",
      "depends_on": ["api"]
    }
  ],
  "contracts_dir": "./contracts"
}

Step 2: Build the Dependency Graph

The Conductor Agent reads services.json and builds a dependency graph:

code

api (root)
├── web (depends on api)
└── worker (depends on api)

Step 3: Detect Cross-Service Impact

When a user story modifies a shared contract (e.g., api.openapi.yaml), the Conductor:

•Identifies all services that depend on the contract.
•Creates linked user stories in the PRDs of those services.

Example:

If US-010 in api/prd.json adds a new field to the /users endpoint:

json

// api/prd.json
{
  "id": "US-010",
  "title": "Add 'role' field to /users endpoint"
}

The Conductor automatically adds:

json

// web/prd.json
{
  "id": "US-010-WEB",
  "title": "[Linked] Update web app to display user role",
  "linkedTo": "api/US-010",
  "passes": false
}

// worker/prd.json
{
  "id": "US-010-WORKER",
  "title": "[Linked] Update worker to handle user role in notifications",
  "linkedTo": "api/US-010",
  "passes": false
}

Step 4: Fan-Out / Fan-In Execution

The Conductor orchestrates the execution:

•Fan-Out: Spawn a Ralph sub-agent for each affected service.
•Parallel Execution: Each sub-agent works on its linked story independently.
•Fan-In: Wait for all sub-agents to complete their verification gates.
•Cross-Service Testing: Run end-to-end tests that span multiple services.
•Commit: If all tests pass, commit changes across all services.

bash

# Pseudocode for Conductor
for service in affected_services:
    spawn_subagent(service.prd, service.claude_md)

wait_for_all_subagents()

run_e2e_tests()

if e2e_tests_pass:
    commit_all_changes()
else:
    rollback_all_changes()

Step 5: Distributed Testing

The Conductor can run end-to-end tests that span multiple services:

bash

# Start all services
docker-compose up -d

# Run e2e tests
npm run test:e2e

# Tear down
docker-compose down

Configuration

Add the following to your root CLAUDE.md:

markdown

## Multi-Service Orchestrator

- **Service Manifest**: `services.json`
- **Contracts Directory**: `./contracts`
- **E2E Test Command**: `npm run test:e2e`
- **Parallel Sub-Agents**: Enabled