# Plan a feature in the chat

You can plan a feature in the chat (⌘J), with the in-app assistant or a machine's Claude Code, Codex or Gemini CLI. You don't need an Orca
session or the `andon` CLI for it. The chat turns the feature into cards on the board and suggests which ones should
ship together in one pull request.

## How it goes

1. **Ask.** "Plan the login revamp for Web", or pick *Help me plan a feature as cards* when you start a new
   conversation with the assistant. If the conversation is scoped to a team (the scope picker in the chat's header), the
   plan goes to that team.
2. **The chat reads first.** It looks at the cards that already exist and at what the team's repositories remember
   (their `.andon/` memory). Then it splits the feature into cards that can each be built, reviewed and merged on their
   own, in dependency order.
3. **You see the plan before anything is added.** It's a short numbered list with each card's title, team › project,
   what it depends on and which cards ship together. Change it in the conversation ("merge 2 and 3", "put the API in
   Platform") until it's right.
4. **Say yes.** The chat adds every card in one go, in the order shown, to the Backlog:
   - Each card's notes are written for a run that sees nothing but the card: *Goal*, *Where to look* and *Done when*.
   - A card that depends on earlier cards ends with a `## Depends on` section that names them by title and key (`WEB-12`).
   - The chip says what landed: *added 4 cards to the Backlog (WEB-12, WEB-13, WEB-14, WEB-15)*.
5. **Confirm the groups.** For each set of cards that has to land in one pull request, the chat shows a
   *Group into one pull request* card. Your tap creates the PR group, with the same rules as grouping on the board:
   one team, one project, one repository and nothing running.

## What it never does

- **Start work.** Planned cards wait in the Backlog. Ask the chat to start them ("run the Session group", "start
  WEB-12"), or start them on the board. Autopilot only picks up cards that reach Ready.
- **Group without your tap.** Grouping is always a confirmation card, as it is for approvals and archiving.
- **Add a plan twice.** If a card fails partway (for example, a team name that matches nothing), the plan stops there.
  The chat tells you which cards landed and doesn't resend them. Fix the problem and ask for the rest.

The `## Depends on` section is an instruction to the run, as it is for plans added with the CLI. Andon doesn't hold a card back
because of it. If a card must wait for another before it can start, add the dependency in the card's
*Blocked by* field ([Sub-tasks and relations](https://andon-docs.pages.dev/guide/subtasks-and-relations.md)).

## Who answers, and on which model

The provider menu in the chat's header picks who answers: the *Assistant* (in Andon, no machine needed), or *Claude*,
*Codex* or *Gemini CLI* on the machine you pick. A machine conversation runs that CLI on the machine's own login: for
Codex, the machine user's `~/.codex` login; for Gemini CLI, the one `andon accounts login gemini default` signs in
([Accounts and providers](https://andon-docs.pages.dev/machines/accounts-and-providers.md)). Codex and Gemini CLI are only offered when a
machine can host the conversation right now: it's online, has that CLI installed, its policy allows it
(`andon policy executors`), and its agent is recent enough to run it in the chat (`andon update`). With one of them
picked, the machine menu lists only those machines. If none can, the provider menu leaves the CLI out, and a chat that
used it last time starts on Claude.

On a phone the pickers sit behind one line in the chat's header that sums them up, such as *Claude · Studio Mac · All
teams*. Tap it to open **Chat settings**: **Who answers**, **Machine**, **Model** and **About**.

Whichever CLI answers, it has the same orch_* tools and nothing else: no shell, files, web search or editing. Codex runs
read-only with its shell tool off; Gemini CLI runs under a policy that denies every tool except the andon server's. If the
machine's chat ceiling is `plan` (`orchestratorMaxPermissionMode`), Codex and Gemini CLI only get the tools that read
the board and open things on your screen.

The picker beside the machine chooses the model the CLI runs the conversation on: the models your org allows in
*Settings → Automation* that this CLI can run, or *Default model* (whatever the CLI on the machine uses). Changing it
mid-conversation applies from the next message. The chat remembers your pick for each machine and CLI in this browser,
so your next conversation there starts on it.

## For a bigger plan

A plan has at most 20 cards and 10 groups. For research first (findings, open questions, a proposed project with
dependencies that the board enforces), start a [study](https://andon-docs.pages.dev/guide/studies.md) instead. The CLI does the same as the chat from a
terminal: the `use-andon` skill's *plan-to-cards* reference.

## Under the hood

Both chats use the `orch_plan_cards` tool, then `orch_group_cards` once for each group. The plan's rules (handles,
dependency order, groups in one team and project) and the `## Depends on` wording are in
`packages/shared/src/feature-plan.ts`. The in-app assistant imports the same file. Each card is created through `orch_create_card`, so the audit log shows *added a card*,
made through the orchestrator, for each one.
