Moos Ivp Mission Builder

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:

  //-------------------------------------------------
  // 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.