agent-protocol

name	agent-protocol
description	Specification for making MUSE role files machine-readable as an Agent Protocol — enabling multi-agent coordination and tool interoperability

Agent Protocol Specification

Inspired by MemOS (multi-agent isolation + sharing) and multi-agent-memory (cross-agent persistence). Adapted for MUSE's pure Markdown zero-dependency architecture. Added in v2.12.0 (Batch 2 — competitive tech absorption).

Why

MUSE role files (.muse/*.md) currently work because AI Agents read Markdown and follow instructions. But as the ecosystem evolves toward multi-agent workflows (MCP servers, Claude Projects, multi-tool chains), role files need a machine-readable protocol — not just human-readable documents.

Problems this solves:

1. Agent handoff: When switching between Agents (e.g., Claude → Gemini), context should be portable
2. Multi-agent coordination: Multiple Agents working on the same project should respect role boundaries
3. Tool interoperability: MCP servers, IDE plugins, and CLI tools should be able to read/write role files

Protocol: MUSE Role File Spec v1.0

File Discovery

.muse/
├── strategy.md    # Strategy role
├── build.md       # Build/Dev role
├── growth.md      # Growth/Marketing role
├── qa.md          # QA/Verification role
├── gm.md          # General Manager role
├── ops.md         # Operations role
├── research.md    # Research role
├── fundraise.md   # Fundraise role
└── archive/       # Archived content (not loaded)

Discovery rule: Any .md file in .muse/ (excluding archive/) = a role file.

L0 Header (Machine-Readable Status Line)

Every role file MUST have an L0 comment as its first line:

<!-- L0: {version} | {top_priority} | {status_flags} -->

Parsed fields:

Field	Type	Description	Example
version	semver	Current project version	v2.11.0
top_priority	string	Most important current task	P0=竞品技术吸收Batch2
status_flags	csv	Comma-separated status indicators	QA PASS, 3 pending directives

L0 is the Agent's "at a glance" API — any tool can grep all L0 lines to get project status in ~400 tokens.

Section Protocol

Role files use Markdown headers as semantic sections. Tools should parse these:

Section Header Pattern	Semantic Meaning	Agent Action
## 📐 职责边界	Role boundaries table	Respect: only act within listed responsibilities
## ⏳ 待办 / ## 🎯 TODO	Pending tasks	Read for context; update checkboxes when completing
## 📡 已接收战略指令	Received directives	Check for pending work from other roles
## 📡 QA→BUILD 通知	Cross-role notifications	Process before starting new work
## 🛠️ 技术栈	Technology constraints	Respect in all code generation
## 📋 CHANGELOG 维护规则	Process rules	Follow during releases

Directive Protocol (📡)

Directives are the message-passing API between roles:

📡 **S{NNN}→{TARGET}**: {STATUS} **{TITLE}**
> {BODY}

Field	Format	Example
S{NNN}	Sequential ID	S041
{TARGET}	ROLE or PROJECT/ROLE	MUSE/BUILD, GROWTH
{STATUS}	🟡 (pending) / ✅ (received)	🟡 = needs pickup
{TITLE}	One-line summary	竞品深度调研回传
{BODY}	Blockquote detail	Full directive content

Pickup protocol:

1. Target role's /resume scans for 🟡 directives
2. On pickup: write to role file's 📡 已接收战略指令 section
3. Change source 🟡 → ✅ with timestamp

Memory Protocol

memory/
├── YYYY-MM-DD.md   # Daily log (short-term, raw)
├── archive/        # Old logs
MEMORIES.md          # Long-term knowledge (distilled + auto-captured)

Memory Type	File	Write Method	Read Method
Short-term	memory/YYYY-MM-DD.md	/bye Step 4	/resume Step ②
Long-term	MEMORIES.md	/distill (batch) + /bye Step 4.7 (auto-capture)	/resume Step ①
Constitutional	CLAUDE.md	Manual	Always loaded
User prefs	USER.md	/settings	/resume Step ④

Isolation Rules

┌─────────────────────────────────────────────┐
│ Agent Session (e.g., /resume build)         │
│                                             │
│  ✅ CAN READ:                               │
│  - Own role file (.muse/build.md)           │
│  - L0 lines of ALL role files               │
│  - memory/*.md                              │
│  - MEMORIES.md, CLAUDE.md, USER.md          │
│  - Source code & docs (on demand)           │
│                                             │
│  ✅ CAN WRITE:                               │
│  - Own role file                            │
│  - memory/YYYY-MM-DD.md                     │
│  - MEMORIES.md (auto-capture only)          │
│  - Source code (if build/dev role)           │
│                                             │
│  ❌ MUST NOT:                                │
│  - Write to other role files directly       │
│  - Create files outside .muse/ convention   │
│  - Discuss other roles' topics in depth     │
│                                             │
│  📡 CROSS-ROLE COMMS:                        │
│  - Only via directive protocol (📡 S{NNN})  │
│  - Sender writes directive to OWN file      │
│  - Receiver picks up during /resume         │
└─────────────────────────────────────────────┘

Multi-Project Protocol

For users managing multiple projects:

~/ProjectA/.muse/build.md     ← ProjectA's build role
~/ProjectB/.muse/build.md     ← ProjectB's build role
~/ProjectA/.muse/strategy.md  ← May hold cross-project directives

Cross-project directives use PROJECT/ROLE targeting:

📡 S041→MUSE/BUILD: 🟡 ...    ← Targets MUSE project's BUILD role
📡 S040→DYA/GROWTH: ✅ ...     ← Targets DYA project's GROWTH role

Path resolution: CLAUDE.md MAY specify absolute paths for cross-project strategy files:

> strategy.md 绝对路径: `/Users/jj/Desktop/DYA/.muse/strategy.md`

Integration Points

For MCP Servers

An MCP server implementing MUSE protocol is included — see scripts/mcp-server.sh (added in v2.15.0).

Tool	Description	Status
muse_get_status	Read all L0 lines → return project status	✅
muse_list_roles	List role files with summaries	✅
muse_get_role	Read a specific role file (L1)	✅
muse_send_directive	Create a 📡 directive in a role file	✅
muse_write_memory	Append to today's memory file	✅
muse_search_memory	Search across memory files + MEMORIES.md	✅

Configuration: Add to your MCP client config:

{
  "mcpServers": {
    "muse": {
      "command": "/path/to/muse/scripts/mcp-server.sh",
      "args": ["--project-root", "/path/to/project"]
    }
  }
}

For CLI Tools

# Get project status (all L0 lines)
grep "<!-- L0:" .muse/*.md

# Check for pending directives
grep "🟡" /path/to/strategy.md

# Count role file lines (bloat check)
wc -l .muse/*.md

For IDE Plugins

• Status bar: Show L0 summary of current role
• Sidebar: List pending directives (🟡)
• On save: Auto-update L0 line if role file changed

Version History

Version	Date	Changes
v1.1	2026-03-15	MCP server implemented (scripts/mcp-server.sh)
v1.0	2026-03-15	Initial spec (Batch 2)