🎵 Conductor

local-first file protocol + verification CLI for multi-agent project state

Structured handoff · Protocol verification · Recoverable project state

English · 中文

---

Protocol-Compatible AI Coding Tools

⌨️ CLI	Claude Code reads AGENTS.md	Codex CLI reads AGENTS.md	Gemini CLI via projection	Kimi Code file-based
🖥️ IDE	Cursor file-aware	Windsurf file-aware	Antigravity file-aware	GitHub Copilot file-aware
	Aider file-based	OpenCode file-based	Continue file-aware	+ any tool that reads/writes files

Compatibility means the tool can read and write the repository files Conductor standardizes. Conductor does not start, host, or control these tools; any AI coding tool that can read and write files is compatible.

---

What Conductor Core Is

Conductor Core is a local-first file protocol + verification CLI for multi-agent project state.

It standardizes local project records, SOP files, verification gates, handoff state, run/usage/review summaries, adapter metadata, and read-only projections over project health.

It does not launch agents, control terminals, route model traffic, collect credentials, run durable workflows, provide hosted SaaS, or replace desktop multi-agent workspaces. Tools such as terminal workspaces, model gateways, workflow engines, and coding-agent runtimes should integrate through adapters and redacted summaries instead.

See ADR 0001 and the agent infrastructure competitive map for the detailed build-vs-integrate boundary.

---

The Problem

You're running Claude Code in one terminal, Cursor in another, maybe Codex for review — all on different projects. By end of day:

• 🤯 You can't remember what each agent decided
• 🔁 New sessions repeat mistakes from yesterday
• 📂 HANDOFF notes, devlogs, and error logs are scattered everywhere
• 🤔 You don't know which agent to trust for which task

Conductor makes that project state explicit, recoverable, and checkable in your repository.

What's Inside

📖 Methodology — The 12 Dimensions of Human-Agent Interaction

We identified 12 dimensions that matter when a human works with multiple AI agents:

#	Dimension	What It Covers
1	Handoff Management	Passing context between sessions without loss
2	Knowledge Capture	Recording decisions, errors, and QA pairs
3	Trust Calibration	Knowing when to verify vs. trust the agent
4	Cognitive Load	Managing your mental bandwidth across agents
5	Prompt Quality	Improving how you communicate with agents
6	Agent Profiling	Tracking each agent's strengths and weaknesses
7	Tool Selection	Picking the right agent for the right task
8	Feedback Loops	Turning errors into prevention rules
9	Attention Allocation	Deciding which project needs you right now
10	Disagreement Resolution	Handling conflicting agent advice
11	Cross-Agent Consistency	Keeping agents aligned on decisions
12	Energy Modeling	Adjusting oversight based on your fatigue

Read more: docs/

📁 Templates — Copy, paste, done

Template	Purpose
HANDOFF.md	Session-end context handoff
CLAUDE.md	Agent rules with handoff protocol
ERROR_BOOK.md	AI mistake tracker for trust calibration
TRUST_PROFILE.md	Agent reliability scorecard
DESIGN.md	UI design system for consistent agent output

🧰 CLI — See all your projects at a glance

$ conductor status

🎵 Conductor · Project Status
┌─────────────┬────────────┬────────┬──────────────────────┐
│ Project     │ Last Active│ Status │ Next Step            │
├─────────────┼────────────┼────────┼──────────────────────┤
│ wenyuan     │ 6h ago     │ ✅     │ Refactor README      │
│ network-opt │ 2h ago     │ ✅     │ VPS setup            │
│ conductor   │ 30m ago    │ ✅     │ Write tests          │
│ old-project │ 3d ago     │ 🔴     │ Archive or continue? │
└─────────────┴────────────┴────────┴──────────────────────┘
 📅 2026-04-09 │ 4 projects │ 5 decisions │ 12 files Δ

$ conductor digest ./my-project

