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, .git/ stays at the root (history is kept and nothing is committed); 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 and team, 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.