Sync Upstream

Keep prompts/base/, prompts/lean/, the prompt-bundle modifiers, and the model table in src/env.ts aligned with what Claude Code actually sends.

This is an investigation, not a checklist. The sections below describe what has to be true when you're done and the tools available to get there — how you sequence them is yours to judge. Two things are not yours to judge: confirm the target version before doing the work, and get changes approved before applying them.

What "aligned" means

Three prompt shapes exist upstream, assembled by one function that forks on a model-capability predicate. All three matter here:

Capabilities also drive --base auto, so the model table in src/env.ts is part of the sync, not a side note: a new flagship changes which base users get by default.

references/fragment-map.md holds the current local↔upstream mapping and the marker strings to find each piece. references/intentional-omissions.md holds every difference that is deliberate.

Ground truth and how to reach it

bun run scripts/extract-upstream-prompt.ts [version] pulls named prompt functions into upstream-prompts/. It is the fastest path for what it covers, which is the standard head and not much else. It does not extract the shared tail, the lean head, the bundle sections, or model capabilities.

For anything it misses, grep the release binary directly:

npm pack @anthropic-ai/claude-code-linux-x64@<version> && tar xzf *.tgz   # → package/claude

It's ~275 MB, so slice by byte offset in Python rather than running wide regexes:

data = open("package/claude","rb").read()
i = data.find(b"<marker text>")
print(data[i-4000:i+4000].decode("utf8","replace"))

Useful anchors: search a distinctive sentence to land in the assembler, then read outward. strings -n 8 package/claude | grep -o 'id:"claude-[a-z0-9-]*"[^}]\{0,220\}' gets the model table with its capabilities arrays.

Diffing two extractions is the cheapest first move. If a previous version's file is still in upstream-prompts/, diff it against the new one — most releases are pure minifier churn (ja_ → aO_) with one or two real sentence changes, and the diff isolates them in seconds. Ignore renamed symbols, template-variable syntax, and whitespace; they are noise.

You may be running under one of these prompts yourself. If so, your own system prompt is a live sample of what a real session receives — worth more than inference about which branch fires. Use it to confirm, and say so when you report.

Finding what isn't on the map

The mapping files are a record of what we already know. Diffing only against them can never surface content we never tracked — that blind spot is exactly how the shared tail sections went missing from prompts/base/ for several releases.

So each sync, spend some effort in the other direction: read the assembler's return value and account for every section it can emit. For each one, land in a category and be able to say which:

• tracked in a local fragment
• documented as an intentional omission
• genuinely inapplicable — session-, environment-, or experiment-gated (a flag that fires on one model, a background-session block, an output-style hook)
• unaccounted for — a real gap, whether or not the current release changed it

Watch for gates that turn out to mean something other than their name suggests. A branch filed as "some terser variant" may be a whole prompt shape; a "compact" mode may be reachable on exactly one model in one experiment. When a gate's meaning is unresolved, resolving it is usually higher-value than diffing another fragment, because an unresolved gate can hide an entire category of content.

Classifying a difference

• Intentional omission — matches a documented entry. Leave it; if the upstream wording moved, update the quote in the reference so future diffs still match.
• Local addition — we carry content upstream doesn't (gitStatus block, tool-agnostic rewrites of tool names). Leave it.
• Drift — upstream changed and we haven't. Candidate to apply.
• Unaccounted — from the sweep above. Report it separately; it usually needs a new fragment or a new omission entry, which is a decision, not a mechanical edit.

New content that lands in axis territory is a new omission, not drift. The test: would carrying it in a base contradict any value of the agency, quality, or scope axes? Read the axis fragments and check rather than guessing — # Delivering work looked like neutral guidance until its scope sentences were read against scope/unrestricted.

Reporting and applying

Report grouped by classification, with the specific changed text for each drift item, and an explicit count of what didn't change so the user can see coverage. Then get approval — AskUserQuestion with a multi-select works well when there are several independent items.

When applying:

• Edit the local fragments. Changes to the shared tail apply to both bases.
• Model table changes usually travel together: a new flagship touches MODEL_TABLE, MODEL_ALIASES, and the "most recent Claude models" line in every base's env.md.
• New fragments need registering in scripts/generate-prompts.ts and src/embedded-prompts.test.ts, plus the manifest and the fragment counts in the count tests and CLAUDE.md.
• Bump the validated-against version in CLAUDE.md and README.md.
• Regenerate embedded prompts and run bun test.

Keeping the references current

The reference files are the durable output of every sync — more so than the prompt edits, which git already records. Before finishing, make sure they reflect what you learned: new mappings and refreshed minified names in fragment-map.md; new or newly-grounded omissions in intentional-omissions.md.

Record resolved mysteries, not just changes. "vE is the lean predicate" and "YFc returns false outright, so that section is dead code" are the findings that save the next sync the most time, and neither shows up as a diff.