Installing the STIG Codex plugin
The stig Codex plugin provides three skills, selected by the requested engineering result.
Skill boundaries
Skill | Owns | Use another skill for |
|---|---|---|
| Model-only elements; authored Context, Requirements, Design, Analysis, and Tests; typed links and Kotlin/Markdown specification review | Native source-analysis setup or evidence review; project installation and ordinary publication |
| New source-backed activities; native targets, software under analysis, harnesses, transforms, analysis execution, confirmation review, and sink agreement through the activity report | Authoring separate CREATE work products; installing STIG or publishing an ordinary report |
| Installation, new consumer projects, Gradle layout and general configuration, task selection, report generation and publication, implementation metrics | Engineering specification content; native analysis configuration, semantics, and evidence alignment |
The responsible skill keeps its supporting steps. For example, specification can run stigCheckModel and generate a report to validate a model change; source-analysis can run stigGenerateHtml to check sink evidence. Sharing a Gradle task or a reference page does not give two skills ownership of the same requested outcome. A request to generate an ordinary report belongs to project. A request spanning distinct outcomes can use more than one skill, preserving the user's decisions and authorization.
How Codex selects a skill
Codex initially receives each available skill's name and description, and reads its SKILL.md when the task calls for it. It reads supporting references as needed. These descriptions therefore carry the selection boundaries; the full instructions refine the workflow after selection. See the official skill documentation.
A skill is instructions, not an independent agent that knows or executes the other skills. The Codex agent can see their advertised capabilities. A link to another skill is guidance to select and read it when needed; it does not automatically include or inherit that skill's instructions. The plugin packages and exposes the skills but does not supply a separate decision-making router.
STIG keeps each workflow in one skill and shares its canonical manual and agent references. Packaging copies these references into each skill so they are locally available; authors maintain them once. The old stig and check-analysis skill names are replaced by the three names above. Refresh the plugin and use the new completion entries; regenerate archived handoffs that name an obsolete skill with the matching STIG version.
Install or refresh
The plugin is a companion to the STIG Gradle plugin. Normal use does not require the STIG source checkout to be a sibling of the consumer project. All three skills are installed and versioned together.
From the root of any consumer project that applies the STIG Gradle plugin, run:
Gradle downloads a pinned native Codex distribution on first use, verifies its SHA-256, and reuses it under GRADLE_USER_HOME/caches/stig/codex (normally ~/.gradle/caches/stig/codex). This needs no administrator rights, npm, or Node. The operating system must provide tar. The full distribution includes Codex's companion binaries. IDE-only users and users without Codex on PATH use the same installation workflow. The task prints the managed executable's absolute path, which can also be used to launch the terminal CLI.
The executable cache is independent of the Codex home, which contains configuration, authentication, and plugins. The home is selected by --codex-home, then CODEX_HOME, then ~/.codex. The task passes this home to every Codex command. An IDE can use its own Codex binary and still discover the installed plugin when it uses the same home; STIG does not inspect or change JetBrains runtime caches. IDE-supplied session credentials are not necessarily available to the standalone CLI.
By default, after verifying the installed files, the task checks login and makes one small model request: 1+1 must return exactly 2. The request runs in a temporary directory with a read-only sandbox, uses the user's configured model/provider, and does not persist a conversation. It consumes a small amount of model usage. This proves model access for the selected CLI and home; it does not prove that an already running IDE has loaded the skills. Use the skill verification prompt below in that IDE to confirm discovery.
When login is missing, an interactive Gradle invocation offers device-code login. Follow the displayed link and one-time code; no password or API key is passed through Gradle task options. Automated runs never prompt by default. See the official Codex authentication guide for browser login, device-login availability, credential storage, and corporate certificates.
--login=NEVER still performs the model check and fails on invalid credentials or unavailable model access. --no-smoke-test and --offline report SKIPPED, rather than claiming that login or model access was verified. An offline cache miss fails with instructions to download the tool online first. Model requests time out after 120 seconds (change with --smoke-test-timeout=SECONDS); an explicitly started device login has a ten-minute limit. If model verification fails, the plugin files remain installed and verified, and the task reports a failure with the next steps. A rerun safely refreshes the installation.
STIG contributors can install directly from the STIG source-checkout root:
This shortcut builds the current STIG Gradle plugin and stages a small installer project with that plugin and its runtime dependencies. It runs the same stigInstallSkill task used by consumers. The launcher sources live under stig-codex-plugin/local-install; the staged project lives under stig-codex-plugin/build/local-install. The original composite launcher also remains available as ./gradlew -p stig-codex-plugin/local-install stigInstallSkill. Use that direct launcher when passing installer options such as --no-smoke-test or --login=DEVICE.
The root shortcut uses a nested Gradle build and does not reuse the outer configuration cache. Normal builds retain their existing cache settings, and installation runs only when explicitly requested.
The consumer's explicit, root-only stigInstallSkill task installs all skills shipped with the exact STIG Gradle-plugin artifact resolved by the build. It works both with a sibling STIG source checkout and with a released plugin from Maven Central. The task:
atomically replaces its managed
exidamarketplace at~/.stig/codex-marketplace;registers that local marketplace when it is not registered yet;
removes an already installed
stig@exidacopy and its Codex cache, then installs the bundled version;verifies the installed file inventory and contents against the packaged guidance;
checks login and the model response, unless explicitly skipped or offline; and
prints STIG Codex plugin installation finished successfully, the installed directory, version, content SHA-256, each
SKILL.mdSHA-256, and a copyable verification prompt.
The task is idempotent. It refuses to replace an existing exida registration from another location or an unmarked directory at the managed path. It never runs from build, report generation, release publication, or CI unless a user explicitly invokes stigInstallSkill or the source-root installSkill shortcut; it also does not run git pull or select another STIG version.
Editing stig-codex-plugin changes the bundle used by the next local STIG build, but it does not update the plugin already installed in Codex. Run ./gradlew installSkill from the STIG source root or ./gradlew stigInstallSkill from the consumer after an intended plugin change.
The bundled Codex plugin manifest is generated with the exact Axion-derived STIG version that produced the Gradle plugin: for example, 2.0.0 at a release tag or 2.0.1-SNAPSHOT during development. The source manifest template does not carry a separately maintained version.
Codex native checksums live in gradle/codex-toolchain.properties, are packaged with the Gradle plugin, and are updated through scripts/update.sh. They do not change just because STIG is released. Consumer stigUpdate receives the pins shipped by the selected STIG artifact. Maven dependency verification remains in its existing workflow; the installer never refreshes accepted checksums. The STIG guidance fingerprint is separately computed from the final packaged content, including the release-version plugin manifest, so a release can change that fingerprint even when the skill text is unchanged.
Use immediately and verify an update
You can use the installed skills immediately in the current conversation. An IDEA restart or a new Codex thread is not normally required. Codex detects skill changes automatically, as described in the official skill documentation. Invoke the skill again and ask Codex to read its installed instructions afresh. Restart Codex, or IDEA when it hosts Codex, only if an updated skill does not appear.
A development version such as 2.1.4-SNAPSHOT can identify several different builds. Use the installer's Plugin content SHA-256 to identify the actual guidance. It covers all three skills, their bundled manual, generated references, shared agent guidance, source references, and plugin metadata. A SKILL.md hash alone cannot detect an update confined to one of its reference documents.
The installer creates .codex-plugin/content.sha256 in the plugin. This UTF-8 checksum manifest contains each payload file's SHA-256 and its path relative to the plugin root, sorted by path, with LF line endings. The manifest excludes itself; Plugin content SHA-256 is the SHA-256 of that manifest. Identical files and paths produce the same fingerprint, regardless of installation location or file timestamps. The task checks both the installed payload and the installed manifest before reporting success; a stale, missing, or unexpected installed file fails installation verification.
Paste the Suggested prompt printed by the completed task. It already includes the expected content SHA-256:
You can substitute $stig:source-analysis or $stig:specification to inspect that skill's installed instructions; the plugin content fingerprint still covers all three. Comparing the printed fingerprint with the installed manifest and checking its files verifies the installed content. Recalling a previous answer or checking only the version does not establish that the update is in use.
For a terminal check, run these commands from the installed plugin directory printed by the task, then compare the first result with the task's Plugin content SHA-256. These commands check the manifest and its listed files; the verification prompt can also check for unlisted files:
Bundled guidance
The bundle contains the public workflow Markdown from this manual, generated Gradle-task, metamodel, and model-rule references, and shared agent guidance. It also includes exact Kotlin rule/model sources and their navigation helpers under each skill's references/source/stig-core/src/main/kotlin/ for inspecting a predicate or fix without a sibling checkout. The generated catalog identifies executable checks and semantic contracts for human or AI judgment. The specification skill uses those contracts for Kotlin and Markdown specification review.
The HTML manual and all three skills use the same authored workflows. Packaging places a copy of the references in each skill; authors maintain each source once. A skill loads only the topics needed for the request. When a sibling STIG checkout supplies the Gradle plugin through a composite build, that local build creates and embeds the bundle before this task executes.
All three skills work in the consumer project without copying plugin files into that project.
Invoke a skill as $stig:specification, $stig:source-analysis, or $stig:project. The first part is the plugin identifier; the second is the skill's declared name. A plugin is an installable, versioned bundle that can contain several skills. Its namespace distinguishes those skills from equally named skills in other plugins. Use the boundaries above for both explicit and automatic selection; do not switch skills at individual pipeline stages.
Use the exact reference selected by Codex completion. Standalone skills have no plugin namespace and therefore appear as $<skill>; providing STIG that way would require changing its installation format. Some IDE clients render a selected skill as a highlighted mention; that client-side presentation does not change the reference that Codex resolves.
Ask $stig:source-analysis
To verify the current source-analysis configuration without editing it, paste:
The plugin metadata identifies Piotr Serwa as author and developer. STIG is licensed under MPL-2.0. Copyright (C) 2026 SAFETYGENCE sp. z o.o.
The skills use the Gradle tasks and structured evidence exposed by the consumer's installed STIG version. A sibling STIG checkout is optional development context and follows the normal composite-build override rules. After changing or upgrading that resolved version, install again from the appropriate root and use the printed verification prompt. For STIG contributor local sync, use ./gradlew installSkill from stig/; no consumer installation step is needed. At the start of later workflows, each skill compares its plugin version with the consumer's effective STIG version reported by stigPrintVersion and gives this same update recommendation when they differ. It does not treat the consumer's gradle.properties pin as authoritative because a sibling STIG composite build can intentionally override that value.
See the official OpenAI documentation for plugin packaging and local marketplaces.