/holohub-module-lifecycle

name: holohub-module-lifecycle
description: "Use for reusable Holoscan Module work with ./holohub: scaffold, tests, editable install, DEB/WHEEL packaging, and clean-consumer proof."
license: Apache-2.0
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  compatibility: "holoscan-cli>=4.5.0"
  github-url: "https://github.com/nvidia-holoscan/holohub"
  tags:
    - holoscan
    - holohub
    - modules

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](https://github.com/nvidia-holoscan/holohub/tree/main/tutorials/holoscan-modules/create-a-module)

and [use-a-module](https://github.com/nvidia-holoscan/holohub/tree/main/tutorials/holoscan-modules/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. 2. **Choose the layout.** Use an external `holoscan-<name>` repository for independent release or an in-tree descriptor under `modules/` for code maintained with HoloHub. 3. **Fix identities before files.** Keep display name, `snake_case` module/namespace, `holoscan-<kebab-case>` repository/package, and `snake_case_op` operator slug consistent. 4. **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. 5. **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. 6. **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. 7. **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. 8. **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. 9. **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