MOOS-IvP Skills

View saved version →

---
name: ivp-behavior-builder
description: "Build or modify user-owned IvP helm behaviors outside the core MOOS-IvP source tree: BHV_* C++ classes, IvPBehavior lifecycle methods, shared behavior libraries, IVP_BEHAVIOR_DIRS wiring, and behavior-specific configuration parameters."
---

# IvP Behavior Builder

## Overview

Use this skill for custom IvP helm behavior development against the local MOOS-IvP checkout. Treat MOOS-IvP as the dependency and example source unless the user explicitly asks to patch core MOOS-IvP.

## MOOS-IvP Checkout Resolution

When this skill needs a local MOOS-IvP checkout, resolve it in this order:

1. Path explicitly provided by the user.
2. `MOOS_IVP_ROOT` from the shell environment.
3. Active task workspace if it contains `ivp/src`.
4. Parent or sibling directories near the active task workspace.
5. Common home locations such as `~/moos-ivp`, `~/src/moos-ivp`, `~/repos/moos-ivp`, and `~/projects/moos-ivp`.
6. A bounded shallow home search for a directory named `moos-ivp`, excluding noisy folders.

Validate a candidate by confirming `ivp/src` exists and `scripts/GenBehavior` is executable.

If no valid checkout is found and the task requires behavior source generation, build wiring, examples, headers, or libraries, stop and ask the user for the checkout path before editing code, generating build files, or using placeholder paths.

## Core Rules

- Default new behaviors to third-party dynamic shared libraries in the user project.
- Do not add new behavior source to core `ivp/src/lib_behaviors*` unless the user explicitly asks to modify core MOOS-IvP.
- Use `$MOOS_IVP_ROOT/scripts/GenBehavior` when there is no close existing behavior to copy.
- Run `GenBehavior` only in a clean behavior source location; it appends to `BHV_<Name>.h/.cpp` if those files already exist.
- Name behavior files and classes `BHV_<Name>.h/.cpp` and `BHV_<Name>`.
- Export `createBehavior` for dynamic loading.
- Build dynamic behaviors as shared libraries named so the output is `libBHV_<Name>.dylib` on macOS or `libBHV_<Name>.so` on Linux.
- Ensure `pHelmIvP` can find the library. Default to the user's shell convention: add the project `lib` directory to `IVP_BEHAVIOR_DIRS`, usually in `.bashrc` or the user's equivalent shell startup file when they ask for persistent setup. Use mission-local `ivp_behavior_dir = <project>/lib` only when the user explicitly wants a self-contained mission, non-interactive execution cannot assume shell setup, or an existing mission already uses that convention.
- Use `.bhv` blocks for mission configuration; do not bake mission-specific parameters into the constructor.
- Call `IvPBehavior::setParam(param, val)` first when the behavior should accept standard behavior parameters.
- Apply `m_priority_wt` to returned IvP functions.
- Use `postWMessage()` or `postEMessage()` for behavior warnings/errors instead of silent failure.
- Preserve the generator-style metadata comment box at the top of source files and update `NAME`, `ORGN`, `FILE`, and `DATE` to match the user project.
- Use short comments before non-obvious behavior logic; do not add comments that merely restate simple code.
- Reuse existing MOOS-IvP behavior, IvP build, geometry, contact, and utility libraries before writing custom parsers, objective-function machinery, or geometry math.
- During live validation, keep `pAntler` in the foreground unless the task
  explicitly requires persistent or concurrent execution. 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.
- Do not commit or present build directories/binaries as source changes unless the user's project already tracks generated artifacts.

## Workflow

1. Choose the behavior shape.
   - Default to the simplest shape that matches the requested effect.
   - Posting-only behavior: use when the behavior should publish state/flags but not influence helm decisions.
   - Single decision variable objective: use ZAIC, for example speed-only, course-only, or depth-only.
   - Coupled multi-variable objective: use AOF plus Reflector only when utility genuinely depends on multiple decision variables together.
   - Contact-relative behavior: use `IvPContactBehavior` only for behaviors centered on another vehicle/contact.
2. Choose the starting point.
   - New simple behavior: create and enter the behavior library source directory, then run `GenBehavior <Name> "<Author>"` there.
   - Inspect similar behaviors as references. Copy a behavior when the user explicitly asks or when it is obviously the nearest local-project base.
3. Wire the build.
   - Read `references/behavior-build.md`.
   - Add or update an `ADD_LIBRARY(BHV_<Name> SHARED ...)` block.
4. Implement lifecycle.
   - Read `references/behavior-patterns.md`.
   - Constructor: descriptor/defaults, `subDomain`, `addInfoVars`.
   - `setParam`: replace the generator placeholder so standard params are accepted through `IvPBehavior::setParam(param, val)` before custom parsing.
   - `onSetParamComplete`: validate required and interdependent params.
   - `onRunState`: read info-buffer state, build/post output, return an `IvPFunction*` or `0`.
5. Implement IvP function construction if needed.
   - Read `references/ivp-function-patterns.md`.
6. Add mission integration only when needed. Use `moos-ivp-mission-builder`
   when the task expands into ordinary mission launchers, ANTLER rosters,
   vehicle/shoreside layout, or pMarineViewer operator controls.
   - Add a `Behavior = BHV_<Name>` block in the relevant `.bhv`.
   - Ensure helm mission files have required geodesy context such as `LatOrigin` and `LongOrigin`; missing origins can put `pHelmIvP` in `MALCONFIG` before behavior loading is exercised.
   - Prefer adding the behavior library directory to `IVP_BEHAVIOR_DIRS` when persistent shell setup is in scope.
   - Add `ivp_behavior_dir = <project>/lib` to `pHelmIvP` config only for explicit self-contained, non-interactive, or existing-mission-convention cases.
7. Validate.
   - Configure/build the project.
   - Confirm the shared library lands in the project `lib/`.
   - Confirm the shared library exports `createBehavior` before runtime loading.
   - If mission config changed, verify `pHelmIvP` can load the behavior through
     a normal `pAntler` mission launch when feasible. Treat direct `pHelmIvP`
     execution as a narrow fallback only; if used, launch with app name
     `pHelmIvP` on `PATH` or pass `--alias=pHelmIvP` so the process reads
     `ProcessConfig = pHelmIvP`.
   - For isolated runtime tests, set `IVP_BEHAVIOR_DIRS` to only the generated
     project `lib` directory unless inherited behavior dirs are part of the
     test.

## Reference Use

- Read `references/behavior-build.md` before writing behavior CMake or mission loading lines.
- Read `references/behavior-patterns.md` before implementing lifecycle methods.
- Read `references/ivp-function-patterns.md` before building an objective function.
- Read `references/behavior-examples.md` when choosing local examples to inspect.

## Validation Checklist

- Shared library builds with the expected `libBHV_*` name.
- Standard behavior params still work.
- Required custom params are validated.
- `addInfoVars()` covers every info-buffer variable read by the behavior.
- `onRunState()` handles unavailable inputs safely; do not invent a freshness
  limit—use a configurable limit only when required by the user or an existing
  interface or mission contract.
- Returned IPF has `m_priority_wt` applied.
- Mission `.bhv` block uses behavior type `BHV_<Name>` and a unique `name`.
- Behavior library path is available to `pHelmIvP`.
- Shared library exposes `createBehavior` as a dynamic symbol.
- Runtime load checks look for explicit success such as `About to load behavior library: BHV_<Name> ... SUCCESS`, `BehaviorSet: all_builds_ok: true`, or equivalent appcast/console confirmation.

Referenced files: 6

View saved version →

---
name: moos-alog-analysis
description: "Analyze existing MOOS .alog files for post-run, log-backed questions such as mission reconstruction, variable history, helm-state context, or timestamped incident evidence."
---

# MOOS ALog Analysis

## Overview
Use this skill for two jobs:
- reconstruct what happened in a mission
- investigate suspicious event(s) in a mission

## Shell Assumption
Run `aloggrep`, `aloghelm`, and `alogscan` directly in the current agent shell.

Do not wrap `alog*` commands in an extra shell bootstrap step.

## Source of Truth
Analyze only the original `.alog` files.

Never read or rely on derived artifacts such as:
- `*_alvtmp/`
- `*.klog`
- any other files generated by `alogview` or similar viewers

These files are not source evidence for mission analysis. If they exist, ignore them and continue using the `.alog` files only.

