engine-todo

name	engine-todo
description	Work a single engine TODO item end-to-end — plan, implement, test/verify, then remove it from the tracker (or update it if only partially done), commit, and push to the nibli repo. Use for engine/runtime-crate tasks, one at a time (the book-manuscript variant is book-todo).

Work one nibli (engine) TODO item

Drive a single engine task from "named" to "committed and pushed." Do exactly one item per invocation — never batch. The user hands you the next item when this one lands.

The user names or quotes the item. The engine roadmap TODO.md was removed from the repo root; if no tracker file exists, work the item the user pasted directly and ask where (if anywhere) they want it recorded. If a tracker file does exist, treat it as the source of truth. If the reference is ambiguous, ask before doing anything.

For book-manuscript items, use the book-todo skill (in the book repo, book/.claude/skills/) — this one is for the engine/runtime crates.

Environment

This project lives on WSL2 (Ubuntu); the Windows working dir does not exist on the Linux side. Run every shell command through the wrapper:

wsl -d Ubuntu -e bash -lc "cd ~/projects/dhilipsiva/nibli && <CMD>"

Anything touching the toolchain (cargo, just, wasmtime, cargo-component) needs the Nix dev shell:

wsl -d Ubuntu -e bash -lc "cd ~/projects/dhilipsiva/nibli && nix --extra-experimental-features 'nix-command flakes' develop --command bash -c '<CMD>'"

All git operations for engine items happen in the nibli repo (remote nibli). Note: .claude/ is gitignored here, so this skill file itself was force-added — keep that in mind if you ever edit it.

The loop

1. Locate & plan. Read the relevant crate source/tests for the item. Architecture, crate roles, and conventions are in CLAUDE.md. State a one-paragraph approach for non-trivial items. Pause and ask only if the item is genuinely ambiguous or needs a design decision — otherwise proceed through the whole loop.

2. Implement. Follow the engine conventions in CLAUDE.md. Key ones:

   • Test with cargo test --lib, not cargo test (the cdylib linker chokes on WIT @ export symbols). Exception: gasnu is a plain bin — cargo test -p nibli-host links fine.
   • Logji (reasoning) tests need --test-threads=1 (shared global state); the Justfile handles this.
   • Don't hand-edit **/bindings.rs (auto-generated by cargo component build).
   • Set CARGO_INCREMENTAL=0 if invoking cargo from the Windows side.

3. Test / verify. Report output faithfully — never claim success without running it:

   • just check for a fast type-check; just ci for the full native gate (fmt-check, clippy, all native suites incl. test-host); targeted just test-* for a single suite.
   • just ci-wasm when WASM component / fuel / memory / trap behavior is involved; just ci-all for the comprehensive pre-push gate.
   • Re-read / re-run to confirm the change does what the item asked. If verification fails, fix and re-verify. Do not commit broken work.

4. Update the tracker. Items are plain - bullets — never - [ ] checkboxes (the workflow deletes or rewrites items, it never checks them off). If a TODO.md/tracker holds the item: fully done → delete the bullet entirely (no ~~strikethrough~~, no "DONE" marker); partial → rewrite it to state exactly what remains; stale → say so and remove it. If there is no tracker, note in the commit what was completed.

5. Sync docs. Per the pre-commit checklist in CLAUDE.md: update CLAUDE.md, README.md (if Lojban coverage or reasoning capability changed), and the tracker, then commit all code + doc changes together.

6. Commit & push (nibli repo).

   • Write the commit message to a temp file and git commit -F /tmp/msg.txt. Heredocs and -m mangle backticks / ? / quotes inside the double-quoted bash -lc wrapper — the file avoids that. (Use the Write tool to author the message at \\wsl.localhost\Ubuntu\tmp\msg.txt, i.e. /tmp/msg.txt.)
   • End the message with the Co-Authored-By: Claude … <[e-mail]> trailer the harness specifies for the model actually doing the work — do not copy a model name hardcoded here (an earlier revision pinned "Opus 4.8" and it went stale).
   • Scope the commit to the files this item touched (git add <those files>). Never sweep in unrelated working-tree changes.
   • Before pushing: git fetch and check the branch isn't behind / nobody else pushed; rebase (not merge) if it moved. Then push. The SSH remote can hang in this environment — if so, push over gh-authed HTTPS: git -c credential.helper='!gh auth git-credential' push https://github.com/dhilipsiva/nibli.git HEAD:main.

7. Stop. Report what changed + the verification result in a few lines, then wait for the next item.

Guardrails

• One item per invocation. Don't pick up adjacent items "while you're here."
• Never run long build/test work in background agents — they have died silently mid-run; work in the main loop with checkpoint commits.
• If blocked on a decision, ask before implementing — don't guess on irreversible or design-shaped calls.