Carlos Florêncio
129 lines
5.3 KiB
Markdown
129 lines
5.3 KiB
Markdown
---
|
|
created: 2026-09-05
|
|
status: complete
|
|
requirements:
|
|
- REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-001
|
|
- REQ-TASKS-TASK-CREATE-LAUNCH-PREVIEW-002
|
|
system_design:
|
|
- ../../specs/tasks/system-design/task-create-launch-preview.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: Task Create Launch Preview
|
|
|
|
## Overview
|
|
|
|
Add a shared frontend projection of the backend immediate-launch rules. Use that
|
|
projection to show the destination step and to preview its composed step prompt.
|
|
The projection must follow the available create action: empty descriptions use
|
|
the plan-mode first step, while nonempty descriptions use immediate agent-start
|
|
routing.
|
|
The pure projection lands first, the UI follows, and responsive E2E tests prove
|
|
the complete flow.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Show the immediate launch destination beside the selected workflow.
|
|
- Preview a nonempty destination step prompt with the current task prompt.
|
|
- Preserve the task prompt while the preview is visible.
|
|
- Localize the new controls in all supported locales.
|
|
- Update the public task creation guide.
|
|
- Prove desktop and mobile behavior.
|
|
|
|
### Out of scope
|
|
|
|
- Changing launch routing or backend prompt composition.
|
|
- Selecting a workflow destination step.
|
|
- Expanding task IDs, saved prompts, or runtime-only context before creation.
|
|
- Adding the preview outside the primary task creation dialog.
|
|
|
|
## Technical approach
|
|
|
|
### Launch projection
|
|
|
|
Add `task-create-dialog-launch-preview.ts` with pure launch-step and prompt
|
|
composition helpers. The step resolver uses the first positional step for the
|
|
empty-description plan-mode action, mirrors `ResolveAutoStartStep` for
|
|
nonempty descriptions, and filters fetched steps by the effective workflow ID.
|
|
|
|
Extend `StepType` and `useWorkflowStepsEffect` so fallback-fetched step data
|
|
retains `prompt` and workflow identity. Keep loaded workflow snapshots current
|
|
from workflow-step WebSocket events, so the visible context does not need a
|
|
component-level refresh request. Build one derived launch-preview model in the
|
|
dialog prop assembly. Do not store derived preview data in form state.
|
|
|
|
### Dialog presentation
|
|
|
|
Extend `WorkflowSelectorRow` with the selected launch destination. Render the
|
|
step after the workflow name with muted, truncating text.
|
|
|
|
Add a focused prompt-preview control to the create composer. Place its icon
|
|
after **Enhance prompt with AI**. The control toggles the existing editor between
|
|
the unchanged task prompt and a read-only composed preview.
|
|
|
|
Keep the task dialog as the outer scroll owner. Give the new icon a 44-pixel
|
|
coarse-pointer hit area and retain compact desktop density.
|
|
|
|
### Localization and documentation
|
|
|
|
Add task-namespace labels for preview mode, edit mode, and the preview surface.
|
|
Update all supported locale catalogs, using `i18n:zh-hant` for Traditional
|
|
Chinese catalogs.
|
|
|
|
Update `docs/public/tasks-and-workflows.md`. Explain that the displayed step is
|
|
the immediate launch destination and that server-owned values remain unresolved
|
|
until task creation.
|
|
|
|
## Tests
|
|
|
|
- `AC-TASKS-TASK-CREATE-LAUNCH-PREVIEW-001.2` and `.5` map to resolver and
|
|
prop-builder tests for plan-mode, auto-start, configured-start, and positional
|
|
fallbacks.
|
|
- `AC-TASKS-TASK-CREATE-LAUNCH-PREVIEW-001.3` maps to stale fetched-step and
|
|
workflow-switch tests.
|
|
- `AC-TASKS-TASK-CREATE-LAUNCH-PREVIEW-002.2` through `.5` map to composition
|
|
and component toggle tests.
|
|
- `AC-TASKS-TASK-CREATE-LAUNCH-PREVIEW-002.6` maps to accessible-state and
|
|
responsive hit-area tests.
|
|
|
|
## E2E tests
|
|
|
|
- Extend `apps/web/e2e/tests/task/create-task.spec.ts` with a custom workflow.
|
|
Its configured start step differs from its first auto-start step. Assert the
|
|
displayed launch destination and composed preview.
|
|
- Add
|
|
`apps/web/e2e/tests/task/mobile-create-task-launch-preview.spec.ts`. Assert the
|
|
same preview flow, a 44-pixel touch target, viewport containment, and no
|
|
document-level horizontal overflow in `mobile-chrome`.
|
|
|
|
## Work orders
|
|
|
|
- [x] [Task 01: Resolve launch preview data](task-01-resolve-launch-preview-data.md)
|
|
- [x] [Task 02: Present launch preview controls](task-02-present-launch-preview-controls.md)
|
|
- [x] [Task 03: Prove responsive launch previews](task-03-prove-responsive-launch-previews.md)
|
|
|
|
## Verification results
|
|
|
|
- Targeted launch-preview, effects, prop-builder, selector, and workflow
|
|
handler tests passed (67 tests after review fixup coverage).
|
|
- Task-create component tests passed (43 tests); focused ESLint, typecheck,
|
|
i18n checks, pseudo-catalog sync, and public-doc validators passed.
|
|
- Desktop and mobile focused E2E tests passed (1 each) in host mode.
|
|
- `git diff --check` passed.
|
|
|
|
## Risks
|
|
|
|
- The frontend resolver can drift from backend launch routing. Focused fallback
|
|
tests must encode the backend precedence.
|
|
- A workflow switch can briefly expose the snapshot while a fresh fetch is in
|
|
flight. Every fetched step must match the current effective workflow before
|
|
use, and a successful empty fetch is authoritative. Loaded snapshots are
|
|
updated by workflow-step WebSocket events for visible and non-visible
|
|
workflows.
|
|
- The preview cannot show server-owned task IDs or saved-prompt expansions.
|
|
Public copy must state this boundary without implying full runtime expansion.
|
|
- Long workflow and step names can crowd the selector on phones. Truncation and
|
|
the mobile browser test must protect the dialog width.
|