# Feature Spec: Dashboard Quick Launch and Control Surface (AOP)

> **Purpose of this document**: Define the dashboard-side authoring and operator controls for launching specs, re-enrolling stalled or blocked features, reducing triage-drawer interference, and adding persistent footer navigation.

**Version:** 1.0
**Date:** 2026-03-16
**Status:** Draft
**Roadmap Mapping:** M51
**Depends On:**

- `spec-files/completed/agentic_orchestrator_dashboard_advanced_ux_spec.md`
- `spec-files/completed/agentic_orchestrator_add_feature_to_active_execution_spec.md`
- `spec-files/completed/agentic_orchestrator_reactive_execution_enrollment_spec.md`
- `spec-files/completed/agentic_orchestrator_dashboard_command_center_redesign_spec.md`

---

## 0. Scope

This spec covers the following user requests:

1. Move Quick Launch onto its own route with a visible dashboard entrypoint.
2. Allow Quick Launch to accept either uploaded spec markdown files or pasted markdown text.
3. Render imported markdown on the Quick Launch page before submission.
4. Submit Quick Launch work through the same active-run enrollment path as `aop add`.
5. Support adding multiple features in one dashboard submission.
6. Allow direct dashboard resume/retry actions for features in client-visible `stalled` or `blocked` states.
7. Refactor the root triage drawer so it remains helpful without obstructing root-route navigation.
8. Add footer links to the GitHub repository and documentation.

Out of scope:

- background runtime boot and standby behavior
- per-phase model/provider selection
- token telemetry collection internals
- organizer/spec-ordering behavior

### 0.1 Required Standards

All implementation derived from this spec MUST preserve:

- deterministic execution-request submission through the existing runtime enrollment path
- normalized `{ ok, data/error }` dashboard and tool response envelopes
- single-active-run repository ownership semantics
- atomic state mutation through existing kernel/service seams rather than ad hoc dashboard writes
- accessibility and responsive behavior already required by the dashboard specs this document depends on

### 0.2 OOP and Architecture Guardrails (Mandatory)

Implementation MUST follow:

- **KISS**: keep dashboard intake, preview, submission, and recovery actions as separate focused modules instead of one oversized route/controller.
- **SRP**: root triage layout, launch authoring flow, execution-request submission, and action authorization MUST remain separate responsibilities.
- **SOLID-oriented design**:
  - open/closed for future intake sources beyond upload/paste without rewriting enrollment plumbing
  - interface segregation between preview/render helpers, submission helpers, and recovery-action helpers
  - dependency inversion so dashboard routes depend on reusable orchestration/service seams rather than hard-coded CLI behavior
- **Hexagonal alignment**: the dashboard MUST call orchestrator services/tools; it MUST NOT become a second control-plane implementation.
- **Composition over inheritance**: build the launch page from small draft/preview/submission components and helper modules.
- **High cohesion / low coupling**: triage-drawer UX fixes must not be bundled with deep Focus-view review behavior.

---

## 1. Problem Statement

The current dashboard has three related gaps:

1. Quick Launch exists only as a small inline panel and initializes a single feature via `feature.init`; it does not work as a first-class spec intake surface and does not reuse the active-run enrollment model introduced by `aop add`.
2. Operators can see blocked or stalled work but cannot consistently recover it from the dashboard using the same semantics as CLI `add --resume` and `retry`.
3. The root triage drawer is positioned in a way that can obscure header controls, and the dashboard lacks persistent navigation affordances to repo/docs destinations.

The desired behavior is a dashboard command surface that is useful for intake and lightweight control, while leaving deep review in `/feature/:id`.

---

## 2. Design Summary

### 2.1 New Quick Launch Route

Add a dedicated route:

- `packages/web-dashboard/src/app/launch/page.tsx`

This route becomes the primary dashboard authoring surface for new work intake.

The existing root-page Quick Launch affordance MUST be reduced to:

- a button or link to `/launch`
- lightweight availability/status messaging only
- no multi-field authoring workflow on the root route

### 2.2 Submission Model

