How agents drive bacio

bacio's CLI was rebuilt around six rules so an LLM can drive it reliably. These are the contract you can assume when you ask Claude or Codex to file an issue, plan a feature, or sweep the backlog.

The six rules

1. Mutations accept JSON via --json. Every mutating command takes --json <inline>, --json - (stdin), or --json @path/to.json. Strict decode — unknown fields are rejected.
2. Schemas published at runtime. bacio schema list / show <name> / all returns JSON Schema (draft 2020-12) reflected from the same input structs the decoder uses. No manual sync.
3. Lists are lean by default. *.list strips heavy bodies (descriptions, doc content). Use *.show or bacio issue brief for full records. Heavy bodies belong on per-row lookups.
4. Validators at the store boundary. Length caps, UTF-8 checks, C0-control rejection — all enforced in internal/store/, not in the CLI handler. CLI, TUI, and REST API all get the same checks.
5. Every mutation has --dry-run. Validates and projects the result, emits to stdout, writes nothing, no audit row. Same shape as a real call so the same parser works.
6. SKILL.md is the agent-facing reference. The single source of truth for agents — embedded in the binary, redistributed by bacio install-skill.

The agent flow

The five-step pattern agents use, bracketed by a declare yourself / tear down pair:

0. Declare yourself — bacio agent register --user <name> --agent <slug> (with --new on first session, then persisting the slug to .bacio/agent). bacio agent claim <KEY> when you start focused work on an issue.
1. Discover — bacio schema show issue.add if the agent is unsure.
2. Compose — build the JSON payload.
3. Rehearse — --dry-run to validate without writing.
4. Execute — run for real with --user <agent-name> for clean audit attribution.
5. Query lean — *.list with filters, not bulk reads.
6. Tear down — bacio agent release <KEY> when you stop, then bacio agent end --reason stop (which auto-releases any remaining claims).

The registry is local-only and never replicated via bacio sync — it's runtime flow data, not durable project state. The full surface is on the bacio agent reference.

What bacio deliberately doesn't do

• No NDJSON / streaming output. One object responses are big enough.
• No --field projection mask. Three opt-in flags cover the actual hot spots.
• No silent normalisation. Whitespace in a filename is an error, not a TrimSpace.
• No autogenerated schema examples. Reflection can't invent useful examples; hand-curated wins.

The longer rationale lives in the upstream docs/agent-cli-principles.md.