runtime-communication

name	runtime-communication
description	Use this skill when working inside the research_mvp tmux runtime with fixed agents (leader, researcher, trainer) and you need to read shared thread messages, inspect per-agent inboxes, delegate tasks between agents, or follow the repository's runtime communication contract. Specifically for the file-backed runtime CLI under research_mvp/runtime_cli.py.
user-invocable	true
triggers	["runtime communication","read the shared thread","delegate to researcher","send to trainer","check agent inbox","runtime_cli","leader to researcher message"]

Runtime Communication

Use this skill only for the local research_mvp runtime.

Files To Read First

• AGENTS.md
• research_mvp/runtime.toml

Commands

Use the configured runtime CLI:

python -m research_mvp.runtime_cli --config research_mvp/runtime.toml status
python -m research_mvp.runtime_cli --config research_mvp/runtime.toml thread tail -n 50
python -m research_mvp.runtime_cli --config research_mvp/runtime.toml inbox list leader

Messaging Rules

• Shared thread is for summaries, planning context, progress reporting, and visibility.
• Direct agent work must go through targeted inbox delegation.
• If you need one specific agent to receive a message, use delegate or thread send through runtime_cli. Do not hand-edit thread.jsonl, because that does not create an inbox delivery.
• Formal long-running training should be submitted to an external train_service, not left running inside the trainer tmux pane.
• If the human request is to start a task under recipe/<name>/, first read recipe/<name>/data.md, recipe/<name>/overview.md, and recipe/<name>/start_prompt.md.
• Treat recipe/<name>/ tasks as Kaggle-style competition tasks by default unless the recipe explicitly says otherwise.
• For a new recipe/<name>/ task, do EDA before baseline iteration. Put EDA scripts, notes, and charts under <workdir>/eda/.
• This runtime is a machine-learning baseline team. Default iteration should follow the repository's existing baseline naming, such as baseline_v10, baseline_v11, baseline_v12.
• Each version should usually contain multiple experiments, managed by yaml configs under baseline/experiments_v*/.
• Default layout:
  • experiment scripts, yaml configs, and helpers in <workdir>/baseline/
  • code in <workdir>/src/baseline/
  • data in <workdir>/data/
  • outputs, checkpoints, metrics, and logs in <workdir>/output/
  • version design and result docs in <workdir>/docs/
  • versioned experiment configs typically under <workdir>/baseline/experiments_v11/
  • versioned formal runners typically under <workdir>/baseline/run_experiments_v11.sh
  • versioned outputs typically under <workdir>/output/baseline_v11/
• For each version, keep one formal version runner script in baseline/, typically baseline/run_experiments_v11.sh. That runner should call python baseline/run_baseline.py --config baseline/experiments_v11/<config>.yaml multiple times.
• runtime_root is only for runtime state, inboxes, and thread data. Do not use it for checkpoints, artifacts, caches, or reports.
• Default training behavior should be observable: unless the human explicitly asks for denser logging, training code should emit at least one meaningful progress log per epoch.
• Good coordination uses both:
  • direct inbox delegation for execution
  • shared thread updates for human visibility and cross-agent context
• Runtime agents should not use control-plane commands like up, attach, or supervise.
• Avoid relying on status from inside a runtime agent. Use thread, inbox, artifacts, and direct delegation instead.
• Prefer:

python -m research_mvp.runtime_cli --config research_mvp/runtime.toml delegate --from leader --to researcher "..."

instead of only writing:

leader -> all: researcher should do ...

Leader Workflow

For each new task:

1. Read latest shared thread and relevant inboxes.
2. Break the task into direct assignments.
3. If the human starts a recipe/<name>/ task, first assign recipe reading and EDA. Do not jump straight to model iteration.
4. If training is needed, first ask researcher for a versioned package that follows the repository layout: code in src/baseline/, configs in baseline/experiments_v*/, a formal runner such as baseline/run_experiments_v11.sh, outputs under output/baseline_v*/, and a design note in docs/ using the existing baseline_v*_exp*.md pattern.
5. Expect exactly one formal version runner script per version under baseline/; it should fan out to multiple experiments via repeated python baseline/run_baseline.py --config ... calls.
6. Review the training package before queue submission. This includes checking that src/baseline/train.py and related scripts provide enough intermediate logs to observe training progress, plus a clear startup log that confirms training has actually begun.
7. Ask researcher to complete the minimal dry run; it should validate startup and configuration without drifting into real training.
8. Only after that hand the package to trainer for queue submission.
9. Delegate to each target agent with delegate.
10. Write one concise leader -> all summary to the shared thread.
11. After a version is completed and worth preserving, make a git commit covering the relevant src/baseline/ and baseline/ changes.
12. Every 5 baseline versions, stop and compare the current team path against reference solutions or newly researched alternatives. Explicitly note the main gaps and the most promising ideas to borrow.
13. Convert the most credible borrowable ideas from that review into concrete next experiments or follow-up tasks.
14. Re-check inbox/thread before deciding the next action.
15. Do not stop at a version summary, result note, or commit. After each version closes, immediately delegate the next version or ask one concrete blocking question to the human.

