# Research & Build Plan — minecraft_protocol How this repo gets built: my orchestration plan (for me) + the task spec every research agent follows (for each agent). Living doc — updated as phases complete. --- ## 0. Goal & scope A version-aware deep-dive reference for the Minecraft: Java Edition wire protocol, **1.7.10 (protocol 5) → latest (26.2 / protocol 776)**. Two layers: 1. **Topical foundation** — how the protocol works as a system (framing, state machine, handshake, status, login+encryption, configuration, proxy forwarding). 2. **Per-version deep-dive** — what changed in *each* protocol-bumping release, sourced from release notes + commits + wiki. ## 1. Method — the loop `research → clone → explore → write → verify → repeat`, with citation discipline: - Every non-trivial claim cites a source inline: a reference-impl `path:line` and/or a wiki URL/section + fetch date. - Wire formats (handshake overloads, encryption, forwarding HMAC, packet IDs) **must** come from source or wiki, never memory. - Anything unconfirmed gets an inline `` flag; Phase 4 resolves them. - Version-aware always: state the version/protocol number where a detail was added/changed. ## 2. Source catalog | Tag | Source | Used for | |---|---|---| | MCWIKI | minecraft.wiki (ex-wiki.vg): `/w/Java_Edition_protocol`, `/w/Protocol_version`, per-version protocol archives, **`/w/Java_Edition_1.X.Y` release articles (release notes)** | spec of record + headline changes per release | | VV | `/tmp/mcproto-refs/ViaVersion` — `ProtocolVersion.java` + `protocols/vX_YtoX_Z/` packages | authoritative version numbers + what packets changed between adjacent versions | | VV-LOG | ViaVersion **git history** (`git log` on each `protocols/` package) | the commits that implemented each version's changes | | MD | PrismarineJS/minecraft-data `protocolVersions.json` + per-version `protocol.json` (raw.githubusercontent) | cross-check numbers + packet field defs | | NMP | `/tmp/mcproto-refs/node-minecraft-protocol` | clean reference impl of framing/encryption/ping/states | | VELO | `/tmp/mcproto-refs/Velocity` | modern forwarding, login flow, state registry | | BUNGEE | `/tmp/mcproto-refs/BungeeCord` | legacy forwarding format | | MOJANG | minecraft.net / feedback.minecraft.net changelogs | official release notes per version | **Setup TODO before Phase 3** (commits are a requested source, but refs were `--depth 1`): - `git -C /tmp/mcproto-refs/ViaVersion fetch --unshallow` (full history for `git log`) - clone `minecraft-data` (sparse `data/pc/`) for per-version `protocol.json` --- ## 3. Orchestration plan (me) ### Phase 1 — Topical foundation (8 docs) | Doc | Status | |---|---| | 00-overview + 01-data-types | ✅ done | | 02-connection-lifecycle | ✅ done | | 03-handshake | ⬜ re-dispatch (cancelled by interrupt) | | 04-status-ping | ✅ done | | 05-login-encryption | ⬜ re-dispatch | | 06-configuration | ⬜ re-dispatch | | 07-version-differences | ✅ done (has the full version map) | | proxy-forwarding/ (6 files) | ⬜ re-dispatch (opus) | → **Action: re-dispatch the 4 ⬜ rows** (specs in §6). Wave 1 closes when all 8 are in. ### Phase 2 — Version map Build `versions/INDEX.md`: every protocol-bumping release 1.7.10→26.2 with {release, protocol #, release date, ViaVersion package, mc-wiki release-article URL, mc-wiki protocol-archive URL}. Derived from `07` + VV `protocols/` listing + MCWIKI. This index drives Phase 3 and becomes the navigation hub for `versions/`. ### Phase 3 — Per-version deep-dive (batched) One doc per **release line** under `versions/` (e.g. `versions/1.13.md`), each with a **sub-section per protocol bump** inside that line (1.13=393, 1.13.1=401, 1.13.2=404). Granularity rationale: a full doc per trivial patch bump is noise; a doc per major.minor line with per-bump sections is thorough without 50 stubs. *(If you want one-doc-per-protocol-number instead, say so — easy to split.)* Batched by the **7 eras** from `07` (keeps each wave ≤ concurrency cap, lets us quality-gate between): - B1 — Era 1: 1.7.10, 1.8 - B2 — Era 2: 1.9, 1.10, 1.11, 1.12 - B3 — Era 3: 1.13, 1.14, 1.15 - B4 — Era 4: 1.16, 1.17, 1.18 - B5 — Era 5: 1.19 - B6 — Era 6: 1.20 - B7 — Era 7: 1.21, 26.x After each batch: I read the docs, spot-check citations, resolve obvious gaps, then launch the next. Per-version agent spec in §7. ### Phase 4 — Verification & polish - `fact-verifier` agents on: all `` flags, every protocol number in the map, the crypto details (AES/CFB8, serverId hash) and forwarding formats (Velocity HMAC payload, Bungee `\0` string). - Cross-link docs; fill the README status table (⬜/✅ per doc); write `references.md`. - Then offer to commit + push to `Timemachine/minecraft_protocol`. ## 4. Conventions (all phases) - **Models**: research/writing agents = `sonnet`; hard synthesis (proxy-forwarding, big-era version docs) = `opus`; never `haiku` for protocol reasoning. Verifiers = `fact-verifier` type. - **No nested fan-out**: every agent works directly, spawns **no** sub-agents. - **One file owner**: each agent writes only its assigned file(s) — no two agents touch the same file (parallel-safe). - **Citations + VERIFY**: as §1. - **Mermaid**: sequence/state diagrams for flows; parse-safe (quote labels containing `:` or special chars). --- ## 5. Per-agent task spec (common template) Every research agent is handed: 1. **Exact output path(s)** in `~/Documents/minecraft_protocol/`. 2. **Topic** + the specific points to cover. 3. **Sources to read**, by path/URL (from §2), with the instruction to cite `path:line` / wiki-URL inline. 4. **Format**: markdown, headers + tables; mermaid for flows; example payloads where useful. 5. **Rules**: version-aware; wire formats from source not memory; `` for anything unconfirmed; **no sub-agents**; touch only the assigned file(s). 6. **Report back**: file path(s) + 3-line summary + any VERIFY flags + (for format-critical docs) the exact extracted format with its citation. ## 6. Phase-1 re-dispatch assignments (the 4 pending) - **03-handshake.md** (sonnet) — handshake packet fields; SRV; serverAddress overloads: Forge `\0FML\0`/`\0FML2\0`/`\0FML3\0`, BungeeCord legacy `host\0ip\0uuid\0props` (exact, from `BUNGEE/.../InitialHandler.java` + `ServerConnector.java`), note Velocity-modern uses a login plugin msg instead; transfer next-state(3)=1.20.5+. - **05-login-encryption.md** (sonnet) — login packet flow; RSA-1024 + AES/CFB8; serverId negative-hex SHA-1; online-mode join/hasJoined (Mojang session server); compression (1.8+); 1.19 profile keys. Sources: NMP `client/encrypt.js`, `transforms/encryption.js`; VELO `EncryptionRequest/ResponsePacket.java`; MCWIKI Protocol_Encryption. - **06-configuration.md** (sonnet) — the 1.20.2 Configuration state; registry/tags/packs → Finish; re-configuration loop; Known Packs (1.20.5). Sources: MCWIKI Configuration; NMP/VELO state handling. - **proxy-forwarding/** (opus, 6 files) — README, online-offline-modes, bungeecord-legacy, velocity-modern, bungeeguard, forge-fml. Velocity HMAC payload from `VELO/.../PlayerDataForwarding.java` + `VelocityConstants.java`; Bungee format from `BUNGEE/.../InitialHandler.java`+`ServerConnector.java`. Comparison table; mermaid for both forwarding flows. ## 7. Phase-3 per-version agent spec (template) For release line **X** (e.g. 1.16), write `versions/X.md` covering every protocol bump in that line. Each agent: **Read:** - MCWIKI release article(s) `/w/Java_Edition_X` and each patch → headline gameplay + technical changes (**release notes**). - MCWIKI protocol archive for X (the version-specific protocol page / the diff section). - VV package(s) for the bump(s) into X — `protocols/vPREVtoX/` — the `ProtocolPREVToX.java` + `Clientbound/ServerboundPacketsX` enums = the authoritative changed-packet list. AND `git -C ViaVersion log --oneline -- ` = the **commits** that implemented it. - MD `protocol.json` for X (raw fetch) to cross-check packet IDs/fields. **Write** `versions/X.md` with: - Header: release line, protocol number(s) + release date(s) (cite MCWIKI/MD). - **Headline changes** (release notes): what shipped, 1-paragraph. - **Protocol changes**: new / removed / renumbered / restructured packets (from VV enums + MCWIKI), grouped by state (handshake/status/login/config/play). Note data-format changes (NBT, registries, chunk, item components). - **Per-patch sub-sections** if the line had multiple protocol numbers (e.g. 1.16→735, 1.16.2→751…), each noting what that bump specifically changed (cite the VV package + commit). - **Proxy/forwarding & translation impact**: what a proxy/ViaVersion must do for this version. - Citations inline; `` for gaps. **Report:** path + which protocol numbers covered + notable changes + VERIFY flags. --- ## 8. Status log - 2026-06-19: repo created (`Timemachine/minecraft_protocol`), refs cloned, README + this PLAN written. Wave-1: 4/8 docs landed (00/01, 02, 04, 07). Next: re-dispatch the 4 pending (§6), then Phase 2.