Chapters · 12. Adopting an existing project

Describes Team AI Console 0.4.19 · updated 2026-11-20

12. Adopting an existing project

For working with a team on a project that already has code written outside the app. It opens with Adopt an existing project… on the home screen, or from the preparation screen when you open a folder with code and no team. It is a four-step wizard, with the steps at the top and Cancel the adoption / ‹ Back / Next › always at the bottom:

  1. Folder — Choose the folder…. The app checks it and shows What will happen: everything in the folder moves to app/; if it has git, what happens to the repository with the option you choose (see If the folder is already a git repository, below); the CI or deployment files that will need updating; and that the agent you choose (Claude Code or Codex) will write the initial documentation. If the folder cannot be adopted (it is empty, it is already an app project, it already has an app/ folder with content), it explains why.
  2. Team — the team cards with the Choose this team button. The chosen one is marked.
  3. Options — summary (folder, team and, with git, the chosen Git option and its remote; each with Change), team language, Agent that analyzes the project (only the installed ones: with both, Claude Code is selected and you can switch to Codex; with only one, it is already selected), Model to generate the documentation (the list is the chosen agent’s; with Claude Code, the models your plan doesn’t include appear disabled: see Models per role), the model of each role, and the notice that moving the project is a real change on disk. Button Adopt the project. If no agent is installed, a notice explains how to fix it (install Claude Code or Codex, or set its path in Home → Agents) with Check again, and you cannot adopt until there is one.
  4. Adoption — progress: the project is moved, the team is copied and the agent reads the code and writes the documentation (Agent: …, files read, documents written, time). With either agent it can only write in the documents folder and AGENTS.md. The agent used becomes the project’s agent. You can Cancel the documentation: the project stays adopted and the documentation can be generated later. When it finishes you see the summary, the list of generated documents, how many statements were marked as [ASSUMPTION] (Spanish teams use [SUPUESTO]) and Open the project.

The initial documentation includes the team’s living documents (brief, architecture, standards with the real commands, backlog, technical debt, test strategy, context, glossary…) and an adoption record (in docs/sprints/sprint-0-adoption/, or sprint-0-adopcion/ if the team is in Spanish). The workflow starts at the Sprint 0 close: the initial role reviews the generated documents with you and starts Sprint 1. If something fails before the documentation, the app undoes the move.

If the folder is already a git repository

The Folder step shows the card This folder is already a git repository (also when .git is a file, as in a worktree or a submodule) with two options. Nothing is preselected and you cannot go on until you choose; both are explained with the same three rows: what stays at the root, what stays in app/ and what gets pushed.

  • Everything in the product’s repository — the usual: .git/ stays at the root, the code moves to app/ and the repository changes structure. On git add, git sees the code as moved to app/ (history is kept) and what you push will also include docs/, the team and the app’s configuration.
  • Each in its own repository — for when the repository belongs to another person or company and only the product must reach it. .git moves with the code to app/: in app/, git status stays as before and the history does not change. A new repository with no commits is created at the root, whose .gitignore ignores app/ (plus .DS_Store and .scratch/); docs/ and the team go there. You can give an optional remote for that repository: it is added as origin, without pushing anything or checking the network (the address cannot contain spaces or start with -). Nothing of the app is written inside app/.

If git is not installed, or the repository cannot be moved safely, the second option appears disabled with the reason and the first one is still available. Neither option commits or pushes. If the adoption fails, the app also undoes moving .git and deletes the new root repository. At the end, the summary says which repository is in each folder.

The choice cannot be changed later (projects adopted before work as the first option). With Each in its own repository the app uses the app/ repository for the code: the changes panel reads the code from app/ and the documents from the root; issues, CI status, the branch comparison link and the repository check in the project readiness use the one in app/. The instructions the agents receive tell them that code is committed and pushed from app/, that docs/ and the team go to the root repository and never to the product’s, and that sprint branches are made in each repository with what belongs to it.