diff --git a/personal/starr/skills/codex-applied-devbox/SKILL.md b/personal/starr/skills/codex-applied-devbox/SKILL.md new file mode 100644 index 0000000000..30a142556d --- /dev/null +++ b/personal/starr/skills/codex-applied-devbox/SKILL.md @@ -0,0 +1,334 @@ +--- +name: codex-applied-devbox +description: Sync a local Codex worktree from `~/code/codex-worktrees/` to a mirrored path on a remote host, then run a reproducible remote build or exec command there. +--- + +# Codex Applied Devbox + +Use this skill when you want local file editing/search on your laptop, but want +the actual build or execution to happen on a remote host such as `dev`. + +This skill assumes: + +- remote host alias: `dev` +- local Codex worktree root: `~/code/codex-worktrees` +- remote mirror root: `/tmp/codex-worktrees` + +If the box itself needs to be created, resumed, suspended, or inspected, use +the `applied-devbox` skill first. + +## Objective + +1. Create or reuse a local worktree under `~/code/codex-worktrees/`. +2. Mirror that worktree to the remote host under `/tmp/codex-worktrees/`. +3. Run one configurable remote Bazel command against the mirrored copy. +4. Keep the flow reproducible by excluding build artifacts and local repo state. + +## Operator Defaults + +When using this skill interactively, the operator should bias toward immediate +execution over setup-heavy preflights. + +Default posture: + +- If the user asks for a specific PR or branch, create a fresh worktree first. +- Do not spend time checking whether an equivalent worktree already exists + unless the user explicitly asked to reuse one. +- Assume `dev` is reachable and run the sync directly; only debug SSH or remote + prereqs after the real command fails. +- Avoid separate "can I reach the host?" or "does rsync exist remotely?" + checks unless there is a known problem pattern. +- Prefer one end-to-end attempt over multiple speculative probes. + +In practice, that means the operator should usually do this: + +1. Fetch the requested PR or ref. +2. Create a new local worktree under `~/code/codex-worktrees/`. +3. Run `sync-worktree-and-run` immediately. +4. Only inspect host reachability, missing tools, or conflicting paths if that + end-to-end run fails. + +### PR Fast Path + +For a request like "build PR 16620 on devbox", prefer this shape: + +```bash +mkdir -p ~/code/codex-worktrees +git -C ~/code/codex fetch origin pull/16620/head +git -C ~/code/codex worktree add -b pr-16620 \ + ~/code/codex-worktrees/pr-16620 FETCH_HEAD +skills/codex-applied-devbox/scripts/sync-worktree-and-run \ + ~/code/codex-worktrees/pr-16620 +``` + +This is intentionally direct. It skips separate validation steps and lets the +real sync/build path prove whether the environment is healthy. + +## Key rule for concurrent builds + +- Keep each worktree as its own Bazel workspace path. +- Let Bazel derive a separate `output_base` per worktree automatically. +- Reuse the shared caches from `.bazelrc`: + - `~/.cache/bazel-disk-cache` + - `~/.cache/bazel-repo-cache` + - `~/.cache/bazel-repo-contents-cache` +- Do not force a shared `--output_base` across two live worktrees. + +On `dev`, this has already been validated with two mirrored worktrees: + +- both builds started at the same second +- each worktree got its own Bazel server and `output_base` +- both builds reused shared cache state and completed successfully + +## Script + +The script lives at: + +`skills/codex-applied-devbox/scripts/sync-worktree-and-run` + +Default behavior: + +- host: `dev` +- local worktree root: `~/code/codex-worktrees` +- remote mirror root: `/tmp/codex-worktrees` +- remote command: + `cd codex-rs && export PATH=$HOME/code/openai/project/dotslash-gen/bin:$HOME/.local/bin:$PATH && bazel build --bes_backend= --bes_results_url= //codex-rs/cli:cli` +- prints the exact copy-paste remote Codex Bazel run command for the mirrored checkout +- the helper command uses `cargo run -p codex-cli --` because that path has + been verified on `dev` +- do not switch the helper command back to Bazel `run` on `dev` until the + remote linker failure is resolved + +Example: + +```bash +skills/codex-applied-devbox/scripts/sync-worktree-and-run \ + ~/code/codex-worktrees/my-feature +``` + +This will mirror: + +- local: `~/code/codex-worktrees/my-feature` +- remote: `/tmp/codex-worktrees/my-feature` + +It will print: + +```bash +ssh -t dev 'cd /tmp/codex-worktrees/my-feature/codex-rs && cargo run -p codex-cli --' +``` + +Custom host, remote root, and command: + +```bash +skills/codex-applied-devbox/scripts/sync-worktree-and-run \ + --host dev \ + --remote-root /tmp/codex-worktrees \ + --command 'cd codex-rs && export PATH=$HOME/code/openai/project/dotslash-gen/bin:$HOME/.local/bin:$PATH && bazel build --bes_backend= --bes_results_url= //codex-rs/tui:tui' \ + ~/code/codex-worktrees/my-feature +``` + +## Recommended setup + +1. Create the local worktree from your main Codex checkout. + +```bash +mkdir -p ~/code/codex-worktrees +git -C ~/code/codex worktree add -b my-feature \ + ~/code/codex-worktrees/my-feature origin/main +``` + +2. Edit locally or fetch the PR/ref you want to test. + +3. Sync and build remotely immediately: + +```bash +skills/codex-applied-devbox/scripts/sync-worktree-and-run \ + ~/code/codex-worktrees/my-feature +``` + +4. Repeat sync/build as needed after local edits. + +## Retrospective Notes + +The main friction in a real run was not rsync itself. It was operator delay +before the first real attempt: + +- checking whether a matching worktree already existed before simply creating + the one needed for the task +- verifying host reachability before letting the real sync prove it +- remembering the mirrored remote path after the sync +- hand-writing the SSH command needed to run Codex in that mirrored checkout +- waiting through a cold Bazel build with no simple "jump in here yourself" + command printed by the script + +The current script update addresses the third and fourth issues by printing the +exact `ssh -t ...` command for running Codex in the mirrored checkout. +This skill update addresses the first two issues by telling the operator to +start the end-to-end flow sooner and only investigate after an actual failure. + +The next improvements worth making, if you want this flow to feel faster and +more automatic, are: + +- add `--pr ` so the script can fetch `pull//head` and create or + reuse `~/code/codex-worktrees/pr-` itself +- add `--tmux-window ` support so the remote command can start in a named + tmux session/window and print the exact follow/log command +- add an optional "sync only changed files" mode driven by git status or + `git diff --name-only` for large worktrees +- add an optional `--bazel-target