skills/moos-ivp-mission-builder/SKILL.md

---
name: moos-ivp-mission-builder
description: "Build or repair the ordinary mission layer for one standalone MOOS-IvP mission: launchers, meta files, helm layout, communities, ports, nsplug targets, viewer setup, and README updates. For self-evaluating missions, use moos-ivp-eval-mission-builder as the primary skill."
---

# MOOS-IvP Mission Builder

## Overview

Use this skill for one ordinary mission folder: launchers, meta files, helm
behavior layout, mission README, and target generation. The mission may be
headless-capable, but it should remain human-readable and runnable on its own.
Optimize for the quality of that single mission, not for batch execution.

For custom app config surfaces, use `moos-app-builder`. For custom behavior
config surfaces, use `ivp-behavior-builder`. For upstream app or behavior
parameters not already clear from the chosen baseline or local repo convention,
use `moos-ivp-docs`. Use `moos-alog-analysis` for existing logs or when a
required claim cannot be established through bounded live evidence.

## Core Rules

- Prefer copying `assets/baseline-single-vehicle/` or
  `assets/baseline-two-vehicle/` and adapting it over writing launchers from
  scratch.
- Treat bundled launch scripts as near-copy templates. Change names, defaults,
  mission-specific parameters, app runs, and forwarded arguments as needed, but
  preserve the launcher structure unless the existing project has a stronger
  local convention.
- Before adding custom mission plumbing or functionality, determine whether
  existing apps, behaviors, or parameters already achieve the requested effect
  by checking local examples and docs/source; add new functionality only when
  none fits.
- Keep `launch.sh`, `launch_vehicle.sh`, `launch_shoreside.sh`, and `clean.sh`
  convention-bound. Preserve their `Part N` structure and help summaries.
- Keep `launch.sh` as the human-facing mission-level launcher.
- Keep sublaunchers thin: each sublauncher generates one community and launches
  it unless `--just_make` is set.
- Let top-level `launch.sh` own interactive `uMAC`; pass `--auto` into
  sublaunchers so they do not open nested `uMAC` sessions.
- Use `--just_make` as the first validation path. It proves target generation,
  not runtime app validity.
- During live validation, preserve the canonical launcher structure and keep
  the top-level `launch.sh`/`uMAC` session in the foreground. Use the shortest
  timeout that proves the claim, capped at 30 seconds unless a stated
  task-specific reason requires longer. After it stops, verify scoped processes
  and selected ports are clear.
- Include caller-controlled port overrides when adding or repairing launchers:
  `--shore_mport`, `--shore_pshare`, `--veh_mport`, and `--veh_pshare` for a
  one-vehicle mission. These make the mission easy to run beside other local
  MOOS work and easy to validate on non-default ports.
- Keep `ServerHost = localhost`; map each sublauncher's `--ip` value to
  `pHostInfo.default_hostip_force`, and map vehicle `--shore` separately to the
  shoreside broker route.
- Use `nsplug --strict --force -x` for both direct and `--auto` sublauncher
  generation so unresolved macros fail consistently and `.moosx` / `.bhvx`
  sidecars remain supported.
- Launchable mission examples should include `ProcessConfig = ANTLER` with the
  `Run = ...` roster. A standalone `ProcessConfig = <AppName>` block is
  appropriate only for intentional snippets or app help text.
- Treat plug files as discretionary style. Follow the local repo convention:
  keep small missions readable with direct `ProcessConfig` blocks unless a plug
  file clearly removes shared duplication or the project already uses plug
  files.
- Keep `.moos` and `.bhv` files in the local boxed-header style:

  ```text
  //-------------------------------------------------
  // FILE: <filename>
  // NAME: <author>
  //-------------------------------------------------
  ```

- Use `//----------------------------------------------------` for internal
  section dividers between `ProcessConfig` or `Behavior` blocks.
- Add a short `README.md` with scenario, files, common run commands, and
  expected operator action.
- Do not add `pAutoPoke`, `pMissionEval`, `uMayFinish`, case loops, matrix
  execution, or result aggregation here unless the user explicitly asks for a
  self-evaluating test mission. They are not part of an ordinary standalone
  mission.

## Workflow

1. Resolve the mission shape.
   - single vehicle vs multiple vehicles
   - simulated vehicle vs hardware/interface app
   - shoreside/vehicle split vs standalone community
   - GUI required vs headless-capable
   - custom app or behavior integration needs
2. Start from `assets/baseline-single-vehicle/` for one vehicle or
   `assets/baseline-two-vehicle/` for two vehicles unless the existing repo
   already has a closer mission family.
3. Read `references/mission-style.md` before editing launchers or meta files.
4. Read `references/baseline-single-vehicle.md` or
   `references/baseline-two-vehicle.md` before adapting a bundled baseline.
5. Edit the mission files for the requested scenario.
   - Keep the wrapper skeleton intact.
   - Add only the MOOS apps needed for the mission.
   - Keep behavior blocks small and named clearly.
   - Preserve port override plumbing end to end.
6. Add or update `README.md`.
7. Validate with `./launch.sh --just_make --nogui <warp>`.
8. Inspect generated `targ_*.moos` and `targ_*.bhv`.
9. Run live mission validation only if requested or necessary for the change.
   - When runtime correctness matters, use `references/validation.md` to define
     the live and post-run `.alog` evidence needed before calling the mission
     clean.

## Reference Use

- Read `references/mission-style.md` for wrapper and file-style rules.
- Read `references/baseline-single-vehicle.md` for the bundled baseline design.
- Read `references/validation.md` before reporting a mission as done.
- Use `scripts/static_check_mission.sh <mission-dir>` for a quick structural
  check after creating a mission.
- Use `scripts/check_generated_ports.sh <mission-dir> --port_base=<base>` to
  verify that non-default port overrides are reflected in generated targets.
  Add `--keep-targets` when you need to inspect the generated files afterward.
- Use `scripts/check_generated_networking.sh <mission-dir>` to verify that
  sublauncher `--ip` values control advertised `pHostInfo` identity, vehicle
  `--shore` controls the broker route, and MOOSDB connections remain local.

## Validation Checklist

- `launch.sh --help`, `launch_vehicle.sh --help`, and
  `launch_shoreside.sh --help` describe the real arguments.
- `./launch.sh --just_make --nogui <warp>` succeeds.
- Non-default port target generation succeeds, for example with
  `scripts/check_generated_ports.sh`.
- Custom-address target generation succeeds with
  `scripts/check_generated_networking.sh`.
- Generated targets include the intended ports, community names, apps, behavior
  file name, and `MOOSTimeWarp`.
- The top-level launcher opens at most one `uMAC` session.
- Sublaunchers receive `--auto` from top-level `launch.sh`.
- `clean.sh` removes generated targets and logs but does not call `ktm`,
  `pkill`, or mission-specific teardown.
- `README.md` explains how to run the mission.