Base Schema

The base schema defines fields that are shared across all brainfile types.

Inherited by All Types

The base schema is the foundation — every brainfile type (Board, Task, Epic, ADR) inherits these fields. You don't need to declare type: board in most cases, as it's the default.

Schema URL

https://brainfile.md/v2/base.json

Overview

The base schema establishes the foundational structure for the Brainfile protocol:

• Common metadata fields (title, schema, version)
• AI agent instructions
• Project rules
• Reusable definitions (timestamps, rules)

Required Fields

title

Type: stringMin Length: 1 Description: Human-readable title for the brainfile

title: My Project Board              # Required — must be non-empty

Optional Fields

type

Type: stringDefault: boardDescription: Type identifier

type: board                           # Optional — defaults to "board"

schema

Type: string (URI) Description: Reference to the specific schema for validation

schema: https://brainfile.md/v2/board.json  # Optional — enables schema validation

protocolVersion

Type: string (semver pattern) Pattern: ^[0-9]+\.[0-9]+\.[0-9]+$Default: 2.0.0Description: Version of the Brainfile protocol

protocolVersion: 2.0.0               # Optional — defaults to 2.0.0

agent

Type: objectDescription: Instructions for AI agents interacting with the brainfile

agent:                              # Optional — AI agent configuration
  instructions:                     # Optional — behavioral rules
    - Modify only the YAML frontmatter
    - Preserve all IDs
  llmNotes: This project uses TypeScript and React  # Optional — free-form context
  tools:                            # Optional — available CLI tools
    brainfile:
      prefer: true
      commands:
        - move --task <id> --column <id>
        - add --title "..." --column <id>

agent.instructions

Type: array of stringDescription: List of specific instructions for AI behavior

agent.llmNotes

Type: stringDescription: Free-form notes about project context and preferences

agent.tools

Type: objectDescription: CLI tools available for agents to use

rules

Type: objectDescription: Project rules organized by category

rules:                              # Optional — project rules
  always:                           # Optional — must always follow
    - id: 1
      rule: test all features before moving to done
  never:                            # Optional — must never violate
    - id: 1
      rule: skip code review
  prefer:                           # Optional — preferred approaches
    - id: 1
      rule: small focused tasks over large epics
  context:                          # Optional — contextual info
    - id: 1
      rule: this is a TypeScript project

Rule Categories

Category	Purpose	Example
always	Must always follow	Always write tests
never	Must never violate	Never skip code review
prefer	Preferred approaches	Prefer functional style
context	Contextual info	This is a React project

Reusable Definitions

timestamp

Type: string (ISO 8601) Format: date-timeExamples:

• 2025-11-24T10:30:00Z
• 2025-11-24T14:22:00-08:00

Used by type-specific schemas for createdAt and updatedAt fields.

rule

Type: objectRequired: id, ruleStructure:

{
  "id": 1,
  "rule": "Rule text here"
}

Example

---
type: board
schema: https://brainfile.md/v2/board.json
title: Production Project
protocolVersion: 2.0.0
agent:
  instructions:
    - Modify only YAML frontmatter
    - Preserve all IDs
  llmNotes: React + TypeScript + Tailwind CSS
  tools:
    brainfile:
      prefer: true
rules:
  always:
    - id: 1
      rule: write tests
  never:
    - id: 1
      rule: skip reviews
columns: [...]
---

See Also

• Board Schema — Board configuration (columns, types, rules)
• Task Schema — All schema types including Task, Epic, ADR
• Contract Schema — Contract object for PM-to-agent workflows