How OpenAI Plugins Define Session-Start and Lifecycle Hooks: A Complete Technical Guide

OpenAI Plugins enforce a mandatory session-start gate defined in runtime-context-header.md that initializes the workspace exactly once per conversation through a four-step validation sequence, followed by compact status updates for the remainder of the session.

The openai/plugins repository implements a strict lifecycle management architecture for AI-driven workflows. Every plugin skill must execute the session-start gate before performing any operations, ensuring consistent runtime validation and user confirmation. This pattern separates heavyweight initialization logic from routine execution through defined presentation formats and file-based state persistence.

The Mandatory Session-Start Gate

The session-start gate functions as the primary lifecycle hook that every plugin-driven workflow must execute. Defined in plugins/nvidia/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md (lines 59-71), this gate establishes a consistent, repeatable start-up sequence that runs exactly once per conversational session.

The gate performs four critical steps:

1. Determine the output_path – Read the destination from the user request or prompt for it explicitly.
2. Validate <output_path>/setup-preflight.json – Check for the pre-flight configuration file. If missing or unreadable, invoke the setup-usd-performance-tuning skill to generate the JSON; otherwise, parse the existing file and continue.
3. Print Format A – Display a multi-line runtime context block showing exact Kit, Scene Optimizer, and Asset Validator versions plus installation paths.
4. Prompt for confirmation – Ask the user to confirm the runtime choice, change Kit installations, switch to standalone mode, or re-run the probe.

Downstream skills inherit the pre-flight data from this initial execution and never re-run the gate, instead using a compact "Format B" one-liner for routine status updates throughout the session.

Presentation Formats and Lifecycle Phases

The plugin lifecycle implements distinct presentation formats to balance information density against execution phase requirements.

Format A: Full Runtime Context

Format A provides the complete runtime environment specification during initialization. As defined in runtime-context-header.md (lines 90-98), this multi-line block appears exactly once at session start or when the user switches runtime environments:

─── Runtime context ───────────────────────────────────────────────────────
Kit application:    USD Composer 110.1.0
  path:             D:\build\chk\usd_composer-fat\110.1.0\kit
  build:            110.1.0+main…
Scene Optimizer:    omni.scene.optimizer.core 110.0.4
Asset Validator:    omniverse-asset-validator 1.x.y via kit-extension
──────────────────────────────────────────────────────────────────────────

Format B: Compact Status Line

After successful initialization, subsequent operations use Format B for concise context. Defined in runtime-context-header.md (lines 66-73), this one-line format prevents UI clutter during mid-session tasks:

[Kit: USD Composer 110.1.0  |  SO: 110.0.4  |  AV: 1.x.y]
profile-stage: starting BASELINE capture in quick mode...

Lifecycle Phase Mapping

The session-start gate coordinates four distinct lifecycle phases:

• Start Phase: The Session-Start Gate (mandatory) initializes the workspace, validates runtime compatibility, and surfaces full context to the user via Format A.
• Mid-Session Phase: Format B provides compact runtime context for subsequent steps without re-prompting the user.
• Runtime Change Phase: The system re-prints Format A when the user switches Kit installations or environments, ensuring visibility into configuration changes.
• Completion Phase: The Final Report (e.g., optimization-report) echoes the same runtime fields for auditability and traceability.

Implementation in Skill Definitions

Individual skills reference the mandatory gate through their SKILL.md documentation files. In plugins/nvidia/skills/omniverse-usd-performance-tuning/SKILL.md (lines 68-70), the skill explicitly declares:

## Runtime context — session-start gate (mandatory)

**Before any other tuning output**, follow the mandatory session‑start gate …

The setup-usd-performance-tuning skill, referenced in plugins/nvidia/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md, contains the logic that creates the setup-preflight.json file consumed by the gate. This separation of concerns ensures that initialization logic remains centralized while individual skills declare compliance with the lifecycle contract.

Key Source Files and Responsibilities

The session-start and lifecycle hook definitions span several critical files in the repository:

• plugins/nvidia/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md – Defines the session-start gate, presentation formats (A and B), and anti-patterns for runtime context display.

• plugins/nvidia/skills/omniverse-usd-performance-tuning/SKILL.md – References the mandatory gate and specifies when it fires within the skill execution flow.

• plugins/nvidia/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md – Contains the generation logic for setup-preflight.json used by the gate to validate workspace state.

• plugins/superpowers/README.md – Example plugin demonstrating session-start hook integration in plugin descriptions.

Summary

• The session-start gate in runtime-context-header.md acts as a mandatory lifecycle hook that runs exactly once per conversational session to initialize workspace state and validate runtime environments.
• Format A (full multi-line block) displays comprehensive runtime details during initialization and runtime changes, while Format B (compact one-liner) provides status updates during mid-session operations.
• The gate checks for <output_path>/setup-preflight.json and automatically invokes the setup-usd-performance-tuning skill to generate missing configuration files.
• Individual skills declare compliance with the lifecycle through their SKILL.md files, ensuring consistent execution patterns across the plugin ecosystem.

Frequently Asked Questions

What triggers the session-start gate to execute?

The session-start gate triggers at the beginning of every new conversational session when a plugin skill first runs, as specified in runtime-context-header.md. It executes before any other tuning or processing output appears, ensuring the workspace is validated and the user confirms the runtime environment. Once confirmed, the gate stores state in setup-preflight.json and subsequent operations skip directly to Format B status updates.

What is the difference between Format A and Format B lifecycle hooks?

Format A serves as the heavyweight initialization hook displaying full Kit, Scene Optimizer, and Asset Validator paths, versions, and build details in a multi-line block. Format B functions as the lightweight maintenance hook, presenting the same runtime information condensed into a single bracketed line like [Kit: USD Composer 110.1.0 | SO: 110.0.4 | AV: 1.x.y]. The system transitions from Format A to Format B after initial user confirmation to reduce UI noise during extended sessions.

How does a plugin handle missing pre-flight configuration files?

When the gate detects a missing or unreadable <output_path>/setup-preflight.json file, it automatically invokes the setup-usd-performance-tuning skill to generate the required pre-flight JSON according to the logic in setup-usd-performance-tuning/README.md. This ensures that every session begins with valid workspace metadata regardless of prior initialization state, maintaining the integrity of downstream lifecycle operations.

Can downstream skills bypass the session-start gate after initialization?

No downstream skills can bypass the gate's requirements, but they inherit the pre-flight data from the initial execution and do not re-run the full gate sequence. Instead, they reference the established output_path and setup-preflight.json created during the first execution, displaying only Format B updates for subsequent operations. If a user requests a runtime environment change, the system re-activates Format A to capture the new configuration details.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}