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.

See also

For the formal field table and object structure, see Reference → Contract Schema.

Schema URL

https://brainfile.md/v2/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

Quick Reference — CLI Commands

Action	Command
Create task with contract	brainfile add --title "..." --with-contract --deliverable "file:path:desc"
Pick up contract	brainfile contract pickup -t task-123
Deliver work	brainfile contract deliver -t task-123
Validate delivery	brainfile contract validate -t task-123
List by status	brainfile list --contract ready

Required Fields

status

Type: stringEnum: ready, in_progress, delivered, done, failed, blockedDescription: Contract lifecycle status

• 🔵 ready — Available for pickup
• 🟡 in_progress — Agent is working
• 🟣 delivered — Submitted for review
• 🟢 done — Validated and approved
• 🔴 failed — Rejected, needs rework
• ⚠️ blocked — Waiting on external dependency

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                    # Optional — category for tooling
      path: src/rateLimiter.ts      # Required — file path or identifier
      description: Token bucket implementation  # Optional — human-readable
    - 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:                       # Run sequentially during validate
      - 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:                      # Not validated automatically
    - Make minimal changes
    - Keep backwards compatibility

outOfScope

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

contract:
  status: ready
  outOfScope:
    - Redesigning unrelated schemas

feedback

Type: stringDescription: PM feedback after failed validation. Used for rework guidance.

version

Type: integerDescription: Contract version number. Increment when amending a contract.

metrics

Type: objectDescription: Auto-tracked timing and rework data (managed by CLI).

contract:
  metrics:
    pickedUpAt: "2026-02-18T10:00:00Z"   # Auto-set on pickup
    deliveredAt: "2026-02-18T12:30:00Z"  # Auto-set on deliver
    duration: 9000                        # Seconds (auto-calculated)
    reworkCount: 0                        # Incremented on re-pickup

v2 migration note

In v2, context.background moved to task.description and context.relevantFiles moved to task.relatedFiles. The context object is deprecated.

See Also

• Agent Contracts Guide
• Board Schema