# 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