8. The workspace (an open project)

When you open a project, the window is divided into: top bar, side panel (left), chat (center) and document viewer (right). The dividers between panels can be dragged; double-clicking resets them to their size.

Top bar

From left to right:

• New window — the first button on the left: opens another app window on the home screen; the current window stays on the project. Same as File → New Window. Without a license that includes multiple windows it shows a 🔒.
• ‹ Projects — goes back to the home screen.
• Project name and its status: Ready, Starting…, “{Role} is working…”, “Running: {tool}”, “Ready · N in the background” or Error. In windows 1360 px wide or less, the status shows only as a colored dot; hover over it to see the text. A long project name is cut with “…”; hovering shows the full name and the folder.
• While work is running, the status dot becomes an activity label: AI (warm, with a pulsing icon) while the model is working, which uses your plan; Local (cool, steady) while a tool runs on your computer, such as a command or reading and editing files, which doesn’t use your plan. A tool that takes less than 300 ms doesn’t switch it. While a tool waits for your permission, it counts as Local. Tools that can’t be classified (for example, MCP server tools) don’t change the label: you see the usual dot. The same happens at rest or on error. Hover over the label to see “AI — uses plan” or “Local — no usage”.
• In shared projects: the sync indicator (Synced, Syncing…, Offline, Error…; clicking it syncs) and the turn (“Turn: {role} · {person}”).
• The new version notice for the app, if there is one.
• The view switcher Chat · Backlog · Improvements · Usage · Team · Pending — what the center of the window shows (see View switcher, below).
• Hide viewer / Show viewer — the document viewer.
• The license status, in a capsule with a colored dot: green with Licensed; amber in the grace period or in read-only mode; red with no license or with an expired, revoked, other-machine or invalid license. Clicking it opens the license panel.
• Autonomy mode chip — the delegation chip (see chapter 9) names the mode: 👁 Supervised in grey when you decide; 🤝 Semi-autonomous · {Role} in the accent color when you delegated and the workflow has reserved steps; ⚡ Autonomous · {Role} filled with the accent color when you delegated and there are no reserved steps; ⚠ Supervised in amber if the delegated role is no longer in the team (hovering explains that the delegation has no effect). In a narrow window the role name is hidden, never the mode. Pressing it opens the delegation dialog.
• {Agent} · {model} ▾ — the agent menu. The button shows the agent and model the active role answers with: with Claude Code and Codex installed, it can be a different agent from the chat’s (see A different agent for each role).
  • Agent (Claude Code or Codex) that runs the turns of this chat. It is fixed once the chat starts; to use another agent, open a new chat. With both agents installed it is the “Project” agent: roles without their own agent use it.
  • Model — Default, one from the list, or Custom… (you type the model id or alias). Below it, the model the agent reports it is using is shown. This model only applies to the chat’s agent: if the active role uses the other agent, a note below says so (“This model only applies to Claude Code. Full Stack Developer uses Codex with its own model.”).
  • Models per role… (see Models per role).
  • Change team… (see Changing the team).
  • Permissions — Always ask, Accept file edits or Automatic (see Permissions).
  • Automatic phase chats — on by default (see Chats per phase).
  • The app version.
• The agent session (that of the active role’s agent): “Signed in” with Sign out (in windows 1360 px wide or less, only Sign out), or Sign in. If the session uses a paid API, Paid API appears in orange.
  • When the project opens (and when you change agent), if checking the session takes more than a moment, a notice appears in the middle: “Checking your {agent} session…”, with an activity bar. It closes by itself when the check finishes. Hide closes it and the check keeps going; the result shows here, in the bar. If you’re not signed in, the notice says so and offers Sign in; if the agent can’t be found or the check fails, it explains what to do and offers Retry; if 15 seconds pass without an answer, it says it’s taking too long and offers Retry or Close to keep using the app. The checks made when you come back to the window are still silent.
• The ES | EN language selector and the theme button.

If the options don’t fit in the window (for example, with the window at its minimum width), the bar’s row can scroll: a fade with an arrow › (or ‹) appears at the edge where options are hidden. Press the arrow, use the mouse wheel or the trackpad, or move through the options with Tab, which brings the focused one into view. If everything fits, the bar looks as it always did and no arrow appears.

All the controls in the bar have the same height and no text wraps onto two lines.

View switcher

The Chat · Backlog · Improvements · Usage · Team · Pending switcher in the top bar chooses what the center of the window shows. One option is always selected (the one with the white background); when you open a project it is Chat. Clicking the option that is already selected does nothing: to go back to the chat, choose Chat.

• Chat — the conversation with the team.
• Backlog — the project’s pending requests (see Backlog).
• Improvements — the team improvement proposals, with the number pending (see chapter 13, Team improvements).
• Usage — AI usage in the project (see AI usage). If your license does not include it, the option shows a 🔒 and clicking it opens the license notice instead of changing the view.
• Pending — what is waiting for a person in the project’s chats, with the number of items in the tab itself: Pending (3) (from 100 on, “99+”; no number when there are none). See Pending, below.
• Team — the collaboration panel (see The Team panel). With a collaboration identity, the option shows your name: Team · {your name} (a long name is cut with “…”; in windows 1360 px wide or less only Team is shown; hovering shows the full name).

The chat keeps working. Switching views does not stop or pause the agent: the reply in progress keeps being written and, when you go back to Chat, the chat is as you left it (scroll position and the text you were typing). If the agent writes a message while you are on another view, a yellow dot appears on the Chat option and goes away when you go back.

Pending. The view lists, from all the project’s chats open in this app session, what is waiting for a person: Question (a role’s question with options), Permission (a tool permission), Gate (an approval question of a workflow step), Role switch (the role proposes Switch to:), Chat switch (it proposes New chat: or continuing the cycle in the same chat) and Turn received (in collaboration, the turn passed to you; it shows here as well as in the system notification). Each row shows the type, what is waiting (two lines at most), the role, the chat and how long it has been waiting (refreshed every 30 seconds); the one waiting longest is at the top. You don’t answer anything from here: Open takes you to the chat (with the question or permission in view) and, for a gate, See document opens the document it reviews in the viewer and See changes opens the viewer’s Changes tab. The tab’s number goes down as soon as you answer in the chat. A footer reminds you that only chats open in this session are shown: what a chat asked before you closed the app can’t be known.

Header of Backlog, Improvements, Usage, Team and Pending. These views have a header at the top with their title and the project name (for example, “Backlog · my-project”). While the agent is working, a yellow dot and “{role} keeps working in Chat” appear on the right, with the active role.

With the keyboard. The switcher is a single tab stop: the ← and → arrows move between options (wrapping around at the ends), Home and End go to the first and last, and Enter or Space choose the option. Screen readers announce the selected option.

If the agent uses a pay-as-you-go API instead of your plan, a notice also appears in the project: every message is billed separately from your subscription; to use your plan, sign out and sign in with your Claude or ChatGPT account.

Side panel

A bar of icons on the left switches between sections:

• Workflow — the team’s workflow steps grouped by phase, with “Step N of M”. Completed steps have a ✓, the current one is marked Current, and optional or conditional steps appear dimmed. Each step takes a single line, with its number (or ✓) and its name, and all rows have the same height; a name that does not fit is cut short with “…”. Hovering over a step shows its number and full name, the role that does it (for example “4. Design specification — UI/UX Designer”) and its description. In shared projects, each step shows the person who owns the role. The panel only shows where the work is: the step advances when the next role is activated and when the role indicates which step it is working on (also when the same role moves from one step to another). When a role is activated, the step is that role’s next one; if its previous step is closer (the work goes back to it after a review with changes, for example from code-review to the Full Stack Developer), the step is that previous one: implementation, not git-push. If you open a new chat while the flow is on its last step (the close of the cycle or sprint), the flow moves to the start of the next cycle.
  • Step not updated notice. If after a Switch to: the agent’s reply does not mark its step, the notice “The workflow step may be out of date: the agent did not mark it when switching roles.” appears under “Step N of M”. It only informs: if the step is wrong, use Skip to a step…. It goes away by itself when a reply marks the step or the step changes, and with ×. It is not saved: it does not follow you to another chat or survive reopening the app.
  • Agent and model of the active role. Under the name of the current step, a line says which agent and model the active role works with, for example “Claude Code · Opus 5.5”. Before that role replies for the first time, it is the configured model (the role’s, or the one the team suggests) and carries the planned tag; if nobody sets a model, it shows the app’s default model with “(app default)”, for example “Claude Code · Sonnet (app default)”. After the reply, it is the model the agent reported and the tag goes away. If it doesn’t match the configured one, an amber line adds “≠ differs from configured: …”: it is for information only and changes nothing. Hovering shows the full explanation. The reported model is remembered per role while the app is open: when the role changes, the line goes back to planned until the new role replies. With Codex, the model shown is the one the app requests for the turn; Codex doesn’t confirm which one it used.
• Roles — the list of the team’s roles, with the Active role highlighted and the Proposed one (the one suggested by the role that just finished). It shows the owner of each role (in shared projects) and its model, if one is assigned. Links: Models per role… and Change team…. Hovering over a role shows the phrase to activate it (“Switch to: {role}”).
• Documents — the tree of the project’s documents folder (docs/ and its subfolders), as it is on disk; the Attachments; and the Team definition (team-ai-console.json, the workflow document and each role’s documents). Open folder opens the folder in the file manager. How to customize? opens a guide on how to add roles, change the documents folder or the quick buttons. Clicking a document opens it in the viewer. With the app’s teams up to date (Vela 4.10, Orion 1.6, Andromeda 5.4 and Lyra 3.2), each new sprint keeps its documents in its own folder, docs/sprints/sprint-N-name/ (the name comes from the sprint chat: «Sprint 14 - Folder per sprint» → sprint-14-folder-per-sprint); the documents of earlier sprints stay loose in docs/sprints/, without being moved.
• Diagnostics — the problems found in the team definition (for example, a role document that does not exist or a workflow step with an unknown role), or “The team definition was read without issues.”
• Readiness (checkbox icon) — seven signals that tell whether the project is ready for the roles to work with more autonomy; the icon has a red badge with the number of failing signals. See Project readiness.

Project readiness

The Readiness section of the side panel shows seven signals, each with an icon of a different shape, its color and a label: Ready (green circle with ✓), Attention (amber triangle with !), Failing (red circle with ✕) or Not checked (grey dashed circle). Under each name, a line says why. At the top, the summary (“5 ready · 1 need attention · 1 failing”) and when the last check with commands ran (“Last check: 3 min ago (when you pressed Check)” or “The project’s commands haven’t been run yet.”).

• When the project opens, only files are read. Signals 4 to 7 are computed from the documents, the local git status (no network) and the app’s data. The first three need to run commands or read the remote, so they stay Not checked, unless what’s missing already shows in the files (for example, no test command or folder, or no CI configuration): then they show Failing.
• Check. Runs the project’s commands without an agent, so it uses no tokens and doesn’t appear in Usage: it checks that the dependencies are installed (for example npm ls), runs the tests, starts the app for 10 seconds and stops it, and reads the last CI run. While it runs you see “Checking… 12 s” with Cancel, and each signal resolves when its own check ends. Everything stops at 120 seconds; a signal that didn’t finish in time shows Attention with “Didn’t finish in time.”. The commands come from the manifests in the code folder (package.json, pyproject.toml, Cargo.toml, go.mod, Makefile).
• When a sprint starts (when the chat of a new sprint opens, also from the Backlog) the check with commands runs by itself and the header says so: “(when the sprint started)”.
• Ask {role}. On a Failing signal (and on Attention for Documents up to date), if the team has a role that can fix it, a button takes you to the chat with the request already written in the box, without sending it: read it, change it if you want and press Send. If that role isn’t the active one, the request starts with “Switch to: {role}”. The role is chosen by its area: tests → quality (or implementation), commands and repository → implementation, CI → operations (or implementation), documents → documentation, assumptions → product. If the team has none, there is no button. Signal 7 doesn’t ask a role: it offers Edit models, which opens the models per role, and See roles with the affected roles.
• With Claude Code and with Codex the seven signals are the same; the agent and models signal names the agent each role works with.
• How this is checked, at the bottom, expands this summary inside the panel.

Document viewer

Shows the chosen document, Rendered (Markdown) or as Source, with Reveal in Finder / Show in folder and × to close it. It refreshes by itself when the file changes and, when the team writes a new document, it shows the most recent one.

Viewer states. The viewer body is never blank: while it reads the document it shows “Loading…”; if the document has no text, “This document is empty.”; if the file can’t be opened (it no longer exists, no permission…), an error box “This document couldn’t be opened” with the reason and Try again; and if the content can’t be shown with formatting, a box with View as text (shows it as source) and Try again. If the viewer itself fails, a notice “The document viewer ran into a problem.” with Try again and Close viewer. In every case the viewer header, the chat and the document list stay usable, and clicking another document opens it normally.

Files that aren’t text. An image, a .zip or any other binary file isn’t loaded in the viewer: instead, a grey box says “This file can’t be previewed”, with the name, extension and size (for example “.zip file · 48.3 MB”), and the header only keeps Reveal in Finder / Show in folder so you can open it with another app. The app only looks at the start of the file, so a large binary doesn’t slow it down. Text files open as always, whatever their extension, or with none.

Links. Clicking a link never takes the window out of the app. In the agent’s replies (the sprint chat and «Talk on the side»), each link opens according to where it points:

