What is SPACE.md and how does it work?

SPACE.md is a plain text markdown file in ~/space/SPACE.md that tells autonomous AI agents what to focus on. Every agent reads it on every run. It contains your mission, current priorities, and constraints in plain English. One page is enough.

How do you write a good SPACE.md file?

Be specific (name files and directories, not vague goals), say what to avoid (agents work on what you don't protect), give context instead of step-by-step instructions, and update it when priorities change. Write what you'd tell a new contractor on their first day.

The SPACE.md protocol: how to direct your AI swarm

Every spacebrr agent reads SPACE.md on every run. This file is the difference between agents that do useful work and agents that wander.

What it is

One markdown file in ~/space/SPACE.md. Tells the agent what you’re working on, what to focus on, what to avoid, what “done” looks like. Write it in plain English.

Each run starts cold. SPACE.md is the stable context that survives across sessions.

What it isn’t

Not a task list. Not a backlog. Not a product requirements doc. SPACE.md is strategy. If it’s more than one page, it’s doing too much.

A minimal example

Pre-product founder:

# SPACE

## What this is
Validating B2B demand for AI-assisted contract review. Target: solo practitioners at firms under 10 people.

## Current focus
10 discovery calls booked this week.
- Synthesize 6 customer interviews → extract top 3 pain points
- Map competitive landscape (Clio, PracticePanther, ContractPodAi)
- Draft cold outreach sequence for solo practitioners

## What to avoid
No building until 10 conversations are done.

Engineering founder:

# SPACE

## What this is
B2B invoicing API. Python + FastAPI. Postgres.

## Current focus
Get payment-related paths to 100% test coverage. No new features until coverage is there.

## What to avoid
Don't touch `/api/legacy/`. Migration in progress separately.

What makes a good one

Be specific. “Improve code quality” produces generic refactors. “Write tests for all functions in /api/payments/ that have no test file” produces targeted commits.

Say what to avoid. Agents work on what you don’t protect.

Give context, not instructions. Write what you’d tell a new contractor on their first day.

Update it. Stale SPACE.md produces stale commits.

What changes at each stage

Pre-product: entirely research and conversations. Agents become research assistants.

Early product: the moving target. What’s highest priority, what to avoid while architecture is unsettled.

Live product: reliability and backlog debt. Test coverage, dead code, the refactors that accumulated during the sprint.

The file format stays the same. The content changes. That’s the protocol.