va-agent-protocol 0.1.0

package/schemas/evidence.schema.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://va-agent-protocol.dev/schemas/evidence.schema.json",
+  "title": "Evidence",
+  "description": "Proof of task completion. CLI-first: evidence must be machine-verifiable, not self-certified.",
+  "type": "object",
+  "required": ["taskId", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "taskId": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["completed", "failed", "blocked"]
+    },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Artifact" },
+      "default": [],
+      "description": "What was produced."
+    },
+    "gateResults": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/GateResult" },
+      "default": [],
+      "description": "Results of quality gate commands."
+    },
+    "verification": {
+      "type": "string",
+      "description": "Human-readable summary of what was verified and how."
+    },
+    "failureDetail": {
+      "$ref": "#/$defs/FailureDetail",
+      "description": "Present when status is 'failed'. Structured failure metadata for pitfall learning."
+    },
+    "blockReason": {
+      "$ref": "#/$defs/BlockReason",
+      "description": "Present when status is 'blocked'. What external input is needed."
+    },
+    "outputs": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Structured outputs produced by this task. Keys should match outputContract.keys if declared. Downstream tasks can reference these via inputs[].fromTask."
+    }
+  },
+  "$defs": {
+    "Artifact": {
+      "type": "object",
+      "required": ["type", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["file", "commit", "report", "diff", "log"],
+          "description": "Kind of artifact produced."
+        },
+        "path": {
+          "type": "string",
+          "description": "File path or commit SHA."
+        },
+        "description": { "type": "string" }
+      }
+    },
+    "GateResult": {
+      "type": "object",
+      "required": ["gate", "passed"],
+      "additionalProperties": false,
+      "properties": {
+        "gate": {
+          "type": "string",
+          "description": "Gate name (e.g., 'typecheck', 'lint', 'unit-tests', 'style-consistency')."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["command", "model-evaluation"],
+          "default": "command",
+          "description": "Gate type. 'command' = CLI command with exit code. 'model-evaluation' = agent/model-as-judge with score."
+        },
+        "command": {
+          "type": "string",
+          "description": "Exact CLI command that was run. Required for type='command'."
+        },
+        "exitCode": {
+          "type": "integer",
+          "description": "Process exit code. For type='command'."
+        },
+        "passed": {
+          "type": "boolean",
+          "description": "Whether the gate passed."
+        },
+        "output": {
+          "type": "string",
+          "description": "Captured stdout/stderr (may be truncated)."
+        },
+        "durationMs": {
+          "type": "integer",
+          "description": "How long the gate took to run."
+        },
+        "evaluator": {
+          "type": "string",
+          "description": "Agent or model ID that performed the evaluation. For type='model-evaluation'."
+        },
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Evaluation score (0.0–1.0). For type='model-evaluation'."
+        },
+        "threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Score threshold for passing. score >= threshold → passed."
+        },
+        "softThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Score between softThreshold and threshold is a 'warning' — not a hard fail. Below softThreshold is a hard fail. Orchestrator can route warnings to blocked (human review) instead of failed (retry)."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["error", "warning"],
+          "description": "When passed=false: 'error' means hard fail (retry), 'warning' means soft fail (consider blocked for human review). Orchestrator decides based on softThreshold."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Human-readable explanation of the evaluation result. For type='model-evaluation'."
+        }
+      }
+    },
+    "FailureDetail": {
+      "type": "object",
+      "required": ["failureType", "attempted", "hypothesis"],
+      "additionalProperties": false,
+      "properties": {
+        "failureType": {
+          "type": "string",
+          "enum": ["gate", "acceptance", "review", "timeout", "crash", "unknown"]
+        },
+        "attempted": {
+          "type": "string",
+          "description": "What was tried."
+        },
+        "hypothesis": {
+          "type": "string",
+          "description": "Why it probably failed."
+        },
+        "missingContext": {
+          "type": "string",
+          "description": "What information was absent."
+        },
+        "dimensions": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/DimensionFeedback"
+          },
+          "description": "Per-dimension breakdown of the failure. Each key is a dimension name (e.g., 'vocabulary', 'tone', 'structure'). Enables targeted retry — the next attempt can focus on the specific dimensions that failed."
+        }
+      }
+    },
+    "DimensionFeedback": {
+      "type": "object",
+      "required": ["status"],
+      "additionalProperties": false,
+      "properties": {
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Dimension score (0.0–1.0)."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ok", "mismatch", "missing"],
+          "description": "Whether this dimension passed, mismatched, or was absent."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Specific feedback on this dimension."
+        }
+      }
+    },
+    "BlockReason": {
+      "type": "object",
+      "required": ["type", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["human-decision", "external-resource", "dependency", "permission"],
+          "description": "Why the task is blocked."
+        },
+        "description": { "type": "string" },
+        "requiredAction": {
+          "type": "string",
+          "description": "What needs to happen to unblock."
+        }
+      }
+    }
+  }
+}