🎵 Conductor · Project Digest
  📁 my-project  │  📅 2026-04-01 → 2026-04-09  │  🔄 5 sessions

  📋 Decisions Made
  ┌────────────┬──────────────────────────────┐
  │ 2026-04-09 │ Chose JWT over sessions      │
  │ 2026-04-08 │ Python 3.9+ compatibility    │
  └────────────┴──────────────────────────────┘

  ⚠️ Errors & Pitfalls
  ┌────────────┬──────────────────────────────┐
  │ 2026-04-09 │ bcrypt 5.x broke hashes      │
  └────────────┴──────────────────────────────┘

$ conductor memory add "Uses FastAPI + PostgreSQL" -t fact -g backend
✅ Memory #1 added (fact)

$ conductor memory search "FastAPI"
🔍 matches: #1 [fact] Uses FastAPI + PostgreSQL

$ conductor verify .
Verification passed: /path/to/project

$ conductor verify --json . | python -m json.tool
{
  "project_path": "/path/to/project",
  "ok": true,
  "errors": [],
  "warnings": []
}

Command Reference

Command	Purpose
conductor status --dir <path>	Multi-project status dashboard
conductor init [path]	Scaffold the v1.0 file/SOP protocol files
conductor digest [path]	Extract decisions and errors from project history
conductor retro [path]	Run interactive agent retrospective
conductor memory ...	Persistent cross-session knowledge store
conductor workspace ...	Manage a local workspace registry across projects; registry commands do not edit project protocol files
conductor demo control-plane	Print local read-only protocol demo commands and safety boundaries
conductor verify [path]	Validate the Conductor file and SOP protocol
conductor verify --json [path]	Emit a machine-readable verification report for automation/CI
conductor orbit ...	Inspect Orbit dispatch files (print-only)

Preview / Bounded Capability Labels

Capability	Label	Honest boundary
Daemon worker	[preview/bounded]	runs at most two bounded cycles, not a resident daemon
Agent adapters	[preview]	generates launch command previews; never executes them
Queue / runtime records	[preview/bounded]	disabled by default; schema reserved

Local Control Plane Demo

The current usable protocol and projection path is local, CLI-first, and read-only. It does not require a frontend or backend service.

Start with the daily operator overview from the local control plane quickstart. For machine-readable status, use existing JSON-capable CLI projections such as conductor operator overview --project . --json; this is the main automation path, not the local HTML dashboard.

conductor operator overview --project .
conductor operator overview --project . --json | python -m json.tool

Example JSON output excerpt from this repository:

{
  "schema_version": 1,
  "mode": "read-only operator overview",
  "project": {
    "scope": "current_project",
    "project_path_included": false,
    "private_registry_inspected": false
  },
  "approval_evidence": {
    "blocked_gate_count": 0,
    "records_total": 0,
    "status": "empty"
  }
}

Then drill down into approval evidence, queue/lease evidence, peer adapter fixtures, and the workspace snapshot. The read-only peer adapter fixture panel is available through the existing CLI preview:

conductor demo control-plane
conductor preview approvals --project .
conductor preview queue-leases --project .
conductor preview peer-adapters --project .
conductor workspace snapshot --registry <workspaces.yaml>

The conductor dashboard HTML server is an [experimental] local read-only HTML preview. It is not the primary CLI or machine-readable path.

Quick Start

Option A: Just use the templates (no install needed)

1. Copy templates/HANDOFF.md.template to your project as HANDOFF.md
2. Copy the handoff protocol from templates/CLAUDE.md.template into your project's CLAUDE.md
3. Tell your AI: "Read HANDOFF.md before starting. Update it before ending."

Option B: Install the CLI from this checkout

Run from the Conductor repository root. This is the RA-6 onboarding acceptance path validated on 2026-06-11.

CONDUCTOR_REPO="$(pwd)"
ONBOARDING_DIR="$(mktemp -d)"
python3 -m venv "$ONBOARDING_DIR/.venv"
"$ONBOARDING_DIR/.venv/bin/python" -m pip install -e "$CONDUCTOR_REPO"
mkdir "$ONBOARDING_DIR/my-project"
cd "$ONBOARDING_DIR"
.venv/bin/conductor init ./my-project
.venv/bin/conductor verify ./my-project
.venv/bin/conductor status --dir .
.venv/bin/conductor digest ./my-project

For existing projects, see the v1.0 migration guide.

Core Concepts

The Handoff Protocol

Every session ends with a structured handoff:

