docs: README update - trim repeated framing, fix stale status claims, drop going-stale badges (#52)

* docs: step 2 of the docs/site cleanup - README rewrite + agentic-development.md numbers refresh

README: trim the repeated AI-collaboration pitch to one mention with a
link (was stated near-verbatim 3x in this file alone); drop the status/
tested_on/built_with badges (CI + license only - the others just go
stale); cut the duplicate 'by the numbers' table and mermaid diagram
(both live, and are current, in docs/dev/agentic-development.md); tighten
the comparison-table Why-it-exists/Status cells; update the Documentation
table for the site-config change in the prior PR. Fixes the contradictory
status claims: audio (in-level music does not play yet, D77 -- was
claimed both silent and working in different sections) and Linux (not
actively tested since v0.1.0 -- was claimed both untested and level-swept
in different sections).

docs/dev/agentic-development.md: refreshed the 'By the numbers' table
with git-verified figures (calendar range, commit count, bug count,
ABI-edit file/line counts) -- the old numbers were from an earlier
session and had drifted well behind main. Trimmed the italic pitch
block under the H1 to one plain paragraph; left the timeline, milestone
table, and effort-split estimate untouched (maintainer's own record, not
independently re-derivable from git).

Claude-Session: https://claude.ai/code/session_016TaKy6AAsVUTfjkhrX6CjG

* docs: README fixup pass - trim bold/em-dash density, drop redundant WARNING callout

Benchmarked against comparable projects (Perfect Dark PC port, the
GoldenEye-Recomp competitor, ripgrep as a general engineering-README
gold standard): this file was still running ~42 bold spans and 48 em
dashes across ~2,600 words, well above what any of those use, and the
alpha-status callout box duplicated the Status section's own opening
paragraph.

- Bold audit for real this time: kept proper nouns on first mention,
  table row labels, and one bullet-lead-phrase convention used
  consistently in three lists; cut everything that was just mid-sentence
  emphasis or a second bold of something already established (the ROM
  phrase, Windows/Linux, v0.1.0, a bolded URL). 42 spans -> 33.
- Un-bolded and merged the duplicate audio/music caveat (was bolded once
  in Working and again in Not-yet-working for the same fact).
- Dropped the alpha WARNING callout; folded its one load-bearing
  sentence into the Status section's existing opening paragraph instead
  of stating it twice in two different box styles. Kept the ROM-supply
  IMPORTANT callout - that one's legally load-bearing and not
  duplicated elsewhere.
- Varied em-dash-as-everything-connector into periods/colons/semicolons/
  parens where a flowing sentence called for it (not touched: the
  term-dash-description bulleted lists in Credits/How-it-works/Not-yet-
  working, which are a legitimate, consistent convention, not filler).
  48 -> 33, and the worst offender (a double-em-dash-wrapped parenthetical
  in Background) is gone.
- Reworded the intro's research-angle sentence away from "doubles as a
  research project" to plain prose.

Claude-Session: https://claude.ai/code/session_016TaKy6AAsVUTfjkhrX6CjG
This commit is contained in:
James Dansereau authored and GitHub committed 2026-09-11 17:37:52 -04:00
1 parent 4d45e78176
commit 972b7e69bf
3 files changed
+110 -159

No files matched your search

+14 -16
View File
@@ -1,12 +1,10 @@
# Agentic development: two AI coding agents porting GoldenEye 007
*A case study in AI-agent collaboration on a large, low-level codebase. A
GoldenEye 007 Nintendo 64 → desktop port, taken from "builds a ROM" to
"playable front end" in about two weeks — driven mostly by two coding agents (a
local open-weight model, Qwen 3.8, on a single RTX 5090, and a hosted frontier
model, Claude / Claude Code), handing work back and forth through shared
written notes under one person's part-time direction. This is the goal, the
method, the timeline, and an honest read on what did and didn't work.*
*How this port was actually built: a local open-weight model (Qwen 3.8 on a
single RTX 5090) and a hosted frontier model (Claude / Claude Code) handing
work back and forth through shared written notes, under one person's
part-time direction. The goal, the setup, the timeline, and an honest read on
what did and didn't work.*
## Contents
@@ -104,15 +102,15 @@ issues still outstanding.
| | |
|---|---|
| Calendar time | 16 days (16 Aug – 1 Sep 2026), one person part-time |
| Commits on the port | ~223 |
| Root-caused bugs logged | 162 (`D1`–`D169` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md); some later merged or withdrawn) |
| Handoff sessions | ~33 (`M-2` … `M-33`) |
| Game-source files given `#ifdef PORT` ABI edits | 63 files, 241 blocks |
| New port-layer / tooling files | 128 |
| Port layer | ~17,000 lines C/C++ (`port/`) |
| PC asset-conversion tooling | ~6,300 lines Python (`tools_pc/`) |
| Outcome | intro + all 21 solo missions render, front end playable; audio not yet done |
| Calendar time | 26 days (17 Aug – 11 Sep 2026), one person part-time |
| Commits on the port | ~430 |
| Root-caused bugs logged | `D1`–`D226` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md), 116 still-listed entries (some labels later merged or withdrawn) |
| Handoff sessions | 89+ (`M-2` … `M-89`, and counting) |
| Game-source files given `#ifdef PORT` ABI edits | 67 files, ~305 blocks |
| New port-layer / tooling files | ~114 |
| Port layer | ~21,900 lines C/C++ (`port/`) |
| PC asset-conversion tooling | ~7,050 lines Python (`tools_pc/`) |
| Outcome | intro + all 21 solo missions render and are crash-free, front end playable, in-level SFX + menu/intro music play; in-level music and full-campaign completion re-confirmation still owed |
### Commit velocity