| name | dream-sync |
| description | Load when the user asks to sync/reconcile the dreamcontext brain repo with a team (a shared `_dream_context/` git remote), or when `dreamcontext brain sync` (or the SessionStart snapshot) reports a team merge awaiting resolution. Triggers: "/dream-sync", "sync the brain", "reconcile with the team", "resolve the brain merge conflict", "already-awaiting-agent", "awaiting-agent", "pending team-merge handoff". This is the agent half of the semantic-merge contract: the CLI resolves every deterministic file (JSON changelog/releases/config/taxonomy, task status + changelog) automatically and only ever defers PROSE files (knowledge/features) where two people edited the same section — you read base/ours/theirs snapshots and write the actual semantic merge, then hand back to the CLI to commit + push.
|
| user-invocable | true |
| alwaysApply | false |
| tags | ["sync","brain-repo","git","merge","collaboration","dreamcontext"] |
/dream-sync — the agent half of the brain-repo merge contract
You are the semantic merge resolver. The CLI (dreamcontext brain sync) already did
everything it safely can on its own: every JSON class (changelog, releases, config, taxonomy) and
every task markdown file were merged and committed automatically — set-unions and furthest-status
logic never lose data and never need judgment. The ONLY thing left for you is prose that two
people edited in the same ## section of a knowledge file or feature doc — a case the CLI
correctly refuses to resolve on its own (see references/merge-rules.md — the "C1 discard
contract"), because a naive textual merge mangles Markdown and a "remote wins" default would
silently throw away one author's words.
Read references/merge-rules.md before touching anything — it is the single source of truth
for the deterministic rules, the CLI-vs-agent split, and the full pull-only → resume → resolve →
continue state machine you are stepping into.
Step 1 — determine the handoff state
Run dreamcontext brain status. It reports two independent booleans:
mergeInProgress (a real git MERGE_HEAD exists) — the classic path: brain sync (auto
mode) hit an agent-class conflict directly and left the merge open.pendingAgentMerge (no MERGE_HEAD, but a report was deferred) — the pull-only path: a
headless background pull (session-start) hit the same conflict, but pull-only NEVER leaves the
tree mid-merge — it aborted back to a clean commit and recorded the defer for you to redo
attended.
Branch on exactly these two signals (equivalently: a plain dreamcontext brain sync returning
already-awaiting-agent tells you one of the two is true, without telling you which):
| State | What to do |
|---|
mergeInProgress: true | Go straight to Step 2 (report already exists, real MERGE_HEAD). |
pendingAgentMerge: true, mergeInProgress: false | Run dreamcontext brain sync --resume FIRST. If it returns pushed or pulled, the handoff is DONE — the remote moved on and nothing needed your judgment. If it returns awaiting-agent, a FRESH report + a real MERGE_HEAD now exist — go to Step 2. |
| Neither | Just run dreamcontext brain sync (normal on-demand sync) — nothing to resolve. |
You never call --resume when a MERGE_HEAD is already there, and you never skip --resume
for a pendingAgentMerge-only state — the CLI enforces this with invalid-flag, but don't rely
on that as your only guardrail; read the state first.
Step 2 — read the report and resolve each deferred file
Read _dream_context/state/.brain-merge/report.json. For each entry in deferred:
- Read the three snapshots it names:
basePath (common ancestor), oursPath (this machine's
version), theirsPath (the remote/teammate's version) — all under state/.brain-merge/.
- Write the semantically-merged content directly into the REAL file at
path (repo-relative,
possibly under an _dream_context/ prefix in in-tree mode — strip it to find the file on disk).
Preserve both authors' intent: don't just pick one side. For a knowledge/feature doc, merge
section-by-section — sections only one side touched keep that side's version; sections BOTH
touched are the ones you're here for — read them and write prose that keeps both people's point,
reconciling wording, not concatenating raw diffs.
- Stage it — run
git add <path> at the project root (the git root is the project folder, so
path carries the _dream_context/ prefix).
Do this for every entry in deferred before moving on — --continue commits everything staged in
one shot.
Step 3 — hand back to the CLI
Run dreamcontext brain sync --continue. It re-scrubs (a secret can be reintroduced by a merge —
never skip this), commits, and pushes (retrying once on a non-fast-forward race). On success the
report and its snapshot files are gone, pendingAgentMerge flips back to false, and a normal
brain sync runs cleanly from here on. If it instead reports blocked-scrub, something you wrote
looks like a secret or a local path — fix it and re-run --continue.
What you must NEVER do
- Never call
--resume or --continue unattended / speculatively — they are the explicit
ATTENDED gates for exactly this handoff. sleep done's autoSync, the session-start background
pull, and the dashboard all stop at already-awaiting-agent and print the instruction to run
/dream-sync — they never drive these flags themselves.
- Never write the CLI's discarded remote-wins output for a deferred knowledge/feature file —
if you see
report.json's deferred entry for a path, that means the CLI's own attempt was
thrown away specifically because it would have clobbered one side; only your snapshot-based
merge is authoritative for that file.
- Never hand-edit
.brain-merge/report.json or its snapshots — they are inputs, not outputs.
