Decision order
- Confirm a plugin is actually required. Prefer SPID, KID, SkyPatcher, FLM, BOS, CDF, or Papyrus runtime lookup when they express the change safely.
- For typed record creation or overrides, prefer a Mutagen C# tool or Synthesis patcher pinned to the target game release.
- For an existing plugin, load a workspace copy and preserve masters, flags, unknown subrecords, and override identity unless the plan explicitly changes them.
- Use raw binary surgery only for a narrow, fully specified transformation with a parser, fixture tests, before/after structural audit, and byte-level diff. It is never the default writer.
- If the selected typed library cannot represent the required record family, stop rather than improvising bytes.
Required inputs
- Target runtime and plugin type.
- Source plugin and required masters.
- Exact record plan with EditorIDs or resolved FormIDs.
- Save-compatibility requirements.
- Script and VMAD requirements.
- Expected new-record count and light-plugin eligibility.
Plugin defaults
Read references/plugin-invariants.md. Legacy light plugins use HEDR 1.70 and new local IDs 0x800-0xFFF. Extended light output uses HEDR 1.71 and local IDs 0x001-0xFFF; when any local ID below 0x800 is used, Skyrim.esm must be the first master. Validate the complete master chain.
Workflow
- Run
forge plugin-info <plugin>for the header/master summary where useful. - Generate a machine-readable record plan.
- Implement with a typed writer in an isolated project.
- Reload the produced plugin with the same library and compare intended records.
- Run
scripts/audit_plugin_headers.py; supply--master-rootwhen master files are available. - Run
scripts/test_plugin_header_fixtures.pyafter changing the validator. - Compile attached Papyrus scripts separately.
- Verify masters, record count, FormID allocation, ESL flag, and archive path.
- Record what was not semantically validated without xEdit or Creation Kit.
Stop conditions
Do not claim completion for navmesh, facegen, complex dialogue/scene data, or unsupported VMAD structures unless the actual authoring and validation path exists.
Evidence standard
Use this hierarchy for version-sensitive facts:
- The active project's
ENVIRONMENT.md,TASK.md, installed framework version, and build files. - Official upstream documentation or source for that exact version.
- Known-good files from the user's installed mod library, read-only.
- Direct inspection of the relevant ESM, ESP, DLL, script, log, or archive.
Do not substitute memory, an old example, or a plausible token. Record the evidence path or URL in VALIDATION.md.
Evidence-derived plugin controls
- VMAD validation must cover string encoding, object format, property data order, script/property visibility, and master/local FormID ownership.
- Treat SEQ as a verified binary artifact. Never emit ASCII FormIDs or invent a
SEQSheader. - Audit HEDR counts against the exact parser/tool contract, including GRUP handling when required by that format.
- Keep an immutable original and parent. Classify defects as inherited, fixed, newly introduced, or unverified.
- Compare final public claims, MCM text, record plan, and actual implementation.