287 lines
18 KiB
Markdown
287 lines
18 KiB
Markdown
---
|
||
spec: docs/specs/tasks/requirements/agent-generated-titles.md
|
||
created: 2026-07-31
|
||
updated: 2026-08-02
|
||
status: done
|
||
---
|
||
|
||
# Implementation Plan: Agent-Generated Task Titles
|
||
|
||
## Overview
|
||
|
||
Waves 1–4 delivered the portable preference, backend-owned provisional-title lifecycle, task-bound MCP
|
||
mutation, conditional first-turn instruction, shared desktop/mobile dialogs, E2E coverage, and public
|
||
docs. The 2026-08-02 continuation makes that shipped flow default-on and replaces pending-only launch
|
||
gating with durable session ownership. The integration seam becomes the pair of persisted task metadata
|
||
keys: creation sets pending intent, the first eligible initial-turn launch atomically records its owner,
|
||
only that session receives title guidance and schema, and either the owner or a human title update clears
|
||
both keys.
|
||
|
||
---
|
||
|
||
## Backend
|
||
|
||
### Portable user setting
|
||
|
||
- Extend `apps/backend/internal/user/models/models.go`, `dto/dto.go`, and
|
||
`service/service.go` with `AgentGeneratedTaskTitles bool` /
|
||
`agent_generated_task_titles`, using pointer PATCH semantics and a missing-field default of `true`.
|
||
Preserve an explicitly stored `false`.
|
||
- Extend `apps/backend/internal/user/store/sqlite.go` JSON encode/decode and defaults. This remains in
|
||
the existing `users.settings` JSON blob, so no schema migration is needed.
|
||
- Project the field through `apps/backend/internal/backendapp/boot_state_routes.go` and the existing
|
||
`user.settings.updated` payload.
|
||
- Add focused store, DTO, service, event-payload, and boot-state tests beside the existing archive and
|
||
MCP-profile preference tests.
|
||
|
||
### Provisional-title creation and pending state
|
||
|
||
- Add `AutoTitle bool` to `service.CreateTaskRequest` in
|
||
`apps/backend/internal/task/service/service_requests.go` and define
|
||
`models.MetaKeyAgentTitlePending = "agent_title_pending"` and
|
||
`models.MetaKeyAgentTitleOwnerSessionID = "agent_title_owner_session_id"` in
|
||
`apps/backend/internal/task/models/models.go`.
|
||
- In `apps/backend/internal/task/service/service_tasks.go`, add a rune-safe helper that trims the
|
||
prompt, selects the first six entries from `strings.Fields`, and joins them with one space. Shorter
|
||
prompts use every word; there is no normal character truncation or ellipsis. Preserve the existing
|
||
absolute 500-character task-title safety boundary. When `AutoTitle` is true, reject an empty
|
||
normalized prompt, replace the request title with the derived value, and add the pending metadata
|
||
before the task row is inserted.
|
||
- Add `auto_title` to `httpCreateTaskRequest` in
|
||
`apps/backend/internal/task/handlers/task_http_handlers.go`. Preserve the existing required-title
|
||
path when it is false; pass the opt-in to the service when true.
|
||
- Make an ordinary `Service.UpdateTask` call with a non-nil title remove both title-lifecycle keys
|
||
before its single task-row update. Add a task-service method for the MCP path that validates the
|
||
500-character title limit, accepts only a pending task whose persisted owner matches the
|
||
server-injected session ID, updates title and metadata atomically, and publishes the standard
|
||
`task.updated` event.
|
||
- Cover whitespace normalization, six-word selection, shorter prompts, the existing absolute title
|
||
limit, empty prompt rejection, top-level and subtask creation, restart-durable metadata, ordinary
|
||
rename precedence, repeated agent calls, and update-event publication in `service_tasks_test.go` and
|
||
focused HTTP handler tests.
|
||
|
||
### Task-mode MCP tool
|
||
|
||
- Add internal `mcp.set_task_title` action plumbing in `apps/backend/pkg/websocket/actions.go`,
|
||
`apps/backend/internal/mcp/server/handlers.go`, and
|
||
`apps/backend/internal/mcp/handlers/handlers.go`.
|
||
- Add a title-pending task-mode variant in `apps/backend/internal/mcp/server/server.go`. It registers all
|
||
regular task tools plus `set_task_title_kandev`; regular `ModeTask` and restricted modes omit the new
|
||
tool entirely. Its public schema has one required `title`; the server injects `s.taskID` into the
|
||
internal payload and never accepts a caller-selected task ID. Write both the tool description and
|
||
`title` argument description to target about six words in sentence case and use a short title phrase
|
||
rather than a sentence or progress update, and clarify that the existing title is provisional and must
|
||
still be replaced.
|
||
- Extend `resolveTaskSessionMCPMode` in
|
||
`apps/backend/internal/orchestrator/executor/executor_execute.go` to select the existing title-pending
|
||
task mode only when `agent_title_pending` is true and `agent_title_owner_session_id` equals the
|
||
launching session. Config and Office modes win. Keep the existing internal mode string stable and
|
||
thread it through the existing agentctl mode validation/configuration path without another flag.
|
||
- Return accepted task/title data on success, an idempotent
|
||
`{accepted:false, reason:"title_not_pending"}` when the marker is absent, and
|
||
`{accepted:false, reason:"title_not_owner"}` when the bound session is not the owner. Preserve
|
||
validation and authorization errors from the task service.
|
||
- Update regular/pending/restricted-mode catalog tests, MCP mode API tests, executor mode-resolution
|
||
tests, handler forwarding tests, MCP integration tests, and the raw-WebSocket MCP-prefix regression
|
||
inventory. Assert that ordinary task mode does not include the new tool schema.
|
||
|
||
### Conditional first-turn instruction
|
||
|
||
- Add a SQLite/PostgreSQL-safe task repository compare-and-set that persists exactly one owner while
|
||
pending. It must distinguish a new claim, an idempotent same-session claim, and a denied claim; the
|
||
orchestrator publishes `task.updated` only when it newly persists ownership. Claim failure aborts the
|
||
launch before prompt persistence/composition, title-capable MCP configuration, or agent-process
|
||
startup. Workspace/agentctl-only preparation stays in ordinary task mode and does not claim.
|
||
- Claim after a concrete session exists and its task/config/Office eligibility is known, but before the
|
||
initial turn is recorded or wrapped. Route direct starts, prepared-session starts, message-start,
|
||
workflow auto-start, structured prompts, and passthrough prompts through the same ownership helper.
|
||
Pre-wrapping paths may call it before `StartCreatedSession`; the repeated same-session call is
|
||
idempotent.
|
||
- Audit every `StartAgent: true`, resume, and execution-profile switch path. A pending unowned session
|
||
must be claimed before its first agent process starts; an already owned session resolves title mode
|
||
only when its ID matches the owner. Workspace-only `StartAgent: false` preparation never exposes the
|
||
title mode.
|
||
|
||
- Add a conditional placeholder to `apps/backend/config/prompts/kandev-context.md` that emits both the
|
||
`set_task_title_kandev` inventory entry and first-call instruction only for title-pending task mode.
|
||
- Extend `sysprompt.KandevContextOptions` in `apps/backend/internal/sysprompt/sysprompt.go` with the
|
||
pending-title capability. The instruction says to call the tool before any other work or tool call,
|
||
even though a provisional title already exists, and requests a short title phrase targeting about six
|
||
words in sentence case rather than a sentence or progress update. It remains absent when the marker is
|
||
not true.
|
||
- Pass the claim result—not a fresh pending-only check—through every first-turn composition path in
|
||
`apps/backend/internal/orchestrator/task_operations.go`,
|
||
`event_handlers_workflow.go`, and
|
||
`apps/backend/internal/task/handlers/message_handlers.go`. Keep canonicalization and trusted-context
|
||
handling intact.
|
||
- For passthrough sessions, prepend the equivalent short instruction only while pending; do not add the
|
||
full task MCP boilerplate that passthrough intentionally skips.
|
||
- Preserve both internal metadata keys against stale task snapshots while pending, and exclude both
|
||
from stale merge payloads after a human or owner resolution so neither key can be resurrected.
|
||
- Extend sysprompt placeholder/canonicalization tests, orchestration launch/auto-start tests, and
|
||
`apps/backend/internal/mcp/server/sysprompt_sync_test.go` so prompt references and registered mode
|
||
catalogs cannot drift. Explicitly prove that ordinary tasks get neither prompt text nor tool schema.
|
||
|
||
---
|
||
|
||
## Frontend
|
||
|
||
### User setting and hydration
|
||
|
||
- Add `agentGeneratedTaskTitles` to `UserSettingsState` and its default (`true`) in
|
||
`apps/web/lib/state/slices/settings/types.ts` and `settings-slice.ts`.
|
||
- Add `agent_generated_task_titles` to `apps/web/lib/types/http-user-settings.ts`, boot/SSR mapping in
|
||
`apps/web/lib/ssr/user-settings.ts`, WS mapping in `apps/web/lib/ws/handlers/users.ts`, and any shared
|
||
settings edit-state mapper that enumerates portable fields.
|
||
- Add `apps/web/components/settings/agent-generated-task-title-settings.tsx` under
|
||
`TaskActionsSettings`. Register it with `useSettingsSaveContributor`, and explain visibly that the
|
||
title input disappears for new tasks/subtasks, a prompt is required, a provisional title from the
|
||
prompt's first six words appears immediately, and the fallback remains if the agent cannot rename it.
|
||
- Add focused component, SSR, store/hydration, and WS mapping tests.
|
||
|
||
### New Task dialog
|
||
|
||
- Read the preference once from the hydrated app store and thread an `autoTitle`/`requiresManualTitle`
|
||
contract through `task-create-dialog.tsx`, form-body props, footer props, submit handlers, and
|
||
`buildCreateTaskPayload`.
|
||
- In create mode with the preference enabled, suppress `InlineTaskName`, focus the description input,
|
||
disable all creation variants until the prompt has content, omit the manual title, and send
|
||
`auto_title: true`. Edit mode and session-only mode retain their existing title behavior.
|
||
- Ensure GitHub/Jira/Linear title autofill does not become a hidden source of truth in auto-title mode.
|
||
Voice auto-send, create-only, plan-mode, repository selection, and task-create-last-used persistence
|
||
continue through the shared submit path.
|
||
- Update helper, footer, payload-builder, form-body, state, and dialog tests for enabled/disabled/edit
|
||
cases and empty-prompt gating.
|
||
|
||
### New Subtask dialog and mobile contract
|
||
|
||
- Read the same preference in `new-subtask-dialog.tsx`. When enabled, omit the title state/input from
|
||
`new-subtask-form-parts.tsx`, require the existing prompt, and have `use-subtask-submit.ts` send
|
||
`auto_title: true` without a manual title. When disabled, preserve the proposed
|
||
`Parent / Subtask N` title and editable input.
|
||
- Keep the existing full-height phone dialogs, fixed headers/footers, internal scroll owner, safe-area
|
||
behavior, and touch-sized actions. No new drawer or route is needed: the prompt simply becomes the
|
||
first editable field in the existing task and subtask surfaces.
|
||
- Use the shipped `TaskCreateDialog` and `NewSubtaskDialog` phone compositions as the mobile exemplars;
|
||
share all preference, payload, validation, and submit logic across viewports.
|
||
- Add component/hook tests for both setting states and payloads.
|
||
|
||
---
|
||
|
||
## Tests
|
||
|
||
- **What:** portable preference defaults true when missing, PATCH preserves omitted and explicit-false
|
||
values, and boot/WS payloads carry it. **Files:** user store/DTO/service tests, backend boot-state
|
||
tests, frontend SSR/WS/settings tests. **How:** table-driven Go JSON tests plus Vitest
|
||
mapping/component tests.
|
||
- **What:** provisional title whitespace normalization, first-six-word selection, shorter prompts,
|
||
empty-prompt rejection, and pending metadata persistence. **Files:**
|
||
`apps/backend/internal/task/service/service_tasks_test.go` and task HTTP handler tests. **How:**
|
||
table-driven service tests and handler-to-service integration.
|
||
- **What:** ordinary title edits win, the first pending MCP title succeeds, repeats are idempotent, and
|
||
`task.updated` is published. **Files:** task-service and MCP handler tests. **How:** real repository +
|
||
event bus tests and WS action handler tests.
|
||
- **What:** ordinary task sessions receive no title prompt/tool schema, while pending-task catalog and
|
||
conditional first-turn instruction stay aligned across direct launch, workflow auto-start,
|
||
message-start, and passthrough. **Files:** MCP server/sysprompt/executor/orchestrator/task handler
|
||
tests. **How:** regular-versus-pending catalog assertions include the six-word sentence-case target,
|
||
and captured launch-prompt tests verify the same gating, guidance, and call ordering.
|
||
- **What:** two concurrent initial-turn launches produce one durable owner; owner retry is idempotent;
|
||
non-owner, config, Office, External, and merely prepared sessions never claim; owner failure does not
|
||
reassign; human/agent resolution clears both keys; stale updates cannot restore them. **Files:** task
|
||
repository/service, executor, orchestrator, message handler, and MCP handler tests. **How:** real
|
||
SQLite concurrency tests, environment-gated PostgreSQL parity, and captured launch/catalog tests.
|
||
- **What:** enabled/disabled UI states produce the correct title visibility, validation, and HTTP
|
||
payload for tasks and subtasks. **Files:** focused `*.test.ts(x)` files beside settings and dialogs.
|
||
**How:** Vitest component/hook tests with mocked API calls.
|
||
|
||
## E2E Tests
|
||
|
||
- **Scenario:** GIVEN a fresh or field-missing preference, WHEN Settings and task/subtask creation load,
|
||
THEN the toggle is enabled and prompt-first behavior is active; GIVEN an explicit opt-out, the manual
|
||
title flow remains. Keep the shared E2E fixture explicitly opted out so unrelated manual-title tests
|
||
retain their intended baseline. **Files:** existing desktop/mobile agent-title specs and
|
||
`apps/web/e2e/fixtures/test-base.ts`.
|
||
|
||
- **Scenario:** GIVEN the setting is enabled, WHEN a user creates a task from the desktop dialog, THEN
|
||
the title input is absent, empty prompt is blocked, and the six-word provisional title appears.
|
||
Backend service/MCP tests cover the mock-agent `set_task_title_kandev` replacement and its
|
||
idempotent late-call behavior. **File:**
|
||
`apps/web/e2e/tests/task/agent-generated-task-titles.spec.ts`.
|
||
- **Scenario:** GIVEN the setting is enabled on a phone viewport, WHEN the user opens the subtask
|
||
creation surface, THEN the prompt is reachable and usable without a title control, actions remain
|
||
within the viewport, and the document has no horizontal overflow. The shared task dialog contract is
|
||
covered by focused frontend tests. **File:**
|
||
`apps/web/e2e/tests/task/mobile-agent-generated-task-titles.spec.ts`.
|
||
- **Scenario:** GIVEN the user saves the setting and reloads, WHEN they reopen task creation, THEN the
|
||
enabled behavior persists. **File:** desktop spec; restore the prior user setting in `afterEach`.
|
||
|
||
## Public documentation
|
||
|
||
- Update `docs/public/tasks-and-workflows.md` with the default-on setting, explicit opt-out, single-owner
|
||
fallback lifecycle, empty-prompt rule, and manual-rename fallback.
|
||
- Update `docs/public/coordination.md` so subtask title requirements describe both setting states.
|
||
- Update `docs/public/automation-and-mcp.md`, `docs/public/agent-communication.md`, and
|
||
`docs/public/coverage.json` with the task-bound `set_task_title_kandev` contract, six-word
|
||
sentence-case target, exactly-one-session ownership, and mode boundary.
|
||
- Validate public docs with `node --test scripts/validate-public-docs.test.mjs` and
|
||
`node scripts/validate-public-docs.mjs`.
|
||
|
||
---
|
||
|
||
## Implementation Waves And Parallel Candidates
|
||
|
||
The default execution order is sequential in the primary conversation. These waves do not authorize
|
||
subagents.
|
||
|
||
Wave 1:
|
||
- [x] [Task 01: Backend preference and provisional-title lifecycle](task-01-backend-title-lifecycle.md) — done
|
||
|
||
Wave 2:
|
||
- [x] [Task 02: Task MCP tool and first-turn instruction](task-02-mcp-title-tool.md) — done
|
||
|
||
Wave 3:
|
||
- [x] [Task 03: Settings and task/subtask dialogs](task-03-frontend-title-flow.md) — done
|
||
|
||
Wave 4:
|
||
- [x] [Task 04: End-to-end coverage and public docs](task-04-e2e-and-docs.md) — done
|
||
|
||
Wave 5:
|
||
- [x] [Task 05: Single-owner title handoff](task-05-single-owner-title-handoff.md) — done
|
||
|
||
Wave 6:
|
||
- [x] [Task 06: Default-on title preference](task-06-default-on-title-preference.md) — done
|
||
|
||
Wave 7:
|
||
- [x] [Task 07: Regression coverage and public docs](task-07-regression-and-docs.md) — done
|
||
|
||
## Previous shipped verification
|
||
|
||
- Backend focused tests: 3,665 passing across 15 affected packages; MCP server tests: 149 passing.
|
||
|
||
## Completion
|
||
|
||
- [x] [Task 05: Single-owner title handoff](task-05-single-owner-title-handoff.md) — done
|
||
- [x] [Task 06: Default-on title preference](task-06-default-on-title-preference.md) — done
|
||
- [x] [Task 07: Regression coverage and public docs](task-07-regression-and-docs.md) — done
|
||
|
||
The continuation was verified with focused backend tests, full backend FTS5 race tests,
|
||
golangci-lint, targeted frontend tests and lint, and public-document validators. PostgreSQL parity
|
||
remains environment-gated and was not run locally because no test DSN was available; the existing PR
|
||
E2E checks passed at the prior head and the shared fixture now opts those scenarios out explicitly.
|
||
- Backend lint: `make -C apps/backend lint` — 0 issues.
|
||
- Frontend focused Vitest suite: 98 passing across 9 files.
|
||
- Frontend lint and TypeScript typecheck — passing.
|
||
- Desktop and mobile Playwright scenarios — 1 passing each.
|
||
- Public documentation tests and validator — 58 tests passing; 41 published pages validated.
|
||
|
||
## Extension verification
|
||
|
||
- [x] SQLite repository, service, orchestrator, executor, task-handler, and MCP tests prove atomic
|
||
one-owner claims and owner-bound title compare-and-set behavior.
|
||
- [x] User-store and frontend mapping tests prove missing/default `true` and explicit `false`
|
||
preservation.
|
||
- [x] Backend race suite, backend lint, frontend lint, targeted frontend tests, and public-doc
|
||
validation passed.
|
||
- [ ] PostgreSQL parity and the new desktop/mobile browser runs remain CI/environment-gated.
|