ShogunOS — Subfolder Architecture & SOP

Universal Design Principles

These principles govern every folder and file decision. Sourced from Anthropic's context engineering guidance, OpenClaw conventions, ADR best practices, and our own hard-won lessons.

Self-documenting names. A human or agent reading ls output should understand what a directory contains without opening any files. No abbreviations, no numbered prefixes (except ADRs), no jargon. knowledge/people/ beats 01-Knowledge-Base/CRM/.

Flat over deep. Max 3 levels deep for navigation. Beyond that, agents waste context exploring. governance/frameworks/architecture-v2.html = 2 levels. Good. System_OS/plans/checkpoint-reviews/sweep-2026-04-09-073201.md = 3 levels. Borderline.

One file, one home. Every file has exactly one canonical location. No duplicates, no shadow copies. If two agents need the same file, one reads from the other's location — or it lives in governance/ or knowledge/.

Eager vs. lazy loading. Small authoritative files (governance/, agent identity) = loaded eagerly into context. Large reference files (knowledge/) = queried on demand via API or file tools. Folder placement signals which pattern to use.

Convention over configuration. Agents know where to look by folder convention, not by reading a config file. agents/*/SOUL.md always exists. projects/*/README.md always exists. No exceptions.

Required files are named, optional files are patterned. Every directory has 0-3 required files (like SOUL.md, README.md). Additional files follow a naming pattern but aren't enumerated. This keeps the SOP short while allowing growth.

Time-series data uses date prefixes. Logs, daily notes, captures, briefs: YYYY-MM-DD-*. This sorts chronologically by default and makes cleanup trivial (find -mtime +30).

Archive, don't delete. Retired content goes to archive/ with a date prefix. Git history is the backup, but archive/ is the human-readable record. The only exception: transient logs older than the rotation window.

What Open Source Told Us

Anthropic

"Folder hierarchies, naming conventions, and timestamps provide important signals." Progressive disclosure via navigation, not pre-loading. Minimal set of high-signal tokens.

OpenClaw

Each agent = workspace + SOUL.md + AGENTS.md. Skills in skills/. Memory in memory/. Convention-based, not config-based.

MADR (ADRs)

Architecture decisions in decisions/ as numbered markdown files. Lightweight, version-controlled, greppable. MADR template: Status, Context, Decision, Consequences.

Obsidian

Single vault, folders for logical separation. Cross-linking via wikilinks. Flat is better than nested for discoverability.

📜 governance/

~1 MB · Constitutional Authority · Read Every Session

governance/ ├── SYSTEM.md ← the constitution. Universal rules for all agents. ├── DECISIONS.md ← architecture decision log (append-only) ├── SYSTEM_LESSONS.md ← hard-won rules (SL-001+). Read every task. ├── THE_AGENT_DOCTRINE.md ← the bot bible. Principles for all agents. ├── CONTEXT_FILE_STANDARD.md ← how files should be structured ├── LINEAR_SOP.md ← Linear project management rules │ ├── decisions/ ← individual ADRs (MADR format) │ ├── 0001-vault-restructure.md │ ├── 0002-agent-naming.md │ └── TEMPLATE.md ← ADR template for new decisions │ ├── frameworks/ ← enduring reference frameworks │ ├── architecture-v2.html ← 5-layer architecture reference │ └── change-protocol-v2.html ← change management protocol │ ├── worldview/ ← worldview project artifacts │ ├── EVALUATION_FRAMEWORK.md │ ├── STORAGE_POLICY.md │ ├── CURRENT_STATE_AUDIT.md │ └── *.html ← dashboards, visualizations │ ├── metrics/ ← system-wide KPIs and tracking │ └── overwatch-metrics-*.md ← periodic metric snapshots │ └── integrations/ ← external service configs + SOPs ├── linear.md ← Linear workspace rules ├── slack.md ← Slack channel directory + rules └── m365.md ← M365 tenant config

SOP: Adding to governance/

When to create a new governance file

The content is a rule, policy, or standard that applies to 2+ agents
It should survive any agent being replaced or added
It has constitutional authority — agents must follow it, not just reference it

Process

Draft the file in your agent workspace first
Create an ADR in governance/decisions/ explaining the change
APEX reviews (for structural changes) or Shogun reviews (for operational rules)
Pat approves (for anything that changes agent authority or constraints)
Move file to governance/. Update DECISIONS.md log.

