conductor — goal → ordered plan of capabilities

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Commands, APIs and runtime behavior described below are conditional examples for a compatible upstream installation; they are not evidence of execution in this package.

The router, generalised: not "which model tier?" but "given this goal, which capabilities, in which order, and what stays local?". The plan is the product — the upstream planning mode emits it without executing steps. Optional upstream execution modes require their own prerequisites and authority checks.

python -m skills.conductor.cli "test my desktop app and report crashes"
python -m skills.conductor.cli "reduce token cost and deploy on my project" --json

# Execute the plan (read-only steps run; mutating/cloud steps are gated):
python -m skills.conductor.cli "audit my project and report metrics" --execute
python -m skills.conductor.cli "..." --execute --dry-run      # preview, runs nothing
python -m skills.conductor.cli "..." --execute --confirm      # also run gated steps

How it plans

1. Curate — picks the capabilities relevant to the goal ([[capabilities]] curator, lexical matching).
2. Order — sorts them by the system's layers (SENSE → DECIDE → ACT → REMEMBER → GOVERN → DEPLOY): understand → decide → act → remember.
3. Annotate — each step gets a concrete command, a local/cloud flag, and the reason it's there.
4. Estimate — the goal's effort tier ([[auto-router]]) tells you whether any step's reasoning will escalate to the cloud.

Expected planning output is an ordered list of annotated steps. Check that the listed commands and capabilities exist in the installed runtime before attempting the plan.

Executing the plan

The plan can be run, not just read. The executor classifies every step:

• safe — read-only analysis (directives_audit, metrics, infra_advisor, checkup, cluster, llm_backends) → upstream read-only execution category.
• gated — mutates state, generates artifacts, or escalates to the cloud → runs only with --confirm / confirm=true.
• needs_args — the command still has an unfilled <placeholder> → never runs.

--dry-run classifies everything and runs nothing (a preview). A failing step yields a non-zero exit so CI can react. The runner is injectable, so the upstream implementation can be tested with a substituted runner. No such runtime test evidence is bundled here.

Exposed via [[llm-mcp]] as conduct (plan) and execute_plan (plan + run safe steps). Built on [[capabilities]], [[auto-router]]; pairs with the [[control-loop]] (measure savings → adapt the routing).

Each executor result also emits agent_state plus agent_state_history using the backend-neutral botte-agent-state-v1 contract. Safe work declares a read scope while queued/working; gated work declares a conservative write scope. Successful subprocesses become completed only after stable Git snapshots provide revision-bound changed paths and exit validation; incomplete captures remain idle.

Confirmed gated steps acquire one atomic mutation lease per Git root. An active Botte writer prevents launch and returns blocked_reason_code=conflict; safe read-only steps do not take the write lease.

A custom gated step may declare mutation_scopes: ["build", "generated"]. Those bounded paths are observed directly, including Git-ignored files. An unsafe or oversized scope blocks before launch or prevents a completed claim. A Git-visible write outside those scopes fails the step even if its command returns 0; scope_violations records the escaped paths without rolling them back. This includes ignored files: a bounded metadata guard observes all paths outside the declared scopes. If its initial evidence is incomplete, launch is blocked; if final evidence is incomplete, the executed step fails without a completion claim.

The default runner also reports process_containment. It uses a Windows Job Object or POSIX process group and closes that boundary before the final workspace snapshot, preventing ordinary descendants from writing after an apparent success. Injected test runners remain supported but are explicitly marked unverified. With --flow --task-run-id <id>, the flow reuses the router's opaque task ID and records a final efficiency verdict. Executed work is eligible for passed/failed only when native process containment is attached; injected or uncontained runners remain unverified.