## 2026-04-09
- done: Implemented user auth module
- decisions: Chose JWT over sessions (stateless, scales better)
- pitfall: bcrypt 5.x changed default rounds — broke existing hashes
- next: Add password reset flow

500 token max. If you can't summarize it, you don't understand it.

→ Full protocol

Trust Calibration

Don't blindly trust or distrust your AI. Calibrate per domain:

Layer	Method
L1	Verify outcomes — does the code run?
L2	Cross-verify — have another agent review
L3	Progressive trust — try on one file first
L4	Demand explanation — ask WHY, not just WHAT

→ Full framework

Task Sizing (S/M/L)

Not every task needs a full planning cycle:

Size	Time	Process
S	< 30min	Just do it → test → commit → HANDOFF
M	1-3h	Brief plan → execute → HANDOFF
L	> 3h	Brainstorm → plan → TDD → review → HANDOFF

→ Full guide

Why Conductor?

vs.	Difference
CrewAI / LangGraph	They run agent-to-agent workflows. Conductor keeps multi-agent project state recoverable in files.
OpenSpec	OpenSpec manages specs within one session. Conductor verifies cross-session project state.
CLAUDE.md alone	CLAUDE.md is one file. We're a complete methodology + tools.
Nothing	You're losing decisions, repeating mistakes, and burning context window tokens.

Roadmap

