159 lines
5.5 KiB
Markdown
159 lines
5.5 KiB
Markdown
# SYNC — Multi-Agent Coordination
|
||
|
||
> **Purpose:** allow several agents (human or AI) to work concurrently on
|
||
> this codebase without stepping on each other.
|
||
>
|
||
> **Scope:** all phases. This document is the live coordination surface;
|
||
> the phase plans (`PHASE-0..PHASE-3`) are immutable plans, this file
|
||
> tracks who is doing what *right now*.
|
||
|
||
---
|
||
|
||
## How this works
|
||
|
||
1. Every concrete work item lives in a phase plan as `T-<phase>.<n>`.
|
||
2. Before starting work on a task, an agent:
|
||
- Pulls latest `main`.
|
||
- Edits the **Active Claims** table below to add a row claiming the
|
||
task with its branch name, owner handle, and timestamp.
|
||
- Commits that edit on `main` directly (small, low-conflict).
|
||
- Then opens the feature branch and works.
|
||
3. When the task is done (PR merged) the agent removes its claim row and
|
||
appends a one-line entry to **History**.
|
||
4. If a task needs to **change a frozen interface contract** (IC-1..IC-4
|
||
from Phase 1, IC-2.1 from Phase 2), the agent must:
|
||
- Open a section under **Contract Change Requests** below.
|
||
- Wait for at least one other active agent (or the orchestrator) to
|
||
acknowledge by editing the row to `acked: <handle>`.
|
||
- Only then implement the change.
|
||
|
||
The point: no central scheduler is required. A short structured edit on
|
||
`main` is the lock.
|
||
|
||
---
|
||
|
||
## Phase Gate
|
||
|
||
| Phase | Status | Notes |
|
||
|---|---|---|
|
||
| Phase 0 — Spike Stream | not started | First task. See `PHASE-0-spike-stream.md`. |
|
||
| Phase 1 — Sidecar | blocked on Phase 0 | Can begin only after Phase 0 verdict is green. |
|
||
| Phase 2 — iOS MVP | blocked on Phase 1 | Sidecar must be reachable and stable. |
|
||
| Phase 3 — iOS Augmentation | blocked on Phase 2 | Continuous after MVP ships. |
|
||
|
||
Update the **Status** column when a phase transitions. Allowed states:
|
||
`not started`, `in progress`, `blocked on …`, `done`.
|
||
|
||
---
|
||
|
||
## Active Claims
|
||
|
||
| Task | Branch | Owner | Claimed at | ETA | Notes |
|
||
|---|---|---|---|---|---|
|
||
| _(none)_ | | | | | |
|
||
|
||
Example of a filled row:
|
||
```
|
||
| T-1.1 | feat/p1-t1-1-tmux-manager | @jay | 2026-05-20 14:00 | +2d | starting with manager.ts |
|
||
```
|
||
|
||
Rules:
|
||
- **One row per task.** A task can have only one active owner.
|
||
- **Owner** = the agent's handle (`@jay`, `@worker-1`, `@scout`, etc.).
|
||
- **ETA** is a rough estimate; missing it is OK, but if a row is stale > 2× ETA, anybody may reclaim after pinging.
|
||
- **Branch** must exist on the remote within 24h of the claim, otherwise
|
||
the row is considered abandoned and may be removed.
|
||
|
||
---
|
||
|
||
## File Ownership Map
|
||
|
||
For each high-traffic file, the table below lists the tasks that may
|
||
legitimately modify it. If you need to touch a file outside this list,
|
||
add a row or open a Contract Change Request.
|
||
|
||
| File | Authorised Tasks |
|
||
|---|---|
|
||
| `extensions/remote-control/index.ts` | T-1.0, T-1.4 (events wiring only) |
|
||
| `extensions/remote-control/server.ts` (legacy) | nobody after T-1.0; legacy frozen |
|
||
| `extensions/remote-control/server/**` | T-1.0 (refactor), T-1.5, T-1.6, T-1.7 |
|
||
| `extensions/remote-control/tmux/**` | T-1.1 |
|
||
| `extensions/remote-control/buffer/**` | T-1.2 |
|
||
| `extensions/remote-control/sequence.ts` | T-1.2 |
|
||
| `extensions/remote-control/auth/**` | T-1.3, T-1.10 (device tokens only) |
|
||
| `extensions/remote-control/pi/**` | T-1.4 |
|
||
| `extensions/remote-control/apns/**` | T-1.10, Phase-2 T-2.9 (when iOS supplies tokens) |
|
||
| `extensions/remote-control/cli/**` | T-1.3, T-1.7 |
|
||
| `extensions/remote-control/config.ts` | T-1.7 |
|
||
| `docs/SYNC.md` | all (this file) |
|
||
| `docs/PHASE-*.md` | nobody once a phase has started (frozen plan) — open a CCR to amend |
|
||
| `docs/reference/**` | nobody during implementation — archival |
|
||
|
||
For the iOS repo `pi-remote-ios`, an analogous map will be added when
|
||
Phase 2 kicks off.
|
||
|
||
---
|
||
|
||
## Frozen Interface Contracts
|
||
|
||
| ID | Defined in | Owner of changes |
|
||
|---|---|---|
|
||
| IC-1 — WebSocket frame protocol | `PHASE-1-sidecar.md` §Interface Contracts | T-1.5 lead, with sign-off from any active T-2.x owner |
|
||
| IC-2 — HTTP REST shape | `PHASE-1-sidecar.md` §Interface Contracts | T-1.5..T-1.7 leads |
|
||
| IC-3 — Pairing payload | `PHASE-1-sidecar.md` §Interface Contracts | T-1.3 lead |
|
||
| IC-4 — Config TOML schema | `PHASE-1-sidecar.md` §Interface Contracts | T-1.7 lead |
|
||
| IC-2.1 — `SessionConnection` Swift surface | `PHASE-2-ios-mvp.md` §Interface Contracts | T-2.5 lead |
|
||
|
||
Once a contract is *frozen* (i.e. at least one consumer task has started
|
||
work that depends on it), changes require a CCR.
|
||
|
||
---
|
||
|
||
## Contract Change Requests (CCR)
|
||
|
||
Format:
|
||
|
||
```
|
||
### CCR-YYYY-MM-DD-<slug>
|
||
- **Contract**: IC-1 / IC-2 / …
|
||
- **Proposer**: @handle
|
||
- **Motivation**: 1-3 sentences.
|
||
- **Proposed change**: diff or prose.
|
||
- **Affected tasks**: list.
|
||
- **Status**: open | acked by @… | merged | rejected
|
||
```
|
||
|
||
_(none open)_
|
||
|
||
---
|
||
|
||
## Cross-Phase Notes
|
||
|
||
Threads that don't belong in a single phase plan.
|
||
|
||
- **Spec deviations.** If implementation reveals that a spec item is
|
||
wrong or unbuildable, write a short note here under **History**, plus
|
||
open a CCR if it changes a frozen contract. The spec itself stays
|
||
immutable until a v4 review round.
|
||
- **Risks materialised.** When a `Risks` row from a phase plan actually
|
||
hits, log it here with the workaround used.
|
||
- **Tools / shared scripts.** Anything added under `scripts/` that's
|
||
reused across tasks gets a one-liner here.
|
||
|
||
---
|
||
|
||
## History
|
||
|
||
Append-only log of completed work and notable events. One line each.
|
||
|
||
```
|
||
yyyy-mm-dd @handle T-x.y what was done
|
||
```
|
||
|
||
Example:
|
||
```
|
||
2026-05-15 @jay init docs reorganised; phase plans + SYNC created
|
||
```
|
||
|
||
(populated as work happens)
|