# The design-apply flow

| Step | What happens | Who acts |
| --- | --- | --- |
| 1 | Maps the app | Agent, `shadcn-maestro reviewer` |
| 2 | Shows the stack and its pages; asks which page and which mode | Agent, then you |
| 3 | Works on the page you confirmed | Agent |
| 4 | Analyzes the page and has an independent session confirm its reading | Agent, `shadcn-maestro review` |
| 5 | Shows a proposal | Agent |
| 6 | Waits for your "sim", then applies the change with your `shadcn` | You, then agent |
| 7 | Checks the page in the browser | Agent, `agent-browser` |
| 8 | Runs the app's checks and reports | Agent |
| 9 | Asks before committing | You |

## 1. Map

The agent runs `shadcn-maestro reviewer` (see [reviewer](/cli/reviewer)). It stops, with your files untouched, when the app is Astro (`astro_not_supported`) or uses an unsupported stack (`stack_not_supported`), and asks which app to use when there are several (`multiple_apps`).

## 2. Stack, page and mode

Before reading any page source, the agent presents the stack and the mapped pages by route (such as `/customers`) and asks you to confirm or choose the page, an existing one or a new one, and the mode: **redesign** (recommended) or **conservador** (see [Modes](/agent/overview#modes)). Then it waits. If the answer names no mode, it asks again. A `manager_conflict` issue is shown to you before any install command.

## 3. Choose the page

The agent reads the page in depth only after you confirm it.

## 4. Analyze, annotate, review

1. The agent reads the page, its layouts and components with `shadcn-maestro reviewer --screen <id>`.
2. It records what each region does with [`reviewer annotate`](/cli/annotate).
3. It opens a separate reviewer session with `shadcn-maestro review --cwd <repo>`. When an annotation has browser evidence, it starts the app's dev script and passes `--url <app-url>`, then stops the process.
4. The reviewer checks the references, can observe the running page with `agent-browser`, and submits `confirmed`, `disputed` or `insufficient_evidence` with [`reviewer review`](/cli/review).

There is no proposal while any annotation of the page is not `reviewed`. A dispute comes to you with both readings and their sources.

## 5. Propose

Before choosing each component, the agent reads its official page on https://ui.shadcn.com/docs for your base. The proposal lists:

* the layout and each shadcn component, with the reason for it;
* every file to change;
* the other screens affected by shared components;
* every global effect: theme CSS, dependencies, `components.json` and shadcn setup.

When the app has no `components.json`, the proposal includes the shadcn "Existing Project" setup for its stack, with the exact `shadcn init` command.

In redesign mode the proposal also names `shadcn init --base <base> --preset nova --force --reinstall`, the diff of the global CSS, every `components/ui` file it replaces and every screen as affected. The layout uses an official block from https://ui.shadcn.com/blocks when one fits, listing every file the block writes.

## 6. Apply after "sim"

Only an explicit "sim" (yes) to the current proposal approves it; "you choose" does not, and a changed proposal needs a new "sim". Then the agent:

1. runs the approved `shadcn init` (redesign), then `shadcn add` for the blocks and components;
2. edits only the approved files plus the files `shadcn` writes, keeping `components/ui` as generated;
3. stops and asks you if `shadcn` prompts for anything the proposal does not answer;
4. stops and reports the failed command and the files already changed if `shadcn` fails: no retry, no rollback.

## 7. Verify in the browser

The agent starts the app's own dev script, opens the page with `agent-browser` and checks the agreed states and interactions, then stops the process. Without Chrome, or when the app does not start, the report says the browser check was not done and why.

## 8. Check and report

The agent runs the `typecheck`, `lint`, `test` and `build` scripts that exist and reports in its final message:

* the mode used;
* every changed file, as `git status --porcelain` lists it;
* every dependency added or changed, marking the ones the proposal did not name;
* each check and its result;
* each browser interaction and what it observed;
* everything not done.

Only a failed check makes the delivery incomplete.

## 9. Commit

The agent asks whether to commit and commits only after an explicit "sim", including `.shadcn-maestro/` (map and reviews). It never pushes.