Architect reference
This page lists runtime facts for Sero Architect. See Architect for the user guide.
Availability
Architect is the built-in @sero-ai/plugin-architect plugin. It has global
scope, so each profile has one project list. It requires persistent agent
sessions, the Orchestrator plugin, and the host capabilities
appAgent.invokeTool, tool.cli, appRuntime.background and
appRuntime.workspaceCreate.
SERO_ARCHITECT_MODEL names the owner's model as provider/model, with an
optional :thinking suffix. Without it, the owner uses the MED tier: the
project default when you set one, otherwise the global selection in Admin. A
tier never falls back to another provider. An unavailable model or an
unsupported thinking level is refused, and the reason is reported.
Terms
Phases and overlays
Phases, in order: intake, discovery, charter, build, release,
maintain. A project never moves back.
Overlays: decision, blocked, paused, limited. An overlay is derived on
every write from the record's flags and is never set by hand.
Milestone statuses
Verification states on a milestone: reported, verified, accepted,
delivered. A lower state never stands in for a higher one.
Wake sources
The runtime wakes the owner for these events, highest priority first:
One wake runs at a time. Wakes of the same kind merge. Ordinary work does not
wake the owner while the project is paused, limited, blocked or stopped.
Directives and decision responses can still wake it. Every wake ends with one
of sleep, decide, blocked, work --operation continue or
work --operation wait; three turns in a row with no outcome
block the project.
Owner tool
The owner reaches the runtime through one bridged tool, architect, run as
sero architect --action <name> --projectId <id>. Every call carries the
project id and is refused for any session that is not that project's owner.
The owner session holds only the architect command and the platform tools.
The architect_projects management tool refuses an owner caller, so the owner
cannot approve its own charter, raise its own cap or answer its own decisions.
Management tool
The user's chat and the project page use architect_projects.
pause lets running turns finish. stop requests cancellation of the owner
and the project's owned work, including active Rooms and Workflows. The project
retains failures and unconfirmed remote termination across restart. Late usage
stays attributed to the work that started it. delete removes the record and
the owner session's grant; files in the folder stay.
At an exhausted cap, directives and decision answers are saved without a paid owner wake. Pending approved work waits too; raising the cap sufficiently replays saved input through the existing project record, including after restart. Cap approvals and Stop remain usable.
Direct work
The owner can do a milestone itself instead of dispatching it. The work
action refuses the request unless all of these hold:
- the project was made under an agreement, not the deprecated charter flow;
- the milestone is not linked to an OpenSpec change;
- the project is in
build,releaseormaintainand has no overlay; - no other direct execution is active;
- in Workspace execution mode, no Workflow or Room is writing the project folder.
In Worktree execution mode, begin opens a checkout and branch for the
milestone at .sero/worktrees/, and the owner works only there. report
commits the work to that branch.
The identity holds the execution id, the run, the owner session, the folder, the starting commit and content, and the requirement revision. It is saved before any file changes. A report for replaced work, or for requirements that changed after the work started, is refused.
A continue wake queues behind every other wake. A pause, a block or the cost
cap holds it. No rule stops the work for making no progress. The run inspector
shows the continuations in a row that changed no file.
A stopped turn, a stalled turn or a restart sets the work to interrupted. The
files and the identity stay and nothing is taken as complete. The owner resumes
with continue.
A report is a claim and leaves the milestone at reported. Evidence,
acceptance and delivery follow the same rules as for dispatched work. The
owner's own test runs are a self-check, not an independent review. With
--destination workspace-files, the delivery receipt is the project folder in
Workspace mode and the milestone's branch in Worktree mode, and the milestone
is delivered once it is accepted. Any other destination is refused: dispatch
the delivery. With no destination, the milestone can be accepted and not
delivered.
On the Work view's Plan tab, the milestone list shows architect as the kind.
After the report, the row links to Evidence.
Waits
The owner can end a wake by waiting for something to end. It runs
work --operation wait --source <kind> --target <id>. Sero saves the wait, and
wakes the owner once when the source ends, fails or is gone.
An expired wait and a failed wait wake the owner with that fact. Neither is completion: the milestone still closes on evidence. If Sero cannot confirm how the work ended, it holds the project and names the work. A pause, a block, the cost cap or an approval that is not given prevents the wake. The ended wait stays on the record. Stop ends every open wait, and none of them wakes the owner afterwards, even if you resume the project.
Sero reads a child source's saved state when it changes, and a process
source when any dev server changes. It reads both when the runtime starts and
when a deadline passes. A dev server that Sero no longer lists, for example
after a restart, holds the project: Sero cannot tell how it ended and does not
start it again. A ci source is read every two minutes while the wait is open.
A read that fails changes nothing and is tried again. No read starts a turn by
itself; only an ended wait does.
Stall recovery and limits
Sero does not stop an owner turn at a fixed time. A turn that keeps working runs as long as it needs. Any tool call, result or text restarts a silence timer.
These are internal safety values. You cannot change them. Limits that you set, such as the project cost cap, are hard stops and are checked as before. Three turns in a row with no declared outcome also hold the project. The run inspector lists each limit and who set it: you, a safety value, a default or an agent.
Tools and skills
The owner session registers every tool your approval allows. It starts with a
small loaded set, and it finds and loads another approved tool in the same
session with Pi's tool_search. A tool outside your approval is not
registered, so the owner cannot find or call it. One line in the owner's prompt
lists the approved tools it does not have, and why: its plugin is not
installed, you turned it off, it is not available to this kind of session, or
it is outside the approval. After the session reopens, the owner can search
for the tool again.
A new project also asks, in its start approval, for Code Mode when Sero offers
it. An approved Code Mode starts loaded, because tool_search cannot find it.
A script can call only the tools the session was approved for, so Code Mode
adds no access. A project that already exists keeps its old approval and does
not gain Code Mode.
A new project asks, in its start approval, for the skills that are enabled in
its workspace. They are listed to the session by name and description, and it
reads one when the work needs it. tool_search finds tools, not skills. A
project that already exists keeps exactly the access it had. The host can amend
a grant, as it does for a running Room,
but no Architect action or control asks it to widen an existing owner yet.
Forced escalations
The runtime raises a decision itself, with the proposal attached, when the
owner tries to change an approved charter, deliver to a destination outside
the workspace (email-send, chat-post, webhook-post), or spend over the
remaining cap. The proposal is applied only when you pick apply.

