# Board and columns

> How a project's board works, what each column's role means, how cards move between columns, what a card shows, and how to search, filter and save views.

This page explains a project's board, so you can read it at a glance and move work across it with confidence. By the
end you'll know what each column does, which moves start or stop a worker, what a card is telling you, and how to
narrow the board to the work you care about and keep that as a view.

Every project has one board. Its columns are the stages work goes through, and each ticket sits in exactly one of
them (see [Tickets and sub-tickets](https://docs.bydawn.com/tickets/)). You move cards by hand, and By Dawn moves them too as its workers start,
ask questions and finish. Choose **Board** in the sidebar, or press `⌘1`, to open it.

## Columns and their roles

Teams rename and add columns, so By Dawn marks the few columns its workflow depends on with a **role**. The role stays
with the column whatever it's called, and the column header shows it as an icon. A new organization's board starts
with one column for each role:

| Column | What its role means |
|---|---|
| **Backlog** | Where new tickets land when nobody chooses a column. |
| **Planning** | Work that's planned but not started. |
| **Running** | **Agents start here when a card lands.** Moving a card into this column starts a worker on it. |
| **Review** | **You review the agent's output here.** A worker's card comes here when it finishes. |
| **Completed** | Finished work. Sub-ticket progress, epic progress and the **Shipped this week** view count a ticket as done once it's here. |

A column your team adds has no role. Cards move in and out of it like any other, but nothing starts there. Running
and Review are **anchored**: you can rename them, but you can't delete them, because By Dawn needs somewhere to run work
and somewhere to hand it back.

Hover the icon on Running or Review to see what the column does. Hover a column's header to reach two buttons:

- **Add to column** (**+**) opens the create bar with that column already chosen.
- **Column options** (**⋯**) changes how this column looks, for you only:
  - **Select all in column** selects its cards for the bulk actions below.
  - **Card size**: **Match board**, **Comfortable** or **Compact**.
  - **Sort by**: **Manual**, **Priority**, **Last updated**, **Created** or **Title**, with a **Direction**.
  - **Group by**: **None**, **Priority**, **Epic**, **Assignee**, **Cycle** or **Release**.
  - **Reset column** puts it back. **Edit columns…** opens the organization's column settings.

## Move cards

Drag a card to another column. Dropping on Running shows **Start agent** before you let go, because that drop starts
a worker. You can also move a ticket from its own view, with the status menu beside its ID.

To move several cards at once, tick the checkbox that appears when you hover a card, then drag any of the ticked cards.
They all move together. While cards are selected, a bar at the bottom offers **Move to cycle**, **Add to release**,
**Archive**, **Delete** and **Clear**. **Move to cycle** and **Add to release** show only when the project uses
cycles or has releases.

A few moves do more than change the column:

- **Into Running**: By Dawn checks that a machine can run the ticket first. If none can, the card stays where it was and
  By Dawn says why, under **Can't start this ticket**.
- **Into the completed column**: By Dawn stops the ticket's worker, because there's nothing left for it to do. If the
  worker can't be stopped, By Dawn tells you so and the card stays in the completed column.
- **A card waiting on your answer**: while a worker is stopped on a question or a permission prompt, its card can't
  be dragged. Answer it first.

### How By Dawn moves cards for you

You don't have to move every card yourself. By Dawn moves them as the work goes:

- **A worker asks you something.** While a worker is stopped on a question or a permission prompt, its card shows in
  Review, and By Dawn moves it there. Answer on the card or in the ticket.
- **A worker finishes.** Its card moves to Review, where you look over what it did.
- **A run is stopped.** A card still in Running goes back to the column it was in before the run started.
- **SAW is shipping it.** When the only steps left in a ticket's mission are By Dawn's own, such as marking the pull
  request ready, approving it and merging it, the card waits in Running and its ticket says **SAW is shipping it**.
  By Dawn then moves it to the completed column itself. See [Missions and templates](https://docs.bydawn.com/missions/).

## What a card shows

A card leads with what needs your attention and keeps the small facts on one line at the bottom.

- **The epic**, on a line of its own at the top, with the epic's colour along the card's left edge. Hover it for the
  epic's progress, or click it to open the epic.
- **The title.**
- **Blocked by**, with the first open blocker's ID (and **+2** for two more), when another ticket holds this one back.
- **How it was resolved**, when a ticket was closed without code: **Duplicate of**, **Already fixed by** or **Won't
  fix**.
- **What's happening now**, which changes with the ticket's state:
  - A worker's question, with its answers as buttons you can click on the card.
  - **No output for a while — still on track?** when a worker goes quiet, with **Peek** and **Nudge**.
  - A permission prompt, a sign-in the worker's machine needs, or a pause on a usage limit.
  - While a worker is running: what it's doing now, and a bar of its acceptance checks, such as **4/9 checks**.
  - In Review: the pull requests, such as **1 PR open for review** or **2 merged**, and the checks.
- **The bottom line**: the count of sub-tickets (**1/3 subs**, hover it for the list), the number of comments, the
  cycle, the estimate and linked GitHub issues when the project uses them, the ticket's ID, and the assignee. An
  unassigned ticket shows an empty circle.

The light around a card is its status: it runs while a worker is live and turns warm when the card is waiting on you.

**Compact** cards fit more on the screen. Each is one or two lines, the light moves to a thin strip down the left
edge, and the assignee and sub-tickets show when you hover.

Sub-tickets don't get cards of their own. They're counted on their parent's card, which keeps a broken-down ticket
from filling a column.

## Change the layout

The tools at the top of the board change how it's drawn:

- **Board** or **List**: columns side by side, or one list grouped by column.
- **Display**: the **Density** of every card, **Comfortable** or **Compact**. `⌘⇧D` switches between
  them.
- **Group** (inside **Display** when the tools sit in the top bar): group the cards **Inside each column** by
  **Priority**, **Assignee**, **Epic**, **Cycle** or **Release**. Tickets without that field get their own group, such
  as **No epic** or **Unassigned**. Under **Across the columns**, **Epic lanes** gives each epic its own row of
  columns. `⌘G` turns epic lanes on and off.

## Search and filter

The search field at the top of the app is the board's search. It names the view you're on and says **Search or
filter this view · jump anywhere**.

- **Type** to narrow the board to tickets that mention your words. By Dawn searches the whole ticket, including its
  comments, plan, labels, epic and pull requests, not only what the card shows. If nothing matches, the board says
  **No tickets match** with your words, and **Clear search** brings everything back.
- **Filter** with the list under **Narrow by**: **Assignee**, **Status**, **Label**, **Epic**, **Cycle**,
  **Release**, **Repo**, **Priority**, **State**, **Created** and **Updated**. Some only appear when the project uses
  them, and **Has Intercom link** only when your plan includes [Intercom](https://docs.bydawn.com/intercom/). As you type, **Filter this view** suggests filters your words could become. `Tab` adds the first.
- Each filter becomes a chip in the field. Click a chip to change it, or press `Backspace` in an empty
  field to remove the last one.

**State** filters by what's happening on a card: **Needs input**, **Stalled**, **Running**, **Paused**,
**Blocked**, **Stuck** or **Ready to ship**.

The same list also offers matching tickets to open and pages to jump to. `⌘K` opens the command
palette instead, which searches tickets and Docs from anywhere in By Dawn.

## Board views

A **view** is a saved set of filters and layout. The sidebar lists the views you've pinned under **Board views**,
each with a live count, and **All views** lists every one the project has, with **Find a view** to search them.

By Dawn ships these views. You can't change them, but you can save a copy and change that.

| Group | View | What it shows |
|---|---|---|
| Board | **All tickets** | Every open ticket on the board |
| For you | **Needs you** | Questions, plan approvals and checkpoints waiting on you |
| For you | **My tickets** | Tickets assigned to you |
| For you | **Waiting on my review** | Your tickets in the review column |
| Workers | **Running now** | A worker is live on it |
| Workers | **Stuck** | Stalled or lost workers, failing checks, or a parked CI gate |
| Workers | **Ready to ship** | In review, every open PR green and mergeable |
| Planning | **This cycle** | Everything planned into the current cycle |
| Planning | **Triage** | Nobody has it yet |
| Planning | **Blocked** | Waiting on an open blocker |
| History | **Shipped this week** | Done in the last 7 days |
| History | **Archived** | Archived tickets, alongside the rest |

### Save a view

1. Open the view closest to what you want, then change the filters, search or layout. The board marks the view
   **Edited**, with **Reset** to undo your changes.

2. Choose **Save view**. On a view you saved yourself, the button says **Update view** instead, and its arrow offers
   **Save as a new view**.

3. Give it a **Name** and choose **Who sees it**: **Only me**, or everyone in the project.

4. Choose **Save view**.

Each view's menu in the sidebar has **Pin to the sidebar** (or **Unpin from the sidebar**), **Duplicate as a new
view**, and, on views you saved, **Rename**, **Share with everyone** or **Make it private**, and **Delete view**. Drag
pinned views to reorder them. Your sidebar order is kept on your account, so it's the same on every device.

## Change the columns

Columns belong to the organization first. Every project's board uses the organization's columns, its **template**,
until someone gives the project its own. Only workspace admins (org owners and admins) can change columns. Everyone
else sees them read-only.

- **Settings › Organization › Board** edits the template, which every project without its own columns
  follows.
- **Settings › This project › Board** shows which columns this project uses. On the template, choose
  **Customize for this project** to copy the columns to the project and edit them there. A customized project stops
  following changes to the template, and **Use the organization template again** takes it back.

The same list of columns appears in both places. In it you can:

- **Add column**. A board holds at most 12 columns, and a name is at most 60 characters.
- Rename a column by clicking its name.
- Reorder columns by dragging them, or with **Move up** and **Move down** in the column's **⋯** menu.
- Give a column a colour with **Colour…**.
- Click a column's ticket count to open the board on that column.
- **Delete column**.

Name new columns with care. A column called "In progress" or "Doing" won't start anything, because only the column
with Running's role starts a worker. By Dawn warns you when a new column's name sounds like it should.

### Delete a column

Deleting a column never deletes its tickets. If the column holds tickets, or carries a role, By Dawn asks where they go
first:

1. In the column's **⋯** menu, choose **Delete column**.

2. Pick the column that takes its tickets. Running isn't offered, because moving tickets there would start a worker
   for each one.

3. If the column has a role, the column you pick takes the role over. Taking over the backlog role means new tickets
   land there, for example.

4. Choose **Move & delete** (or **Delete column** for an empty column).

A bar then confirms what happened, with **Undo**. An empty column with no role is deleted straight away, and you can
undo that too.

> **Going back to the template moves tickets:** **Use the organization template again** asks you to confirm with **Restore the template**, because it moves the
> project's tickets back onto the organization's columns and drops the project's own. Tickets in a column the project
> added move to the first template column that isn't Running. If the template has nowhere to put some of them, By Dawn asks
> you to move them first.

## FAQ

**I renamed a column to 'In progress'. Why don't workers start when I drop a card there?**

Workers start only in the column with Running's role, whatever it's called. Rename that column instead (it's
**Running** on a new board), and keep your own columns for stages where nothing runs.

**Why did a card jump to Review on its own?**

Its worker either finished or stopped to ask you something. Open the card to see which: a question shows on the card
itself, and a finished run shows its pull requests and checks.

**Why can't I change the board's columns?**

Only workspace admins can. If your project follows the organization's template, an admin changes the columns in
**Settings › Organization › Board**, or gives the project its own in **Settings › This project › Board**.

**Does changing a column's sort or grouping change it for everyone?**

No. The **⋯** options on a column, and the **Group** and **Display** tools, change the board for you only. To share a
layout, save it as a view and choose to share it with everyone in the project.

## Next

- [Tickets and sub-tickets](https://docs.bydawn.com/tickets/): what's on a card when you open it.
- [Cycles](https://docs.bydawn.com/cycles/): plan which cards the team takes on next.

Source: https://docs.bydawn.com/board-and-columns/