# Brainfile Protocol

> An open protocol for agent-to-agent task coordination. File-system native.

## Quick Facts

- Format: YAML frontmatter + Markdown, one file per task
- Structure: `.brainfile/brainfile.md` (config), `.brainfile/board/` (active tasks), `.brainfile/logs/` (completed history with `ledger.jsonl`)
- Document types: task, epic, adr (enforced by strict mode)
- License: MIT
- Schema: https://brainfile.md/v2

## Directory Structure

```
.brainfile/
├── brainfile.md        # Board config (columns, types, rules)
├── board/              # Active task files
│   ├── task-1.md
│   ├── epic-1.md
│   └── adr-1.md
└── logs/               # Completed history
    ├── ledger.jsonl    # Primary completion record
    └── task-2.md       # (legacy) Archived task
```

## Task File Format

Each task is an individual markdown file in `.brainfile/board/`:

```yaml
---
id: task-1
type: task
title: Implement rate limiting
column: in-progress
priority: high
assignee: codex
tags: [backend, api]
relatedFiles:
  - src/api/gateway.ts
subtasks:
  - id: sub-1
    title: Write implementation
    completed: true
  - id: sub-2
    title: Add tests
    completed: false
contract:
  status: in_progress
  deliverables:
    - path: src/rateLimiter.ts
    - path: src/__tests__/rateLimiter.test.ts
  validation:
    commands:
      - npm test -- rateLimiter
      - npm run build
  constraints:
    - Use token bucket algorithm
---

## Description

Detailed requirements and context go here.
```

## Core Fields

### Task Level
- `id` (required): Unique identifier (e.g., "task-1", "epic-2", "adr-3")
- `type` (required in strict mode): task, epic, or adr
- `title` (required): Task name
- `column` (required): Column ID from board config
- `description`: Short description
- `priority`: low, medium, high, critical
- `tags`: Array of strings
- `assignee`: Person or agent assigned
- `parentId`: Parent document ID (for epics)
- `relatedFiles`: Array of file paths relevant to the task
- `subtasks`: Array of {id, title, completed} objects
- `contract`: Optional agent contract (see Contracts section)

### Board Config (`.brainfile/brainfile.md`)
- `title`: Project name
- `columns` (required): Array of {id, title} objects
- `types`: Document type definitions with allowed columns
- `rules`: Project rules (always, never, prefer, context categories)

## CLI Commands

```
brainfile list                                    # all tasks
brainfile list -c todo                            # filter by column
brainfile list -t bug                             # filter by tag
brainfile list --contract ready                   # filter by contract status
brainfile show --task task-1                      # view task details
brainfile add --title "Task name"                 # create task
brainfile add --title "Fix bug" -p high --tags bug  # with metadata
brainfile move --task task-1 --column in-progress # move between columns
brainfile complete --task task-1                  # done (appends to ledger.jsonl and archives)
brainfile patch --task task-1 -p critical         # update fields
brainfile subtask --add "Write tests" --task task-1   # add subtask
brainfile subtask --toggle sub-1 --task task-1    # toggle completion
brainfile archive --task task-1                   # archive task
brainfile delete --task task-1                    # permanently remove
```

## MCP Tools

If connected via MCP (`.mcp.json`), these tools are available:

```
list_tasks          List/filter tasks by column, tag, priority, contract status
get_task            Get full task details by ID
search_tasks        Search by query, assignee, priority
add_task            Create a task (supports with_contract, deliverables, constraints)
move_task           Move task to a different column
patch_task          Update specific fields
delete_task         Remove a task
add_subtask         Add subtask to a task
toggle_subtask      Mark subtask complete/incomplete
delete_subtask      Remove a subtask
bulk_set_subtasks   Set multiple subtasks complete/incomplete at once
complete_all_subtasks  Mark all subtasks in a task as done
archive_task        Archive to local, GitHub Issues, or Linear
restore_task        Restore archived task
bulk_move_tasks     Move multiple tasks at once
bulk_patch_tasks    Patch multiple tasks at once
bulk_delete_tasks   Delete multiple tasks
bulk_archive_tasks  Archive multiple tasks
contract_pickup     Claim a contract (sets status to in_progress)
contract_deliver    Mark contract as delivered
contract_validate   Check deliverables and run validation commands
attach_contract     Add contract to existing task
list_rules          List project rules
add_rule            Add a project rule
delete_rule         Remove a project rule
```

## Contracts

Contracts formalize what an agent must deliver and how to verify it.

### Lifecycle
```
ready → in_progress → delivered → done
                  ↘               ↗
                   failed → ready (rework)
```

### Creating a Contract
```
brainfile add --title "Add auth" \
  --assignee codex \
  --with-contract \
  --deliverable "file:src/auth.ts:Implementation" \
  --deliverable "test:src/__tests__/auth.test.ts:Tests" \
  --validation "npm test -- auth" \
  --constraint "Use OAuth 2.0 PKCE flow"
```

### Agent Workflow
1. `contract_pickup` or `brainfile contract pickup --task ID` — claim it
2. Implement the deliverables
3. `contract_deliver` or `brainfile contract deliver --task ID` — mark delivered
4. PM validates: `contract_validate` or `brainfile contract validate --task ID`

### Contract Fields
- `status`: ready | in_progress | delivered | done | failed | blocked
- `deliverables`: Array of {path, description} — files to produce
- `validation.commands`: Commands to verify deliverables
- `constraints`: Implementation rules
- `feedback`: Rework guidance (added after failed validation)

## Rules System

Projects define rules in the board config:

```yaml
rules:
  always:
    - id: 1
      rule: write tests for all new features
  never:
    - id: 1
      rule: commit directly to main
  prefer:
    - id: 1
      rule: functional components over class components
  context:
    - id: 1
      rule: this is a TypeScript monorepo
```

Rules are injected into agent context automatically via MCP.

## Best Practices

- Use CLI or MCP tools to manage tasks — don't edit files manually unless necessary
- Preserve all task IDs (never regenerate them)
- Keep relatedFiles updated so agents have context
- Include validation commands in contracts for automated verification
- Complete tasks with `brainfile complete` (appends to `ledger.jsonl` and archives)

## References

- Bootstrap: https://brainfile.md/llms-install.txt
- Full reference: https://brainfile.md/llms-full.txt
- Specification: https://brainfile.md/reference/protocol
- GitHub: https://github.com/brainfile