Documentation and agent knowledge ownership

Canonical ownership

Generated API/reference Markdown is build output and is never checked in or hand-edited. The generator writes it under stig-codex-plugin/build/; Writerside stages it under stig-docs/build/writerside-source, and plugin packaging embeds the same generated files with the canonical public manual.

The Glossary is authored in stig-docs/src/main/kotlin/com/stigway/cfg/glossary.xml, using Writerside's native terms/term format. Each term contains a plain-text definition, followed when needed by blank-separated Acronym: and Example: paragraphs. Keep terms alphabetical, ignoring case. The source-root generateWritersideGlossary task validates the XML against the bundled Writerside DTD and rejects duplicate or out-of-order names and blank names or definitions. Its Kotlin parser and KTE renderer preserve source order and write only stig-engine/build/generated/writerside/docs/glossary.md, escaping the decoded text for Markdown. The engine publishes this file through writersideGlossaryElements; Writerside staging and the Codex bundle consume that artifact rather than reaching into another project's build directory. There is no authored docs/glossary.md. The introduction and Markdown presentation belong to the engine's glossary.md.kte template.

prepareWritersideSource copies the authored XML unchanged and includes the generated Markdown, generated references, and media in stig-docs/build/writerside-source/stig/. Keep glossary.md in the Writerside navigation; it resolves in that prepared module. The bundled skills include the same generated glossary Markdown.

Generated reference content describes Kotlin-defined APIs and rule contracts and does not embed the build's version label. A transition from a snapshot to a release, or to the next snapshot, must not change these files unless those contracts change. The packaged .codex-plugin/plugin.json remains the version authority for the installed guidance, and staging verification checks it against Axion's project.version. Do not normalize version text or introduce a checked-in generated snapshot during CI release preparation.

The Codex module's test gate runs the real generator in separate JVMs with snapshot, release, and next-snapshot plugin metadata. It checks the resolved version in each process and compares every generated file byte-for-byte across them.

Documentation source layout

stig.tree determines the navigation and the physical topic paths under docs/. Keep each topic's filename equal to its topic attribute. A parent topic owns a directory with the same name without .md; a navigation group without a topic uses its lowercase title with spaces replaced by hyphens. For example:

• modeling-with-create.md owns modeling-with-create/tutorial_introduction.md.

• The Build and test group below developer-guide.md owns developer-guide/build-and-test/.

• The generated Highway model and rule catalogs belong in specifications/specifications-and-rules/.

Keep Kotlin examples in a directory named after their tutorial, such as modeling-with-create/context_tutorial/. Their Kotlin package declarations remain independent of the documentation navigation. writerside.cfg registers docs as the topic root. Generated references and the bundled manual preserve the same topic paths.

Link to other Writerside topics by their globally unique filenames. The pinned Writerside builder resolves these topic names independently of their directories; relative filesystem paths in topic links are not supported.

Use Markdown image syntax with paths relative to the topic so images render in both Writerside and IntelliJ IDEA's Markdown preview. Preserve sizing with Writerside's Markdown attributes. Revideo sources live in stig-docs/src/main/kotlin/com/stigway/videos/; the documentation build stages their generated media under images/ideaTour/.

Terminology

Use the preferred terms and meanings in the Glossary whenever discussing STIG concepts: conversation, progress updates, reviews, Markdown documentation and specifications, KDoc, and code comments. Read the relevant definitions before writing; use the same term for the same concept and keep different counting units distinct. For example, distinguish an activity transform-rule use(...) entry from a P5 rewrite application, and a missing required P5 definition from an incorrect list of reported P3 matches.

Prefer glossary concepts when naming new or deliberately renamed types, objects, functions, and properties, adapting them to the language's naming conventions. Preserve existing API identifiers, task names, schema fields, paths, and quoted evidence exactly; explain their meaning with the preferred terminology. Do not turn a documentation wording change into an API migration or alter historical evidence to match current prose.

Align wording first. Writerside term/tooltip markup and visual boxes are a separate presentation change; do not add them as part of terminology alignment. Ordinary Markdown and glossary links keep the same text useful in Writerside, Dokka, and the bundled skills. Edit definitions, acronyms, and examples in the authored cfg/glossary.xml, never in generated glossary.md or a staged skill copy.

Workflow rule

Explain each user-facing capability once on its public workflow page: what it solves, how to use it, a realistic example, the associated Gradle task, and a copyable prompt for the responsible skill. The task API supplies exhaustive version-specific syntax. The skills link those two sources and add only decisions that are specific to an agent.

