/report

ao report

Persist a meaningful worker report for durable delivery to the active project orchestrator.

Syntax

ao report <free-form-text>
ao report --checkpoint --note <text> [output flags]
ao report --needs-input --note <text> [output flags]
ao report --stuck --note <text> [output flags]
ao report --done --note <text> [output flags]

Output flags are repeatable:

--artifact <absolute-path>
--pr-created <pr-or-mr-url>
--pr-reviewed <pr-or-mr-url>

Use reports for meaningful transitions, decisions, blockers, required input, outputs, and terminal judgment. Do not file a report for routine commands. Outputs do not imply completion, and `--done` does not terminate the session.

Attach a reviewable deliverable as soon as it is ready, not only at `--done`: use `--artifact <absolute-path>` on the report for the milestone that produced it, one flag per deliverable, not its supporting files. Examples include a requested document, a rendered dashboard, or another output the orchestrator or human needs to open directly. `--artifact` takes only a path to a file in the session artifact directory; mention issues, links, and other URLs in the note. `--artifact` does not make a file appear as a session artifact: run [`ao artifact add`](artifact.md) for that, before you report it. In a chat session, an HTML file from the artifact directory that you attach with `--artifact` also shows in the thread.

Routine test logs, command output, scratch notes, and intermediate diagnostics are working material, not deliverables. Do not attach them unless requested or needed to explain an actionable failure. Summarize validation in the report note; when a separate deliverable is useful, prefer one consolidated report over individual logs. Ordinary progress updates and concise final answers do not need separate artifact files.

Saving a local artifact or attaching its reference to an Orchestrator report is not external publishing authorization. Publish externally only within the user-authorized scope.

`--pr-created` and `--pr-reviewed` accept complete GitHub PR or GitLab MR URLs.

`--needs-input` requests immediate non-interrupting delivery. `--stuck` requests immediate delivery plus a rate-limited interrupt. Informational work batches for up to one hour, while the first done report opens a fixed five minute settlement window.

**Examples:**

ao report "The focused tests pass; I am checking the generated diff."
ao report --done --note "Ready for review." \
  --pr-created https://github.com/owner/repo/pull/88