brainfile

An open protocol for agent-to-agent task coordination.

Human-in-the-loop compatible. File-system native. MIT licensed.

---
title: My Project
columns:
  - id: todo
    title: To Do
  - id: in-progress
    title: In Progress
types:
  task: { idPrefix: task, completable: true }
  epic: { idPrefix: epic, completable: true }
  adr: { idPrefix: adr, completable: false }
---
---
id: task-12
title: Add rate limiting to API gateway
column: in-progress
assignee: codex
priority: high
parentId: epic-3
tags: [backend, performance]
relatedFiles:
  - src/api/gateway.ts
subtasks:
  - id: task-12-1
    title: Write unit tests
    completed: false
---
# added to task-12 frontmatter
contract:
  status: in_progress
  deliverables:
    - path: src/middleware/rateLimiter.ts
      description: Token bucket implementation
    - path: src/__tests__/rateLimiter.test.ts
      description: Unit tests
  validation:
    commands:
      - npm test -- rateLimiter
      - npm run build
  constraints:
    - Token bucket algorithm
    - Non-blocking async implementation
$ brainfile contract validate -t task-12
 Checking deliverables...
   src/middleware/rateLimiter.ts exists
   src/__tests__/rateLimiter.test.ts exists
 Running validation commands...
   npm test -- rateLimiter (exit 0)
   npm run build (exit 0)

✓ Contract validated. Status: done
readyin_progressdelivereddoneblockedfailedContract created, waiting for agent pickupAgent actively working on deliverablesWork complete, awaiting validationValidated and approvedAgent stuck on external dependencyValidation failed, needs rework
01define

Write a contract as a markdown file in your repo.

02delegate

An agent picks it up, implements, and delivers.

03validate

Automated commands verify the deliverables. Done.

Why files?

Tasks live in your repo. Git history is your audit trail. No database, no API, no vendor lock-in.

Why contracts?

Informal "please do X" breaks down at scale. Structured deliverables and validation commands make agent output verifiable.

Why a protocol?

Tools change. Claude, Cursor, Copilot, the next thing. A protocol survives all of them.

Integrations are optional adapters. The protocol comes first.

terminal
$ npm install -g @brainfile/cli

$ brainfile init
✓ Created .brainfile/brainfile.md

$ brainfile add -c todo --title "My first task" --with-contract \
  --deliverable "file:src/feature.ts:Implementation" \
  --validation "npm test"
✓ Created task-1

$ brainfile contract pickup -t task-1
✓ Contract status: in_progress

$ brainfile contract deliver -t task-1
✓ Contract status: delivered
Full Quick Start guide