Skip to content
Kairos

Wind down a team

Disband a team whose work is finished or absorbed elsewhere, and get its delete to go through.

Before you start: you are an org admin. Deleting a team is org-admin only.

Kairos refuses the delete while anything still points at the team, and the refusal names what. There are exactly two guards, they fire in this order, and clearing them is the whole job:

  1. The team must own no repositories — 409.
  2. Its delivery board must hold no live cards — 422 BOARD_NOT_EMPTY.

Work through them in that order; the second refusal will not appear until the first is clear.

1. Try the delete and read the refusal

Section titled “1. Try the delete and read the refusal”
Terminal window
kairos teams delete <team-id> --confirm
409 — The team "Mobile" has 1 repository: [payments-api]. Give each
repository to a different team. Then delete the team.

The message lists the repositories by slug, and details.repositories carries the same list.

2. Re-home or retire the repositories

Section titled “2. Re-home or retire the repositories”

Re-home it to the surviving team:

Terminal window
kairos repos update payments-api --team platform

The change of owner does not change the tasks that link to the repository. Or retire the repository entirely, which is itself refused with 409 while any task or webhook connection still references it:

Terminal window
kairos repos delete payments-api --confirm

A new owner changes the owner only. Each task that links to the repository stays on its board, with its team, and can move to any delivery board. The tasks on the board of the old team still hold the second guard, so clear them in step 3.

3. Clear the board

Section titled “3. Clear the board”
Terminal window
kairos teams delete <team-id> --confirm
422 BOARD_NOT_EMPTY — The delivery board "Mobile Delivery" of the team "Mobile"
has 2 live cards: [MOBILE-T-0001, MOBILE-T-0002]. Move each card to a different board
(POST /api/tasks/{code}/move) or delete it. Then delete the team.

The refusal names the cards — up to twenty of them — so this is a worklist, not a puzzle. Two ways to clear each one, and the choice matters:

  • The work continues somewhere else → move it:

    Terminal window
    kairos tasks move MOBILE-T-0001 --to-board platform-delivery

    See Move work between boards, which is also where the manage_tasks-on-both-boards requirement lives. The task keeps its repository. If an agent worked the old board, see Agents that work the old board.

  • The work is finished → archive it:

    Terminal window
    kairos tasks delete MOBILE-T-0002 --confirm

    Despite the verb this is a soft delete, and archived cards do not hold the guard open, so this is the normal way to empty a board at the end of a quarter (Archiving).

    It cascades to the card’s children. A parent named in the refusal takes its whole subtree with it, so check what a card holds before archiving it rather than after — restore does not un-cascade, and putting the subtree back is one item at a time.

    It takes only the children that you can edit. Read the output of the command. It names each child that stays live, and the capability that you need on its board. Archive those children with an account that can edit them, or ask an organization admin to archive the parent.

Decide before you archive

Section titled “Decide before you archive”

Archiving is easy to undo while the board exists. Once the team goes, its delivery board is soft-deleted with it and answers 404, so an archived card that was on that board can no longer be restored — a restore is refused with RESTORE_BLOCKED naming the missing board. The activity log still records that the work existed and who did what to it, either way.

So: anything somebody might plausibly pick back up should be moved, not archived. See Find archived work.

4. Delete the team

Section titled “4. Delete the team”
Terminal window
kairos teams delete <team-id> --confirm
kairos teams list --limit 100      # it is gone

The team and its delivery board are soft-deleted together, so there is no orphan board left behind. Move the people and any service accounts to their new team first or after, as you prefer:

Terminal window
kairos teams members add <surviving-team-id> --user <user-id>

Deleting the team does not delete its members’ accounts, and does not touch work that moved to another board.

Section titled “Related”