STIG workflows
This is the starting point for the main activities that a person, the STIG skills, or both working together perform with STIG. There is one workflow contract: the skills follow the same public guidance and invoke the same Gradle tasks as a person. You can ask it to complete a whole workflow, delegate one step, or use it to review work you performed directly. Agent-only guidance adds authorization and evidence-handling rules; it does not define a parallel product workflow.
Gradle tasks are the executable entry points for generation, checks, analysis, and publication. Authored engineering intent remains in the Kotlin/Markdown specification and project configuration. Generated files belong under build/ and are not committed. Gradle reuses valid outputs and regenerates affected outputs when inputs change.
The stig plugin provides specification, source-analysis, and project. Use the skill boundaries to select by the requested result. The responsible skill keeps its supporting checks and report verification. Source-analysis setup and later repairs stay in source-analysis; a shared Gradle task does not require switching skills.
In Codex CLI or the IDE extension, type the explicit reference, select the entry after $, or use /skills. The selector uses <plugin>:<skill>. Use the exact completion entry. A client may render it as ordinary text or as a highlighted mention; that rendering is separate from skill resolution. Codex may also select a skill implicitly when a request matches its description. Preserve the user's decisions and authorization when a request spans workflows.
Choose a workflow
The primary task column names the normal automation entry point. A workflow can also include source editing, engineering review, and checks around that task. The generated task diagrams show registered prerequisites; the task API supplies exact options and task-specific prompts.
Workflow | Primary Gradle task(s) | Scope | Codex skill |
|---|---|---|---|
Install STIG or start a consumer project | Follow the installation/project guide; | Project/user setup as requested |
|
Create a model-only element |
| Root creation |
|
Author or review CREATE specifications | Edit or review the authored model; | One element or project-wide validation |
|
Create a source-backed activity |
| Root creation; configuration for one element |
|
Create or reconcile source-analysis configuration |
| One element, selected by its Gradle path |
|
Check and align analysis evidence |
| One activity or root; progress per activity |
|
Generate and inspect the report |
| One element or root generation |
|
Publish the report |
| Root |
|
Initialize an element
stigInitElement creates an element's Gradle registration and initial authored model files. Use --importEnabled true when a configured source importer will own its Context interfaces. The scaffold is an ordinary Kotlin Context; stigImportModel later updates its interfaces explicitly. Use --importEnabled false when the interfaces are maintained in Kotlin.
There is no element-update command: edit authored model content directly. Start a new Gradle invocation after changing settings or build scripts.
Author or revise STIG specifications
Author engineering intent in the element's Context, Requirements, Design, Analysis, and Tests Kotlin sources and their supporting Markdown. Follow the CREATE authoring guide and the linked viewpoint tutorials. No Gradle task can invent or approve engineering intent: a person supplies it directly or answers the STIG skill's focused intake questions. Validate authored changes with the narrow element stigCheckModel, then generate the applicable report when the specification is ready for integrated review.
Configure analysis
stigConfigureAnalysis creates missing analysis configuration or reconciles an existing configuration using current native and LLVM evidence. The element's Gradle path selects the target:
Omitted inputs reuse the element's configuration. First configuration requires the native target, implementation, source selection, topics, annotations where applicable, and lifecycle information. Explicit options also determine the evidence used to produce the candidate.
--preview writes candidates and review findings under the element's build/stig/stigConfigureAnalysis/ directory. Without --preview, the command edits owned regions of the element's build.gradle.kts and the shared transform registry. It preserves explicit models and cannot supply engineering confirmation for a proposed transform. Run this command alone, then use a new Gradle invocation for compilation or reporting. It is never a report dependency. For a new code-backed Context, follow the source-backed element setup to extract its interface inventory, import it explicitly and check the resulting Kotlin sources before generating the report.
Check and align analysis evidence
stigCheckAnalysis has one staged review workflow and two collection modes. The default mode runs/reuses each activity's stigGenerateHtml chain and collects configuration, LLVM, P6, P7, and report evidence. Add --configuration-only while resolving configuration; it stops at P5 and does not run P6, P7, or HTML.
Follow Check and align analysis evidence with $stig:source-analysis: resolve missing shared registry definitions, required activity use(...) entries, and other incorrect configuration, review and confirm every active activity transform rule, choose a supported rerun, compare every sink across adjacent stages, then record accepted defects in activity-local knownGaps. Full semantic alignment is a review outcome, not an automatic consequence of a successful task or a zero flow-gap count. Activities can reach different stages independently.
Both modes produce structured local results. With --zip, an element task exports that activity; the root task exports one deduplicated collection of its selected activities. Export reports the archive path, size and encryption state. Configuration review also has the shared-rule index at build/stig/stigAggregateAnalysisConfigurationEvidence/source_code_analysis_review.json.
An export-only request does not request configuration edits or engineering acceptance:
It maps to:
For a full-chain collection that retains available evidence after failures:
Available evidence from a started activity is retained after failure by default. Add --continue to attempt other independent activities. The build still fails for failed producers. The unified evidence guide explains partial status, the structured replacement for HANDOFF.md, confirmation rules, and the current limits of source-free replay.
Generate and publish
stigGenerateHtml runs model checks, enabled harness generation and analysis, and HTML rendering. A change to generated content causes affected work to regenerate. Invalid inputs, failed compilation, and analysis contract violations remain errors.
The HTML pipeline first runs stigPrintVersion, which prints the consumer project name/version, the selected stigSource=published|local, and the loaded STIG plugin version. Use ./gradlew stigPrintVersion to inspect the same identity without generating a report. Local mode reports the loaded checkout's version; it does not report the ignored consumer stigVersion pin.
stigPublishHtml runs the report pipeline and publishes the result to the configured destination. It performs a remote write. See Report workflow for preview, publication, and module selection.
Automatic tasks that can also be invoked directly
Task | Output | Part of |
|---|---|---|
| C++ wrapper, interface header, and contract under the element's | Yes, when the configured generated harness is consumed by enabled analysis |
| Model/report Markdown under | Yes |
| Native build, LLVM, analysis, and diagram artifacts | The stages required by enabled features |
stigImportModel explicitly updates Kotlin specification sources from configured SYML, native Highway or code inputs. Run it separately, then invoke stigCheckModel or reporting. Compilation, checking and reporting never run model import. stigExportModel exports model data or the canonical Kotlin-defined JSON schema. See Model import and export for persistent mappings and the refresh workflow.
For code input, element.importEnabled enables the element's importer; the ordinary Context keeps authored hierarchy and internal units. Disabling further imports leaves existing source files available to compilation. Import and analysis remain separate switches. The analysis harness remains a cacheable build output.
Project and element scope
A pure project aggregate invokes element tasks with exactly the same name: each element's stigQuickCheck compiles its own classes. Root stigImportModel processes configured file inputs and delegates selected code inputs to the same-named element tasks, such as :activities:example_activity:stigImportModel.
Some root tasks produce their own output: root stigGenerateHtml renders the combined Dokka publication; root stigGenerateMarkdown writes project-level Markdown; root stigCheckModel and stigCheckAnalysis combine review evidence; root stigPublishHtml publishes the combined report. These producers have their own prerequisites and do not merely rename an element workflow.
An element's stigCheckModel loads every Highway declaration in its Kotlin module, then the complete contents of the model modules referenced by any of those declarations. This includes nested units and unreferenced declarations inside each selected module. References originating only in the supporting modules do not recursively expand the model-check scope; ordinary Kotlin runtime dependencies remain available. The same scope applies to live IDEA checks. Missing local viewpoints produce rule findings; failure to load a required module is an execution error.
Use ./gradlew help --task <task> or the generated Gradle task API for exact options.
Upgrade from STIG 2.0
Update scripts and evidence paths to the current task names. The former commands are removed:
Former command | Current command |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Run stigConfigureAnalysis for exactly one element in its own Gradle invocation. --preview retains candidate files under build/; the normal invocation edits configuration. Generate the report in a subsequent invocation.
Imported Context is ordinary Kotlin source. For example, ExampleActivityContext.kt declares the same element class and instance used by hand-authored viewpoints:
Configure inputs in the root stigProject { model { imports { ... } } } block. Use code { fromModules(...) } for native interface inventories, syml { ... } for SYML, cHeader { ... } for plain C header function prototypes and highwayJson { ... } for converted safety models. Run stigImportModel explicitly and commit the resulting sources. Compilation, checking and report generation never run import. Existing consumers that inherited an imported base class must consolidate its declarations into their ordinary Context class, retaining the element instance, parent and internal units.
Remove analyzerInput.harness.appendFromConvention. Keep the reviewed harness.lifecycleProfile and harness.enabled = true to consume the generated harness directly. Remove committed generator-owned harness copies after preserving any authored fragments, and select those fragments explicitly with harness.include(...). Generated C++ and headers stay under the element's build/ directory; imported Kotlin remains in src/main/kotlin/.
stigCheckAnalysis --configuration-only is the P1–P5 diagnostic mode; stigCheckAnalysis without that option checks the full report chain. Both modes leave generated evidence under build/ and never stage, commit, or push it.