docs: PLAN2 + TODOLIST + RIVETKIT_RUST_FIX (clean slate, post-wipe)

[abcxff]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-5187 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Jun 8, 2026 at 6:40 pm
frontend-cloud	😴 Sleeping (View Logs)	Web	Jun 8, 2026 at 6:39 pm
ladle	✅ Success (View Logs)	Web	Jun 8, 2026 at 6:33 pm
kitchen-sink	❌ Build Failed (View Logs)	Web	Jun 8, 2026 at 6:30 pm
mcp-hub	✅ Success (View Logs)	Web	Jun 8, 2026 at 6:30 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Jun 8, 2026 at 6:30 pm

[abcxff]

Stack for rivet-dev/rivet

• feat(rivetkit-agent-os): phase 3 process — 11 arms (exec/spawn/wait/kill/stop/list/all/tree/get/writeStdin/closeStdin) + ExecResultDto #5197 unkrsszt · 2026-06-08 18:29:29
• test(rivetkit-agent-os): partial-failure driver test for readFiles batch DTO (Option<content>, Option<error>) #5196 pzzzpmtr · 2026-06-08 18:29:28
• feat(rivetkit-agent-os): phase 3 filesystem — mkdir/readdir/exists/move/deleteFile/readFiles/writeFiles/readdirRecursive arms + batch DTOs #5195 onyykwlk · 2026-06-08 18:29:27
• test(rivetkit-agent-os): config parsing tests + documented JS↔Rust software shape mismatch (phase 3 prep) #5194 ouyvrlxt · 2026-06-08 18:29:26
• feat(rivetkit-agent-os): phase 2 — stat action arm + structured-payload wrapper tests for cross-encoding parity #5193 slkvonmt · 2026-06-08 18:29:25
• feat(rivetkit): phase 1c — agentOs() native ladder + engine driver branch + driver-suite e2e green #5192 nxzrussy · 2026-06-08 18:29:24
• feat(rivetkit-napi): phase 1b — NapiActorFactory.fromAgentOs static constructor + writeFile arm + e2e factory round-trip #5191 mtlnunov · 2026-06-08 18:29:22
• feat(rivetkit-agent-os): phase 1a — rust crate skeleton + readFile arm + dispatcher e2e against real sidecar #5190 wrxkrssv · 2026-06-08 18:29:21
• feat(rivetkit): JSON_COMPAT_UINT8_ARRAY byte-payload encoding parity with TS (encode + decode + cross-language tests) #5189 ukssumln · 2026-06-08 18:29:20
• chore: phase 0 prereqs (rivetkit workspace member, serde_bare align, wasm skip.agentOs default) #5188 qvnkvkxw · 2026-06-08 18:29:19
• docs: PLAN2 + TODOLIST + RIVETKIT_RUST_FIX (clean slate, post-wipe) #5187 yqrwozvn · 2026-06-08 18:29:18 👈
• main

Check out this stack: forklift get https://github.com/rivet-dev/rivet/pull/5187
Pull/update this stack: forklift sync
Publish local edits: forklift submit
Merge when ready: forklift merge

[claude]

Code Review: PR #5187 — docs: PLAN2 + TODOLIST + RIVETKIT_RUST_FIX

Summary

This PR adds three planning and specification documents to the repository root:

• PLAN2.md — Architecture design doc for the agent-os integration (NAPI-backed Rust actor)
• RIVETKIT_RUST_FIX.md — Design spec for fixing Uint8Array encoding parity between Rust and TypeScript
• TODOLIST.md — Phase-by-phase implementation checklist for the above

There is no production code change. All 917 additions are documentation.

---

Critical Issues

1. Wrong location — agent working files must live in ~/.agents/, not in the repo.

CLAUDE.md is explicit:

All agent working files live user-scoped in ~/.agents/, never inside the repo. … These files are not committed.

These three files are exactly the kinds of content that belong in ~/.agents/:

File	Correct location
PLAN2.md	~/.agents/specs/plan2-agent-os.md
RIVETKIT_RUST_FIX.md	~/.agents/specs/rivetkit-rust-fix-uint8array.md
TODOLIST.md	~/.agents/todo/agent-os-todolist.md

The .gitignore entry for .agent/ is a safety net for accidental in-repo agent dirs, not a substitute for the correct ~/.agents/ workflow. These files must not land in the repo.

---

Style / Convention Violations

2. Pervasive use of em dashes (—) throughout all three files.

CLAUDE.md under Code Style states:

Do not use em dashes (—). Use periods to separate sentences instead.

All three documents use em dashes extensively in headings and prose (40+ instances). Examples from PLAN2.md:

# Plan 2 — agent-os integration
No `HostToolInvoker` trait. No `entry_fn` + `actor_config` + `build_core_factory` three-way API — just `build_core_factory(config) -> CoreActorFactory`.

---

Design Observations (for when implementation begins)

These are not blockers on their own given this is a doc-only PR, but worth flagging early so the spec can be updated before implementation starts.

3. The (definition as any).nativeFactoryBuilder pattern is a red flag.

PLAN2.md proposes casting to any to access nativeFactoryBuilder in multiple places. AnyActorDefinition is a public interface. The correct approach is to add nativeFactoryBuilder to the interface directly, or use a proper discriminated-union type guard (isNativeFactoryDefinition(definition)). Using as any casts at multiple call sites defeats TypeScript's type safety and makes the discriminator invisible to future maintainers.

4. The registerActor signature widening in CoreRuntime has a larger blast radius than the spec acknowledges.

The existing CoreRuntime.registerActor takes a pre-resolved ActorFactoryHandle. The plan proposes moving factory resolution inside registerActor. This changes the interface implemented by both NapiCoreRuntime and WasmCoreRuntime, and every call site in native.ts would need updating. The spec should capture this wider impact explicitly.

5. WfHistory::reply and WfReplay::reply should not use encode_json_compat.

RIVETKIT_RUST_FIX.md proposes swapping encode_cbor in WfHistory::reply and WfReplay::reply to use the new encode_json_compat adapter. However, workflow history and replay payloads are consumed by the Rust workflow engine, not by JS clients. Applying ["$Uint8Array", base64] wrapping there would break workflow state serialization when byte fields appear in workflow state, because the Rust deserializer does not understand that convention. Only Action::ok — which returns a value to a JS caller — needs the compat wrapping. The spec should explicitly exclude WfHistory::reply and WfReplay::reply from the swap list, or confirm they are actually JS-facing.

6. ConnParams=serde_json::Value type alignment needs verification.

TODOLIST.md (Phase 1a) specifies AgentOsActor with ConnParams=serde_json::Value. Confirm serde_json::Value satisfies the Actor::ConnParams trait bounds (Send + 'static + DeserializeOwned) without special handling, or pick a more appropriate type.

7. CLAUDE.md/AGENTS.md symlink must be created in the same change.

TODOLIST.md Phase 6 treats creating CLAUDE.md and its AGENTS.md symlink as separate steps. Per CLAUDE.md:

Every directory that has a CLAUDE.md must also have an AGENTS.md symlink pointing to it. When creating a new CLAUDE.md, create the symlink in the same change.

These must be consolidated into a single checklist item and a single commit.

8. The tracing::debug! grep in Phase 6 is misleading.

TODOLIST.md Phase 6 includes grep -rE "console\.error|tracing::debug" as a "clean up" step. tracing::debug! is a valid, encouraged log level — not something to clean up. The pattern should target leftover ad-hoc debug prints (e.g., // DEBUG comments, or tracing::debug!("TODO patterns) rather than all tracing::debug! calls.

---

Verdict

This PR should not be merged as-is. The three files are agent working artifacts that belong in ~/.agents/specs/ and ~/.agents/todo/, not the repository root. The em-dash style violations are also a CLAUDE.md convention failure. The design observations above are worth addressing in the spec before implementation begins.