Scribe Agent Contract

Scribe is an agent-first CLI for managing local AI coding agent skills. Prefer JSON mode for automation and inspect command schemas when composing calls.

JSON Envelope

Migrated commands emit a versioned envelope on stdout:

{
  "status": "ok",
  "format_version": "1",
  "data": {},
  "meta": {
    "duration_ms": 12,
    "bootstrap_ms": 3,
    "command": "scribe list",
    "scribe_version": "dev"
  }
}

Errors use the same envelope shape on stderr. Payload keys that were previously top-level now live under data.

Exit Codes

Prompting Tips

Use scribe schema <command> --json before calling an unfamiliar command. Use --fields only on commands whose schema lists the flag. When updating scripts from pre-envelope output, change jq '.foo' to jq '.data.foo'.

Examples:

scribe list --json --fields name,status
scribe schema sync --json
scribe sync --json | jq '.data.summary'
scribe adopt --dry-run --json | jq '.data.conflicts'

Commands

Spec Deviations

• Use --fields name,version as a separate flag, not overloaded --json name,version; this preserves boolean --json=true compatibility.
• meta.duration_ms measures leaf RunE execution. meta.bootstrap_ms covers first-run, store migration, builtins apply, and embedded-agent refresh work before the leaf command runs.
• Some wave-3 commands still reject --json with JSON_NOT_SUPPORTED; inspect scribe schema --all --json for migrated commands.