feat: Conductor Expert — opt-in knowledge base for Conductor-aware agents (#180)

[brrusino]

Summary

Implements Phase 1 of issue #180: bundles the existing plugin reference docs as package data and wires them into the instructions pipeline with an opt-in flag. This gives agents deep understanding of Conductor's YAML schema, execution model, authoring patterns, and CLI commands.

Changes

New: src/conductor/expert/ package

• loader.py — loads and caches (~70KB) bundled reference docs via importlib.resources + lru_cache, wraps in <conductor_knowledge> tags
• knowledge/ — bundled markdown reference docs (yaml-schema.md, authoring.md, execution.md)

Schema (config/schema.py)

• AgentDef.conductor_expert: bool | None — tri-state: None = inherit workflow default, True = force enable, False = force disable. Forbidden on script/workflow/human_gate agents.
• RuntimeConfig.conductor_expert: bool — workflow-wide default (False)

Executor (executor/agent.py)

• New _build_prompt_prefix() helper shared by execute() and render_prompt()
• New _should_inject_expert() — resolves tri-state agent flag vs workflow default

Engine (engine/workflow.py)

• Passes conductor_expert_default to AgentExecutor in both single-provider and multi-provider paths

Tests & Docs

• 25 new tests in tests/test_expert/ covering loader, schema validation, and executor integration
• Updated AGENTS.md with expert package documentation
• Added examples/conductor-expert.yaml example workflow

Closes #180 (Phase 1)

[brrusino]

🤖 Multi-Agent PR Review #1

PR: #1 — feat: Conductor Expert — opt-in knowledge base for Conductor-aware agents (#180)
Merge readiness: ⚠️ Needs minor fixes
Review confidence: 82/100 🟡 · reviewer agreement & finding strength — not a PR-quality score
Models: claude-opus-4.7 (Security & Correctness), gpt-5.5 (Robustness & Completeness)
Deliberation: 1 round, consensus reached

---

📋 Summary

Clean, well-scoped Phase 1 of the Conductor Expert feature. The tri-state opt-in resolution, shared prompt-prefix builder, and schema validation rejecting the flag on non-provider-backed agents are all implemented correctly, and test coverage hits the meaningful seams (loader caching, tag wrapping, tri-state, ordering, validator rejections). No security or correctness blockers — the knowledge content is static package data with no user-controlled paths.

The one item worth addressing before merge is that the bundled knowledge docs the feature is supposed to teach agents from are now stale: they don't document the new runtime.conductor_expert field or the per-agent override, so expert-enabled agents could flag valid workflows or omit the flag when generating examples. Remaining items (packaging robustness for the bundled .md files, error handling in the loader) are weak-consensus polish — non-blocking.

🔍 Consensus Findings

Severity	File	Finding	Recommendation
🟡 warning	src/conductor/expert/knowledge/yaml-schema.md:29-38, 150-154	Bundled knowledge docs don't document the new workflow.runtime.conductor_expert field or per-agent tri-state override. Expert-enabled agents may flag valid workflows as having unknown fields or omit the flag when generating examples.	Update yaml-schema.md and authoring.md (and execution.md if it covers prompt construction) to cover the runtime default, per-agent tri-state semantics, prompt ordering, and the provider-backed-only restriction.
🔵 suggestion	src/conductor/expert/loader.py:2508-2517	load_expert_knowledge() calls resource.read_text(...) with no error handling. A missing/corrupted doc surfaces as a raw FileNotFoundError/UnicodeDecodeError from inside agent execution, and because lru_cache doesn't cache exceptions, every expert-enabled agent will repeatedly re-attempt the failing read.	Wrap reads in try/except for FileNotFoundError/OSError/UnicodeDecodeError and raise a project-specific error with reinstall guidance.
🔵 suggestion	pyproject.toml:64-68	src/conductor/expert/knowledge/*.md is loaded via importlib.resources. Hatchling defaults include the files today, but no test exercises the loader against an installed wheel — a future build-config change could silently drop the docs.	Declare an explicit Hatchling artifacts rule for the knowledge .md files, or add a wheel-install smoke test.
🔵 suggestion	src/conductor/config/schema.py:159-178	Both reviewers converged: strict rejection of conductor_expert (including false) on script/human_gate/workflow agent types is the intended design — surfaces author confusion early and matches reasoning/retry handling.	No change required.

💡 Suggested fix for R2-001 (stale knowledge docs)

     max_agent_iterations: integer   # Max tool-use roundtrips per agent (1-500, optional)
     max_session_seconds: float      # Wall-clock timeout per agent session in seconds (optional)
     default_reasoning_effort: string # Workflow-wide reasoning/thinking effort: low, medium, high, xhigh (optional)
+    conductor_expert: boolean       # Inject bundled Conductor knowledge into provider-backed agents (default: false)
     mcp_servers:                    # MCP server configurations

💡 Suggested fix for R1-002 (loader error handling)

-        text = resource.read_text(encoding="utf-8").strip()
+        try:
+            text = resource.read_text(encoding="utf-8").strip()
+        except (FileNotFoundError, OSError, UnicodeDecodeError) as e:
+            raise RuntimeError(
+                f"Conductor Expert knowledge file '{name}' is missing or unreadable. "
+                "This usually indicates a broken install; try reinstalling conductor."
+            ) from e

💡 Suggested fix for R1-001 (explicit packaging artifacts)

 [tool.hatch.build.targets.wheel]
 packages = ["src/conductor"]
+artifacts = ["src/conductor/expert/knowledge/*.md"]
 exclude = [
     "src/conductor/web/frontend",
 ]

🔎 Unique / Disputed Findings

None — all findings reached consensus in round 1.

📊 Model Comparison

Aspect	Reviewer 1 (claude-opus-4.7)	Reviewer 2 (gpt-5.5)
Merge Readiness	✅ Ready to merge	⚠️ Needs minor fixes
Critical findings	0	0
Warnings	0	1
Suggestions	3	0
Total findings	3	1

🏁 Verdict

Reviewers agree on the substance: no blockers, one warning worth addressing (stale bundled knowledge docs), and a few polish suggestions. Updating the bundled yaml-schema.md / authoring.md to document the new conductor_expert field is the only change that meaningfully affects the feature's value, since expert-enabled agents will be reading those docs.

Merge readiness: ⚠️ Needs minor fixes — update bundled knowledge docs to cover the new conductor_expert field before merge; loader error handling and explicit packaging artifacts are non-blocking polish.
Review confidence: 82/100 🟡 · reviewer agreement & finding strength — not a PR-quality score

[brrusino]

Inline finding

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@04b46ec). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #215   +/-   ##
=======================================
  Coverage        ?   88.27%           
=======================================
  Files           ?       62           
  Lines           ?     9700           
  Branches        ?        0           
=======================================
  Hits            ?     8563           
  Misses          ?     1137           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.