⚠️ Anti-pattern

Don't put agent-specific rules here. Shogun's lessons belong in agents/shogun/skills/lessons.md, not in governance. Governance is for universal rules only.

🧠 knowledge/

~475 MB · Reference Library · Query On Demand

knowledge/ ├── people/ ← 1,902 contact files (CRM output) │ ├── john-smith.md ← one file per person │ ├── jane-doe.md │ └── _index.md ← optional: quick-lookup table │ ├── orgs/ ← 112 organization profiles │ ├── deus-x-defense.md │ ├── axon-enterprise.md │ └── _index.md │ ├── transcripts/ ← 192 meeting transcripts │ ├── 2026-03-15-orcrist-weekly.md │ └── 2026-04-01-board-prep.md ← YYYY-MM-DD-slug format │ ├── digests/ ← 36 digest files by domain │ ├── email-digest-2026-04.md │ ├── calendar-digest-2026-04.md │ ├── finance-digest-q1-2026.md │ └── business-digest-2026-04.md │ ├── reference/ ← SOPs, proposals, product docs │ ├── sops/ ← 9 standard operating procedures │ ├── brand/ ← logos, templates, brand guide, Zoom BGs │ ├── proposals/ ← capture plans, MOUs, intros │ └── templates/ ← reusable doc templates │ ├── pat/ ← Pat's personal context │ ├── USER_PROFILE.md ← comprehensive Pat profile │ └── PERSONAL_CONTEXT.md ← family, home, priorities │ ├── dxd/ ← DxD-specific business context │ ├── DXD_CONTEXT.md │ ├── PRODUCT_OVERVIEW.md │ └── architecture/ ← system architecture docs │ ├── graph/ ← knowledge graph + extraction DB │ ├── extraction.sqlite ← 74MB entity/relationship DB │ └── schema.md ← graph schema documentation │ ├── staging/ ← inbound content awaiting classification │ ├── inbound/ ← raw intake │ └── classified/ ← classified, awaiting move to final home │ └── archive/ ← retired knowledge content └── crm-snapshots/ ← historical CRM state

SOP: Adding to knowledge/

Automated Ingestion (most content)

Pipeline drops file into knowledge/staging/inbound/
Classifier agent (Network SME or Librarian) categorizes it
File moves to knowledge/staging/classified/ with metadata tag
On daily triage pass: move to correct subdirectory
World-model API re-indexes the new file

Manual Addition

Determine type: person → people/, org → orgs/, meeting → transcripts/
Use the naming convention for that directory (see Naming SOP tab)
Include frontmatter: source, date, tags
Trigger world-model re-index if time-sensitive

Access

All agents read via world-model API (:8081) or file tools. Network SME and Librarian have write access. Direct context-window loading is prohibited — these files are too large. Always query.

⚠️ Git

knowledge/ may be .gitignored if repo size is a concern (475MB). In that case, sync via rclone or Obsidian Sync. The world-model API is the primary access path regardless.

🤖 agents/

Per-Agent Workspaces · Convention-Based