Paths are looked up from the project folder; an absolute path only opens if it is inside it. If a link can’t be opened, a short notice above the message box says why: the file doesn’t exist in the project, it points outside the project folder, the viewer can’t show that type of file (binary or over 1 MB), the app doesn’t open that link type (for example ftp:), the link points to another part of the reply (#section) or the system browser couldn’t be opened. The notice disappears after 6 seconds (it stays while the mouse is over it or it has the focus) and × closes it sooner. In «Talk on the side», which has no viewer, the document opens in the viewer of the project’s main window, which comes to the front; if the project isn’t open in any window, the notice says “Open the project in its main window to see the document.”. Hovering over a link shows its destination. Links inside a document in the viewer are explained in Viewer tabs, below.

Viewer tabs. When you click, inside a document in the viewer, a link to another document of the project (for example, those in index.md), that document opens in a new tab of the viewer. The tab strip appears above the header only when there is such a tab; the first tab is the document you chose in the Documents panel, the chat or «Talk on the side», and it can’t be closed (the whole viewer closes with its usual ×, and the extra tabs with it). Each extra tab has its own × to close it; when you close the one you are viewing, the one to its left stays. With the keyboard, ← and → move between tabs, Enter opens one and Delete closes an extra one. How each link is followed:

• If the document is already open in a tab, that tab is activated instead of opening another.
• An http:// or https:// link opens in the system browser; the viewer doesn’t change. Other link types (for example mailto:) do nothing.
• A link with a section (document.md#section) opens the document and goes to that section; a #section link only goes to that section of the document you are viewing. If the section doesn’t exist, the document stays at the top.
• Paths are looked up from the folder of the document that has the link (../ allowed) and must stay inside the project. A link to a document that doesn’t exist shows the notice “Can’t open this link: «…» doesn’t exist in the project.” under the header, with Dismiss; it also closes when you click a tab or open another link.
• Choosing another document in the Documents panel replaces the one in the first tab (or activates its tab if it is already open in an extra one).

View / Edit. The viewer header has a View | Edit switch. View is the usual reading. Edit replaces the content with the document’s Markdown text so you can write in it, in the same panel:

• You can edit the .md documents in the documents folder of the project (docs/ and its subfolders, attachments included). Those of the team definition (team/) and files that are not .md are read-only: Edit is disabled with the hint “Only .md documents in the documents folder can be edited”. The “How to customize?” guide does not show the switch.
• Editing requires an active license that includes Edit documents (also during the offline grace period). With a license that does not include it, an expired license or no license, Edit shows a 🔒 and, when you click it, the Edit documents dialog opens with See the license. If the license stops being valid while you edit, the viewer goes back to View and, if you had unsaved changes, shows your text so you can copy it.
• Save (or ⌘S / Ctrl+S) writes the file; Discard goes back to the last saved text. On the right you see “Unsaved changes” or, after saving, “Saved”.
• If you try to switch to View, open another document, switch or close a tab or close the viewer with unsaved changes, a strip warns you: Save and continue, Discard and continue or Keep editing. (Leaving the project does not warn yet.)
• If the document changes on disk while you edit it (for example, the agent writes it), a strip lets you choose Load the version on disk or Keep mine; your text is never lost unless you choose so. If the file had changed when you save, nothing is saved until you choose Overwrite or Load the version on disk.
• In a project with collaboration, the saved document travels with the next publication of the turn, like any other change.

Review. The third button of the switch, View | Edit | Review, lets you review a deliverable by annotating the document itself instead of describing the changes in the chat. It follows the same rules as Edit: only for .md documents in the documents folder (elsewhere it is disabled with “Only .md documents in the documents folder can be reviewed”) and with the Edit documents license feature (without it, it shows a 🔒). Review always shows the formatted document.

• Annotate. Select a passage with the mouse (or with Shift+arrows after entering the document with Tab) and pick Comment, Suggest replacement or Mark for deletion in the bubble. The same three buttons appear in the margin, in the Selected passage card, for keyboard use. Comment and Suggest replacement ask for the text (Save or ⌘/Ctrl+Enter; Esc cancels); Mark for deletion creates the annotation right away (with Edit you can add a reason).
• The margin. On the right (or below, collapsible, when the viewer is narrow) the annotations are listed in document order: type, the quoted passage, the section, “Occurrence n of total” if the passage repeats, your text and its status (Not sent, Sent, Addressed, Pending, or Not found if the passage is gone). Each annotated passage is highlighted with the color and shape of its type (dotted, wavy or strike-through); clicking a card takes you to the passage. Edit and Delete on each card.
• Where they are kept. In the project’s .team-ai-console/annotations.json, only for you: they survive closing and reopening the project, and that folder’s .gitignore keeps them out of git.
• Request changes (n). Sends the active role’s chat a message with the document and, for each annotation, its type, the section, the file line (if found), the quoted passage (and its occurrence number if it repeats) and your text, asking it to change only those passages and leave the rest as is. The message is in the app’s language and is plain text, so it works the same with Claude Code and Codex. Unsent and pending annotations are sent; while the role is answering a turn, the button is disabled with its explanation. If an approval question was open, it is first answered “in the chat” and the message is sent when that turn ends.
• Addressed or pending. When the role finishes its turn, each sent annotation becomes Addressed if its passage is no longer there as it was, or Pending if it is unchanged. A new Request changes sends the pending ones again (marked “pending from the previous request”) together with the new ones.
• Approve. Same as answering the approval option (for example “Build it this way” or “All good”) in the question panel. It is enabled only when the document is the step’s deliverable and its approval question is open; otherwise it is disabled with the explanation. If there are unsent annotations, it warns you first with Approve anyway, Request changes or Cancel.

See what changed. After Request changes, when the role finishes its turn the See what changed link appears in the Review header; it opens History with that comparison already picked.

History and Compare. The fourth button of the switcher, View | Edit | Review | History, lists the versions of the open document. Only for .md documents in the documents folder (on others it is disabled with “History is only available for documents in the documents folder”) and without a paid license: reading versions writes nothing.

• Versions. A table with a Compare checkbox, the date and time, the role and the turn that wrote it (“Turn 14”); the newest at the top, marked Current. Up to 6 rows show and the rest scroll. The app saves a version of each document that changes in a turn and another when you press Request changes (“before requesting changes”); in a git project, the versions from the file’s git history are added (with their commit; the role is taken from the turn that ended just before). The versions the app saves live in .team-ai-console/snapshots/, outside git.
• Compare. Tick two boxes (ticking a third unticks the older of the two). By default it compares the version saved the last time you requested changes with the current one; if there was no request, the two newest. The Document view shows the formatted document with what was added underlined on a green background and marked “+”, and what was removed struck through on a red background and marked “−”, by blocks (paragraphs, tables, lists). The Text view shows the Markdown with the same diff as Changes. A document over 1 MB is compared in Text view only.
• Annotations. If you sent annotations from Review on that document, the bar says “2 of 5 addressed” and the margin (on the right with a wide viewer, below and collapsible with a narrow one) lists each annotation as Addressed (its fragment changed between the two versions) or Pending (still the same).
• It works the same in projects with and without git.

Changes. Above the viewer there are two tabs: Document (everything above) and Changes (n), with the project files that changed:

• This turn | Sprint. “This turn” is what changed since your last message to the role (its whole reply); “Sprint”, since the sprint’s first turn (the chats of the phases of one sprint count together). The app takes a snapshot of the project each time you send a message: with git, in an index of its own that doesn’t touch yours; without git, in .team-ai-console/snapshots/. The .team-ai-console/ folder doesn’t count.
• File list. “8 files · +142 −37” and a row per file with A (added), M (modified) or D (deleted), the path and its added and removed lines. Binary files and files over 1 MB are listed with “no diff”. ↑/↓ move between files.
• Diff. Unified (two line numbers and +/−) or Side by side (before | after; only with a viewer 640 px wide or more). Three lines of context per change; the rest folds into “Show n unchanged lines”.
• Comment and Request changes. Click a line number (or click one and Shift+click another, or Shift+↑/↓, for a range; Esc cancels), write, and choose Comment (a remark or question, no edit needed) or Request changes (the role must fix those lines). The annotation stays under the lines with Edit and Delete. Send to role (n) sends the active role’s chat a message with, per annotation, the file, the lines, the quoted fragment, the type and your text; it is plain text, so it works the same with Claude Code and with Codex. When the turn ends each annotation becomes Addressed (its lines are no longer the same) or Pending; pending ones are sent again with the new ones. Changes annotations are kept in the app, only for you.
• Open in GitHub / GitLab. With a GitHub or GitLab remote, the link opens the comparison of the branch with the integration branch in the browser; with the branch not pushed it is disabled (“Push the branch to open it”). Without a remote (or with another provider) it doesn’t show.
• From the gate. When the question panel brings the question of the implementation or acceptance step and files changed, its context shows “8 files changed · See changes”: it opens the viewer on Changes and the question panel stays where it is.

The chat

Getting started. In an empty chat, the app shows the current workflow step (“Start here” or “Continue the workflow”) and the role in charge, with the Activate {role} button. You can also type your idea directly or activate a role by typing “Switch to: {role}” (in Spanish teams, “Cambiar a: {role}”).

Typing. Enter sends; Shift+Enter inserts a new line. Above the text box are the active role pill (or “No active role”) and the team’s quick buttons. Each of your messages shows which role it was addressed to.

Dictating by voice. On macOS and Windows, to the right of the text box (before Send) there is a microphone button. One click starts dictation: the button turns red, with a square “stop” icon and a pulsing halo, and the box says “Listening… speak now”. What you say appears live at the end of what you had already typed; another click stops. Dictated text can be edited like any other and is never sent on its own: it goes out when you press Send or Enter (if you do so while dictating, what is already shown is sent). If you type, paste or delete while dictating, dictation stops and your change is kept. Dictation uses the interface language (English or Spanish) and the system’s speech recognition, on your computer: no keys or external services. On macOS it works offline if the system has that language installed for dictation; on Windows it uses Windows speech recognition (you may need to turn on “Online speech recognition” in Settings › Privacy › Speech). The first time, the system asks for permission to use the microphone and speech recognition. If permission is missing or dictation isn’t available (no recognition for the language, turned off, or no microphone), a notice above the box explains what is missing; the chat keeps working and the notice closes with ×. The microphone is in the agent chat and in the “Aside” chat (not in the role editor or other fields) and does not appear on Linux. Note: the system’s own dictation (press fn twice on macOS, Win+H on Windows) also works in the chat box.

What you see while the agent works:

• The text of the reply in real time.
• The activity of the agent’s tools (reading, writing, running commands…), each with its status: running, in the background, finished or error, and the time elapsed.
• Stop (red button) interrupts the current turn.

What to do now. When the agent is not working, a bar above the text box always says what you can do:

• “{Role} is active: write in the chat to continue.”
• “{Role} is waiting for your answer: write it in the chat.” (if its last message is a question)
• “Next step of the flow: “{step}”, owned by {role}.” with the Activate {role} button (if no role is active)
• The proposal of the role that just finished (see below), if there is one.

When a role activates itself (for example, the initial role when a new chat opens) and announces it with “Switch to: {role}” at the start of its message, the app marks it as the active role. The app never proposes switching to the role that is already active.

Role suggestions. When a role finishes, it proposes the next one: a notice “The role suggests continuing with {role}.” appears with the Switch to: {role} button. If the role proposes opening a chat with the same name as the current one (for example, Sprint 0 was done in a chat already named “Sprint 1 - …”), the app does not open another: it shows “The role proposed opening "{name}", which is this very chat” with the Continue here button, which moves the flow to the first step of the next cycle and tells the role. If the next step belongs to the same role, the role proposes itself and the app shows “{role} suggests going on with its next step” with the Continue: {role} button, which asks it to go on in the same chat. It can also propose a new chat (for example, when starting a sprint), with a button to create it. The agent knows which chat it is in: if it proposes the chat you are already in, the app does not show it. The same sprint without the phase also counts as the current chat: in “Sprint 7 - Payments · Build”, a proposal of “Sprint 7 - Payments” (or “Sprint 7 - …” with another title) shows no button; “Sprint 7 - Payments · Test” does, because it is another chat. Continue here only appears when the flow is on its last step, where it leads to the next cycle; in the middle of the sprint the proposal is ignored.

Chats per phase. The flow phases marked with newChat (in the app’s teams: Sprint 0, Definition and Design in Orion; every phase in Vela and in Andromeda) start in a new chat. The previous phase’s context is already in the documents: a long chat makes the agent go over everything it contains on every call, and that is what consumes the most. By default the app handles it by itself, without asking you anything:

• When a role finishes and proposes switching to another whose step opens one of those phases, the switch happens in a new chat: the app opens it with the current chat’s name plus the phase (for example, “Compass · Build”) and activates the proposed role in it. The same happens when the step arrives through an agent mark, a skip or, in collaboration, with the turn; in that case the chat opens as soon as the running turn ends and it is your turn.
• Once the chat is heavy (40 turns, or about 120,000 tokens or more gone over on every call), any phase change also opens a new chat, even if the phase is not marked. It never interrupts within a phase.
• The previous chat stays in the list with a note saying which chat the phase continues in, and the new one starts with a note saying where it comes from. Names never repeat: the second time in the same phase is “… · Build 2”.
• A freshly opened chat is never split during its first turn, and a role you activated yourself in the chat (“Switch to: {role}”) keeps working in it.

If you prefer to decide yourself, turn off Automatic phase chats in the agent menu: the app goes back to proposing the chat in the bar (“The phase “{phase}” starts in a new chat: {name}“) with the button to create it, and to showing the context warning (“This chat has {N} turns and the agent goes over about {X} tokens on every call…”) when the chat is heavy.

Flow state for the agent. With each of your messages, when it changes, the app prepends (invisibly in the chat) a [Flow state] line with the current step and its id, the phase, the active role and the last document written. That way the agent knows where it is without re-reading documents and marks the right step.

Role questions. When a role needs a decision from you, the “The role needs your decision” panel appears with closed options (sometimes more than one can be selected). It is a floating panel: it doesn’t darken the window, the chat behind it stays visible and you can scroll it to reread earlier messages. Move it by dragging its header (the ⋮⋮ grip), or with the arrow keys while the header has focus (Shift for bigger steps); it can’t leave the window. It is landscape (about 860 px wide, narrower in small windows; if the content is long it stops at 60 % of the height and scrolls inside) and every question opens centered in the window, without remembering where you moved the previous one. Above the options, the panel shows where the question comes from: the Role, the flow Step (“4 of 12 · …”) and the last Document written, plus the Agent’s last message before the question, formatted and with its own scroll if it’s long; anything the app doesn’t know is left out. You can pick an option or click Answer in chat instead to reply freely. That applies to that question only: the next one with options opens the panel again. If you answer in the chat, the agent repeats the question with the alternatives in a numbered list (one per line) and you can reply with just the number, for example “2”.

Criteria review. If the question comes at a gate with acceptance criteria (see The team editor), the panel shows the Criteria review block above the question, with “Reviewer: {role}” or “Reviewer: project agent”. First it says “⟳ Reviewing criteria…”: the app starts, once per question, a separate, headless, read-only session with the project’s own agent (Claude Code or Codex), which reads the latest deliverable and modifies no file. When it ends, each criterion shows ✓ Met, ✗ Not met or ? Not checkable with a short reason, plus a summary (“2 met, 1 not met, 0 not checkable”). If there is some ✗ and one of the options matches a gate exit that goes back (for example “There is a problem”), that option is highlighted with “The review suggests this exit”; with no match, nothing is highlighted. If the review fails or 3 minutes go by, “⚠ The review failed: … You can still decide.” appears; if the answer cannot be read, every criterion shows “Not checkable” with the notice “unreadable answer”. The buttons always work, also while reviewing: the review guides you, you decide. If you answer before it ends, it is cancelled. A gate without criteria looks as usual. With delegation on there is no separate review at the gates the delegated role decides (see chapter 9); at reserved steps there is.

Permissions. When the agent wants to write or edit a file, run a command or use another tool, the Permission: {what} dialog opens with the details (for example, the change to the file, with the lines it removes and adds). Options: Allow, Always allow ({tool}) (it does not ask again for that tool in this session) or Deny. If there are several pending permissions, “+N queued” is shown. The permission mode in the agent menu changes when it asks:

• Always ask — asks for permission for every action.
• Accept file edits — does not ask to edit files; it does ask for commands.
• Automatic — does not ask (with Codex, it relies on its automatic reviewer).

Delegating to a role. If you do not want to answer every confirmation, you can delegate your responsibilities to a team role with the 🤝 Delegate chip in the top bar. How the three modes work, what the role does not do, when automatic progress stops and where each decision is recorded is explained in chapter 9.

Attach document. Copies a document (vision, PRD, brief, image…) into the project’s attachments folder (usually docs/reference/) and mentions it to the role so it reads it.

Log. Opens the process log: agent session, model, tools used, timings, errors and when changes were pushed to the remote.

Chats. The chat selector (showing the name of the current chat) lets you switch chats, Rename it, Delete it (removes it from the app; the agent session stays on disk) and create a + New chat. When creating a chat you choose its name (the app suggests one) and, optionally, a role that is activated when it opens. Each chat is an independent agent session, with its own history and active role, and it is resumed when you reopen the app. The selector is disabled while a turn is running. The menu header, with New chat, always stays at the top and in view; the list of chats, newest first, scrolls inside and the menu never goes off the window, however many chats there are or however short the window is.

Talk on the side. The Talk on the side button, to the right of the chat selector, opens a menu “Who do you want to talk to?” with the team’s roles and The model (no role, just the project context). It works with Claude Code and with Codex: it talks to the project’s engine and model. Choosing one opens a separate system window (with its own title bar; you can drag it, also to another monitor) while the sprint goes on in its chat:

• One window per project and interlocutor, and several can be open at once (up to 8 conversations across the whole app; beyond that, the menu says “Too many conversations are open; discard one.”). Choosing the same interlocutor again brings its window to the front. In the menu, each row is marked Open or Hidden if that conversation already exists.
• The window title and its header say who it is: “Aside · {role} · {project} · {team} · Sprint N · {engine} · {model} · {language}” (the engine is Claude Code or Codex; the language is the team’s). The window’s info line says “Project … · Team … · Sprint N · Engine … · Model … · Language …”.
• It answers even while a role is working in the sprint (the window says “The sprint is still working”), and what you write there does not change the workflow step or the active role, nor does it show “Switch to:” or new chat proposals.
• It can only read project files: it does not write code or documents and does not ask you for permissions. There is no option to change this. With Claude Code, it also does not run commands.
• With Codex, read-only mode is enforced by Codex itself (it works in a read-only sandbox, without asking for approvals): it cannot create, change or delete files even if you ask it to. To read the project it runs read-only commands (ls, cat, rg…), which show up as tool rows in the conversation; a command that tries to write fails. Web search is turned off. If you have MCP servers configured in your Codex (~/.codex/config.toml), Codex could use them from «Talk on the side», and those run outside read-only mode; the app rejects the ones that ask for approval, but it cannot stop one that doesn’t (Codex’s default configuration has none).
• If the project’s engine is not installed, the window says “{engine} isn’t installed or the app can’t find it. Install it or set its path in Home → Agents, then send your message again.”; if it isn’t signed in, “{engine} isn’t signed in or its session expired. Sign in with the Sign in button in the top bar of the project window, then send your message again.”; with any other error, “Couldn’t answer: {reason}”. In every case you can send again.
• If you change the project’s agent while an «Aside» conversation is open, the next message starts a new conversation with the other engine.
• Attaching evidence (a screenshot of an error, a log): the Attach file button, on the right of the row below the messages, opens the system file picker (you can pick several); you can also paste a screenshot into the text box with ⌘V (Ctrl+V on Windows and Linux); if the clipboard only has text, the text is pasted as usual. Images (png, jpg, gif, webp) and text or log files (txt, log, md, json, csv, yaml, xml) are accepted, up to 10 MB per file and 5 files per message. Attachments appear above that row, with a thumbnail (or 🖼/📄) and their name; ✕ removes one. Below them, a notice reminds you that files are saved in the project (docs/backlog/evidence/) and may end up in git: don’t attach passwords or personal data. If a file is not an accepted type, is too big, there are already 5 in the row or it can’t be copied, a message says why and the conversation goes on. You can send with attachments only, without text. The sent message shows “📎 Attachments: …” and the agent reads them. If the conversation ends in a saved request, the backlog item links them in an Evidence section and the message says “Saved “title” in … with n evidence file(s) in …”; files you send after saving that same request are added to that section. Files that don’t end up in a request are deleted from the project when you press Discard or quit the app (closing the window deletes nothing). It needs the Attach documents license feature, like the sprint chat’s Attach document: without it, the button shows 🔒 and pasting an image doesn’t attach it.
• Dictating by voice: the text box has the same microphone button as the agent chat, between the box and Send, with the same behaviour, notices and permissions (see Dictating by voice in the chat chapter). Pasting a file or closing the window also stops dictation; when you reopen it, the microphone is stopped. Dictation runs in one window at a time: if you start dictating in another, the previous one stops and keeps what it had already written.
• Not everything has to go to the backlog: you can use «Talk on the side» just to clear up doubts. When the conversation reaches a clear decision or wish, the agent asks whether to save it as a request and does not draft it until you say yes; if you say no, it saves nothing and does not ask again about the same thing (only if you bring up something different). If you ask it to save it, or press Save as request, it drafts it without asking.
• Save as request (or asking the agent in the conversation) drafts what was discussed and the app saves it as a pending item of the project backlog, in docs/backlog/bk-YYYYMMDD-{name}.md (type —feature, change or bug, proposed by the agent—, status, date, origin and the request: problem, decision or wish, draft criteria and a conversation summary), and updates the index docs/backlog/index.md. It no longer writes to docs/reference/ or docs/request-log.md. The “Saved “title” in …” message gives the title and the path. If the agent drafts several requests in one answer, the app saves them all, one after another and in the order of the answer, each in its own backlog item and with its own “Saved “title” in …” message; if one can’t be saved, its “Couldn’t save “title”: …” message gives the reason and the others are saved anyway (attached evidence goes to the first one saved). The agent gets the list of all of them, so it doesn’t draft them again. If you pressed the button and the agent replied without drafting it, a message says so and the button stays available to try again; if saving fails (disk, permissions), the message gives the real reason. You can save several in the same conversation, one entry per decision; an existing one is never overwritten. If you save the same request again (same title and body) in that conversation —for example, asking for it in the chat and then pressing the button—, no new entry is created and the message “The request “title” was already saved in …” tells you where it is. Discard forgets what was saved in the conversation.
• What you save appears in the Backlog view (see below) and the role that starts the next sprint proposes it to you.
• The conversation is kept while the app is open: closing the window (system button or ⌘W) hides it without asking, and leaving the project hides them too; when you choose the interlocutor again, the conversation continues where it was. A window where you wrote nothing closes completely. Discard deletes the conversation without asking for confirmation (requests already saved are kept, with their evidence; attached files that didn’t end up in a request are deleted). Nothing is left after quitting the app.
• On the Projects screen, if there are conversations, the Aside (n) button appears: its menu lists “{role} · {project}” and brings the window to the front, even if the project is closed.
• Its usage is counted separately, with the project’s engine (see AI usage).

Backlog. The Backlog option of the view switcher in the top bar opens the project’s requests saved in docs/backlog/; to go back to the chat, choose Chat in the switcher.

• A list with title, type and status (pending, in sprint N or done) and creation date (new items also carry the time, YYYY-MM-DD HH:mm; older ones only the day). The In sprint · Pending · Done · All filter narrows it, and In sprint is selected on opening, with the first item of the list selected. To the right of the filters, the Date ↑ / ↓ button sorts the list by creation date and time: on opening it goes from oldest to newest (Date ↑) and pressing it reverses it (Date ↓); it does not group by status, the filter does not change the direction, and when you close and reopen the backlog it goes back to In sprint and Date ↑. Items of the same day without a time are ordered by their id. The ↑↓ arrows move through the list.
• In the header, Talk on the side to add something new opens the same “Who do you want to talk to?” menu as the chat’s Talk on the side button. If the conversation with that person is new, the window starts with “Tell me what you want to add to the backlog.”; if it already existed, it is shown as it was. The request you save shows up in the list without leaving the backlog. It is visible with an empty backlog too and works with Claude Code and with Codex, like the Talk on the side button.
• Choosing an item shows its content read-only, its origin and its path; Open in documents shows it in the viewer.
• Pending items have Start a sprint with this: it opens the chat “Sprint N+1 - {title}” (or uses the current chat if it is empty), activates the role that starts the sprint and sends it the request; the item becomes in sprint N+1 and the role does not ask you about the backlog. The button is disabled, with the reason below it, if a sprint is in progress (“A sprint is in progress. Finish it before starting another one.”), while the agent is replying or if the team has no workflow. In collaboration it only appears on the machine that has the turn.
• To start a sprint with several pending items, tick the checkbox each pending item has on its left (Tab and Space work too; ticking doesn’t change the item in the detail). When you tick the first one, the Selected: N bar appears above the list, with Start sprint with the selected ones and Clear selection; the ticks are kept when you change the filter, and an item that stops being pending is unticked by itself. The button opens the chat “Sprint N+1 - {first title} and {k} more” (or uses the current chat if it is empty), sends all the items to the role that starts the sprint and sets them to in sprint N+1. It has the same blocks and license as Start a sprint with this: with a sprint in progress you can tick, but the button is disabled with the reason at the top of the panel.
• Every item has the Status selector (Pending, In sprint, Done), between Start a sprint with this and Delete, with the current status selected. You can go from any status to any other: choosing Pending or Done applies the change straight away, with no confirmation. Choosing In sprint shows the Sprint number field below it (suggesting the highest sprint number in the backlog): type a whole number greater than 0 and press Apply or Enter; Cancel or Esc leave it as it was. The change is saved in the item’s file and in docs/backlog/index.md, and the pill, the list and the filter update at once (if the active filter no longer includes the item, the neighbouring one is selected). A done item does not offer Start a sprint with this; if you set it back to pending, it does. Like Delete, it needs the Sprint from the backlog license feature (without it, it shows 🔒 and opens the same notice).
• Every item (pending, in sprint or done) has Delete. It opens the “Delete this item” window with its title: Delete removes it for good from docs/backlog/ and its index (there is no trash or undo in the app; if the project is in git, you can recover it from git) and the neighbouring item is selected; Cancel or Esc change nothing. If the item is in sprint N, the window warns that the sprint carries on but, when it is accepted, there will be no item to mark as done. If the deletion fails, the reason appears in the window itself. Like Start a sprint with this, in collaboration it only appears with the turn and needs the Sprint from the backlog license feature.
• When a sprint starts in a new chat, the app passes the pending backlog to the starting role (with any team, the app’s unchanged ones included): it asks you only once “What do you want to include in this sprint?” in a multiple-choice window (title and type of each; with more than 4, in several lists “Backlog 1/2”, “Backlog 2/2”…, up to 16). You can tick one or several; if you tick none or answer in “Other”, it asks what you want to do and the backlog does not change. The picked ones become in sprint N. If you pick several that are different requests (from the panel too), the role warns you, recommends what goes in now and what to leave for future sprints, and waits for your decision: what you leave for later goes back to pending. When the sprint ends (the flow reaches its last step, the end of the sprint), the app moves each item that went in to done, even if the role does not mark it and even if it carries another sprint number; if the sprint does not end (you abandon it or it goes back to the interview to fix something), they stay in sprint N. Items are only deleted with Delete. With an empty backlog there is no question.
• The first time a project without docs/backlog/ is opened, the open “Future” rows of docs/request-log.md are copied once into the backlog as pending (what was already accepted stays as history). With no items, the view says “There are no requests in the backlog yet…”.
• Importing issues from GitHub or GitLab. In the backlog header, the Import issues… button brings in the open issues of the project’s remote repository (origin, or the first remote; an HTTPS or SSH URL on github.com or gitlab.com) and creates one pending item per issue, with its title, its description (or “The issue has no description.”), the origin “Issue #N from {repo}” and, in the detail, the line Issue #N · Open in the browser. The type comes from the labels: bug is a bug, feature or enhancement is a feature, and anything else is a change. Pull requests and closed issues are not imported. You can import as often as you like: the notice below the header says “{n} new, {m} already there (from {repo}).” and nothing is duplicated; what was already imported is not updated or deleted even if the issue changes or is closed on the remote. If any is created and the filter is In sprint or Done, it switches to Pending so you can see them. Each import brings at most 200 new issues; if there are more, the notice says so and the rest arrive when you import again. Public repositories are read without a credential; for private ones, the app uses the HTTPS git credential you already have saved for that host (for example, after a push). If something is missing, the notice says what: the project is not a git repository, it has no remote, the remote is not on github.com or gitlab.com, the repository is private or the credential is missing, the host is limiting requests, or there is no network. It needs the Sprint from the backlog license feature and, in collaboration, the turn.
• Closing the issue when done. When an imported item becomes done (when the sprint is accepted, when it ends, or with the Status selector), the Close the issue on GitHub window (or “Close N issues”, with a checkbox per issue, if there are several) shows the comment that will be posted —“Resolved in Sprint N — {name}.” and, if the sprint close is already pushed, its link— and closes nothing until you press Close issue. The app posts the comment first and then closes the issue; if the comment fails, the issue is not closed and the window says why. Not now (or Esc) leaves the issue open, the detail shows “Not closed from the app” and you are not asked again; you can ask for it later with Close issue… in the item’s detail. An issue closed from the app shows “Closed on {date}”. Closing needs a credential with write access to the repository. If a role question is open, the window waits until you answer it.
• Pipeline status. If the repository has GitHub Actions or GitLab CI, the question of the acceptance gate (in Lyra, the user test step) shows the Pipeline (CI) strip with the status of the current branch’s latest pipeline (Running, Passed, Failed, or Cancelled or skipped), the branch, View pipeline and Refresh. It is informational only: it does not change the gate’s options. Without CI, without pipelines on that branch, or with a remote that is not GitHub or GitLab, it does not appear; if the check fails, a discreet line says why. With delegation on, the delegated role decides the gate without the question, so the strip is not shown.

Background tasks. If the agent leaves tasks running in the background (for example, a server or a long test), they appear in a “Still running in the background…” box with their elapsed time. Each one has Stop, which asks the agent to stop it; if it was the last one, the role continues with the next workflow step. Stop all (with confirmation) closes the agent process and everything it had running; then the active role continues with the next step. Stop tracking them removes them from the list if they have already finished and no notice arrived.

Skipping to a step. The notice “Want to go straight to another workflow step?” has the Skip to a step… button: you choose the destination step, see which steps will be left undone and, optionally, write the reason. I would rather explain it in the chat makes the agent ask you which step you want to go to. Every jump is recorded in .team-ai-console/workflow-log.md (in a collaborative project, in workflow-log.md on the app branch).

Expired session. If the agent is not signed in, the chat tells you: use Sign in in the top bar and send the message again.