## Workflow
1. Find the relevant `.alog` files.
2. If you already know the variable, signal, or specific variable set you care about, go straight to targeted `aloggrep` queries.
3. If you need mission phases, behavior transitions, or helm context, use `aloghelm`.
4. If you need variable discovery, use `scripts/alogvars.sh <alog_path>` first. Add one or more prefixes when you already know the variable family.
5. Read raw log lines only when you need the exact posting format, need to resolve source ambiguity, or need to cite original evidence lines.
6. If the question is geometric or numeric, extract the relevant variables and analyze them directly.

## Tool Policy
Autonomous tools:
- `aloggrep`
- `aloghelm`
- `alogscan`
- `scripts/alogvars.sh`

Use them with this bias:
- `aloggrep` is the default tool when you already know the variable names or have already narrowed the problem to a specific variable set.
- `aloghelm` is the default mission-context tool.
- `scripts/alogvars.sh` is the default discovery tool when the variable names are still unknown.
- Raw `alogscan --sort=vars --nocolors` is acceptable for a full variable
  inventory when you actually need counts, sources, or full scan metadata, but
  prefer `scripts/alogvars.sh` for compact unknown-variable discovery.

Read `references/alog-tool-guide.md` when you need concise examples for `aloggrep`, `aloghelm`, or `alogvars.sh`.

## Mission Overview
For mission reconstruction:
- if the key variables are already known, use `aloggrep` immediately
- if the question names a specific variable set, stay targeted and use one or more `aloggrep` queries for that set before doing broader discovery
- use `aloghelm` first for modes and behaviors when mission phases matter
- use `scripts/alogvars.sh` only when the variable set is still unclear
- inspect raw log lines only when the exact payload format or source matters

## Incident Forensics
For one event or anomaly:
- identify the relevant variables to the event
- if the user already gave a variable set, start with that set and use `aloggrep` directly
- if the variable names are still unknown, use `scripts/alogvars.sh` to discover them compactly
- use `aloggrep` once the variables are known
- use `aloghelm` if the incident may be explained by a mode or behavior change
- use shell or Python for custom logic
- use raw log lines only when you need exact evidence or payload structure
- for source attribution, prefer `aloggrep <alog> <var> --format=time:var:src`
  when the installed build emits all requested fields. Some builds advertise
  that format but emit only the source field; in that case use a narrow raw
  `.alog` check for timestamped source evidence instead of broad log reads.

If the question is about loops, turns, divergence, rendezvous, stops, or similar geometry, do not expect an `alog*` command to answer it directly.
For these cases, still extract evidence only from the `.alog` file.


## Evidence Standard
- Cite exact command(s) used.
- Cite timestamped output lines for each conclusion.

## Reference
Use `references/alog-tool-guide.md` only if more detail is needed.

Referenced files: 4

View saved version →

---
name: moos-app-builder
description: "Build or modify user-owned MOOS apps outside the core MOOS-IvP source tree: C++ app generation, project build wiring, MOOS mail/config/iterate logic, app help/interface text, and app-specific ProcessConfig examples."
---

# MOOS App Builder

## Overview

Use this skill for user application development against the local MOOS-IvP checkout. Treat MOOS-IvP itself as the dependency and example source unless the user explicitly asks to patch core MOOS-IvP.

## MOOS-IvP Checkout Resolution

When this skill needs a local MOOS-IvP checkout, resolve it in this order:

1. Path explicitly provided by the user.
2. `MOOS_IVP_ROOT` from the shell environment.
3. Active task workspace if it contains `ivp/src`.
4. Parent or sibling directories near the active task workspace.
5. Common home locations such as `~/moos-ivp`, `~/src/moos-ivp`, `~/repos/moos-ivp`, and `~/projects/moos-ivp`.
6. A bounded shallow home search for a directory named `moos-ivp`, excluding noisy folders.

Validate a candidate by confirming `ivp/src` exists and `scripts/GenMOOSApp_AppCasting` is executable.

If no valid checkout is found and the task requires app source generation, build wiring, examples, headers, or libraries, stop and ask the user for the checkout path before editing code, generating build files, or using placeholder paths.

## Core Rules

- Use `GenMOOSApp_AppCasting` for new apps.
- If the project has `src/CMakeLists.txt`, update it with `ADD_SUBDIRECTORY(<app-dir>)`.
- If the project has no build skeleton, create the smallest project-level CMake needed for the new app and point it at the resolved `MOOS_IVP_ROOT`.
- Keep MOOS communication boundaries clear: `OnNewMail()` ingests mail, validates messages, and updates state through `handleMail*` helpers; `Iterate()` owns most business logic, recurring work, and state-derived publications.
- Keep config parsing in `OnStartUp()`, using `handleConfig*` helpers for nontrivial values and AppCasting warnings for bad or unhandled config.
- Keep subscriptions centralized in `registerVariables()` and call `AppCastingMOOSApp::RegisterVariables()` in AppCasting apps.
- Update `_Info.cpp` as part of the app implementation: synopsis, example config, subscriptions, publications, and options must describe the real app.
- Preserve the generator-style metadata comment box at the top of source files and update `NAME`, `ORGN`, `FILE`, and `DATE` to match the user project.
- Use short comments before non-obvious logic blocks; do not add comments that merely restate simple code.
- Reuse existing MOOS-IvP libraries and helpers before writing new parsing, geometry, contact, logic, or AppCasting support code.
- Use local style: MOOS variables are usually uppercase with underscores; mission config params are usually lowercase snake case; C++ members use `m_`; helpers commonly use `handleMail*`, `handleConfig*`, `post*`, `update*`.
- Build and run `--help`, `--example`, and `--interface` as binary smoke checks
  before finishing when feasible. These prove the app starts and its
  self-documentation is wired; they do not prove mission runtime config.
- During live validation, keep `pAntler` in the foreground unless the task
  explicitly requires persistent or concurrent execution. 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.
- Do not commit or present build directories/binaries as source changes unless the user's project already tracks generated artifacts.

## Workflow

1. Identify the app role and prefix.
   - `p`: process/control/monitoring app
   - `u`: utility or simulation-support app
   - `uFld`: shoreside field app
   - `i`: interface/driver app
   - If the user did not specify a prefix, use `p` for process/control/monitoring apps and `u` for utilities or simulation helpers.
2. Generate the starting point.
   - New app: run `$MOOS_IVP_ROOT/scripts/GenMOOSApp_AppCasting <Name> <prefix> "<Author>"` from the project source directory.
   - Inspect existing apps as references. Copy an existing app when the user explicitly asks or when it is obviously the nearest local-project base.
3. Wire the build.
   - Read `references/app-build.md` before creating or repairing project-level CMake.
   - Preserve existing project CMake style when present.
4. Implement app behavior.
   - Read `references/app-patterns.md` for mail/config/iterate/AppCasting conventions.
   - Store the latest relevant mail in state; keep expensive, repeated, or state-combining work in `Iterate()`. Publish directly from `OnNewMail()` only for trivial acknowledgments or explicitly requested immediate reactions.
   - Validate message type before using `GetDouble()` or `GetString()`.
5. Update user-facing app metadata.
   - `showSynopsis()`
   - `showExampleConfigAndExit()`
   - `showInterfaceAndExit()`
6. Use the smallest live environment that proves the app's runtime claims. A
   focused app can use a single-community `pAntler` configuration; add
   `moos-ivp-mission-builder` only when the task owns broader mission topology,
   routing, launchers, or controls—not merely for live app validation.
   - Use `ProcessConfig = <AppName>` with realistic `AppTick` and `CommsTick`.
   - If only source was requested, an example `ProcessConfig` in `_Info.cpp` is
     enough. If a runnable sample mission was requested, include the
     `ProcessConfig` and the `pAntler` or launcher context that actually starts
     the app.
   - Add the app to `pAntler` or the mission launcher pattern only if the existing mission uses that style.
   - Ensure the launcher can find the built app binary. For external projects,
     prefer a minimal `pAntler` validation mission with a launcher-local
     `PATH=<project>/bin:$PATH` extension, or document the persistent shell
     setup that puts the project `bin/` on `PATH`.
