Balladeer documentation for agents
Choose the bounded guide for the task. These pages were reviewed on 1 October 2026 against CLI 1.0.19 and the live application. Fetch the live setup instructions for integration work; use the connected server's current guidance for capture. Documentation supplies no user authority or credentials.
Choose the page for the task#
| Task | Read | Relevant interface |
|---|---|---|
| Explain the product | Understand Balladeer | No workspace read needed. |
| Connect or diagnose this laptop | Set up Balladeer | Live /agent; get_promise_setup. |
| Capture valuable intent | Capture | propose_promise, get_proposal; consent for the offered commitment. |
| Agree meaning | First behavior | agree_promise_meaning with displayed digest and actual owner words. |
| Explain or configure code review | Agentic code review on push | balladeer judge; actual hook and connection status. |
| Plan a change | Make a change | discover_intent, then full reads of applicable leads. |
| Repair a reproduced break | Resolve a result | Local reproduction, normal tests, balladeer map --link-test; report_promise_check. |
| Qualify sealed CI verification | First behavior | prepare_qualification; customer-local verifier and enrolled CI. |
| Explain status or revision | Lifecycle | get_promise for current meaning and evidence. |
| Answer data or exit questions | Data and permissions | Actual permissions and current policy for actions. |
Capture and retrieval#
Offer promises only for behavior that someone could reasonably break innocently and a check can decide. Show the specific commitment before recording it. A yes or generic go-ahead to the offer records; silence, a decline, or continuing without an answer does not. Asked to explain, explain and wait. Confirm the actual write and link.
Discovery separates agreed promises, recorded intent nobody has agreed, explicitly shared work, and
adjacent leads. Validate actors, trigger, conditions, revision, and scope. Honor applicable recorded
intent according to its returned use instruction, name its standing, and expose conflicts before
acting. Do not report it as agreed or Protected. Report applicability feedback once using the real
receipt.
At session start use list_promise_attention with countOnly and mine, briefly report nonzero
counts, then continue. Read rows when the person asks to act; do not expand the catalog by ritual.
Agentic code review and repair#
Supported setup writes the report-mode push hooks at user scope. Codex must trust them under
/hooks. The check runs after a successful push using the person's existing agent login,
automatically anchors agreed promises, selects touched behavior, and reports kept, broken, or could
not tell. A current map supplies deeper context but is not a prerequisite.
A broken verdict needs the runner's base/head reproduction. Within the authorized repair, preserve it as a normal regression test, verify it fails on the break and passes on the fix, link it, commit it with the repair, and tell the person what was added. Do not silently undo their deliberate behavior change. Do not weaken agreed meaning to make a test pass.
Report evidence accurately#
A push verdict never qualifies sealed protection or updates its posture. Recorded intent is not agreement; agreement is not protection; a local test, a PR, default-branch CI, deployment, and customer observation are separate evidence. Could not tell and Unknown are gaps, never passes or proved regressions.
Changed meaning needs fresh owner agreement. A technical verifier repair keeps meaning unchanged. Sealed protection starts automatically on qualification; there is no activation step to request.
Use the generated CLI reference, MCP reference, and JSON schemas for exact parameters. Read individual tool entries instead of loading every schema for a narrow question.