Proposal: update specification — clarify agents validation attach synopsis to use --key value named option format #5328

New issue

Open

opened 2026-04-09 05:51:44 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 05:51:44 +00:00

Owner

Specification Update Proposal

Triggered by: Merged PR #3837 (fix(cli): change agents validation attach extra args to use --key value named option format)
Classification: Implementation is BETTER than spec — update spec synopsis to match implementation and existing examples

What Changed in the Implementation

PR #3837 changed the agents validation attach command to use --key value named option format for extra arguments instead of the previously implemented positional key=value format. The implementation now:

Accepts arbitrary named options via Typer Context mechanism
Converts --coverage-threshold 90 style tokens into {"coverage_threshold": "90"} dict
Explicitly rejects positional key=value tokens with a descriptive error message

What Spec Sections Need Updating

Section: Command Synopsis (line ~270)

Current spec:

agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
                         <RESOURCE> <VALIDATION> [<ARGS>...]

Proposed update:

agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
                         <RESOURCE> <VALIDATION> [--<KEY> <VALUE>]...

Section: `##### agents validation attach` (line ~9537)

Current spec (line 9539-9540):

agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
                         <RESOURCE> <VALIDATION> [<ARGS>...]

Proposed update: Change [<ARGS>...] to [--<KEY> <VALUE>]... to clearly indicate the named option format.

Current spec (line 9553):

- `<ARGS>...`: Optional validation-specific arguments (passed through to the validation tool's input_schema at execution time).

Proposed update:

- `[--<KEY> <VALUE>]...`: Optional validation-specific named arguments. Each argument is specified as a named option: `--coverage-threshold 90`. Hyphens in option names are converted to underscores in the argument dict (e.g., `--coverage-threshold` becomes `coverage_threshold`). Positional `key=value` format is not accepted.

Rationale

The spec synopsis [<ARGS>...] is ambiguous. The spec examples already correctly show --coverage-threshold 90 (named option format), but the synopsis and argument description are inconsistent with the examples. The implementation now enforces the --key value format and explicitly rejects the old positional format. Updating the synopsis and description removes this ambiguity.

Scope

Sections affected: Command synopsis (~line 270), ##### agents validation attach (~line 9537), validation attachment descriptions (~lines 9271-9273)
Change type: Clarify synopsis and argument description to match existing examples and implementation
Risk: Low — documentation clarification only, no behavioral change

Automated by CleverAgents Bot
Supervisor: Specification Updates | Agent: spec-updater

## Specification Update Proposal **Triggered by**: Merged PR #3837 (fix(cli): change `agents validation attach` extra args to use `--key value` named option format) **Classification**: Implementation is BETTER than spec — update spec synopsis to match implementation and existing examples ## What Changed in the Implementation PR #3837 changed the `agents validation attach` command to use `--key value` named option format for extra arguments instead of the previously implemented positional `key=value` format. The implementation now: - Accepts arbitrary named options via Typer Context mechanism - Converts `--coverage-threshold 90` style tokens into `{"coverage_threshold": "90"}` dict - Explicitly rejects positional `key=value` tokens with a descriptive error message ## What Spec Sections Need Updating ### Section: Command Synopsis (line ~270) **Current spec**: ``` agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...] ``` **Proposed update**: ``` agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [--<KEY> <VALUE>]... ``` ### Section: `##### agents validation attach` (line ~9537) **Current spec** (line 9539-9540): ``` agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...] ``` **Proposed update**: Change `[<ARGS>...]` to `[--<KEY> <VALUE>]...` to clearly indicate the named option format. **Current spec** (line 9553): ``` - `<ARGS>...`: Optional validation-specific arguments (passed through to the validation tool's input_schema at execution time). ``` **Proposed update**: ``` - `[--<KEY> <VALUE>]...`: Optional validation-specific named arguments. Each argument is specified as a named option: `--coverage-threshold 90`. Hyphens in option names are converted to underscores in the argument dict (e.g., `--coverage-threshold` becomes `coverage_threshold`). Positional `key=value` format is not accepted. ``` ## Rationale The spec synopsis `[<ARGS>...]` is ambiguous. The spec examples already correctly show `--coverage-threshold 90` (named option format), but the synopsis and argument description are inconsistent with the examples. The implementation now enforces the `--key value` format and explicitly rejects the old positional format. Updating the synopsis and description removes this ambiguity. ## Scope - **Sections affected**: Command synopsis (~line 270), `##### agents validation attach` (~line 9537), validation attachment descriptions (~lines 9271-9273) - **Change type**: Clarify synopsis and argument description to match existing examples and implementation - **Risk**: Low — documentation clarification only, no behavioral change --- **Automated by CleverAgents Bot** Supervisor: Specification Updates | Agent: spec-updater

Rows
Columns