Runs and operations

Status, stats, and the dashboard

/guild:status is the one place to read where a project stands. The bare form writes no .guild/ data.

Bare status

/guild:status shows the current run state, the furthest phase, the next gate, blockers, the layout version, and the active team for each phase. It resolves state by a filesystem scan, or by an optional SQLite read-through cache that lives on platform state, off the repo. --no-index skips the cache.

A legacy single-file team.yaml is reported once as legacy; status never acts on it.

Sub-verbs

The dashboard

/guild:status dashboard launches the local benchmark UI: a runs table, a Knowledge view, and a Wiki browser. It imports the project's run logs and prints the URL.

• Port: default 3055. If that port is taken, it moves to the next free one. --port N picks another.
• Checkout: it looks for the benchmark repo as a workspace sibling, then in-repo, then as a cached clone under .guild/cache/benchmark.
• No network by default. A clone or an install happens only after you confirm it.
• Managed, not a daemon. The server logs to .guild/cache/dashboard.log and records its PID in .guild/cache/dashboard.json, which --stop reads.

Use stats when you want text in the terminal. Use dashboard when you want to browse runs and the knowledge graph in a browser.

Run analysis in the dashboard (upcoming beta)

The upcoming beta (next) releases add a behavioral-analysis view to the dashboard. You can start an analysis of one run, a comparison of several, or an analysis of an initiative or an independent-run group, and watch the job's progress. The analysis itself always runs in the plugin; the dashboard only displays its artifacts and triggers the plugin's own commands.

Three rules keep what you see honest:

• Evidence states are explicit. A report renders as current, stale, missing, malformed, or failed — each distinctly. A stale report (its inputs changed since it was computed) is never actionable; refresh the analysis first.
• Partial evidence stays partial. Not every event class has a producer wired yet, so some conclusions report unobservable instead of a verdict. Absence of evidence never proves success.
• A recommendation decision is scoped and explicit. Before you decide, the panel shows exactly where the decision lands: accepting a plugin recommendation writes a local draft under .guild/recommendations/drafts/ (nothing is filed anywhere external); accepting a project recommendation moves it to the queue in .guild/recommendations/queue.jsonl. Neither accept implements anything — implementation is always separate, later work, and the plugin re-checks freshness at decision time and refuses a stale decide.

The status line

Guild Stack ships a small script that prints one line of run state: the phase, the review round, the loop cap, the active loops, and the restart count. It is off by default.

Turn it on

statusline is a settings-schema key with default false. It is not a policy key, so /guild:config set statusline … is refused in v3.0.0. Use one of these:

• Pass --statusline through Guild Stack's runner.
• Export GUILD_STATUSLINE=1 yourself before you start the host.

The script prints nothing unless GUILD_STATUSLINE is exactly 1.

When the key is true, the agent-team launcher exports GUILD_STATUSLINE=1 and passes it to every specialist pane. If you already exported it, the launcher keeps your value. If settings cannot be read, it leaves the variable unset.

What it shows

With a run id and a counters file, the line is:

phase: build | round: 2 | cap: 16 | loops: all | restarts: 0

The run directory is GUILD_RUN_DIR if set, else <cwd>/.guild/runs/<GUILD_RUN_ID>.

Fallback lines

The script always exits 0 and prints no errors. It reads the host's stdin JSON so the host does not block, but it does not use its fields.

What the source does not cover

The plugin ships the script and the opt-in key. The v3.0.0 source does not register the script as a host's status-line command, and hooks/hooks.json does not reference it. The HELP text for the key describes a tmux status pane. This page does not claim which hosts render the line. Treat it as a script you point your host at yourself.

See Config reference for the statusline key and Status, stats, and dashboard for the status command.

Ops runbooks

/guild:ops is the operations phase. It runs a runbook: a written, reviewed procedure for a release, an alert, an outage or a revert. Every runbook runs behind a mandatory pre-flight dry-run. For the phase overview see Lifecycle in depth.

Try it

/guild:ops              # Guild suggests a runbook and asks you to confirm
/guild:ops <runbook>    # name the runbook yourself

Either way the class is confirmed with you before anything runs.

The five classes

The five runbooks are chapters of one assembler skill, not separate skills. Approving a runbook lowers only the soft gate. It never lowers the hard set.

Where runbooks live

A runbook's trust root is .guild/wiki/standards/runbooks/<name>.md. It is promoted through the decisions flow. See Knowledge.

Four safety rails

The router enforces these for every class, before dispatch. Rail 4 has two legs, so four rails produce five checkable booleans in guild.ops.v1. All five must be true.

The hard set is release, security, ops and destructive. The gates that can never run autonomously are ops and destructive.

An op_class_allowlist may never contain a destructive, network or spend class. Plan validation rejects it with exit code 2.

The pre-flight dry-run

The dry-run is rail 4. It is mandatory and the router checks it before the runbook is dispatched. The result is recorded as preflight_dry_run_ran. Every hard-set step is also recorded as autonomy: prompted_inline.

Risky or destructive steps prompt you every time.

Refusing on a quality BLOCK