The plugin contains three skills with one owner per requested outcome: specification for CREATE authoring and review, source-analysis for initial source-analysis setup through evidence checking and repair, and project for installation, general Gradle configuration, and ordinary reports. Keep supporting checks and report verification with the workflow that needs them. Sharing a task or reference does not require loading another skill. The public skill boundaries explain selection; each SKILL.md description must express the same boundary. Preserve user decisions across a real handoff. Do not create one skill per Gradle task or copy shared agent rules into independently authored skill trees.

The two stigCheckAnalysis collection modes share Check and align analysis evidence. Keep its staged activity workflow and source-free replay limits there, and route both modes to it from source-analysis/SKILL.md. Structured review JSON carries current facts and candidate edits; the skill adds agent decisions. Do not restore a generated long HANDOFF.md as another procedure or a second place to record confirmation.

A generated activity review template presents those facts with explicit units, severities, and availability, followed by two complete sink tables. Collection writes that template only into build outputs and the optional ZIP. At review time, the standalone Kotlin review task can initialize a persistent working copy at an explicitly selected destination outside the archive and disposable task outputs. The AI fills the designated semantic observations, comparison statuses, and proof notes there; that working copy is an authored assessment document. Producer observations, counts, and problem identities retain their Kotlin/JSON authority. Refresh them from fresh evidence, preserve reviewer edits, and mark affected assessments stale when their inputs change. The public evidence workflow owns the cell meanings and the skill owns how an agent reviews them. This worksheet records progress without recreating the retired procedural handoff or accepting transforms.

Do not create a second skill-authored version of a public workflow. Do not put explanatory prose into generated JSON. Do not copy task options into hand-written Markdown when the generated reference can be linked instead.

Repository-owned development guidance

STIG maintainer workflows are followed from the current Git checkout. Keep a short routing entry in each repository's AGENTS.md and one canonical development page per workflow. Change sync instruction owns all submission paths; Submission execution owns their focused reading, waiting, diagnostics, and compact run state. A handoff records the current request and evidence, not another authored procedure.

This guidance needs no plugin installation. The consumer-facing stig-codex-plugin owns CREATE, source-analysis, and project/report workflows; a submission gate that invokes a consumer task does not transfer ownership to a consumer skill. Developer reference pages may be part of the shared manual without becoming skill entry points.

Codex supports checked-in .agents/skills/<name>/SKILL.md files without user-scoped installation. Use that option only when a focused named entry point or automatic discovery has a demonstrated benefit, and have it route to the same canonical documentation. Repository discovery stops at the repository root, so a consumer checkout does not automatically discover a skill in a sibling STIG checkout. The direct AGENTS.md route works across this layout. See Codex skills for discovery and progressive loading.

A separate development plugin is useful when reusable capabilities need distribution across unrelated checkouts or MCP/tool dependencies. Packaging by itself does not reduce context: short entry files, selective reference loading, bounded tool results, and reusable run state do. Do not duplicate workflows or enlarge the consumer plugin solely to make local development instructions callable.

Distribution boundary

Stage the canonical public manual, generated API and shared agent references into each declared skill. Verify each skill's name, metadata, required references and link closure. This duplicated distribution keeps references local to the selected skill without maintaining two manuals. Generated task prompts and archive entry points select the responsible skill. Retained archives are read through explicit supported schema contracts; an older skill name in workflowContract.skill is informational metadata. Request regeneration for missing or stale required evidence, not for that label alone. New archives include producer revision, dirty state and source fingerprint to distinguish builds that share a SNAPSHOT version.

For model-rule review, also stage the canonical CREATE rules, Highway metamodel, and local problem/reference helpers with repository-relative paths and byte parity. These are source references read on demand, not independently authored rules. Kotlin supplies semantic contracts and selects review work; the skill owns evidence-based judgment and the Kotlin/Markdown review procedure. Semantic assessments do not feed AI verdicts into build failure thresholds.

The rule catalog takes display names and possible finding severities from ModelRule. Its implementation blocks come from generateStigRuleImplementations, which uses the pinned Kotlin parser in an isolated process, then feed generateStigKnowledgeReferences. Inherited rules show their concrete configuration and shared check implementation. Maintain the Kotlin source instead of editing these excerpts. Severity badge images use the report palette and are staged into Writerside's image directory; the bundled Markdown retains their text alternatives.

Bundle public workflow Markdown and small text examples. Exclude Internals, workplans, release history, generated site assets, and large media. Internals are maintainer policy, not context every consumer agent should load. Images and video remain in Writerside; their surrounding explanation remains useful in the bundled Markdown without the binary asset.

stigInstallSkill owns installation; the STIG source-root installSkill shortcut delegates to it using the current build's packaged Gradle plugin. Building STIG or a local composite consumer may build and embed the Codex bundle, but no normal build, report, CI, or publication task installs it or changes user-scoped Codex state.