For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/architect.md.

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

TermMeaning
Projectone idea, its folder, workspace, owner session, charter, milestones, decisions, directives, budget and history
Ownerthe persistent agent session for one project; the runtime runs it on the project's behalf
Charterthe brief, milestone list, cost cap and autonomy setting proposed after discovery and approved by you; only the deprecated charter flow uses it
Milestoneone unit of work, dispatched as a Workflow or a Room or done by the owner itself, and closed only on evidence
Decisiona question raised to you with options, consequences, a recommendation and a reason
Directivea message from you to the owner; it replies once
Evidencecommand results and a diff summary recorded by the runtime at a named commit; preview milestones also include a capture
Wakeone turn of the owner session, started by the runtime for an event

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

StatusMeaning
plannedadded to the plan, no plan approved yet
approvedthe plan is approved; the owner may dispatch it
runninga Workflow, a Room or the owner is running it
verifyingthe work reported completion; the runtime is checking the evidence
doneaccepted on verified evidence
parkedwaiting on an open decision; returns to its previous status when answered

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:

KindCause
directiveyou sent a directive
decisionyou answered a decision, approved a charter or plan, or raised the cap
dispatch-blockeda Workflow or Room needs input or stopped
dispatch-completea Workflow or Room finished and the evidence check ran
external-eventthe maintenance Workflow ran for an issue, a CI failure or its schedule
waitwork the owner waited for ended, failed or passed its deadline; see Waits
continuethe owner asked for another turn on a milestone it does itself
quietthe project was created, research finished, or planned work remains

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.

ActionEffect
briefrecords the brief
charterproposes the charter; on an approved charter it raises a decision instead
milestoneadds a milestone, sets its plan, or claims completion (--done), which is refused without evidence
decideraises a decision and parks the milestones it names
researchasks the runtime to run a structured research subagent
dispatchasks the runtime to create a Workflow or a Room for a milestone
workdoes a milestone itself: --operation begin --milestoneId <id>, --operation continue, --operation report --executionId <id> --text "..." [--destination workspace-files], or `--operation wait --source child
evidenceasks the runtime to run the checks; the owner cannot attach results itself
statusreads the record
replyanswers the open directive
blockedends the wake blocked, with a reason
sleepends the wake

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.

ActionParameters
listnone
showprojectId
createidea, folder or workspaceId, capUsd (the start cap; with it the project runs under a delivery agreement)
feedbackoptional projectId. Returns what the project's owner, research, Workflows and Rooms do now, as bounded metadata with no output text
watch_owner, unwatch_ownerprojectId, observerId. Opens or ends one view's watch on the owner's current turn
watch_room, unwatch_roomprojectId, roomId, observerId. The same for a Room the project started; any other Room is refused
pause, resume, stop, deleteprojectId
raise_capprojectId, capUsd
set_autonomyprojectId, autonomy (milestones, charter-only, model-judged)
approveprojectId, target (charter or milestone), milestoneId
answerprojectId, decisionId, optionId, optional note
directiveprojectId, text

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, release or maintain and 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.

OperationEffect
beginsaves the execution identity and starts the work. A repeated call returns the same execution
continueends the wake and requests a continue wake. A directive without a reply must be answered first
reportrecords a completion claim for the current execution and moves the milestone to verifying

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.

PartRule
child sourcea linked Workflow or Room. Name it by its milestone or research id
process sourcea dev server Sero manages in the project's workspace, by the id sero devserver list shows. It must be running. Exit code 0 or a stop satisfies the wait; any other exit fails it
ci sourcethe CI checks of a branch or commit in the project's repository, read through gh. Sero refuses the wait when gh cannot read them. All checks passing satisfies it; one failing fails it
Milestonea process or ci wait belongs to the milestone the owner does itself, or to --milestoneId
Deadline--deadlineMinutes, from 1 minute to 7 days. Without it a child or process wait has no deadline and a ci wait ends after 6 hours
Wakeone per wait. The wake is saved before it is sent and marked used when its turn starts, so a restart does not send it twice
Anything elseSero refuses it. The owner ends the wake with sleep or blocked and says what you must check. You resume the project
Already finishedthe call is refused and returns the result

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.

SilenceWhat happens
10 minutesthe owner is asked to save its work and end the turn with an outcome
5 more minutesthe turn is interrupted and the owner is woken once more
a second stall in a rowthe project is held for you. Resume it when you are ready

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.

Architect board asking a two-option question, with the step it holds waiting for your answer

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.

Architect board after delivery: the result with Open preview and See the checks, and proof for each step

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.

TermMeaning
Runone objective's work, opened before its first model call and closed when it ends
Shared activitywork charged once to the project and linked from the runs it served, never split by a guessed share
Attributable costcost charged to the run itself
Aggregate coveragea total a source reported without per-call detail
Observed waita wait whose start and end were both recorded, by cause

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.

RuleEffect
The outcome comes from the task's checksno dispatch failure is not acceptance
A run that did not finish is incompleteit is kept, and it supports no claim
An input that differs is namedthe difference is not credited to the strategy
A record is not compared with itselftwo distinct runs are necessary
Missing model or cost data stays missingno total-cost claim from partial cost
An intervention is recordedthat run does not show unassisted completion

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

PathContent
~/.sero-ui/apps/architect/state.jsonthe index: one row per project (id, name, phase, overlay, state line, spend, cap, needs-you count)
~/.sero-ui/apps/architect/projects/<id>.jsonthe full project record; the runtime is its only writer
~/.sero-ui/apps/architect/runs/<project>/<run>.*one run's journal and its checkpoint
<folder>/.sero/apps/architect/evidence/<milestone>/<commit>.pngcaptures taken by the verifier
<folder>/.sero/apps/architect/research/<id>.mda finished research report, referenced from the owner contract instead of repeated in it

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.