agents/ ├── shogun/ ← Chief of Staff │ ├── SOUL.md ← identity, principles, constraints (REQUIRED) │ ├── CLAUDE.md ← workspace orientation for Claude Code (REQUIRED) │ ├── AGENTS.md ← OpenClaw behavioral config │ ├── USER.md ← about Pat (the human) │ ├── MEMORY.md ← curated long-term memory │ ├── HEARTBEAT.md ← autonomous ops schedule │ ├── IDENTITY.md ← avatar, emoji, creature type │ ├── TOOLS.md ← local setup notes │ │ │ ├── memory/ ← time-series operational memory │ │ ├── 2026-04-11.md ← daily session log (YYYY-MM-DD.md) │ │ ├── 2026-04-10.md │ │ ├── captures/ ← task captures from Slack │ │ │ └── 2026-04-11.md │ │ ├── heartbeat-log.md ← heartbeat output log │ │ ├── heartbeat-state.json ← last-check timestamps │ │ ├── growth-log.md ← learning from external sources │ │ └── open-requests.json ← pending inter-agent requests │ │ │ ├── skills/ ← agent-specific operational knowledge │ │ ├── lessons.md ← hard-won lessons (agent-level) │ │ ├── protocol.md ← inter-agent protocol reference │ │ ├── model-selection.md ← when to use which model │ │ ├── verification.md ← how to verify work │ │ └── wins.md ← what's working well │ │ │ ├── entities/ ← business entity contexts │ │ ├── DxD/ ← Deus X Defense identity + CLAUDE.md │ │ ├── HoldCo/ ← Shogun Madden LLC │ │ ├── Montauk/ ← Montauk entity │ │ ├── Personal/ ← Personal context │ │ └── Apex_Architect/ ← APEX sub-agent │ │ │ ├── scripts/ ← agent-specific automation │ │ ├── briefing/ ← morning/evening brief generation │ │ └── email/ ← email processing scripts │ │ │ ├── state/ ← runtime state files │ │ └── current-task.md ← what I'm working on right now │ │ │ └── archive/ ← agent-level archive │ ├── retired-agents/ │ └── legacy-infra/ │ ├── forge/ ← CPTO / Builder │ ├── SOUL.md │ ├── CLAUDE.md │ ├── FORGE_DOCTRINE.md ← single authoritative copy │ ├── CHANGELOG.md ← single authoritative changelog │ ├── lessons_learned.md │ │ │ ├── memory/ ← same pattern as shogun │ ├── skills/ │ │ │ ├── architecture/ ← ADRs, system designs │ │ └── *.md │ ├── projects/ ← forge-internal projects only │ ├── code/ ← code references (symlinks OK) │ ├── forensics/ ← incident investigation artifacts │ ├── AARs/ ← after-action reviews │ ├── logs/ ← forge-specific runtime logs │ ├── scripts/ ← forge automation │ ├── specs/ ← technical specifications │ └── world-model/ ← world-model service code + data │ ├── *.py │ └── chromadb_store/ ← vector DB (2.1GB — .gitignored) │ └── sentinel/ ← Behavioral Monitor ├── identity.md ← sentinel identity + rules ├── config/ ← sentinel configuration └── checkpoints/ ← audit checkpoint outputs

SOP: Creating a New Agent

Steps (every time, no exceptions)

mkdir agents/<name>/
Create SOUL.md — identity, role, principles, constraints. Required.
Create CLAUDE.md — workspace orientation, vault access rules, load order. Required.
Create memory/ — daily logs will go here automatically
Create skills/ if the agent has operational knowledge
Add agent to governance/ roster (if permanent agent, not a sub-agent)
Add mailbox: mkdir ops/mailbox/<name>/inbox/
Update root CLAUDE.md routing table

Agent Workspace Conventions

Required

SOUL.md + CLAUDE.md in every agent dir. No exceptions. These two files ARE the agent.

Memory

memory/YYYY-MM-DD.md for daily logs. MEMORY.md at agent root for curated long-term. memory/captures/ for task captures. memory/heartbeat-state.json for operational state.

Skills

skills/ for operational knowledge. These are NOT OpenClaw SKILL.md skills (those live in ~/.openclaw/workspace/skills/). These are agent-specific reference docs.

📋 projects/

Cross-Agent Work · Pat-Owned Initiatives

projects/ ├── orcrist-capture/ ← Federal capture program │ ├── README.md ← REQUIRED: owner, agents, status, links │ ├── plan.md ← current execution plan │ ├── decisions/ ← project-level ADRs │ ├── artifacts/ ← deliverables, specs, analysis │ │ ├── capture-plan-v3.md │ │ └── competitive-analysis.md │ ├── research/ ← research inputs (optional) │ └── archive/ ← completed phases │ ├── worldview-architecture/ ← this project │ ├── README.md │ ├── plan.md │ └── artifacts/ │ ├── unified-data-plan/ ← Forge's data management project │ ├── README.md │ ├── UNIFIED_PLAN.md │ └── decisions/ │ └── seam-2-development/ ← SEAM-2 product development ├── README.md └── artifacts/

SOP: Creating a New Project

Decision: projects/ or agents/<name>/projects/?

2+ agents involved? → projects/
Pat is the owner or stakeholder? → projects/
Single agent, internal housekeeping? → agents/<name>/projects/
Unclear? → Default to projects/. Better to be visible than buried.

Steps

