Getting Started with Contracts

Brainfile isn't just for human-to-human task management. Its most powerful feature is Agent Coordination: the ability for one AI assistant (acting as a PM) to assign structured work to another AI assistant (the worker).

What are Contracts?

A Contract is an optional set of rules attached to a task. It defines exactly what needs to be done, how it will be verified, and what constraints must be followed.

When an AI agent sees a task with a contract, it doesn't just "try its best"—it follows a formal lifecycle to ensure the work meets your specifications.

Why use them?

• Reliability: Agents know exactly what deliverables are expected.
• Automation: Validation commands can automatically check work before it's marked "Done".
• Delegation: You (or your primary AI assistant) can delegate complex sub-tasks to other specialized agents with high confidence.

A Simple Example

Imagine you want an agent to create a new React component. Instead of a vague task, you create a contract:

---
id: task-101
title: "Create UserProfile component"
contract:
  status: ready
  deliverables:
    - type: file
      path: src/components/UserProfile.tsx
      description: Main component file
    - type: test
      path: src/components/UserProfile.test.tsx
  validation:
    commands:
      - npm test src/components/UserProfile.test.tsx
  constraints:
    - Use Tailwind CSS for styling
    - Must be a functional component
---

The Coordination Lifecycle

1. Ready (ready): The contract is defined and available for a worker agent to pick up.
2. In Progress (in_progress): A worker agent has claimed the task and started work.
3. Delivered (delivered): The worker has finished and is waiting for PM validation.
4. Done (done): The work has been validated and accepted.
5. Failed (failed): Validation failed — feedback is provided for rework.
6. Blocked (blocked): The agent is stuck on an external dependency and needs PM help.

Try it now

You can add a contract to any task using the CLI:

brainfile add --title "Refactor Auth" \
  --with-contract \
  --deliverable "file:src/auth.ts:Auth refactor" \
  --validation "npm test"

Next, learn about Complex Agent Workflows or see the full Contract Schema Reference.