From ec6987a0140f4ec8e295f34dfd0f7d8cd9ff6c3a Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 06:17:57 +0000 Subject: [PATCH] docs(spec): clarify agents validation attach synopsis to use --key value named option format Closes #5328 The spec synopsis showed [...] which was ambiguous. The implementation (PR #3837) enforces --key value named option format and explicitly rejects positional key=value tokens. This commit aligns the synopsis, argument description, and all inline references throughout the spec to match the implementation and the existing examples which already showed --coverage-threshold 90. Changes: - Command synopsis (line ~270): [...] -> [-- ]... - agents validation attach section synopsis: same fix - Argument description: clarify named option format, hyphen-to-underscore conversion - Inline references at lines 9271-9273: updated all three attachment scope examples - Attachment model section (lines 22536, 22546, 22556): updated all three entries - Management table (line 22986): updated synopsis and added note about named options --- docs/specification.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index dbe7bd381..2983916dc 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -268,7 +268,7 @@ The following standards are integrated into the architecture: agents validation add --config|-c <FILE> [--update] agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] - <RESOURCE> <VALIDATION> [<ARGS>...] + <RESOURCE> <VALIDATION> [--<KEY> <VALUE>]... agents validation detach [--yes|-y] <ATTACHMENT_ID> agents actor run [(--output|-o) <OUTPUT_FILE>] @@ -9268,9 +9268,9 @@ Because Validations are a subtype of Tool and share the same Tool Registry and n - **Remove a validation**: `agents tool remove ` (automatically removes all attachments) A validation is always attached to a resource. The optional `--project` or `--plan` flag controls the scope of the attachment: -- **Direct attachment** (no scope flag): The validation is always active for that resource, regardless of which plan or project accesses it. Use `agents validation attach [args...]`. -- **Project-scoped attachment** (`--project`): The validation only runs for that resource when it is being interacted with through the specified project. Use `agents validation attach --project [args...]`. -- **Plan-scoped attachment** (`--plan`): The validation only runs for that resource when it is being interacted with through the specified plan. Use `agents validation attach --plan [args...]`. +- **Direct attachment** (no scope flag): The validation is always active for that resource, regardless of which plan or project accesses it. Use `agents validation attach [-- ]...`. +- **Project-scoped attachment** (`--project`): The validation only runs for that resource when it is being interacted with through the specified project. Use `agents validation attach --project [-- ]...`. +- **Plan-scoped attachment** (`--plan`): The validation only runs for that resource when it is being interacted with through the specified plan. Use `agents validation attach --plan [-- ]...`. The same validation can be attached to the same resource multiple times — directly, through different projects, and through different plans — and since validations accept arguments, attaching the same validation to the same resource multiple times with different arguments is a common and useful configuration pattern (e.g., running the same test suite with different coverage thresholds for different projects). @@ -9537,7 +9537,7 @@ Register a new validation. The validation is fully defined by the YAML configura ##### agents validation attach 
agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
-                         <RESOURCE> <VALIDATION> [<ARGS>...]
+ <RESOURCE> <VALIDATION> [--<KEY> <VALUE>]... **Purpose** Attach a registered validation to a resource, with an optional project or plan scope. A resource is always required — validations are fundamentally resource-centric. The optional `--project` or `--plan` flag narrows when the validation is active: without either flag, the validation runs whenever any plan or project accesses the resource; with `--project`, it only runs when the resource is accessed through that project; with `--plan`, it only runs when the resource is accessed through that plan. At most one scope flag may be provided per invocation. @@ -9550,7 +9550,7 @@ The command returns a system-assigned **attachment ULID** that uniquely identifi - ``: Validation name (positional argument, required). - `--project PROJECT`: Scope the attachment to a specific project. The validation only runs for this resource when it is accessed through the specified project. - `--plan PLAN_ID`: Scope the attachment to a specific plan. The validation only runs for this resource when it is accessed through the specified plan. -- `...`: Optional validation-specific arguments (passed through to the validation tool's `input_schema` at execution time). +- `[-- ]...`: Optional validation-specific named arguments. Each argument is specified as a named option (e.g., `--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. **Examples** @@ -22534,7 +22534,7 @@ Validations are not globally active — they must be explicitly **attached** to A validation is always attached to a resource. The optional `--project` or `--plan` flag controls the scope under which the validation is active for that resource: -1. **Direct attachment** (`agents validation attach [args...]`) +1. **Direct attachment** (`agents validation attach [-- ]...`) The validation is always active when that resource is accessed by any plan, regardless of which project or plan is involved. This scope is for invariants that must hold for a resource in all contexts — e.g., a lint check that must pass for a repository no matter what project is using it. @@ -22544,7 +22544,7 @@ A validation is always attached to a resource. The optional `--project` or `--pl - Security scanning on any codebase resource - License compliance checks -2. **Project-scoped attachment** (`agents validation attach --project [args...]`) +2. **Project-scoped attachment** (`agents validation attach --project [-- ]...`) The validation is active only for that resource when it is being interacted with through the specified project. Different projects using the same resource can have different validation requirements. This is the most common attachment scope. @@ -22554,7 +22554,7 @@ A validation is always attached to a resource. The optional `--project` or `--pl - API compatibility checks for a microservice project - Bundle size checks for a frontend project -3. **Plan-scoped attachment** (`agents validation attach --plan [args...]`) +3. **Plan-scoped attachment** (`agents validation attach --plan [-- ]...`) The validation is active only for that resource when it is being interacted with through the specified plan. This is the most targeted scope, useful for one-off or experimental validations. @@ -22984,7 +22984,7 @@ Validations are **registered** via `agents validation add` and **attached** via |-----------|---------|-------| | **Register** | `agents validation add --config ` | Validation-specific. Config file defines all properties including mode (`required`/`informational`). | | **Update** | `agents validation add --config --update` | Uses the `--update` flag to overwrite existing registration. | -| **Attach** | `agents validation attach [--project\|--plan] [args...]` | Returns an attachment ULID. Resource is always required; project/plan scope is optional. | +| **Attach** | `agents validation attach [--project\|--plan] [-- ]...` | Returns an attachment ULID. Resource is always required; project/plan scope is optional. Named options pass validation-specific arguments. | | **Detach** | `agents validation detach [--yes] ` | Uses the attachment ULID, not the validation name. | | **List** | `agents tool list --type validation` | Shared with tools. Use `--type validation` to filter. | | **Show** | `agents tool show ` | Shows validation-specific fields when the entry is a Validation. |