agent-contracts-runtime/dsl/handoff-types.yaml

Runtime bridge for executing agent-contracts workflows on Agent SDKs

implement-request:
  version: 1
  description: Request to implement LLM-powered features in a CLI tool
  schema:
    type: object
    required:
      - description
      - project_dir
    properties:
      description:
        type: string
        description: Description of the LLM feature(s) to implement
      project_dir:
        type: string
        description: Absolute path to the target project directory
      reference_doc:
        type: string
        description: Content of the integrate-llm-commands reference documentation

audit-request:
  version: 1
  description: Request to audit an LLM command integration
  schema:
    type: object
    required:
      - project_dir
    properties:
      project_dir:
        type: string
        description: Absolute path to the target project directory
      focus:
        type: string
        description: >-
          Optional focus area (dsl, runtime, cli-contract, architecture, or all).
          Defaults to all.
        enum: [all, dsl, runtime, cli-contract, architecture]

audit-result:
  version: 1
  description: >-
    Structured audit result following AgentAuditResult shape.
    Conforms to cli-contracts reference schema.
  schema:
    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: any critical → critical,
          any error → high, any warning → medium, info only → low
      findings:
        type: array
        items:
          type: object
          required:
            - severity
            - category
            - message
          properties:
            id:
              type: string
              description: Unique finding identifier (e.g. AUDIT-001)
            severity:
              type: string
              enum: [info, warning, error, critical]
            category:
              type: string
              description: >-
                One of: dsl-structure, dsl-agent, dsl-task, dsl-handoff,
                dsl-workflow, dsl-guardrail, runtime-adapter,
                runtime-orchestrator, runtime-registry, runtime-handler,
                runtime-plugin, cli-contract-options, cli-contract-xagent,
                cli-contract-exits, cli-contract-schema,
                architecture-modules, architecture-dry-run,
                architecture-context-builder, architecture-agent-coherence,
                architecture-adapter-cwd, architecture-handler,
                architecture-formatter
            target:
              type: string
              description: File path where the issue was found
            location:
              type: string
              description: Line number or section within the file
            message:
              type: string
              description: Concise description of the issue
            recommendation:
              type: string
              description: Concrete fix or remediation step
            confidence:
              type: number
              minimum: 0
              maximum: 1
              description: >-
                1.0 for pattern match, 0.8+ for structural check,
                0.5-0.8 for heuristic assessment
      recommendedActions:
        type: array
        items:
          type: object
          required:
            - kind
            - title
          properties:
            kind:
              type: string
              enum: [run_command, edit_file, review, confirm, block, ignore]
            title:
              type: string
            command:
              type: string
              description: CLI command to run (for run_command kind)
            target:
              type: string
              description: Target file or resource
            rationale:
              type: string
      metadata:
        type: object
        properties:
          tool:
            type: string
          command:
            type: string
          version:
            type: string
          generatedAt:
            type: string
          adapter:
            type: string
          model:
            type: string

implementation-result:
  version: 1
  description: Result of the LLM feature implementation
  schema:
    type: object
    required:
      - files_created
      - files_modified
      - summary
    properties:
      files_created:
        type: array
        items:
          type: string
        description: List of newly created files
      files_modified:
        type: array
        items:
          type: string
        description: List of modified existing files
      summary:
        type: string
        description: Human-readable summary of the implementation
      commands_added:
        type: array
        items:
          type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Command name
            type:
              type: string
              enum: [audit, propose, explain]
              description: Command type
            description:
              type: string
              description: Command description
      next_steps:
        type: array
        items:
          type: string
        description: Recommended next steps for the developer