7. Validate.
   - Configure/build the project or target when feasible.
   - Run the generated binary with `--help`, `--example`, and `--interface` as
     smoke checks when those options are supported.
   - If runtime config matters, validate through a normal `pAntler` launch with
     `ProcessConfig = <AppName>` rather than treating a direct binary run as
     equivalent.
   - If a mission was touched, launch only when the user asked for runtime validation or the change is risky enough to justify it.

## Reference Use

- Read `references/app-build.md` when the project build layout is missing, broken, or unfamiliar.
- Read `references/app-patterns.md` before implementing nontrivial app logic.
- Read `references/app-examples.md` when choosing a representative app to inspect in the resolved `MOOS_IVP_ROOT`.

## Validation Checklist

- App has a project build entry.
- App links only the libraries it actually needs, plus `apputil` for AppCasting and `mbutil` for common utilities.
- `OnNewMail()` handles or deliberately ignores subscribed mail without warning on `APPCAST_REQ`.
- `registerVariables()` lists every subscribed variable.
- `showInterfaceAndExit()` matches actual subscriptions/publications.
- Build succeeds, or the blocker is reported with the exact missing dependency/error.
- `--help`, `--example`, and `--interface` reflect the real app and do not
  crash when supported.
- Runtime config, when relevant, is verified through `pAntler` with
  `ProcessConfig = <AppName>`, not by direct app-by-path execution alone.
- For clean-host or relocatable claims, run
  `<skill-dir>/scripts/check_portable_paths.sh <project-dir>`, resolving
  `<skill-dir>` as the directory containing this `SKILL.md`, and include a
  clean build with a caller-supplied non-default `MOOS_IVP_ROOT`.

Referenced files: 6

View saved version →

---
name: moos-ivp-docs
description: "Consult MIT MOOS-IvP PDFs and local ivp/src for documentation-backed answers about apps, behaviors, parameters, concepts, upstream semantics, or doc-vs-source differences."
---

# MOOS-IVP Docs

## Overview

Use this skill to ground MOOS-IvP answers in the live MIT manual PDFs and, when needed, the local `moos-ivp` source tree.

Read `references/doc-selection.md` when you need the filename-family rules, alias map, repo discovery order, or source-inspection rules.

## When To Use

Use this skill when the task is about:
- MOOS-IvP app or utility behavior
- IvP behavior semantics or parameters
- MOOS-IvP terminology, architecture, or conceptual questions
- `.moos` or `.bhv` settings whose upstream meaning should be confirmed in the docs
- comparing upstream documentation against a local `moos-ivp` checkout

## When Not To Use

Do not use this skill as the primary tool for:
- `.alog` mission reconstruction or incident forensics
- launching or tearing down missions
- purely local code-editing tasks when no documentation question is involved

If the task is mainly about `.alog` evidence, use `moos-alog-analysis` first.

## Authority Model

Apply this authority order:

1. If the user explicitly asks for documentation, or if you are unsure about upstream MOOS-IvP behavior, use the MIT PDFs first. Do not answer from memory in this case.
2. If the user asks what the current checkout actually does, inspect local `ivp/src` first and use MIT PDFs only as upstream context.
3. If MIT docs and local source differ, say so explicitly and cite both.
4. Do not widen to broader web sources in v1.

Treat the MIT PDFs as the upstream source of truth for documented semantics when asked or when uncertain. Treat local `ivp/src` as the source of truth for checkout-specific implementation behavior.

## MIT PDF Lookup Workflow

1. Open the live MIT index at `https://oceanai.mit.edu/ivpman/pdfs/` first.
2. Classify the question as one of:
   - app or utility
   - behavior
   - conceptual or architecture
   - tutorial or operator help
3. Build a shortlist of 1 to 3 candidate PDFs from the live filenames only.
   - For an exact app or utility name, prefer the matching `app_*` filename first if it exists, for example `uQueryDB` -> `app_uquerydb.pdf`.
4. Open the best candidate first. If opening the PDF from the index fails, construct the direct PDF URL from the filename shown in the index and open that URL directly. If both attempts fail, treat that document as unavailable and either try another candidate or fall back to local source inspection.
5. Use in-PDF search to verify the app name, behavior name, parameter, or topic appears in the document before relying on it.
6. Open a second or third candidate only if the first document is incomplete, too general, or ambiguous.
7. Answer with the selected PDF URL and line citations. If the PDF tool does
   not provide stable line numbers, use `pdftotext -layout <pdf> - | nl -ba`
   or an equivalent extraction artifact and label those as extracted-text line
   spans rather than canonical PDF anchors.

Representative pattern:

- `uQueryDB` question: inspect the live index, shortlist `app_uquerydb.pdf`, verify `uQueryDB` appears inside the PDF, and only then fall back to local `ivp/src/uQueryDB` if the PDF is unavailable or incomplete.

Critical rule:
- Do not hard-default a conceptual question to a specific `chap_*` PDF before inspecting the live index and verifying the topic inside the PDF.

## Local Repo Fallback Workflow

Use local source inspection when:
- the docs are unavailable
- no clear PDF match exists
- the PDF text is too weak to settle the question
- the user asks what the current checkout actually does
- the local checkout version is newer or more specific than the available MIT PDFs

When local MOOS-IvP source is needed, resolve the checkout in this order:

1. Path explicitly provided by the user.
2. `MOOS_IVP_ROOT` from the shell environment.
3. Active task workspace if it contains `ivp/src`.
4. Parent or sibling directories near the active task workspace.
5. Common home locations such as `~/moos-ivp`, `~/src/moos-ivp`, `~/repos/moos-ivp`, and `~/projects/moos-ivp`.
6. A bounded shallow home search for a directory named `moos-ivp`, excluding noisy folders.

Prefer explicit common-root checks before broad `find` searches. If a bounded
home search is needed on macOS or a permissions-noisy system, suppress expected
permission noise, for example with `2>/dev/null`.

Validate a candidate repo by confirming:
- `ivp/src` exists
- recognizable app or behavior directories exist under `ivp/src`

If local source is required and no valid checkout is found, stop and ask the user for the checkout path. Do not answer source-specific questions from memory or weaker evidence.

If multiple repos are found, prefer the current workspace repo when applicable. Otherwise prefer the repo nearest to the current working directory and state which repo you used.

If the checkout has a versioned app or behavior with no same-version PDF in the MIT index, treat local source as authoritative for that version-specific behavior and cite MIT docs only as the nearest upstream reference.

## Citation Requirements

When you use this skill:
- cite the MIT PDF URL and PDF line spans when the docs path is used
- cite local file paths and line spans when the source path is used
- clearly label whether the answer is based on upstream documentation, local checkout source, or both
- say explicitly when MIT docs did not fully settle the question and the answer was completed from source inspection

## Conflict Handling

If docs and source disagree:
- separate the upstream-doc answer from the checkout-specific answer
- do not collapse them into a single blended claim
- explain which source is authoritative for each part of the answer

## Failure Modes

- MIT index unavailable: fall back to local source inspection if a repo can be found
- MIT index available but no clear PDF match: use local source if present, otherwise say no exact document was identified
- PDF text extraction weak: use nearby lines or a second supporting PDF, but do not overstate certainty
- repo not found: say that local source fallback was unavailable

## Coordination With Other MOOS Skills

- Use `moos-alog-analysis` first for existing `.alog` analysis. Bring this skill in only if documentation context would help interpret the findings.

Referenced files: 3

View saved version →

---
name: moos-ivp-eval-mission-builder
description: "Build or repair one self-evaluating MOOS-IvP mission by adding an evaluation layer to an ordinary mission: headless startup, pMissionEval grading, results.txt, uMayFinish/xlaunch completion, zlaunch automation, scoped teardown, and single-scenario validation."
---

# MOOS-IvP Eval Mission Builder

## Overview

Use this skill for one self-evaluating mission folder: a normal MOOS-IvP mission
with an added single-run grading contract. The mission should still be readable
and runnable by a person, but it must also run headlessly, decide pass/fail
inside the mission, write `results.txt`, and finish through the shared
`xlaunch.sh` / `uMayFinish` path.

For ordinary mission layout, use `moos-ivp-mission-builder` first. For multi-case
matrices, patch sweeps, parallel runs, or expected-vs-actual aggregation, use
`moos-ivp-harness-builder`. For post-run `.alog` evidence, use
`moos-alog-analysis`.

## Core Rules

- Start from an ordinary mission that already launches cleanly. Prefer the
  `moos-ivp-mission-builder` baselines or an existing nearby mission family.
