kandev/docs/plans/task-workflow-agent-overrides/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-19	done	REQ-TASKS-WORKFLOW-AGENT-OVERRIDES-001	../../specs/tasks/system-design/workflow-agent-overrides.md

Task workflow agent overrides plan

Overview

Add task-specific replacements for fixed workflow profiles. Deliver persistence, validation, and routing first. Then expose the contract in Advanced settings. Both work orders are complete, including desktop and phone lifecycle evidence.

Scope

One replacement per distinct fixed step profile, task-only persistence, explicit session binding compatibility, and desktop/mobile task creation are in scope. Existing-task editing, workflow mutation, Office/review-action overrides, MCP schema expansion, and child inheritance are out of scope.

Sources and technical approach

• Requirements
• System design
• Existing resolveStepAgentProfile and task service creation own runtime integration.
• A nullable task column stores a typed workflow ID and step-to-replacement bindings, expanded from grouped source-profile choices.
• TaskCreateAdvancedSettings, form state, and buildCreateTaskPayload own presentation and submission.
• The existing profile-session lifecycle remains authoritative for initial and earlier-step targets.

No companion package currently defines this override capability. Related profile-session work supplies the existing routing contract, not an additional implementation dependency.

ASCII UI preview

UI-01: Desktop, create task with Advanced settings expanded

Workflow       [Feature v]
Initial Agent  [Astra Medium v]
[v] Advanced settings
  Depends on [None v]       Priority [Normal v]
  Workflow agents
  Changes apply only to this task.
  5.6 Luna Max             [5.6 Terra High v] [Reset]
  Implement, PR
                                [Create task]

UI-02: Phone, same expanded state

New task                              [Close]
Workflow
[Feature                                  v]
Initial Agent
[Astra Medium                             v]
[v] Advanced settings
Depends on [None                          v]
Priority   [Normal                        v]
Workflow agents
Changes apply only to this task.
5.6 Luna Max
Implement, PR
[5.6 Terra High                           v]
[Reset to workflow profile]
---------------------------------------------
[Create task]

The form body scrolls. The existing footer remains reachable above the safe area. The phone selector opens the existing responsive agent picker. No new screen is necessary. Source labels and replacement choices are structural requirements. Spacing and the example replacement are illustrative. These excerpts omit unchanged task fields and retain their current order.

UI-03: Loading and errors within Workflow agents

Workflow agents
[Loading workflow agents...]

Workflow agents
Could not load workflow agents. [Retry]

5.6 Luna Max             [Unavailable profile v] [Reset]
Choose an available agent profile.

Submission is disabled during unresolved workflow loading/errors and invalid selections. A successful empty result removes this region. Collapsing Advanced settings does not discard choices. Criteria .1, .2, .6, .7, .8, and .10 apply.

UI-04: Existing step disclosure, task-specific model

Entry points: hover/focus in the topbar or above chat. On phones, tap opens the existing touch disclosure. Keep the current surface composition and controls.

Analysis      Current step
  Agent running  Codex / Astra Medium
Implement     [Move here]
  New session / gpt-5.6-terra
Review        [Move here]
  Reuse initial session / gpt-6-astra
PR            [Move here]
  Reuse Implement session / gpt-5.6-terra

This example assumes Terra replaces Luna and the Implement binding exists. Actual lifecycle labels follow the runtime projection. Before Implement starts, PR shows Planned model / gpt-5.6-terra. Once its session exists, PR shows the actual effective model. Indeterminate models remain unknown. Never invent a session binding. AC-TASKS-WORKFLOW-AGENT-OVERRIDES-001.11 applies to both desktop entry points and their phone tap disclosures.

Tests

Criteria	Planned evidence
.1, .2, .6, .8, .10	task-create-dialog-workflow-agent-overrides.test.ts: grouping, selector reset, stale data, and form lifetime
.3, .9	workflow_agent_overrides_test.go in task repository: migration, round trip, unrelated updates, workflow scope
.2, .5, .9, .10	Task service/handler tests: normalization, eligibility, invalid sources, create-only/start, replay
.3, .4, .5, .9	Orchestrator tests: effective routing across initial/ensure/manual/automatic/preflight paths and restart
.10	task-create-dialog-submit.test.tsx: all ordinary create payloads and retry retention

E2E tests

Create e2e/tests/task/create-task-workflow-agent-overrides.spec.ts for chromium and mobile-create-task-workflow-agent-overrides.spec.ts for mobile-chrome. Use isolated mock-agent fixtures, not the user's active workspace.

The shared scenario creates Initial Agent A and replacement B. It advances Analysis -> Implement -> Review -> PR and asserts the profile and session ID at each step. PR must reuse Implement's B session. A second task without an override must still use the workflow's original profile. A third task with its own replacement C must continue using C. Interleave transitions across all three tasks and repeat resolution after reload to detect shared-state leakage. The workflow and profile records must remain unchanged. Cover create-only followed by later start, reset, collapse, workflow change, new-task reset, and unavailable choices. Mobile coverage adds touch sizing, focus return, viewport containment, and no horizontal overflow with long profile names. Use causal waits, not timed sleeps.

The desktop E2E must open both the topbar and above-chat disclosures and assert the effective profile/model for fixed, initial, and earlier-step recipients. Repeat across the three isolation tasks and after reload. Phone E2E opens both equivalent tap surfaces. Preview requests must not create or start sessions. Include loading, failed preview, unknown model, and session-model override cases. These checks cover criterion .11.

The interview added criteria .11 and .12: verify planned-to-actual preview updates and shared-workflow edits. Change Implement's default from Luna to Sol after task creation. The overridden task retains Terra; the default task uses Sol. New step IDs do not inherit previous bindings. Repository tests verify these bindings survive reload. Both preview entry points show planned Terra before Implement starts, then its actual effective session model.

Work orders

• 01: Persist and apply task overrides
• 02: Add task-create controls and lifecycle coverage

Task 02 depends on Task 01. Execute sequentially. No delegation is authorized.

Verification

Passed on 2026-09-19:

• go test ./internal/task/models ./internal/task/repository/sqlite ./internal/task/service ./internal/task/handlers ./internal/orchestrator
• pnpm exec vitest run for the six focused frontend suites: 129 tests passed.
• pnpm run typecheck, pnpm run lint, pnpm run i18n:check, and pnpm run i18n:ratchet.
• Desktop Chromium E2E: 2 tests passed.
• Mobile Chromium E2E: 1 test passed.
• make -C apps/backend build and pnpm --filter @kandev/web build:vite.
• Public documentation and specification validators, plus git diff --check.
• Review remediation: task-read failures now stop routing, preflight, and start before side effects; create-boundary executor compatibility rejects invalid replacements before persistence; and preview revisions include task-bound replacement profiles.
• Review regressions passed: full internal/orchestrator package, task service/handler/backendapp packages, six frontend suites with 129 tests, full web lint and typecheck, and both web/backend builds.

Risks

• A missed resolver caller can make preview, credential preflight, and launch disagree.
• Profile reuse by ID must not change explicit initial/earlier-step session identity.
• Ordinary task updates must preserve the stored map across SQLite and PostgreSQL.
• Workflow snapshots can load after a selection changes. Ignore stale responses.
• Plugin create transports must not silently drop host create fields. Preserve the normal payload contract; report unsupported custom transports rather than claim success.

Documentation impact

During implementation, update docs/public/tasks-and-workflows.md as a how-to section. Explain Advanced settings, task-only scope, reset, and session reuse. Reconcile fixed-profile resolution summaries in the related system designs. No public documentation claims that this draft feature already exists.