mkdir projects/<project-slug>/
Create README.md from template (see Templates tab). Required.
Create plan.md — execution plan, phases, timeline
mkdir decisions/ artifacts/
Add to Linear if tracked there (link in README.md)
Announce in relevant Slack channel

Project Lifecycle

Active

Project has a README.md with status = "Active". Agents are writing to it. Plan.md is current.

On Hold

README.md status = "On Hold" + reason. No active work. Agents check during heartbeat rotation.

Complete

README.md status = "Complete" + completion date. Final artifacts in place. Move to archive/projects/<slug>/ after 30 days.

⚙️ ops/

Shared Infrastructure · Transient + Operational

ops/ ├── mailbox/ ← inter-agent communication hub │ ├── shogun/ │ │ └── inbox/ ← YAML-frontmatter messages TO Shogun │ ├── forge/ │ │ └── inbox/ │ ├── sentinel/ │ │ └── inbox/ │ └── mailbox_send.sh ← auto-wraps YAML frontmatter │ ├── briefs/ ← generated HTML briefings + dashboards │ ├── morning-brief-2026-04-11.html │ ├── evening-brief-2026-04-10.html │ ├── vault-architecture-v2.html ← symlinks to source OK │ └── dashboard.html │ ├── staging/ ← NEW: inbound file triage area │ ├── from-pat/ ← Pat drops files here │ ├── from-external/ ← email attachments, web downloads, cloud LLM outputs │ └── processed/ ← triaged, awaiting move to final home │ ├── logs/ ← all operational logs (with rotation) │ ├── forge-launch.log ← rotated: keep 7 days, max 10MB │ ├── sentinel-watchdog.log │ ├── forge-watcher.log │ ├── checkpoint-reviews/ ← sentinel sweep outputs │ └── rotated/ ← compressed old logs │ └── scripts/ ← shared automation ├── mailbox_send.sh ├── sentinel_alert.sh ├── brief-server.sh └── log-rotate.sh

SOP: Mailbox Protocol

Sending a message

Write message with YAML frontmatter (from, to, priority, timestamp, subject, status, type)
Use ops/scripts/mailbox_send.sh to auto-format
File lands in ops/mailbox/<recipient>/inbox/
Optionally notify via Slack (AFTER mailbox write, never instead of)

SOP: Staging Triage

Daily triage pass (Shogun, during heartbeat)

ls ops/staging/from-pat/ and ops/staging/from-external/
For each file: determine type (knowledge, project artifact, governance input, reference)
Move to correct destination directory
Move to ops/staging/processed/ if needs further work
Update capture log if task-shaped

SOP: Log Rotation

Rules (Forge maintains)

Logs rotate at 10MB OR 7 days, whichever comes first
Rotated logs compressed to ops/logs/rotated/
Rotated logs deleted after 30 days
Checkpoint reviews: keep 7 days of individual files, then consolidate to JSONL

⚠️ Transient

Nothing in ops/ is permanent. Mailbox messages are consumed. Logs are rotated. Briefs are regenerated. Staging files move to their final home. If it needs to persist, it doesn't belong in ops/.

File & Folder Naming Conventions

Consistency makes the system navigable. These rules are non-negotiable.

Type	Convention	Example	Notes
Directories	`lowercase-kebab-case/`	`orcrist-capture/`	No spaces, no underscores, no capitals. Exception: agent identity files (SOUL.md etc.)
Identity files	`UPPERCASE.md`	`SOUL.md`, `CLAUDE.md`, `README.md`	Convention from OpenClaw + GitHub. These are "read me first" files.
Governance files	`UPPER_SNAKE_CASE.md`	`SYSTEM_LESSONS.md`	Signals authority. These files have constitutional weight.
Daily logs	`YYYY-MM-DD.md`	`2026-04-11.md`	Sorts chronologically. One file per day per agent.
Transcripts	`YYYY-MM-DD-slug.md`	`2026-03-15-orcrist-weekly.md`	Date first for sorting. Slug for identification.
Briefs	`type-brief-YYYY-MM-DD.html`	`morning-brief-2026-04-11.html`	Type prefix for filtering. Date for sorting.
ADRs	`NNNN-slug.md`	`0001-vault-restructure.md`	MADR convention. Sequential numbering. Never renumber.
Mailbox messages	`YYYYMMDD_HHMMSS_from_subject.md`	`20260411_233500_shogun_vault-restructure.md`	Timestamp + sender + slug. Auto-generated by mailbox_send.sh.
People (CRM)	`firstname-lastname.md`	`serge-glushenko.md`	Lowercase kebab. One file per person.
Orgs	`org-name.md`	`deus-x-defense.md`	Lowercase kebab. Full name, not abbreviation.
Skills (agent)	`topic.md`	`lessons.md`, `protocol.md`	Lowercase, descriptive, no date prefix (these are evergreen).
Scripts	`verb-noun.sh`	`mailbox-send.sh`, `log-rotate.sh`	Action-oriented naming. Always executable.
Archive dirs	`YYYY-MM-DD-description/`	`2026-04-10-cockpit-recon/`	Date prefix required. Description of what was archived.