- Add only the evaluation plumbing needed for one scenario:
  optional `pAutoPoke`, optional `uTimerScript`, `pMissionEval`,
  `results.txt`, and a thin `zlaunch.sh`.
- Keep `launch.sh` human-facing. It may accept `--xlaunched`, `--nogui`, and
  port overrides, but it should not contain case loops or result aggregation.
- Keep `zlaunch.sh` thin: parse automation arguments, truncate `results.txt`,
  call shared `xlaunch.sh`, validate that `results.txt` contains `grade=`, then
  apply project-local scoped cleanup.
- Let `xlaunch.sh --max_time=<secs>` own `uMayFinish` and the timed wait/stop
  contract. Do not duplicate that lifecycle in mission-local wrappers.
- Do not synthesize `grade=` or write the final result row from `zlaunch.sh`,
  `launch.sh`, or target-file parsing. `pMissionEval` must own the verdict and
  write `results.txt`; wrappers may only truncate, launch, wait, validate
  presence of `grade=`, and clean up.
- For cleanup backstops, copy `assets/moos_scoped_teardown.sh` into the target
  project as `<project-root>/scripts/moos_scoped_teardown.sh` if it does not
  already exist. Reuse an existing project-root helper unless it is clearly
  stale or incompatible.
- Prefer `pAutoPoke` to seed deploy and evaluation variables in moving
  missions. Unit-style evals may use `uTimerScript` or the app under test for
  readiness when there is no vehicle/deploy lifecycle. Do not put pass/fail
  logic in `pAutoPoke`.
- Use `pMissionEval` as the primary verdict owner. Prefer mission-level booleans
  or simple scalar checks over harness-side parsing of raw MOOS traffic.
- Prefer event-driven `pMissionEval` leads: evaluate when the mission-owned
  completion event occurs. Use `uMayFinish` through `xlaunch.sh --max_time` as
  the outer infrastructure ceiling. Use a time-driven evaluation-window lead
  only when non-completion is an expected mission outcome that should produce
  mission-owned `grade=fail`.
- Multiple `lead_condition` lines in the same aspect are allowed, but they are
  ANDed: all must be true before pass/fail conditions are evaluated. A
  `lead_condition` after pass/fail conditions starts the next ordered aspect.
  A single `lead_condition` may use textual `or` when each operand is
  parenthesized, for example `(EVENT_A = true) or (EVENT_B = true)`. Do not use
  `||`; it is not a supported `LogicCondition` operator.
- Treat `BHV_ERROR_SEEN=false` as a normal safety/integrity pass condition.
  Treat `BHV_WARNING` as advisory development evidence by default: inspect and
  investigate it with appcasts or `.alog` tools, but do not add a sticky
  `BHV_WARNING_SEEN` mailflag, result column, or pass condition unless the
  scenario is explicitly warning-intolerant and the warning signal is known to be
  stable rather than transient/retracted.
- Keep `results.txt` scalar and parseable. The only hard schema requirement is
  `grade=<pass|fail>`; fields such as `form=`, `eval=`, `timeout=`, domain
  facts, and `mhash=` are recommended evidence, not a mandatory metric set.
- `mission_mod` is optional mission-owned provenance. Use it only when one
  mission folder intentionally supports multiple named standalone modes. Omit
  it from single-scenario eval missions, and do not use it to represent harness
  cases.
- If a vehicle-local variable is graded shoreside, bridge it explicitly through
  the vehicle broker and shoreside broker.
- For GUI-capable eval missions, keep normal operator buttons available. Do not
  force appcast/realmcast viewer modes unless the evaluation scenario needs it.
- Do not add `--case`, `--jobs`, temp mission copies, per-case port blocks, or
  expected-vs-actual aggregation here. Those belong to the harness builder.

## Workflow

1. Confirm the base mission launches and generates targets.
2. Identify the smallest mission-owned pass/fail signal.
   - unit-style app variable
   - behavior end flag
   - arrival/collision/encounter outcome
   - load/process/host info signal
3. Add evaluation state to the relevant `.bhv` or app config.
   - When adapting an ordinary waypoint mission, make the graded behavior
     finite, such as `repeat = 0`, or add an explicit completion flag. A
     repeating operator survey is usually not a valid eval completion signal.
4. Bridge graded vehicle-local variables to shoreside when needed.
5. Add `pAutoPoke` or an equivalent explicit initializer for deploy and
   evaluation variables.
6. Add `pMissionEval` with simple lead condition(s), clear pass conditions,
   `result_flag = MISSION_EVALUATED = true`, and `report_file = results.txt`.
7. Add or update `zlaunch.sh` to set a mission-appropriate `MAX_TIME` default,
   accept `--max_time=<secs>` as an override, and forward the final value to
   `xlaunch.sh --max_time=<secs>`.
8. Add or update `README.md` with scenario, grading signal, and run commands.
9. Validate target generation, then run the headless cycle and inspect
   `results.txt`.

## Reference Use

- Read `references/eval-mission-style.md` for boundaries and file layout.
- Read `references/evaluator-apps.md` before wiring `pAutoPoke` or
  `pMissionEval`.
- Read `references/scenario-and-grading.md` before grading obstacles, contacts,
  moving/integration outcomes, or structured payloads.
- Read `references/zlaunch-xlaunch.md` before editing automation wrappers.
- Read `references/validation.md` before reporting an eval mission as done.
- Copy `assets/eval-single-vehicle/` when a concrete minimal moving example is
  useful.
- Copy `assets/moos_scoped_teardown.sh` into the target project as
  `<project-root>/scripts/moos_scoped_teardown.sh` when the project does not
  already have an equivalent root-scoped helper.
- Run `scripts/static_check_eval_mission.sh <mission-dir>` for a quick
  structural check.
- Run `scripts/live_check_eval_mission.sh <mission-dir> --port_base=<free-base>`
  for bundled-example or high-trust validation when MOOS-IvP runtime tools are
  available.
- Treat live-check teardown failure as a test failure, show the teardown error,
  and preserve the temporary workdir for diagnosis.

## Validation Checklist

- `./launch.sh --just_make --nogui <warp>` succeeds.
- Generated targets contain `pMissionEval`, explicit initialization
  (`pAutoPoke`, `uTimerScript`, or an app-owned producer), and any evaluator
  apps needed for reported columns such as `pMissionHash`.
- If `pMissionHash` is used for `mhash=` evidence, keep it headless-only by
  default; GUI targets should not launch both `pMissionHash` and
  `pMarineViewer` unless the overlapping pMarineViewer hash feature is
  deliberately disabled.
- Generated targets include bridged graded variables if the verdict depends on
  vehicle-local posts.
- `./zlaunch.sh --just_make <warp>` succeeds when `xlaunch.sh` is on `PATH`.
- Headless `./zlaunch.sh --max_time=<secs> <warp>` exits cleanly.
- `results.txt` contains one parseable result line with `grade=`.
- Runtime warnings are investigated during validation; only stable,
  scenario-relevant warning metrics are surfaced in `results.txt`.
- High-trust checks use `scripts/live_check_eval_mission.sh` or equivalent to
  verify result rows, surface warning evidence, and detect leftover listeners on
  scoped ports.
- No mission wrapper uses global `ktm`, `pkill`, or unrelated cleanup.
- Eval wrappers use `<project-root>/scripts/moos_scoped_teardown.sh` as a scoped
  backstop after `xlaunch.sh`; they do not use global `ktm`, `pkill`, or broad
  process discovery.
- GUI runs retain normal operator controls unless the user requested a
  headless-only mission.

Referenced files: 20

View saved version →

---
name: moos-ivp-harness-builder
description: "Build or repair multi-case MOOS-IvP test harnesses around self-evaluating stem missions: case matrices, per-case mission copies, result aggregation, serial and rolling parallel execution, port isolation, scoped teardown, and nspatch variants. Use moos-ivp-eval-mission-builder for stem missions."
---

# MOOS-IvP Harness Builder

## Overview

Use this skill for a harness that runs one or more self-evaluating stem missions
across multiple named cases. The stem mission should own the mission grade. The
harness should own case selection, patching, temp copies, port isolation,
rolling parallel execution, cleanup, and direct publication of per-case result
rows.

For the stem mission itself, use `moos-ivp-eval-mission-builder`. For ordinary
mission construction before evaluation plumbing, use `moos-ivp-mission-builder`.
For post-run `.alog` evidence, use `moos-alog-analysis`.

## Core Rules

- Start from a stem mission that runs headlessly and writes `results.txt` with a
  `grade=` column.
- Prefer placing harness directories at the repository root, alongside
  `missions/`, for example `harnesses/<harness_name>/` paired with
  `missions/<stem_mission>/`. In larger repositories, use optional family
  grouping for both sides, such as
  `harnesses/<family>_harnesses/HNN-<harness_name>/` paired with
  `missions/<family>_missions/<stem_mission>/`. Have the harness refer to stem
  missions with explicit relative paths. Other layouts are acceptable when
  project conventions or packaging require them.
- The stem mission must be a real eval mission: `pMissionEval` writes the
  `grade=` row. Do not accept a stem where `zlaunch.sh` or shell code
  synthesizes `grade=` from target files, patch markers, or harness knowledge.
- Keep case intent documented in the harness README under `Cases` or
  `Current Matrix`.
- Use exact case tokens in documentation and in `zlaunch.sh`.
- `case=` is the harness-owned variation identity. Harnesses must not set,
  derive, require, or interpret `mmod`; any `mmod=` field produced by the
  mission is opaque mission-owned provenance.
- Keep case setup explicit. A shell `case` block mapping case name to patch
  files, fixture files, stem launch arguments, and intent is easier to audit
  than filename inference.
- When multiple cases reuse one stem but need different setup or evaluation
  criteria, express the differences in the case matrix and case-owned patch
  files, fixture files, or stem launch arguments.
- Keep `launch.sh` and stem wrappers human-facing. Put loops, temp copies,
  aggregation, and archives in harness code.
- Prefer mission-owned grades. The harness should normally prepend
  `case=<case_name>` to the mission result row and preserve the mission's
  `grade=pass|fail` as the case verdict.
- For expected-negative cases, make the stem `pMissionEval` pass when the
  expected negative evidence is observed. Do not encode those cases as
  `expected=fail actual=fail` unless the harness is explicitly testing failure
  machinery such as `pMissionEval`, `uMayFinish`, or CLI return semantics.
- Harness code should synthesize its own `grade=fail` rows only for runner
  failures, such as `reason=launch_error`, `reason=missing_result`,
  `reason=prepare_error`, `reason=missing_result_file`, or
  `reason=teardown_error`.
- Do not add a harness-owned `reason=` for ordinary `pMissionEval` failures.
  Preserve the mission evidence columns that explain the failure. A mission may
  report its own compact `reason=`, but the harness should not reinterpret it.
- Avoid new `case_result=success|mismatch|error` result formats for ordinary
  harnesses. Treat them as legacy compatibility or as a special pattern for
  tests whose subject is the failure machinery itself.
- Keep evaluation levels strict: app-level harnesses should grade the app under
  test; moving/integration harnesses may grade arrival, encounter outcome,
  collision state, or other mission outcomes.
- Expose `--case`, `--port_base`, `--keep_workdirs`, `--gui`, `--nogui`, and
  `--max_time` when the harness can support them. New generated harnesses must
  expose `--jobs`, default it to `1`, and run real backgrounded cases when it is
  greater than `1`. Prefer Bash 5.1+ rolling scheduling with
  `wait -p <pidvar> -n`, so the next pending case starts as soon as any active
  case finishes. Batch-barrier waves are a legacy compatibility pattern and do
  not satisfy the new generated harness contract.
- Modern generated harnesses may require Bash 5.1+ for reliable rolling
  scheduling and PID-to-case bookkeeping. Use `#!/usr/bin/env bash`, add an
  early Bash version guard with a clear macOS/Homebrew message, and optionally
  re-exec a known Homebrew/Linuxbrew Bash before failing.
- Treat harness `--max_time` as a run-time ceiling override forwarded to each
  stem eval mission's `zlaunch.sh`; do not use it as harness-side grading
  logic.
- Default generated harnesses to `PORT_BASE=9000`. Use higher fresh bases only
  as explicit run-time overrides for automation or local sessions that may
  collide with ordinary missions in the `9000` range.
- Use headless mode as the default. Keep `--gui` available for an individual
  case when visual inspection is useful.
- For parallel execution, give each live case its own temp mission copy and
  port block. Do not patch or run through a shared stem directory while
  multiple cases are active.
- Create per-case temp mission copies under a harness-owned run root, not a
  generic system temp location. `--keep_workdirs` should preserve one auditable
  run tree beneath the harness directory.
- Use scoped teardown between cases and at harness exit. Prefer
  copying `assets/moos_scoped_teardown.sh` into the generated project as
  `<project-root>/scripts/moos_scoped_teardown.sh`, sourcing it from harness
  launchers, and calling `moos_scoped_teardown_stop_root` on the harness-owned
  run root or case directory. Do not use global `ktm`, `pkill`, or machine-wide
  cleanup as the normal path.
## Workflow

1. Confirm the stem mission passes as a single eval mission.
   - run the eval mission static checker against the stem
   - `launch.sh` accepts and forwards `--shore_mport`, `--veh_mport`,
     `--shore_pshare`, and `--veh_pshare`.
   - launchers use `nsplug -x` so `.moosx` and `.bhvx` sidecars are consumed.
   - generated targets prove the forwarded ports and patches actually landed.
2. Define case tokens, case intent, and the mission-owned evidence each case
   should report.
3. Document the case matrix in `README.md`.
4. Decide whether each case needs patch files, fixture files, stem launch
   arguments, or no setup changes.
5. Build `zlaunch.sh` around:
   - argument parsing
   - case selection and setup mapping
   - optional patch overlay application
   - `run_case`
   - serial and rolling execution
   - result aggregation
   - cleanup traps
6. Add the teardown helper asset to the generated project if there is not
   already an equivalent root-scoped helper.
7. Implement port forwarding from harness to stem mission and verify generated
   targets reflect those ports.
8. Add `--keep_workdirs` for debugging preserved temp copies.
9. Validate one case, `--jobs=1`, then a small rolling run on a fresh
   `--port_base`.

## Reference Use

- Read `references/harness-style.md` for the overall architecture.
- Read `references/case-matrix.md` before writing README case docs.
- Read `references/nspatch-workflow.md` before adding patch overlays.
- Read `references/ports-and-parallelism.md` before implementing `--jobs` or
  `--port_base`.
- Read `references/generated-harness-self-tests.md` before reporting a new or
  heavily changed harness as trustworthy.
- Read `references/validation.md` before reporting a harness as done.
- Read `references/timing-and-benchmarking.md` before tuning `--jobs`, sleeps,
  `--max_time`, or benchmarking rolling runs.
- Read `references/scoped-teardown.md` before writing cleanup logic.
- Read `references/example-harness-zlaunch.md` for a compact runner skeleton.
- Reuse `assets/moos_scoped_teardown.sh` by copying it into generated harness
  projects as `<project-root>/scripts/moos_scoped_teardown.sh` when they do not
  already provide an equivalent root-scoped helper.
- Run `scripts/static_check_harness.sh <harness-dir>` for a structural check.

## Validation Checklist

- Stem mission passes alone with `./zlaunch.sh --max_time=<secs>`.
- Stem mission passes `moos-ivp-eval-mission-builder` static validation; the
  harness static checker alone is not enough.
- Harness README has a `Cases` or `Current Matrix` section with exact case
  tokens and prose intent.
- `./zlaunch.sh --case=<case> --max_time=<secs>` works for at least one nominal
  case and one expected-negative case if the suite has both.
- `./zlaunch.sh --jobs=1 --port_base=<base>` works, and a rolling run with
  `--jobs=2` or higher uses distinct temp directories and distinct port blocks.
  New generated harnesses should start the next pending case whenever an active
  case finishes, not wait for an entire batch barrier.
- Aggregated results include `case=` and the mission's original result columns,
  especially `grade=` and useful evidence fields such as `eval=`,
  `warning_count=`, `expected=`, `observed=`, or case-specific scalars.
- `case=` is the harness row key. Harness case setup should be explicit in the
  case matrix, patch files, fixture files, or stem launch arguments. `form=`,
  `mhash=`, and mission-owned evidence columns may be preserved as provenance.
- Ordinary case success is `grade=pass`. Any row with `grade!=pass` should make
  the harness exit nonzero unless the harness is explicitly testing failure
  machinery.
- Harness-owned failure rows use `case=<case> grade=fail reason=<runner_reason>`
  and preserve launch return codes or setup evidence when available.
- Selected runs produce one normalized result line for every selected case,
  including setup errors and intentional failures.
- A selected run that produces zero case rows is a harness failure and should
  exit nonzero with a clear diagnostic. This catches portability bugs where the
  case loop never actually ran.
- New generated harnesses that implement rolling scheduling should require Bash
  5.1+ and check that requirement near the top of `zlaunch.sh`. For legacy
  portable harnesses that intentionally target macOS system Bash 3.2, avoid
  `mapfile`, `readarray`, associative arrays, `wait -n`, and `wait -p`.
- `--keep_workdirs` preserves enough files to inspect generated targets and
  `results.txt`.
- Preserved workdirs show generated targets using distinct forwarded ports and
  any intended `.moosx` / `.bhvx` sidecars.
- No harness path relies on global `ktm`, `pkill`, or `killall`.
- Harness cleanup uses a root-scoped teardown helper or an equivalent recorded
  PID cleanup path; generated harnesses should not invent broad process cleanup.
- A teardown failure is visible, makes an otherwise successful run fail, and
  preserves the affected run root for inspection.
- Logs do not contain unexpected warnings hidden by case aggregation.

Referenced files: 13

View saved version →

---
name: moos-ivp-installer
description: "Install or validate upstream MOOS-IvP: locate or clone moos-ivp/moos-ivp, follow the platform setup README, create env.sh, and verify the checkout for MOOS-IvP development."
---

# MOOS-IvP Installer

## Overview

Use this skill to get a working local checkout of upstream MOOS-IvP. Keep the
install simple: clone or locate the checkout, follow the upstream setup README,
then add the small environment setup the other MOOS-IvP skills expect.

After this skill succeeds, the machine should be ready for MOOS-IvP extension
repo, app, behavior, or mission work.

## Defaults

- Source repo: `https://github.com/moos-ivp/moos-ivp.git`
- SSH form when requested: `git@github.com:moos-ivp/moos-ivp.git`
- Default install path: `~/moos-ivp`
- Environment file: `<moos-ivp-root>/env.sh`
- Dependencies and build commands: follow the relevant upstream setup README
- Persistent shell profile edits: ask first

## Confirm Before Changes

Before cloning, installing packages, building, creating `env.sh`, or editing a
shell profile:

1. Do non-destructive discovery first: look for an existing checkout, resolve
   the likely install path, and choose the platform setup README.
2. Ask for any missing user choices: install location and whether to add
   persistent shell integration.
3. Summarize the resolved path, clone URL if cloning, branch or tag if
   requested, selected README, and shell-profile choice in one concise
   sentence.
4. Proceed when the user has already given explicit approval, or after they
   confirm the summary. Still ask before package-manager, `sudo`, or shell
   profile edits unless that specific approval was already given.

## Workflow

1. Check whether the user already has a valid checkout.
   - Try an explicit user path first.
   - Then try `MOOS_IVP_ROOT`.
   - Then try common paths such as `~/moos-ivp`, `~/src/moos-ivp`,
     `~/repos/moos-ivp`, and `~/projects/moos-ivp`.
   - Treat a checkout as valid when it has `ivp/src`, `build-moos.sh`,
     `build-ivp.sh`, `scripts/GenMOOSApp_AppCasting`, and
     `scripts/GenBehavior`.
2. If no checkout exists, confirm the target path before cloning.
3. Clone with the confirmed source URL:

   ```bash
   git clone https://github.com/moos-ivp/moos-ivp.git <target-root>
   ```

   If the user requests a branch or tag, include it in the clone or checkout
   plan before building.

4. Choose the relevant setup README from the checkout:
   - macOS: `README-OS-X.txt`
   - GNU/Linux: `README-GNULINUX.txt`
   - Windows: `README-WINDOWS.txt`
5. Read the selected README and follow its dependency and build instructions.
   Ask before running package-manager or sudo commands.
6. Create the checkout-local shell environment file.
   - Write `<moos-ivp-root>/env.sh`.
   - Resolve the absolute checkout path before writing the file.
   - Write expanded absolute paths inside `env.sh`, not `~` or `$HOME`.
   - Make repeated sourcing idempotent so `PATH` does not accumulate duplicate
     entries.
   - Keep the file source-compatible with common Bash and zsh startup files.
   - Only set `MOOS_IVP_ROOT` and `PATH` for the core checkout. Do not set
     `IVP_BEHAVIOR_DIRS` here; extension repos own their behavior library
     paths.
   - Use this shape:

   ```bash
   #!/usr/bin/env bash
   # Source this file to use this MOOS-IvP checkout.
   export MOOS_IVP_ROOT="<absolute-moos-ivp-root>"
   case ":$PATH:" in *":<absolute-moos-ivp-root>/bin:"*) ;; *) PATH="$PATH:<absolute-moos-ivp-root>/bin" ;; esac
   case ":$PATH:" in *":<absolute-moos-ivp-root>/scripts:"*) ;; *) PATH="$PATH:<absolute-moos-ivp-root>/scripts" ;; esac
   export PATH
   ```

7. If the user opted into persistent shell integration, update the selected
   shell profile.
   - Do not require the user to already know shell profile details. If the user
     named a shell, suggest its usual profile, such as `~/.zshrc` for zsh or
     `~/.bashrc` for Bash, and ask for confirmation. If the user did not name a
     shell, ask which profile to update and offer common choices: `~/.zshrc`,
     `~/.bashrc`, or no profile edit.
   - Create the profile file if it does not exist.
   - Preserve user content.
   - Append the managed source block near the end of the profile so it runs
     after earlier `PATH` setup. Do not insert it before later lines that reset
     or export `PATH`.
   - Use a clearly marked block:

   ```bash
   # >>> moos-ivp core >>>
   [ -f "<absolute-moos-ivp-root>/env.sh" ] && . "<absolute-moos-ivp-root>/env.sh"
   # <<< moos-ivp core <<<
   ```

   - If the user opted out, leave the profile unchanged and tell them they can
     run `. <moos-ivp-root>/env.sh` in a shell session.

   Creating `env.sh` is the normal local shell setup for this skill. Adding the
   profile source block is the separate persistent terminal setup that requires
   explicit user approval.

8. Validate:

   ```bash
   <skill-dir>/scripts/validate_moos_ivp_install.sh <moos-ivp-root>
   ```

   Run this after the README build steps and `env.sh` creation. For earlier
   discovery, use the structural checkout checks in step 1. Treat any
   `fail - ...` line as the concise reason to report or fix.

## Failure Handling

- If dependencies are missing, report the README consulted and the missing
  package or tool.
- If build fails, report the first actionable compiler, linker, CMake, or
  missing-library error.
- If profile editing fails, leave the checkout intact and tell the user to
  source `env.sh` manually.

Referenced files: 3

View saved version →

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

Referenced files: 27

View saved version →

---
name: moos-ivp-repo-builder
description: "Create a user-owned MOOS-IvP extension repository from moos-ivp-extend: clone/customize the template, confirm the local MOOS-IvP dependency, configure PATH and IVP_BEHAVIOR_DIRS, initialize independent Git, and validate the baseline build before app, behavior, or mission work."
---

# MOOS-IvP Repo Builder

## Overview

Use this skill to bootstrap a new external MOOS-IvP project modeled on the
course `moos-ivp-extend` tree. The goal is a working user-owned repository that
builds, has its `bin`, `scripts`, and behavior `lib` paths available from the
shell, and is ready for custom apps, behaviors, and missions.

This skill owns the repo shell and environment setup. For code inside the new
repo, delegate follow-on work to:

- `moos-app-builder` for custom MOOS apps
- `ivp-behavior-builder` for custom IvP behaviors
- `moos-ivp-mission-builder` for runnable missions

## Defaults

- Template source: `https://github.com/moos-ivp/moos-ivp-extend.git`
- Git handling: fresh repo. Remove the template `.git/`, then run `git init`.
- Environment file: `<repo>/env.sh`
- Persistent shell integration: ask before editing a shell profile
- Environment additions:
  - add `<repo>/bin` and `<repo>/scripts` to `PATH`
  - add `<repo>/lib` to `IVP_BEHAVIOR_DIRS`
- Keep the example app, behavior, and missions unless the user asks for a
  clean shell.

Use a different template repo or skip the repo-local environment file only when
the user explicitly asks.

## Confirmation Gate

Before cloning or editing files, collect and confirm:

1. New repo name and target parent directory or full target path.
2. Repository author name and optional organization string for customized
   project text. This is not the same as Git commit identity.
3. Whether examples should stay or be removed.
4. Whether to add persistent shell integration by sourcing `<repo>/env.sh` from
   the user's preferred shell profile. If yes, confirm the profile path.

If the user already gave these values and said to proceed, treat that as the
confirmation. Otherwise, stop and ask a concise confirmation question before
cloning.

## Guiding Vague Users

When the user starts with a vague request such as "I want a new MOOS-IvP repo",
guide them with one or two small questions at a time instead of dumping the
whole checklist at once.

Good first move:

1. Try to resolve `MOOS_IVP_ROOT` in the background.
2. Say whether it was found.
3. Ask for the repo name.

Then ask for the target location, project display author, examples/defaults,
and shell integration preference as needed. If the user says "wherever is fine",
suggest a concrete default path and confirm it. Prefer a sibling of the
validated `moos-ivp` checkout, for example `~/my-new-repo` when
`MOOS_IVP_ROOT` is `~/moos-ivp`. Do not default to nesting the new repo inside
an unrelated active workspace. Explain that the project display author is for
README/CMake text, not a Git committer email.

When proposing persistent shell integration, show the concise block that would
be added to the selected profile:

```bash
# >>> moos-ivp repo: <repo-name> >>>
[ -f "<absolute-repo-path>/env.sh" ] && . "<absolute-repo-path>/env.sh"
# <<< moos-ivp repo: <repo-name> <<<
```

Before side effects, summarize the resolved values in one sentence and ask for
explicit confirmation.

## MOOS-IvP Root Resolution

Resolve `MOOS_IVP_ROOT` before cloning. Try, in order:

1. Path explicitly provided by the user.
2. `MOOS_IVP_ROOT` from the shell environment.
3. A sibling or parent `moos-ivp` near the target path or current workspace.
4. Common home locations:
   - `~/moos-ivp`
   - `~/src/moos-ivp`
   - `~/repos/moos-ivp`
   - `~/projects/moos-ivp`
5. A bounded shallow home search for a directory named `moos-ivp`, suppressing
   expected permission noise.

Validate a candidate by confirming:

- `ivp/src` exists
- `build-moos.sh` exists
- `build-ivp.sh` exists
- `scripts/GenMOOSApp_AppCasting` exists and is executable
- `scripts/GenBehavior` exists and is executable

If no valid checkout is found, stop and ask explicitly for the path to the
local `moos-ivp` checkout. Do not clone, edit shell profiles, or create a
placeholder path.

If multiple checkouts are found, prefer the one nearest the target repo. State
which path will be used in the confirmation.

## Workflow

1. Confirm setup values and validated `MOOS_IVP_ROOT`.
2. Create or verify the target parent directory.
3. Refuse to overwrite a non-empty target directory unless the user explicitly
   asks to reuse it.
4. Clone the template into the target path:

   ```bash
   git clone https://github.com/moos-ivp/moos-ivp-extend.git <target-repo>
   ```

5. Detach the template Git metadata and initialize a fresh repo:

   ```bash
   rm -rf .git
   git init
   git branch -M main
   ```

6. Customize repository text and build wiring.
   - Keep one top-level README by default. Prefer `README.md`, migrate any
     useful unique text from legacy `README` if needed, then remove `README`.
     Keep both only if the user explicitly asks.
   - Remove inherited template CI metadata by default, including
     `.github/workflows/build_extend.yml` and `.gitlab-ci.yml`, and remove any
     README badges or links that refer to the upstream template CI.
   - Update README title and obvious references from `moos-ivp-extend` to the
     new repo name in the retained README.
   - Use the repository author name in the top-level CMake `# NAME:` line and
     any newly written project text. Label this to the user as the project
     display author, not Git commit identity. Do not rewrite upstream example
     source file authors unless the user explicitly asks to claim or replace
     example code.
   - Update top-level CMake comments and `PROJECT(...)` only when a clear
     project identifier is available. Use an uppercase, underscore-safe project
     token.
   - If the repo name appears in nested example docs such as
     `missions/alder/README` or `src/lib_behaviors-test/README`, update only
     path references needed for the examples to remain accurate.
   - Scrub obvious visible template names in comments and docs that a user is
     likely to open, including top-level `CMakeLists.txt`, `src/CMakeLists.txt`,
     and mission/example README files. Do not churn source-file history
     comments merely to remove upstream maintainer names.
   - Make the resolved `MOOS_IVP_ROOT` effective for builds. Treat it as a
     setup-time input, not a shell variable that users must keep forever. The
     upstream
     template only searches nearby relative paths, so a repo outside the same
     parent as `moos-ivp` can fail unless the path is wired explicitly.
     Update top-level `CMakeLists.txt` with the resolved absolute path:
     - append `<moos-ivp-root>/build/MOOS/MOOSCore` to `CMAKE_PREFIX_PATH`
       before `find_package(MOOS 10.0)`
     - add `<moos-ivp-root>` to the
       `find_path(MOOSIVP_SOURCE_TREE_BASE ... PATHS ...)` list
     This makes normal future `./build.sh` runs work without requiring
     `MOOS_IVP_ROOT` in `.bashrc`.
   - Do not add repository automation files or remote GitHub setup unless the
     user explicitly asks.
7. If the user requested a clean shell, remove sample source and mission
   directories carefully and keep the build skeleton valid. Otherwise retain
   examples so the baseline build has known artifacts to verify.
8. Create the repo-local shell environment file.
   - Write `<repo>/env.sh`.
   - Resolve the absolute paths for the new repo's `bin`, `scripts`, and
     `lib` directories before writing the file.
   - Make repeated sourcing idempotent so PATH and `IVP_BEHAVIOR_DIRS` do not
     accumulate duplicate entries.
   - Keep the file source-compatible with common Bash and zsh startup files.
   - Use this shape:

     ```bash
     #!/usr/bin/env bash
     # Source this file to use this MOOS-IvP extension repo.
     case ":$PATH:" in *":<absolute-repo-bin>:"*) ;; *) PATH="$PATH:<absolute-repo-bin>" ;; esac
     case ":$PATH:" in *":<absolute-repo-scripts>:"*) ;; *) PATH="$PATH:<absolute-repo-scripts>" ;; esac
     case ":${IVP_BEHAVIOR_DIRS:-}:" in *":<absolute-repo-lib>:"*) ;; *) IVP_BEHAVIOR_DIRS="${IVP_BEHAVIOR_DIRS:+$IVP_BEHAVIOR_DIRS:}<absolute-repo-lib>" ;; esac
     export PATH
     export IVP_BEHAVIOR_DIRS
     ```

9. If the user opted into persistent shell integration, update the selected
   shell profile.
   - Ask for the profile path instead of assuming one. If the user named a
     shell, suggest its usual profile, such as `~/.zshrc` for zsh or
     `~/.bashrc` for Bash, and ask for confirmation. If the user did not name a
     shell, ask which profile to update and offer common choices: `~/.zshrc`,
     `~/.bashrc`, or no profile edit.
   - Create the profile file if it does not exist.
   - Preserve user content.
   - Append the managed source block near the end of the profile so it runs
     after earlier PATH setup. Do not insert it before later lines that reset or
     export PATH.
   - Use a clearly marked block:

     ```bash
     # >>> moos-ivp repo: <repo-name> >>>
     [ -f "<absolute-repo-path>/env.sh" ] && . "<absolute-repo-path>/env.sh"
     # <<< moos-ivp repo: <repo-name> <<<
     ```

   - If the user opted out, leave the profile unchanged and tell them they can
     run `. <repo>/env.sh` in a shell session.
10. Validate the baseline.
   - Run `./build.sh` from a normal tool-capable shell, not from a shell whose
     profile has hidden basic build tools. The repo CMake should already have
     the resolved `moos-ivp` path wired in, so build validation should not
     depend on `MOOS_IVP_ROOT` being exported.
   - If examples were retained, confirm:
     - `bin/pXRelayTest` exists and is executable
     - `lib/libBHV_SimpleWaypoint.dylib` on macOS or
       `lib/libBHV_SimpleWaypoint.so` on Linux exists
   - Validate `<repo>/env.sh` separately by sourcing it in a shell and
     confirming the new absolute `bin`, `scripts`, and `lib` paths appear in
     `PATH` / `IVP_BEHAVIOR_DIRS`.
   - If a persistent profile source block was added, validate that applying the
     selected profile reaches the same environment.
   - If sourcing the user's profile hides build tools such as `mkdir`, `make`,
     or `cmake`, report that as a profile/tooling issue, not as a repo build
     failure.
   - Run `which pXRelayTest` or `command -v pXRelayTest` only after applying
     `<repo>/env.sh` or the selected profile.
11. Initialize the first commit when the user asked for Git setup or when they
    asked for a ready fresh repo, but only if Git identity is already
    configured or the user supplied both a commit author name and email.
    Repository author text collected earlier is for project files, not enough
    to invent a Git committer email:

    ```bash
    git add .
    git commit -m "chore: initialize MOOS-IvP extension repo"
    ```

    Skip the commit if Git user identity is missing and report the exact
    blocker instead of inventing identity values. Do not ask for Git email
    during the initial setup unless the user specifically wants the first
    commit completed in the same turn.
12. If no remote was attached, mention the natural next step: create an empty
    GitHub repository under the user's account or organization, add it as
    `origin`, and push `main`. Do not perform this unless the user explicitly
    asks. Remind the user that if their GitHub credentials are connected, the
    AI agent can create the GitHub repo, add the remote, and push for them.

## Environment Editing Rules

- Expand `~` to an absolute path before writing shell profile blocks.
- Quote paths in shell exports.
- Do not edit any shell profile unless the user opts into persistent shell
  integration and confirms the profile path.
- Do not remove an existing matching block for another repo.
- If replacing a block for the same repo path, replace only the managed block
  with the same marker.
- Keep profile edits idempotent: running the skill twice should not append
  duplicate path entries.
- Keep the repo-local `env.sh` as the source of the PATH and
  `IVP_BEHAVIOR_DIRS` details; shell profiles should only source that file.

## Validation Checklist

- Target repo was cloned from the intended template.
- Template `.git/` was removed before `git init`.
- `git remote -v` is empty unless the user asked to attach a remote.
- The resolved local `moos-ivp` checkout was validated.
- The new repo's build can find the resolved `moos-ivp` checkout, even when the
  repo is not a sibling of `moos-ivp`.
- `./build.sh` succeeds, or the exact compiler/configuration blocker is
  reported.
- `PATH` and `IVP_BEHAVIOR_DIRS` setup was written to `<repo>/env.sh`.
- If requested, the selected shell profile sources `<repo>/env.sh`.
- Generated `bin/` and `lib/` artifacts are not treated as source changes.
- Final message names the new repo path, env file path, profile path if
  updated, validation result, and the next appropriate skills.

## Failure Handling

- Missing `MOOS_IVP_ROOT`: stop and ask for the local checkout path.
- Non-empty target path: stop unless the user explicitly asked to reuse it.
- Clone failure: report the template URL and Git error.
- Build failure: report the first actionable CMake or compiler error.
- Shell profile write failure: leave the repo intact and tell the user to
  source `<repo>/env.sh` manually.
- Git commit failure due to identity: leave files initialized and staged state
  as-is; tell the user to configure Git identity.

Referenced files: 2

View saved version →

---
name: moos-map-builder
description: "Create and verify MOOS-IvP TIFF background maps with the moos-map application. Use when a user wants to select a map region visually in the local GUI; build directly from two geographic corners through the CLI; choose imagery, zoom, mission origin, or output location; recreate a map from existing bounds; or inspect and verify generated .tif, .info, and .moos files."
---

# MOOS Map Builder

## Principles

Use the public `moos-map` application as the single implementation. Do not
reimplement its map-building or verification logic inside this skill.

Address the user directly. Ask plainly for any needed choice, confirmation, or missing information without referring to this skill or its workflow.

## Route First

If the user already requested the GUI or CLI, use that route without asking
again. Otherwise ask one concise question and wait for the answer:

> Would you like to select the region visually in the GUI, or build it directly through the CLI?

- Choose the GUI for manual map browsing and visual corner selection.
- Choose the CLI for known coordinates, repeatable builds, or agent-driven
  automation.

Make this routing decision before searching the workspace, inspecting existing
map code, or looking for prior map files.

## Check the Application

Before either route, run:

```bash
command -v moos-map
moos-map --version
```

Use only the executable returned by `command -v moos-map`; do not substitute
another mapping application or activate a repository `.venv`. If it is
unavailable, ask before installing it with:

```bash
pipx install moos-map
```

If the installed command lacks an option used below, inspect
`moos-map <command> -h` before suggesting `pipx upgrade moos-map`. Ask before
upgrading.

## GUI Route

Launch:

```bash
moos-map ui
```

Keep the server process alive while the user works and report its URL. Once the
user finishes the build, ask for the TIFF path they chose and verify it with
`moos-map verify /absolute/path/to/MAP_NAME.tif --json`. Do not claim that a map
was created merely because the UI launched.

If the default port is occupied, choose a free one with `--port` and report the
exact resulting URL.

## CLI Route

### Resolve only essential inputs

- **Corners:** require two diagonally opposite WGS84 points as
  `latitude longitude` pairs. Either corner order is accepted.
- **Name:** obtain or derive a short filesystem-safe map name.
- **Origin:** add `--origin LAT_ORIGIN LON_ORIGIN` only when the user explicitly
  requests those origin coordinates. Otherwise let `moos-map` use the map
  center.
- **Optional choices:** retain Esri World Imagery, zoom 17,
  `~/moos-maps`, the `.moos` snippet, cached tiles, and output replacement as
  defaults unless the user requests otherwise.

If the user supplies only a city or place name, do not invent a rectangle or
scale. Offer the visual GUI route, or ask for the two corners or desired area.

When an existing `.info` file defines the requested map, reuse its north, south,
east, and west bounds unless the user asks to change them. Reuse its datum only
when the user explicitly asks to preserve that origin.

### Plan, confirm, and build

Run `plan` with the same corners, origin, source, zoom, and resource-limit
options intended for the build:

```bash
moos-map plan --corners LAT1 LON1 LAT2 LON2
```

Tell the user the estimated TIFF size and dimensions, then ask for confirmation
before building. After confirmation, run:

```bash
moos-map build \
  --corners LAT1 LON1 LAT2 LON2 \
  --name MAP_NAME \
  --json
```

Use `moos-map sources` only when the user wants to compare providers. Add
custom `--origin`, `--source`, `--zoom`, or `--output-dir` only when requested.
Consult `moos-map build -h` for other options rather than inventing arguments.

Preserve these defaults unless the user says otherwise:

- include the `.moos` snippet;
- replace an existing same-named bundle safely;
- reuse cached source tiles.

The build JSON includes the plan, output paths, and verification report. Treat
the CLI build as complete only when it succeeds and `verification.ok` is true;
a separate `verify` call is unnecessary for that newly built bundle.

## Verify Existing or GUI-Built Maps

For a GUI-built map, an existing map, or a direct verification request, run:

```bash
moos-map verify /absolute/path/to/MAP_NAME.tif --json
```

Treat the map as verified only when `ok` is true.

## Report

Read the CLI build's `plan` and `verification` objects, or the standalone
verification JSON, and report:

- map directory and generated `.tif`, `.info`, and optional `.moos` paths;
- TIFF dimensions and actual file size;
- source, zoom, bounds, and origin when available;
- verification warnings.

If mentioning a display-alignment estimate (you don't have to), identify it as a theoretical
display/model estimate rather than a displacement of mission navigation or
local XY.

Each default build is a bundle:

```text
<output-directory>/<map-name>/
├── <map-name>.tif
├── <map-name>.info
└── <map-name>.moos
```

Do not edit or re-encode the TIFF after verification. If the user asks to
integrate the result into a mission, use the generated `.moos` snippet and
ensure pMarineViewer can find the exact map directory; do not silently modify
mission files when the request was only to create a map.

## Failure Handling

- Report the first actionable `moos-map` error verbatim, then explain the
  corrective input or option.
- Do not silently change invalid coordinates, origin, output directory,
  source, or zoom.

Referenced files: 2