upstream-sync

---
name: upstream-sync
description: 'Investigate a local web app against the upstream product it clones (a local claude.ai/code browser, a Workflowy replica), feature by feature, with serial browser investigators (a recursive Workflow in Claude Code, a hand-run loop in Codex), produce per-feature gap files with red/green TDD tasks plus a prioritized roadmap, then implement the roadmap on agent branches gated into a known-good local main. Use when the user wants to sync, diff, or reach parity with upstream, or to find everything upstream has that the local app lacks.'
---

# Upstream sync

Bring a local app to near-exact parity with the upstream product it mirrors: same features, DOM structure, class names and CSS values, minus anything with no local meaning. The investigation only writes under `.llm/upstream-sync/`. Implementation comes afterward, from the roadmap, on agent branches that each pass a per-commit gate before local `main` moves.

The engine is a Workflow script, `<plugin-root>/scripts/upstream-sync-workflow.js`. Resolve `<plugin-root>` first: in Claude Code use `${CLAUDE_PLUGIN_ROOT}`; in Codex use the plugin root that contains this `skills/upstream-sync/SKILL.md` file. Codex has no Workflow tool, so it runs the same phases by hand; see the Codex section below. The script runs:

- **Broad:** a code-only local inventory and a browser survey of upstream, in parallel. The survey seeds the feature queue.
- **Investigate:** one browser investigator per feature, strictly serial because they share Chrome. Priority order is P1, then P2, then P3. Each investigator writes `features/<slug>.md` and returns any new features it discovered, which join the queue, so the investigation recurses.
- **Critic:** up to `maxCriticRounds` completeness reviews, each adding missed features, until a round adds nothing.
- **Synthesize:** `SUMMARY.md`, a roadmap ordered by milestone.

The orchestrator owns `features.md` and rewrites it every `registryEvery` investigations. Investigators never edit it, so the queue never gets duplicate or conflicting rows.

## Settle the safety model before anything else

Find out whether interacting with upstream or the local app changes real data. For example, both sides may write to the user's real account, or opening a page may create a record. Ask the user (with AskUserQuestion in Claude Code), offering these options:

- **Sandbox:** create one dedicated container, such as a top-level node, a scratch project or a test document. Investigators may edit only inside it, and may only read everywhere else.
- **Strictly read-only:** no edits anywhere. Editing behavior is decoded from the DOM and the JS bundle.
- **User performs edits:** investigators stop and ask the user to take any action that mutates data.

Also check whether an upstream page is bridged to something live outside the browser. Existing claude.ai sessions, for example, may be connected to running local terminals, so a keystroke in the wrong tab acts on the user's machine. The rules must then name the only pages where writes are allowed (for claude.ai: the bare new-session page, or a session the agent created itself), and every agent must re-read `location.href` in the same step as any type, click or key action. A screenshot taken before an earlier action proves nothing about where the next one lands.

Create the sandbox through the project's own write path (its CLI or API), never by editing a cache or database directly. Then verify that it exists, and that it exists exactly once.

Write the rules as concrete, checkable instructions. Include the sandbox's id and URL, and the shortcuts that act on the focused item, so investigators verify focus before pressing them. These rules become the `safety` arg.

## Lay out the sync directory

Create `.llm/upstream-sync/` and confirm it is gitignored. Then fill it:

- `README.md`: copy `protocol-template.md` from this skill's directory and replace every `{{PLACEHOLDER}}`. `{{CONTEXT}}` says how the local app differs from upstream on purpose: local extras to keep, upstream features that will never apply.
- `features.md`: a stub. The workflow overwrites it once the survey finishes.
- `features/` and `dumps/`: create empty.

If an earlier sync left this directory behind, read its `README.md` Tips and `SUMMARY.md` first. Carry the lessons forward instead of starting over.

To reuse an earlier run's queue, pass it as `seed` instead of re-surveying. Audit `features.md` first: a row marked `done` is only real if its `features/<slug>.md` exists and its notes describe findings. A row whose notes say the agent declined, answered another question, or did not investigate is a placeholder; seed it without `existing`. Seed real rows with `existing: true`, and seed `todo` and `failed` rows as they are.

## Verify the local app is running

Check that the local dev server is listening on the expected port and that an HTTP request returns a non-error response, before launching. Also confirm the user is logged in to upstream in the browser profile your browser tools drive: claude-in-chrome in Claude Code, or whichever browser MCP is connected in Codex. If no browser tool is available, stop and tell the user; the investigation can't run on code alone.

## Launch the workflow

Call Workflow with `scriptPath: <plugin-root>/scripts/upstream-sync-workflow.js` and these `args`:

| Arg                           | Meaning                                                                                                                                                                                                               |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dir`                         | Absolute path of the sync directory                                                                                                                                                                                   |
| `upstreamName`, `upstreamUrl` | The product being cloned and where to reach it                                                                                                                                                                        |
| `localName`, `localUrl`       | The local app and its running dev URL                                                                                                                                                                                 |
| `localSource`                 | Absolute path of the local source                                                                                                                                                                                     |
| `context`                     | Intentional differences, as in `{{CONTEXT}}`                                                                                                                                                                          |
| `safety`                      | The concrete safety rules; this text goes into every browser prompt                                                                                                                                                   |
| `surveyFocus`                 | Optional: surfaces and features to make sure the survey covers                                                                                                                                                        |
| `inventoryFocus`              | Optional: local areas to make sure the inventory covers                                                                                                                                                               |
| `acknowledgedIncidents`       | Optional: slugs whose investigator incidents the user has reviewed, so a resumed run records them and continues                                                                                                       |
| `approvedExceptions`          | Optional: actions the user approved after an incident; this text goes only into investigator prompts                                                                                                                  |
| `acknowledgeSurveyIncidents`  | Optional: true once the user has reviewed a survey incident, so a resumed run continues                                                                                                                               |
| `only`                        | Optional: a list of `{slug, name, priority, notes}` to re-investigate, skipping the broad and critic phases and merging rows into `features.md`                                                                       |
| `seed`                        | Optional: a list of `{slug, name, priority, notes, existing?}` that replaces the broad phase; critic rounds still run. `existing: true` makes the investigator re-verify that feature's file instead of rebuilding it |
| `maxInvestigations`           | Default 150; anything left over is listed as not investigated                                                                                                                                                         |
| `maxCriticRounds`             | Default 3                                                                                                                                                                                                             |
| `registryEvery`               | Default 6; how often `features.md` is rewritten                                                                                                                                                                       |

Launch or resume the run only in a turn where the user's latest message asks for it. Workflow subagents read the user's most recent message as the request they are serving. When that message was an unrelated question, investigators declined the browser work and returned placeholder results, wasting a hundred investigations. They now report `investigated: false`, which counts as a failure, but the cost is still a retry per feature. If the run needs relaunching after the user asked something else, ask them to say so first.

The run is long. Tell the user the run id, that `/workflows` shows progress, and that `features.md` plus the `features/` file count are the live progress readout.

## Run it in Codex

Codex has no Workflow tool, so you are the orchestrator and do by hand what the script does. The script stays the single source of truth for the briefs: read `<plugin-root>/scripts/upstream-sync-workflow.js` and reuse its local-inventory, survey, investigator, critic and summary prompts verbatim, filling each `${...}` from the same args you would have passed.

- Run the broad phase: the local inventory (code only), then the upstream survey.
- Keep the queue in `features.md` yourself, as the script's `writeRegistry` does: dedup slugs case-insensitively, and always take the next `todo` row in P1, then P2, then P3 order.
- Investigate one feature at a time. If Codex can start subagents, give each investigator its own subagent so the browser dumps stay out of your context. Otherwise investigate in your own context and keep only the feature file's summary line. Never run two browser investigations at once.
- After each investigation, add the features it discovered to `features.md`, and check its safety report. Stop at the first incident, exactly as the script would.
- A dead investigator gets one retry with the script's retry note; after that, mark it `failed`.
- When the queue is empty, run critic rounds until one adds nothing (at most 3), then write `SUMMARY.md` with the summary prompt.
- Long runs outlive one Codex session. `features.md` is the resume point: a fresh session continues from the first `todo` row.

## While it runs

Don't edit the local source. The dev server hot-reloads under the investigators, and the findings would describe a moving target. Batch any bugs worth fixing until the run ends.

## When it halts on a safety incident

The workflow stops at the first reported incident. A survey incident stops it before any investigation; an investigator incident stops it after that investigation, and the summary is still written.

- Verify the damage independently through a primary source, such as the upstream API or the project's CLI. An agent's report that it undid something is not proof.
- Report what happened and what you verified, and ask the user how to continue.
- To resume, re-invoke Workflow with the persisted script path from the original result and `resumeFromRunId`, so completed agents replay from cache. Keep `safety`, `context` and the survey args unchanged: changing any text in a cached prompt re-runs that agent and everything after it. Put newly approved actions in `approvedExceptions`, set `acknowledgeSurveyIncidents: true` when the incident came from the survey, and add the investigator's slug to `acknowledgedIncidents` when it came from an investigator; neither changes a prompt, so the cache still replays. Update the README's Tips to match the decision.

## When investigators fail

An investigator whose agent dies (a network drop, a terminal API error) is retried once automatically, with a prompt that tells it to reuse any partial dumps. If the retry dies too, the feature is marked `failed` and the run moves on. Don't stop the run to fix it: the result lists the failed slugs. After the run finishes, launch a fresh Workflow with the same args plus `only` set to those features (take name, priority and notes from `features.md`). Never run it while the main run is still going, because the two would fight over the browser.

## After the run

Read `SUMMARY.md` and the result's `notInvestigated` and `failed` lists, and report them. The usual next step is to import the roadmap into `.llm/todo.md` with the markdown-tasks import-plan skill, then implement it.

## Implement the roadmap

Implementers may run in parallel, each on its own branch. Local `main` is the base every new worktree starts from, so it must always be known-good: it only fast-forwards, and only to commits that are already rebased onto it and already pass `git test run` per commit. Never cherry-pick work onto main and gate it afterwards.

Integrate each implementer branch with the same loop as the git plugin's rebase-all skill and the build plugin's test-all skill, scoped to one branch with local `main` as the base:

1. Create the branch and its worktree from local `main` (`git worktree add -b <branch> <path> main`). Agent worktree isolation branches from `origin/main` instead, so don't rely on it.
2. When the implementer finishes, rebase the branch onto `main` and run `git test run main..<branch>`.
3. Repair each failure in a subagent, as test-all does: fix it, commit with `git commit --fixup <breaking sha>`, replay the rest of the branch with `git replay --onto HEAD HEAD^..<branch>`, then `GIT_SEQUENCE_EDITOR=true git rebase --autosquash main`. Rerun `git test run main..<branch>` until every commit passes. Never run `git test forget-results`.
4. From main's worktree, `git merge --ff-only <branch>`.
5. Delete the branch and its worktree.

If a commit doesn't rebase or cherry-pick cleanly, abort. Don't rescue it by resolving the conflict, and don't read the conflicting diff. Wait until no other branch is integrating, then redo that task serially in a fresh subagent from its task description, on a new branch from `main`.

Tests that validate the user's live on-disk data, such as a schema check against real files, fail on every commit before the schema-drift fix that makes them pass. Put schema-drift fixes first, or fold them into the branch's first commit, before gating; otherwise every earlier commit reports a failure that isn't its own.

When `origin/main` moves, rebase promptly, while the gap is a few commits rather than dozens. git-test caches results per tree, so a rebase invalidates every result on the rebased commits and a long-diverged one forces a full re-gate. Rebase main's unpushed commits onto `origin/main` on a temporary branch, gate it with `git test run origin/main..<temp>`, and only then move `main` to it; then rebase the in-flight work branches onto the new `main`.

Keep the branch count minimal so the user can follow the state: delete merged, backup and leftover branches as soon as they stop being needed. Report the state as "`main` (known good, N ahead of `origin/main`) + these work branches".

Parity checks in the browser during implementation follow the same data-safety rules as the investigation, including the `location.href` check before every write action.

Append any lesson that would help the next project to the Tips section of `protocol-template.md` in this plugin, not only to the project's README.

• SKILL.md 17 KB
• protocol-template.md 4 KB