Generate Command Schemas for AI Agents from the Real Commands and Flags

## Change the Registry and Generators, Not Generated Files Treat repository guidance as a contract for the files in its scope. Preserve unrelated work, apply the language formatter to every modified source file, and change only the smallest owning input needed for the requested behavior. Identify authoritative inputs before editing. A reviewed command registry should own stable command identity, primary paths, aliases, and navigation. The executable command tree should own whether a path exists, is runnable, and which flags it accepts. Generated catalogs and agent metadata are outputs, not editing surfaces; change their source inputs and generators, then regenerate them. Run the repository-defined build, full tests, generation, drift checks, policy checks, and focused command tests that cover the change. Review the generated difference and reject unrelated rewrites. ## Build Schemas in One Direction and Bind Each Command Once Keep schema resolution directional: 1. Build the real executable command tree and flags. 2. Combine the reviewed identity registry with reviewed metadata overlays before binding. 3. Resolve parameter types, mappings, required states, defaults, and cross-parameter constraints. 4. Resolve agent selection, safety, interface, and runtime-gate semantics by declared source precedence. 5. Bind each command exactly once into one typed tool specification and index. 6. Publish catalogs, full exports, summaries, and generated metadata only from that typed source. After binding, do not reopen annotations, source records, previous catalogs, or generated JSON to repair or re-resolve identity. A production loader that decodes an embedded snapshot is a delivery boundary, not a second source-resolution stage. It must never create or repair commands, flags, registry entries, or later generation inputs. Preserve the published wire contract unless a versioned change is explicitly authorized. Architectural alignment with another system does not justify an unversioned format change. ## Check Both Ways That Every Command and Schema Match The binder must reject a missing or non-runnable command path, alias collisions, and native identity assertions that disagree with the effective registry. A missing native identity assertion may be allowed when annotations are consistency checks rather than fallback identity sources. Enforce coverage in both directions: 1. Every delivered schema tool, including its catalog projection, must resolve to an executable command. 2. Every public runnable command leaf must resolve to schema or appear as an exact reviewed exclusion with a non-empty reason. Never use prefix or wildcard exclusions because they can hide future commands. Stale, invalid, or duplicate exclusions must fail generation, and an exclusion must be retired when its command enters schema. Treat the reviewed registry as the sole source of stable identity and navigation, while treating the executable tree as the source of path, runnability, and flag truth. Run reverse-completeness tests whenever the command tree changes. ## Keep Safety Metadata and Agent Selection Text Separate Keep human-authored inputs split by ownership. Metadata owns effects, risk, confirmation, idempotency, interfaces, runtime gates, and optional parameter overlays. Selection owns agent summaries, positive and negative routing guidance, examples, and product routing. An index should only map product identifiers to those files. Do not mix fields across these blocks. Every authored entry must be explicitly reviewed, include a concrete review reason and evidence references, and be the smallest entry that expresses the user-visible behavior. Selection prose should explain trigger intent, sibling-command routing, and expected outcomes rather than restating a command summary. Resolve evidence by declared precedence: executable runtime facts first, then live interface schema, pinned interface metadata, and skill documentation as evidence only. When live discovery uses personal credentials, never print or commit tokens. If live discovery fails, record that failure, use the approved fallback evidence, and do not invent an interface or remote procedure. Parameter overlays must target an exact public runnable leaf and real flags. They may refine descriptions, interface mappings, required states, and conditional requirements, but they must not create commands or flags, define an interface, or advertise an unknown remote procedure. ## Rebuild All Outputs from Scratch and Check They Match Treat generation as a full deterministic snapshot rebuild, not an incremental patch over a previous catalog. Re-read every reviewed input, retire stale generated product metadata, and rewrite the exact output projections. Generated files must never become merge inputs, and byte guards should fail if generation changes authored inputs or the reviewed registry. Use the same resolved typed tool specification for every projection. A leaf payload must equal its corresponding entry in the full export and catalog, while overview and group summaries must equal the summary projection of that same tool. An alias lookup may change only alias-specific view fields; it must not re-resolve or mutate the command contract. For every delivered tool and parameter field, the selected provenance value must exactly equal the delivered value. Checking only the source name, candidate count, field presence, or hash is insufficient. Run generation, runtime-confirmation truth checks, reverse-completeness tests, focused command tests, and final embedded-loader checks. Review all resulting differences before accepting the snapshot. ## Check Examples and Dry Runs Without Skips or --yes Store no more than two reviewed examples per tool. Examples must use a real primary or alias path, accepted flags, required positionals, and all effective require-one-of, require-together, and mutual-exclusion constraints. Do not include shell comments or confirmation-bypass flags such as `--yes`. Every example must pass contract validation against its bound command. A missing required value, constraint failure, runtime error, or interface-resolution error is a contract defect, not a reason to skip the example. Runtime example execution is opt-in and permitted only when the final typed tool publishes an explicit reviewed dry-run capability. Risk and confirmation metadata must not manufacture preview support. A reviewed manual disposition may narrow an existing dry-run capability for one exact zero-based example index, but it must use an approved reason code, provide a concrete reason, and never turn ordinary contract validation into a skip. Never catch a dry-run failure and downgrade it dynamically to contract-only validation. Run exhaustive contract gates by default; execute only the eligible dry-run subset through the real command with isolated user state and blocked proxies. Treat changes to stable execution counts as reviewable contract changes. ## Test Which Command the AI Picks Without Sending It the Answers Treat every positive selection scenario as an assertion that its reviewed command should be chosen, and every negative scenario as an assertion that the command must not be chosen. Derive deterministic typed fixtures from the authored selection fields, require exact tool coverage and runnable primary commands, and reject missing, duplicate, or contradictory expectations. String matching alone does not prove semantic understanding. Keep live-model selection checks explicitly opt-in. Support a small smoke set, a full reviewed set, and an exact case list. Send only case identifiers, scenario text, and a same-product candidate table to the evaluator; keep expected and forbidden assertions local. Allowlist built-in HTTPS evaluator endpoints. Any other HTTPS provider requires its exact base URL in the approved allowlist, and plaintext HTTP is acceptable only for a loopback test server. Never send API credentials to an arbitrary cleartext endpoint. Normal continuous integration must remain deterministic and must not call a model. Its blocking gates are reproducible fixtures, command binding, example validity, provenance, and final-delivery equality. ## Set Safety and Confirmation by Source Priority Resolve safety and parameter metadata by source precedence, not by choosing whichever value appears stricter. A higher-priority reviewed source may intentionally raise or lower effect, risk, confirmation, idempotency, descriptions, or mappings. Preserve all candidates and the selected source, and fail same-precedence conflicts instead of silently merging them. Required command flags are a hard floor: an overlay may make an optional flag required, but it must never weaken a requirement declared by the executable command. For command text, prefer reviewed command-specific hints, then command help, then interface metadata; generic remote-procedure prose must not overwrite a specialized command description. Do not infer one safety field from another. A destructive effect or high risk does not mechanically rewrite confirmation. Confirmation must match the explicit runtime gate, and user-required confirmation must be obtained before adding a bypass flag such as `--yes`. If shipped command help and leaf schema disagree, pass only flags accepted by the executable command. If safety sources conflict, use the safer interpretation or stop and report the contract drift. Verify confirmation semantics through the final embedded loader and query path, not only in a generator unit test. ## Explore Commands Step by Step, Then Run Real Commands for Data Keep ordinary discovery progressive: overview, then product or group, then leaf. Reserve the full export as the stable compatibility contract, and include complete parameters, constraints, and safety semantics for every final tool, including an empty parameter object for commands without flags. A compact full export is not a complete compatibility baseline. Command help determines whether a path exists and which flags the executable accepts. Leaf schema determines agent selection, parameter mapping and constraints, and safety and confirmation semantics. Any disagreement is contract drift, not permission to guess. Schemas and help describe commands; they do not return business data. After discovery, execute the appropriate real read, search, or list command within its confirmed permissions to obtain data. Before delivery, confirm that command identity is reviewed, executable coverage is bidirectional, exclusions are exact, authored blocks retain separate ownership, source precedence is preserved, generated outputs remain output-only, examples pass their real contracts, confirmation matches runtime gates, and every projection equals the same typed source.