Holohub App Lifecycle

HoloHub application lifecycle

Purpose

Take a non-failing application request from checkout selection to reviewable, finite evidence through the public ./holohub workflow.

Inputs

Require the task, checkout or starting workspace, and finite acceptance check. Take remaining values from the request or selected checkout; do not guess data rights or sensitive-data constraints. Benchmark details are optional unless performance work is requested.

• a non-failing application task and its deliverable: application, operator-plus-demo, tutorial, or fix;
• the starting workspace or an explicit HoloHub checkout;
• language, mode, platform, input, and output requirements;
• input origin and redistribution terms, including any private or sensitive data constraints;
• a finite success condition and the evidence needed to support it.

Route a concrete failing or wrong ./holohub command to holohub-debug-build-run, reusable Module or DEB/WHEEL work to holohub-module-lifecycle, and first-time SDK host installation to holoscan-setup. If the matching skill is unavailable, preserve the handoff context and name the skill to install instead of improvising its workflow.

Prerequisites

• Always read the CLI contract.
• Read the application workflow for workspace resolution, input handling, scaffolding, metadata, implementation, tests, evidence, and review.
• Read flow benchmarking only when performance work is requested.

The selected checkout's AGENTS.md, local ./holohub help, schemas, and contribution guide 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 such as env-check --json and stop only when a failed capability is required by the selected project's documented needs or the requested proof.

1. Resolve one safe checkout. Preserve the starting workspace. Reuse one validated checkout at its current revision. An auto-discovered checkout must be clean. Proceed in a dirty checkout only when the user explicitly selected it and comparing the requested paths with the existing working-tree changes proves they do not overlap. If scope is uncertain, preserve the checkout and request authorization for the documented project-local clone fallback. Never overwrite a workspace or coerce an existing checkout to the contract's evidence snapshot.
2. Preserve and orient. Record both roots, provenance, full HEAD, and concise status. Create a task branch before editing a new app only in a clean checkout. In an explicitly selected dirty checkout, switch branches only with user authorization; otherwise request authorization for the fallback. Run wrapper commands from the checkout root and confirm syntax with local help.
3. Define the proof. Confirm the contribution type, licensed inputs, input integrity/schema when applicable, and a verdict bounded by an explicit frame/message count, timeout, or artifact completion. Include visual evidence when relevant and state claims the evidence cannot support.
4. Select strong local examples. Choose two or three relevant applications for graph/domain, language/build/test, and data/Holoviz/benchmark patterns. Record what will be reused; do not copy an application wholesale.
5. Scaffold only when needed. For a new app, preview template setup, inspect its host dependency installation, and obtain explicit user authorization before the real setup. Only after setup succeeds, preview and run a non-interactive, language-explicit create. Treat preview as potentially mutating. Obtain any repository-required approval for parent CMake registration; if denied or setup fails, stop before creation. Do not replace an existing app.
6. Implement the smallest complete path. Validate metadata, keep automated modes finite, register deterministic tests, exclude generated/data/model artifacts from Git, and emit an observable verdict or artifact.
7. Preview, act, and verify. Keep project, mode, language, inputs, and other effect-bearing options identical between each preview and real build, run, and test, while treating the preview itself as potentially mutating. Use the container-first path. Require process success plus the finite verdict, intended tests, and visual or recording inspection when applicable.
8. Shorten only a proved loop. Reuse an unchanged image with --no-docker-build only after one matching build/run. Use --no-local-build only when current artifacts or mounted-source execution are proved sufficient. Rebuild after image or setup changes.
9. Finish reviewably. Benchmark only after correctness, then restore normal source/build state. Run focused and wrapper tests, git diff --check, and final status. In an explicitly selected 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 rather than rewriting unrelated work. Do not commit or push unless requested.