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. 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-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

Workspaces (Top Level)
└── Task Initiatives (Strategic grouping)
    └── Task Projects (Cross-board coordination)
        └── Workspace Boards (Kanban boards)
            └── Task Lists (Columns)
                └── Workspace Tasks (Individual items)

1. Workspaces

Container for all workspace resources.
// Get workspace
const { data: workspace } = await supabase
  .from("workspaces")
  .select("*")
  .eq("id", wsId)
  .single();

2. Task Initiatives

Strategic initiatives grouping related projects.
CREATE TABLE task_initiatives (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  start_date date,
  end_date date,
  created_at timestamptz DEFAULT now()
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createInitiative(data: {
  wsId: string;
  name: string;
  description?: string;
  startDate?: Date;
  endDate?: Date;
}) {
  const supabase = await createClient();

  const { data: initiative, error } = await supabase
    .from("task_initiatives")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      description: data.description,
      start_date: data.startDate?.toISOString().split("T")[0],
      end_date: data.endDate?.toISOString().split("T")[0],
    })
    .select()
    .single();

  if (error) throw error;
  return initiative;
}

3. Task Projects

Cross-functional projects coordinating tasks across boards.
CREATE TABLE task_projects (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_at timestamptz DEFAULT now()
);

-- Link projects to initiatives
CREATE TABLE task_project_initiatives (
  project_id text REFERENCES task_projects(id) ON DELETE CASCADE,
  initiative_id text REFERENCES task_initiatives(id) ON DELETE CASCADE,
  PRIMARY KEY (project_id, initiative_id)
);

-- Link tasks to projects (cross-board)
CREATE TABLE task_project_tasks (
  project_id text REFERENCES task_projects(id) ON DELETE CASCADE,
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  PRIMARY KEY (project_id, task_id)
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createProject(data: {
  wsId: string;
  name: string;
  description?: string;
  initiativeIds?: string[];
}) {
  const supabase = await createClient();

  // Create project
  const { data: project, error } = await supabase
    .from("task_projects")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      description: data.description,
    })
    .select()
    .single();

  if (error) throw error;

  // Link to initiatives
  if (data.initiativeIds && data.initiativeIds.length > 0) {
    await supabase.from("task_project_initiatives").insert(
      data.initiativeIds.map((initiativeId) => ({
        project_id: project.id,
        initiative_id: initiativeId,
      })),
    );
  }

  return project;
}

export async function addTaskToProject(projectId: string, taskId: string) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_project_tasks").insert({
    project_id: projectId,
    task_id: taskId,
  });

  if (error) throw error;
}

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.

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:
ttr tasks description get <task-id>
ttr tasks description set <task-id> --file notes.md --format markdown
ttr tasks description append <task-id> --text "Follow-up note"
ttr tasks description edit <task-id>
For local conversion or debugging, use the login-free codec commands:
ttr tiptap parse --input notes.md --format markdown --output json
ttr tiptap encode --input description.json --format json --output yjs-base64
ttr tiptap decode --input state.txt --format yjs-base64 --output text

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:
ttr task-templates list --no-update-check
ttr task-templates create "Bug report" --key bug-report --title "Investigate bug"
ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md
ttr task-templates import .tuturuuu/task-templates/bug-report.md
ttr tasks create --template bug-report --list <list-id> --name "Investigate checkout bug"
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. 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.
CREATE TABLE workspace_boards (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_at timestamptz DEFAULT now()
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createBoard(wsId: string, name: string) {
  const supabase = await createClient();

  const { data: board, error } = await supabase
    .from("workspace_boards")
    .insert({
      ws_id: wsId,
      name,
    })
    .select()
    .single();

  if (error) throw error;

  // Create default lists
  const defaultLists = ["To Do", "In Progress", "Done"];

  await supabase.from("task_lists").insert(
    defaultLists.map((listName, index) => ({
      board_id: board.id,
      name: listName,
      position: index,
    })),
  );

  return board;
}

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.
CREATE TABLE task_lists (
  id text PRIMARY KEY,
  board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE,
  name text NOT NULL,
  position integer NOT NULL,
  created_at timestamptz DEFAULT now()
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function reorderLists(boardId: string, listIds: string[]) {
  const supabase = await createClient();

  // Update positions based on array order
  const updates = listIds.map((listId, index) => ({
    id: listId,
    position: index,
  }));

  for (const update of updates) {
    await supabase
      .from("task_lists")
      .update({ position: update.position })
      .eq("id", update.id);
  }
}

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.
CREATE TABLE workspace_tasks (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  list_id text REFERENCES task_lists(id) ON DELETE SET NULL,
  name text NOT NULL,
  description text,
  priority integer CHECK (priority BETWEEN 0 AND 5),
  completed boolean DEFAULT false,
  start_date date,
  due_date date,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);

Bucket Dump Feature

Rapidly capture thoughts as notes, then convert to tasks or projects.

Notes Table

CREATE TABLE notes (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  title text NOT NULL,
  content text,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now()
);

Convert Note to Task

"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function convertNoteToTask(data: {
  noteId: string;
  listId: string;
  priority?: number;
}) {
  const supabase = await createClient();

  // Get note
  const { data: note } = await supabase
    .from("notes")
    .select("*")
    .eq("id", data.noteId)
    .single();

  if (!note) throw new Error("Note not found");

  // Create task from note
  const { data: task, error } = await supabase
    .from("workspace_tasks")
    .insert({
      ws_id: note.ws_id,
      list_id: data.listId,
      name: note.title,
      description: note.content,
      priority: data.priority,
      created_by: note.created_by,
    })
    .select()
    .single();

  if (error) throw error;

  // Optionally delete note
  await supabase.from("notes").delete().eq("id", data.noteId);

  return task;
}

