# OPENCLAW SYSTEM FOUNDATION MASTER

## Purpose

This file is the master continuity document for the OpenClaw multi-agent system.

It is meant to live **outside chat** and serve as the single reference point for future work so new chats do **not** need fragmented continuation summaries.

This document consolidates the important material from the beginning of the build through the current state. It removes fluff, repetition, and drift, but preserves the architecture, reasoning, rules, decisions, build order, agent structure, file layers, skill lessons, tests, and current next steps.

---

## How this file should be used

Use this file as the standing reference for future chats.

Future chats should:

- treat this as the foundation unless a newer authoritative file replaces it
- continue the build rather than restarting the project
- preserve the architectural rules already established here
- avoid guessing file contents when exact files matter
- use the real file set when available
- keep all work grounded in the official OpenClaw docs and official Google Search Central docs listed below

---

# 1. PROJECT NORTH STAR

We are building a **governed, token-efficient, OpenClaw-native multi-agent agency system**.

This is **not** a loose collection of agents.
It is a **governed operating system for agents**.

The system is being designed so that:

- **Marvin** is final authority
- **Victor** is the COO / Project Manager / Orchestrator
- specialist agents handle focused domain work
- each agent stays in its lane
- governance stays above the whole system
- the architecture respects OpenClaw’s real behavior
- token efficiency is a first-class design rule
- stronger models improve output, but do **not** rescue weak architecture

The larger goal is to create a digital agency team made of disciplined specialist agents that can eventually perform the work of a traditional agency with:

- better consistency
- cleaner delegation
- tighter review standards
- lower token waste
- clearer escalation
- scalable oversight

---

# 2. THE DEEPEST NON-NEGOTIABLE RULES

## 2.1 Token discipline comes first

This entire project is built with **TOKEN DISCIPLINE FIRST**.

Every token must earn its existence.

That means:

- injected/core files must stay lean
- anything that does not need to auto-load should not live in core
- heavy governance, strategy, notes, templates, and knowledge should be referenced, not injected
- weak architecture must **not** be “fixed” by piling on more prompt text
- Victor should **not** need giant corrective prompts every time he delegates work
- narrow reusable skills are better than bloated mixed-purpose skills

## 2.2 Governance comes before scale

The system is being built with rules first, scale second.

That means:

- clear authority
- clear scope boundaries
- clear escalation
- clear review standards
- clear monitoring
- clear intervention thresholds
- clear deprecation logic

## 2.3 OpenClaw architecture must lead the design

The project is being designed according to how OpenClaw actually works:

- per-agent workspaces
- per-agent sessions
- per-agent state
- per-agent auth boundaries
- lean injected files
- referenced files for deeper rules
- knowledge/reference files for expertise
- skills for reusable execution routines

## 2.4 Victor is the manager, not the mega-agent

Victor exists specifically to **prevent** the system from collapsing into one bloated generalist.

Victor is **not** supposed to do everyone’s specialist work.

Victor should:

- receive work
- classify work
- route work
- delegate work
- review work
- detect blockers
- escalate when needed
- preserve structure and token discipline

## 2.5 Specialists must stay disciplined

A specialist is not elite because it knows a lot.
A specialist is elite when it:

- stays in role
- resists drift
- produces consistent output
- is easy for Victor to review
- does not improvise outside its lane
- does not become a mini-system
- does not waste tokens

## 2.6 Global governance must stay global

System-wide governance belongs in the main workspace and should **not** be duplicated into every specialist workspace unless there is a very clear reason.

## 2.7 No guessing file contents

This is a critical ongoing rule.

When exact file contents matter, **DO NOT guess** what a file says.
Ask for the exact file.

This matters especially for Meredith and future specialist work.

## 2.8 Elite standard only

The target is **ELITE**, not “good enough.”

That means:

- repeated testing until behavior is correct
- no moving on from weak skills
- no lazy drift
- no hidden assumptions
- no vague architecture
- no tolerating role bleed because it “sort of works”

---

# 3. WHY THE SYSTEM IS BUILT THIS WAY

Victor was created because Marvin does **not** want one chaotic mega-agent trying to do everything.

The system is built this way because of these truths:

- injected/core files cost tokens every session
- repeating the same governance rules in every workspace wastes tokens
- strong architecture beats repeated hard-prompting
- specialists should specialize
- governance should be centralized
- referenced documents are better than bloated always-loaded instructions
- the system should be testable, disciplined, safe, reviewable, and scalable

The system exists to behave like a real organization with oversight, not like one assistant improvising everything.

---

# 4. AUTHORITY AND OPERATING STRUCTURE

## 4.1 Authority hierarchy

- **Marvin** = final authority
- **Victor** = operational authority / orchestrator / reviewer / escalation gate
- **Specialist agents** = scoped executors inside their own domains

## 4.2 Intended operating pattern

The intended system flow is:

1. Marvin gives direction to Victor
2. Victor interprets the task
3. Victor decides whether to handle or delegate
4. Victor routes work to the correct specialist
5. Specialist returns scoped output
6. Victor reviews output
7. Victor routes the next step or escalates if needed

That is the core machine.

## 4.3 What makes a build decision correct

A build decision is correct if it:

- reduces recurring token waste
- respects OpenClaw’s real architecture
- strengthens role boundaries
- makes outputs easier for Victor to review
- improves consistency
- avoids role bleed
- scales to more agents later
- reduces dependence on giant prompts

