13. Changing the team or updating its version

A project can move to another team (for example, from Ceres to Vela once the idea is defined, from Orion to Vela to build in the app, or from Vela to Andromeda to deploy) or to a new version of its same team (for example, an updated own team). It opens with Change team… in the agent menu or in the Roles panel. It is a three-step wizard:

1. New team — the team cards. The current team’s card shows “● Current team · {version}” and, if a newer version is available, “→ version X available”. If the project had other teams before, Go back to a previous team appears at the top, with the date you left it.
2. Review — Now and After (team, language and version; the language can be changed, also to move the same team to its other language), the roles that Stay, Leave and Join, and What will happen: whether it is an update of the same team, which step the workflow is at, which step the new team starts at (its Sprint 0), the handoff document, the chats and the backup. You choose the Model to write the handoff (the ones your Claude Code plan doesn’t include appear disabled: see Models per role). The handoff is written by the project’s agent (or, if it is not installed, whichever is available); the progress shows Agent: …. With Codex its default model is used. The button is Change team or Update to version X.
3. Change — progress and result: summary, handoff document, pending items collected, what to check first and where the previous team was saved. Button Open with the new team.

What the change does:

• The code and the documents (docs/) are not touched; the roles, the workflow and the templates are replaced.
• The previous team is saved in .team-ai-console/team-history/ and you can go back to it from the same wizard.
• The workflow starts at the new team’s Sprint 0. A new chat, Team change, is opened; previous chats are kept.
• Claude Code writes the handoff document in docs/handoff/: what exists, what is pending, which role takes over each responsibility and what Sprint 0 must produce. It is the new team’s input. If the handoff fails or you cancel it, the change is still done and you can Generate the handoff again.
• The app only says that the project “already uses that team” if the team, the language, the version and the files all match.

Notice when opening the project. If the app includes a newer version of the team the project uses (the same team, in the same language), a notice appears when you open it: “A new version of {team} is available”, with the current and the new version. Update to version X opens the wizard directly at the review step; Not now leaves it for later (it will ask again next time); Don’t ask again for this version silences it for that version (a newer one will be announced again). It works for every team in the app, whether it declares its version or carries it in its signature. If the project’s version cannot be determined, it is treated as an earlier version: the notice says it uses a version that cannot be identified and offers the app’s. The notice only appears in individual projects, not in those with collaboration enabled.

Current limitations: only in individual projects (no active collaboration) and with the agent stopped. The new team must be allowed by your license.

Team improvements: from the retrospective to the catalog

When a sprint closes, a role can propose a change to the team itself (for example, a new rule in a role’s sheet). Those proposals appear in the project’s Improvements tab (view switcher, next to Backlog), with the number pending: Improvements (2).

How to propose one. A proposal is a .md file in the project’s docs/team-improvements/ (the documents folder the project uses), for example mejora-2026-11-03-english-texts.md. The role can write it (with Claude Code or Codex: the app only reads files) or you can. Format:

---
type: team-improvement
team: galaxy
file: team/flow/uud.md
sprint: 122
status: pendiente
---

## Reason
The designer delivered the specification without checking the English texts and it had to be redone.

## Evidence
Round 2 of Sprint 122 (failure repeated in two sprints).

## Before
```text
- Accessible by default.
```

## After
```text
- Accessible by default.
- New texts are written in Spanish and English in the same specification.
```

team is the team’s id (the template.id in team-ai-console.json), file is the team file that changes, and Before / After are the exact text that is replaced and the new one. The Spanish keys (tipo: mejora-equipo, equipo, archivo, estado) and headings (Motivo, Evidencia, Antes, Después) are accepted too. The status values are always the ones the app writes: pendiente, aplicada-proyecto, aplicada-catalogo, guardada, descartada. A file that does not follow the format is not shown as a card: the tab says “N unrecognized files” and, when expanded, the reason for each.

The “Team improvement proposal” card. It shows the team, the file and the sprint, the reason, Before and After side by side (stacked when the tab is narrow: a small window or wide side panels), the evidence and three actions:

• Apply to the project — changes the team file of this project. If the “before” text is no longer in the file (or appears more than once, or the change was already made), nothing is changed and the card says so. If the project’s team was a signed app team, it then counts as an edited team (see Licenses).
• Apply to the catalog team — takes the change to your own team in Teams and Roles so that it reaches future projects. The app leaves the project and opens the team editor with the change already applied to the draft, a band saying which project and sprint it comes from and which version it will raise to, and the affected document open. Review it and press Save: before saving, the editor’s checks run; if they fail, nothing is saved, the version does not change and the band says why (the Checks step gives the details). Cancel or Reset discard the change and the proposal stays pending. Leaving the editor takes you back to the project. If you have several teams of your own and none has that id, you pick the target in a list. It needs the Edit teams license feature: without it, the button shows 🔒 and pressing it explains why.
• Dismiss — the proposal moves to Resolved, without confirmation.

App teams. If the proposal is for a signed app team, the card warns that that team is not modified and its actions change: Copy and apply copies the team to Your teams and opens its editor with the change prepared (needs Create teams and Edit teams), and Save as proposal leaves a copy in the project’s docs/team-proposals/ (no license needed). Apply to the project and Dismiss remain available.

Resolved. Below the pending ones, collapsed, with their status: Applied to the project, In the catalog · v{version}, Saved as proposal or Dismissed. The status is stored in the file itself, so it is kept between sessions. View the proposal opens the file in the viewer.

“Team improvements” log. Every improvement saved from a project is recorded in the own team’s team/IMPROVEMENTS.md, in the same Save, and travels with the version. In the team editor, the Identity step shows it at the end: version, what changed, project and sprint, evidence and date, most recent first. App teams do not keep this log.

It reaches the other projects. The own team’s new version is announced in the other projects that use it with the new-version notice (above, Notice when opening the project), and the Now and After review shows the changed file.