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:
- 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.
- 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"}'.
- 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.
- 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.
- 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.
- 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 #156
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 getused--name/--kind/--namespace,docs getused--entity-ref,templateused--template-ref; (2) JSON strings as CLI arguments is hostile UX (--filters '{"kind":"Component"}'vs--filter kind=Component); (3)docs getreturned exit code 0 for non-existing entities; (4)docs searchfailed with a misleading 400 error when the required plugin was not configured instead of detecting the missing plugin; (5)--helpoutput hid backstage-cli's available flags; (6)--rhdh-urlwas 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...ofwork on this value?) but not design correctness (should this command use--entity-refor 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 Conventionssection toAGENTS.md(or expand## Key Conventions) encoding the design principles established through PR #156's review:[kind:][namespace/]nameformat. Do not use inconsistent--entity-ref,--template-ref,--name/--kind/--namespaceflags across command groups.--flag key=valuesyntax (parsed bykv.ts) instead of JSON string arguments. Example:--filter kind=Component --filter type=service, not--filters '{"kind":"Component"}'.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.intent-errors.tsto extract human-readable reasons from Backstage error responses. Do not expose raw JSON schema validation output or full stack traces to the user.--helpoutput, 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/]namepattern, 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 touchingsrc/commands/intent-based-actions/.Generated by retro agent from #156