Skip to content

feat(cli): structured output and agent-friendly error messages for fleet CLI #100

@khang859

Description

@khang859

Overview

As Fleet adds more autonomous agent roles (Navigator, First Officer, etc.), the fleet CLI needs richer, more structured output across all commands — not just the Navigator-specific paths. This is a standalone improvement to make the CLI more reliable for smaller models (Haiku) and easier to build on top of.

Goals

  • Consistent structured JSON output mode across all command groups
  • Actionable error messages with hints and corrective suggestions (not just failure strings)
  • Input validation with clear pre-flight errors before executing irreversible commands
  • Next-step hints in successful command responses to guide agents toward correct follow-up actions

Scope

All existing command groups:

  • fleet crew *
  • fleet missions *
  • fleet comms *
  • fleet sectors *
  • fleet cargo *

Out of Scope

Navigator-specific CLI output (structured output for FLEET_NAVIGATOR=1 env var, execution-scoped commands, protocol step guards) is handled as part of the Protocols & Navigator feature.

Notes

  • Smaller models like Haiku won't recover gracefully from vague errors — the CLI needs to do more of the thinking
  • Pattern: { "ok": true, "data": {...}, "hint": "suggested next command" } and { "ok": false, "error": "...", "hint": "corrective action" }
  • Irreversible commands (crew recall, crew deploy) should validate all inputs upfront before executing

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions