163 lines
6.5 KiB
Markdown
163 lines
6.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 | done | ✅ GREEN LIGHT with caveat: pipe-pane unreliable. See `reference/PHASE-0-report.md`. |
|
||
| Phase 0.5 — Spike tmux Control Mode | done | ✅ VERDICT: Path B (control mode) recommended. See `reference/PHASE-0.5-report.md`. |
|
||
| Phase 1 — Sidecar | ready to start | Streaming path decided: tmux control mode (Path B). |
|
||
| 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 (control mode, not pipe-pane — see Phase 0.5) |
|
||
| `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 | Status | Frozen at | Owner of changes |
|
||
|---|---|---|---|---|
|
||
| IC-1 — WebSocket frame protocol | `PHASE-1-sidecar.md` §Interface Contracts | **draft** — needs orchestrator sign-off before T-1.5 starts | — | 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 | **draft** | — | T-1.5..T-1.7 leads |
|
||
| IC-3 — Pairing payload | `PHASE-1-sidecar.md` §Interface Contracts | **draft** | — | T-1.3 lead |
|
||
| IC-4 — Config TOML schema | `PHASE-1-sidecar.md` §Interface Contracts | **draft** | — | T-1.7 lead |
|
||
| IC-2.1 — `SessionConnection` Swift surface | `PHASE-2-ios-mvp.md` §Interface Contracts | **draft** — freeze at Phase 2 kickoff | — | T-2.5 lead |
|
||
|
||
**Freeze protocol:** when the orchestrator is ready to fan out work that
|
||
depends on a contract, they (a) re-read the contract spec, (b) update the
|
||
Status column to `frozen` and fill in the `Frozen at` date, (c) commit
|
||
that change to main. After that, modifications require a CCR.
|
||
|
||
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
|
||
```
|
||
|
||
```
|
||
2026-05-15 @worker-phase0 T-0.* Phase 0 spike complete. tmux+pipe-pane PoC validated. GREEN LIGHT for Phase 1. Report: reference/PHASE-0-report.md. Branch: feat/spike-stream (kept for reference, not merged).
|
||
2026-05-15 @worker-phase0.5 T-0.5 Phase 0.5 spike complete. tmux control mode validated. VERDICT: Path B recommended. Report: reference/PHASE-0.5-report.md. Branch: feat/spike-tmux-cc (kept for reference, not merged).
|
||
```
|