Do not:

• restart the runtime on your own
• treat tmux/socket repair as part of the normal task
• spend cycles checking infrastructure health unless the human explicitly asks for runtime repair

Worker Workflow

• Treat inbox messages as executable tasks.
• Report progress, completion, and blockers back to leader by default.
• If the recipient is specifically leader, prefer python -m research_mvp.runtime_cli --config research_mvp/runtime.toml delegate --from <worker> --to leader "..." so the message lands in both the thread and leader inbox.
• Use shared-thread updates for milestone visibility, artifact announcements, and high-value cross-agent context.
• If blocked, say what you need and who should act next.

Additional trainer-specific rule:

• trainer should only do job submission and result triage inside the runtime.
• Once a formal training job is submitted, treat the task as waiting on an external service.
• When a callback arrives from the training service, inspect the result and report back to leader.
• After submitting a training job, wait at least 1 second before querying status or queue state again.
• Do not draft or publish the final training report until the result callback has actually arrived.
• trainer should not run local dry runs by default; dry runs belong to researcher.
• Once researcher has confirmed the minimal dry run passed, submission to train_service should normally follow immediately rather than waiting for another manual nudge.
• When reporting the submission, include train_task_id, script_path, technical_focus, script_args, and workdir.
• Default dry run should use python baseline/run_baseline.py --config <yaml> --dry-run --fold 0.
• Default formal submission should use a real script file under <workdir>/baseline/, typically baseline/run_experiments_v11.sh, or another queue-ready shell wrapper created for that version.
• Before saying train_service is unavailable, first verify it with a concrete request such as curl -sS http://127.0.0.1:8100/queue.
• For localhost endpoints like 127.0.0.1:8100 and 127.0.0.1:8090, bypass shell proxy settings. Prefer curl --noproxy '*' ... or NO_PROXY=127.0.0.1,localhost curl ....
• When calling POST /jobs, use real existing paths for script_path and workdir; do not reuse placeholder values like /abs/path/to/train.sh.
• If an HTTP call fails, report the exact URL, command, status code, and response body to leader instead of a vague statement like “127.0.0.1:8100/8090 returned 502”.

Additional researcher-specific rule:

• researcher owns the minimal dry run for newly written training code and scripts.
• For recipe/<name>/ tasks, researcher should begin by reading the three recipe docs and producing EDA assets under eda/ before proposing iterative model work.
• That dry run should validate startup, config parsing, data path resolution, and dependency wiring without drifting into real training.
• src/baseline/train.py should emit a clear startup log before training begins so humans and agents can tell that the job truly started.
• After designing each experiment version, researcher should write the design note to docs/ using the existing pattern, such as docs/baseline_v11_1_exp.md.

Additional trainer-specific documentation rule:

• After results come back from train_service, trainer should write a result summary to docs/ using the matching result-note pattern, such as docs/baseline_v11_1_exp_result.md.
• That result summary should default to the same general style as docs/baseline_v11_1_exp_result.md: one-line conclusion first, then Markdown tables for the key comparisons.
• If multiple experiments, folds, or configs are involved, prefer a compact table, but choose columns according to the current task rather than a fixed project-specific schema.
• Even for a single run, include at least one compact Markdown table for metrics instead of only prose.
• After each completed baseline_v* version, trainer should also generate a historical PNG trend chart under docs/ that tracks the best top 3 experiments of each baseline version across versions.
• Use a filename like docs/baseline_v08_to_v11_top3_trend.png.
• When multiple baseline versions are included, connect versions with line plots so humans can visually track the trend over time.
• Mention the generated PNG path and the high-level takeaway in the corresponding result summary.