# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json cli_contracts: 0.1.0 info: title: agent-contracts CLI version: 0.32.4 description: >- Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions. license: name: MIT contact: name: foo-log-inc url: https://github.com/foo-log-inc/agent-contracts artifact_slots: dsl-definitions: description: Agent contracts DSL YAML files (agent-contracts.yaml and extends targets) direction: read config: description: agent-contracts.config.yaml configuration file direction: read generated-templates: description: Rendered output files from Handlebars templates direction: write generated-guardrails: description: Generated guardrail binding files (cursor-rules, AGENTS.md, etc.) direction: write generated-interface: description: Generated team interface YAML/JSON files direction: write audit-report: description: LLM audit result output files direction: write command_sets: agent-contracts: summary: Agent contracts tooling — validate, lint, render DSL files. executable: agent-contracts global_options: - name: version aliases: [V] description: Print version and exit. schema: type: boolean - name: help aliases: [h] description: Show help and exit. schema: type: boolean commands: # ── resolve ─────────────────────────────────────── resolve: summary: Resolve DSL (load + merge extends) and output YAML. description: >- Loads the agent-contracts DSL file, merges all extends inheritance chains, substitutes variables from config, and outputs the fully resolved result as YAML or JSON. usage: - agent-contracts resolve - agent-contracts resolve path/to/agent-contracts.yaml - agent-contracts resolve --format json - agent-contracts resolve --expand-defaults - agent-contracts resolve -c agent-contracts.config.yaml arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [text, json] default: text - name: expand-defaults description: >- Expand all Zod default values in output. Fields like required_validations, tags, and can_read_artifacts are written explicitly instead of relying on schema defaults. schema: type: boolean default: false exits: '0': description: Resolved DSL output successfully. stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Defaults to text (YAML representation); json produces a JSON object. '1': description: Resolution failed (file not found, parse error, or config error). stderr: format: text # ── validate ────────────────────────────────────── validate: summary: Validate DSL against schema and check references. description: >- Validates the resolved DSL against the Zod schema, checks inter-entity references (agent→task, task→artifact, etc.), and validates handoff schemas. Reports diagnostics with severity levels. usage: - agent-contracts validate - agent-contracts validate path/to/agent-contracts.yaml - agent-contracts validate --strict - agent-contracts validate --format json - agent-contracts validate --quiet arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Diagnostic output format. value_name: format schema: type: string enum: [text, json] default: text - name: quiet description: Suppress output on success. schema: type: boolean default: false - name: strict description: Treat warnings as errors. schema: type: boolean default: false exits: '0': description: Validation passed. No errors found. stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Text shows human-readable diagnostics; json produces structured validation results. '1': description: Validation failed or unexpected error. stderr: format: text # ── lint ────────────────────────────────────────── lint: summary: Run semantic lint rules on resolved DSL. description: >- Runs TypeScript-based semantic lint rules and Spectral rules on the resolved DSL. Checks for best-practice violations, naming conventions, and structural issues beyond schema conformance. usage: - agent-contracts lint - agent-contracts lint path/to/agent-contracts.yaml - agent-contracts lint --strict - agent-contracts lint --format json arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [text, json] default: text - name: quiet description: Suppress output on success. schema: type: boolean default: false - name: strict description: Treat warnings as errors. schema: type: boolean default: false exits: '0': description: Lint passed. No errors or warnings. stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Text shows human-readable diagnostics; json produces structured lint results. '1': description: Lint failed or unexpected error. stderr: format: text # ── render (deprecated alias) ───────────────────── render: summary: (deprecated) Alias for 'generate templates'. deprecated: message: >- Use 'agent-contracts generate templates' instead. alternative: generate templates description: >- Deprecated alias for 'agent-contracts generate templates'. Renders output files from the resolved DSL using Handlebars templates and emits a deprecation warning. Supports --check for drift detection. Requires a config file. usage: - agent-contracts render -c agent-contracts.config.yaml - agent-contracts render -c agent-contracts.config.yaml --check - agent-contracts render --quiet effects: risk_level: medium writes: - generated-templates options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: check description: Check for template drift without writing files. schema: type: boolean default: false - name: quiet description: Suppress output on success. schema: type: boolean default: false exits: '0': description: Generation succeeded (or no drift detected in --check mode). stdout: format: text '1': description: >- Generation failed, config not found, schema validation failed, or drift detected in --check mode. stderr: format: text x-agent: recommended_before_use: - Ensure agent-contracts.config.yaml exists with render targets. - Run validate first to confirm DSL is valid. # ── check ───────────────────────────────────────── check: summary: Run full pipeline — resolve, validate, lint, render --check. description: >- Executes the complete verification pipeline in order: (1) resolve DSL, (2) validate schema and references, (3) run lint rules, (4) check render drift via render --check. Steps 1–4 always run. Additionally, when the DSL declares cross-team interfaces, (5) verifies interface import consistency and (6) checks team-interface.yaml drift. Steps 5–6 are skipped when no cross-team interfaces exist. usage: - agent-contracts check -c agent-contracts.config.yaml - agent-contracts check -c agent-contracts.config.yaml --strict - agent-contracts check --format json --quiet options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Diagnostic output format. value_name: format schema: type: string enum: [text, json] default: text - name: quiet description: Suppress output on success. schema: type: boolean default: false - name: strict description: Treat warnings as errors. schema: type: boolean default: false exits: '0': description: All checks passed. stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Text shows human-readable pipeline summary; json produces structured results per pipeline stage. '1': description: >- One or more checks failed — validation errors, lint errors, render drift, or missing interface files. stderr: format: text x-agent: recommended_before_use: - Ensure agent-contracts.config.yaml exists. # ── score ───────────────────────────────────────── score: summary: Calculate DSL completeness score. description: >- Evaluates the resolved DSL across 7 dimensions including artifact validation coverage, task validation coverage, guardrail policy coverage, workflow validation integration, schema completeness, cross-reference bidirectionality, and guardrail scope resolution. Returns a score out of 100 with optional CI gating via --threshold. usage: - agent-contracts score - agent-contracts score --format json - agent-contracts score --threshold 70 - agent-contracts score -c agent-contracts.config.yaml arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [text, json] default: text - name: threshold description: Minimum score; exit 1 if below (for CI gates). value_name: number schema: type: integer exits: '0': description: Score calculated (and above threshold if specified). stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Text shows human-readable score breakdown; json produces structured score object with per-dimension details. '1': description: >- Score below threshold, schema validation failed, or unexpected error. stderr: format: text # ── audit ─────────────────────────────────────────── audit: summary: Run LLM-based semantic audit on DSL definitions and generated outputs. description: >- Performs LLM-based semantic analysis on DSL definitions and/or generated outputs. Four audit types are available: "render" checks whether generated files faithfully reflect the resolved DSL, "dsl" reviews DSL design for semantic coherence, "prompt" verifies that generated prompts accurately express DSL intent, and "extensions" detects declared x-* properties that are not consumed by render templates or runtime codegen. Uses agent-contracts-runtime (optional peer dependency) for LLM execution with handoff schema validation and follow-up recovery. usage: - agent-contracts audit render -c agent-contracts.config.yaml - agent-contracts audit dsl -c agent-contracts.config.yaml - agent-contracts audit prompt -c agent-contracts.config.yaml - agent-contracts audit extensions -c agent-contracts.config.yaml - agent-contracts audit all -c agent-contracts.config.yaml - agent-contracts audit dsl --dry-run -c agent-contracts.config.yaml - agent-contracts audit render --format json -c agent-contracts.config.yaml - agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml effects: risk_level: medium reads: - dsl-definitions - config writes: - audit-report network: description: >- LLM API calls to configured adapter (e.g. OpenAI, Gemini, Cursor). Incurs token cost and sends DSL content to the LLM provider. idempotent: false idempotent_note: >- LLM inference is non-deterministic — identical inputs may produce different findings across runs. arguments: - name: type index: 0 required: false description: >- Audit type to run: render (semantic diff of generated outputs vs DSL), dsl (design coherence review), prompt (generated prompt fidelity check), extensions (unconsumed x-* property detection), or all (run all four). schema: type: string enum: [render, dsl, prompt, extensions, all] default: all options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [text, json, markdown] default: text - name: scope description: >- Limit audit scope to specified entities (e.g. agents:architect,implementer). value_name: entities schema: type: string - name: dry-run description: Output the audit prompt without calling LLM. schema: type: boolean default: false - name: adapter description: >- SDK adapter to use for LLM calls (overrides config audit.adapter). value_name: name schema: type: string - name: model description: LLM model override (overrides config audit.model). value_name: name schema: type: string - name: fail-on description: >- Minimum finding severity that causes exit 10 (info|warning|error|critical). value_name: level schema: type: string enum: [info, warning, error, critical] default: critical - name: output aliases: [o] description: Write result to a file instead of stdout. value_name: file schema: type: string file: mode: write encoding: utf-8 - name: report-format description: >- Alias for --format. When both are specified, --report-format takes precedence. value_name: fmt schema: type: string enum: [text, json, markdown] default: text exits: '0': description: Audit succeeded. No findings at or above --fail-on threshold. stdout: format: '{options.format}' schema: $ref: './dsl_base/components.yaml#/schemas/agent-audit-result' '1': description: Unexpected error (invalid input, config error, or internal failure). stderr: format: text '10': description: Findings at or above --fail-on severity threshold detected. stdout: format: '{options.format}' schema: $ref: './dsl_base/components.yaml#/schemas/agent-audit-result' stderr: format: text schema_note: >- Summary diagnostic on stderr. Structured findings are emitted on stdout in the requested format. '11': description: >- Runtime dependency missing (agent-contracts-runtime not installed). stderr: format: text '12': description: LLM provider or adapter error (API failure, auth error). stderr: format: text x-agent: retryable_exit_codes: [12] recommended_before_use: - Ensure agent-contracts.config.yaml exists with render targets. - Run validate first to confirm DSL is valid. - Install agent-contracts-runtime if not using --dry-run. # ── generate ────────────────────────────────────── generate: summary: Generate artifacts from DSL — templates, guardrails, and/or interface. description: >- Unified generation command. When type is omitted, runs all generation targets (templates, guardrails, interface). When type is "templates", renders output files from the DSL using Handlebars templates. When type is "guardrails", produces guardrail binding files from DSL, policies, and software bindings. When type is "interface", generates a team interface YAML/JSON file from the DSL's team_interface section. usage: - agent-contracts generate - agent-contracts generate -c agent-contracts.config.yaml - agent-contracts generate templates - agent-contracts generate templates --check - agent-contracts generate guardrails -c agent-contracts.config.yaml - agent-contracts generate guardrails --binding cursor-rules - agent-contracts generate guardrails --dry-run - agent-contracts generate interface -c agent-contracts.config.yaml - agent-contracts generate interface --format json - agent-contracts generate interface -o team-interface.yaml --dry-run effects: risk_level: low writes: - generated-templates - generated-guardrails - generated-interface arguments: - name: type index: 0 required: false description: >- Type of artifacts to generate. Omit to run all targets. schema: type: string enum: [templates, guardrails, interface] options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: check description: >- Check for template drift without writing files. Only applies to the templates target. schema: type: boolean default: false - name: binding description: Filter to specific software binding(s). Guardrails type only. value_name: name repeatable: true schema: type: string - name: output aliases: [o] description: Output path for generated team interface. Interface type only. value_name: path schema: type: string file: mode: write media_type: application/yaml encoding: utf-8 - name: format description: Output format for team interface (yaml or json). Interface type only. value_name: format schema: type: string enum: [yaml, json] default: yaml - name: dry-run description: Print what would be generated without writing files. schema: type: boolean default: false - name: quiet description: Suppress output on success. schema: type: boolean default: false exits: '0': description: Generation succeeded (or no drift detected in --check mode). stdout: format: text '1': description: >- Generation failed — unknown type, schema validation failed, config not found, drift detected, or error-level diagnostics. stderr: format: text x-agent: recommended_before_use: - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions. - Run validate first to confirm DSL is valid. # ── navigation-index ────────────────────────────── navigation-index: summary: Build artifact-centric navigation index from resolved DSL. description: >- Compiles a structured navigation index that maps each artifact to its operations (producer, validator, consumer tools), agent permissions (owner, editor, reader), inter-artifact relations, and recommended action routes. The index is a queryable model for runtime planners, guardrails, and governance tools. usage: - agent-contracts navigation-index - agent-contracts navigation-index --format json - agent-contracts navigation-index --artifact api-contracts - agent-contracts navigation-index -c agent-contracts.config.yaml arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [json, yaml] default: json - name: artifact description: Filter output to a single artifact by ID. value_name: id schema: type: string - name: quiet description: Suppress informational output. schema: type: boolean default: false exits: '0': description: Navigation index built successfully. stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. JSON produces a ProjectNavigationIndex object; yaml produces its YAML representation. '1': description: Build failed — schema validation error, config error, or resolution failure. stderr: format: text # ── artifact-coverage ──────────────────────────────── artifact-coverage: summary: Measure file coverage by artifact path_patterns definitions. description: >- Cross-references git ls-files output against compiled artifact path_patterns / exclude_patterns to measure what percentage of a project's tracked files are covered by artifact definitions. Reports uncovered files, overlapping files, and per-artifact match counts. Supports CI gating via --min-coverage. usage: - agent-contracts artifact-coverage - agent-contracts artifact-coverage -c agent-contracts.config.yaml - agent-contracts artifact-coverage --format json - agent-contracts artifact-coverage --min-coverage 80 arguments: - name: dir index: 0 required: false description: Path to agent-contracts.yaml. schema: type: string default: agent-contracts.yaml file: mode: read exists: true media_type: application/yaml encoding: utf-8 options: - name: config aliases: [c] description: Path to agent-contracts.config.yaml. value_name: path schema: type: string file: mode: read exists: false media_type: application/yaml encoding: utf-8 - name: team description: Limit to one team (multi-team config only). value_name: id schema: type: string - name: format description: Output format. value_name: format schema: type: string enum: [text, json] default: text - name: min-coverage description: Minimum coverage percentage; exit 1 if below (for CI gates). value_name: number schema: type: number exits: '0': description: Coverage report generated (and above threshold if --min-coverage specified). stdout: format: '{options.format}' schema_note: >- Output format depends on --format option. Text shows human-readable coverage report; json produces structured ArtifactCoverageReport object. '1': description: >- Coverage below threshold, schema validation failed, or unexpected error. stderr: format: text