| name | conductor |
| description | Use when a complex task needs dependency-aware interactive branches, subagents, or AI coding threads while keeping the master session context clean through explicit branch briefs, completion reports, wave planning, and user-approved merges. Especially useful with grill-me, Trellis, research, implementation, writing, and planning workflows that risk context pollution. |
Conductor
Purpose
conductor is a context isolation and branch registry protocol. It keeps one master session clean while messy exploration, implementation, research, review, or learning happens in separate user-interactive branch sessions.
Use it to decide whether a request belongs in the master session, an interactive branch, an explainer sidecar, or a merge flow. It does not replace Trellis executors or other workflow agents; it governs how branches are created, tracked, completed, and optionally merged.
Core Rules
- The master session owns the project overview: goal, constraints, branch map, global decisions, approved summaries, risks, and next steps.
- Use session registry first. Create visible branch cards before creating real sessions.
- Do not create a new session until the user confirms the branch card and its stable session title.
- Every session must have a stable ID, stable title, purpose card, expected output, and return condition.
- Never put mutable status such as
active, done, or blocked in the session title. Status belongs in the branch map or Today View.
- Branch sessions are user-interactive threads, not one-shot background workers.
- A branch receives only a branch brief, approved summaries, explicit file references, and messages inside that branch.
- The master session must not read or absorb raw branch history by default.
- A completion report is generated only after the user confirms the branch is complete.
- The master session only edits and merges branch context after the user explicitly chooses to merge that completed branch.
- Explainer branches are pollution zones for learning and long explanations. They default to no merge.
- The explainer sidecar may read across all session contexts for explanation, but its output is non-authoritative and never merges by default.
- Decisions made inside a branch are not globally binding until confirmed in the master session.
- Do not assume all branches can run in parallel. Always run a dependency pass before opening branches.
Session Types And Names
Use exactly these session types:
| Type | Stable title pattern | Purpose | Default merge behavior |
|---|
master | [CD-MAIN][master] <project> | Project control room: global goals, branch map, confirmed decisions, risks, approved summaries | Source of truth |
dispatch | [CD-DISPATCH][routing] Branch planning | Discuss whether to open sessions, whether work is parallel or serial, dependency waves, and session cards | Merge only final dispatch decisions |
branch | [CD-001][W1][task] First confirmed branch | User-interactive work session for one bounded task | Report generated after user-confirmed completion; merge only after explicit user approval |
explainer | [CD-E01][sidecar][explainer] Dirty questions | Dirty learning session for questions, tutorials, and cross-session explanation | No merge by default |
Rules:
- Session titles must start with the Conductor ID.
- Session titles must include role and wave when relevant.
- Session titles must be short enough to identify in a thread list.
- Do not create multiple explainer sessions. Use one fixed explainer per project.
- Do not create multiple dispatch sessions. Use one fixed dispatch session per project.
- Prefer at most 2 active interactive branch sessions, plus the optional dispatch session and fixed explainer sidecar.
Session Registry First
Conductor creates branch cards before sessions. A branch card must include:
- ID and stable session title
- type and role
- one-sentence purpose
- why it exists
- dependency/wave placement
- allowed context
- expected artifact
- completion criteria
- return condition
- whether it should open now, stay planned, or stay blocked
Only after the user confirms the card should Conductor create or bind a real session. When entering a branch, the first visible content must be a Purpose Card:
You are branch CD-001: First confirmed branch
Purpose: do the first bounded task the user confirmed
Not for: unscoped work outside the branch card
Input: master snapshot snap-xxx; approved summaries only
Output: completion-report.md
Return to master when: branch output is ready and the user confirms completion
After creating, blocking, completing, merging, parking, or archiving a session, refresh a compact Today View in the master session:
Active now:
- CD-001 First confirmed branch — task — waiting for user review
- CD-E01 Dirty questions — sidecar explainer
Planned, not opened:
- CD-002 Implementation plan — waits for CD-001
Merge pending:
- none
Routing
Whenever this skill is active, route each new request before acting:
- Keep in master session if it changes global goals, scope, constraints, priorities, branch structure, merge decisions, or project snapshots.
- Use the dispatch session if the conversation is mainly about whether to open sessions, whether tasks are parallel or serial, dependency order, wave planning, or branch-card design.
- Create or use an interactive branch if the work is exploratory, implementation-heavy, research-heavy, review-heavy, or likely to produce many intermediate details.
- Send to the explainer sidecar if the user wants long-form explanation, background learning, conceptual clarification, or tutorial-style help.
- Enter merge flow only after a branch is user-confirmed complete.
Keep this routing lightweight. Do not turn every message into process ceremony.
Dispatch Session
Do not open the dispatch session by default. Suggest opening [CD-DISPATCH][routing] Branch planning when:
- branch planning takes more than 2-3 turns
- there are more than 3 candidate branch cards
- dependency order is unclear
- the user asks whether work should be parallel or serial
- session proliferation is starting to make the project hard to navigate
The dispatch session is isolated from the master session. It may discuss:
- which sessions should exist
- which branches should be planned, opened, parked, blocked, or archived
- which work can run in parallel and which must be serial
- branch titles, roles, expected outputs, and completion criteria
- active-session budget
The dispatch session must not do implementation, research, review, or long-form explanation. It must not read raw branch histories by default. It returns only a compact dispatch decision to the master session, for example:
Dispatch decision:
- Open CD-001 and CD-E01 now.
- Keep CD-002 planned until CD-001 completion report is ready.
- Do not open implementation branch yet.
Dependency Pass And Wave Plan
Before creating or opening branches, identify execution order. Many branches depend on outputs from earlier branches and must remain planned or blocked until their prerequisites are done.
Classify each proposed branch:
ready_parallel: can start now from the current master snapshot without waiting on another branch.dependent: needs a specific branch output, decision, artifact, or user confirmation first.gate: a review, merge, or master-session decision required before the next wave can start.optional: useful but not on the critical path.explainer: can run as a sidecar unless the user explicitly makes it blocking.
Output a compact wave plan before creating threads:
| Wave | Branches | Prerequisites | Gate to unlock next wave |
|---|
| 0 | master decisions | none | user confirms scope |
| 1 | branches that can run now | current snapshot | completion reports reviewed |
| 2 | dependent branches | Wave 1 outputs | merge or user decision |
Rules:
- Only branches in the current unlocked wave should become active by default.
- Later-wave branches may be recorded as
planned; mark them blocked if the user tries to start them before prerequisites are met.
- Parallel means "safe to run from the same snapshot without needing each other's outputs", not merely "different topics".
- If dependencies are ambiguous, ask the user to confirm the order before creating branch threads.
- After a wave completes, update the snapshot, note what it unlocks, and then propose the next wave.
Branch State Machine
Use these stable states:
| State | Meaning | Typical next step |
|---|
planned | Suggested by master, not confirmed | create brief or cancel |
brief_ready | Branch brief exists, thread not created | create thread or revise brief |
active | User can enter and interact | block, park, or suggest completion |
blocked | Waiting on master, user, external input, or another branch | resume or cancel |
completion_suggested | Branch thinks it may be done | user confirms completion or continues |
report_ready | User confirmed completion and report exists | request merge or archive |
merge_pending | Master asks whether to merge report | merge, reject, or defer |
merged | Master wrote approved compressed record | archive |
rejected | User chose not to merge | archive |
archived | Hidden from active view | reopen |
Default active interactive branch limit: 2. The fixed explainer sidecar and optional dispatch session do not count as interactive branches. If creating a third active branch, suggest parking, completing, or archiving an existing branch first.
Creating Branches
Create branches only after user confirmation. First show:
- stable session title
- proposed branch title and role
- why it should be a branch
- whether it is in the current wave or waiting on prerequisites
- dependencies, unblocks, and gate condition
- expected artifact
- completion criteria
- whether it needs a Trellis child task, an AI coding thread, or both
Create only current-wave branches by default. Do not create all planned branch threads at once unless the user explicitly requests that.
After confirmation, write a branch brief using references/branch-brief-template.md. If thread tools are available, create or bind an AI coding thread, set the thread title to the stable session title when possible, and give it only the branch brief as the initial prompt. Record the returned thread_id; a Codex deep link such as codex://threads/<thread-id> is optional when using Codex and is not the source of truth.
If thread creation is unavailable, create the brief and ask the user to start a separate session with it.
Completion And Merge
A branch may suggest completion, but only the user can confirm it. After confirmation, generate a completion report using references/completion-report-template.md.
The master session then asks whether to merge:
- Merge: read the completion report, compress it, normalize terminology, and add a short approved record to the master context.
- Reject: record that the branch completed but was not merged.
- Defer: leave the branch in
merge_pending.
Do not read raw branch history unless the user explicitly asks to debug or audit that branch. The default merge input is completion-report.md, especially its Suggested Merge Note.
Explainer Sidecar
Use one explainer thread per project. It is for questions that would heavily pollute context: tutorials, long derivations, conceptual gaps, background knowledge, and repeated clarification.
The explainer is context-rich but non-authoritative. It may read across all session contexts to answer user questions, but should load only the relevant context for the current question and should label source authority:
- L0: master snapshot, branch map, Today View - confirmed
- L1: branch cards and branch briefs - intended scope
- L2: completion reports and approved summaries - reviewed outputs
- L3: raw branch histories - branch-local and unconfirmed; read only when the user explicitly asks
- L4: explainer history - dirty learning context
Do not create a Trellis child task for the explainer by default. Represent it as a sidecar in the branch map. Only promote explainer output if the user strongly requests it and the content becomes a project decision, constraint, terminology definition, or spec/task update. Even then, merge as a very short project knowledge item, not as teaching material.
Global Decisions
If a branch discussion creates or implies a decision affecting other branches, architecture, scope, naming, deadlines, acceptance criteria, or project goals, the branch must record it as a proposed global decision. It is not binding until the master session confirms it.
Completion reports should include proposed global decisions with:
- decision
- affected scope
- why it matters
- affected branches
- recommended master-session action
Snapshots And Staleness
The master session should create short snapshots after major events: branch creation, branch completion, merge, archival, and confirmed global decisions.
Each branch brief should record:
based_on_snapshot_idbrief_version- creation date
- parent task or root branch
When the master snapshot changes in a way that affects an active branch, mark that branch stale and ask whether to refresh its brief. Do not silently sync hidden context.
Trellis Best Practice
With Trellis, map conductor like this:
- master session: parent/root task
- dispatch session: sidecar AI coding thread for branch planning; not a Trellis child task by default
- interactive branch: Trellis child task plus a user-enterable AI coding thread
- explainer: sidecar AI coding thread, not a Trellis child task by default
- branch map: parent task
branch-map.md
- machine binding:
task.json.meta.conductor
Prefer Trellis scripts such as task.py create --parent or task.py add-subtask for parent/child relationships. Do not manually edit parent or children unless Trellis scripts are unavailable or fail.
Use task.json.meta.conductor only for small machine-readable fields:
{
"conductor": {
"branch_id": "CD-001",
"branch_type": "branch",
"interaction_mode": "user_interactive",
"role": "research",
"parent_branch_id": "CD-MAIN",
"thread_id": "thr_xxx",
"branch_brief_path": ".trellis/tasks/example/branch-brief.md",
"completion_report_path": ".trellis/tasks/example/completion-report.md",
"status": "active",
"brief_version": 1,
"based_on_snapshot_id": "snap-2026-06-03-001",
"execution_wave": 1,
"depends_on": [],
"unblocks": ["CD-002"],
"start_policy": "current_wave_only",
"gate_condition": "completion_report_ready",
"merge_policy": "explicit_user_confirm"
}
}
Do not add branch briefs, completion reports, or raw conversation summaries to implement.jsonl or check.jsonl by default. Those files are for Trellis execution/check context and should be touched only when the user confirms the branch artifact must become implementation or check context.
Non-Trellis Fallback
If Trellis is not available, maintain:
conductor.yaml as the machine-readable registrybranch-map.md as the human-readable snapshot- Mermaid inside
branch-map.md for visualization
Use references/branch-map-template.md when creating or refreshing the map.
When To Stop And Summarize
When the user asks for a Trellis-ready summary or before implementation begins, provide:
- goal and non-goals
- user flow
- routing rules
- branch states
- Trellis mapping or fallback registry
- acceptance criteria
- risks
- open questions
