Tasks - Smart Task Management
Tasks is Tuturuuu’s intelligent task management system featuring a 6-level hierarchy, bucket dump for rapid capture, and cross-board project coordination.Overview
Tasks provides:- Hierarchical organization - 6 levels from workspaces to individual tasks
- Bucket dump - Capture notes and convert to tasks/projects
- Cross-board projects - Coordinate tasks across multiple boards
- Task cycles - Sprint/iteration management
- Smart estimation - Fibonacci, exponential, linear, and t-shirt sizing
- Custom statuses - Per-board status workflows
- Labels & priorities - Flexible categorization
Board And List Name Uniqueness
- Active and archived task board names are unique per workspace using
lower(btrim(name)); only trashed boards withdeleted_atset release the name. - Non-deleted task list names are unique per board using
lower(btrim(name)), regardless of status/category. - Duplicate board writes return
409withcode: "TASK_BOARD_NAME_EXISTS". Duplicate list writes return409withcode: "TASK_LIST_NAME_EXISTS". - Existing duplicate rows are preserved by the forward migration that renames older duplicates with a deterministic
(duplicate <id>)suffix before the unique indexes are created. The migration does not move or delete tasks.
Satellite Auth And API Ownership
apps/tasks is registered internally as the tasks app. All app-session
checks, cross-app token verification, and Web API allowlists must use
targetApp: 'tasks'.
The local /api/auth/verify-app-token route must delegate token validation to
the central Web verifier with verificationBaseUrl: TTR_URL. That handoff sets
both the host-only Tasks app-session cookie and the Web-issued app-session
cookie used by central API requests. Do not reintroduce Tasks-local Supabase
session validation for cross-app login.
Tasks must also keep a local /login page. It is a redirect-only route: valid
Tasks app-session cookies continue to /personal/tasks or the safe next
path, while missing or stale cookies redirect to apps/web login with a
/verify-token return URL. Without this route, a successful Web handoff can set
cookies and still leave the browser on a Next.js 404.
The Tasks app should not authenticate protected product APIs with local
Supabase Auth cookies. Fallback /api/* traffic is proxied through the local
catch-all API route, which strips sb-*-auth-token cookies before forwarding to
Web. Keep the corresponding Web routes app-session aware for
targetApp: 'tasks'; otherwise the browser can have valid Tasks cookies while
the data layer still loops through 401 and proxy-side 429 responses.
Task board/list count endpoints must compute counts in the database, preferably
through private service-role RPCs, and return one aggregate row per board/list.
Do not hydrate every matching tasks row in an API route just to count them.
Rich Text Editor Notes
The task editor includes isolated React roots inside some Tiptap node views, especially task mention chips.- Do not mount
next-themesThemeProviderinside those isolatedcreateRoot(...)islands.next-themesinjects an inline script, and Next.js 16 will warn or fail when that script is rendered from a client subtree instead of the app root. - Resolve theme for those islands from
document.documentElementandprefers-color-scheme, then pass that resolved value through local component state instead of re-creating app-wide providers. - Add
referrerPolicy="strict-origin-when-cross-origin"to every YouTube iframe path used by the task editor or its previews. Missing referrer policy can surface as YouTubeError 153even when the video URL itself is valid.
Task Link Notes
- Canonical deep links for board tasks should use the board route with the task query parameter:
/{wsId}/tasks/boards/{boardId}?task={taskId}. - Tuturuuu Mobile normalizes production web links from
https://tuturuuu.cominto native routes for task boards, board task details, task estimates, task portfolio/project routes, and common workspace modules. Mobile accepts both?task={taskId}from web and?taskId={taskId}from native routes. - Links can opt out of native app opening with
native=0oropenInBrowser=1. Use this for flows that must stay in the browser, such as debugging, web-only admin surfaces, or temporary compatibility issues. - Avoid generating or persisting modal-only URLs such as
/{wsId}/tasks/{taskId}for share/copy flows unless the dedicated task detail page is the explicit target. The board-backed URL is the reliable reloadable path used by the dashboard task dialog. - When reloading or recovering a task deep link, resolve the task through the workspace-scoped task API (
/api/v1/workspaces/{wsId}/tasks/{taskId}) rather than the current-user task dialog API. The current-user endpoint can 404 for valid board tasks because it is optimized for dialog hydration, not route recovery. - Android opens supported links by default only after App Links verification succeeds. Keep
apps/web/public/.well-known/assetlinks.jsonin sync with the production Android signing certificate fingerprint; if Play App Signing uses a different app-signing certificate than the repo release keystore, add the Play Console SHA-256 fingerprint before release. - Keep
GoRouter.overridePlatformDefaultLocationenabled in mobile. iOS can provide a universal link URL as Flutter’s platform default route on cold start, and GoRouter will show a no-route page unlessapp_linksis allowed to normalize that URL first.
Mobile Board List Mode Notes
- Mobile board list mode hides
documents,done, andclosedtask lists by default when no explicit list or status filter is selected. - The filter sheet must disclose that default exclusion and indicate when a selected list/status filter overrides it, because those filters intentionally reveal otherwise hidden list categories.
- Moving a task between lists, including marking it done or closed, should refresh the affected source and destination lists instead of relying on a full board reload.
Task Board Realtime And Cache Notes
- Successful task mutations must update visible TanStack Query caches in place before broadcasting. Patch all visible task shapes that can render the same card:
['tasks', boardId], every['tasks-full', boardId, ...]query,['task', taskId], matching['workspaceTask', wsId, taskId], and personal task buckets when present. - Relation-only updates for labels, projects, and assignees should broadcast
task:relations-changedand call the active board refresh with{ invalidateTasks: false }. Do not invalidate['tasks', boardId]or['tasks-full', boardId]after successful relation-only changes; refetching those visible arrays causes card flicker while the optimistic cache already has the relation data. - Scalar task changes such as priority, dates, estimate, name, and list should patch visible task caches and broadcast
task:upsertwith the changed fields. Rollbacks should restore snapshots of the touched task ids instead of invalidating the whole board task cache. - Realtime receivers may reconcile task detail, history, counts, and personal task queries in the background. The board page should revalidate loaded progressive-list data without invalidating visible task arrays so shared boards stay current without remounting cards.
- Task edit dialogs should keep dropdowns and popovers controlled from a single active overlay id within each dialog section. Opening another menu must close the previous one, and outside-click/Escape close behavior should flow through the same
onOpenChangepath.
AI Journal Capture Notes
- The quick-journal endpoint at
/api/v1/workspaces/{wsId}/tasks/journalis a two-step flow: preview requests may invoke AI, but save requests that already include reviewedtasksplus alistIdmust persist directly. - Do not re-resolve the AI model, re-check credits, or regenerate tasks during that save step. A successful preview must be able to save even if model allocation changes afterward.
- When the destination picker allows switching workspaces, clear the currently selected board/list immediately in the same UI event before loading the new workspace boards. Effect-only cleanup is too late for save flows and can send a stale
listIdthat belongs to a different workspace. - If the final create request fails, reopen the destination-selection step with the reviewed tasks still in memory. Do not clear the journal draft optimistically before the insert succeeds, or users can lose the prompt they just refined.
- Any workspace alias accepted by the board/list bootstrap endpoints, such as
personal, must also be normalized by the journal save route before membership and list checks. Otherwise the picker can show valid destinations while the final save still rejects the same workspace context. - The journal save route should verify workspace membership first with the request-scoped client, then validate the chosen list against that normalized workspace. Admin-backed list checks are fine for consistency with selector data, but they must never bypass the caller’s workspace access gate.
- Any workspace-scoped project validation in that same save route should follow the same pattern: verify membership with the request-scoped client first, then resolve valid
task_projectsIDs through the admin client scoped to the normalized workspace. Do not read protected workspace project tables directly from the caller-scoped client after access has already been established. - Any top-level
labelIdsor reviewed tasklabels[].idin that save route must be checked againstworkspace_task_labels.ws_idfor the normalized workspace before task rows are inserted. Foreign workspace label IDs must fail the request instead of being carried intotask_labels; labels created by name can still be upserted through the admin-backed workspace path after membership passes. - After membership passes, persist the journal-created
tasksrows and their relation-table writes (task_labels,task_project_tasks,task_assignees, label upserts) through the same admin-backed workspace path, and stamp actor-owned columns such ascreator_idexplicitly. Do not mix admin-backed validation with caller-scoped writes or the save step can still fail with table-level permission errors.
Task Hierarchy
1. Workspaces
Container for all workspace resources.2. Task Initiatives
Strategic initiatives grouping related projects.3. Task Projects
Cross-functional projects coordinating tasks across boards.4. Workspace Boards
Kanban-style task boards. Personal workspaces should always have a default active task board namedTasks. Web and mobile task-board listing APIs ensure that board exists before
returning board data, so users should not see a prompt just to bootstrap their
personal task workflow. Mobile opens that default board directly from both the
Tasks and Boards surfaces unless the user disables default task-board navigation
in mobile Settings. The web settings dialog exposes the same preference for the
Boards page, keeping the board picker available for users who prefer the
previous flow.
Task list status semantics
Task liststatus is a workflow category, not the list display name. The
review status sits between active and done: moving a task into a review
list resolves the task for deadline/reminder filtering, but it must not set
completed, completed_at, or closed_at. Review tasks should keep the same
unchecked checkbox and non-completed visual treatment used by active tasks.
Review lists are for walkthrough or acceptance queues. Task cards in review,
done, or closed lists should not show due-date or overdue treatment because
those tasks are already resolved for deadline purposes. Mobile list mode still
shows review lists by default; only documents, done, and closed are
hidden when no explicit list or status filter is selected.
Task description realtime
Task descriptions use a Yjs CRDT document stored intasks.description_yjs_state. Once that state exists, treat it as the
authoritative collaborative source. The JSON tasks.description field is the
read/search/cache projection and must not overwrite a valid Yjs state just
because it differs; board caches and recently opened dialogs can hold stale
description JSON while another collaborator has newer Yjs edits.
Initialization or repair writes that seed the local Yjs document from persisted
state must use the provider sync origin so those changes are not broadcast as
fresh user edits. Persistence should serialize the description projection from
the Yjs update being saved, keeping description and description_yjs_state
from diverging under multi-user edit churn.
The ttr CLI uses the same description endpoint and TipTap/Yjs codec as the web
editor. Prefer first-class description commands over raw task update payloads:
Task templates
Task templates are reusable single-task starters and are intentionally separate from board templates. Store workspace templates intask_templates with
creator ownership, private or workspace visibility, archived timestamps,
default board/list ids, priority, dates, estimate, labels, assignees, projects,
and optional TipTap/Yjs description state.
Template API routes live under
/api/v1/workspaces/{wsId}/task-templates. They must accept authenticated
workspace members and tasks app-session JWTs from ttr, reject direct
task-board guests, and keep private templates readable only by their creator.
Workspace-visible template mutation should follow the task/project management
permission used by task-board management flows; private template mutation stays
scoped to the member owner.
The web templates hub at /{locale}/{wsId}/tasks/templates should default to
the Task Templates tab while preserving Board Templates as the secondary tab and
keeping existing board-template detail links stable.
The CLI supports both workspace-stored and local markdown templates:
.tuturuuu/task-templates/*.md use YAML frontmatter for
template fields and the markdown body as the task description. Explicit
ttr tasks create flags must override template defaults so users can reuse a
starter without losing the current task context.
Mobile board caching
The mobile task-board flow restores workspace boards, board metadata, and per-list task pages fromCacheStore before network revalidation. Board detail pages
prefetch the first three lists on open and the focused Kanban list plus the next
two lists on horizontal page changes, so column swipes should not wait for one
on-demand request at a time. Cached task-page payloads must preserve the display
metadata used by cards, including assignees, labels, projects, and relationship
summaries.
The mobile board List tab hides tasks in done and closed lists by default.
Explicit status filters or list filters are treated as user intent and can show
those terminal lists again.
Mobile task details open description in a read-first fullscreen surface. Keep
that surface borderless and height-bounded under the task title, with editing
entered only from the edit FAB and save actions kept inside the editor chrome.
Task create/update API routes silently drop assignee ids that no longer belong
to the workspace. This lets stale task assignments be cleaned up during the next
save instead of blocking unrelated edits such as description updates.
Timeline board view
The task board Timeline is task-first:TimelineBoard keeps its public props
stable for board and project views, while the internal model renders one
scheduled task per readable row grouped by task list. Task titles and source
metadata belong in the sticky left column; timeline bars should communicate the
date range only, so narrow zoom levels never hide task names behind clipped bar
labels.
Keep drag, resize, schedule-from-unscheduled, edit, delete, and context-menu
actions routed through the same board mutation path used by the other views.
The row model must preserve personal and external task metadata and keep
unknown-list tasks grouped under the virtual unknown-list section instead of
dropping them from the schedule.
Personal external tasks
Personal task boards can reference tasks from other workspaces without cloning or moving the source task. Assigned tasks from accessible source workspaces appear by default in a virtualExternal tasks lane on each personal board.
The tasks API may use the server-side admin client to hydrate candidate source
tasks, but it must filter those rows through the current user’s source
workspace_members rows with type = 'MEMBER' before returning personal
default or placed external cards. A guest row in the source workspace is not
enough to reveal task data through the personal board.
The virtual lane is presentation-only: it has no task_lists row, no list
actions, no create-task form, no list reordering, and can be collapsed per board
when the user wants to focus on planned lists. Personal boards default the lane
to collapsed when the board has no assigned external task references; once
assigned external tasks exist, the lane opens by default unless the user has
saved an explicit collapsed or expanded preference for that board.
By default the external lane shows only open source tasks from normal task
lists. Source tasks in documents, review, done, or closed lists are
filtered out unless the lane-level compact filters explicitly include resolved
tasks. Lane sorting is
also local to the external lane, so changing it does not reorder the user’s real
personal lists.
External task cards should show the source workspace and the source board’s
ticket identifier. Opening an external task must resolve the task by id through
the current-user task route so the dialog receives the source workspace, source
board, and source lists instead of the personal board context.
Per-user placement lives on task_user_overrides with personal_board_id,
personal_list_id, personal_sort_key, personal_added_at, and
personal_placed_at.
Placement writes must go through upsert_personal_task_placement. Drag clients
should pass the previous and next visible task ids when available, and the RPC
uses calculate_personal_task_placement_sort_key to compute a sort key against
the combined personal list of native personal tasks and placed external task
references.
Per-list task loading for personal boards must include the personal boardId
alongside listId; the API needs both values to load placed external
references for real personal lists and to keep already-placed external tasks out
of the virtual external lane.
Optimistic personal-placement moves must keep a fresh _localMutationAt marker
after the placement API response is merged. Loaded-list revalidation may still
return a pre-move page briefly, and the marker prevents that stale response from
evicting the placed external task until the server view catches up.
Optimistic placement writes should upsert the task into both the progressive
board task cache and any full-board cache that is already mounted, because stale
list reloads can briefly remove the card before the destination list refetches.
The card renderer should hide only the active pre-drop drag source; once a
placement mutation is optimistic, the real destination card must stay visible
even if the sortable layer still reports that task id as dragging.
Native task reorders and external personal-placement moves should both stamp a
fresh _localMutationAt marker on optimistic writes and on the server-confirmed
cache merge. Progressive list loading treats that marker as authority for
movement fields such as list_id, sort_key, personal_list_id, and
personal_sort_key, which prevents stale list pages from flashing a card back
to its previous position while the mutation response is still settling.
Personal-board list badges must use exact includeCount responses, not a
page-size estimate from progressive loading. External reference counts should be
resolved through get_personal_task_board_external_counts so placed external
tasks, default external-lane tasks, source-workspace access, and external-lane
filters stay aligned with the records the board can actually show.
Board source filters use TaskFilters.sourceScope to decide which task source
set is visible. all_visible preserves the existing board behavior,
current_board returns only tasks from the active board, and the two external
scopes return assigned-to-me tasks whose source board is not the active board.
external_current_workspace stays inside the current workspace, while
external_specific requires selected source workspace ids or source board ids;
when nothing is selected, the client should show an empty prompt instead of
running an unbounded external query.
Source-filtered list and timeline reads must go through the tasks API route,
which normalizes the route workspace, verifies request-scoped membership, then
uses the server-side Supabase admin client to call the
private.list_task_source_filter_ids RPC. The RPC rechecks target workspace
membership and source workspace access before returning paginated task ids plus
total_count for API-side hydration. Client UI must not call the private RPC
directly or trust client-provided source ids as authorization.
personal_board_idpoints to the destination personal board after an external task is planned there.personal_list_idpoints to the real personal list that owns the planning position.- Dragging from the virtual lane into a real personal list creates or updates the personal placement.
- Dragging a placed external task back to the virtual lane removes the personal placement so the task returns to the default external view.
- Personal-only label and project overlays live in
task_user_override_labelsandtask_user_override_projects. Those rows reference labels/projects owned by the user’s personal workspace and are loaded only for that owner.
tasks.list_id, task_labels, and
task_project_tasks, must not be changed when a task appears in the external
lane, is planned into a personal list, is moved within the personal board, or
returns to the external lane unless the personal move changes the task’s
workflow status. Routes that read personal board tasks should keep filtering
inaccessible source tasks out instead of surfacing stale placements to users who
no longer have source-workspace access.
When a placed external task moves to a personal list with a different workflow
status, the source task must also move to the first matching list on its original
board. done and closed targets require the matching terminal source list.
Non-terminal targets first try the same source status, then fall back to
active and not_started lists so tasks moved out of source done or closed
queues do not keep completed or closed card state.
5. Task Lists
Columns within boards (e.g., “To Do”, “In Progress”, “Done”). Task boards may contain multipleclosed lists when teams need distinct terminal buckets such as Abandoned, Not Planned, or Duplicate. Treat closed as a status group for sorting/reporting, not a singleton board column.
6. Workspace Tasks
Individual work items. Task titles support up to1024 characters. Keep task-only validation on the dedicated task-title limit rather than the generic name limit so task routes, drafts, and database checks stay aligned.
Bucket Dump Feature
Rapidly capture thoughts as notes, then convert to tasks or projects.Notes Table
Convert Note to Task
Convert Note to Project
Task Cycles (Sprints)
Task Estimation
- Fibonacci: 1, 2, 3, 5, 8, 13, 21
- Exponential: 1, 2, 4, 8, 16, 32
- Linear: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
- T-Shirt: XS (1), S (2), M (3), L (5), XL (8), XXL (13)
Task Labels
Custom Task Statuses
Task Dependencies
Track task relationships and blockers.User Interface Components
Board View
Best Practices
✅ DO
-
Use hierarchy appropriately
-
Leverage bucket dump
-
Set task estimates
-
Use labels for categorization
-
Track dependencies
❌ DON’T
-
Don’t create deep hierarchies
-
Don’t skip workspace isolation