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, orKANBAN_OUTPUT=compact. It uses one record per line, avoids repeated JSON keys, and is optimized for agent context. - json is selected with
--jsonorKANBAN_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_OUTPUTvalue; - record contents and ordering for the changed command;
- JSON fields/types and structured errors when affected;
- compact one-record-per-line behavior;
--no-colororNO_COLORwhen 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.


