Add CLI UX design conventions to AGENTS.md Key Conventions section

What happened

On PR #156, human reviewer kadel caught 6 UX design issues and 3 architecture issues that the review agent ($8.30, opus/high) missed entirely. The agent's 14 findings were all code-level (null handling, edge cases, shell escaping, DRY). The human's design findings included: (1) inconsistent entity reference formats across commands — catalog get used --name/--kind/--namespace, docs get used --entity-ref, template used --template-ref; (2) JSON strings as CLI arguments is hostile UX (--filters '{"kind":"Component"}' vs --filter kind=Component); (3) docs get returned exit code 0 for non-existing entities; (4) docs search failed with a misleading 400 error when the required plugin was not configured instead of detecting the missing plugin; (5) --help output hid backstage-cli's available flags; (6) --rhdh-url was redundant with existing --backend-url. The current AGENTS.md Key Conventions section covers code organization (format.ts, client.ts, intent-errors.ts separation) and test co-location, but contains no CLI UX design principles.

What could go better

The review agent had no guidance on what constitutes good CLI design for this project. It could verify code correctness (does for...of work on this value?) but not design correctness (should this command use --entity-ref or a positional argument?). The human reviewer applied implicit design standards — consistent flag naming, key=value over JSON, graceful degradation when plugins are missing, non-zero exit codes for errors — that are nowhere in the repo's agent-facing documentation. If AGENTS.md encoded these conventions, the agent could check new commands against them. Confidence: high that adding these conventions would have caught the entity reference inconsistency and exit code issues (these are pattern-matchable). Moderate confidence for JSON-vs-key=value (requires UX judgment) and plugin detection (requires architectural reasoning). Low confidence for --help completeness (requires understanding Commander.js passthrough behavior).

Proposed change

Add a ## CLI UX Design Conventions section to AGENTS.md (or expand ## Key Conventions) encoding the design principles established through PR #156's review:

1. Entity references: All commands that target a single entity must accept a positional argument in [kind:][namespace/]name format. Do not use inconsistent --entity-ref, --template-ref, --name/--kind/--namespace flags across command groups.
2. Filter and input flags: Use repeatable --flag key=value syntax (parsed by kv.ts) instead of JSON string arguments. Example: --filter kind=Component --filter type=service, not --filters '{"kind":"Component"}'.
3. Plugin dependencies: Commands that depend on optional Backstage plugins (techdocs-mcp-extras, search-backend-module-techdocs) must detect when the plugin is not configured and exit with a clear error message suggesting how to enable it. Do not surface raw HTTP 400/500 responses.
4. Exit codes: Commands must exit with a non-zero code when the requested entity is not found or the operation fails. Informational "not found" messages must not exit 0.
5. Error presentation: Use intent-errors.ts to extract human-readable reasons from Backstage error responses. Do not expose raw JSON schema validation output or full stack traces to the user.
6. Help text: Passthrough commands must surface the underlying tool's flags in --help output, not just the wrapper's flags.

Validation criteria

On the next PR that adds or modifies an intent-based CLI command group in this repo, the review agent should check the new command's flags and error handling against these documented conventions. Specifically: (a) the agent should flag any command that introduces a new entity-reference flag format inconsistent with the positional [kind:][namespace/]name pattern, and (b) the agent should flag any command that exits 0 on a not-found condition. Validate against the next 3 review agent runs on PRs touching src/commands/intent-based-actions/.

Generated by retro agent from https://github.com/redhat-developer/rhdh-cli/pull/156

Start with AGENTS.md and review PR #156, then inspect the existing conventions around intent-based commands and the src/commands/intent-based-actions/ path. Add a CLI UX conventions section covering the six proposed areas; it is done when the documented rules and validation criteria are clear enough for future review-agent runs.