> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Architect

Sero Architect manages work across a product instead of one task. Give it a
request and a start cap. It plans the work, builds it through Workflows and
Rooms or does small pieces itself, and checks the result. The cap stops new
work when reported spend reaches it; active requests can still add cost.
Architect checks the result before it moves on to release and maintenance. It
asks for your input when it needs a decision.

Use Architect when you want Sero to take a product from idea through
maintenance. Use [Orchestrator](/guide/orchestrator.md) when you want to run one
Workflow, Room or Goal yourself.

![Architect project list showing project phases, spend, and items that need attention](/static/image/architect-projects.de84c58ee2.png)
## Before you start

1. [Install and open Sero](/guide/getting-started.md).
2. [Configure a model](/guide/models-and-providers.md). Architect runs its owner
   session on the **MED** tier: the project default if you set one, otherwise
   the global selection in Admin. Delegated Workflows and Rooms resolve the same
   way per tier. Set `SERO_ARCHITECT_MODEL` to override the owner regardless of
   tier. Architect never falls back to another provider: if the selected model
   is unavailable, it says so and asks you to choose.
3. Make sure Orchestrator is available. Architect dispatches its work through
   Workflows and Rooms.

Architect keeps one persistent agent session for each project. When a project
starts, Sero asks for permission to run that session, as it does for a Room
member. The session can access only the project folder and the tools you
approve.

For a new project, the same approval also asks for the skills that are enabled
in the workspace, and for Code Mode when Sero offers it. The session finds an
approved tool by searching for it. The approved skills are listed in its prompt,
and it reads one when the work needs it. It can use only what you approved. A
project that already exists keeps the access it had, without Code Mode, and the
project page has no control to add more. Start a new project to get them.

## Create a project

1. Open **Architect** from the app bar and select **New project**.
2. Under **What do you want?**, write the request in your own words. Architect
   keeps the text exactly as you wrote it. You do not need a plan, a team or a
   quality level: Architect chooses the agents and the steps.
3. Choose **New folder** and give a name and a location inside your home
   directory, or choose **Existing workspace** and select one. A workspace that
   already has an Architect project, and the Global workspace, cannot be chosen.
4. Set the **Start cap ($)**. Research, building, checks and repairs all use
   this one budget. Reported usage gates new work; requests already in flight can add cost.
5. Select **Continue**. Sero then shows its own approval prompt with the access
   the project asks for. Paid work starts only after you allow it.

If you do not allow the access, the project stays **Not started**. Select
**Review access** on the project page to see the prompt again.

A project made this way runs under a delivery agreement: it continues on its
own under the spending and access limits you approved, and it asks you only when a
decision is yours to make. A project made before this change runs on the
**charter flow**, which is deprecated. It keeps its saved charter and its
approvals, and it is marked "charter flow · deprecated" on the list and on its
page. Sero does not convert it. New behaviour, such as the Architect doing work
itself, applies to projects made under an agreement and not to the charter flow.

For an experimental OpenSpec path, turn on **Use OpenSpec for coding changes**
at creation. This project flag initialises `openspec/` in the selected folder.
The proof of concept uses **Workspace** execution. The first build still uses
the ordinary Architect charter and milestones; the flag applies to later
change requests in maintenance. For an existing Workspace project already in
maintenance, use **Enable OpenSpec changes** in the project controls menu.

![Architect setting up a new project](/static/image/architect-intake.32ec14cc8c.png)
Architect creates the folder, runs `git init`, registers the folder as a Sero
workspace, and then asks you to allow the owner session. The project stays in
`intake` until you allow it. After that, work starts in `build`.

## Phases

A project under an agreement goes from `intake` straight to `build`, then on
through `release` and `maintain`. It never moves back.

| Phase      | What happens                                                                                          | What you do                             |
| ---------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `intake`   | The folder, repository and workspace are created.                                                     | Allow the owner session.                |
| `build`    | The Architect researches, plans milestones and does or dispatches them. Each closes only on evidence. | Answer decisions.                       |
| `release`  | The last milestone is delivered, for example as a pull request.                                       | Approve delivery outside the workspace. |
| `maintain` | A maintenance Workflow listens to issues, CI failures and a weekly review.                            | Answer the decisions it raises.         |

A charter flow project also has `discovery` and `charter` between `intake` and
`build`, where you approve its charter.

### Request later changes with OpenSpec

In an OpenSpec enabled project that has reached `maintain`, type a request in
the project page composer and select **Start OpenSpec change**. Repeat this for
each later change. The `architect_projects` tool also accepts
`action: "request_change"`, `projectId` and `text`. A normal directive remains
available for instructions that are not a new coding change.

Architect creates a separate `openspec/changes/<name>/` scaffold and a linked
milestone for each request. It sends the question to a read only Room to
investigate the codebase, options, requirements and unresolved choices. The
Room reports findings to Architect; it does not edit the implementation.
Architect then writes the proposal, capability specs, design and tasks in that
change folder, following the OpenSpec CLI's artifact instructions. The runtime
requires completed planning artifacts and strict CLI validation before the
milestone can be planned or dispatched. With the default `milestones` autonomy,
you approve its plan on the project page.

The approved milestone goes to a Workflow with the change path in its prompt.
The Workflow implements the tasks and updates `tasks.md`; Architect runs its
usual evidence checks and compares the result with the requirements before
accepting it. The next request creates another change in the same project.
The PoC leaves completed changes in place for inspection and does not archive
or sync them into the project's durable OpenSpec specs automatically. The
Room reproduces the investigation part of `/opsx:explore` within Sero; it is
not an interactive OpenSpec command session.

An overlay describes a stop or wait during a phase. It does not add a phase:

- `decision`: a question waits for you. Nothing that depends on it moves.
- `paused`: you paused the project. Running work finishes, but Architect does
  not start more work until you resume.
- `limited`: spend reached the cap. Raise the cap to continue.
- `blocked`: the owner needs help it cannot get on its own. The page says why.

## The project page

The project page is a board of tiles. The top tile says where the project is,
with steps done, spend against the start cap and elapsed time. If Sero cannot
confirm that work is live in this session, it says "Last known". The tiles below
it show only what applies now:

- **Needs you** lists each question with its options and their effects. The
  option the Architect suggests is marked. Pressing an option sends your answer.
- **Not started** or **Stopped** carries the control that fixes it, for example
  **Review access**.
