design-kanban-md-output

Preserve and evolve kanban-md table, compact, and JSON output contracts. Use when changing output defaults, format-selection flags or environment variables, renderers, fields, grouping, errors, or tok

SKILL.md

GitHub

Design kanban-md output

CLI output serves humans, agents, and scripts. Treat the default, format selection, field names, record boundaries, and error shapes as user-facing contracts rather than incidental presentation.

Format roles

  • table is the default in both TTY and non-TTY environments. It is padded, readable output for interactive use.
  • compact is selected with --compact, --oneline, or KANBAN_OUTPUT=compact. It uses one record per line, avoids repeated JSON keys, and is optimized for agent context.
  • json is selected with --json or KANBAN_OUTPUT=json. It is the complete structured form for parsing, pipes, and integrations.

TTY auto-detection was intentionally removed because agents commonly execute in non-TTY environments and previously received verbose JSON by default. Do not restore implicit TTY-dependent selection without new evidence and an explicit compatibility decision.

Contract rules

  • Preserve explicit format flags and environment-variable behavior. Conflicting selectors must fail or resolve through the documented precedence, never silently vary with terminal state.
  • Keep compact output one-line-per-record and sufficiently self-describing for agents. Avoid repeated labels or decorative padding that materially increases token use.
  • Keep JSON complete and machine-oriented. Field removals, renames, type changes, and error-shape changes require compatibility analysis; additive fields still require documentation and tests.
  • Keep table output readable and stable enough for humans, while avoiding tests that prevent harmless spacing improvements unless alignment itself is the contract.
  • Do not publish precise token-savings claims without a current, reproducible measurement against the formats being compared.
  • Update README.md, command help, examples, and embedded skill references when output behavior changes.

Implementation and verification

Centralize semantic data before rendering so table, compact, and JSON surfaces do not drift. Test renderer behavior in internal/output/ and complete command selection in e2e/.

At minimum, cover:

  • the default format in non-TTY execution;
  • each explicit flag and supported KANBAN_OUTPUT value;
  • record contents and ordering for the changed command;
  • JSON fields/types and structured errors when affected;
  • compact one-record-per-line behavior;
  • --no-color or NO_COLOR when styling changes.

Follow test-kanban-md for the broader verification ladder. For the product and token-cost rationale, read docs/research/2026-08-25-kanban-md-design-principles-orientation.md.