Repository navigation
docs: Claude Code guidance for TeensyROM - #79
Merged
SensoriumEmbedded merged 9 commits intoOct 31, 2026
Merged
Conversation
kfox
marked this pull request as ready for review
October 29, 2026 02:10
Claude Code reads this file at the start of every session in the repo. It points at the architecture docs rather than repeating them, lists the gates and the Constraints.md rules that cause hardware-only failures, and sets the rules for findings, review effort, pinned paths, hardware use and what may appear in public text.
Claude Code asks before every shell command it has not been allowed. These are the gates CLAUDE.md asks for and the read-only git commands; flashing still asks, except the --check that only identifies boards. Worktrees and personal settings stay out of git status.
The reviewer agent runs one review of one change in a worktree and commits its own fixes; panel-review runs the four lanes (auditor, adversary, steward, pragmatist) for a large or risky change. The generic bodies come from the c64cast setup; each gets a TeensyROM section naming the gates, the PHI2 and RAM rules, the trust boundaries (the unauthenticated port 2112 protocol, files from SD/USB, NFC, self-flash) and the contracts that drift.
Adapted from c64cast: one review per change at the effort CLAUDE.md sets, a draft PR whose body says what it was tested on and its memory impact, CI green, then ready for review, and never a merge.
…enu_Regs.i The mpe/ directory is gone; the host harnesses now run under npm test and verify:extensions. Menu_Regs.i has been generated from Menu_Regs.h by build:c64 since the Node build, so editing both is wrong: the .i edit is overwritten.
The prrev skill reviews ITCM growth, strings in DTCM, idle cost, every entry and failure path, chip-model fidelity, PR wording and hardware coverage. CLAUDE.md and the reviewer now carry those as firmware rules, and ship gains a before-Ready step that takes base-vs-head memory figures from CI, applies FLASHMEM to ITCM growth and re-reads the PR's words; a firmware PR headed upstream gets prrev's sections 3 to 5 as its final pass.
The pointers into prrev carried the memory table, the hardware axes and the upstream final pass; each is stated in place. F() is only a cast on Teensy 4, so strings go through PSTR(). The reviewer counts permanent RAM2 holds as findings, matching CONTRIBUTING.md's checklist.
kfox
force-pushed
the
docs/claude-guidance
branch
from
October 29, 2026 18:41
19cbf20 to
e4b1c16
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Claude Code guidance for this repo, adapted from what has been working in c64cast. Each piece stands alone, so any of it can be kept or dropped.
CLAUDE.md: what Claude reads at the start of every session here. It points atdocs/Architecture/rather than repeating it, and covers:fBusSnoop, RAM banks, the single-threaded loop, the hand-synced lists, the toolchain pin, C128 timing);.claude/settings.json: runs the tests, the builds,npm run flash -- --checkand read-only git without asking. Flashing a board still asks..claude/agents/: arevieweragent that reviews one change in its worktree and commits its own fixes, plus four review agents (auditor, adversary, steward, pragmatist). Each one has a TeensyROM section: the timing and RAM rules, the inputs from outside (the unauthenticated port-2112 protocol, SD/USB files, NFC, firmware self-update), and the docs and layouts that drift..claude/skills/shiptakes a change from worktree to a ready-for-review draft PR and never merges. Before Ready it takes base-vs-head memory figures for each image from CI, re-reads the PR's title and description against the final code, and lists what ran on hardware; a firmware PR headed upstream gets a high review, that memory comparison and the hardware list as its final pass..claude/skills/panel-reviewruns the four review agents on one large or risky change..gitignoreignores.claude/worktrees/and.claude/settings.local.json.CONTRIBUTING.mddrops the removedmpe/test paths and says to edit onlyMenu_Regs.h, sinceMenu_Regs.iis generated from it.