v3 — Clean-sheet architecture · Every folder, file, source, and flow
Clean-sheet design. Six top-level directories. Every subfolder intentional.
CLAUDE.md (neutral agent router) · README.md (human onboarding) · .gitignore~1 MB total. Loaded into context every session. Highest authority. Changes require ADR + approval.
| File / Folder | Purpose | Who Writes | How Often |
|---|---|---|---|
SYSTEM.md | Universal operating rules for all agents | APEX + Pat | Rarely (constitutional) |
DECISIONS.md | Running log of all architecture decisions | Any agent (append) | When decisions are made |
SYSTEM_LESSONS.md | Hard-won rules that survive agent resets | Any agent (propose) + Pat (approve) | After incidents |
THE_AGENT_DOCTRINE.md | The bot bible — behavioral principles | APEX + Pat | Quarterly review |
CONTEXT_FILE_STANDARD.md | File formatting and metadata rules | Forge/APEX | When standards evolve |
decisions/ | Individual ADRs (0001-slug.md). MADR format. | Proposing agent | Per decision |
frameworks/ | Enduring reference frameworks (architecture, change protocol) | Shogun/APEX | Major revisions only |
integrations/ | External service configs: Linear rules, Slack channel map, M365 tenant | Forge | When integrations change |
metrics/ | System-wide KPIs, overwatch snapshots | Sentinel/Shogun | Daily-weekly |
agents/shogun/skills/. Forge's changelog → agents/forge/. Governance is universal only.~475 MB. Never loaded into context window. Accessed via world-model API (:8081) or file tools.
| Folder | Contents | File Count | Naming Convention | Ingestion Source |
|---|---|---|---|---|
people/ | One file per person — role, relationship, notes | 1,902 | firstname-lastname.md | Network SME (automated CRM pipeline) |
orgs/ | Company profiles — description, contacts, relationship | 112 | org-name.md | Network SME + Cartographer |
transcripts/ | Meeting transcripts from Fireflies + Limitless | 192 | YYYY-MM-DD-slug.md | transcript-ingestion skill (Fireflies API) |
digests/ | Rollup summaries — email, calendar, finance, legal | 36 | domain-digest-YYYY-MM.md | Shogun (email-monitor) + Dispatch (calendar) |
reference/ | SOPs, brand guide, proposals, templates, Zoom BGs | ~50 | Descriptive filenames | Manual + Forge |
pat/ | Pat's comprehensive profile + personal context | 2 | Fixed names | Shogun (maintained manually) |
dxd/ | DxD business context, product overview, architecture | ~10 | Descriptive filenames | Shogun + Forge |
graph/ | 74MB SQLite extraction DB + knowledge graph schema | 2 | Fixed names | Cartographer (automated) |
staging/ | Content awaiting classification (inbound/ → classified/) | Variable | Original filename | Any pipeline |
Each agent is a subfolder with a standardized internal structure. Two files are required for every agent.
Every agent directory follows this pattern. Some folders are optional depending on the agent's role.
| File / Folder | Purpose | Required? | Contents |
|---|---|---|---|
SOUL.md | Identity kernel — who am I, what are my principles | ✅ Yes | Name, role, principles, constraints, workspace map |
CLAUDE.md | Workspace orientation for Claude Code sessions | ✅ Yes | Load order, vault access rules, key files |
MEMORY.md | Curated long-term memory | Recommended | Key decisions, people context, lessons distilled from daily logs |
HEARTBEAT.md | Autonomous operation schedule | If autonomous | Heartbeat checks, rotation, rate limits, exit conditions |
memory/ | Time-series operational memory | Recommended | YYYY-MM-DD.md daily logs, captures/, heartbeat-state.json, growth-log.md |
skills/ | Agent-specific operational knowledge | Recommended | lessons.md, protocol.md, model-selection.md, wins.md |
entities/ | Business entity contexts | If multi-entity | Subfolders per entity (DxD/, HoldCo/, Montauk/) with SOUL.md + CLAUDE.md |
scripts/ | Agent-specific automation | Optional | Briefing scripts, email processing, custom tools |
state/ | Runtime state | Optional | current-task.md, working files the agent is actively using |
archive/ | Agent-level retired content | Optional | Completed work, retired skills, old configs |
Chief of Staff. Triage, routing, briefs, task capture. OpenClaw runtime. Has: memory, skills, entities, scripts.
CPTO. Architecture, engineering, SRE, deploy. Claude Code runtime. Has: memory, skills, architecture, code, specs, world-model service.
Behavioral monitor. Compliance audits, drift detection. Hermes runtime. Has: identity, config, checkpoints.
projects/. Communication goes through ops/mailbox/.Every meaningful initiative gets a project folder. This is the richest subfolder structure in the system.
| Trigger | Goes To | Example |
|---|---|---|
| Pat assigns multi-agent work | projects/ | Orcrist capture program |
| Work involves 2+ agents | projects/ | Worldview architecture |
| Pat is a direct stakeholder | projects/ | SEAM-2 development |
| Single agent, internal housekeeping | agents/<name>/projects/ | Forge's log rotation |
| Unsure? | projects/ | Default to visible |
Everything transient. Mailbox messages are consumed. Logs are rotated. Briefs are regenerated. Staging files move on.
| Folder | Purpose | Who Uses | Lifecycle |
|---|---|---|---|
mailbox/<agent>/inbox/ | Inter-agent messages (YAML frontmatter required) | All agents (send/receive) | Read → processed → can be archived |
briefs/ | Generated HTML briefings, dashboards, reports | Shogun (generates), Pat (consumes) | Regenerated daily. Old briefs rotated at 30 days. |
staging/from-pat/ | Files Pat drops for agent review | Pat (drops), Shogun (triages) | Triaged daily → moved to correct vault dir |
staging/from-external/ | Email attachments, web downloads, cloud LLM outputs | Pipelines (drop), Shogun (triages) | Same — triaged and moved |
staging/processed/ | Triaged but needs further work before filing | Shogun | Should be empty within 48 hours |
logs/ | Service logs, checkpoint reviews | All services, Sentinel | Rotated: 10MB or 7 days. Compressed to logs/rotated/. Deleted at 30 days. |
scripts/ | Shared automation scripts | Forge (maintains), all agents (use) | Permanent — updated as needed |
Every data source. Where it enters. What processes it. Where it lands. What agent owns it.
| Source | What | Entry Point | Processing Agent | Processing Steps | Final Destination |
|---|---|---|---|---|---|
| Slack messages | Pat's messages in monitored channels | OpenClaw inbound | Shogun | 1. Receive message 2. task-capture skill classifies 3. Write capture if task-shaped 4. Respond if needed |
agents/shogun/memory/captures/YYYY-MM-DD.md |
| Fireflies.ai | Meeting transcripts | Fireflies API poll | Shogun (transcript-ingestion skill) | 1. Poll API for new transcripts 2. Download + format to markdown 3. Extract action items 4. Write transcript + capture items |
knowledge/transcripts/YYYY-MM-DD-slug.mdAction items → agents/shogun/memory/captures/ |
| Gmail | Email inbox | Gmail API (email-monitor skill) | Shogun | 1. Scan inbox on heartbeat 2. Classify: Decide / Review / Handled 3. Surface VIP to Pat via Slack 4. Write digest |
Alerts → Slack Digest → knowledge/digests/email-digest-YYYY-MM.md |
| Outlook / M365 | Calendar, DxD email | M365 Graph API | Dispatch (calendar) / Shogun | 1. Fetch calendar events 2. Format for briefs 3. Include in morning brief |
knowledge/digests/calendar-digest-YYYY-MM.mdBrief → ops/briefs/ |
| Linear | Project tickets + status | Linear API | Shogun (morning-briefing skill) | 1. Fetch active issues 2. Tier by priority (P0/P1/P2) 3. Include in morning brief 4. Flag stale tickets |
Brief → ops/briefs/morning-brief-YYYY-MM-DD.html |
| Pat file drops | Documents, PDFs, images Pat wants agents to process | ops/staging/from-pat/ |
Shogun | 1. Detect new file 2. Determine type (knowledge, project artifact, reference) 3. Process/extract if needed 4. Move to final location |
Varies: knowledge/reference/, projects/*/artifacts/, etc. |
| Cloud LLM outputs | Perplexity, Gemini, ChatGPT session exports | ops/staging/from-external/ |
Shogun | 1. Ingest file 2. Extract key content 3. Determine if it updates existing knowledge or creates new 4. File appropriately |
knowledge/ subdir or projects/*/research/ |
| CRM pipeline | Contact enrichment, relationship updates | Network SME automated run | Network SME | 1. Cross-reference emails, transcripts, KB 2. Identify stale/incomplete contacts 3. Enrich and update contact files |
knowledge/people/*.md |
| Inter-agent messages | Requests, status updates, done notifications | ops/mailbox/<agent>/inbox/ |
Receiving agent | 1. Read on heartbeat/check 2. Process request 3. ACK within 3 min 4. STATUS every 10 min 5. DONE with evidence |
Stays in ops/mailbox/ (consumed in place) |
| Sentinel audits | Compliance checks, drift detection | Scheduled cron (3x daily) | Sentinel | 1. Read gateway logs 2. Check against governance/ rules 3. Flag violations 4. Write checkpoint |
ops/logs/checkpoint-reviews/Alerts → Slack #forge |
| Web research | Growth scan, competitive intel, tech radar | Agent-initiated web_search | Shogun / Tech Radar | 1. Search during heartbeat rotation 2. Evaluate relevance 3. Log findings |
agents/shogun/memory/growth-log.mdor projects/*/research/ |
| Dropbox | Personal files, business docs (Pat's filesystem) | Direct filesystem access (read-only for agents) | Any agent (on Pat's request) | 1. Pat asks "look at X in Dropbox" 2. Agent reads file 3. If agent needs to keep a copy → staging 4. Triage to correct location |
Varies — agents don't write to Dropbox |
| OneDrive (DxD) | DxD corporate documents | OneDrive filesystem (read-only) | Any agent (on Pat's request) | Read-only. Never write. Copy to ShogunOS if agent needs to work with it. | N/A — read in place |
How data moves through every lifecycle in the system.
Copy-paste starters for every standard file type.
# Project Name **Owner:** [agent] **Participants:** [agent1, agent2] **Status:** Active | On Hold | Complete **Created:** YYYY-MM-DD **Linear:** [link if tracked] ## Description What this project does and why it exists. ## Current Phase What's happening now. Key next steps. ## Key Decisions - [decision 1] — see decisions/0001-*.md - [decision 2] ## Links - Slack: #channel - Dashboard: [URL] - Related: [links]
# NNNN — Decision Title **Status:** Proposed | Accepted | Deprecated **Date:** YYYY-MM-DD **Author:** [agent or Pat] ## Context What is the issue? Why now? ## Decision What was decided. Specific and actionable. ## Consequences Positive: [what this enables] Negative: [what this costs or constrains] ## Alternatives Considered - Option A: [rejected because...] - Option B: [rejected because...]
# 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 - [Boundary 1] - [Boundary 2] ## Workspace - Own dir: agents/[name]/ - Reads: governance/, knowledge/ (API), projects/ - Writes: agents/[name]/, projects/, ops/
# Project Context — [Project Name] **Updated:** YYYY-MM-DD ## Key Assumptions - [Assumption 1 — verified/unverified] - [Assumption 2] ## Stakeholder Preferences - Pat wants: [specific direction] - Constraints: [budget, timeline, etc.] ## Open Questions - [ ] [Question 1] - [ ] [Question 2] ## What We've Learned - [Lesson from phase 1] - [Lesson from research]
--- from: [sender] to: [recipient] priority: P0|P1|P2 timestamp: YYYY-MM-DDTHH:MM:SSZ subject: [kebab-slug] status: unread type: request|acknowledgment|status|done --- ## [Subject] [Body] ### Requested Action [What you need done] ### Deadline [When, if applicable]
--- type: person source: [crm|transcript|manual] date: YYYY-MM-DD tags: [defense, investor, advisor] --- # Firstname Lastname **Role:** [Title] at [Company] **Relationship:** [How Pat knows them] **Last Contact:** YYYY-MM-DD ## Context Key information about this person. ## History - YYYY-MM-DD: [interaction note] - YYYY-MM-DD: [interaction note]
# [Project] — Work Log **Date:** YYYY-MM-DD **Agent:** [name] ## What I Did - [Action 1] - [Action 2] ## Decisions Made - [Decision + rationale] ## Blockers - [Blocker if any] ## Next Steps - [What's next]
# [Event Description] **Date:** YYYY-MM-DD **Participants:** [Pat, Shogun, Forge] **Type:** meeting-notes | direction-change | scope-update ## Summary What happened and why it matters. ## Key Quotes / Direction - Pat said: "[direct quote if important]" - Decision: [what was decided] ## Impact What changed as a result.