Skip to main content

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 with deleted_at set release the name.
  • Non-deleted task list names are unique per board using lower(btrim(name)), regardless of status/category.
  • Duplicate board writes return 409 with code: "TASK_BOARD_NAME_EXISTS". Duplicate list writes return 409 with code: "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. App-session checks, cross-app token verification, and Web API allowlists should use targetApp: 'tasks' unless a route explicitly accepts another first-party audience such as the CLI’s Web-minted targetApp: 'platform' task tokens. apps/tasks is also the canonical owner for authenticated task product pages and task-owned APIs. Do not add new task UI or task API behavior to apps/web. Old authenticated Web task URLs should stay as redirects to the Tasks origin, while /products/tasks remains Web-owned marketing content. Task-owned API families include tasks, task boards, board aliases, labels, templates, projects, initiatives, cycles, drafts, task progress, plans, shared task links, admin task embeddings, task webhooks, task cron routes, Mira task endpoints, habits, and habit trackers. First-party task clients should resolve the Tasks origin through TASKS_APP_URL, NEXT_PUBLIC_TASKS_APP_URL, or TUTURUUU_TASKS_BASE_URL. Legacy TUDO_APP_URL and NEXT_PUBLIC_TUDO_APP_URL are accepted only as compatibility aliases. Local development falls back to the Tasks app origin (http://localhost:7809 or the matching portless Tasks domain). SDK, CLI, mobile, and packages/internal-api task-domain helpers should use that Tasks origin outside apps/tasks; inside apps/tasks, relative API calls are still preferred. Tasks may serve credentialed browser API traffic from first-party Web/platform origins, but CORS must stay origin-specific. Do not use wildcard credentialed CORS for task APIs.

Task Embedding Webhook Operations

The Supabase task embedding webhook must send its configured shared secret in the x-webhook-secret header. Set SUPABASE_WEBHOOK_SECRET in the Tasks deployment and use the same value in the Supabase Database Webhook header configuration. Use a secret placeholder in local examples and operational documentation; never record the deployed value. The route fails closed before parsing the payload or creating an admin Supabase client. Missing or empty server configuration returns a server configuration error, while an absent or mismatched request header returns 401 Unauthorized. CLI task commands call the Tasks origin with bearer app-session tokens minted by apps/web. The Tasks proxy must pass ttr_app_... bearer tokens to route-level withSessionAuth so the route can verify CLI scope, expiry, and target-app allowlists. Production apps/web and apps/tasks must share TUTURUUU_APP_COORDINATION_SECRET, or the same accepted fallback signing secret, or freshly minted CLI tokens will be rejected as Unauthorized. 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.

Board Capacity Rules

Board capacity rules provide reusable work-in-progress controls for task queues. Rules can select lists, labels, and projects; selector dimensions combine with AND, while labels and projects can use Any or All matching. A matching task is counted once even when several relations match. Rules can measure task count or estimation points and can count active tasks (the default) or all non-deleted tasks. Authenticated clients use these Tasks-owned routes:
  • GET/POST /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules
  • PATCH/DELETE /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules/{ruleId}
Joined workspace members and direct board guests may read capacity status. Only joined members with manage_projects may configure rules. Hard limits are enforced in PostgreSQL under a board-scoped transaction lock so browser, CLI, guest, bulk, and API writes share the same admission decision. Rejected writes return 409 with code: "TASK_CAPACITY_EXCEEDED" and structured rule usage. Successful task writes may include capacityWarnings for exceeded soft rules. Active tasks are non-deleted, not completed or closed, and outside done and closed lists. Missing estimation points contribute zero. A rule whose selected list, label, or project is deleted is disabled automatically, preventing an empty selector from accidentally broadening its scope.

Rich Text Editor Notes

The task editor includes isolated React roots inside some Tiptap node views, especially task mention chips.
  • Do not mount next-themes ThemeProvider inside those isolated createRoot(...) islands. next-themes injects 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.documentElement and prefers-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 YouTube Error 153 even when the video URL itself is valid.
  • 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.com into 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=0 or openInBrowser=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.json in 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.overridePlatformDefaultLocation enabled 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 unless app_links is allowed to normalize that URL first.

Mobile Board List Mode Notes

  • Mobile board list mode hides documents, done, and closed task 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-changed and 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:upsert with 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 onOpenChange path.

AI Journal Capture Notes

  • The quick-journal endpoint at /api/v1/workspaces/{wsId}/tasks/journal is a two-step flow: preview requests may invoke AI, but save requests that already include reviewed tasks plus a listId must 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 listId that 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_projects IDs 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 labelIds or reviewed task labels[].id in that save route must be checked against workspace_task_labels.ws_id for the normalized workspace before task rows are inserted. Foreign workspace label IDs must fail the request instead of being carried into task_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 tasks rows 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 as creator_id explicitly. 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.
Usage:

3. Task Projects

Cross-functional projects coordinating tasks across boards.
Usage:

4. Workspace Boards

Kanban-style task boards. Personal workspaces should always have a default active task board named Tasks. 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. The Tasks board header also exposes a global create action. It lists only workspaces where the caller has manage_projects, including workspaces that do not yet contain a board, and opens the newly created board immediately. In the Tasks settings dialog, each workspace can store a per-user TASK_DEFAULT_BOARD_ID. The Tasks root/proxy entrypoint validates that saved ID against active accessible boards before redirecting and falls back to the first active board when the preference is empty or stale.

Task list status semantics

Task list status 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 in tasks.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:
For local conversion or debugging, use the login-free codec commands:

Task templates

Task templates are reusable single-task starters and are intentionally separate from board templates. Store workspace templates in task_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:
Local files under .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 from CacheStore 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 virtual External tasks lane on each personal board. Explicit personal-board placements can also reference tasks from another board inside the same personal workspace; those cards are external to the destination board even though the source workspace is personal. Native tasks from the same personal board must still move through the normal workspace task route instead of the personal-placement route. 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_id points to the destination personal board after an external task is planned there.
  • personal_list_id points 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_labels and task_user_override_projects. Those rows reference labels/projects owned by the user’s personal workspace and are loaded only for that owner.
Source task fields, including 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.
Usage:

5. Task Lists

Columns within boards (e.g., “To Do”, “In Progress”, “Done”). Task boards may contain multiple closed 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.
Usage:

6. Workspace Tasks

Individual work items. Task titles support up to 1024 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)

Usage:

Task Estimation

Estimation Types:
  • 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

Usage:

Custom Task Statuses

Usage:

Task Dependencies

Track task relationships and blockers.
Usage:

User Interface Components

Board View

Best Practices

✅ DO

  1. Use hierarchy appropriately
  2. Leverage bucket dump
  3. Set task estimates
  4. Use labels for categorization
  5. Track dependencies

❌ DON’T

  1. Don’t create deep hierarchies
  2. Don’t skip workspace isolation