agent-contracts-runtime/cli-contract.yaml

Runtime bridge for executing agent-contracts workflows on Agent SDKs

cli_contracts: 0.1.0

info:
  title: agent-runtime CLI
  version: 0.36.0
  description: |
    Runtime bridge for executing agent-contracts workflows on Agent SDKs.
    Generates typed contracts, handoff validators, and guardrail hooks from DSL,
    then runs workflows through pluggable SDK adapters.
  license:
    name: MIT

command_sets:
  agent-runtime:
    summary: CLI for agent-contracts-runtime — generate, run, and manage agent workflows.
    global_options:
      - name: config
        aliases: [c]
        description: Path to agents.conf.yaml (project runtime config).
        schema:
          type: string
          default: ./agents.conf.yaml
        file:
          mode: read
          exists: true
          media_type: application/yaml

      - name: verbose
        aliases: [v]
        description: Enable verbose output.
        schema:
          type: boolean
          default: false

      - name: quiet
        aliases: [q]
        description: Suppress non-error output.
        schema:
          type: boolean
          default: false

    commands:
      # -----------------------------------------------------------------------
      # init
      # -----------------------------------------------------------------------
      init:
        summary: Initialize runtime scaffolding for a project.
        description: |
          Generates the initial directory structure and configuration files
          for using agent-contracts-runtime in a project.
          Creates agents.conf.yaml and agent/src/ user code templates.
        options:
          - name: adapter
            aliases: [a]
            description: Default SDK adapter to configure.
            schema:
              type: string
              enum: [claude, gemini, openai, mock]
              default: mock

          - name: output
            aliases: [o]
            description: Output directory for generated scaffolding.
            schema:
              type: string
              default: "."

          - name: force
            aliases: [f]
            description: Overwrite existing files without prompting.
            schema:
              type: boolean
              default: false

        exits:
          "0":
            description: Scaffolding generated successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/InitResult"

          "1":
            description: Initialization failed (existing files, permission error, etc.).
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: false
          sideEffects:
            - filesystem_write
          safeDryRunOption: ""

      # -----------------------------------------------------------------------
      # generate
      # -----------------------------------------------------------------------
      generate:
        summary: Generate runtime contracts and hooks from DSL.
        description: |
          Reads agent-contracts.yaml, resolves the DSL, validates it,
          and generates typed contracts, handoff schemas, guardrail hooks,
          and a runtime manifest into the configured generated_dir.

          Each generated file includes a DO NOT EDIT header.
        options:
          - name: clean
            description: |
              Delete generated_dir before regenerating.
              Removes stale files that may remain from previous generations.
            schema:
              type: boolean
              default: false

          - name: check
            description: |
              Dry-run mode for CI. Does not write files.
              Compares current generated output with what would be regenerated.
              Exits with code 1 if any differences are found.
            schema:
              type: boolean
              default: false

          - name: templates
            aliases: [t]
            description: Custom templates directory. Overrides built-in templates.
            schema:
              type: string

        exits:
          "0":
            description: Generation completed successfully (or --check found no differences).
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/GenerateResult"

          "1":
            description: |
              Generation failed, or --check detected differences between
              current generated files and expected output.
            stderr:
              format: text

          "2":
            description: DSL validation error. The input DSL has structural or semantic issues.
            stderr:
              format: json
              schema:
                $ref: "#/components/schemas/ValidationError"

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects:
            - filesystem_write
          safeDryRunOption: check

      # -----------------------------------------------------------------------
      # run
      # -----------------------------------------------------------------------
      run:
        summary: Execute a workflow.
        description: |
          Loads generated contracts, creates an SDK adapter, registers user plugins,
          and executes the specified workflow with the given user request.

          The workflow runner orchestrates task delegation, retry, gate handling,
          and handoff validation mechanically.
        arguments:
          - name: workflow-id
            required: false
            description: ID of the workflow to execute. Required unless --file is used.
            schema:
              type: string

          - name: user-request
            required: false
            description: Natural language description of what to do. Required unless --file is used.
            schema:
              type: string

        options:
          - name: adapter
            aliases: [a]
            description: SDK adapter to use. Overrides config.
            schema:
              type: string
              enum: [claude, gemini, openai, mock]

          - name: max-retries
            aliases: [r]
            description: Override default max retries per step.
            schema:
              type: integer
              minimum: 0
              maximum: 10

          - name: max-follow-ups
            aliases: [f]
            description: Override default max follow-ups per step.
            schema:
              type: integer
              minimum: 0
              maximum: 10

          - name: dry-run
            aliases: [n]
            description: Simulate execution without calling the SDK adapter.
            schema:
              type: boolean
              default: false

          - name: auto-approve-gates
            description: Automatically approve all gate steps.
            schema:
              type: boolean
              default: false

          - name: file
            description: |
              Path to a YAML invocation file. When provided, workflow-id and
              user-request arguments are read from the file instead of CLI args.
            schema:
              type: string
            file:
              mode: read
              exists: true
              media_type: application/yaml

          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file. Overrides config logging.progress_log.
            schema:
              type: string
            file:
              mode: write

        exits:
          "0":
            description: Workflow completed successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/WorkflowResult"

          "1":
            description: Workflow failed (escalation, error, or gate rejection).
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/WorkflowResult"
            stderr:
              format: text

          "3":
            description: >-
              Input validation failed (invalid arguments, unknown workflow/adapter,
              or generated files outdated).
            stderr:
              format: text

          "12":
            description: Adapter initialization error (missing API key, etc.).
            stderr:
              format: text

        x-agent:
          riskLevel: high
          requiresConfirmation: true
          idempotent: false
          sideEffects:
            - sdk_call
            - filesystem_write
          safeDryRunOption: dry-run
          expectedDurationMs: 300000
          recommendedBeforeUse:
            - Run `agent-runtime generate --check` to ensure contracts are up to date.
            - Run `agent-runtime doctor` to verify SDK configuration.

      # -----------------------------------------------------------------------
      # list
      # -----------------------------------------------------------------------
      list:
        summary: List available workflows, tasks, or agents.
        description: |
          Reads generated contracts and displays available resources.
          Useful for discovering what workflows, tasks, and agents
          are defined in the current project.
        arguments:
          - name: resource
            required: true
            description: Type of resource to list.
            schema:
              type: string
              enum: [workflows, tasks, agents]

        options:
          - name: format
            description: Output format.
            schema:
              type: string
              enum: [table, json]
              default: table

        exits:
          "0":
            description: Resources listed successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/ListResult"

          "1":
            description: Failed to load contracts.
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []

      # -----------------------------------------------------------------------
      # show-prompt
      # -----------------------------------------------------------------------
      show-prompt:
        summary: Display the generated prompt for a task.
        description: |
          Builds and displays the full prompt that would be sent to an SDK agent
          for a given task. Useful for inspecting, debugging, and validating
          prompt content before execution.

          Shows the agent role, responsibilities, constraints, task details,
          completion criteria, handoff schema fields, and output format example.
        arguments:
          - name: task-id
            required: true
            description: ID of the task to show the prompt for (e.g. plan-and-implement, audit-tests).
            schema:
              type: string

        options:
          - name: user-request
            aliases: [u]
            description: User request text to include in the prompt preview.
            schema:
              type: string
              default: "(preview)"

          - name: format
            description: Output format.
            schema:
              type: string
              enum: [markdown, raw, json]
              default: markdown

          - name: with-plugins
            description: Apply registered plugin prompt enhancers to the output.
            schema:
              type: boolean
              default: false

        exits:
          "0":
            description: Prompt displayed successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/ShowPromptResult"

          "1":
            description: Failed to build prompt (unknown task, missing contracts, etc.).
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []

      # -----------------------------------------------------------------------
      # implement
      # -----------------------------------------------------------------------
      implement:
        summary: Implement LLM-powered commands in a CLI tool.
        description: |
          Uses an agentic LLM adapter (Claude, etc.) to analyze the
          target project and implement LLM-powered commands following the
          agent-contracts + agent-contracts-runtime + cli-contracts stack.

          The agent reads the project structure, cli-contract.yaml, and existing
          code, then generates DSL definitions, TypeScript modules (orchestrator,
          context-builder, formatter), CLI command handlers, and updates the
          CLI contract with x-agent metadata.

          Requires an agentic adapter that supports tool use (file read/write).
        arguments:
          - name: description
            required: true
            description: >-
              Natural language description of the LLM feature(s) to implement.
              Examples: "Add an audit command for migration safety",
              "Add propose and explain commands for SQL optimization".
            schema:
              type: string

        options:
          - name: adapter
            aliases: [a]
            description: SDK adapter to use. Must be an agentic adapter (claude).
            schema:
              type: string
              enum: [claude, mock]
              default: claude

          - name: project-dir
            aliases: [p]
            description: Path to the target project directory.
            schema:
              type: string
              default: "."

          - name: dry-run
            aliases: [n]
            description: Output the prompt context without calling the LLM.
            schema:
              type: boolean
              default: false

          - name: model
            description: Model name override for the selected adapter.
            schema:
              type: string

          - name: output
            aliases: [o]
            description: Write the result to a file instead of stdout.
            schema:
              type: string
            file:
              mode: write

          - name: report-format
            description: Output format for the result.
            schema:
              type: string
              enum: [json, text, yaml]
              default: text

          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file.
            schema:
              type: string
            file:
              mode: write

        exits:
          "0":
            description: Implementation completed successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/ImplementResult"

          "1":
            description: Implementation failed.
            stderr:
              format: text

          "3":
            description: Input validation failed (e.g. project directory not found).
            stderr:
              format: text

          "12":
            description: Adapter initialization error.
            stderr:
              format: text

        x-agent:
          riskLevel: high
          requiresConfirmation: true
          idempotent: false
          sideEffects:
            - sdk_call
            - filesystem_write
          safeDryRunOption: dry-run
          expectedDurationMs: 300000
          retryableExitCodes: [1, 12]
          recommendedBeforeUse:
            - Ensure the target project has a cli-contract.yaml or plan to create one.
            - Run in a clean git working tree so changes can be reviewed.

      # -----------------------------------------------------------------------
      # audit-implementation
      # -----------------------------------------------------------------------
      audit-implementation:
        summary: Audit an LLM command integration for pattern conformance.
        description: |
          Analyzes a target project's LLM command integration to verify it
          correctly follows the agent-contracts + agent-contracts-runtime +
          cli-contracts stack conventions.

          Checks all three layers:
          1. DSL definitions (agents, tasks, workflows, handoff schemas)
          2. Runtime integration (adapter usage, runTask/runWorkflow, registries)
          3. CLI contract (standard options, x-agent metadata, exit codes)

          Produces structured findings with severity, category, and
          concrete remediation steps. Read-only — does not modify files.
        arguments:
          - name: project-dir
            required: false
            description: >-
              Path to the project directory to audit. Defaults to current directory.
            schema:
              type: string

        options:
          - name: adapter
            aliases: [a]
            description: SDK adapter to use for the audit agent.
            schema:
              type: string
              enum: [claude, mock]
              default: claude

          - name: focus
            description: >-
              Limit audit to a specific layer. Defaults to all layers.
            schema:
              type: string
              enum: [all, dsl, runtime, cli-contract, architecture]
              default: all

          - name: dry-run
            aliases: [n]
            description: Output the prompt context without calling the LLM.
            schema:
              type: boolean
              default: false

          - name: fail-on
            description: Minimum finding severity that causes a non-zero exit.
            schema:
              type: string
              enum: [warning, error, critical]
              default: error

          - name: model
            description: Model name override for the selected adapter.
            schema:
              type: string

          - name: output
            aliases: [o]
            description: Write the result to a file instead of stdout.
            schema:
              type: string
            file:
              mode: write

          - name: report-format
            description: Output format for the audit report.
            schema:
              type: string
              enum: [json, text, yaml]
              default: text

          - name: log-file
            aliases: [l]
            description: Write agent progress log to this file.
            schema:
              type: string
            file:
              mode: write

        exits:
          "0":
            description: Audit completed with no findings above threshold.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/AuditImplementationResult"

          "1":
            description: Audit failed (agent error, unexpected failure).
            stderr:
              format: text

          "3":
            description: Input validation failed (e.g. project directory not found).
            stderr:
              format: text

          "10":
            description: Audit completed with findings above --fail-on threshold.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/AuditImplementationResult"

          "12":
            description: Adapter initialization error.
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects:
            - network
          sideEffectNote: >-
            Network calls to LLM provider when adapter is not mock.
            Filesystem write only when --output is specified.
          safeDryRunOption: dry-run
          expectedDurationMs: 180000
          retryableExitCodes: [1, 12]

      # -----------------------------------------------------------------------
      # agents
      # -----------------------------------------------------------------------
      agents:
        summary: Output the full resolved DSL as structured data.
        description: |
          Outputs the complete resolved DSL (agents, tasks, workflows,
          handoff_types, etc.) embedded in this CLI binary.

          Useful for debugging, external tooling integration, and DSL
          inspection. Unlike `list`, which shows tabular summaries,
          this command outputs the full DSL structure.
        options:
          - name: format
            aliases: [F]
            description: Output format.
            schema:
              type: string
              enum: [yaml, json]
              default: yaml

        exits:
          "0":
            description: DSL output successfully.
            stdout:
              format: text

          "1":
            description: Failed to load embedded DSL.
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []

      # -----------------------------------------------------------------------
      # doctor
      # -----------------------------------------------------------------------
      doctor:
        summary: Verify configuration, generated files, and SDK connectivity.
        description: |
          Runs a series of diagnostic checks to verify that the project
          is correctly configured for agent-runtime execution.

          Checks: config existence, DSL existence, generated manifest freshness,
          adapter configuration, API key environment variables, plugin entrypoint.
        exits:
          "0":
            description: All checks passed.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/DoctorResult"

          "1":
            description: One or more checks failed.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/DoctorResult"

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []

      # -----------------------------------------------------------------------
      # navigation-index
      # -----------------------------------------------------------------------
      navigation-index:
        summary: Build artifact navigation index from resolved DSL.
        description: |
          Resolves the embedded DSL (merged with project overlay if configured),
          applies artifact binding, and builds a navigation index showing
          artifact-to-tool-to-agent mappings.

          The output is a JSON/YAML structure suitable for IDE integration,
          routing rules, and artifact coverage analysis.
        options:
          - name: format
            aliases: [F]
            description: Output format.
            schema:
              type: string
              enum: [json, yaml]
              default: json

          - name: artifact
            description: Filter output to a single artifact by ID.
            schema:
              type: string

          - name: output
            aliases: [o]
            description: Write output to a file instead of stdout.
            schema:
              type: string
            file:
              mode: write

        exits:
          "0":
            description: Navigation index built successfully.
            stdout:
              format: json
              schema:
                $ref: "#/components/schemas/NavigationIndexResult"

          "1":
            description: Failed to build navigation index.
            stderr:
              format: text

        x-agent:
          riskLevel: low
          requiresConfirmation: false
          idempotent: true
          sideEffects: []


