Files
kandev/docs/plans/task-creation-auto-focus/plan.md
T
2026-09-14 13:01:29 +00:00

132 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
created: 2026-09-13
status: implemented
requirements:
- REQ-TASKS-CREATION-AUTO-FOCUS-001
system_design:
- ../../specs/tasks/system-design/creation-auto-focus.md
legacy_specs: []
---
# Implementation plan: Task creation auto-focus
## Overview
Deliver one vertical preference: persist a default-on setting, expose it in Task
Actions, and honor it at all shared task-creation completion boundaries. One
sequential work order keeps the preference and its behavior together.
## Scope
Include persistence, settings discovery, desktop/phone UI, localization,
creation completion, focused tests, and public task documentation. Exclude
per-task overrides, agent-start policy changes, Quick Chat, edit/session flows,
and automatic focus for background/API events.
## Technical approach
Follow the [design](../../specs/tasks/system-design/creation-auto-focus.md).
Use the existing settings JSON with a true missing-value default and the shared
save coordinator. Extend creation metadata with `autoFocus`; retain the
distinct meaning of `willNavigate`. Inspect every dialog caller before changes,
retain cache and completion work before suppression guards, and decouple plan
initialization from navigation.
The per-user scope and Task Actions placement follow existing preference
patterns. User-confirmed behavior is an option to prevent focus with current
behavior as the default; this package proposes those routine UI/storage details.
## ASCII UI preview
UI-01: Settings > Task Behavior, saved default. Desktop and phone use
the same inline card composition:
```text
+-------------------------------------------+
| Auto-focus new tasks [ ON ] |
| Open newly created tasks automatically. |
| Turn this off to stay on your current |
| view. Tasks and agents still start as |
| requested. |
+-------------------------------------------+
After toggling: [ OFF ] (unsaved)
Existing shared action: [ Save changes ]
```
UI-02: Successful creation with the saved setting off:
```text
Current task or listing -> [Create task] -> Same task or listing
dialog closes New task is available
for manual opening
```
Card hierarchy, visible help, and shared save ownership are structural. Spacing
and line breaks are illustrative. On phone, text wraps in the existing page
scroll region; the switch has a >=44px touch target and the existing save
control clears the safe area. No nested scroller or new drawer. A save failure
retains dirty state and existing shared error UI; discard restores the saved
switch value. Creation failure retains the existing dialog error flow.
These views cover AC-TASKS-CREATION-AUTO-FOCUS-001.1–001.5 and are verified by
the E2E files below.
## Tests
Use TDD for changed logic. The work order owns exact commands.
| AC suffix | Test location and cases |
| --- | --- |
| .1, .4 | New `creation_auto_focus_test.go` tests in user models/store/service and boot projection: true default, absent JSON, false/true round trip, omitted patch preservation |
| .1, .4 | `lib/ssr/user-settings.test.ts`: missing value true and explicit false through mapping; new settings component test for save/discard/rejection |
| .2, .3 | `task-create-dialog-submit.test.tsx`, helpers and caller suites: enabled/default behavior, false/no callback suppression, no-agent, agent, passthrough, plan, queued/no session, error and edit/session regressions |
| .2, .3 | Caller tests: sidebar, canvas, task header, phone switcher and board, asserting retained cache upserts and no route/active task/session/layout change |
For new focused test files use the `creation-auto-focus.test.tsx` basename or
suffix so the work-order Vitest filter includes them. Extend existing suites
where their fixtures already cover the changed consumer.
## E2E tests
Add `e2e/tests/task/creation-auto-focus.spec.ts` (chromium) and
`e2e/tests/task/mobile-creation-auto-focus.spec.ts` (mobile-chrome).
Use existing task creation and mobile switcher fixtures, with no per-test
device overrides. Prove default-on behavior, saving off and reloading,
creation from a listing and an already active task, preserved route/selection,
manual opening, re-enabling, and unchanged explicit launch outcome. Verify
phone switch accessibility, >=44px target, containment, and focus return.
Unit/component tests cover the full caller and launch-mode matrix; E2E covers
the integrated user flows. Rebuild web and backend before browser tests.
## Work orders
- [x] [Task 01: Implement saved auto-focus preference](task-01-auto-focus-preference.md)
## Verification results
Implementation and verification completed on 2026-09-13. Backend persistence,
partial settings updates, boot projection, and settings catalog checks passed.
The broad frontend run passed 315 tests across 25 files; subsequent focused
runs verified final dialog focus restoration (11 tests), Azure launcher, and
settings fixture changes. TypeScript, changed-file ESLint, Prettier,
localization checks and ratchet, native backend builds, and web build passed.
Desktop and phone browser scenarios passed, including saved preference reload,
retained current view, manual opening, requested background agent execution,
re-enabled auto-focus, keyboard focus return, and phone touch/overflow checks.
Public documentation validation passed (62 tests, 46 pages). Specification
catalog/lint and whitespace validation passed. Exact commands and build scope
are recorded in the completed work order.
## Risks
- Missing/default coercion must not replace explicit false with true.
- Parent callbacks must not interpret suppressed navigation as permission to navigate.
- Planning task setup must survive disabled navigation without switching the current layout.
- Filtered lists need not reveal a newly created task; cache updates must still occur normally.
## Documentation impact
Updated `docs/public/tasks-and-workflows.md` with the setting location, enabled
default, saved scope, and unchanged requested agent-start behavior.