Lightweight contracts for agent task delegation.

Agent Contracts is a narrow specification and validation layer for delegated agent work. It helps teams describe what an agent is being asked to do, what inputs and outputs matter, which execution constraints apply, and when approval or handoff rules should shape the work.

This repository is intentionally not a workflow engine, orchestration framework, or full multi-agent platform. The goal of the alpha is smaller and sharper: make delegated work more explicit, more portable, and easier to validate.

Agent handoffs are often underspecified. A planner asks an executor to do work, but the contract between them is implied rather than declared. That usually means:

• required inputs are missing
• expected outputs are vague
• risk handling is inconsistent
• approval posture is unclear
• delegation rules are implicit
• downstream review is harder than it should be

Agent Contracts gives that handoff a lightweight, portable shape.

The current alpha includes:

• parsing of contract.yaml
• explicit JSON Schema validation
• minimum structural validation
• heuristic detection of weak delegation signals
• a local CLI with validate, lint, inspect, explain, init, and format
• JSON output mode for local tooling and CI
• an initial JSON Schema
• example contracts
• public-facing docs for vision, architecture, and roadmap

npm install
npm run build
node dist/cli.js validate examples/research-contract
node dist/cli.js lint examples/research-contract
node dist/cli.js inspect examples/change-plan-contract
node dist/cli.js explain examples/extraction-contract
node dist/cli.js init ./contracts/new-research --template research
node dist/cli.js format ./contracts/new-research --check
npm test

During development, you can also run:

npm run dev -- validate examples/research-contract

Checks schema compliance plus minimum validation posture. It fails when the schema is invalid or when high-severity issues are present.

agent-contracts validate ./examples/research-contract
agent-contracts validate ./examples/research-contract --json

Reports every contract finding, including lower-severity authoring gaps. This is the stricter quality command and is useful in CI or review workflows.

agent-contracts lint ./examples/research-contract
agent-contracts lint ./examples/research-contract --json

Example output:

Contract: Web Research Contract (research-web-v1)
Valid: yes
Schema valid: yes
Lint clean: yes
Signal strength: strong
Issue counts: 0 high, 0 medium, 0 low
No validation issues detected.

Prints a structured view of the contract for humans reviewing the file.

agent-contracts inspect ./examples/change-plan-contract
agent-contracts inspect ./examples/change-plan-contract --json

Turns the contract into a short human-oriented explanation, including key gaps if validation found any.

agent-contracts explain ./examples/extraction-contract
agent-contracts explain ./examples/extraction-contract --json

Creates a new contract scaffold from a small starter template.

agent-contracts init ./contracts/new-research --template research
agent-contracts init ./contracts/new-generic --template generic --json

Normalizes contract.yaml into a stable canonical order. Use --check to fail CI when formatting changes would be required.

agent-contracts format ./contracts/new-research
agent-contracts format ./contracts/new-research --check
agent-contracts format ./contracts/new-research --json

--json emits a versioned envelope with the stable shape:

{
 "format": "agent-contracts-cli",
 "formatVersion": 1,
 "command": "validate",
 "result": {}
}

The alpha contract model focuses on eleven concerns:

• identity
• intent
• inputs
• outputs
• constraints
• risk
• escalation
• approvals
• execution
• handoff
• provenance

Example:

id: research-web-v1
name: Web Research Contract
version: 0.1.0
intent:
 type: research
 description: Gather cited information on a defined topic and return a concise synthesis.
inputs:
 required:
 - research_query
outputs:
 expected:
 - structured_summary
 - citations
 - uncertainty_notes
constraints:
 max_latency_ms: 12000
 max_cost_usd: 0.25
 allow_external_web: true
risk:
 level: medium
 failure_mode: escalate_if_low_confidence
escalation:
 on_blocker: escalate_to_requester
 contact_role: requester
approvals:
 required: false
execution:
 retries: 1
 timeout_ms: 15000
handoff:
 delegation_allowed: true
 allowed_delegate_types:
 - researcher
 - analyst
provenance:
 source: human
 requested_by: requester

The schema lives at schemas/contract.schema.json.

The first validator is intentionally simple. It combines:

• explicit JSON Schema validation
• minimum required structure checks
• heuristic issue detection for weak delegation signals
• rule-based validation that is easy to extend without introducing a policy engine yet
• readable CLI output for human review

It does not yet implement advanced policy packs, trace validation, or runtime integration logic.

src/
 cli.ts
 explain.ts
 format.ts
 init.ts
 inspect.ts
 parser.ts
 schema-validator.ts
 types.ts
 validation-rules.ts
 validator.ts
test/
 *.test.ts
examples/
 research-contract/
 extraction-contract/
 change-plan-contract/
schemas/
 contract.schema.json
docs/
 vision.md
 architecture.md
 contract-spec.md
 roadmap.md

Agent Contracts is not trying to be:

• a runtime for coordinating agents
• a database-backed control plane
• a dashboard-heavy product
• a generic multi-agent framework
• a full approval workflow engine

Those may connect to Agent Contracts later. They are not the purpose of this alpha.

• docs/vision.md
• docs/architecture.md
• docs/contract-spec.md
• docs/roadmap.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md
• docs/release-checklist.md

MIT