minecraft_protocol/PLAN.md

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 <!-- VERIFY --> 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 <!-- VERIFY --> 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; <!-- VERIFY --> 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 -- <that package> = 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; <!-- VERIFY --> 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.