⛩️ ShogunOS — Future Vault Architecture

Proposed structure · Stress-tested against open source · Pat review draft

🏗️ Structure
🤖 Agent Matrix
📥 Triage Rules
🔄 Data Flows
🔀 Migration Map
🌐 Machine Sync
Directory Tree
Six top-level directories. Self-documenting names. Every file has exactly one home.

📜 governance/ ~1 MB · Read Every Session

governance/ ← was System_OS
SYSTEM.md ← the constitution
DECISIONS.md ← architecture decision records
SYSTEM_LESSONS.md ← hard-won rules (SL-001+)
THE_AGENT_DOCTRINE.md ← bot bible
CONTEXT_FILE_STANDARD.md
frameworks/ ← architecture-v2, change-protocol-v2
worldview/ ← this project's artifacts
metrics/ ← system-wide KPIs
integrations/ ← Linear, M365, Slack config
Access Rule: All agents read. Only APEX + Pat can modify. Changes require ADR in DECISIONS.md.

🧠 knowledge/ ~475 MB · Query On Demand

knowledge/ ← was System_Context
people/ ← 1,902 CRM contacts
orgs/ ← 112 org profiles
transcripts/ ← 192 meeting transcripts
digests/ ← email, calendar, finance, legal
reference/ ← SOPs, brand guide, templates
pat/ ← USER_PROFILE, PERSONAL_CONTEXT
extraction-db/ ← 74MB SQLite knowledge graph
Access Rule: All agents read via world-model API (:8081). Network SME + Librarian write. Never loaded into context directly — always queried.

🤖 agents/ Per-Agent Workspaces

agents/
shogun/ ← was Shogun_OS
SOUL.md, CLAUDE.md, AGENTS.md, USER.md
MEMORY.md, HEARTBEAT.md
memory/ ← daily logs, captures
skills/ ← lessons, protocol, etc.
entities/ ← DxD, HoldCo, Montauk, Personal
forge/ ← was Forge_OS
SOUL.md, CLAUDE.md
FORGE_DOCTRINE.md ← single authoritative copy
architecture/ ← ADRs, designs
projects/ ← agent-internal only
sentinel/
identity.md, config/
Access Rule: Each agent has read-write to their own dir. Read-only to other agents' dirs. New agent = mkdir agents/<name>/ + SOUL.md + CLAUDE.md.

📋 projects/ Cross-Agent Work

projects/
orcrist-capture/ ← Shogun + Forge + external
README.md ← owner, agents, status
plan.md
decisions/
artifacts/
worldview-architecture/ ← this project
unified-data-plan/
seam-2-development/
Triage Rule: Multi-agent or Pat-owned work → projects/. Single-agent internal work → agents/<name>/projects/. Every project has a README.md with owner + participants.

⚙️ ops/ Shared Infrastructure

ops/
mailbox/ ← inter-agent communication
shogun/inbox/
forge/inbox/
sentinel/inbox/
briefs/ ← generated HTML briefings
staging/ ← NEW: replaces Dropbox staging
from-pat/ ← Pat drops files for agent review
from-external/ ← email, web, cloud LLMs
processed/ ← after triage
logs/ ← all agent logs (with rotation)
scripts/ ← automation, mailbox_send.sh, etc.
Access Rule: Shared read-write. Mailbox follows IAP (YAML frontmatter required). Logs auto-rotated by Forge. Staging triaged by Shogun daily.

🗄️ archive/ Historical

archive/
2026-04-10-cockpit-recon/
retired-agents/
legacy-infra/
pre-migration/
Rule: Date-prefixed dirs. Read-only after creation. Never deleted. Git-tracked for audit trail.
Root Files: CLAUDE.md (neutral agent router — NOT agent-specific), README.md (human onboarding), .gitignore, .obsidian/
Agent Access Matrix
Who can read/write where. Every agent's scope is explicit.
⛩️ Shogun
Chief of Staff · Triage · Coordination · Pat's interface

Workspace

  • agents/shogun/ read-write
  • governance/ read
  • knowledge/ read (via API)
  • projects/ read-write
  • ops/ read-write
  • agents/*/ read (other agents)

Responsibilities

  • Triage all inbound from Pat
  • Route work to correct agent via mailbox
  • Manage ops/staging/ daily triage
  • Generate morning + evening briefs
  • Maintain project README.md status
  • Capture tasks from Slack → memory/captures/
🔨 Forge
CPTO · Architecture · Engineering · SRE · Deploy

Workspace

  • agents/forge/ read-write
  • governance/ read + propose
  • knowledge/ read
  • projects/ read-write
  • ops/ read-write (infra owner)
  • agents/*/ read (architecture review)

