tb_create_board

Instructions

Implementation Reference

• src/tools/task-board.ts:18-106 (handler)

  The `server.tool("tb_create_board", ...)` call registers and implements the tb_create_board tool. The handler function (lines 26-105) creates a new board in SQLite, optionally with inline tasks in a single atomic transaction. It generates a board ID, inserts the board row, and if tasks are provided, generates task IDs, resolves dependency references, and inserts all tasks within a transaction.

  server.tool(
    "tb_create_board",
    "Create a new task board for a project. Optionally include tasks inline to create board + all tasks in a single atomic call (avoids N separate tb_add_task calls).",
    {
      project: z.string().max(256).regex(/^[a-zA-Z0-9_.-]+$/).describe("Project identifier (e.g. my-project)"),
      name: z.string().max(256).describe("Board name"),
      tasks: z.array(TaskInputSchema).max(100).optional().describe("Optional: tasks to create with the board. Each task: {title, description?, priority?, spec_ref?, acceptance_criteria?, dependencies?}. Dependencies reference other task titles or indices."),
    },
    async ({ project, name, tasks }) => {
      const db = getDb();
      const boardId = generateId("board");
  
      if (!tasks || tasks.length === 0) {
        db.prepare(
          `INSERT INTO boards (id, project, name) VALUES (?, ?, ?)`
        ).run(boardId, project, name);
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ created: true, board_id: boardId, project, name, task_count: 0 }),
            },
          ],
        };
      }
  
      // Atomic: create board + all tasks in one transaction
      const insertBoard = db.prepare(
        `INSERT INTO boards (id, project, name) VALUES (?, ?, ?)`
      );
      const insertTask = db.prepare(
        `INSERT INTO tasks (id, board_id, title, description, priority, spec_ref, acceptance_criteria, dependencies, status)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
      );
  
      const taskIds: string[] = [];
      const taskIdMap: Record<string, string> = {};
  
      // Pre-generate IDs so dependencies can reference them
      for (let i = 0; i < tasks.length; i++) {
        const id = generateId("task");
        taskIds.push(id);
        taskIdMap[tasks[i].title] = id;
        taskIdMap[String(i)] = id;
      }
  
      const tx = db.transaction(() => {
        insertBoard.run(boardId, project, name);
  
        for (let i = 0; i < tasks.length; i++) {
          const t = tasks[i];
          // Resolve dependency references (by title or index) to generated IDs
          const resolvedDeps = t.dependencies.map((dep) => taskIdMap[dep] || dep);
          // Tasks with no dependencies start as "ready", others as "backlog"
          const status = resolvedDeps.length === 0 ? "ready" : "backlog";
  
          insertTask.run(
            taskIds[i],
            boardId,
            t.title,
            t.description,
            t.priority,
            t.spec_ref || null,
            t.acceptance_criteria,
            JSON.stringify(resolvedDeps),
            status
          );
        }
      });
      tx();
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              created: true,
              board_id: boardId,
              project,
              name,
              task_count: tasks.length,
              task_ids: taskIds,
            }),
          },
        ],
      };
    }
  );

• src/tools/task-board.ts:21-25 (schema)

  Input schema for tb_create_board: requires `project` (string matching /^[a-zA-Z0-9_.-]+$/, max 256), `name` (string, max 256), and optional `tasks` (array of TaskInputSchema, max 100). TaskInputSchema (lines 9-16) defines title, description, priority, spec_ref, acceptance_criteria, and dependencies.

  {
    project: z.string().max(256).regex(/^[a-zA-Z0-9_.-]+$/).describe("Project identifier (e.g. my-project)"),
    name: z.string().max(256).describe("Board name"),
    tasks: z.array(TaskInputSchema).max(100).optional().describe("Optional: tasks to create with the board. Each task: {title, description?, priority?, spec_ref?, acceptance_criteria?, dependencies?}. Dependencies reference other task titles or indices."),
  },

• src/server.ts:18-23 (registration)

  The tool registration is triggered by `registerTaskBoardTools(server)` in createServer(), which calls the function that contains the server.tool("tb_create_board", ...) call.

    registerSddTools(server);
    registerTaskBoardTools(server);
    registerFileTools(server);
  
    return server;
  }

• src/utils/id.ts:3-6 (helper)

  The `generateId` helper function generates unique IDs with a prefix (e.g., 'board-<uuid>'), used by tb_create_board to create board_id and task IDs.

  export function generateId(prefix: string = ""): string {
    const uuid = randomUUID().replace(/-/g, "");
    return prefix ? `${prefix}-${uuid}` : uuid;
  }

• src/database/index.ts:46-52 (helper)

  Database schema for the `boards` table (created via initSchema), which stores board rows with id, project, name, and timestamps.

  CREATE TABLE IF NOT EXISTS boards (
    id TEXT PRIMARY KEY,
    project TEXT NOT NULL,
    name TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
  );