# =============================================================================
# Components
# =============================================================================

components:
  schemas:
    # -------------------------------------------------------------------------
    # init
    # -------------------------------------------------------------------------
    InitResult:
      type: object
      required: [files_created]
      properties:
        files_created:
          type: array
          items:
            type: string
          description: List of files created by init.

    # -------------------------------------------------------------------------
    # generate
    # -------------------------------------------------------------------------
    GenerateResult:
      type: object
      required: [files_generated, dsl_hash, generation_input_hash]
      properties:
        files_generated:
          type: array
          items:
            type: string
          description: List of generated file paths.
        dsl_hash:
          type: string
          description: SHA-256 hash of the resolved DSL (canonical stringify).
        generation_input_hash:
          type: string
          description: SHA-256 hash of all generation inputs.
        cleaned:
          type: boolean
          description: Whether --clean was used.
        check_mode:
          type: boolean
          description: Whether --check was used.
        has_differences:
          type: boolean
          description: In --check mode, whether differences were found.

    ValidationError:
      type: object
      required: [errors]
      properties:
        errors:
          type: array
          items:
            type: object
            required: [code, message]
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: string
                description: JSON path to the invalid element.

    # -------------------------------------------------------------------------
    # run
    # -------------------------------------------------------------------------
    WorkflowResult:
      type: object
      required: [workflow_id, status, steps, total_elapsed_ms]
      properties:
        workflow_id:
          type: string
        status:
          type: string
          enum: [completed, escalated, gate_rejected, error]
        steps:
          type: array
          items:
            $ref: "#/components/schemas/StepResult"
        total_elapsed_ms:
          type: integer
          minimum: 0
        escalation_reason:
          type: string
        error_message:
          type: string

    StepResult:
      type: object
      required: [step_index, retries_used, elapsed_ms, outcome]
      properties:
        step_index:
          type: integer
          minimum: 0
        task_id:
          type: string
        gate_kind:
          type: string
        outcome:
          type: object
          required: [status]
          properties:
            status:
              type: string
              enum: [success, validation_error, escalation, error, gate_approved, gate_rejected, skipped]
        retries_used:
          type: integer
          minimum: 0
        elapsed_ms:
          type: integer
          minimum: 0

    # -------------------------------------------------------------------------
    # list
    # -------------------------------------------------------------------------
    ListResult:
      type: object
      required: [resource, items]
      properties:
        resource:
          type: string
          enum: [workflows, tasks, agents]
        items:
          type: array
          items:
            type: object
            required: [id, description]
            properties:
              id:
                type: string
              description:
                type: string

    # -------------------------------------------------------------------------
    # show-prompt
    # -------------------------------------------------------------------------
    ShowPromptResult:
      type: object
      required: [task_id, agent_id, prompt]
      properties:
        task_id:
          type: string
          description: The task ID used to build the prompt.
        agent_id:
          type: string
          description: The target agent ID for this task.
        prompt:
          type: string
          description: The full generated prompt text.
        handoff_schema:
          type: string
          description: The handoff schema ID for the task result.
        plugins_applied:
          type: boolean
          description: Whether plugin prompt enhancers were applied.

    # -------------------------------------------------------------------------
    # doctor
    # -------------------------------------------------------------------------
    DoctorResult:
      type: object
      required: [checks, all_passed]
      properties:
        checks:
          type: array
          items:
            $ref: "#/components/schemas/DoctorCheck"
        all_passed:
          type: boolean

    # -------------------------------------------------------------------------
    # implement
    # -------------------------------------------------------------------------
    ImplementResult:
      type: object
      required: [files_created, files_modified, summary]
      properties:
        files_created:
          type: array
          items:
            type: string
          description: List of new files created.
        files_modified:
          type: array
          items:
            type: string
          description: List of existing files modified.
        summary:
          type: string
          description: Human-readable summary of what was implemented.
        commands_added:
          type: array
          items:
            type: object
            required: [name, type]
            properties:
              name:
                type: string
              type:
                type: string
                enum: [audit, propose, explain]
              description:
                type: string
        next_steps:
          type: array
          items:
            type: string
          description: Recommended next steps for the developer.

    # -------------------------------------------------------------------------
    # audit-implementation
    # -------------------------------------------------------------------------
    AuditImplementationResult:
      type: object
      required: [summary, riskLevel, findings]
      properties:
        summary:
          type: string
          description: One-paragraph overall assessment.
        riskLevel:
          type: string
          enum: [low, medium, high, critical]
          description: Derived from worst finding severity.
        findings:
          type: array
          items:
            $ref: "#/components/schemas/AgentFinding"
        recommendedActions:
          type: array
          items:
            $ref: "#/components/schemas/AgentRecommendedAction"
        metadata:
          type: object
          properties:
            tool:
              type: string
            command:
              type: string
            version:
              type: string
            generatedAt:
              type: string
            adapter:
              type: string
            model:
              type: string

    DoctorCheck:
      type: object
      required: [name, status]
      properties:
        name:
          type: string
          description: Check name (e.g. config_exists, dsl_exists, manifest_fresh).
        status:
          type: string
          enum: [pass, fail, warn]
        message:
          type: string
          description: Human-readable detail.

    # -------------------------------------------------------------------------
    # navigation-index
    # -------------------------------------------------------------------------
    NavigationIndexResult:
      type: object
      required: [version, generated_at, system, artifacts]
      properties:
        version:
          type: string
        generated_at:
          type: string
        system:
          type: object
          required: [id, name]
          properties:
            id:
              type: string
            name:
              type: string
        artifacts:
          type: object
          additionalProperties: true

    # -------------------------------------------------------------------------
    # Canonical agent result schemas (AgentAuditResult sub-types)
    # -------------------------------------------------------------------------
    AgentFinding:
      type: object
      required: [severity, category, message]
      properties:
        id:
          type: string
          description: Unique finding identifier (e.g. F-001).
        severity:
          type: string
          enum: [info, warning, error, critical]
        category:
          type: string
          description: Domain vocabulary category (e.g. cli-contract-options, runtime-adapter).
        target:
          type: string
          description: File path or resource the finding applies to.
        location:
          type: string
          description: Line range or specific location within the target.
        message:
          type: string
          description: Human-readable description of the finding.
        recommendation:
          type: string
          description: Concrete remediation step.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence score (0–1) for the finding.
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/AgentEvidence"
        details:
          type: object
          description: Additional structured details specific to the finding category.

    AgentRecommendedAction:
      type: object
      required: [kind, title]
      properties:
        kind:
          type: string
          enum: [run_command, edit_file, review, confirm, block, ignore]
        title:
          type: string
          description: Short human-readable title for the action.
        command:
          type: string
          description: Shell command to run (when kind is run_command).
        target:
          type: string
          description: File path to edit (when kind is edit_file).
        rationale:
          type: string
          description: Explanation of why this action is recommended.

    AgentEvidence:
      type: object
      required: [type, content]
      properties:
        type:
          type: string
          description: Evidence type (e.g. code_snippet, file_excerpt, lint_output).
        content:
          type: string
          description: The evidence content.
        source:
          type: string
          description: Source file path or URL for the evidence.