Convert Note to Project

"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function convertNoteToProject(data: {
  noteId: string;
  initiativeId?: string;
}) {
  const supabase = await createClient();

  const { data: note } = await supabase
    .from("notes")
    .select("*")
    .eq("id", data.noteId)
    .single();

  if (!note) throw new Error("Note not found");

  // Create project from note
  const { data: project, error } = await supabase
    .from("task_projects")
    .insert({
      ws_id: note.ws_id,
      name: note.title,
      description: note.content,
    })
    .select()
    .single();

  if (error) throw error;

  // Link to initiative if provided
  if (data.initiativeId) {
    await supabase.from("task_project_initiatives").insert({
      project_id: project.id,
      initiative_id: data.initiativeId,
    });
  }

  // Delete note
  await supabase.from("notes").delete().eq("id", data.noteId);

  return project;
}

Task Cycles (Sprints)

CREATE TABLE task_cycles (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  start_date date NOT NULL,
  end_date date NOT NULL,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to cycles
ALTER TABLE workspace_tasks
ADD COLUMN cycle_id text REFERENCES task_cycles(id) ON DELETE SET NULL;
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createCycle(data: {
  wsId: string;
  name: string;
  startDate: Date;
  endDate: Date;
}) {
  const supabase = await createClient();

  const { data: cycle, error } = await supabase
    .from("task_cycles")
    .insert({
      ws_id: data.wsId,
      name: data.name,
      start_date: data.startDate.toISOString().split("T")[0],
      end_date: data.endDate.toISOString().split("T")[0],
    })
    .select()
    .single();

  if (error) throw error;
  return cycle;
}

export async function getActiveCycle(wsId: string) {
  const supabase = await createClient();
  const today = new Date().toISOString().split("T")[0];

  const { data: cycle } = await supabase
    .from("task_cycles")
    .select("*")
    .eq("ws_id", wsId)
    .lte("start_date", today)
    .gte("end_date", today)
    .single();

  return cycle;
}

Task Estimation

CREATE TABLE task_estimates (
  task_id text PRIMARY KEY REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  type text NOT NULL, -- fibonacci, exponential, linear, tshirt
  value numeric NOT NULL,
  created_at timestamptz DEFAULT now()
);
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)
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function estimateTask(
  taskId: string,
  estimationType: "fibonacci" | "exponential" | "linear" | "tshirt",
  value: number,
) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_estimates").upsert({
    task_id: taskId,
    type: estimationType,
    value,
  });

  if (error) throw error;
}

Task Labels

CREATE TABLE task_labels (
  id text PRIMARY KEY,
  ws_id text REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  color text,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to labels (many-to-many)
CREATE TABLE task_label_assignments (
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  label_id text REFERENCES task_labels(id) ON DELETE CASCADE,
  PRIMARY KEY (task_id, label_id)
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createLabel(wsId: string, name: string, color: string) {
  const supabase = await createClient();

  const { data: label, error } = await supabase
    .from("task_labels")
    .insert({ ws_id: wsId, name, color })
    .select()
    .single();

  if (error) throw error;
  return label;
}

export async function assignLabel(taskId: string, labelId: string) {
  const supabase = await createClient();

  const { error } = await supabase
    .from("task_label_assignments")
    .insert({ task_id: taskId, label_id: labelId });

  if (error) throw error;
}

Custom Task Statuses

CREATE TABLE task_statuses (
  id text PRIMARY KEY,
  board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE,
  name text NOT NULL,
  color text,
  position integer NOT NULL,
  is_completed boolean DEFAULT false,
  created_at timestamptz DEFAULT now()
);

-- Link tasks to statuses
ALTER TABLE workspace_tasks
ADD COLUMN status_id text REFERENCES task_statuses(id) ON DELETE SET NULL;
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function createBoardWithStatuses(wsId: string, boardName: string) {
  const supabase = await createClient();

  // Create board
  const { data: board } = await supabase
    .from("workspace_boards")
    .insert({ ws_id: wsId, name: boardName })
    .select()
    .single();

  if (!board) throw new Error("Failed to create board");

  // Create default statuses
  const statuses = [
    { name: "Backlog", color: "#gray", position: 0, is_completed: false },
    { name: "To Do", color: "#blue", position: 1, is_completed: false },
    { name: "In Progress", color: "#yellow", position: 2, is_completed: false },
    { name: "Review", color: "#purple", position: 3, is_completed: false },
    { name: "Done", color: "#green", position: 4, is_completed: true },
  ];

  await supabase.from("task_statuses").insert(
    statuses.map((status) => ({
      board_id: board.id,
      ...status,
    })),
  );

  return board;
}

Task Dependencies

Track task relationships and blockers.
CREATE TABLE task_dependencies (
  task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  depends_on_task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE,
  PRIMARY KEY (task_id, depends_on_task_id),
  CHECK (task_id != depends_on_task_id)
);
Usage:
"use server";

import { createClient } from "@tuturuuu/supabase/next/server";

export async function addDependency(taskId: string, dependsOnTaskId: string) {
  const supabase = await createClient();

  const { error } = await supabase.from("task_dependencies").insert({
    task_id: taskId,
    depends_on_task_id: dependsOnTaskId,
  });

  if (error) throw error;
}

export async function getBlockedTasks(wsId: string) {
  const supabase = await createClient();

  const { data: tasks } = await supabase
    .from("workspace_tasks")
    .select(
      `
      *,
      task_dependencies!task_id (
        depends_on:workspace_tasks!depends_on_task_id (
          id,
          name,
          completed
        )
      )
    `,
    )
    .eq("ws_id", wsId)
    .eq("completed", false);

  // Filter tasks with incomplete dependencies
  return tasks?.filter((task) =>
    task.task_dependencies.some((dep: any) => !dep.depends_on.completed),
  );
}

User Interface Components

Board View

"use client";

import { trpc } from "@/trpc/client";
import { DragDropContext, Droppable, Draggable } from "@hello-pangea/dnd";

export function BoardView({
  wsId,
  boardId,
}: {
  wsId: string;
  boardId: string;
}) {
  const { data: lists } = trpc.boards.lists.useQuery({ boardId });
  const moveTask = trpc.tasks.move.useMutation();

  function handleDragEnd(result: any) {
    if (!result.destination) return;

    moveTask.mutate({
      taskId: result.draggableId,
      listId: result.destination.droppableId,
      position: result.destination.index,
    });
  }

  return (
    <DragDropContext onDragEnd={handleDragEnd}>
      <div className="flex gap-4">
        {lists?.map((list) => (
          <Droppable key={list.id} droppableId={list.id}>
            {(provided) => (
              <div
                ref={provided.innerRef}
                {...provided.droppableProps}
                className="min-w-75 bg-dynamic-gray/5 p-4 rounded-lg"
              >
                <h3>{list.name}</h3>
                {/* Task cards */}
                {provided.placeholder}
              </div>
            )}
          </Droppable>
        ))}
      </div>
    </DragDropContext>
  );
}

Best Practices

✅ DO

  1. Use hierarchy appropriately
    // Strategic: Initiative
    // Tactical: Project
    // Operational: Board → List → Task
    
  2. Leverage bucket dump
    // Capture quickly, organize later
    await createNote({ title, content });
    
  3. Set task estimates
    await estimateTask(taskId, "fibonacci", 8);
    
  4. Use labels for categorization
    await assignLabel(taskId, "bug");
    await assignLabel(taskId, "high-priority");
    
  5. Track dependencies
    await addDependency(taskId, blockerTaskId);
    

❌ DON’T

  1. Don’t create deep hierarchies
    // ❌ Bad: Too many nested levels
    
  2. Don’t skip workspace isolation
    // ❌ Bad
    .eq('id', taskId)
    
    // ✅ Good
    .eq('id', taskId).eq('ws_id', wsId)