## 4.4 What we are explicitly not doing

We are **not**:

- stuffing everything into core files
- duplicating the full governance stack into every workspace
- making Victor the all-purpose mega-agent
- letting specialists wander into unrelated roles
- confusing knowledge files with skills
- building around stronger models as a crutch
- accepting “good enough” when the target is elite behavior

---

# 5. GLOBAL GOVERNANCE LAYER

The global governance layer is the top law / oversight layer for the system.

These are global non-core governance / oversight files and should remain global:

- `SYSTEM_CONSTITUTION.md`
- `RATE_LIMITS.md`
- `DEPRECATION_PROTOCOL.md`
- `ESCALATION.md`
- `SUSPENSION.md`
- `AGENT_SCOPE_REGISTRY.md`
- `AGENT_PERFORMANCE_SCORING.md`
- `AUTOMATED_INTERVENTION_PROTOCOL.md`
- `COST_MONITOR.md`
- `DECISION_LOG.md`
- `QUARTERLY_AGENT_REVIEW.md`
- `RISK_REGISTER.md`
- `SYSTEM_HEALTH_SCORE.md`
- `SYSTEM_PROJECTION_MODEL.md`
- `EXECUTIVE_REPORT.md`
- `ROADMAP.md`
- `SCENARIO_SIMULATION_ENGINE.md`

Other governance/support files discussed in the project include:

- `EXECUTION_PROTOCOL.md`
- `MEMORY_POLICY.md`
- `CHANGE_MANAGEMENT.md`
- `PERMISSIONS_MATRIX.md`
- `PERFORMANCE_EVALUATION.md`

## 5.1 Governance purpose

These files exist to:

- keep authority centralized
- keep standards consistent
- avoid repeating heavy governance in each workspace
- preserve token efficiency
- support scaling to more agents later
- provide review, intervention, scoring, logging, cost tracking, and deprecation logic

## 5.2 Governance pattern already established

The operating pattern that emerged is:

- **global governance** = system law
- **agent core files** = local runtime identity / behavior
- **referenced files** = role operating rules
- **knowledge files** = expertise layer
- **skills** = reusable execution routines

This pattern is one of the most important architectural outcomes of the project.

---

# 6. VICTOR

## 6.1 Why Victor exists

Victor was created because Marvin does **not** want a single bloated mega-agent trying to do everything.

Victor exists to be the operational brain of the system:

- orchestrator
- COO / Project Manager
- quality controller
- escalation point
- structure enforcer

Victor manages the system so it behaves like an organization with oversight instead of one chaotic assistant.

## 6.2 Victor’s role

Victor’s responsibilities are:

- coordinate specialists
- classify incoming work
- decide whether to handle or delegate
- review outputs before acceptance
- challenge weak reasoning
- preserve structure
- protect token efficiency
- detect blockers
- escalate when needed

## 6.3 What Victor should not do

Victor should **not**:

- do all specialist work himself
- silently expand scope
- silently restructure systems
- silently make pricing decisions
- silently make client commitments
- become a one-man department

## 6.4 Victor’s status

Victor is considered operational enough to manage specialists.

Victor already has:

- lean core files
- role identity
- scope
- delegation rules
- escalation boundaries
- review standards

Victor is the manager of the system, not the specialist for every domain.

---

# 7. STANDARD SPECIALIST AGENT ARCHITECTURE

Each specialist agent should follow the same architectural pattern, but **not** as a duplicate of the full system.

## 7.1 Lean core files

Each specialist gets lean versions of:

- `AGENTS.md`
- `SOUL.md`
- `TOOLS.md`
- `IDENTITY.md`
- `USER.md`
- `HEARTBEAT.md`

These must stay lean because they affect recurring context cost.

## 7.2 Role-specific referenced files

These hold non-core operating rules such as:

- scope
- deliverable standards
- escalation boundaries
- review expectations

## 7.3 Knowledge/reference layer

This is the expertise layer.

This is where the system stores:

- trusted source material
- practical frameworks
- best practices
- structured notes
- templates
- source-backed summaries

This material should **not** bloat the core files.

## 7.4 Skills

Skills are reusable workflows.

They are **not** giant brains.
They are **not** generic assistant behavior.

A skill should do one job clearly and repeatedly.

## 7.5 Knowledge before over-automation

Before trying to make agents do everything, the right move is to build their expertise correctly using:

- trusted sources
- structured notes
- reusable templates
- focused skills

That is how an agent becomes strong without becoming bloated.

---

# 8. PLANNED AGENCY STRUCTURE

The intended long-term agency roster includes:

- Agency Owner: Marvin
- Victor: COO / Project Manager / Orchestrator
- Sales Scout Agent
- Marketing Director Agent
- SEO & Search Visibility Specialist Agent
- Social Media Specialist Agent
- Content Creator Agent
- Graphic Designer Agent
- Data Analyst Agent
- Senior Web Developer Agent
- Account Manager Agent

## 8.1 Build order logic

The build order established so far is:

1. Victor first
2. Meredith / SEO second
3. Senior Web Developer after Meredith is stable

---

## 25.2 Critical working rule for revisions

When updating a skill, **ALWAYS provide the full updated `SKILL.md` file**, not partial snippets.

This preference was explicitly established.

**LEAN CORE. GLOBAL GOVERNANCE. STRICT ROLES. KNOWLEDGE IN THE RIGHT LAYER. NARROW SKILLS. ELITE STANDARDS.**