# AI Coordination Protocol

## Required reading at session start

- **[working-with-sam.md](./working-with-sam.md)** — Operating manual. How Sam thinks, what helps, what gets in the way. Read this first every session.
- [shared-state.md](./shared-state.md) — Current cross-AI state snapshot.
- [planning-to-cc.md](./planning-to-cc.md) — Queue from planning chat to CC.

## Purpose

Make CC (Claude Code) and planning chat collaborate without Sam manually relaying everything between them.

Sam runs two AI sessions in parallel:
- **CC** — does the file-system + git + deploy work in the substrate repo
- **Planning chat** — strategic thinking, paste-driven, broader context

Without coordination, Sam is the message broker for every cross-AI handoff. That's a bottleneck and a bandwidth drain.

This folder is the **shared bulletin board**: both AIs read/write here so they can collaborate via the substrate instead of through Sam's working memory.

## The 3 files

| File | Direction | Updated by |
|---|---|---|
| `cc-to-planning.md` | CC → Planning chat | CC at end of session |
| `planning-to-cc.md` | Planning chat → CC | Sam pastes from planning chat |
| `shared-state.md` | Both directions | Either AI when status shifts |

## How CC uses this

1. **At start of CC session** — Read `planning-to-cc.md` and `shared-state.md` for context Sam may not have pasted directly
2. **During session** — Note any items planning chat should consider
3. **At end of session** — Update `cc-to-planning.md` with anything strategic for planning chat to address
4. **Also update** — `shared-state.md` if focus / blockers / energy signals change

## How planning chat uses this (via Sam)

1. **At start of planning chat session** — Sam pastes contents of `cc-to-planning.md`
2. **During session** — Planning chat sees CC's perspective naturally; can argue with it
3. **At end of session** — Sam pastes planning chat's response into `planning-to-cc.md`
4. **Shared state** — Both AIs read at session start

## Why this matters

- Reduces Sam's message-broker burden
- Both AIs see each other's perspective in writing (better than translation through Sam)
- Substrate becomes the persistent memory across both sessions
- **Foundation for SameI Tier 1** — the inbox processor pattern that will eventually be automated via Claude API ([see SameI vision](/personal/ai-hub/samei/))

## Convention: signal vs noise

Keep these files **terse and current**. They are not project documents — they are working bulletin boards.

- ✅ Specific open questions, current focus, observed signals
- ❌ Long histories, completed work catalogs, narrative

When an item resolves, move it to a one-line "recently resolved" section, then prune after 1 week.

## Lifecycle of an item

```
[CC drafts in cc-to-planning.md]
   ↓
Sam pastes to planning chat
   ↓
[Planning chat responds, Sam pastes to planning-to-cc.md]
   ↓
CC reads at next session start
   ↓
CC acts on it OR raises follow-up
   ↓
Item marked [RESOLVED] with one-line outcome
```

Same loop in reverse for planning-initiated items.