Rebuild on the main branch

Problem: A long-lived v2 branch falls behind, and merging it back becomes the project nobody wants to do.
Idea: Build v2 on the main branch next to v1, log every contract change with its data impact, and review every old setting.

The classic way to build a version 2 is a long-lived branch. It starts clean, falls behind, and becomes a merge nobody wants to do. This repo tried that: its 2.0 branch ends at a commit called "2.0 exploration", from April. Everything on it has been merged, and it's now 4,760 commits behind the default branch.

The real rewrite happens on the default branch, next to v1, and it's engineered so both can be live at once.

Two versions, one database

Clear names, side by sideNew code lives in places like specs/v2, test/v2, the v2 plugin and SDK folders and a session/v2 page in the app, while v1 keeps shipping releases.
A bridge between themA shadow bridge publishes prompts made through v1 as the same v2 events, so v2's projections see the conversation during the transition.
Disposable on one side onlyExperimental v2 events, projections and inputs may be reset when their shape changes. Canonical v1 session, message and part rows are always preserved.

A dated log of every contract change

A schema changelog records each v2 change to the database, durable events, projected messages, HTTP API or generated SDK: 28 dated entries, each with why it changed and whether consumers or stored data need compatibility handling. Commit messages for those changes are meant to carry the same summary.

Reset experimental V2 events, projections, inputs, Context Epochs, and synchronized workspace state while preserving canonical V1 session, message, and part rows.

Durable event names carry a version number, like session.next.prompt.admitted.1, and changes to unpublished experimental events are logged with what happens to data already stored.

Port nothing by default

The legacy config schema was reviewed field by field: 12 keep, 14 remove, 13 redesign, each with a reason.

Removed: logLevel

"No config consumer exists and logging initializes from CLI input."

Removed: server

Location config is loaded after the server is already running, so it could never take effect.

The old config.json filename isn't supported in v2, and design options that lost are kept in the specs as history. The planning doc is refreshingly honest about the goal: "ok we need to work towards a launch of v2 so we can get out of this rebuild phase".

Steal this

Grow the next version on your main branch behind clear names, bridge the old writes into the new model, version every durable contract, log every change with its data impact, and make every legacy setting earn its way in.

Use it in your code

A prompt for your coding agent

Run it from the root of your repo. It checks whether the idea fits before it changes anything.

Plan a rewrite or next major version of part of this project without a long-lived branch.

The idea: build the new version on the main branch next to the old one, behind clear names (v2 folders, flags or modules). Keep a dated log of every contract change (database, events, API, SDK) saying why it changed and what existing data needs. Give every legacy setting a keep, remove or redesign decision before porting it.

1. If it isn't obvious which part is being rewritten, ask me. Then map the old code's public contracts: storage schema, events, API endpoints, config options and SDK surface.
2. Propose a layout for the new version next to the old one, and how both can run during the transition: a bridge, a flag or a read-only adapter.
3. Create a changelog file for contract changes with a short template: date, what changed, why, and compatibility and data impact.
4. Create a config review table that lists every existing option with a proposed keep, remove or redesign decision and a one-line reason.

Don't move any code yet. Deliver the plan, the changelog file and the review table.

Read the source

Where this comes from

OpenCode (anomalyco/opencode), the open-source coding agent (these lessons are from its upcoming v2). The files behind this lesson: