
conductor-protocol
Multi-agent orchestration protocol for coordinating parallel Claude instances
- version
- 1.0.0
Install
/plugin install conductor-protocol@conductor-protocolRun it inside Claude Code after adding the marketplace with /plugin marketplace add MarioGiancini/conductor-protocol.
Contents
Discovered from sourceSkills 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:
- Each agent registers when starting a task
- Agents claim files before editing them
- A priority gate rejects misaligned work
- 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:
- Generates unique instance ID (e.g.,
itm-a1b2c3) - Checks priority against north-stars alignment
- Registers in
~/.conductor/status.json - 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:
- Checks if any file is already claimed
- If clear, adds files to your instance's
files_claimedarray - 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:
- Releases all file claims
- Logs task to
~/.conductor/history.jsonl - 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:
- Reads
north-stars.mdfrom digital-self - Reads current sprint priorities (if defined)
- 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:
- Run
/conductor statusto show active instances - Flag any orphaned instances (started >24h ago)
- Suggest cleanup if needed
With /shutdown
At session end, shutdown should:
- Run
/conductor doneto release this instance's claims - Log final status to history
With File Edits
When editing files, agents should:
- Check if file is claimed before editing
- If not claimed, claim it first
- If claimed by another, coordinate or wait
Priority Levels
| Level | Description | Examples |
|---|---|---|
| P1 | Critical, sprint-blocking | Revenue features, production bugs |
| P2 | Important, planned work | Backlog items, improvements |
| P3 | Nice-to-have, opportunistic | Refactoring, 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
- protocol.md - Detailed protocol specification
- schema.md - JSON schema definitions
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 taskstatus- Show all active instancesclaim path/to/file.ts [more files...]- Lock files before editingrelease [file] | --all- Release file claimsdone- Complete task and release all claimsalign "task description"- Check task against north-starsconflicts- Show active conflictscleanup- Remove orphaned instancesreset- 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":
-
Parse arguments:
- Task description (quoted string after "start")
--projectflag value--priorityflag value (P1, P2, or P3)--overrideflag value (optional justification)
-
Detect source environment:
- Check
$CURSOR_SESSIONfor Cursor - Check
$TERM_PROGRAMfor iTerm - Default to "web" if unknown
- Check
-
Generate instance ID:
source_prefix="itm" # or cur, vsc, web, cow random_suffix=$(openssl rand -hex 3) instance_id="${source_prefix}-${random_suffix}" -
Priority gate check:
- If priority is P1, pass automatically
- If priority is P2 or P3, check
~/.conductor/sprint.jsonif it exists - If sprint focus is P1 and task is lower priority, require
--override
-
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 -
Store instance ID for this session (for subsequent commands):
- Write to
~/.conductor/current_instance - Or announce it clearly so the agent remembers it
- Write to
-
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:
- Read ~/.conductor/status.json
- 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] │
└─────────────────────────────────────────────────────────────┘
- Calculate age from
started_atto now - Highlight any orphaned instances (heartbeat > 60 min ago)
Subcommand: claim
When $ARGUMENTS starts with "claim":
-
Get current instance ID from
~/.conductor/current_instanceor ask user -
Parse file paths from arguments
-
For each file:
- Check if in
global_claims - If claimed by another, report conflict
- If unclaimed, add to claims
- Check if in
-
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 -
Output:
- Success: "✅ Claimed: [files]. Safe to edit."
- Conflict: "⚠️ CONFLICT: [file] is claimed by [instance] ([task]). Coordinate or wait."
Subcommand: done
When $ARGUMENTS is "done":
-
Get current instance ID
-
Get list of files that were claimed
-
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 -
Append to history.jsonl:
echo '{"id":"'$instance_id'","project":"'$project'","task":"'$task'",...,"outcome":"success"}' >> ~/.conductor/history.jsonl -
Clear current_instance file
-
Output: "✅ Task complete. All claims released."
Subcommand: release
When $ARGUMENTS starts with "release":
- If
--all, release all files for current instance - Otherwise, release specific files listed
- Update status.json to remove from both instance's files_claimed and global_claims
- Output: "✅ Released: [files]"
Subcommand: align
When $ARGUMENTS starts with "align":
-
Parse task description
-
Read north-stars from
~/Developer/digital-self/2-areas/personal/north-stars.md -
Check alignment with:
- Priority hierarchy (Pitchello > LP > Self Engineer > Personal)
- Current quarterly goals
- Anti-goals (what we're NOT optimizing for)
-
Output assessment:
ALIGNMENT CHECK: "[task]" ✅ Aligns with: [north-star priority] ⚠️ Concern: [any misalignment] Recommendation: [proceed/defer/reconsider]
Subcommand: conflicts
When $ARGUMENTS is "conflicts":
- Scan global_claims for any issues
- Check for orphaned claims (instance gone but claims remain)
- Report any active conflicts
- Output detailed conflict information
Subcommand: cleanup
When $ARGUMENTS is "cleanup":
- Find instances with last_heartbeat > 60 minutes ago
- For each orphan:
- Release their claims
- Log to history with outcome "orphaned"
- Remove from status.json
- Output: "✅ Cleaned up [count] orphaned instances"
Subcommand: reset
When $ARGUMENTS is "reset":
- Backup current status.json to history
- Create fresh empty status.json
- Output: "✅ Status reset. Previous state backed up to history."
State File Location
All state lives in ~/.conductor/:
status.json- Current instance statehistory.jsonl- Completed task logcurrent_instance- This session's instance IDsprint.json- Optional sprint focus configuration
Error Handling
- If status.json is corrupted, offer to reset
- If instance ID not found, prompt to run
/conductor startfirst - If file claims fail, suggest
--forceoption 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