Scrubbed extract of ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.8-Agent-Spawn-Flow.md — cited by the Chronicle (03-the-platform-rises). Redactions: phone / service detail / secrets / clearance / personal / internal hosts.

type: implementation-plan category: Work project: ADP-Orchestration-UI priority: High status: done created: 2026-05-14 epic: Epic-2-Orchestration-Dashboard user-story: US-OUI-2.8 effort: 10h precedence:

• “[[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.2-Agent-Session-List]]”
• “[[US-OUI-1.6-Permission-Scoping-Enforcement]]” parallel_group: review-profile: standard source: wireframe-gap-analysis-2026-05 depends-on:
• ADR-009
• ADR-036
• ADR-037
• ADR-017 tags:
• implementation-plan
• epic-2
• spawn-flow
• supervisor

US-OUI-2.8: Agent Spawn Flow

[!note] ADR-016 superseded 2026-08-22 — this story’s shipped contract is unaffected and is now normative Superseded by [[../../AI-Dev-Platform/ADR/ADR-036-Agent-Routing-And-Capability-Binding|ADR-036]] + [[../../AI-Dev-Platform/ADR/ADR-037-Agent-Workflow-Composition|ADR-037]]. This story is done and stays done: ADR-036 §7 adopts this consumer’s vocabulary — single-agent | sequential | concurrent | handoff | group-chat as declared in src/spawn/SpawnRequest.ts:5 — as the one normative spelling, and ADR-037 §5 preserves those five as archetype labels.

Two server-side notes for whoever next touches the spawn lane: the AIService supervisor emits a non-conformant vocabulary (Solo | Hierarchical | Sequential | Swarm | PeerReview, SupervisorDtos.cs) and recommends five agent names present in no catalog — see [[../../AI-Service-Implementation/Epic-7-Stories/IP-AIS-7.9-Supervisor-Recommendation-Endpoint|IP-AIS-7.9]]. The recommendation endpoint is also still unrouted, so the hook 404s today.

Epic: [[README|Epic 2: Orchestration Dashboard]] Owner Agent: \xe2\x80\x94 Effort: 10h Priority: 🔼 High Status: 🔵 Backlog

Mission

Build the Spawn Agent dialog reached from the + SPAWN action in the agent session list. The dialog walks the developer through story binding, ADR/PKF context selection, model tier override, parent session attachment, and the supervisor’s recommended specialist agent with a confidence reading per [[../../AI-MLOps-Platform/ADR/ADR-016-Agent-Selection-And-Collaboration-Model|ADR-016]] §3. At spawn time, the agent’s working branch is created per [[../../AI-Dev-Platform/ADR/ADR-017-Human-Review-Branching-And-TDD-Workflow|ADR-017]] §3 (agent/<US-XXX>-<slug>) — the branch name must be visible in the dialog before the user clicks “Spawn”. The user can override the supervisor’s recommendation; an override is recorded in the supervisor decision audit.

Context

The Wireframe Gap Analysis §1 names spawn-and-control as the dashboard’s primary command operation; §11 names the supervisor as the new architectural primitive that picks the specialist agent; §13 establishes that branch creation is the agent’s first action and therefore must be visible at spawn time so the human can audit the branch name before commit history begins. ADR-016 provides the supervisor decision contract; ADR-017 fixes branch naming; ADR-009 fixes the MAF workflow patterns the dialog must surface (single / handoff / concurrent / group-chat).

Context Bootstrap

Read the following before writing any code, in order:

1. [[../../AI-Dev-Platform/ADR/ADR-017-Human-Review-Branching-And-TDD-Workflow|ADR-017]] — review profile, branch-per-story discipline, PR description schema
2. [[../../AI-MLOps-Platform/ADR/ADR-016-Agent-Selection-And-Collaboration-Model|ADR-016]] — §1 capability registry, §3 ISpecialistSupervisor, §4 workflow elevation rules
3. [[../../AI-Dev-Platform/ADR/ADR-009-MAF-Integration-Strategy|ADR-009]] — workflow primitives (Sequential / HandoffWorkflow / ConcurrentWorkflow / GroupChatWorkflow)
4. [[../Wireframe-Gap-Analysis|Wi[[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.2-Agent-Session-List]]13
5. [[Projects/ADP-Orchestration-UI/Epic-2-Stories/US-OUI-2.2-Agent-Session-List]] — the + SPAWN entry point
6. [[../../AI-Service-Implementation/Epic-7-Stories/US-AIS-7.1-Session-Agent-Endpoints]] — the spawn REST endpoint shape
7. [[../_pkf|OUI _pkf]]

Gate Policy

Deliverables

src/spawn/SpawnDialog.tsx (new)

• Modal with five panels: Story Binding, Context Selection, Supervisor Recommendation, Branch Preview, Confirmation
• Story binding searches US-* stories from the API client; selecting one preloads referenced ADRs and the project PKF
• Context selection lists vault docs with <SensitivityBadge> per US-OUI-1.7; sensitive selections force tier-lock indicator and disable non-local tier options
• Supervisor recommendation shows specialist name, confidence (gauge), reasoning summary, and alternative options
• User override sets supervisor_override: true on the spawn request payload
• Branch preview shows the resolved agent/<US-XXX>-<slug> name; non-editable; copyable

src/spawn/useSupervisorRecommendation.ts (new)

• Calls POST /api/orchestration/supervisor/recommend with { storyId, contextDocIds, hints }
• Returns { specialist, confidence, reasoning, alternatives, workflowPattern } typed against ADR-016 §3
• Loading and error states surfaced to the dialog as Confidence-Gate-style affordances (not silent fallback to default specialist)

src/spawn/SpawnRequest.ts (new)

• Type for the POST payload to /api/orchestration/sessions matching US-AIS-7.1
• Includes branchName, storyId, contextDocIds, tierOverride, parentSessionId, specialist, supervisorOverride

src/spawn/__tests__/spawn.test.tsx (new)

• Branch-name preview is derived from storyId deterministically
• Selecting a sensitive context doc locks the tier and disables Premium tier option
• Spawn POST is rejected client-side if targetBranch resolves to main
• Supervisor override is captured in the request payload
• <RoleGate require="adp-developer"> wraps the SPAWN action

Execution Phases

TDD-ordered per ADR-017 §4.

1. Branch Creation — agent/US-OUI-2.8-spawn-flow from main.
2. Load Context — Read Context Bootstrap files. (Plan Review.)
3. Write Failing Tests — Tests above. Run pnpm test --run; all fail. (Test Review.)
4. Implement — SpawnDialog, hook, request type.
5. Verify & Refactor — Full pipeline green. Status review.
6. PR Submission — Push branch; open PR. (PR Review.)

PR Submission Requirements

ADR-017 §5 schema: Reasoning Chain, Gate History, Citations, Review Profile (standard), Test Plan with TestTransition rows.

Implementation Notes

Branch name derivation

Slugify storyId lowercased; drop US-; append a short hash of the spawn timestamp. Example: US-AIS-2.2 + 2026-06-18T14:02Z → agent/AIS-2.2-spawn-a7f3. The hash distinguishes restarts of the same story.

Tier lock visualization

Sensitive context doc → routing visualization (US-OUI-2.4) shows only the local node as active; this story’s dialog mirrors that lock by disabling the Premium/Mid/Budget tier radio buttons with an explanatory tooltip citing ADR-015 §3b.

Files to Modify

• src/spawn/* — new files above
• src/dashboard/AgentSessionList.tsx — + SPAWN button opens <SpawnDialog>
• src/api/client.ts — typed spawn POST + supervisor-recommend POST

Definition of Done

• All Deliverables checked
• All Execution Phases verified
• Tests pass: pnpm test --run src/spawn
• Branch-name invariant test prevents main/master/trunk regressions
• Status updated to review

Related

• [[../../AI-Dev-Platform/ADR/ADR-017-Human-Review-Branching-And-TDD-Workflow|ADR-017]]
• [[../../AI-MLOps-Platform/ADR/ADR-016-Agent-Selection-And-Collaboration-Model|ADR-016]]
• [[../../AI-Dev-Platform/ADR/ADR-009-MAF-Integration-Strategy|ADR-009]]
• [[US-OUI-2.12-Agent-Selection-Collaboration]] — surfaces supervisor decisions on the timeline after spawn
• [[../../AI-Service-Implementation/Epic-7-Stories/US-AIS-7.1-Session-Agent-Endpoints]]
• [[../Wireframe-Gap-Analysis|Wireframe Gap Analysis]] §1, §11, §13
• [[../_pkf|OUI _pkf]]