Responsibilities

  • All code, infra, deploy, config work
  • Maintain ops/scripts/ and log rotation
  • Execute vault restructures (like this one)
  • Manage LaunchAgents, Docker, services
  • Architecture decisions → agents/forge/architecture/
  • Git repo health, sync, backups
👁️ Sentinel
Behavioral Monitor · Compliance · Drift Detection

Workspace

  • agents/sentinel/ read-write
  • governance/ read (audit source)
  • ops/logs/ read (audit target)
  • agents/*/ read (compliance check)

Responsibilities

  • 3x daily scheduled audits
  • Real-time constraint violation alerts
  • Check agents against governance/ doctrine
  • Write checkpoint reviews → ops/logs/
🧭 APEX
Architect · Strategy · Analysis

Workspace

  • governance/ read-write (governance authority)
  • knowledge/ read
  • projects/ read-write

Responsibilities

  • Governance file authority (with Pat)
  • Architecture decisions + reviews
  • Strategic analysis when invoked
👤 Pat
CEO · Commander · Final Authority

Workspace

  • everything/ full access

Interaction Points

  • Slack → Shogun (primary interface)
  • ops/staging/from-pat/ (file drops)
  • Obsidian vault (direct edits anywhere)
  • Briefs served at engine.tail…/briefs/
  • Approves governance changes
  • Approves L1-L2 Linear tickets
🆕 New Agent Template
Onboarding in 3 steps

To Add a New Agent

  • mkdir agents/<name>/
  • Create SOUL.md (identity + principles)
  • Create CLAUDE.md (workspace orientation)
  • Optional: memory/, skills/, projects/
  • Add to governance/ roster if permanent
File Triage Decision Tree
Where does a new file go? Follow the decision tree.
If the file is… It goes in… Example Who writes it
A rule, policy, or system-wide decision governance/ New system lesson, architecture decision APEX + Pat approval
About a person, company, or meeting knowledge/ CRM contact, transcript, org profile Network SME, Librarian, ingestion pipelines
An agent's identity, memory, or skills agents/<name>/ SOUL.md, daily log, lessons.md The agent itself
Work involving 2+ agents or owned by Pat projects/<name>/ Orcrist capture plan, this architecture project Owning agent (Shogun coordinates)
Work involving only one agent agents/<name>/projects/ Forge's log rotation project That agent
Inter-agent communication ops/mailbox/ Request from Shogun to Forge Sending agent (via mailbox_send.sh)
Generated output for Pat (brief, report) ops/briefs/ Morning brief HTML, dashboard Shogun (briefs), any agent (reports)
Inbound file needing triage ops/staging/ Email attachment, web download, Pat file drop Ingestion pipeline → Shogun triages
A log, metric, or operational artifact ops/logs/ Sentinel checkpoint, forge-watcher log The generating agent/service
Completed/retired content archive/ Old vault structure, retired agent Any agent (date-prefix required)
A script or automation ops/scripts/ mailbox_send.sh, sentinel_alert.sh Forge
Conflict Resolution Rules
Conflict Type Resolution
Same file exists in 2+ locations Determine authoritative copy per SOR matrix. Keep authority copy, delete others. If both have unique content → merge into authority copy, archive the other.
Agent doc vs governance doc disagree governance/ wins. Agent doc must be updated to align.
Two agents claim ownership of same project Move to projects/ (cross-agent). Assign one owner in README.md.
Stale file (>90 days, no references) Move to archive/ with date prefix. Keep git history.
File doesn't fit any category ops/staging/ → Shogun triages during next daily pass.
Data Flows
How information moves through the system.

📥 Inbound: Pat → System

Slack message
→
Shogun
task-capture
→
agents/shogun/memory/captures/
File drop
(Obsidian, Dropbox)
→
ops/staging/from-pat/
→
Shogun triage
→
Correct vault dir
Voice memo
→
Whisper transcribe
→
Shogun processes
→
Response + capture

🔄 Inter-Agent: Agent → Agent

Shogun
→
ops/mailbox/forge/inbox/
YAML frontmatter required
→
Forge reads + ACKs
Then optionally: Slack #forge notification (never instead of mailbox)

📤 Outbound: System → Pat

Morning Brief
→
ops/briefs/
→
Funnel HTTP serve
→
Slack link to Pat
Project status
→
projects/<name>/README.md

🧠 Knowledge: Query Path

Any agent
→
world-model API
:8081
→
ChromaDB vectors
+ SQLite graph
→
Relevant snippets
(not full files)
Agents never load knowledge/ directly into context. Always query via API or file tools.

📊 Governance: Change Flow

Agent proposes change
→
ADR in governance/DECISIONS.md
→
APEX reviews
→
Pat approves
→
Governance updated
Current → Future Migration
Every path rename in one view. One atomic git commit.
Current Path Future Path Notes
System_OS/ → governance/ Rename only. All contents preserved.
System_Context/ → knowledge/ Rename only. ~475MB.
Shogun_OS/ → agents/shogun/ Nested under agents/.
Forge_OS/ → agents/forge/ Nested under agents/.
mailbox/ → ops/mailbox/ Grouped with ops infra.
briefs/ → ops/briefs/ Grouped with ops infra.
logs/ → ops/logs/ Grouped with ops infra.
openclaw-memory/ → ops/openclaw-memory/ OpenClaw internal state.
archive/ → archive/ No change — already correct.
— + projects/ New. Cross-agent work.
— + ops/staging/ New. Replaces Dropbox staging.
Shogun_OS/CLAUDE.md ✕ agents/shogun/CLAUDE.md ⚠️ Rewrite — currently says "Forge"!
CLAUDE.md (root) ✎ CLAUDE.md (root) ⚠️ Rewrite — neutral router, not Forge-specific.
Post-rename fixups: Update openclaw.json workspace paths · Bulk-update Obsidian wikilinks · Update SOUL.md/HEARTBEAT.md path references · Update LaunchAgent plists · Update sentinel scripts · Verify world-model ingestion paths · Test all agents start clean
Migration Phases

Phase 1

Prep
Write root README.md
Rewrite root CLAUDE.md
Fix Shogun CLAUDE.md
Pat final review

Phase 2

Atomic Rename
git mv (all dirs)
mkdir projects/, ops/staging/
Single commit

Phase 3

Fix References
openclaw.json paths
Obsidian wikilinks
SOUL.md, HEARTBEAT.md
LaunchAgents, scripts
world-model config

Phase 4

Remote Machines
Gateway: wipe old → clone
Nomad: wipe old → clone
Cockpit: git pull
Outpost: add governance/

Phase 5

Cleanup
Dropbox agent artifacts → vault
Delete shadow duplicates
Merge diverged lessons files
Verify all services running
Machine Sync Strategy
Engine is the master. Other machines get what they need.

🖥️ Engine

M3 Ultra · Master
✅ governance/
✅ knowledge/ (475MB)
✅ agents/ (all)
✅ projects/
✅ ops/
✅ archive/
Source of truth. All services run here.

💻 Cockpit

M4 Max · Pat's Workstation
✅ governance/
✅ knowledge/ (via Obsidian Sync)
✅ agents/ (all)
✅ projects/
⚡ ops/ (briefs only)
✅ archive/
Full vault for Pat's direct editing.

📡 Gateway

Mac Mini M4 Pro · Backup
✅ governance/
— knowledge/ (query via API)
⚡ agents/ (subset)
— projects/
— ops/
— archive/
Minimal. Backup routing only.

✈️ Nomad

MacBook Air · Travel
✅ governance/
— knowledge/ (too large)
⚡ agents/shogun/ only
⚡ projects/ (active only)
— ops/
— archive/
Lightweight. Pat + Shogun context only.

🌐 Outpost

Hostinger VPS · Services
⚡ governance/ (read-only copy)
— knowledge/
— agents/
— projects/
— ops/ (has own service logs)
— archive/
Service host only. Runs Docker + PM2.
Sync Mechanisms: Obsidian Sync (Cockpit ↔ Engine) · Git sparse checkout (Gateway, Nomad) · rclone nightly (Outpost) · SSH on-demand (all)
Generated by Shogun · 2026-04-11 · ShogunOS Worldview Architecture Program