Skip to content

Document and version the --json output schema #23

Description

@wkentaro

What to build

Give --json a documented, versioned contract so downstream agents and tools
can depend on it. Real usage shows agents guessing at the shape (a flat list of
hunk objects vs. a nested by-file/by-status structure) and silently failing when
they guess wrong. Pin the schema down:

  • Add a schema_version to the JSON envelope.
  • Document the exact shape (fields, types, status values) in the README.
  • Optionally expose the JSON Schema (e.g. a --json-schema flag) so consumers
    can validate.

Acceptance criteria

  • list --json output carries an explicit schema_version.
  • The JSON shape is documented in the README with field descriptions.
  • The contract is covered by a test that would fail if the shape changes
    unintentionally.

Blocked by

None - can start immediately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentissue: Fully specified, ready for an AFK agenttype: featureissue: Requesting a new capability or improvement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions