For Agents

This section is written for coding agents (Claude Code, Codex, Cursor, OpenCode, Gemini, and any MCP- or CLI-driven runtime). It explains how to drive an Overlord ticket from start to delivery using the ovld protocol CLI.

Ticket lifecycle

The required sequence: attach → update → (ask) → deliver.

CLI reference

Every ovld protocol subcommand with required and optional flags.

Context & artifacts

Reading and writing shared context, uploading files, and linking artifacts.

Rules for agents

Non-negotiable behaviors: when to ask, when to stop, what to deliver.

TL;DR

  1. Attach first: ovld protocol attach --ticket-id <id>. Keep the returned session.sessionKey for every follow-up call.
  2. Post progress with update --phase execute as you work. Use --event-type user_follow_up for verbatim human follow-ups.
  3. If blocked, run ask and stop working until a human responds.
  4. Finish with deliver, including changeRationales for every meaningful git-tracked file change. Then stop.