RunLogosRunLogos

Quick Start: From Proposal to Auto-Archive

This tutorial walks you through your first full unattended run. Before starting, make sure OpenLogos CLI (≥ 0.13.6) and your agents are ready.

Step 1: Create a change proposal

From the project root (where logos/logos.config.json lives):

cd <project-root>
openlogos change my-feature

The CLI scaffolds logos/changes/my-feature/ with proposal.md and tasks.md templates, and takes the active-change lock.

Step 2: Let an agent fill in the proposal

Ask any open agent to fill in the proposal for my-feature. It analyzes the impact surface and writes the change rationale, scope, deployment decision, and task lists.

While the proposal is still a bare template, the drive button stays disabled (the content-readiness gate) with the hint "proposal is being written". This is deliberate: it prevents the driver from grabbing the PTY of an agent that is still drafting. The button re-enables automatically once content is ready.

Step 3: Open agent sessions

The Driver only picks executors from open agent tabs — it never spawns headless sessions. Open at least one agent; to enable multi-agent review, open a second, different one.

Step 4: Click Drive and configure the run

The launch dialog configures everything in one screen:

  1. Mode: semi-automatic / fully automatic (default);
  2. Primary agent: pick one open agent;
  3. Multi-agent review (optional): choose reviewed stages (deltas + code by default), a reviewer agent (must differ from the primary), and a conflict policy (the default strict-then-lenient is recommended);
  4. Advanced: block severity, max review rounds, and the cumulative findings cap (a per-proposal review-lifecycle ceiling, not a per-round quota);
  5. Optionally save as the project default (persisted to driver.review in logos.config.json).

Click Start — the Driver takes over.

Step 5: Watch it drive

  • The stage flow highlights each phase from proposal writing through archive;
  • Each stage row shows the current action and latest output summary;
  • With review enabled, a six-state review sub-row appears under the reviewed stage;
  • The menu-bar icon shows running drivers at a glance.

You can walk away — heartbeats and watchdogs guarantee that a stuck run stops loudly instead of hanging silently.

Step 6: Let verify / smoke failures self-heal

Failed verification doesn't need you: the Driver dispatches the failure summary back to the agent, reruns, and loops to convergence. Same for smoke (fix → rerun verify → redeploy if needed → smoke again). Only when repair rounds are exhausted with tests still red does it stop for takeover — that is the loop-exhausted red line.

Step 7: Deployment — automatic in full-auto, confirmed in semi-auto

In fully automatic mode you do nothing here: once verify is green, standing authorization passes the deployment entry gate, the Driver executes the merged deployment plan, stamps completion via openlogos deploy-done, and moves on to smoke automatically. In semi-automatic mode, a confirmation appears before deployment — review the summary and release the gate yourself.

Step 8: Archive — automatic close-out in full-auto

After smoke passes, fully automatic mode archives the proposal automatically: it moves into logos/changes/archive/ and the active-change lock is released — the run is complete, which is exactly what "unattended" means. In semi-automatic mode the proposal waits for you to click archive and confirm.

Step 9: Replay in the lifecycle log

Open the proposal lifecycle log page: the verdict banner, the ten-step milestone strip, and a stage-partitioned timeline (with every review round expandable) let you replay exactly who did what, when, and how it turned out.