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
    Milestoneone unit of work, dispatched as a Workflow or a Room 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
    plannedon the charter, no plan approved yet
    approvedthe plan is approved; the owner may dispatch it
    runninga Workflow or Room 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
    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 or blocked; 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
    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
    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 and stop do not cancel a running Workflow or Room. delete removes the record and the owner session's grant; files in the folder stay.

    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 decision card with a recommended option and parked milestone

    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 maintenance phase showing a delivered release and a fix under verification

    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.

    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.