Ops reads the quality report from QA. If its recommendation is block and no human force_pass is recorded:

• release and rollback refuse, and route you back to QA.
• monitoring, maintenance and incident may proceed.

Review and evidence

The ops team is composed and approved before any dispatch. Its advisory challengers are security (always) and architect (only on the multi_component signal). A cross-host reviewer is optional and policy-gated, as in QA. Neither changes the safety rails.

Records go under .guild/runs/<run-id>/ops/, with per-step evidence in ops/evidence/. Every run writes guild.ops.v1. Incident and rollback also write guild.incident.v1. Release also writes guild.release.v1.

Ops only supplies evidence for closing an initiative. The release record carries outcome.status, doc_sync_status and release_evidence_refs. Closing stays with the initiative close gate. See Initiatives.

Initiatives

An initiative is work that spans more than one run. It is opt-in. A one-off /guild:guild run never creates one. Attachment is always explicit, in one of three ways:

1. You run /guild:initiative … directly.
2. You pass --initiative=<id|new> to a phase command.
3. Your brief names a durable goal. Then /guild:guild asks you: attach to a new initiative, an existing one, or keep it one-off. It never attaches on its own.

Initiatives live under .guild/initiatives/active/<id>/ and .guild/initiatives/archived/<id>/.

Sub-verbs

The close gate

close runs a deterministic gate script (the D8 gate) and refuses on a non-zero exit. It also refuses when any cited evidence path does not exist: a close_gate.evidence entry or a work-item evidence_refs entry. The skill never re-decides the outcome in prose.

An unknown sub-verb prints usage and runs nothing.

Workspaces

A workspace is a folder whose immediate children are separate projects. Each child has its own .git/ or .guild/. Guild Stack has exactly two state levels: the workspace root (the umbrella) and its immediate children (the sub-guilds). Each level has its own .guild/. There is no third nested level. The umbrella reads child state in place. It never replicates a child's agents, skills, wiki pages, initiatives, or runs.

How Guild Stack detects one

/guild:init and /guild:learn map run a detection script before they scan anything. It looks at immediate children only. Depth is fixed at 1. A child counts if it holds a nested .git/ or .guild/. Plain folders such as docs/ match neither and are ignored. Guild Stack shows you the verdict ("detected N sub-guilds: …, by rule …"). It is never silent, and you can override it.

On a regular repo, none of this runs and nothing changes.

The workspace.mode setting

Set workspace.mode in .guild/settings.json to override detection.

The default is auto.

What init writes on a workspace

• .guild/workspace.json (schema guild.workspace.v1), the federation manifest. It lists each detected sub-guild. A script writes it, and re-running init refreshes it without clobbering other state.
• A root wiki, only when the manifest says root_wiki: true. That is the case when the root itself has scannable top-level code. A pure federation root (for example, just docs/ and the child repos) gets no root wiki.
• For each child that has no .guild/ yet, Guild Stack offers to run /guild:init on it. It registers the child either way. It never auto-inits and never forces.

All writes land under the workspace's own .guild/. Detection and registration are read-only on every child's .guild/.

Federation: query, not copy

When the root has a .guild/workspace.json, a wiki query does not stop at the root's own (often empty) wiki. It fans out across every registered sub-guild that has a wiki, then merges the results into one ranked list. Each hit is tagged with the sub-guild it came from. The root wiki joins as one more source when root_wiki is true.

• A query that names one sub-guild searches only that sub-guild.
• A query that names none searches all of them.
• The same fan-out feeds a lane's context bundle. No child knowledge is copied into the bundle, and the bundle size cap is unchanged.

The same rule holds for the knowledge graph. Each child keeps its own codebase-map.json and knowledge-graph.json under its own .guild/. The root graph never merges them. Cross-repo references are counted and left unresolved, not turned into root-graph nodes.

When pages conflict

The plugin at v3.0.0 has no rule that ranks the umbrella wiki above a child wiki. A federated query uses the normal contradiction policy instead. When two returned pages contradict on the same claim, the newer page wins, unless the older page has confidence: high and the newer one does not. Guild Stack never picks silently. It shows both pages with their paths, updated_at, confidence, and a resolution: line, and suggests guild:wiki-lint so a person decides.

If your team wants the umbrella wiki to win cross-project conflicts, keep that as a workspace convention (for example in the umbrella AGENTS.md). Guild Stack does not enforce it.

Learning across children

/guild:learn map on a workspace registers the children. It does not auto-run a deep scan on each. The no-argument /guild:learn does fan out. Its behavior follows the workspace knowledge setting learn_fanout:

• auto (default): fans out to the children after showing a cost estimate.
• plan-only: writes the fan-out plan to .guild/runs/<run-id>/learn/workspace-plan.md and stops.

--dry-run always behaves as plan-only.

Once children have their own harvest candidates, a script can stage the cross-cutting ones for the umbrella. It writes only a reference manifest at <root>/.guild/runs/<run-id>/upstream-candidates.json. It writes nothing under .guild/wiki/. A candidate lands in the umbrella wiki only through the separate, human-gated wiki-ingest step.