# Teams, projects and PR groups

Andon files work at four levels. A **team** is a repository, the settings for how its cards run, and the list of
who sees it. A **project** is a goal inside a team, with a lead and dates. A **PR group** is the cards that ship
together in one pull request. A **card** is one piece of work.

```
Workspace
└─ Team        repository, machines, automation, who sees it, key, sub-teams
   └─ Project  a goal: lead, status, dates, milestones
      ├─ PR group   what ships together: one branch, one run, one pull request
      │  └─ Card
      └─ Card       not grouped yet
```

## Teams

A team is where a repository, its machines, its automation and its people come together. Every card in a team is
numbered with the team's key, such as `WEB-12` (see [Card keys](https://andon-docs.pages.dev/guide/board.md#card-keys)).

### Add a team

1. Open **Settings → Teams** and click **Add team**. You can also pick **New team…** from the Team pill in
   [Start work](https://andon-docs.pages.dev/guide/start-work.md).
2. Pick a repository a machine already has, start from a folder (a machine makes it and starts a git repository in
   it), or make a team with no repository.
3. Pick **How much Andon does** for it, and click **Create team**.

A new team gets a **General** project at once. New teams start private: only the person who made them sees them
until they share them. See [Who can do what](https://andon-docs.pages.dev/reference/permissions.md).

### Sub-teams and the sidebar

Under **Identity**, **Parent team** nests a team under another, up to five levels deep. A sub-team's cards show
under its parent too, and it follows its parent's overrides unless it sets its own.

On a desktop, drag a team in the sidebar onto the top or bottom edge of another to put it above or below, or onto
its middle to nest it. Owners and admins move teams. Each drop has Undo.

### The team page

Click a team in the sidebar to filter the board to it, then click **Team page** in the header. The page shows:

- **Projects**, each with its status and progress, and **New project**.
- **Cycles**, with **New cycle**. See [Planning](https://andon-docs.pages.dev/guide/planning.md).
- **Machines and repositories**.
- **Automation**: its level, agent and model, with **Edit**.
- **Memory**: how many lessons are active and waiting, with **Open memory**.
- **Autopilot**: the team's Autopilot switch, **Group related cards** and **PRs building at once**, with **Every team**
  to open the Autopilot sheet and **Edit** to change them.

**Show on board** filters the board to the team, and **Team settings** opens it in Settings.

### Archive a team

In **Settings → Teams**, pick **Archive…** on a team's ⋯ menu, or tick several teams and click **Archive**. A team's
editor has **Archive** in its **Archive** section too. An archived team leaves the board and every picker. Nothing
is deleted, and you can unarchive it from the Teams list.

When the teams have cards, the dialog offers **Also archive its N cards**, ticked by default. Ticked, those cards are
archived too and show on the [Archive page](https://andon-docs.pages.dev/guide/activity.md#the-archive). Unticked, they're hidden with the team and
come back when it's unarchived. Only the ticked teams' own cards count: a sub-team you didn't tick stays on the board with its
cards. Andon skips a card you couldn't archive on your own, such as someone else's, and the message says how many.
**Undo** brings back the teams and exactly the cards this archived.

## Projects

A project is a goal: *Checkout v2*, *Billing*. Every card in a team belongs to one of its projects. Cards that don't
name a project go to the team's **General** project, which is always there.

### Add a project

- On the team's page, click **New project**.
- In the sidebar, open a team's menu and pick **New project…**.
- In [Start work](https://andon-docs.pages.dev/guide/start-work.md), name a project the team doesn't have yet ("add invoices to a new Billing
  project"), or pick **New project…** from the Project pill. It is made when you press Enter.

### The project page

Open a project from its team's page, or from the sidebar. Set its **Status**, **Lead**, **Start** and **Target**
dates right on the page; **Edit** beside **Description** changes the description. Type in **New card in …** to add a
card to it.

The status (planned, active, paused, done or canceled) is a label. It doesn't stop or start anything. A project
still planned becomes active when one of its workstreams starts.

**How its cards run** says the level, model and the team it follows (*Assist · Claude Code default · follows
Storefront*). The side rail shows its progress, what needs a person, how many cards wait on another card and how many
can start now, and the team's memory.

| To | Do this |
|---|---|
| finish it | **Mark as done** on the page, or on the project's row menu in the sidebar. Undo puts the old status back. A done or canceled project leaves the sidebar and stays on its team's page |
| open it again | **Reopen** on its page |
| keep Autopilot from starting its cards | **Hold this project**. See [Autopilot](https://andon-docs.pages.dev/guide/autopilot.md#hold-work-back) |
| see only its cards | **Show only this project** on its sidebar row menu, or **Show on board** on its page |
| put it away | **Archive** on its sidebar row menu. Its cards move to the team's General project |

A card's **Project** menu offers the team's open projects: planned, active or paused, and General. Drag a project in
the sidebar above or below another to change the order. General stays first.

On the board, filter to one team and split it into lanes by project to see each goal's cards. Dropping a card into
another project's lane moves it to that project. See [Views, the filter bar and swimlanes](https://andon-docs.pages.dev/guide/views.md).

## PR groups

A PR group is the cards that build together: one branch, one run, one pull request. Group cards that change the
same thing, so you review them once. A card that runs on its own is a group of one.

[Autopilot](https://andon-docs.pages.dev/guide/autopilot.md) groups related Ready cards by itself. You can group cards by hand too, and a group you made
or changed is never regrouped.

### Group cards

- Pick the cards with `X` and press `G`.
- Drag a card onto another card in the same column and hold it still for 600 ms, until the target says *Group with
  WEB-3*. Hold `⇧` to group at once.
- Drag a card onto a group's stack, the same way, to add it.
- While you drag picked cards, drop them on the **New group** zone at the end of a column.
- Open a card and pick **Group with…** from its ⋯ menu, then a group or **New group**.

The toast says what happened, with Undo. Cards in one group must share a team, a project, a repository and an
owner, and run the same recipe. Code changes and bug fixes can share a group.

### What a group looks like

A group is one stack in its column: its name, how many cards it holds, its run and its pipeline, and its cards' keys.
Click the stack to open it and see its cards. A group moves between columns as one.

### Take cards out

| To | Do this |
|---|---|
| take one card out of a planned group | the **×** on the card in the open stack, **Remove from group** in the card's ⋯ menu, or pick it and press `⇧G` |
| undo a whole planned group | **Ungroup** in the stack's ⋯ menu, or select the stack and press `⇧G` |
| take a card out of a group that is building | **Split from group** in the card's ⋯ menu. The card goes back to Ready; the branch keeps its commits |
| stop a group | **Abandon group** in a card's ⋯ menu. A planned group's cards stay where they are. A building group's queued runs are cancelled, its pipeline stops and its cards go back to Ready |

The first card in a group carries the group's run, so it can't be split out of a group that is building: abandon the
group instead.

### How a group builds and merges

The group's run gets every card's title, notes, links and files, numbered in order. The agent works through them on
one branch and writes the pull request's description with a section per card. The review checks each card on its
own. When the pull request merges, every card in the group moves to Done.

A card the run skipped leaves the group when it merges and goes back to Ready with a note. A card you add to a group
that is building joins its pull request. A group that depends on another group's cards waits in Ready and starts by
itself when that group merges.
