deep_research/docs/platform-branch-strategy.md

Platform Branch Strategy

Use one of two clean separation patterns.

Preferred Default: Source Templates + Rebuilt Envs

The main branch tracks only source templates:

• platform_adapters/antigravity
• platform_adapters/codex
• platform_adapters/opencode
• platform_adapters/claude-code
• platform_adapters/gemini-cli

Local runnable environments are generated and ignored:

• platform_envs/antigravity
• platform_envs/codex
• platform_envs/opencode
• platform_envs/claude-code
• platform_envs/gemini-cli

Update flow:

git pull --ff-only
python scripts/update_platform_envs.py --platform antigravity --skip-pull

or:

python scripts/update_platform_envs.py --platform all

Open the generated platform env, not the full repository.

Alternative: Per-Platform Branches

If a platform keeps ignoring generated-env boundaries, split Gitea branches:

• main: Python core, docs, canonical skills, shared configs.
• platform/codex: Codex-only working tree.
• platform/antigravity: Antigravity-only working tree.
• platform/opencode: OpenCode-only working tree.
• platform/claude-code: Claude Code-only working tree.
• platform/gemini-cli: Gemini CLI-only working tree.

In that mode, platform branches should remove unrelated platform directories entirely. Merge shared runtime changes from main; do not merge one platform branch into another.