- A wait card shows what the Architect waits for and until when. See
  [Waiting for work](#waiting-for-work).
- **Live** lists each agent that works now, grouped by its Room or Workflow,
  with the tool it runs. Select a row to read what that agent writes at this
  moment. The text is sent only while the row is open. **Open the Room** and
  **Open the Workflow** open the same work in Orchestrator. While the Architect
  does a milestone itself, its group is headed with that milestone's name.
- **Result** has **Open preview** and **See the checks**.

The side column holds the **Plan** and **Decisions made**. The note box at the
foot sends the Architect a short note at any time. Current work continues.

## The Work view

**Full plan** and **Research** in the Plan tile, and **See the checks** in the
Result tile, open the work behind the board. It has three tabs:

- **Plan** shows your request as written, the working plan and its acceptance
  criteria, each step with its state, Architect's last report, and under
  **Your notes** every note you sent with its answer.
- **Research** shows each research question and its findings.
- **Evidence** shows the checks that ran for each step.

History is its own view, opened from the project controls menu (⋯). The page
never shows an event log. To read the owner's session, select **Open session**
in the top bar.

## Work the Architect does itself

The Architect can do a milestone itself instead of starting a Workflow or Room.
It chooses by the work: a task one agent can finish stays with the Architect,
and work that needs specialists, parallel effort or an independent reviewer is
dispatched. A small task needs no Workflow, Room or planning step. Workflows and
Rooms work as before.

- **Available when.** The project was made under an agreement and the
  milestone is not linked to an OpenSpec change. A charter flow project and an
  OpenSpec change always dispatch.
- **Where it works.** In a **Workspace** project the Architect works in the
  project folder. In a **Worktree** project Sero makes a checkout and branch
  for the milestone, the Architect works only there, and reporting commits the
  work to that branch.
- **Saved identity.** Before any file changes, Sero records the work with an
  execution id, its run, the owner session, the folder, the starting commit and
  the requirement revision it answers. Starting the same work again returns the
  same record.
- **Continuing.** The Architect can ask for another turn. Your instructions,
  answered decisions and events from running work are handled first. A pause, a
  block or the cost cap stops it. There is no automatic stop for a lack of
  progress: reported spend reaching the cost cap requests cancellation. The run inspector shows how many
  continuations in a row changed no file.
- **Interruption.** A stopped turn, a stalled turn or a restart marks the work
  interrupted. The files and the saved identity stay, nothing counts as
  complete, and the Architect resumes the work.
- **One writer.** The Architect's own work and a Workflow or Room that writes
  the project folder never run at the same time.
- **Reporting is a claim.** When the Architect says the work is complete, the
  milestone is `reported` and the evidence rules below apply unchanged. Its own
  test runs are a self-check, never an independent review. If you require an
  independent review, a reviewer that did not do the work still runs.
- **Delivery.** Work reported with the destination `workspace-files` is
  delivered once it is accepted. The receipt is the project folder in a
  Workspace project and the milestone's branch in a Worktree project. Any other
  destination goes through a dispatch and its user decision. With no
  destination, the milestone can be accepted without being delivered.

In the milestone list on the Plan tab, such a milestone shows `architect` as its
kind. Once it has reported, it links to **Evidence**.

## Waiting for work

When the Architect has nothing else to do until something ends, it can wait.
It can wait for a Workflow or Room it started, for a dev server that Sero
manages, or for the CI checks of a branch or commit. Sero wakes it once when
that thing ends, fails or passes a deadline that the Architect set. You do not
need to resume it.

- A wait that ends in a failure or a deadline is not completion. The Architect
  sees the fact and decides what to do next. A milestone still closes only on
  evidence.
- Sero refuses a wait on anything else. In that case the Architect ends its
  turn and says what you should check. You resume the project.
- If Sero cannot confirm how the work ended, it holds the project and says why.
  A dev server that is gone after a restart is held this way. Sero does not
  start it again.
- **Pause**, **Stop** and the cost cap still apply. A paused or stopped project
  is not woken, and **Stop** cancels every open wait.

[Goals](/guide/goals.md#how-a-goal-ends) wait in the same way.

## When a turn goes quiet

The Architect has no fixed time limit for a turn. A turn that keeps working runs
on. If it shows no activity for 10 minutes, Sero asks it to save its work and
end the turn. If it is still quiet 5 minutes later, Sero interrupts the turn
and wakes the Architect once more. A second quiet turn in a row holds the
project for you. Resume it when you are ready. Limits that you set, such as the
cost cap, still stop the work.

## Milestones close on evidence

A milestone is complete only when Architect has checked it. The owner cannot
mark a milestone done by saying so. Architect runs the project's check
commands, reads the git diff, and for a milestone with a preview route it
starts the dev server, loads the route in a hidden window and saves a
screenshot. The capture does not change what the user is looking at. The result
is recorded on the milestone as one of four states:

| State       | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| `reported`  | the work claims it is complete                              |
| `verified`  | Architect's checks passed at a named commit                 |
| `accepted`  | the owner accepted the verified result                      |
| `delivered` | the result was delivered, for example a merged pull request |

![Architect board while it works: the live browser view, the plan with proof for the finished step, and the decisions made](/static/image/architect-build.bb0c3eb4b4.png)
A lower state never stands in for a higher one. If files change after the
evidence was taken, the evidence is marked stale and the checks run again.

## Decisions

Architect asks for your approval before it:

- delivers anything outside the workspace, such as an email or webhook;
- spends beyond the cap.

A project under an agreement continues on its own otherwise. **Autonomy** in the
controls menu (⋯) changes what else you approve:

| Setting                                    | What you approve                    |
| ------------------------------------------ | ----------------------------------- |
| `charter-only` (default for a new project) | nothing beyond the list above       |
| `milestones`                               | each milestone plan as well         |
| `model-judged`                             | what the Architect decides to raise |

A charter flow project also asks before it changes its approved charter. Its
default is `milestones`.

A decision has no timeout and no default. Work that depends on your answer
waits. Other milestones keep running.

### Research that must run something

A research Room reads by default: one shared checkout, no shell. When the
owner knows a question can only be answered by running commands, such as a
test suite or a build, it asks for a Room with command access. Each member
then works in its own worktree and may run commands, but still must not
implement the product.

If a Room's planner asks for something it does not have, that question comes
to you as a decision instead of stopping the project:

- **Let the Room run commands** plans the research again with command access.
- **Answer in a note** withdraws the research and gives your note to the
  owner, which rewords the question.
- **Withdraw the question** drops the research and the owner continues without
  it.

## Cost

Every project has a cost cap: the start cap you set when you created it. Spend
includes the owner
session, research runs and every dispatched Workflow and Room. When the project
reaches the cap, Architect stops starting new work and requests cancellation
of its owned work. Requests already in flight can add cost before cancellation
takes effect. Raise the cap from the project page to continue.

Replies and decision answers are saved while the cap is exhausted. They do not
start another paid turn. Raise the cap above reported spend to process the saved
input. Stop and the cap controls remain available.

The cap limits the work Architect starts. It is not a ceiling on what a project
can spend: cancellation may not stop an active provider request or remote
process immediately. The project records the cancellation request and any
work it could not reach. The spend line shows a lower bound. When a source
reported a total without per-call detail, or did not report at all, the amount
is marked as incomplete rather than filled in.

## Run inspector

Open **Run inspector** from the controls menu. It shows where a project's time
and money went, and it opens on the totals: reading the individual operations is
a separate action named **Load activity**.

- **View** selects **Shared activity** or one run. A project groups its work by
  objective, so each run answers one thing rather than one session.
- **Cumulative spend**, **By activity** and **By model** are computed from the
  operations shown. A row in the activity chart sets the timeline filter, so the
  two always describe the same records.
- **Selected activity** shows an operation's own cost and, separately, its
  inclusive cost with everything below it. The inclusive figure is never added
  into a total that already counts those operations.
- Shared activity is charged once to the project and is reported beside a run's own figure, never inside it.
- A filtered view says which scope its total covers, rather than presenting part
  of a run as the whole of it.

Model and thinking level are shown together, because the same model at two
effort levels is two decisions. An operation that recorded no model says so
rather than showing a blank.

## Requests and linked work

The project board shows requests that need your answer, including session access
and permission prompts. The workspace attention mark also stays visible while a
request is pending. Answering the request clears it from both places.

Linked Workflows show their progress and current steps. Open a Workflow to reach
the saved run, or open a Room to review its questions and result. Completed
research remains under **Made** on the board.

After restarting Sero, the board keeps the saved reason a project paused or
stopped. A wait that reaches its deadline offers **Resume work**; resuming is a
manual choice when Sero cannot confirm the result of the work it was waiting on.

## Controls

The **Result** tile keeps the requested outcome beside Architect's account of
what it delivered. It shows recorded checks, their commit and requirement
revision, saved destinations, and requirements that still need review. Expand
a check to read its full output. A report from an agent, a passing check,
acceptance, and recorded delivery are separate facts. Missing or stale proof
keeps the result marked for review.

Use **Open result**, **Open Git changes**, or **Open preview** when available.
Saved destinations and checks describe what was recorded; opening the output
lets you assess its current state. Project totals show elapsed time through the
last update and recorded cost, with an explicit label when accounting is
incomplete. **Request changes / continue** focuses the existing message box;
write and send your request there. OpenSpec projects also offer **Start OpenSpec
change** when they are in maintenance.

For a result delivered on a worktree branch, **Open recorded result** opens its
saved checks and diff. The branch stays visible, but the board cannot open that
branch's files or live preview. Its checkout may have been released. The project
folder's preview is not a preview of the delivered branch.

The controls menu on the project page offers:

- **Pause** and **Resume**. Pause prevents Architect from starting or planning
  new work. Work in flight continues.
- **Stop**. Stops future work and requests cancellation of the Architect and
  its owned Rooms, Workflows and subagents. Some remote processes may still
  finish. The project keeps the cancellation outcome across restart, and late
  usage remains attributed to the run that started the work.
- **Raise cap**.
- **Autonomy**. Cycles through the three settings.
- **Models…**. Sets a project model default per tier. A tier with no project
  default inherits the global selection in Admin.
- **Run inspector…**. Opens the run inspector for this project.
- **Delete project**. Removes the record and the owner session. Files in the
  project folder stay.

## The dashboard widget

The Architect widget shows your projects with their state lines and the
number of items that need you. With no projects it offers one action, **New
project**.

## Related pages

- [Architect reference](/reference/architect.md): tools, record fields, statuses
  and storage.
- [Orchestrator](/guide/orchestrator.md): Workflows, Rooms and Goals.
- [Manage a Room](/guide/rooms-advanced.md): how a running Room changes its team and tools.
- [Goals](/guide/goals.md): waits and limits for one chat session.
