Add README documentation for mcp and state directories
- mcp/README.md: Document Gmail setup, delegation helpers, MCP patterns - state/README.md: Document state files, ownership, and subdirectories Completes documentation coverage for all major directories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OpenCode Test
88
mcp/README.md
Normal file
88
mcp/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# MCP Integrations
|
||||
|
||||
Model Context Protocol servers and delegation helpers.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
mcp/
|
||||
├── gmail/ # Gmail OAuth setup and venv
|
||||
│ ├── venv/ # Python virtual environment
|
||||
│ └── ...
|
||||
└── delegation/ # Tiered delegation helpers
|
||||
├── gmail_delegate.py
|
||||
└── gcal_delegate.py
|
||||
```
|
||||
|
||||
## Gmail Integration
|
||||
|
||||
### Setup
|
||||
|
||||
The Gmail integration uses a Python virtual environment with `gmail-mcp`:
|
||||
|
||||
```bash
|
||||
# Create venv (one time)
|
||||
cd ~/.claude/mcp/gmail
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install gmail-mcp
|
||||
|
||||
# Credentials
|
||||
# OAuth credentials at: ~/.gmail-mcp/credentials.json
|
||||
# Token cached at: ~/.gmail-mcp/token.json
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Skills reference the venv directly:
|
||||
|
||||
```bash
|
||||
~/.claude/mcp/gmail/venv/bin/python script.py
|
||||
```
|
||||
|
||||
## Delegation Helpers
|
||||
|
||||
Helpers that implement tiered model delegation:
|
||||
|
||||
| Helper | Purpose | Tiers |
|
||||
|--------|---------|-------|
|
||||
| `gmail_delegate.py` | Gmail operations | Haiku (list), Sonnet (summarize) |
|
||||
| `gcal_delegate.py` | Calendar operations | Haiku (list), Sonnet (analyze) |
|
||||
|
||||
### Pattern
|
||||
|
||||
```bash
|
||||
GMAIL_PY=~/.claude/mcp/gmail/venv/bin/python
|
||||
HELPER=~/.claude/mcp/delegation/gmail_delegate.py
|
||||
|
||||
# Haiku tier - no LLM, just fetch
|
||||
$GMAIL_PY $HELPER check-unread --days 7
|
||||
|
||||
# Sonnet tier - spawns claude --model sonnet
|
||||
$GMAIL_PY $HELPER summarize --query "from:github.com"
|
||||
```
|
||||
|
||||
## Adding MCP Servers
|
||||
|
||||
For proper MCP servers (vs. delegation helpers):
|
||||
|
||||
1. Create server in `mcp/server-name/`
|
||||
2. Add to `.mcp.json` or `plugin.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server-name/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Note
|
||||
|
||||
Current integrations use direct Python API calls rather than MCP protocol.
|
||||
This works but doesn't leverage MCP's tool registration and permissions.
|
||||
|
||||
Future improvement: Convert to proper MCP servers.
|
||||
81
state/README.md
Normal file
81
state/README.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# State Files
|
||||
|
||||
Shared state for the multi-agent system. JSON format for machine readability.
|
||||
|
||||
## Top-Level State
|
||||
|
||||
| File | Purpose | Writer |
|
||||
|------|---------|--------|
|
||||
| `system-instructions.json` | Central process definitions | master-orchestrator |
|
||||
| `future-considerations.json` | Deferred features/decisions | master-orchestrator |
|
||||
| `model-policy.json` | Model selection rules | master-orchestrator |
|
||||
| `autonomy-levels.json` | Autonomy level definitions | master-orchestrator |
|
||||
| `component-registry.json` | Skills, commands, agents for routing | master-orchestrator |
|
||||
| `personal-assistant-preferences.json` | PA persistent config | personal-assistant |
|
||||
| `kb.json` | Shared knowledge base | personal-assistant |
|
||||
|
||||
## Subdirectories
|
||||
|
||||
### `personal-assistant/`
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `general-instructions.json` | User memory (via `/pa --remember`) |
|
||||
| `session-context.json` | Session context override |
|
||||
| `kb.json` | PA-specific knowledge base |
|
||||
| `history/index.json` | Session history index |
|
||||
| `memory/decisions.json` | Recorded decisions |
|
||||
| `memory/preferences.json` | Learned preferences |
|
||||
| `memory/projects.json` | Project context |
|
||||
| `memory/facts.json` | Environment facts |
|
||||
|
||||
### `sysadmin/`
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `session-autonomy.json` | Per-session autonomy override |
|
||||
|
||||
### `programmer/`
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `projects/*.json` | Registered project configurations |
|
||||
|
||||
### `usage/`
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `config.json` | Usage tracking configuration |
|
||||
|
||||
## File Format
|
||||
|
||||
All state files use JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"description": "What this file contains",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Reading State
|
||||
|
||||
Agents read state at session start:
|
||||
|
||||
```bash
|
||||
cat ~/.claude/state/system-instructions.json
|
||||
```
|
||||
|
||||
## Writing State
|
||||
|
||||
- **master-orchestrator**: Primary writer for top-level state
|
||||
- **personal-assistant**: Override authority, writes to PA state
|
||||
- **linux-sysadmin**: Writes to `sysadmin/` state
|
||||
|
||||
## Principles
|
||||
|
||||
1. **No duplication** - Each fact in one place only
|
||||
2. **JSON format** - Machine readable
|
||||
3. **Clear ownership** - Each file has one primary writer
|
||||
4. **Override authority** - PA can override master-orchestrator
|
||||
Reference in New Issue
Block a user