⏺ HZL CLI Agent-Readiness Review

  Overall verdict: Strong. The reviewer called HZL "Very strong, with a few improvements to make it great" with no blockers found.

  Scorecard

  ┌───────────────────────┬──────────────┬─────────────────────────────────────────────────────────────────────────────────┐
  │       Principle       │   Severity   │                                     Finding                                     │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Non-interactive paths │ None         │ Only init --force has a prompt, properly guarded with --yes + TTY detection     │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Structured output     │ Friction     │ Success responses are bare JSON; errors use {ok, error} envelope — inconsistent │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Help discovery        │ Optimization │ Group-level examples are good; leaf commands lack inline examples               │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Actionable errors     │ None         │ Fuzzy correction, decision traces, status-aware suggestions — "best I've seen"  │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Safe retries          │ Optimization │ Workflow has --op-id; task add lacks idempotency key                            │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Composable structure  │ Optimization │ No stdin pipe support for bulk ops                                              │
  ├───────────────────────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────┤
  │ Bounded responses     │ Optimization │ Good defaults; stuck lacks --limit                                              │
  └───────────────────────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────┘

  Top 4 Recommended Improvements

  1. Wrap success JSON in the envelope — createSuccessEnvelope already exists in output.ts but ~50 command handlers bypass it with bare
  console.log(JSON.stringify(result)). Wrapping gives agents a uniform {ok, data} / {ok, error} contract.
  2. Add --op-id to task add — The pattern exists in WorkflowService. Extending it prevents duplicate tasks from agent retries.
  3. Add inline examples to leaf command help — claim, list, add, complete, update, workflow run start would benefit from .addHelpText('after', ...) examples.
  4. Add --quiet mode for mutations — Emit only the entity ID so agents can compose without JSON parsing: TASK_ID=$(hzl task add "Fix" --quiet).

  Standout Strengths

  - Fuzzy input normalization — edit distance, prefix matching, --assignee → --agent aliasing, task next → task claim --next rewriting
  - Decision traces on claim --next — full algorithm transparency with eligibility, outcome reason, and alternatives
  - JSON-default output — --format json is the default (inverse of most CLIs, correct for agent-first)
  - --view summary|standard|full — three verbosity tiers for token control
  - Anti-herd claim stagger — SHA-256 deterministic delay spreading
  - Atomic BEGIN IMMEDIATE transactions for claiming
  - CLI manifest + doc parity CI checks preventing stale documentation