Card descriptions

A card can carry a description: the task, written out as Markdown text. You write it once, and when the card's agent starts fresh it is asked to read it and check with you before it starts. Agents can also hand tasks to each other through descriptions. This page explains how to write one and how it reaches the agent.

Write a description

There are four ways to give a card a description:

• the Description field of the New card dialog, when you create it;
• Edit description… in the card's ⋯ menu, at any time;
• Edit description… in the command palette, for the card that is open;
• board describe (or board create --description-file) from a terminal, which is how agents write them; see below.

The field is plain multi-line text with the placeholder Markdown, optional. Enter starts a new line; Cmd+Enter on macOS (Ctrl+Enter on Linux) saves, as does Save (or Create in the New card dialog). Esc and Cancel change nothing.

Changing a description only changes what is stored: nothing is typed into a running card. An agent that is already running sees the new text the next time it reads the description.

Length and format

• A description holds at most 100,000 characters. Past 90,000 the field shows a counter; a longer text is refused when you save, never cut.
• Trailing spaces and blank lines are trimmed, and an empty description removes it.
• It is kept as text and shown as text: Bikube never renders the Markdown.
• It is saved and synced with the card, like its title.

On the board

A card with a description shows a document icon after its title. Hover the icon to see the description's first five lines (each cut at 120 characters, with … when there is more). board list marks such cards with · description.

What the agent gets

On every fresh start of the card's agent, Bikube passes it one fixed first prompt, exactly:

This card has a task description. Read it with: board description .  Then summarise it in a few lines and ask me whether to start on it. Do not start working on it until I say so.

So the agent reads the task from Bikube, sums it up, and waits for your go-ahead; it never starts on the work by itself. A fresh start is:

• the card's first start;
• the first start after you pick an agent the card hasn't run before (with Startup command…);
• the first start in a new worktree, when the card moves into its own worktree, which gives it a new agent session.

The prompt is never sent when the card resumes its agent's session, for example when you reopen a stopped card or after a restart, and never to a Custom… command. Cards without a description start their agent with no prompt.

Each agent receives the prompt the way its command takes a first message:

Claude Code cards are also told, in the instructions Bikube's hooks give Claude, that the card may have a task description and to read it with "$BIKUBE_BIN/board" description . when it needs the task. See Activity & status.

From the command line

Inside any card, board description prints a card's description (nothing when it has none), and board describe replaces it with a file's text, or with standard input for -. An empty file removes it.

# Print this card's description
board description .

# Replace another card's description with a file
board describe "Fix the login redirect" notes/login-task.md

# Write one from standard input
echo "Add a /releases endpoint that lists the GitHub releases." | board describe . -

board create --description-file creates a card with a description in one step, which is how an agent hands a task to a new card, in this workspace or another. See The board command.