/holohub-app-lifecycle

name: holohub-app-lifecycle
description: "Use for non-failing HoloHub app work with ./holohub: scaffold, build, run, test, visual evidence, lint, and flow benchmarking."
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
    - application-development

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](references/holohub-cli-contract.md).
• Read the [application workflow](references/application-workflow.md) for

workspace resolution, input handling, scaffolding, metadata, implementation, tests, evidence, and review.

• Read [flow benchmarking](references/flow-benchmarking.md) 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.

Troubleshooting

If a wrapper command begins failing, stop the happy path and hand off its exact command, revision, dirty state, inputs, and observed result to `hol