Model-agnostic identity · Code & Git · Session lifecycle · Feedback loops · Audit system
You're right — CLAUDE.md is a Claude/Anthropic convention. The system should work with any model, any harness.
Currently, agent identity is defined via CLAUDE.md — a file convention specific to Claude Code. But Pat uses multiple models and harnesses:
Baking CLAUDE.md into the architecture ties us to one vendor's convention.
| File | Purpose | Read By | Model-Agnostic? |
|---|---|---|---|
SOUL.md |
The universal identity file. Who am I, what are my principles, what's my scope. Works with ANY model/harness. | All harnesses (OpenClaw reads it natively; others can be pointed to it) | ✅ Yes — it's just markdown. Any LLM can read it. |
AGENTS.md |
Behavioral config. Session startup, memory rules, heartbeat schedule, group chat behavior. | OpenClaw (native), Codex (native) | ✅ Yes |
CONTEXT.md ← NEW (replaces CLAUDE.md) |
Workspace orientation. Directory map, access rules, key files, load order. What CLAUDE.md currently does, but model-agnostic. | Any agent working in the directory. Claude Code reads CLAUDE.md → we symlink or alias. | ✅ Yes |
CLAUDE.md |
Compatibility symlink. Points to CONTEXT.md. Exists solely because Claude Code looks for this filename. | Claude Code only (auto-discovered) | It's a bridge to vendor convention, not the source of truth. |
| Location | SOUL.md | CONTEXT.md | CLAUDE.md | Purpose |
|---|---|---|---|---|
~/ShogunOS/ (root) | — | ✅ System overview + routing | → symlink to CONTEXT.md | Any agent starting at repo root gets orientation |
agents/shogun/ | ✅ Shogun identity | ✅ Shogun workspace map | → symlink | OpenClaw reads SOUL.md; Claude Code reads CLAUDE.md → CONTEXT.md |
agents/forge/ | ✅ Forge identity | ✅ Forge workspace map | → symlink | Claude Code enters → reads CLAUDE.md → gets Forge identity |
projects/*/ | — | Optional: project-specific context | → symlink if present | Agent entering a project dir gets project context |
Currently tells you to paste MEMORY.md → SYSTEM.md → CONTEXT.md manually into Grok/Gemini/ChatGPT.
For cloud LLMs without file access:
governance/SYSTEM.md — universal rulesSOUL.md — identityCONTEXT.md — workspace orientationOne set of files serves every model. No vendor-specific variants.
Code lives in a separate Git repo managed by Forge. This vault is docs + context. They're connected, not merged.
| Repo | Contains | Who Writes | Review Process |
|---|---|---|---|
ShogunOS (this vault) |
Governance, knowledge, agent workspaces, projects, ops. Markdown, HTML, YAML. | All agents (per write-safety rules) | Governance changes: ADR + approval. Other changes: auto-commit + Sentinel audit. |
Code repo (Forge-managed) |
Services (world-model, brief-server), infrastructure configs (LaunchAgents, nginx, Docker), automation scripts, auth scripts. | Forge only | Forge's version control model: branch → test → merge. Done-declaration requires evidence. |
Already partially built. Here's the full model:
| Tool | What It Does | Location |
|---|---|---|
boot_preflight.sh | Session start: reads last closeout, checks system health, reads mailbox | Code repo (currently Forge_OS/Code/) |
session_closeout.sh | Session end: writes current-task.md with state, pending items, next steps | Code repo |
done_declaration.sh | Task completion: requires evidence, optionally runs test command, posts to Shogun's mailbox | Code repo |
mailbox_send.sh | Inter-agent messaging with YAML frontmatter | ops/scripts/ |
artifacts/ can contain documentation ABOUT code (specs, architecture), not the code itselfCONTEXT.md includes the code repo path and describes what's theregovernance/integrations/ documents what services exist and how they're configured — the actual configs live in the code repoWhat happens when an agent starts, runs, and ends a session. Every phase has a checklist.
mkdir agents/<name>/ with memory/ and skills/ subdirs
Identity, role, principles, constraints, workspace scope. Use the template. This is the agent's "birth certificate."
Workspace orientation: directory map, access rules, key files, load order. Claude Code compatibility: ln -s CONTEXT.md CLAUDE.md
OpenClaw: add to openclaw.json agents list. Claude Code: root CLAUDE.md routes to agent. Hermes: configure agent config. Other: update ONBOARDING_TEMPLATE.md.
Create mailbox: mkdir ops/mailbox/<name>/inbox/. Add to governance roster. Update Slack channel permissions if needed.
Start the agent. Verify it reads SOUL.md correctly. Verify it can access its workspace, read governance/, query knowledge/. Log results.
| Step | What | Files Read | Purpose |
|---|---|---|---|
| 1 | Read identity | SOUL.md | Remember who I am |
| 2 | Read workspace context | CONTEXT.md | Know where everything is |
| 3 | Read governance | governance/SYSTEM_LESSONS.md | Hard-won rules (every task, every session) |
| 4 | Read last session state | memory/YYYY-MM-DD.md (today + yesterday) | Continuity — what happened last time |
| 5 | Read long-term memory | MEMORY.md (if main session) | Who Pat is, key decisions, important context |
| 6 | Check mailbox | ops/mailbox/<me>/inbox/ | Pending messages from other agents |
| 7 | Check active tasks | state/current-task.md (if exists) | Resume interrupted work |
| 8 | Run preflight (Forge) | boot_preflight.sh (Forge-specific) | System health check |
| Step | What | Files Written | Purpose |
|---|---|---|---|
| 1 | Write session log | memory/YYYY-MM-DD.md | What happened this session — decisions, actions, learnings |
| 2 | Update long-term memory | MEMORY.md (if significant events) | Promote important context to curated memory |
| 3 | Write current-task state | state/current-task.md | If work is in progress: what's pending, what's next, blockers |
| 4 | Run post-task reflection | memory/YYYY-MM-DD.md (append) | 3-line reflection: what went right, what I'd change, one improvement |
| 5 | Close out mailbox | ops/mailbox/ | Send any DONE messages for completed work. Update STATUS on in-progress items. |
| 6 | Session closeout (Forge) | session_closeout.sh (Forge-specific) | Structured state dump for next session's boot_preflight |
How agents track issues, recommend changes, and propose improvements. The "suggestion box" system.
| Issue Type | Tracked In | Who Creates | Who Resolves |
|---|---|---|---|
| Agent operational issue (bug, mistake, drift) | agents/<name>/skills/lessons.md | The agent itself (self-reflection) | The agent (behavior change) |
| System-wide lesson (hard-won rule) | governance/SYSTEM_LESSONS.md | Any agent (proposes) → Pat approves | All agents (must read every task) |
| Infrastructure issue | Linear (CEO Tasks project) | Shogun captures → Pat validates → ticket created | Forge |
| Project-specific issue | projects/<name>/memory/open-questions.md | Any participating agent | Project owner |
| Security/compliance violation | ops/logs/checkpoint-reviews/ + Slack alert | Sentinel (automated) | Offending agent + Forge (if infra) |
| Recurring audit item | governance/MONTHLY_AUDIT.md | Any agent | Forge (execution) + Sentinel (reminders) |
Agents don't just identify problems — they recommend fixes. Here's how:
| Change Type | Where to Propose | Review Required | Example |
|---|---|---|---|
| Self-improvement Agent changes its own behavior |
Own skills/lessons.md or skills/wins.md |
None — agent self-implements | "I should check mailbox before processing completions" → write to lessons.md, change behavior |
| Own workspace edit Agent improves its own SOUL.md, HEARTBEAT.md, etc. |
Edit directly + log in memory/YYYY-MM-DD.md |
None — agent owns its workspace | Shogun adds a new heartbeat check rotation |
| Governance change Rules that affect all agents |
Write ADR in governance/decisions/ |
APEX reviews + Pat approves | "Add a new system lesson about credential handling" |
| Infrastructure change Code, configs, services |
Mailbox to Forge with proposal | Forge reviews + implements. Done-declaration for verification. | "Log rotation should happen at 5MB not 10MB" |
| Process/SOP change How we work, not what we build |
Mailbox to Shogun (who routes to Pat if needed) | Shogun evaluates. Pat approval if it changes agent authority. | "Morning brief should include Dropbox staging queue count" |
| Another agent's behavior One agent thinks another should change |
Mailbox to the target agent (proposal, not instruction) | Target agent decides. Escalate to Shogun/Pat if disagreement. | Sentinel recommends Forge add verification step to deploy process |
skills/lessons.md immediatelyskills/wins.mdHow the whole system gets audited — real-time, daily, monthly, and quarterly.
| Layer | Frequency | Who | What's Checked | Output |
|---|---|---|---|---|
| 1. Real-Time Monitoring | Continuous | Sentinel |
• Agent constraint violations (shell exec, out-of-scope writes) • Protocol violations (Slack without mailbox, tickets without Pat approval) • Same error 2x consecutive (Jidoka trigger) |
Immediate Slack alert + ops/logs/checkpoint-reviews/ |
| 2. Scheduled Audit | 3x daily (07:00, 13:00, 19:00) | Sentinel |
• Read gateway logs, match against governance/ rules • Check CHANGELOG entries have revert paths • Check Linear for tickets created without Pat confirmation • Verify done-declarations include evidence |
ops/logs/checkpoint-reviews/sweep-YYYY-MM-DD-HHMMSS.md |
| 3. Self-Audit (Agent-Level) | Every heartbeat (30 min cycle) | Each agent |
• Principle adherence (review last 2-3 actions against SOUL.md) • Lesson compliance (did I repeat any?) • Doctrine scoring (THE_AGENT_DOCTRINE.md random 2 principles) • Memory hygiene (daily → MEMORY.md promotion) • Cost tracking (session spend estimate) |
agents/<name>/memory/YYYY-MM-DD.md (heartbeat log entry) |
| 4. QC/QA Gate (Per-Deliverable) | Before every deliverable | Building agent + independent reviewer |
• Gate 1: SRAL self-check (builder verifies own work) • Gate 2: Adversarial self-review (5-point checklist) • Gate 3: Cross-agent independent verification (fresh reviewer, no build context) • Gate 4: Pat review (for high-stakes deliverables) |
Verification evidence in done-declaration or deliverable doc |
Already exists. Sentinel posts reminders on the 1st of each month. Items have added, last_reviewed, next_review, action, context fields.
Current items: credential rotation, 1Password tier review, + whatever gets added as recurring concerns surface.
Proposed additions:
Changes from v3: model-agnostic identity, code repo separation, full lifecycle SOPs.
| # | Change | Reason |
|---|---|---|
| 1 | CONTEXT.md replaces CLAUDE.md as the source of truth. CLAUDE.md becomes a compatibility symlink. | Model-agnostic. CONTEXT.md works with any LLM. CLAUDE.md is a Claude Code convenience. |
| 2 | Code stays in separate Git repo (Forge-managed). Vault references code by path, never duplicates. | Pat confirmed: Forge has a code repo with version control. "Docs in the vault, code in the repo." |
| 3 | Session lifecycle SOPs formalized: boot sequence (8 steps), closeout (6 steps), both universal. | Pat asked: what happens at start/end of sessions? |
| 4 | Change proposal pipeline defined: 6 change types, each with where-to-write and review requirements. | Pat asked: how do agents recommend improvements? |
| 5 | 4-layer audit model documented: real-time + scheduled + self-audit + QC/QA gate. | Pat asked: how is the whole system audited? |
| 6 | Monthly audit additions: vault compliance, stale projects, knowledge freshness, identity drift, Git sync. | Existing MONTHLY_AUDIT.md is good — just needs more items. |
ShogunOS/ ├── CONTEXT.md ← NEW: system orientation (model-agnostic) ├── CLAUDE.md ← symlink → CONTEXT.md (Claude Code compat) ├── README.md ← human onboarding │ ├── governance/ ← Git-tracked. Rules + decisions. │ ├── SYSTEM.md, DECISIONS.md, SYSTEM_LESSONS.md │ ├── THE_AGENT_DOCTRINE.md, CONTEXT_FILE_STANDARD.md │ ├── MONTHLY_AUDIT.md, QC_QA_SOP.md, ONBOARDING_TEMPLATE.md │ ├── decisions/ ← ADRs (0001-slug.md) │ ├── frameworks/ ← enduring reference (HTML) │ ├── integrations/ ← Linear, Slack, M365 configs │ └── metrics/ ← system KPIs │ ├── knowledge/ ← .gitignored. Synced separately. │ ├── people/, orgs/, transcripts/, digests/ │ ├── reference/, pat/ │ ├── dxd/, holdco/, montauk/ ← business entity contexts │ ├── graph/ ← extraction DB + schema │ └── staging/ ← inbound → classified │ ├── agents/ ← Git-tracked. Per-agent workspaces. │ ├── shogun/ │ │ ├── SOUL.md ← identity (universal) │ │ ├── CONTEXT.md ← workspace orientation (universal) │ │ ├── CLAUDE.md ← symlink → CONTEXT.md │ │ ├── AGENTS.md ← OpenClaw behavioral config │ │ ├── USER.md, MEMORY.md, HEARTBEAT.md │ │ ├── memory/ ← daily logs, captures, heartbeat state │ │ ├── skills/ ← operational reference (lessons, protocol) │ │ ├── entities/ ← CONTEXT.md stubs pointing to knowledge/ │ │ └── scripts/ ← agent-specific automation │ ├── forge/ │ │ ├── SOUL.md, CONTEXT.md, CLAUDE.md→symlink │ │ ├── FORGE_DOCTRINE.md, CHANGELOG.md │ │ ├── memory/, skills/, architecture/, specs/ │ │ └── code lives in separate repo (Forge-managed) │ └── sentinel/ │ ├── projects/ ← Git-tracked. Cross-agent work. │ └── <name>/ │ ├── README.md, plan.md, CONTEXT.md (optional) │ ├── decisions/, artifacts/, research/ │ ├── history/, memory/, logs/ │ └── archive/ │ ├── ops/ ← scripts/ Git-tracked. Rest .gitignored. │ ├── mailbox/ ← inter-agent comms │ ├── briefs/ ← generated HTML │ ├── staging/ ← from-pat, from-external, processed │ ├── logs/ ← rotated operational logs │ └── scripts/ ← shared automation │ └── archive/ ← date-prefixed. Read-only.