• v0.1 — Methodology docs + templates + conductor status
• v0.2 — conductor digest — extract decisions/errors from project history
• v0.3 — conductor retro — interactive post-session agent review
• v0.4 — conductor memory — persistent cross-session knowledge store
• v0.5 — File and SOP foundation: BACKLOG.md, DEVLOG.md, normalized HANDOFF.md, CONTEXT.md, .conductor/config.yaml, .conductor/sops/*.yaml, AGENTS.md + projected CLAUDE.md
• v0.6 — conductor verify [path] — read-only validator for the v0.5 protocol
• v0.7 — conductor verify --json [path] + GitHub Actions verify workflow for CI use
• v0.8 — Release hygiene and push readiness (complete locally; see CHANGELOG.md)
• v0.9 — Read-only repair suggestions in conductor verify
• v0.10 — Real Orbit task dogfooding
• v0.11 — Supervised development-loop runbook
• v1.0 — Stable protocol slice, verify JSON schema, v1.0 init scaffolding, migration guide, dogfood, and local release gate (local-first/protocol slice pushed to main; tag, release, and publication still require explicit approval)

Full plan: docs/archive/plans/2026-05-22-conductor-roadmap-v0.8-v1.0.md.

What's New in v0.5-v0.11

Conductor v0.5-v0.11 turn the methodology into a checkable file protocol and local verification loop so multiple AI coding agents can read the same project state without re-explaining it.

v0.5 — File and SOP foundation

• Adds BACKLOG.md (task pool with fenced YAML metadata), DEVLOG.md (append-only execution history), normalized HANDOFF.md (current recovery state only), and CONTEXT.md (stable background).
• Adds .conductor/config.yaml with paths, sensitive-file globs, agent declarations, and instruction-target projections.
• Adds five default SOP files under .conductor/sops/: simple, tdd, spec-first, research-spike, review-fix.
• Adds AGENTS.md as the canonical agent instruction entrypoint, with managed-block projections into CLAUDE.md (and optional GEMINI.md / Copilot instructions).
• File-only release: no agent execution, no daemon, no event stream.
• Schema reference: docs/conductor-schema.md.
• Design doc: docs/archive/plans/v0.5-file-and-sop-foundation.md.

v0.6 — conductor verify

A read-only validator that checks a Conductor project against the v0.5 file protocol. It validates:

• Required files exist (BACKLOG.md, DEVLOG.md, HANDOFF.md, CONTEXT.md, AGENTS.md, .conductor/config.yaml, the five SOPs).
• .conductor/config.yaml and SOP YAML files parse and follow the documented schema.
• SOPs encode their distinguishing requirements (failing test, plan/spec artifact, cited feedback, etc.).
• BACKLOG.md tasks have valid ids and metadata.
• HANDOFF.md has the current-state headings.
• DEVLOG.md entries have the expected shape.
• AGENTS.md references the read-before-work artifacts.
• CLAUDE.md (and other projected instruction files) contain valid managed-block markers.

conductor verify .
# Verification passed: /path/to/project

Exits non-zero when validation errors exist.

v0.7 — Automation readiness

• conductor verify --json [path] emits a machine-readable verification report so CI and other automations can consume the result without scraping terminal output.
• .github/workflows/verify.yml runs install, pytest, human-readable verify, and JSON verify on pull requests and pushes to main. No publishing, no agent execution, no secrets.

conductor verify --json . | python -m json.tool

v0.8 — Release hygiene and push readiness

• Public docs, release notes, and the push-readiness checklist documented the v0.5-v0.7 protocol work and its manual push gate.
• docs/push-readiness.md records the tracked-file sensitive scan, workflow review, verification commands, and manual gate.
• Package version is now 0.5.0; protocol milestones are not automatic PyPI releases.

v0.9 — Verify repair suggestions

• conductor verify issues now include deterministic read-only repair suggestions in human and JSON output.
• Suggestions do not modify files automatically and preserve existing issue codes and exit-code behavior.

v0.10 — Real Orbit task dogfooding

• The real Orbit dispatch file was dogfooded with TASK-20260523-001, a local Conductor push-readiness audit task.
• conductor orbit status, conductor orbit next, and conductor orbit launch <task_id> were verified against that task.
• orbit launch remains print-only; the printed command is not executed by Conductor.

v0.11 — Supervised development-loop runbook

• docs/runbooks/development-loop.md defines the local supervisor/worker recordkeeping workflow.
• Current role split: Codex App supervises/reviews/integrates, Codex CLI implements one bounded milestone at a time, and Claude Code is review-only for milestone gates.
• The runbook preserves local-first boundaries: no daemon, no hosted service, no automatic executor, and no automatic push.

Recommended worker / reviewer workflow

For feature implementation against this Conductor protocol project the current split is:

• Codex App as supervisor, reviewer, and integrator — selects one approved milestone, reviews worker output, reruns verification independently, and records integration state.
• Codex CLI as implementation worker — reads AGENTS.md, HANDOFF.md, CONTEXT.md, BACKLOG.md, .conductor/config.yaml, and the selected SOP; works in an isolated worktree; implements exactly one bounded milestone; commits and stops.
• Claude Code as review-only gate — reviews the just-completed milestone and reports accepted/rejected with findings, verification evidence, and residual risk. It is not the default implementation worker.

See AGENTS.md for the full protocol.

v1.0 Local Release Gate

The v1.0 local-first/protocol slice has been pushed to main. It includes the stable protocol document, verify JSON schema, v1.0 conductor init scaffolding, migration guide, clean-project dogfood, and the local release gate.

Tag, release, and publication remain separate manual gates: they may happen only after explicit user approval or a standing policy recorded in project state.

Release & Push Readiness

The local-first/protocol slice has been pushed to main; this does not imply a tag, package release, publication, or public launch.

• Release notes for those milestones live in CHANGELOG.md.
• The release-gate checklist (sensitive-file scan, verification commands, manual confirmation) lives in docs/push-readiness.md.
• Quick sensitive-file scan against tracked files:

git ls-tree -r --name-only HEAD | grep -E "(\.env|secret|token|key)" && echo "REVIEW REQUIRED" || echo "clean"

Future pushes, tags, releases, publications, and public PRs remain manual steps that must happen only after the checklist passes and after explicit user confirmation, unless a standing policy is explicitly recorded in project state. Automations must not mutate remote or public release state on their own.

Philosophy

"If you just drive the AI to work and walk away, you'll never know what you don't know. The original sin of AI-assisted development is not reviewing, not reflecting, not improving."

Conductor is built on three principles:

1. Structure over ceremony — Lightweight protocols that actually get followed, not heavy processes that get skipped.
2. Observe, then trust — Build trust through data (error books, trust profiles), not assumptions.
3. The human improves too — It's not just about making AI better. It's about making you better at working with AI.

Contributing

Contributions welcome! Please read the methodology docs first to understand the philosophy.

License

MIT