Quick Launch MUST submit through the same durable execution-enrollment pipeline as CLI `aop add`.

That means the dashboard MUST NOT shell out to CLI commands and MUST NOT bypass runtime request persistence.

Normative rule:

- dashboard intake -> server-side spec normalization/preview -> execution request submission -> supervisor enrollment

### 2.3 Multi-Spec Authoring Model

The Quick Launch page MUST support a batch of draft specs.

Each draft card contains:

- `feature_id`
- markdown source
- source type: `upload` or `paste`
- preview status
- validation errors, if any

The page MUST allow operators to:

- upload multiple `.md` files in one action
- paste one markdown block and add it as a draft
- paste multiple markdown blocks as separate drafts only if they are explicitly delimited by the UI flow; free-form auto-splitting is out of scope for v1
- remove drafts before submission
- submit one draft or all valid drafts

---

## 3. Functional Requirements

### FR-1 Dedicated Launch Navigation

The dashboard header or root-page control surface MUST include a visible link/button to the new Quick Launch route.

Acceptance criteria:

1. `/` exposes a non-hidden path to `/launch`.
2. `/launch` is reachable by keyboard and touch.
3. The current inline panel no longer owns the full intake workflow.

### FR-2 Markdown Upload and Paste

Quick Launch MUST accept either:

- file upload of one or more markdown files
- direct markdown paste into a draft composer

Acceptance criteria:

1. Uploaded files are read server-side or client-side and shown as draft specs before submission.
2. Pasted markdown is preserved exactly for preview and downstream ingestion.
3. Unsupported file types fail with inline validation, not silent ignore.

### FR-3 Rendered Markdown Preview

Each draft MUST have a rendered preview panel and a raw markdown editor/reader panel.

Acceptance criteria:

1. Markdown rendering happens before submission.
2. Preview and raw source stay synchronized.
3. Render failures degrade to raw markdown with an explicit warning.

### FR-4 Reuse `aop add` Semantics

Quick Launch MUST reuse the same core semantics as `aop add`:

- canonical feature resolution
- durable execution request submission
- active-run targeting
- request disposition tracking

Acceptance criteria:

1. Dashboard submissions create an execution request artifact, not an ad hoc state mutation.
2. The server path rejects submission when no active run is available.
3. Duplicate/terminal/already-queued handling matches the enrollment scheduler behavior already used by `aop add`.

### FR-5 Multi-Feature Add

The Quick Launch page MUST support batch submission of multiple valid specs in one request.

Acceptance criteria:

1. A single dashboard action can submit multiple feature specs.
2. Request ordering remains deterministic by draft order, then `feature_id`.
3. Partial validity is supported: invalid drafts block only themselves unless the operator chooses “submit all-or-none”.

### FR-6 Resume/Retry Dashboard Actions

Dashboard operators MUST be able to recover stalled or blocked features directly from dashboard surfaces.

Rules:

- `blocked` features with retry-eligible evidence use the existing retry path.
- `stalled` features use resumable re-enrollment semantics aligned to `aop add --resume`.
- the UI label MAY be unified (`Resume / Retry`) but the backend action MUST preserve the correct semantic path.

Acceptance criteria:

1. Root triage drawer and focus view both expose recovery affordances when the action is valid.
2. `stalled` does not incorrectly call the gate retry endpoint.
3. Recovery actions return updated action-state envelopes just like existing dashboard mutations.

### FR-7 Non-Intrusive Triage Drawer

The root-route triage drawer MUST stop blocking access to `Board`, `List`, and `Analytics`.

Normative layout rule:

- on desktop, the triage drawer must live inside the page grid below the header, not as an overlay that can cover top navigation
- on smaller breakpoints, it may become a sheet/drawer, but header navigation must remain reachable or the drawer must yield focus/space cleanly

Acceptance criteria:

1. Header controls remain clickable while a feature is selected.
2. Keyboard focus is not trapped unexpectedly on desktop.
3. The drawer still shows summary, actions, and “Open Focus View”.

### FR-8 Footer Links

The dashboard MUST include persistent footer links to:

