diff --git a/AGENTS.md b/AGENTS.md index 8771e9b..eb2ec7a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ Eventually, a C toolchain necessary. However, it is helpful much sooner: ## Project status -Last updated 2026-07-21. The project just finished migrating its boot +Last updated 2026-07-26. The project just finished migrating its boot process from Multiboot2/GRUB to a custom UEFI loader. The loader (`loader/`) now successfully parses the kernel ELF, maps its segments, sets up paging, and jumps into `kernel_entry` in [src/kmain.rs](src/kmain.rs). @@ -55,7 +55,10 @@ inert the way it was right after the UEFI migration. A dedicated testing/verification strategy (beyond ad hoc debugcon-reading and manual QEMU boots) landed in `.github/workflows/ci.yml` (PR #25): three jobs — `cheap` (host unit tests + per-crate compile checks), -`expensive` (Miri), and `smoke` (full image build + a headless QEMU boot, +`expensive` (Miri — path-gated to `shared`/Miri inputs so unrelated PRs get +a green no-op, plus a daily `schedule:` run that forces the full suite to +catch dateless-`nightly` drift), and `smoke` (full image build + a headless +QEMU boot, gated on a new `src/qemu.rs` isa-debug-exit pass/fail signal, see "Verifying changes" below). GDB-over-QEMU-stub debugging is still real but slow for interactive local work, so CI — not local runs — is what now @@ -219,6 +222,12 @@ of running them all by hand every time. Locally, in order of preference: ### Booting headlessly and bounding the run +This whole procedure is packaged as the **`qemu-boot` skill** +(`.claude/skills/qemu-boot/SKILL.md`) — an agent verifying a change by +booting should invoke that skill rather than re-deriving the watchdog by +hand. The prose below is the source of truth the skill follows; keep the two +in sync when boot behavior changes. + Rebuild first (`./make-image.sh`), then run headless and capture output. QEMU never exits on its own after the kernel halts, and there's **no `timeout`/`gtimeout` on macOS**. A `perl -e 'alarm N; exec ...'` wrapper @@ -260,6 +269,30 @@ triple fault (QEMU silently resets without `-no-reboot`). Add QEMU's own exception/reset trace instead of re-guessing from debugcon silence alone. +## Claude Code tooling (`.claude/`) + +Some agent tooling is checked into the repo under `.claude/` (this is a +learning project, and part of that is learning how to use Claude Code here). +Tracked assets, and what each is for: + +* **`skills/qemu-boot/`** — a skill that rebuilds the image and boots it + headlessly in QEMU with the external watchdog, distinguishing a hang from + a triple-fault reset from a normal panic. Use it for any boot-based + verification instead of hand-rolling the procedure in "Verifying changes" + above; that section remains the source of truth the skill defers to. +* **`agents/source-grounded-explorer.md`** — a read-only subagent for + open-ended architectural/strategic questions about this codebase (e.g. + "how should X be re-wired for the UEFI handoff"). It reads the actual + source before reasoning and returns a labeled option menu with a + recommendation. Not for concrete already-decided fixes — just do those + directly. +* **`output-styles/terse.md`** + **`settings.json`** — a project-wide + "Terse" output style (enabled via the checked-in `settings.json`) that + trims response verbosity without touching reasoning depth. + +`.claude/settings.local.json` is gitignored (machine-local overrides) and +won't exist in a fresh clone. + ## Contribution conventions * Keep commit messages concise (short subject, at most a brief sentence or