package/schemas/lifecycle.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://va-agent-protocol.dev/schemas/lifecycle.schema.json",
+  "title": "TaskLifecycle",
+  "description": "State machine for task execution. Defines valid states and transitions.",
+  "type": "object",
+  "$defs": {
+    "TaskState": {
+      "type": "string",
+      "enum": ["pending", "running", "completed", "failed", "blocked", "cancelled"],
+      "description": "pending: queued, not yet dispatched. running: execution in progress. completed: all acceptance criteria met with evidence. failed: execution failed (may retry). blocked: needs external input (human or dependency). cancelled: terminated by orchestrator."
+    },
+    "ValidTransitions": {
+      "description": "Allowed state transitions. Any transition not listed here is invalid.",
+      "type": "object",
+      "properties": {
+        "pending":   { "const": ["running", "cancelled"] },
+        "running":   { "const": ["completed", "failed", "blocked", "cancelled"] },
+        "blocked":   { "const": ["running", "failed", "cancelled"] },
+        "completed": { "const": [] },
+        "failed":    { "const": ["running"] },
+        "cancelled": { "const": [] }
+      }
+    },
+    "StateTransition": {
+      "type": "object",
+      "required": ["from", "to", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "from": { "$ref": "#/$defs/TaskState" },
+        "to": { "$ref": "#/$defs/TaskState" },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Why this transition happened."
+        },
+        "actor": {
+          "type": "string",
+          "description": "Who triggered the transition (agent ID, 'orchestrator', or 'human')."
+        }
+      }
+    },
+    "TaskExecution": {
+      "type": "object",
+      "required": ["taskId", "correlationId", "currentState", "transitions"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": { "type": "string" },
+        "correlationId": {
+          "type": "string",
+          "description": "Unique ID for this execution attempt. A task may have multiple executions (retries)."
+        },
+        "agentId": { "type": "string" },
+        "currentState": { "$ref": "#/$defs/TaskState" },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Which retry attempt this is."
+        },
+        "transitions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/StateTransition" },
+          "description": "Ordered history of state transitions."
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

