Feature: Conductor Expert — reusable, version-accurate knowledge base for Conductor-aware agents

[brrusino]

Summary

Proposal for a built-in, auto-generated knowledge base that gives any agent deep understanding of Conductor's YAML schema, execution model, routing patterns, and best practices. Agents opt into this knowledge — it's a reusable capability, not a standalone agent.

Problem

Conductor agents know nothing about Conductor itself. When an agent needs to evaluate, improve, debug, or generate workflow YAML, it's flying blind — it doesn't know what fields are valid, what patterns work, or how the engine actually executes a workflow.

Today, the only workaround is manually copying documentation into system prompts. This is:

• Manual — every workflow author who needs Conductor-aware agents has to do it themselves

• Stale — the docs go out of date the moment a schema field is added or behavior changes

• Inconsistent — different authors include different subsets of knowledge, with varying accuracy

Proposal

A bundled knowledge base, generated from source

The Conductor Expert is a structured knowledge document generated from Conductor's own source code:

• Schema reference — every YAML field, type, default, and constraint, derived from the Pydantic models in config/schema.py. When a field is added to the schema, it automatically appears in the knowledge base.

• Execution model — how the engine works: the main loop, context accumulation, parallel execution, route evaluation, checkpoint/resume. Derived from the engine implementation.

• Patterns & best practices — loop-back reviews, parallel validation, for-each batching, context mode selection, common anti-patterns. Curated from examples and AGENTS.md.

• Working examples — actual workflow YAML from Conductor's examples directory, conditionally included when relevant.

Because it's generated from the running version's source, it's always accurate. No version mismatch, no hallucinated fields.

Opt-in, not injected

The knowledge base is opt-in via three mechanisms:

Per-agent:

agents:

  - name: workflow_reviewer

    conductor_expert: true

    prompt: "Review this workflow for correctness..."

Workflow-level:

workflow:

  runtime:

    conductor_expert: true  # All agents get Conductor knowledge

Automatic for built-in features:

Commands like conductor watch (#181) automatically enable it for their evaluator agents — no user configuration needed.

Plugs into existing instructions system

Conductor already has a well-designed instructions injection pipeline (config/instructions.py) that discovers workspace files, loads YAML instruction entries, and accepts CLI --instructions paths. The Conductor Expert knowledge base is an additional source in this same pipeline — it composes with workspace instructions rather than replacing them.

Why this matters

For conductor watch (#181)

conductor watch (#181) wraps existing workflows with an external validation loop. Watch's evaluator agent needs to understand Conductor deeply to suggest meaningful workflow improvements. Without Conductor knowledge, the agent can only guess at what to change. With it, the agent can:

• Identify suboptimal routing patterns

• Detect context mode mismatches

• Suggest appropriate failure modes for parallel/for-each groups

• Validate output schemas match downstream expectations

For future features

The same knowledge base enables:

• Workflow scaffolding — generate valid YAML from natural language descriptions

• Workflow debugging — diagnose failures from symptoms (route conditions that never match, context references that resolve to None)

• Community workflows — agents in shared registry workflows can understand and adapt to Conductor idioms

For the open-source community

This creates a compelling advantage: Conductor would be one of the few (if any) multi-agent orchestrators where agents can be natively fluent in the orchestrator itself. It's self-aware tooling — and it gets better automatically with every release because the knowledge base regenerates from source.

Relationship to existing proposals

Companion to conductor watch (#181)

This is a companion feature to conductor watch (#181). Watch is the first consumer of the Conductor Expert in workflow wrapper mode — its evaluator agent needs deep Conductor knowledge to suggest meaningful workflow improvements. The Expert is independently useful and designed for reuse.

Foundation layer for #135 — Conductor developer toolkit

Issue #135 proposes an authoring skill kit (starter scaffolds, validation helpers, debug tools) and an MCP server for log/state introspection. The Conductor Expert is a natural foundation layer for that work:

• Skill kit authoring agents would be more effective with Expert knowledge — an agent generating a scaffold workflow needs to understand valid schema, available patterns, and best practices to produce correct YAML

• Validation skills in Feature: Conductor developer toolkit — authoring skill kit + MCP server for log/state introspection #135 overlap with Expert's schema-aware validation — the Expert provides the knowledge that validation skills act on. They compose rather than compete

• The MCP server proposed in Feature: Conductor developer toolkit — authoring skill kit + MCP server for log/state introspection #135 aligns with Phase 3 of the Expert (interactive knowledge via MCP). Introspection tools (log querying, state inspection, plan tree traversal) complement the Expert's static knowledge with runtime observability — these could share the same MCP server surface

The Expert fills a gap that #135 implicitly assumes but doesn't address: where does the Conductor-specific knowledge come from? The skill kit provides tools and building blocks. The Expert provides the understanding to use them well.

Integration point already exists

The existing instructions injection pipeline (config/instructions.py → AgentExecutor.instructions_preamble) is the natural hook. The Expert adds a new source to this pipeline alongside auto-discovered workspace files, YAML instructions, and CLI --instructions paths. No architectural changes to the engine needed.

Phased approach

Phase 1 — Static knowledge base: Hand-curate a conductor_expert.md covering schema, execution model, and key patterns. Bundle as package data. Wire into the instructions preamble with an opt-in flag.

Phase 2 — Generated knowledge base: Build-time generator that introspects Pydantic models programmatically. Auto-select relevant examples based on workflow patterns. Layer selection and token budget controls.

Phase 3 — Interactive knowledge (MCP): An MCP server exposing Conductor knowledge as queryable tools (schema lookup, pattern search, validation). Lower token cost — agents ask targeted questions rather than receiving the full knowledge base upfront.

Open questions

• Token budget — The full knowledge base could be large. Should there be layer selection (schema only, schema + execution_model, all) or a token cap?

• Generation timing — Build-time (bundled with package) vs runtime (generated on first use)? Build-time is simpler and ensures consistency.

• Field name — conductor_expert: true on agents, or something more general like knowledge: [conductor] that could extend to other knowledge packs in the future?

---

I have a detailed vision doc covering architecture, integration points, token budget strategies, and all four knowledge layers. Happy to share.