Config Layers

Reeve's 4-layer config system resolves agent context files (AGENTS.md, SOUL.md, TOOLS.md, etc.) by merging them from bottom to top. Each layer can replace, append to, or extend the layer below.

Layer 1: Universal

Path: reeve/config/universal/
Managed by: The Reeve gateway (ships with the product)

This is the operating system layer. Every agent inherits it automatically. Contains:

• AGENTS.md — Rooster Rules, safety protocols, date/time awareness, formatting guidelines
• SOUL.md — Base Reeve personality
• Role-specific templates in templates/roles/

You cannot override this layer — it's embedded in the gateway. But higher layers can extend or replace specific content.

Layer 2: Org/Team

Path: Derived from workspace path in cloud mode (/data/tenants/{team}/org/)
Managed by: Team admins

The org layer contains shared knowledge for a team or organization:

• Company context (what the company does, products, team)
• Shared tool configurations
• Team coding standards or communication guidelines
• Domain knowledge (product specs, customer personas)

Org auto-detection

In cloud mode, the org path is derived automatically from the workspace path:

Workspace: /data/tenants/mindfortress/agents/marketing/workspace
     → Org: /data/tenants/mindfortress/org/

In local mode, set the org path in reeve.json:

{
  "layers": {
    "org": "/path/to/org/directory"
  }
}

Layer 3: Individual

Path: ~/.reeve/user/ (default)
Managed by: Individual users

Personal preferences that apply across all agents for this user:

• Writing style preferences
• Preferred tools and workflows
• Personal context (timezone, communication preferences)

Configure the path in reeve.json:

{
  "layers": {
    "individual": "/path/to/personal/config"
  }
}

Individual-only files

Some files only come from the individual layer — they're never inherited from org:

• USER.md — Personal user context
• BOOTSTRAP.md — User-specific bootstrap instructions

This prevents org admins from overriding personal preferences.

Layer 4: Workspace

Path: The agent's configured workspace directory
Managed by: The agent itself or the user

The highest-priority layer. Agent-specific instructions that override everything:

• Domain-specific AGENTS.md (marketing rules, engineering standards)
• Custom SOUL.md personality overrides
• Specialized TOOLS.md with agent-specific tool documentation

Merge Strategies

Each file type has a merge strategy that determines how layers combine:

Append strategy

Content from all layers is joined with \n\n---\n\n:

<!-- From Universal -->
## Safety Rules
Never delete production data...

---

<!-- From Org -->
## Company Context
MindFortress builds AI agent platforms...

---

<!-- From Workspace -->
## Marketing Instructions
Focus on B2B SaaS messaging...

Replace strategy

Only the highest-priority layer's content is used. If workspace has IDENTITY.md, the org and universal versions are ignored entirely.

Merge Implementation

The merge logic lives in config/layers/merge.js:

import { resolveFileMergeStrategy } from './types.js';

export function mergeBootstrapFile(base, override) {
  const strategy = resolveFileMergeStrategy(base.name);

  switch (strategy) {
    case 'replace':
      return { ...override };
    case 'append': {
      const merged = [base.content, override.content]
        .filter(Boolean)
        .join('\n\n---\n\n');
      return { name: override.name, path: override.path, content: merged };
    }
    case 'extend':
      // Same as append but semantically different
      return { /* merged content */ };
  }
}

The full merge runs bottom-up across all 4 layers:

// bootstrap-files.js
const universalFiles = loadUniversalFiles();
const orgFiles = loadOrgFiles(orgPath);
const individualFiles = loadIndividualFiles(userPath);
const workspaceFiles = loadWorkspaceFiles(workspacePath);

const merged = mergeBootstrapFiles(
  mergeBootstrapFiles(
    mergeBootstrapFiles(universalFiles, orgFiles),
    individualFiles
  ),
  workspaceFiles
);