English | 中文

Conductor is a context hygiene and interactive branch orchestration skill for long-running AI work. The protocol is tool-agnostic; this repository includes a Codex-compatible skill folder, a Claude Code-native plugin adapter, and one-shot prompts for Codex or Claude Code.

Conductor treats a long project like an orchestra. You and the master session stay at the podium with the score: the goal, constraints, decisions, and shape of the whole piece. The dispatch room decides which parts should play now and which must wait. Each branch takes its own part, the explainer sidecar becomes the rehearsal room for questions and false starts, and only the passages worth keeping are written back into the score.

It keeps the master session clean, cues interactive branch sessions for detailed work, reserves a dispatch session for session-planning debate, and keeps a deliberately dirty sidecar where users can ask all the questions that would otherwise poison the master context. Branch context only returns to the master session through a completion report and a user-approved merge.

Most AI workflows do not fail because the model cannot do the work. They fail because everything lands in one overloaded conversation:

• requirement interviews
• exploratory branches
• implementation details
• failed attempts
• long explanations
• review notes
• final process documentation

Even after workflows like Superpowers or grill-me, users may still not fully understand every part of their own project. That is normal. Conductor gives that uncertainty a dedicated place: a dirty explainer sidecar for deep questions, tutorials, and repeated clarification, while the master session stays useful as the project control room.

.
├── README.md
├── README.zh-CN.md
├── LICENSE
├── claude-code/
│   ├── .claude-plugin/plugin.json
│   ├── commands/
│   ├── hooks/
│   ├── scripts/
│   └── skills/conductor-cc/
├── docs/
│   ├── AI_INSTALL.zh.md
│   ├── DESIGN.zh.md
│   └── REVIEW_CHECKLIST.zh.md
├── examples/
│   ├── branch-map.md
│   ├── conductor.yaml
│   └── trellis-task-meta.json
├── prompts/
│   ├── install-with-claude-code.md
│   └── install-with-codex.md
├── scripts/
│   └── install.sh
└── skills/
    └── conductor/
        ├── SKILL.md
        ├── agents/openai.yaml
        └── references/
            ├── branch-brief-template.md
            ├── branch-map-template.md
            └── completion-report-template.md

Copy the skill folder into your Codex skills directory:

cp -R skills/conductor ~/.codex/skills/conductor

Or run the local installer from the repository root:

bash scripts/install.sh

Then start a new Codex session and invoke:

Use $conductor to keep this as the clean master session, create named branch cards before opening sessions, use CD-DISPATCH for routing debate, use CD-E01 as a context-rich dirty explainer, and merge only approved completion reports.

Claude Code users can use the native adapter under claude-code/. It ports Conductor into Claude Code slash commands and hooks, so the same protocol is enforced by the Claude Code harness:

claude plugin validate ./claude-code
claude --plugin-dir ./claude-code

Then, inside a project, run /cd-init to make the current Claude Code session the Conductor master.

You can also hand the installation to Codex or Claude Code with a one-shot prompt:

• Install with Codex
• Install with Claude Code

Paste the whole prompt into the target AI coding agent. The prompts already point to this repository.

Conductor follows a few hard rules:

1. The master session owns global context only.
2. Conductor creates visible branch cards before opening real sessions.
3. Every session must have a stable title, purpose card, expected output, and return condition.
4. Branch sessions are interactive threads, not one-shot background agents.
5. Branches receive only a brief, approved summaries, explicit file references, and messages inside their own thread.
6. Branches are not assumed parallel; Conductor plans dependency-aware waves before opening threads.
7. The dispatch session handles session-planning debate and returns only final routing decisions to the master.
8. Completion reports are generated only after the user confirms branch completion.
9. The master session merges only after explicit user approval.
10. Explainer branches default to no merge, even though the explainer may read across all session contexts on demand.
11. Branch-local global decisions must be confirmed in the master session.

Conductor uses stable titles so the thread list stays navigable. The initial open sessions should stay small: usually the clean master, the optional dispatch room, the dirty explainer, and the first user-confirmed branch.

[CD-MAIN][master] Project control room
[CD-DISPATCH][routing] Branch planning
[CD-E01][sidecar][explainer] Dirty questions
[CD-001][W1][task] First confirmed branch

Do not put mutable status such as active, done, or blocked in the title. Status belongs in the branch map and Today View.

Replace task and First confirmed branch with the actual role and purpose from the confirmed branch card. Later branches such as [CD-002][W1][review] Risk check or [CD-003][W2][implement] Prototype implementation should start as planned branch cards, not open sessions. A card becomes a session only after the user confirms the card, stable title, purpose, output, and return condition.

With Trellis, Conductor maps naturally onto parent and child tasks:

• parent/root task: master session
• dispatch session: sidecar routing thread, not a Trellis child task by default
• child task: interactive branch
• Codex / Claude Code thread: user-enterable conversation for the branch
• explainer sidecar: dirty context-rich explanation thread, not a Trellis child task by default
• branch-map.md: human-readable branch view
• task.json.meta.conductor: minimal machine-readable binding
• dependency fields: execution_wave, depends_on, unblocks, gate_condition

Conductor should prefer Trellis task scripts for parent/child relationships and should not use implement.jsonl or check.jsonl as a dumping ground for branch chat history.

Conductor is especially useful when paired with grill-me (or grill-me-docs) and Trellis:

Recommended flow:

1. Start with grill-me (or grill-me-docs) in the master session.
2. When multiple independent directions appear, enable Conductor.
3. If session planning becomes multi-turn, open [CD-DISPATCH][routing] Branch planning and keep routing debate out of the master session.
4. Run a dependency pass before opening threads: identify what can run now, what must wait, and what gate unlocks the next wave.
5. Create branch cards before creating real sessions.
6. Map the master session to a Trellis parent/root task.
7. Map current-wave interactive branches to Trellis child tasks and user-enterable AI coding threads.
8. Keep dependent branches as planned or blocked until their prerequisites are done.
9. Keep [CD-E01][sidecar][explainer] Dirty questions outside Trellis child tasks by default, but allow it to read relevant context across all sessions on demand.
10. Generate completion reports only after the user confirms a branch is done.
11. Merge only the approved compressed report back into the master session.

Copyable starter prompt:

Use $grill-me (or $grill-me-docs) first if the requirements are still unclear. Once the work splits into multiple directions, enable $conductor.

Treat this session as [CD-MAIN][master] Project control room. Keep only goals, constraints, the branch map, confirmed decisions, risks, snapshots, and approved summaries here.

Create branch cards before opening sessions. Each card must include stable title, purpose, allowed context, expected output, dependencies/wave, completion criteria, and return condition. Open only user-confirmed current-wave branches, with at most two active interactive branches; keep later branches planned or blocked.

Use stable names: [CD-DISPATCH][routing] Branch planning only when routing debate needs its own thread, [CD-E01][sidecar][explainer] Dirty questions as the single dirty explainer, and branch titles like [CD-001][W1][task] First confirmed branch with the real role and purpose substituted.

Run a dependency pass before opening branches. Branches are user-interactive and receive only their branch brief plus approved master context. The explainer may read relevant context across sessions for questions, but is non-authoritative and no-merge by default.

After I confirm a branch is complete, generate its completion report. Ask before merging; merge only my approved compressed summary into master. If I am using Trellis, persist the branch map, parent/child tasks, and task.json.meta.conductor fields without dumping raw chat into implement.jsonl or check.jsonl.

Initial public draft. Licensed under the MIT License.