Delivery
A release milestone names a destination. Inside the workspace: pr,
workspace-files, saved-artifact, email-draft. Outside it, always a
decision first: email-send, chat-post, webhook-post. A delivery receipt
is recorded on the milestone; it never substitutes for verification.
Maintenance
On entering maintain, the runtime creates one Workflow subscribed to
github:issue-opened, github:ci-failed and the schedule 0 8 * * 1
(Mondays at 08:00 UTC). Each run wakes the owner to triage. A fix is a
milestone and moves through the same four verification states.

Runs and telemetry
A project groups its work by objective. One objective has one run, so the run inspector can show what an answer cost without mixing it with the next one. Several objectives can be in flight at once.
Each charge is written to the run journal as the same delta the budget takes, so a run's total and the project spend for the same scope reconcile. A replay of a cumulative report adds nothing.
Coverage is never smoothed. A source that reported no tokens, a run that predates run identity, or a restart that lost part of its telemetry all report as incomplete. Counters nobody reported stay absent rather than showing zero, and an older record keeps the amount it recorded without inventing the calls behind it.
Strategy comparisons
Sero developers can compare the Architect with one persistent chat agent on the same task. The comparison holds these inputs equal: the request, the starting files, the acceptance checks, the model and effort, the capabilities, the cost cap and the time limit. Each strategy chooses how it does the work.
The first baseline records have partial cost coverage and no run identity. They stay available with that classification. The procedure is in the Architect plugin README.
State and storage
The UI, widget and management tool read the index and project record. Open session also reads persistent owner-session history. Layout preferences persist through the host layout service, never through browser storage.