Adaptive Work Routing

Adaptive Work Routing lets Snipara separate planning from execution. A strong planner model can keep the reasoning, risk, and context while a cheaper or local worker handles scoped implementation work such as documentation, tests, or bounded edits.

The Pattern

The useful case is not just lower inference cost. The useful case is putting the right worker behind the right work package while keeping Project Intelligence in control of why the work exists, what risk it carries, and what proof is needed.

Roadmap

Requirements, Not Model Lists

Snipara does not ask maintainers to keep a static list of model names up to date. The stable input is a requirement profile: worker role, reasoning level, context budget, cost target, endpoint preference, capabilities, write scope, and fallback.

"workerRole": "coding",

"reasoning": "low",

"plannerRetainsReasoning": true,

"cost": "minimal",

"writeScope": ["docs/**"],

"preferredEndpointTypes": ["local"],

"fallback": "main_agent"

Provider and model discovery belongs to runtime catalogs and project configuration. When a provider upgrades or exposes a new model, the resolver can see a new candidate without a Snipara code migration.

BYOM And Local LLMs

Project providers are configured as encrypted project-owned credentials. The agent sees only sanitized worker candidates: worker class, endpoint type, capabilities, cost hints, context budget, and allowed write scope. It never receives raw API keys, ciphertext, or private base URLs from the routing catalog.

• OpenAI, OpenRouter, Anthropic-compatible, or other OpenAI-compatible cloud gateways
• Ollama, LM Studio, AnythingLLM, or another local OpenAI-compatible endpoint
• Self-hosted or customer-hosted gateways reachable from the worker runtime

Local means reachable from the worker execution environment. If the worker runs on a developer machine, Ollama or LM Studio can be local. If the worker runs in a hosted backend, the local endpoint needs a bridge, tunnel, same-machine worker, or self-hosted gateway.

Project Automation Policy

Project owners can set Adaptive Work Routing under Project > Automation. The policy controls whether routing is off, recommendation-only, or backed by hosted catalog lookup. It also bounds allowed endpoint types, preferred local workers, worker classes, approval, planner-retained reasoning, and budget hints.

Companion reads that hosted policy during workflow run. CLI flags can request a dry run or local preference, but they cannot broaden the project policy. If the hosted catalog omits success: true, Companion treats it as a failed gateway signal and falls back to the main agent.

The catalog and resolver now expose an explicit policy decision: dry_run keeps execution on the main agent, approval_required requires an adaptive-routing-approval-v1 receipt, and auto_low_risk is only available for low-risk explicit handoffs with policy enablement, a candidate, and budget headroom. None of these modes silently spawn a worker.

Companion also exposes snipara-companion workers execute for Controlled Worker Execution V0. The command writes proof-required execution receipts, defaults to dry-run, requires an approval receipt for --execute, blocks high-risk commands, and marks successful worker output as verification_required until reviewed.

Orchestration Readiness

Adaptive routing becomes useful when the receiving work is a bounded package, not a vague request to spawn agents. Orchestration Readiness evaluates whether a delegated package has an owner, write scope, source context, acceptance criteria, proof requirements, evidence, an explicit handoff, approval when required, and live or reclaimable state.

Project Health now exposes this as an Orchestration Readiness lane. It reports work packages, ready and blocked packages, reclaimable work, missing owners, proof gaps, missing approvals, active conflicts, and sample-gated routes. A cold start is not hidden: if sessions or leases exist without explicit work packages, the lane says execution should stay advisory until the contract is real.

• No explicit work package keeps execution on the main agent.
• Missing owner, scope, context, or acceptance criteria requires review.
• Missing proof, approval, or external handoff blocks delegated completion.
• Timed-out or abandoned work must be reclaimed before another agent depends on it.
• Sample-gated routes remain recommendations until accepted outcomes clear the gate.

The model is intentionally fail-closed: Snipara owns the routing intelligence, proof contract, and continuity, while ADEs and worker runtimes execute through explicit handoffs. The readiness layer spawns 0 workers and falls back to main_agent whenever the contract is not strong enough.

Work Package Lifecycle keeps the same boundary and adds the closure trail. Each package can expose its lifecycle stage, proof state, handoff receipt state, approval state, outcome state, waiver count, receipt ids, and timestamps. Project Health can then separate work that is ready to delegate from work that is actually closed with proof and linked or explicitly missed outcome evidence.

Companion Engineering Lead Plan

Project Health now exposes an Engineering Lead Plan over the same signals. The plan reads Project Brain state, Orchestration Readiness, Proof Report evidence, repo risk, and calibration, then returns a lead posture, recommended worker roles, routing mode, bounded contract, proof gates, fallback, and candidate Project Brain updates.

The Engineering Lead contract adds a stable contractVersion, supervised workPackages, supervision state, and execution receipts. Receipts make handoff, claim, approval, proof, outcome, and Project Brain update requirements explicit per package. Unknown future status values fail closed with visible reason codes, so an imported plan cannot silently overstate readiness.

This is the first shipped step from Companion as an engineer toward Companion as an engineering lead. It is still advisory and fail-closed: the plan spawns 0 workers, keeps main_agent as fallback, and treats Brain updates as candidates until explicit handoff, proof, outcome, and Brain update receipts exist.

The local snipara-companion package exposes this as snipara-companion lead-plan. It can build a lead plan from workflow and Team Sync state plus explicit task, file, context, proof, and acceptance inputs, or normalize a Project Health cockpit JSON export with --from-cockpit or --from-plan. Use --reconcile to compare an imported lead plan against current workflow, Team Sync, proof, and scope signals before delegating.

snipara-orchestrator route --dry-run --lead-plan-file can consume the same contract and derive provider-neutral routing requirements from the selected supervised work package. snipara-orchestrator agents coordinate --lead-plan-file and agents check-receipt can dry-run receipt coordination and verify claim, approval, proof, outcome, and Brain-update evidence gates. They remain dry-run gates, not automatic worker launchers.

The open snipara-companion package can also run the recommendation path without Snipara SaaS from .snipara/adaptive-routing.json. In that local-only mode, Companion emits routing metadata and handoff files, but it does not call hosted context, hosted catalog, or planner APIs.

Companion Dry Run

Companion is the local UX surface. It can recommend routing, call the hosted catalog for sanitized worker candidates when project auth is configured, and write handoff metadata. It does not silently spawn workers.

snipara-companion workflow run \

--mode full \

--adaptive-routing-dry-run \

--route-local-workers \

--routing-worker-role coding \

--routing-preferred-endpoint local \

--planner-retains-reasoning \

"Document the new integration"

Receipts And Effectiveness

Worker completion is not judged by raw savings. HTask completion can include a routing receipt with actual cost, quality-adjusted cost, baseline cost, endpoint type, worker class, and outcome. Snipara records the raw sanitized receipt and aggregates project effectiveness by task type, worker class, and endpoint type.

Project Health uses quality-adjusted cost per accepted outcome. A route stays sample-gated until it has enough accepted outcomes to avoid overconfident routing.

Boundary

• Companion recommends, prints, and writes handoff metadata.
• Companion reconciles imported Engineering Lead plans before treating them as current.
• Orchestrator resolves provider-neutral requirements against runtime candidates.
• Orchestrator can route from a selected supervised work package in dry-run mode.
• The hosted gateway returns sanitized catalogs and keeps credentials server-side.
• Workers are explicit htask claims, handoffs, or external runtimes.
• Failure falls back to the main agent instead of guessing.

For the underlying orchestration package, see Snipara Orchestrator. For the local command surface, see snipara-companion.