HoloHub Holoscan Module lifecycle

Purpose

Take a reusable Holoscan Module from layout and API contract through producer, consumer, and clean artifact-install proof.

Inputs

Require the API contract, checkout, layout, identities, SDK floor, license, maintainer, package formats, and acceptance checks from the request or an authoritative repository source. If consequential release metadata remains unknown, stop before scaffolding or packaging rather than guessing.

• a reusable producer/consumer API contract rather than an ordinary app;
• the user-provided HoloHub checkout;
• external self-contained repository or in-tree descriptor layout;
• language, module/operator/package identities, minimum SDK version, license,

maintainer details, and requested package formats;

• finite producer, consumer, and artifact acceptance checks.

Route an ordinary app to holohub-app-lifecycle and a concrete failing or wrong ./holohub command to holohub-debug-build-run. If the matching skill is unavailable, preserve the handoff context and name the skill to install instead of broadening this workflow.

Prerequisites

• Always read the [CLI contract](references/holohub-cli-contract.md).
• Read [module development](references/module-development.md) for layout,

naming, scaffold, metadata, implementation, build, and test scope.

• Read [consumer and packaging](references/module-consumer-packaging.md) when a

consuming app, editable install, or binary artifact is in scope.

• Use HoloHub's current create-a-module

and use-a-module tutorials as producer and consumer walkthroughs, then recheck version-sensitive commands against the selected checkout and CLI contract.

The selected checkout's AGENTS.md, local help, module guidance, schemas, templates, tutorials, and nearby examples are the live technical authority where they do not conflict with user, system, or safety constraints.

Instructions

At any step, a failing effect-bearing wrapper command ends this happy path; follow Troubleshooting with its exact context. Parse read-only diagnostic results and stop only when a failed capability is required by the module, consumer, packaging environment, or requested proof.

1. Preserve and orient. Record full HEAD, concise status, local wrapper

version/environment, and discovery output. Preserve the checkout revision and unrelated work.

1. Choose the layout. Use an external holoscan-<name> repository for

independent release or an in-tree descriptor under modules/ for code maintained with HoloHub.

1. Fix identities before files. Keep display name, snake_case

module/namespace, holoscan-<kebab-case> repository/package, and snakecaseop operator slug consistent.

1. Scaffold external modules safely. Preview template setup, inspect its

host dependency installation, and obtain explicit user authorization before the real setup. Only after setup succeeds, preview and run the fully specified non-interactive create command, treating preview as potentially mutating. Require an existing parent, inspect the generated staged Git repository, and never push it without a request.

1. Implement the smallest public contract. Validate metadata, expose one

useful operator/API, add deterministic tests, and add a finite demo that consumes the same public surface as another project. Keep demo policy out of the reusable operator.

1. Build and test honestly. Preview and run container-first module and demo

commands. In HoloHub, test every declared operator and demo because test <module> is not module-scoped. In a generated repository, combine its repository-wide test with focused pytest or CTest targets.

1. Prove a real consumer. Declare the exact metadata dependency and an

immutable full SHA for external source. Use a mounted source override for fast iteration or an editable install only in the environment reported by env-info --json. Record the hook and remove it even if a later step fails; if removal fails, report the exact environment and hook state.

1. Package only after behavior proof. Preview and build requested DEB/WHEEL

artifacts, inspect identity/metadata/dependencies/payload, and install each format in a clean artifact-only consumer with an import/link and finite smoke check.

1. Validate and hand off. Rerun producer and clean-consumer checks,

git diff --check, and final status. In a dirty checkout, restrict auto-fixing lint to task paths; before a requested commit, validate the exact candidate change with the repository-required full lint in a clean disposable checkout. Confirm no generated artifacts or editable hooks are staged. Do not commit, push, upload, publish, or release unless requested.

Troubleshooting

If a wrapper command fails, stop the happy path and hand off its exact command, revision, dirty state, inputs, and observed result to holohub-debug-build-run.

Examples

• Scaffold and package a reusable operator with clean-consumer proof: use this

skill.

• Package an ordinary app or diagnose a failing build: route out of this skill.

Limitations

• Preserve unrelated work. Do not reset, clean, remove unrelated files, change

host configuration, broaden privileges, commit, push, upload, publish, or release without authorization.

• Never run sudo ./holohub; obtain approval for host packages, host-local

execution, root containers, devices/capabilities, or permission changes.

• Keep build, data, install, package output, and editable hooks out of commits.
• Protect credentials, proprietary source, patient data, private media, and

identifying metadata.

• Claim support, reproducibility, installability, performance, or safety only

for the producer, artifacts, and clean-consumer evidence actually collected.

Output

Return layout and identities, public API/demo, metadata and registrations, preview and real command results, honest test scope, consumer proof, artifact identity/contents/install results, licensing and publication limits, and final worktree state.

For a planning-only request, return the proposed order, authoritative metadata sources, approval boundaries, and proof requirements without claiming results.