operator-surface-authority-designer

name	operator-surface-authority-designer
description	Decide which single operator surface — Scout, FleetBar, or pd-console — owns each capability by its distance-from-work (intake/ambient/deep), and audit that placement for authority spread, unenforceable controls, evidence overflow into FleetBar, and hot/cool bus-subscription mismatches. Use when placing a new capability on one of Agent Harbor's three operator surfaces, reconciling a mockup that duplicates a capability across two surfaces, or auditing an existing operator-surface spec before implementation locks it in. NOT for choosing SDK/CLI/MCP/GUI surfaces for API-consuming developers (developer-surface-strategist), designing the concrete interaction flow within one already-assigned surface (agentic-coding-ux-designer), or the hot-bus/cool-bus transport mechanics themselves (swarm-invocation-designer).
license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"category":"Agent & Orchestration","tags":["operator-surfaces","authority-model","fleetbar","pd-console","human-gate"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"swarm-invocation-designer","reason":"Builds the hot-bus/cool-bus transport mechanics behind the busSubscription category this skill assigns."},{"skill":"human-gate-designer","reason":"Designs the actual approval UX for a human-gate capability once this skill places it on FleetBar."},{"skill":"agentic-coding-ux-designer","reason":"Designs the concrete interaction flow within a surface once this skill has decided which surface owns the capability."}],"io-contract":{"kind":"deliverable","consumes":[{"kind":"operator-surface-design-brief","format":"markdown"},{"kind":"surface-authority-spec","format":"json"}],"produces":[{"kind":"surface-authority-decision","format":"markdown"},{"kind":"surface-authority-audit-report","format":"json"}]}}

Operator Surface Authority Designer

Decide which one of Scout, FleetBar, or pd-console owns a capability — by distance-from-work, not by which surface was fastest to build it in.

Use This For

• Placing a new capability on Scout, FleetBar, or pd-console when speccing Agent Harbor's operator triad.
• Reconciling a mockup or prototype that built the same affordance on two surfaces before either was canonical.
• Deciding whether a capability's evidence weight means it belongs on pd-console instead of FleetBar's popover.
• Choosing a capability's hot-bus vs. cool-bus subscription so it matches its declared distance.
• Auditing an existing operator-surface spec for authority spread, ungated controls, or a surface quietly owning runtime state before implementation locks it in.

Do Not Use This For

• Choosing SDK/CLI/MCP/GUI/API/webhook surfaces for developers who consume the product programmatically (developer-surface-strategist).
• Designing the concrete interaction flow, copy, or motion within one already-assigned surface (agentic-coding-ux-designer).
• Implementing the hot-bus/cool-bus transport itself — the multiplexed WebSocket, message envelopes, latency budgets (swarm-invocation-designer).

Distance-Based Authority Model

flowchart TD
  A[New or disputed capability] --> B{What is its distance from the work?}
  B -->|inside the artifact, at observation| C[intake -> Scout]
  B -->|ambient, glanceable, consent-only| D[ambient -> FleetBar]
  B -->|seated, full-evidence inspection| E[deep -> pd-console]
  C --> F{Evidence screens > 1?}
  D --> F
  E --> F
  F -->|yes, and surface is FleetBar| G[Move to pd-console; FleetBar deep-links instead]
  F -->|no| H{Daemon can enforce every rendered control?}
  G --> H
  H -->|no| I[Do not ship the control yet]
  H -->|yes| J{Bus subscription matches distance?}
  J -->|intake/deep must be cool, ambient may mix| K[Fix subscription or reclassify distance]
  J -->|matches| L[Run scripts/surface_authority_audit.mjs]
  K --> L
  L -->|pass: true| M[Ship: exactly one owner, enforceable, no owned runtime state]

1. Classify the capability's distance. Is the operator acting at the point of observation (intake), glancing at ambient status or granting consent (ambient), or seated doing deep inspection (deep)? See references/distance-based-authority-model.md.
2. Assign the one canonical surface for that distance. intake → Scout, ambient → FleetBar, deep → pd-console. Never let a capability claim two surfaces, and never leave one with no valid surface at all.
3. Weigh the evidence. If a capability needs more than one screen of evidence to evaluate, it does not belong on FleetBar regardless of its distance label — move it to pd-console and leave a deep link.
4. Check daemon enforceability. A surface may render a control only if the daemon can actually back the decision it represents (acceptance criterion 6). If the daemon can't enforce it yet, the control doesn't ship yet either.
5. Pick the bus subscription. intake and deep capabilities subscribe to the cool bus (Work Intents and transcript events are cool-bus objects); ambient capabilities may legitimately mix hot and cool. See references/hot-bus-cool-bus-subscription-contract.md.
6. Confirm no surface owns runtime state. Every surface renders daemon truth and submits commands through the same envelopes — a locally-cached, treated-as-authoritative slice of state on any surface is a defect, not a performance optimization.
7. Confirm adapter boundaries. Native surfaces do not shell out to CLI or MCP internally. Scout, FleetBar, pd-console, CLI, and MCP all enter through the shared daemon contract / Surface Gateway path; CLI and MCP are automation adapters, not hidden implementation dependencies for the operator surfaces.
8. Audit before you build, and again before you ship. Run scripts/surface_authority_audit.mjs against the spec at design time, and again against the shipped reality.

Output Contract

Produce a capability authority table plus a machine-checkable audit:

