Multi-agent orchestration protocol for coordinating parallel Claude instances

version
1.0.0

Install

/plugin install conductor-protocol@conductor-protocol

Run it inside Claude Code after adding the marketplace with /plugin marketplace add MarioGiancini/conductor-protocol.

Contents

Discovered from source

Skills 1

Conductor: Multi-Agent Orchestration Protocol

Conductor coordinates multiple Claude Code instances working in parallel. It prevents conflicts, enforces strategic alignment, and provides visibility into what each agent is doing.

Quick Reference

/conductor start "task description" --project name --priority P1|P2|P3
/conductor status                    # Show all active instances
/conductor claim path/to/file.ts     # Lock files before editing
/conductor release                   # Release your file claims
/conductor done                      # Mark task complete, release all claims
/conductor align                     # Check task against north-stars
/conductor conflicts                 # Show any active conflicts

Core Concepts

The Problem

When running 3-5+ Claude instances simultaneously:

  • Conflicting changes: Two agents edit the same file
  • Strategic drift: Agents work on low-priority tasks
  • Lost visibility: No idea what each instance is doing
  • Wasted effort: Duplicate work or incompatible changes

The Solution

A lightweight coordination protocol where:

  1. Each agent registers when starting a task
  2. Agents claim files before editing them
  3. A priority gate rejects misaligned work
  4. A status dashboard shows all activity

How It Works

Status File Location

Global coordination state lives at:

~/.conductor/
├── status.json      # Current state of all instances
├── history.jsonl    # Completed tasks log
└── conflicts.log    # Conflict history for learning

Instance Lifecycle

┌─────────────────────────────────────────────────────────────┐
│                    INSTANCE LIFECYCLE                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   /conductor start "Fix auth bug" --project pitchello      │
│          │                                                  │
│          ▼                                                  │
│   ┌─────────────────┐                                       │
│   │ Priority Check  │──Fail──▶ ⚠️ Drift warning            │
│   │ (vs north-stars)│         (require override)            │
│   └────────┬────────┘                                       │
│            │ Pass                                           │
│            ▼                                                │
│   ┌─────────────────┐                                       │
│   │ Register in     │                                       │
│   │ status.json     │                                       │
│   └────────┬────────┘                                       │
│            │                                                │
│            ▼                                                │
│   /conductor claim src/auth.ts src/lib/session.ts          │
│          │                                                  │
│          ▼                                                  │
│   ┌─────────────────┐                                       │
│   │ Conflict Check  │──Conflict──▶ ⚠️ File locked          │
│   └────────┬────────┘              (coordinate)             │
│            │ Clear                                          │
│            ▼                                                │
│   ✅ Work on task (files are claimed)                      │
│            │                                                │
│            ▼                                                │
│   /conductor done                                           │
│          │                                                  │
│          ▼                                                  │
│   ┌─────────────────┐                                       │
│   │ Release claims  │                                       │
│   │ Log to history  │                                       │
│   │ Remove from     │                                       │
│   │ status.json     │                                       │
│   └─────────────────┘                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Commands Detail

/conductor start

Register a new task with the conductor.

/conductor start "Implement user authentication" --project pitchello --priority P1

What it does:

  1. Generates unique instance ID (e.g., itm-a1b2c3)
  2. Checks priority against north-stars alignment
  3. Registers in ~/.conductor/status.json
  4. Returns instance ID for reference

Flags:

  • --project (required): Project name (pitchello, mission-control, digital-self, etc.)
  • --priority (required): P1 (critical), P2 (important), P3 (nice-to-have)
  • --override (optional): Skip priority gate with justification

/conductor claim

Lock files before editing to prevent conflicts.

/conductor claim src/api/users.ts src/lib/auth.ts

What it does:

  1. Checks if any file is already claimed
  2. If clear, adds files to your instance's files_claimed array
  3. If conflict, shows who has the file and suggests coordination

Best practice: Claim files at the start of work, not mid-task.

/conductor status

Show dashboard of all active instances.

/conductor status

Output:

┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR STATUS - 2026-01-17 10:30                         │
├─────────────────────────────────────────────────────────────┤
│ ACTIVE INSTANCES (3)                                        │
├─────────────────────────────────────────────────────────────┤
│ [itm-a1b2] pitchello       │ P1 │ Fix auth bug      │ 45m  │
│            └─ src/api/users.ts, src/lib/auth.ts             │
│                                                             │
│ [itm-c3d4] mission-control │ P1 │ Lead scoring API  │ 30m  │
│            └─ app/api/agent/leads/*                         │
│                                                             │
│ [cur-e5f6] digital-self    │ P2 │ Content draft     │ 15m  │
│            └─ (no files claimed)                            │
├─────────────────────────────────────────────────────────────┤
│ CONFLICTS: None                                             │
│ DRIFT WARNINGS: 1 (cur-e5f6 working on P2 during P1 sprint) │
└─────────────────────────────────────────────────────────────┘

/conductor done

Complete your task and release all claims.

/conductor done

What it does:

  1. Releases all file claims
  2. Logs task to ~/.conductor/history.jsonl
  3. Removes instance from status.json

/conductor align

Check if your current/proposed task aligns with strategic priorities.

/conductor align "Add dark mode to settings"

What it does:

  1. Reads north-stars.md from digital-self
  2. Reads current sprint priorities (if defined)
  3. Returns alignment assessment

/conductor release

Release file claims without completing the task (e.g., when switching focus).

/conductor release src/api/users.ts
# or release all
/conductor release --all

/conductor conflicts

Show detailed conflict information.

/conductor conflicts

Integration Points

With /daily-brief

At session start, daily-brief should:

  1. Run /conductor status to show active instances
  2. Flag any orphaned instances (started >24h ago)
  3. Suggest cleanup if needed

With /shutdown

At session end, shutdown should:

  1. Run /conductor done to release this instance's claims
  2. Log final status to history

With File Edits

When editing files, agents should:

  1. Check if file is claimed before editing
  2. If not claimed, claim it first
  3. If claimed by another, coordinate or wait

Priority Levels

LevelDescriptionExamples
P1Critical, sprint-blockingRevenue features, production bugs
P2Important, planned workBacklog items, improvements
P3Nice-to-have, opportunisticRefactoring, documentation

Priority Gate Rule: During focused sprints, P3 work requires explicit override.

When to Use Conductor

Always use when:

  • Running 2+ Claude instances simultaneously
  • Working on shared codebases
  • Tasks that will modify files

Skip when:

  • Single instance, simple task
  • Read-only research/exploration
  • Content creation (no file conflicts possible)

Troubleshooting

Orphaned Instances

If an instance crashed without /conductor done:

/conductor cleanup --instance itm-a1b2c3

Stale Claims

If files are claimed but instance is gone:

/conductor release --force src/api/users.ts

Manual Status Reset

If status.json is corrupted:

/conductor reset

(Backs up current state to history, creates fresh status.json)

See Also

Commands 1

/conductor Command

Coordinate multiple Claude instances to prevent conflicts and maintain strategic alignment.

Subcommands

Parse $ARGUMENTS to determine which subcommand to run:

  • start "task" --project name --priority P1|P2|P3 - Register a new task
  • status - Show all active instances
  • claim path/to/file.ts [more files...] - Lock files before editing
  • release [file] | --all - Release file claims
  • done - Complete task and release all claims
  • align "task description" - Check task against north-stars
  • conflicts - Show active conflicts
  • cleanup - Remove orphaned instances
  • reset - Reset status file (backup current state first)

Setup Check

First, ensure the conductor directory and files exist:

# Check if status.json exists
if [[ ! -f ~/.conductor/status.json ]]; then
  # Create initial empty state
  echo '{
  "version": "1.0",
  "updated_at": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
  "instances": [],
  "global_claims": {},
  "drift_warnings": []
}' > ~/.conductor/status.json
fi

Subcommand: start

When $ARGUMENTS starts with "start":

  1. Parse arguments:

    • Task description (quoted string after "start")
    • --project flag value
    • --priority flag value (P1, P2, or P3)
    • --override flag value (optional justification)
  2. Detect source environment:

    • Check $CURSOR_SESSION for Cursor
    • Check $TERM_PROGRAM for iTerm
    • Default to "web" if unknown
  3. Generate instance ID:

    source_prefix="itm"  # or cur, vsc, web, cow
    random_suffix=$(openssl rand -hex 3)
    instance_id="${source_prefix}-${random_suffix}"
    
  4. Priority gate check:

    • If priority is P1, pass automatically
    • If priority is P2 or P3, check ~/.conductor/sprint.json if it exists
    • If sprint focus is P1 and task is lower priority, require --override
  5. Add instance to status.json using jq:

    jq --arg id "$instance_id" \
       --arg source "$source" \
       --arg project "$project" \
       --arg task "$task" \
       --arg priority "$priority" \
       --arg started "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
       --arg heartbeat "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
       --arg workdir "$(pwd)" \
       '.instances += [{
         id: $id,
         source: $source,
         project: $project,
         task: $task,
         priority: $priority,
         files_claimed: [],
         started_at: $started,
         last_heartbeat: $heartbeat,
         working_directory: $workdir
       }] | .updated_at = $heartbeat' ~/.conductor/status.json > ~/.conductor/status.json.tmp \
       && mv ~/.conductor/status.json.tmp ~/.conductor/status.json
    
  6. Store instance ID for this session (for subsequent commands):

    • Write to ~/.conductor/current_instance
    • Or announce it clearly so the agent remembers it
  7. Output:

    ✅ Registered as [instance_id]
    Project: [project]
    Task: [task]
    Priority: [priority]
    
    Next: Use `/conductor claim <files>` to lock files before editing.
    

Subcommand: status

When $ARGUMENTS is "status" or empty:

  1. Read ~/.conductor/status.json
  2. Format as dashboard:
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR STATUS - [timestamp]                              │
├─────────────────────────────────────────────────────────────┤
│ ACTIVE INSTANCES ([count])                                  │
├─────────────────────────────────────────────────────────────┤
│ [id] [project]      │ [priority] │ [task]          │ [age] │
│      └─ [claimed files list]                                │
│                                                             │
│ [repeat for each instance]                                  │
├─────────────────────────────────────────────────────────────┤
│ CONFLICTS: [count or "None"]                                │
│ DRIFT WARNINGS: [count with details]                        │
└─────────────────────────────────────────────────────────────┘
  1. Calculate age from started_at to now
  2. Highlight any orphaned instances (heartbeat > 60 min ago)

Subcommand: claim

When $ARGUMENTS starts with "claim":

  1. Get current instance ID from ~/.conductor/current_instance or ask user

  2. Parse file paths from arguments

  3. For each file:

    • Check if in global_claims
    • If claimed by another, report conflict
    • If unclaimed, add to claims
  4. Update status.json:

    jq --arg id "$instance_id" \
       --arg file "$filepath" \
       '.instances |= map(if .id == $id then .files_claimed += [$file] else . end)
        | .global_claims[$file] = $id
        | .updated_at = (now | todate)' ~/.conductor/status.json
    
  5. Output:

    • Success: "✅ Claimed: [files]. Safe to edit."
    • Conflict: "⚠️ CONFLICT: [file] is claimed by [instance] ([task]). Coordinate or wait."

Subcommand: done

When $ARGUMENTS is "done":

  1. Get current instance ID

  2. Get list of files that were claimed

  3. Remove instance from status.json:

    jq --arg id "$instance_id" \
       'del(.instances[] | select(.id == $id))
        | .global_claims |= with_entries(select(.value != $id))
        | .updated_at = (now | todate)' ~/.conductor/status.json
    
  4. Append to history.jsonl:

    echo '{"id":"'$instance_id'","project":"'$project'","task":"'$task'",...,"outcome":"success"}' >> ~/.conductor/history.jsonl
    
  5. Clear current_instance file

  6. Output: "✅ Task complete. All claims released."

Subcommand: release

When $ARGUMENTS starts with "release":

  1. If --all, release all files for current instance
  2. Otherwise, release specific files listed
  3. Update status.json to remove from both instance's files_claimed and global_claims
  4. Output: "✅ Released: [files]"

Subcommand: align

When $ARGUMENTS starts with "align":

  1. Parse task description

  2. Read north-stars from ~/Developer/digital-self/2-areas/personal/north-stars.md

  3. Check alignment with:

    • Priority hierarchy (Pitchello > LP > Self Engineer > Personal)
    • Current quarterly goals
    • Anti-goals (what we're NOT optimizing for)
  4. Output assessment:

    ALIGNMENT CHECK: "[task]"
    
    ✅ Aligns with: [north-star priority]
    ⚠️ Concern: [any misalignment]
    
    Recommendation: [proceed/defer/reconsider]
    

Subcommand: conflicts

When $ARGUMENTS is "conflicts":

  1. Scan global_claims for any issues
  2. Check for orphaned claims (instance gone but claims remain)
  3. Report any active conflicts
  4. Output detailed conflict information

Subcommand: cleanup

When $ARGUMENTS is "cleanup":

  1. Find instances with last_heartbeat > 60 minutes ago
  2. For each orphan:
    • Release their claims
    • Log to history with outcome "orphaned"
    • Remove from status.json
  3. Output: "✅ Cleaned up [count] orphaned instances"

Subcommand: reset

When $ARGUMENTS is "reset":

  1. Backup current status.json to history
  2. Create fresh empty status.json
  3. Output: "✅ Status reset. Previous state backed up to history."

State File Location

All state lives in ~/.conductor/:

  • status.json - Current instance state
  • history.jsonl - Completed task log
  • current_instance - This session's instance ID
  • sprint.json - Optional sprint focus configuration

Error Handling

  • If status.json is corrupted, offer to reset
  • If instance ID not found, prompt to run /conductor start first
  • If file claims fail, suggest --force option for human override

See Also

Read the full skill documentation at ~/.claude/skills/conductor/SKILL.md for:

  • Complete protocol specification
  • JSON schemas
  • Integration patterns

Sponsors

Details

Marketplace
MarioGiancini/conductor-protocol
Author
Mario Giancini
Category
Productivity
Keywords
orchestration, multi-agent, coordination, parallel