--- name: migrate-to-submodule description: Plan and execute moving non-host-specific code (and its tests) from the OpenHuman core (crates/openhuman-core) into the vendored tiny* submodule libraries (vendor/tiny*), then release the submodule and re-pin the registry digests. Use when asked to "move X out of core", "upstream this into tinyfoo", "extract a crate", or to shrink the host to composition/policy only. --- # Migrate core code into a vendored submodule OpenHuman is the **host**: composition, config, security policy, approvals, lifecycle, and adapters. Behavior that is not specific to OpenHuman belongs in the owning `vendor/tiny*` project (see "Submodule ownership" in `CLAUDE.md`). This skill drives one migration end to end: plan, move code + tests, ship the submodule release, re-pin the host. Default to executing. Use plan mode only for step 1 (the split decision), and only when the boundary is genuinely ambiguous or the move is large. Work in a worktree (`worktree ` from the repo root); never on `main`. Do not squash commits; the auto-commit hook checkpoints for you. ## How TinyBus fits TinyBus is the seam that makes this migration possible and shapes its design. - A loadable module is a first-party `cdylib` speaking the TinyBus module ABI, downloaded from a pinned GitHub release and attached to an in-process broker as a bus peer. The core calls it through a **typed contract**, not a Rust import. - Each module has a `*-bus` contract crate (names, methods, request/response types, contract version). It is synchronous and free of I/O and runtime deps. **Never redeclare a contract type in OpenHuman; call members through the contract constants.** - Because the module is a separate binary in the same process, anything you move must be reachable from the host through the bus contract. So a migration is usually three pieces: (a) implementation in the module crate, (b) new/changed methods and types in the `*-bus` crate (bump its contract version), (c) a thin host adapter under `crates/openhuman-core/src/modules/.rs` (or the domain that calls it) that forwards to the bus and keeps policy/config/creds. - Data that cannot cross a boundary (task-local state, callbacks, secrets) is passed explicitly in the request, or served *to* the module as a host callback (see `modules/memory_host.rs`). Credentials never ride in tool arguments; they go through module init/reinit config. - Module code must not depend on `openhuman`. Host callbacks are traits/bus services the module defines and the host implements. - Not every submodule is a loadable module. Pure libraries (`tinyagents`, `tinytools`, `tinychannels`, `tinyskills`, `tinyvoice`, `tinywallet`, ...) are linked via Cargo; a move there needs no bus contract or digest re-pin, only a gitlink bump. Check the module's `MODULE.md`/README to know which kind it is. ## Step 1: Plan (freedom to decide the split) 1. Identify the code to move and read its callers. Use Explore/Grep on `crates/openhuman-core/src//`. 2. Classify every item as **moves** or **stays**: | Moves to the submodule | Stays in OpenHuman | | --- | --- | | Algorithms, parsers, protocol/wire types, engines, generic tools, provider clients with no product identity | Config schema and loading, `SecurityPolicy`/approvals/sandbox decisions, credential resolution (`resolve_backend_credential`), `Outcome` controllers and RPC schemas, event-bus publishing, product identity/attribution headers, Redux/Tauri glue | | Tests that exercise only the moved logic | Cross-module tests, host-adapter tests, JSON-RPC E2E, anything needing the mock backend or `CoreContext` | 3. Pick the destination using the ownership table in `CLAUDE.md`. Put the change in the repo that owns the behavior, not where it is easiest to land. Read the target's `README.md`, `AGENTS.md`, crate boundaries and `*-bus` crate first. 4. **You may create new crates** in the submodule workspace when the code has no good home (e.g. a new `tinyfoo-` library crate, or a new `*-bus` if a new module needs its own contract). Prefer extending an existing crate. Only propose a brand-new submodule/repo when no existing project owns the concept; that one is a user decision, so stop and ask. 5. Write the plan down briefly (in the PR description or `docs/plans/`): what moves, what stays, new crates, bus contract changes, dependency direction, and the release order. Skip a formal doc for a small, obvious move. Dependency rules to check while planning: the core must not depend on `tinyhumans-sdk` (only `openhuman-tinyhumans` may); a module must not depend on `openhuman`; there is one `tinytools` copy (via `vendor/tinyagents/`); tool-call parsing/dialects/agent loop belong in `tinyagents`, not the host. ## Step 2: Move the code, upstream first Submodule PRs go **first**, raised against that repo's canonical upstream (`tinyhumansai/`), never a fork. Follow the submodule's own `AGENTS.md`/ `CONTRIBUTING.md` (fmt, clippy `-D warnings`, per-file coverage gates such as 90% in tinysearch's release workflow). 1. Branch inside the submodule at the recorded gitlink (the `worktree` helper already put every submodule on branch ``). Do not create nested worktrees. 2. Move the implementation into the target crate with `git mv`-style history where practical. Keep public API minimal and documented; keep files under about 500 lines. 3. Move tests with the code. Unit tests go beside the moved modules in the submodule. Add bus-contract tests in the `*-bus` crate for any new wire type. Tests that need the host stay in OpenHuman. 4. If a bus contract changed, bump its version and update both sides in the same change set. Keep the contract synchronous and I/O-free. 5. Replace the removed core code with the thin host adapter. Delete the old implementation and its old tests, do not leave a copy. Keep `Outcome` controllers and RPC namespace strings (wire contracts) unchanged. 6. Verify in the submodule: `cargo fmt --all -- --check`, `cargo clippy --all-targets --all-features -- -D warnings`, `cargo test --all-features` (plus the coverage gate if the repo has one). 7. Open the submodule PR ready for review, babysit to green, merge. Unshallow submodule clones before merging upstream if needed. If the change spans nested submodules (`tinyagents/vendor/tinytools`, `tinymemory/vendor/tinycortex`, ...), release/merge the innermost first and bump gitlinks outward. ## Step 3: Release the submodule Only for **loadable modules** (a `cdylib` with a registry record). Pure Cargo libraries just need the merged commit. 1. Trigger the submodule's `Release` workflow (`workflow_dispatch` on `main`, input `bump`: patch/minor/major/current), e.g. `gh workflow run release.yml -R tinyhumansai/ -f bump=patch`. It runs fmt/clippy/tests, builds per-platform archives, tags `vX.Y.Z`, and publishes a GitHub release with `checksum.toml`. 2. Wait for it to finish (`gh run watch`). Confirm the release has one archive per host key the registry lists (macOS 15/26 arm64+x86_64, Ubuntu 22.04/24.04 x86_64+arm64, Windows) plus `checksum.toml`. 3. Ask before triggering a release if the user has not already authorized it: it publishes tags and artifacts and is hard to undo. ## Step 4: Re-pin the host Modules are pinned **twice**, and both must describe the same release (`scripts/ci/check-module-pins.mjs`): 1. **Submodule gitlink**: `git -C vendor/ fetch --tags && git -C vendor/ checkout vX.Y.Z`, then stage the gitlink in the superproject. 2. **Registry record**: edit `crates/openhuman-core/src/modules/registry/records_*.rs` for the module: `version`, `release_url`, and every `PlatformAsset` `archive` name and `sha256`. - Copy digests **verbatim from the published release's `checksum.toml`** (`gh release download vX.Y.Z -R tinyhumansai/ -p checksum.toml`). - **Never compute a digest from a local build.** A locally recomputed hash agrees with itself no matter what was served, which defeats the pin. - At load time tinybus fetches the release's own `checksum.toml`, compares it with the host pin, hashes the archive, then extracts. A re-cut tag stops matching instead of silently replacing what runs in-process. 3. Update anything else that names the version (for example the pinned archive version and sha256 in the CI workflows). If a module is deliberately off-tag, that needs an entry in `scripts/ci/module-pin-exemptions.json` with a reason. Prefer a fresh release over an exemption. 4. Bump the OpenHuman-side contract crate reference if the `*-bus` version moved, and update `crates/openhuman-core/src/modules/README.md` and `platform/about_app/` if the layout or user-visible capability changed. 5. Verify: ```bash node scripts/ci/check-module-pins.mjs node scripts/ci/check-submodule-monotonic.mjs pnpm rust:layout cargo check --manifest-path Cargo.toml cargo test -p openhuman-cli --test # or: pnpm debug rust ``` Test with a feature both enabled and disabled if a gate moved. Never export `CARGO_TARGET_DIR`. Run long CI-style commands through `scripts/ci-cancel-aware.sh`. ## Step 5: Open the OpenHuman PR - PR against `upstream` (`tinyhumansai/openhuman`), ready for review, not draft. If the submodule release is not out yet, say so and mark draft only then. - Body: what moved, what deliberately stayed and why, new crates, bus contract changes, links to the submodule PRs and release, and the digest source. - The gitlink must point at a commit that exists upstream (merged, tagged). - Hand off to `pr-babysitter` for CI and review threads. ## Checklist - [ ] Every moved item is non-host-specific; host policy/config/creds stayed - [ ] Tests moved with the code; cross-module/host tests stayed - [ ] Bus contract updated and versioned; no redeclared contract types - [ ] Submodule PR merged upstream first; fmt/clippy/tests/coverage green - [ ] Release published with `checksum.toml` (loadable modules) - [ ] Gitlink and registry `version`/`release_url`/digests agree, digests copied from the release - [ ] `check-module-pins` and `check-submodule-monotonic` pass - [ ] Old core code and tests deleted, docs updated