What is REEF?

REEF — the declared local digital habitat.

The organism knows its territory before it dives.

REACH reaches into systems. OCTO coordinates the arms. TRACE records everything that ran. But none of them knew — until REEF — what territory they were operating in. REEF is the declaration that comes first: the named, bounded habitat that REACH, OCTO, and TRACE live inside.

The octopus does not explore a random ocean floor. It knows its reef — every crevice, every source, every current. That knowledge is not discovered at runtime. It is declared.

---

Where REEF Fits

REEF     →  declares the habitat — what sources exist, where things live
             read once, at startup, before any arm moves

REACH    →  reaches into declared sources, surfaces findings
             arms reference sources named in the reef

OCTO     →  coordinates arms across the declared habitat
             workflows reference reef sources by dot-path

TRACE    →  records everything that happened, immutably
             the trace file path is declared in the reef

reef-mcp →  gives Claude intelligence over the reef
             reads the habitat, executes arms, writes trace events

Each does one thing. REEF is the substrate all four sit on.

---

Declared, Not Discovered

Every AI tool and automation framework built before REEF shares a hidden assumption: the environment is unknown until the agent reaches into it. The inbox is discovered on the first call. The database is found when the query runs. The territory is explored fresh each session.

REEF inverts this. The habitat is declared once — in a .reef file — before any arm moves. Sources are named. Paths are fixed. Nodes are enumerated. When REACH compiles an arm for outlook.inbox, it is not guessing that Outlook exists. The reef says so.

Discovered (the old model):
  Agent → reaches blindly → finds what exists → acts

Declared (REEF):
  .reef declares the habitat
  OCTO knows the territory
  Arms reach into known sources
  TRACE records against a known path

The difference is not performance. It is reliability and composability. An arm that references outlook.inbox in a reef that declares outlook.inbox is verifiable at declaration time, not only at runtime.

---

The .reef File

The habitat is declared in a single file that lives alongside .reach and .octo files.

morning.reef          ← the habitat
morning.octo          ← what runs in it
reach-trace.ndjson    ← what got recorded

A minimal reef:

reef my-habitat

paths
  trace   ./reach-trace.ndjson
  arms    ./arms

sources
  - outlook.inbox
  - outlook.calendar
  - git.commits

A fuller reef — work machine with SQL and Planner:

reef work-habitat

paths
  trace     C:\workspace\reach-trace.ndjson
  arms      C:\workspace\trace\arms
  workspace C:\workspace
  reach     C:\workspace\reach

sources
  - outlook.inbox
  - outlook.calendar
  - outlook.draft
  - teams.planner
  - teams.transcript
  - git.commits
  - sql.staging
  - sql.production
  - browser.internal

The .reef file is the configuration layer the ecosystem was always missing. Arm paths, trace paths, source declarations — previously scattered across env vars and repeated in every .octo file. The reef declares them once. Everything else references them.

---

The Relationship to .octo

.reef and .octo are complementary specs at different layers. The distinction is precise:

	.reef	.octo
Declares	What exists	What runs
Read	Once, at startup	On demand
Contains	Sources, paths, nodes	Arms, surface, close
Scope	The habitat	A workflow
Changes when	A new source joins	A workflow is updated
Author	The practitioner	The practitioner

An .octo file references sources by dot-path (outlook.inbox, git.commits). The reef is where those dot-paths resolve to real systems. The workflow doesn't need to know how to find Outlook. The reef knows.

---

The OCTOPUS

REEF is the habitat of the OCTOPUS — the unified organism the ecosystem composes into:

OCTOPUS
  ├── REACH    arms — reaching into reef sources
  ├── OCTO     brain — coordinating across the reef
  └── TRACE    nervous system — recording everything that happened

REEF             the habitat the organism lives in

Name the habitat. The organism knows its territory. The practice becomes portable.

---

Current State

Implemented and tested. reef-mcp reads .reef at startup — env var wins if set, .reef is the fallback, so adopting it never breaks an existing env-var setup. Six tools, including check_habitat, which reports exactly what's resolved and where each value came from. Four real arms exist and run against it (MORNING-BRIEF, REPO-STATUS, MARKET-BRIEF, FLARE). Every arm now declares a MODE (READ or ACT) in its own header — write_arm won't save one without it, and run_arm structurally refuses to execute an ACT arm without an explicit second, confirmed call.

sources — the trust-boundary declaration — is parsed and reported, not yet enforced. That's the one piece of this page's original vision still ahead of the implementation.

---

Next

• File Format → — the .reef syntax, real and working
• The MCP Server → — reef-mcp's six tools, and the MODE/TIER gate

GitHub: semanticintent