# Intro to By Dawn

> What By Dawn is for, and the loop every piece of work goes through, followed once from a one-line ticket to a merged pull request.

This guide shows you how work moves through By Dawn by following one small ticket from start to finish. By the end you'll
know the loop that every ticket goes through, where you come in, and which parts By Dawn handles for you.

By Dawn is a project tracker where AI agents do the building. You still decide what gets built and whether it's good
enough to ship. The agent writes the plan, the code and the pull request, and a **mission** checks the work at each
step, so what reaches you has already been tested.

## The loop

Every ticket goes through the same five stages, whatever its size:

1. **You write the ticket**: what you want and how you'll know it's done.
2. **An agent plans it**, and you agree the plan or send it back.
3. **The agent builds it** on its own branch, and opens a pull request.
4. **The mission proves it**: the tests and build pass, CI goes green, and anything else the team asked for.
5. **You review it**, and it ships.

The board shows where each ticket is. A new project's columns are **Backlog**, **Planning**, **Running**, **Review**
and **Completed**, and By Dawn moves the card itself as the work goes. Your team can rename the columns, and By Dawn still
knows which is which. See [Board and columns](https://docs.bydawn.com/board-and-columns/).

## One ticket, start to finish

Maya runs the billing project at a small company. Customers keep asking for their invoices as a spreadsheet, so
she decides to add an export.

### She writes it down

On the board she presses `⌘N`. A bar opens at the bottom of the board, asking **What do you want to
build?** She types the title, then chooses **Advanced** to add more:

> **Add a CSV export to the invoices page**
>
> Customers want their invoices in a spreadsheet. Add an **Export CSV** button to the invoices page that downloads
> the invoices currently shown, with the filters applied. Columns: number, date, customer, total, status.
>
> Done when: the button downloads a file that opens in Excel and Google Sheets, and matches what's on screen.

She chooses **Create ticket**, and it lands in Backlog as `BIL-142`. Writing a ticket like this, one an agent can
finish without guessing, is a skill of its own. [Writing tickets an agent can
finish](https://docs.bydawn.com/learn/writing-tickets/) covers it.

### An agent plans it

Maya opens the ticket to start work on it, and By Dawn asks how. There are three modes:

- **Plan first** writes a plan and asks you to agree it. No code changes until you do.
- **Build now** builds in one go, stopping at each step that asks you.
- **Plan + build** plans, waits for your approval, then builds.

She picks **Plan + build**, leaves the mission's steps as By Dawn ticked them, and chooses **Start plan + build**. The
card moves to Running. [Start a ticket](https://docs.bydawn.com/start-a-ticket/) covers the modes and the steps in full.

A few minutes later the ticket's **Plan** section fills in: the **Outcome**, a list of **Acceptance checks**, the
files and screens it will touch (**Touchpoints**), the **Constraints** it will keep to, and any **Open questions**.
The bell in the title bar, your [Inbox](https://docs.bydawn.com/inbox/), lights up with **Needs you**, because the mission's first step is **Approve the plan**.

Maya reads it. The plan exports every invoice, not just the filtered ones, so she chooses **Request changes**,
writes "Only the invoices on screen, with the filters applied", and chooses **Send back**. The agent revises the plan
and asks again. This time she chooses **Approve plan**, and the build starts. [Checkpoints and
debriefs](https://docs.bydawn.com/mission-checkpoints/#approve-the-plan) covers every way to answer a plan.

### It builds, and the mission checks it

The agent works on its own branch and opens a pull request. Maya doesn't watch it, but she could: the ticket shows
the agent's live feed, its terminal, and the changes as it makes them.

Before the agent can call the work finished, the mission runs its checks. **Tests and build pass** runs the repo's
own tests, type checks and build. **Try it for real** starts the app, opens it and takes screenshots of what it saw.
**Get CI green** watches CI, and if it fails, the agent is brought back with the failure until it passes. Each of
these is a fact By Dawn checked, not something the agent said. [Missions and templates](https://docs.bydawn.com/missions/) explains where
the steps come from.

### She reviews it, and it ships

When the work is done the card moves to Review. Maya opens it and reads the **Mission** section first: every step
passed, so she knows the tests ran and CI is green. She spends her time on what only she can judge. Does the
export match what customers asked for? Are the column names right? She opens the pull request in **Changes**, reads
the diff, and is happy with it.

Depending on how her team set up its missions, she merges the pull request herself, or approves it and lets By Dawn
merge it and move the card to Completed. [Reviewing agent work](https://docs.bydawn.com/learn/reviewing-agent-work/) goes through a
review in detail.

## What you do, and what By Dawn does

| You | By Dawn |
|---|---|
| Decide what to build, and write the ticket | Plans it, and keeps the plan up to date as it goes |
| Agree the plan, or send it back with a note | Builds on its own branch and opens the pull request |
| Answer questions the agent can't answer from the code | Runs the tests and build, tries the app, watches CI |
| Judge whether the result is right | Moves the card, and merges and closes it if you asked it to |

Most of your time goes into the left column. The better the ticket, the less of it you spend answering questions
and sending work back.

## Where to go next

- [Start guide](https://docs.bydawn.com/start/): set up your own project, repo and machine, and run your first ticket.
- [Writing tickets an agent can finish](https://docs.bydawn.com/learn/writing-tickets/): what makes the difference between a ticket that
  ships and one that comes back.
- [Planning a feature as an epic](https://docs.bydawn.com/learn/planning-an-epic/): when the work is bigger than one ticket.
- [Coming from Linear or Jira](https://docs.bydawn.com/learn/coming-from-linear-or-jira/): if you're bringing a team and its work over.
- [Words we use](https://docs.bydawn.com/glossary/): the By Dawn words in one place.

Source: https://docs.bydawn.com/learn/intro-to-saw/