Wayfinder: Open-source skill-aware Agent fleet control plane

[2233admin]

Destination

Produce a reviewed, handoff-ready specification for an open-source Agent control plane: a replaceable primary controller that coordinates a bounded, skill-aware Agent fleet with recursive delegation, snapshot-bound project understanding, evidence arbitration, policy envelopes, cache reuse, and recoverable long tasks. The map ends when the remaining decisions are clear enough for to-spec, to-tickets, and implementation.

Notes

• Domain: Code Intel Pipeline and its Agent-facing control plane.
• Task authority: this GitHub issue map; repository code, contracts, tests, ADRs, and artifacts remain the technical authority.
• Consult every session: CONTEXT.md, active decision records, agent-orchestrator, code-intel-pipeline, domain-modeling, and skill-creator.
• Standing constraints: the primary controller arbitrates policy and evidence; workers execute inside delegation contracts; high-risk conflicts freeze only the affected branch; stale cache is acceleration, never authority; routine autonomy uses a task-level policy envelope.
• Existing project constraints: Project Understanding Loop and the local-first Task/Friction control plane are already recorded in the repository decision records.

Decisions so far

• Decision: Delegation contract and skill-use attestation #268 — Delegation contract and skill-use attestation (resolved 2026-08-15): Every child Agent attempt starts from an immutable, versioned Delegation Contract issued by the replaceable Primary Controller. It binds task/attempt lineage, goal and acceptance, Snapshot Identity and Artifact Refs, versioned Skill/Tool grants, effects, model/resource/recursion limits, and stop/pause/escalation rules. Runtime/tool adapters emit ordered attestations for observable skill activation/tool invocation; the Controller promotes only results whose required evidence and attestations verify. Undeclared capabilities pause for a chained contract extension; cache reuse may satisfy admissible evidence requirements but is not fresh skill/tool use. See DR-0007 and the glossary in CONTEXT.md.

Not yet specified

• The durable controller state shape and cross-machine handoff protocol.
• The exact delegation-contract and skill/tool-use evidence contracts.
• Fleet scheduling, leases, workspace isolation, merge ownership, and recovery semantics.
• Model-tier routing, weak-model fallback, recursive depth budgets, and cache admission.
• Policy-envelope limits for mutation, network, model/API cost, and human escalation.
• Replay, observability, failure classification, and takeover behavior.

Out of scope

• Computer Use or UI automation as the first control-plane capability.
• Training new models or adding general model capabilities.
• Replacing the Code Intel evidence kernel.
• Public beta/release, pricing changes, or external publication.

[2233admin]

Proposed extension: local skill-aware dispatch fallback

This requirement should extend the existing assistance.discovery proposal atom rather than bypass its evidence/authority boundary.

User outcome

When the project's preferred tools or the upstream assistance catalog are absent, Code Intel should be able to build a useful dispatch plan from the user's locally installed skills and local usage context. If repository evidence reveals a missing step during execution, the controller may select an available local skill automatically when the route is high-confidence, low-risk, and already covered by the task policy envelope.

Suggested capability boundary

Add a assistance.local-dispatch (or equivalent) capability with an optional local capability adapter:

1. Discover active local registries through explicit, read-only adapters (Codex/Claude-compatible skill directories, skills ls output, and MCM catalog when present). Do not assume one vendor or one filesystem layout.
2. Normalize each entry into a capability record: stable id, name, source, active/archived/conflicted state, path, description, tags/triggers, declared effects, prerequisites, verification command, and provenance.
3. Combine the normalized inventory with the current task contract, project snapshot/AGENTS evidence, Code Intel gap evidence, and soft usage preferences. Usage frequency may rank equivalent candidates, but must never authorize an otherwise unsafe route.
4. Emit an explainable dispatch plan: selected skill/capability, companion steps, confidence, evidence refs, missing capabilities, blocked candidates, expected effects, and verification plan. Preserve provenance for every decision.
5. Keep three outcomes distinct: proposal (show the plan), auto_route (invoke an already available low-risk skill inside the granted envelope), and decision_required (ask for authority). Unknown skills are never auto-installed; network, mutation, model/API cost, and external messaging remain explicit effects.
6. If a selected skill reports a gap during execution, feed that gap back through the same resolver and emit a new attestation/decision record. Do not silently recurse without depth, cost, and stop limits.

Contract and safety requirements

• Local discovery is optional and must degrade cleanly to the reviewed repository catalog.
• The local registry is evidence about availability, not an authority grant.
• Local history is a soft preference only; support an opt-out/denylist and never persist raw conversation content as a routing profile.
• Exclude archived, disabled, duplicate, and unresolved same-name entries unless an explicit compatibility policy selects one.
• A local skill invocation must produce ordered skill/tool-use attestation and post-route verification evidence, so the controller can reject unverified results.
• Add fixtures for: no local registry, mixed Codex/Claude/MCM registries, duplicate names, archived-only candidates, low-confidence matches, high-confidence low-risk auto-route, and a missing capability that requires a decision.

This is deliberately a control-plane extension, not an Agent launcher and not a replacement for the Code Intel evidence kernel. It lets Code Intel adapt to a user's available tools without making the user's local setup a hidden dependency.

Implementation note: the repository currently has 6 open PRs, above DR-0005's integration-debt ceiling. This comment records the reviewed scope for #267; implementation should start after the queue is reduced or under an explicitly approved exception.