Contract Schema

The contract schema defines an optional contract object that can be attached to a task. Contracts are designed for PM-to-agent workflows: they specify what must be produced, how it can be validated, and any constraints to follow.

Schema URL

https://brainfile.md/v1/contract.json

Used In

• Board Schema — task.contract

Overview

A contract is a structured, machine-friendly agreement attached to a task. It supports:

• Contract lifecycle status tracking (ready → in_progress → delivered → done / failed)
• Explicit deliverables (files, docs, tests, links, etc.)
• Optional validation commands that can be run by a PM or tool
• Optional implementation constraints and context

Required Fields

status

Type: stringEnum: draft, ready, in_progress, delivered, done, failedDescription: Contract lifecycle status

contract:
  status: ready

Optional Fields

deliverables

Type: array of deliverable objects Description: Specific artifacts that must be produced

contract:
  status: in_progress
  deliverables:
    - type: file
      path: src/rateLimiter.ts
      description: Token bucket implementation
    - type: test
      path: src/__tests__/rateLimiter.test.ts
      description: Unit tests

deliverable.type

Type: stringDescription: Deliverable category (tooling may use this for checks)

Common values include: file, test, docs, design, research.

deliverable.path

Type: stringDescription: Path or identifier for the deliverable

deliverable.description

Type: stringDescription: Optional human-readable description

validation

Type: objectDescription: Optional validation configuration

contract:
  status: delivered
  validation:
    commands:
      - npm test
      - npm run build

validation.commands

Type: array of stringDescription: Shell commands to run for automated verification

constraints

Type: array of stringDescription: Rules or constraints to follow during implementation

contract:
  status: in_progress
  constraints:
    - Make minimal changes
    - Keep backwards compatibility

context

Type: objectDescription: Optional additional context

contract:
  status: ready
  context:
    background: This work is part of the v1 protocol stabilization effort.
    relevantFiles:
      - protocol/v1/board.json
      - protocol/docs/types/board.md
    outOfScope:
      - Redesigning unrelated schemas

context.background

Type: stringDescription: Background notes for the agent

context.relevantFiles

Type: array of stringDescription: Additional file paths or code locations relevant to the contract

context.outOfScope

Type: array of stringDescription: Explicitly out-of-scope items

See Also

• Agent Contracts Guide
• Board Schema