package/schemas/message.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://va-agent-protocol.dev/schemas/message.schema.json",
+  "title": "ProtocolMessage",
+  "description": "Envelope format for all orchestrator <-> agent communication. Every interaction is a message.",
+  "type": "object",
+  "required": ["protocol", "version", "type", "timestamp", "correlationId", "payload"],
+  "additionalProperties": false,
+  "properties": {
+    "protocol": {
+      "type": "string",
+      "const": "va-agent-protocol",
+      "description": "Protocol identifier. Always 'va-agent-protocol'."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Protocol version (semver)."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["dispatch", "accepted", "progress", "completed", "failed", "blocked", "cancel"],
+      "description": "Message type. dispatch/cancel: orchestrator->agent. accepted/progress/completed/failed/blocked: agent->orchestrator."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp."
+    },
+    "correlationId": {
+      "type": "string",
+      "description": "Ties all messages for one task execution together."
+    },
+    "sourceId": {
+      "type": "string",
+      "description": "ID of the sender (agent ID or 'orchestrator')."
+    },
+    "payload": {
+      "description": "Type-specific content. Schema depends on message type.",
+      "oneOf": [
+        { "$ref": "#/$defs/DispatchPayload" },
+        { "$ref": "#/$defs/AcceptedPayload" },
+        { "$ref": "#/$defs/ProgressPayload" },
+        { "$ref": "#/$defs/CompletedPayload" },
+        { "$ref": "#/$defs/FailedPayload" },
+        { "$ref": "#/$defs/BlockedPayload" },
+        { "$ref": "#/$defs/CancelPayload" }
+      ]
+    }
+  },
+  "$defs": {
+    "DispatchPayload": {
+      "type": "object",
+      "required": ["task"],
+      "additionalProperties": false,
+      "properties": {
+        "task": {
+          "$ref": "task-unit.schema.json",
+          "description": "The task to execute."
+        }
+      }
+    },
+    "AcceptedPayload": {
+      "type": "object",
+      "required": ["taskId"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": { "type": "string" },
+        "estimatedCapabilities": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "What capabilities the agent will use for this task."
+        }
+      }
+    },
+    "ProgressPayload": {
+      "type": "object",
+      "required": ["taskId"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": { "type": "string" },
+        "phase": {
+          "type": "string",
+          "description": "Current execution phase (agent-defined, e.g., 'implementing', 'reviewing', 'testing')."
+        },
+        "summary": {
+          "type": "string",
+          "description": "Brief status update."
+        },
+        "completionEstimate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "0.0 to 1.0 progress estimate. Optional and advisory only."
+        },
+        "logs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ProgressLog" },
+          "description": "Structured log entries from the agent's execution."
+        },
+        "data": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Key-value data the agent wants to expose to the orchestrator/UI."
+        },
+        "agentId": {
+          "type": "string",
+          "description": "The agent currently handling this task (populated by orchestrator)."
+        }
+      }
+    },
+    "CompletedPayload": {
+      "type": "object",
+      "required": ["evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "evidence": {
+          "$ref": "evidence.schema.json",
+          "description": "Proof of completion."
+        }
+      }
+    },
+    "FailedPayload": {
+      "type": "object",
+      "required": ["evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "evidence": {
+          "$ref": "evidence.schema.json",
+          "description": "Failure details with structured metadata."
+        },
+        "retryable": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the orchestrator should retry."
+        }
+      }
+    },
+    "BlockedPayload": {
+      "type": "object",
+      "required": ["evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "evidence": {
+          "$ref": "evidence.schema.json",
+          "description": "Block reason details."
+        }
+      }
+    },
+    "ProgressLog": {
+      "type": "object",
+      "required": ["timestamp", "level", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the log entry."
+        },
+        "level": {
+          "type": "string",
+          "enum": ["info", "warn", "error", "debug"],
+          "description": "Log severity level."
+        },
+        "message": {
+          "type": "string",
+          "description": "Log message content."
+        }
+      }
+    },
+    "CancelPayload": {
+      "type": "object",
+      "required": ["taskId"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": { "type": "string" },
+        "reason": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/task-unit.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://va-agent-protocol.dev/schemas/task-unit.schema.json",
+  "title": "TaskUnit",
+  "description": "Universal task contract. Defines WHAT to achieve, never HOW. The atomic unit of work in va-agent-protocol.",
+  "type": "object",
+  "required": ["id", "objective", "acceptanceCriteria"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique task identifier. Format is adapter-specific (e.g., 'AP-001' for va-auto-pilot)."
+    },
+    "objective": {
+      "type": "string",
+      "description": "What must be achieved. Goal-level description, not implementation steps."
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Hard limits that must hold throughout execution. Violations are automatic failures."
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Machine-verifiable conditions. Each should map to a deterministic check (CLI command, test, assertion)."
+    },
+    "context": {
+      "$ref": "#/$defs/TaskContext",
+      "description": "Input context provided to the agent."
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["P0", "P1", "P2", "P3"],
+      "default": "P1",
+      "description": "P0=blocking/critical, P1=high, P2=medium, P3=optimization/nice-to-have."
+    },
+    "dependsOn": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Task IDs that must complete before this task can start."
+    },
+    "timeout": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Maximum execution time in milliseconds. 0 or absent means no timeout."
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          { "$ref": "#/$defs/InputRef" },
+          {}
+        ]
+      },
+      "description": "Named inputs for this task. Values are either static (any JSON value) or references to outputs from dependency tasks (InputRef)."
+    },
+    "outputContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "keys": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Output keys this task promises to produce (stored in evidence.outputs)."
+        }
+      },
+      "description": "Declares what structured outputs this task will produce."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Adapter-specific or user-defined metadata. Protocol does not inspect this."
+    }
+  },
+  "$defs": {
+    "InputRef": {
+      "type": "object",
+      "required": ["fromTask", "outputKey"],
+      "additionalProperties": false,
+      "properties": {
+        "fromTask": {
+          "type": "string",
+          "description": "Task ID to read output from. Must be in dependsOn."
+        },
+        "outputKey": {
+          "type": "string",
+          "description": "Key in the source task's evidence.outputs to read."
+        }
+      },
+      "description": "Reference to an output from a dependency task. Resolved by the orchestrator before dispatch."
+    },
+    "TaskContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "codebaseRoot": {
+          "type": "string",
+          "description": "Absolute path to the working directory for this task."
+        },
+        "files": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relevant file paths (relative to codebaseRoot)."
+        },
+        "history": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Prior relevant decisions, context, or notes."
+        },
+        "pitfalls": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Pitfall" },
+          "description": "Known failure patterns from previous attempts."
+        }
+      }
+    },
+    "Pitfall": {
+      "type": "object",
+      "required": ["id", "failureType", "attempted", "hypothesis"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "failureType": {
+          "type": "string",
+          "enum": ["gate", "acceptance", "review", "timeout", "crash", "unknown"]
+        },
+        "attempted": { "type": "string" },
+        "hypothesis": { "type": "string" },
+        "missingContext": { "type": "string" }
+      }
+    }
+  }
+}