- the GitHub repository
- the documentation

Acceptance criteria:

1. Links appear on root, launch, analytics, and focus routes through shared layout or shared footer composition.
2. URLs can come from configuration, environment, or package metadata fallback.
3. Missing configured URLs degrade to sensible repository-local defaults where possible.

---

## 4. API and UI Contracts

### 4.1 New Routes

Add:

- `GET /launch`
- `POST /api/launch/preview`
- `POST /api/launch/submit`

`/api/launch/preview` responsibilities:

- accept uploaded or pasted markdown drafts
- validate shape and derive candidate `feature_id`
- return rendered preview payloads and validation results

`/api/launch/submit` responsibilities:

- normalize approved drafts into execution-request payloads
- submit durable enrollment requests against the active run
- return per-draft outcomes and request ids

### 4.2 Draft Payload Shape

```json
{
  "drafts": [
    {
      "draft_id": "draft_01",
      "feature_id": "feature_checkout_flow",
      "markdown": "# Feature Spec ...",
      "source_type": "upload"
    }
  ],
  "mode": "submit_valid"
}
```

### 4.3 Action Additions

Extend dashboard action handling with a resumable action path.

Recommended action names:

- `feature.resume`
- `feature.retry`

If the existing `feature.retry` name is retained for the UI, the server must still branch into resume vs retry logic based on feature state and action type rather than overloading one tool call blindly.

---

## 5. File-Level Targets

- `packages/web-dashboard/src/app/page.tsx`
  - replace root Quick Launch authoring with route link and compact status.
- `packages/web-dashboard/src/app/launch/page.tsx`
  - new dedicated intake route.
- `packages/web-dashboard/src/app/layout.tsx`
  - shared footer with repo/docs links.
- `packages/web-dashboard/src/app/api/launch/preview/route.ts`
  - new preview endpoint.
- `packages/web-dashboard/src/app/api/launch/submit/route.ts`
  - new submission endpoint wired to execution request submission.
- `packages/web-dashboard/src/app/api/actions/route.ts`
  - add resume-aware dashboard recovery path.
- `packages/web-dashboard/src/components/quick-launch-panel.tsx`
  - repurpose as compact link/status affordance or retire in favor of route-local components.
- `packages/web-dashboard/src/components/dashboard/triage-drawer.tsx`
  - move to non-obstructive layout contract and add resume/retry affordances.
- `packages/web-dashboard/src/components/dashboard/command-center-header.tsx`
  - add Quick Launch navigation entry.
- `packages/web-dashboard/src/lib/orchestrator-tools.ts`
  - add execution-request submission helpers if required.
- `packages/web-dashboard/src/lib/types.ts`
  - add launch draft/preview/submit payload types.
- `apps/control-plane/src/cli/spec-input-resolver.ts`
  - reuse semantics only; dashboard must not fork spec parsing logic from the CLI path.
- `apps/control-plane/src/cli/spec-ingestion-service.ts`
  - likely extraction target for dashboard/server reuse.

---

## 6. Acceptance Criteria

1. Operators can navigate to a dedicated Quick Launch route from the dashboard.
2. Quick Launch accepts uploaded or pasted markdown and renders a preview before submission.
3. Quick Launch can submit multiple features in one action.
4. Submitted dashboard work enters the same durable active-run enrollment pipeline as `aop add`.
5. Blocked and stalled features can be recovered from dashboard surfaces using the correct underlying semantics.
6. The root triage drawer no longer obstructs root-route navigation controls.
7. Footer links to repo/docs are visible across dashboard routes.

---

## 7. Risks and Mitigations

- Risk: dashboard implements a separate spec parser that diverges from CLI behavior.
  - Mitigation: extract reusable normalization logic from existing CLI services instead of duplicating markdown-to-feature rules in the Next.js layer.
- Risk: batch submission hides partial failures.
  - Mitigation: return per-draft outcomes and explicit request ids.
- Risk: resume and retry semantics get conflated for stalled vs blocked work.
  - Mitigation: keep server-side state-driven branching explicit and test both flows separately.
