5.5 KiB

Raw Blame History

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

Every concrete work item lives in a phase plan as T-<phase>.<n>.
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.
When the task is done (PR merged) the agent removes its claim row and appends a one-line entry to History.
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)

5.5 KiB Raw Blame History Unescape Escape