• capabilities[]: name, assignedSurface (scout/fleetbar/pd-console), distance (intake/ambient/deep), evidenceScreens, daemonEnforceable, busSubscription (hot/cool).
• surfacesOwnRuntimeState: must be false for every capability's surface.

Use scripts/surface_authority_audit.mjs to score a spec matching schemas/surface-authority-spec.schema.json and return { pass, score, findings, recommendations }.

Anti-Patterns

One Capability, Two Homes (Or No Home)

Novice: "It's easier to keep the FleetBar version around too, in case pd-console isn't open" — or a typo'd surface name ("browser-tab", a retired dashboard) survives from an earlier prototype. Expert: Each capability belongs to exactly one surface by distance-from-work. A capability claimed by two surfaces will drift the moment one implementation changes and the other doesn't; a capability claimed by no valid surface has no enforceable owner at all. Detection: surface_authority_audit.mjs fires capability-multi-surface (critical) when the same capability name is assigned to more than one distinct surface, when assignedSurface is outside {scout, fleetbar, pd-console}, or when a valid assignedSurface disagrees with the canonical surface for its declared distance.

FleetBar Grows A Console

Novice: "Just add a diff viewer to the popover, it's more convenient than deep-linking out." Expert: Anything requiring more than one screen of evidence belongs in pd-console, not FleetBar. FleetBar deep-links into pd-console rather than growing panes — a menu-bar popover that needs multiple screens of context to evaluate is a console feature wearing FleetBar's chrome. Detection: surface_authority_audit.mjs fires deep-evidence-in-fleetbar (critical) when a capability assigned to fleetbar has evidenceScreens > 1, and often co-fires capability-multi-surface when the capability's distance is actually deep.

A Button (And A Bus) The Daemon Can't Back

Novice: Render the approve/deny control immediately because the UI is ready, wire it to the daemon "in a follow-up," and let a surface cache its own roster copy "for snappiness" while the wiring lands. Expert: No surface may render a control the daemon cannot enforce, and no surface owns runtime state — both break the guarantee that all three surfaces render the same daemon truth and degrade identically when the daemon dies. A capability's bus subscription must match its distance too: intake/deep capabilities are durable cool-bus objects (Work Intents, transcript events), not ephemeral hot-bus chatter. Detection: surface_authority_audit.mjs fires unenforceable-control-rendered (critical) when daemonEnforceable is false, surface-owns-runtime-state (critical) when surfacesOwnRuntimeState is true, and bus-distance-mismatch (critical) when an intake/deep capability's busSubscription isn't cool.

Native Surface Calls The Automation Adapter

Novice: Have FleetBar or pd-console run pd ... or call MCP tools internally because the command already exists and the UI needs the same behavior. Expert: CLI and MCP are automation adapters for agents, CI, scripts, emergency repair, and integrations. Native operator surfaces use the shared daemon contract / Surface Gateway path directly so operator truth, automation truth, and policy enforcement stay one thing. Detection: Surface specs or implementation notes mention FleetBar, Scout, or pd-console invoking CLI/MCP as their internal path instead of submitting the shared command/query/event envelope.

References

File	Load When
references/distance-based-authority-model.md	Deciding or reviewing which surface owns a capability by its intake/ambient/deep distance, or resolving a two-surface claim.
references/hot-bus-cool-bus-subscription-contract.md	Picking or auditing a capability's hot/cool bus subscription, especially for intake/deep capabilities.
examples/expected-output.md	Need a worked example auditing a concrete operator-surface spec, weak-then-fixed.
examples/sample-input.json	Need a complete spec that already passes the audit, as a starting fixture.
templates/output-template.md	Need a fill-in-the-blank capability authority table.
schemas/surface-authority-spec.schema.json	Need to validate a spec's structure before running the audit.
scripts/surface_authority_audit.mjs	Need deterministic scoring of a proposed or shipped operator-surface authority spec.
agents/openai.yaml	Need a subagent descriptor for delegated surface-authority review.

Skill Bundle Index

Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.

root

• CHANGELOG.md — Operator Surface Authority Designer — Changelog — - Initial skill creation - Distance-based authority model (intake/ambient/deep) defined - Reference files and deterministic surface_authorit
• README.md — Operator Surface Authority Designer — Decide which of the three operator surfaces — Scout, FleetBar, pd-console — owns a capability, by distance-from-work, and audit the placemen

agents/

• agents/openai.yaml — openai (data/schema)

examples/

• examples/expected-output.md — Example Output: Operator Surface Authority Designer — Scenario: a team is speccing Agent Harbor's operator triad.
• examples/sample-input.json — sample input (data/schema)

references/

• references/distance-based-authority-model.md — Distance-Based Authority Model — Use this when deciding which of the three operator surfaces — Scout, FleetBar, pd-console — should own a given capability, or when reviewing
• references/hot-bus-cool-bus-subscription-contract.md — Hot-Bus / Cool-Bus Subscription Contract — Use this when deciding (or auditing) which message plane a capability's data should ride, or when a bus-distance-mismatch finding needs ju

schemas/

• schemas/surface-authority-spec.schema.json — surface authority spec.schema (data/schema)

scripts/

• scripts/surface_authority_audit.mjs

templates/

• templates/output-template.md — Operator Surface Authority Decision — Fill in one row per capability before assigning it to a surface.