Frontmatter Standard

Knowledge files

YAML frontmatter with: source, date, tags, type (person|org|transcript|digest|reference)

Mailbox files

YAML frontmatter with: from, to, priority, timestamp, subject, status, type

ADRs

MADR format: Title, Status (proposed/accepted/deprecated), Context, Decision, Consequences

Project READMEs

Structured sections: Owner, Participants, Status, Description, Links, Current Phase

File Templates

Copy-paste these when creating new files. They enforce consistency.

📋 Project README.md

# Project Name
**Owner:** [agent name]
**Participants:** [agent1, agent2]
**Status:** Active | On Hold | Complete
**Created:** YYYY-MM-DD
**Linear:** [link if tracked]

## Description
One paragraph: what this project does and why.

## Current Phase
What's happening now. Key milestones.

## Decisions
Link to decisions/ dir or inline key decisions.

## Links
- Slack channel: #channel
- Dashboard: [URL]
- Related projects: [links]

📜 ADR (decisions/NNNN-slug.md)

# NNNN — Decision Title

**Status:** Proposed | Accepted | Deprecated
**Date:** YYYY-MM-DD
**Author:** [agent or Pat]

## Context
What is the issue? Why does a decision need to be made?

## Decision
What was decided. Be specific.

## Consequences
What happens as a result. Both positive and negative.

## Alternatives Considered
What else was considered and why it was rejected.

🤖 Agent SOUL.md

# SOUL.md — [Agent Name]
**Agent:** [Name] | **Version:** 1.0
**Runtime:** [OpenClaw | Claude Code | Hermes]

## Identity
- **Name:** [Name]
- **Role:** [One-line description]
- **Commander:** Patrick R. Madden (Pat)

## Principles
1. [Principle 1]
2. [Principle 2]
3. [Principle 3]

## Constraints
- [What this agent cannot do]
- [Boundaries of authority]

## Workspace
- Own dir: agents/[name]/
- Read access: [list]
- Write access: [list]

🗂️ Agent CLAUDE.md

# agents/[name]/ — [Role Description]

## Identity
This is **[Name]**'s workspace.
Load order: SOUL.md → skills/ as needed

**Commander:** Patrick R. Madden (Pat)
**Role:** [Role description]

## Vault Access
| Directory | Access | Purpose |
|-----------|--------|---------|
| governance/ | Read | Universal rules |
| knowledge/ | Read (via API) | Reference data |
| agents/[name]/ | Read-write | Own workspace |
| projects/ | Read-write | Cross-agent work |
| ops/ | [scope] | [purpose] |

## Key Files
| File | Purpose |
|------|---------|
| SOUL.md | Identity kernel |
| memory/ | Operational memory |
| skills/ | Operational knowledge |

👤 Knowledge Person File

---
type: person
source: [CRM | transcript | manual]
date: YYYY-MM-DD
tags: [tag1, tag2]
---
# Firstname Lastname

**Role:** [Title] at [Company]
**Relationship:** [How Pat knows them]
**Last Contact:** YYYY-MM-DD

## Context
Key information about this person.

## Notes
Running notes from interactions.

📨 Mailbox Message

---
from: [sender-agent]
to: [recipient-agent]
priority: P0|P1|P2
timestamp: YYYY-MM-DDTHH:MM:SSZ
subject: [kebab-case-slug]
status: unread
type: request|acknowledgment|status|done
---

## [Subject]

[Body of message]

### Requested Action
[What you need the recipient to do]

### Deadline
[When, if applicable]

⛩️ ShogunOS — Subfolder Architecture & SOPs