--- status: draft system: tasks requirements: - REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-001 - REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-002 --- # Task Create Launch Preview System Design ## Purpose and boundaries The task system owns immediate-launch routing and workflow-step prompt composition. The shared task creation dialog presents a pre-creation projection of those rules. The projection follows the action currently available in the form: an empty description exposes **Start Plan Mode**, while a nonempty description exposes immediate agent-start actions. This design adds no endpoint, persisted state, or runtime prompt behavior. It uses the workflow data that the dialog already receives from boot state or the workflow-step API. ## Requirement mapping | Requirement | Design sections | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-001` | [Launch-step projection](#launch-step-projection), [Workflow selector](#workflow-selector) | | `REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-002` | [Prompt composition](#prompt-composition), [Prompt editor](#prompt-editor), [Responsive behavior](#responsive-behavior) | ## Components and responsibilities - A pure task-create helper selects the launch destination and composes the step-prompt preview. - `useWorkflowStepsEffect` retains each fallback-fetched step prompt with its actions, position, and workflow identity. - Workflow-step WebSocket handlers keep loaded workflow snapshots synchronized for step create, update, and delete events. - `buildDialogFormBodyProps` selects steps for the effective workflow. It passes one launch-preview model to the shared create form. - `WorkflowSelectorRow` shows the launch destination beside the selected workflow name. - `TaskFormInputs` owns the local preview toggle because it already owns the current task prompt and editor state. - A focused preview control renders the icon, tooltip, accessible state, and read-only preview surface. ## Data and contracts The launch-preview model contains the destination step ID, step name, and step prompt. It is derived data and is not stored in `DialogFormState`. The resolver accepts steps from one effective workflow. A step supplies these existing fields: - `id` - `title` - `position` - `events.on_enter` - `is_start_step` - `prompt` - `workflowId` when the step came from a fallback fetch The dialog uses matching fetched steps when they exist. A successful empty fetch is authoritative and produces no destination. If the fetch is unavailable, or contains only steps from another workflow, the dialog uses the selected workflow snapshot. A fetched step from another workflow is never a candidate. When the effective workflow is the visible context workflow, the dialog uses its live snapshot; workflow-step WebSocket events keep that snapshot current after edits made elsewhere. A different effective workflow is fetched by the existing fallback path. ## Launch-step projection For a nonempty description, the frontend resolver mirrors `workflow.Service.ResolveAutoStartStep`: 1. Sort the effective workflow steps by `position`. 2. Select the first step whose `on_enter` actions contain `auto_start_agent`. 3. If none exists, select the first step with `is_start_step`. 4. If none exists, select the first positional step. For an empty description, the resolver selects the first positional step. This matches the **Start Plan Mode** path, which does not start an agent immediately. The auto-start projection describes the **Start task** and **Start task in plan mode** actions when a description is present. It does not describe **Create without starting agent**, which uses the configured start step. ## Prompt composition The preview helper mirrors the step-template part of `orchestrator.Service.buildWorkflowPromptWithTrustedContext`. If the step prompt contains `{{task_prompt}}`, the helper replaces its first occurrence with the current editor value. The backend also replaces only the first occurrence. If the token is absent, the helper returns the step prompt without adding the editor value. The helper does not resolve `{task_id}` because no task exists. It also leaves `@name` references unchanged. Saved-prompt expansion remains server-owned under [ADR-2026-09-01](../../../decisions/2026-09-01-server-owned-saved-prompt-expansion.md). The preview excludes workflow-level instructions and runtime-only system context. Its purpose is to show how the launch step applies its own template. ## Workflow selector The selected workflow trigger renders only the workflow name and existing chevron. The launch destination renders as a sibling group outside the trigger, immediately to its right. The group contains an `IconArrowBigRightLines` help button first and the muted destination step name second. The arrow expresses the flow from the selected workflow into its launch destination, so the visible **Start step:** prefix and the generic information glyph are removed. The trigger keeps its intrinsic selector width and does not claim the full row. The arrow button exposes the existing localized help in a tooltip on pointer hover and keyboard focus. On coarse pointers, `useTouchDrawer` replaces the tooltip with a drawer containing the same localized title and description. The button retains its localized accessible name and has a hit area of at least 44 CSS pixels on coarse pointers. Truncation keeps the selector row within its available width. The existing selector visibility rules remain unchanged. A single implicit workflow can still omit the selector when it has no override information. ## Prompt editor The preview button appears only in create mode when the launch destination has a nonempty prompt. It follows **Enhance prompt with AI** in the toolbar. The editor keeps its draft in the existing local description state. Preview mode replaces the editable textarea with a read-only, wrapping text surface. The preview surface uses the same height boundary and overflow ownership as the textarea. The button uses `aria-pressed` and localized labels for preview and edit modes. The inactive preview label identifies the workflow step prompt and resolved step, for example **Preview launch prompt with workflow step prompt: In Progress**. If the workflow changes to a destination without a prompt, the component closes preview mode and shows the unchanged editor value. ## Responsive behavior Desktop and mobile use the same launch resolver, prompt value, and toggle state. The existing task creation dialog remains the entry point and scroll owner. On fine pointers, the preview icon keeps the compact composer density. On coarse pointers, its active hit area is at least 44 CSS pixels. The read-only text wraps inside the composer and owns only the same bounded overflow as the textarea. The nearest mobile exemplar is the current Kanban FAB to task-create dialog flow. The launch-destination explanation uses the standard coarse-pointer drawer; this change adds no route, fixed control, or safe-area boundary. ## Failure and recovery If workflow steps are unavailable, the dialog keeps the selected workflow snapshot as a temporary fallback and the remaining form stays usable. A successful empty response omits the destination and preview controls rather than retaining stale snapshot steps. Workflow identity filtering prevents another workflow's fetched steps from becoming candidates. If steps arrive after the dialog opens, the derived model updates from those steps. A workflow change removes any prior preview model before new steps can replace it. Step create, update, and delete events update loaded workflow snapshots, so the visible workflow does not require a component-level refresh request to reflect edits made elsewhere. ## Localization and public documentation All new labels use the task namespace in every supported locale. The public task creation guide explains the launch label, preview boundary, and unresolved server-owned values. ## Verification - Unit tests cover action-sensitive launch routing, stale workflow filtering, workflow-snapshot step-event synchronization, and prompt composition. - Component tests cover selector text, toggle state, draft preservation, and the no-prompt fallback. Focused selector coverage also verifies the arrow glyph and help disclosure. - Desktop Playwright covers workflow switching, pointer-hover help, and composed preview content. - Mobile Playwright covers the same user value, the touch drawer, the 44-pixel hit area, viewport containment, and horizontal overflow. ## Related decisions - [Keep Saved-Prompt Expansion Server-Owned](../../../decisions/2026-09-01-server-owned-saved-prompt-expansion.md)