About this project

# Skyrim Creation Kit Agent This repository contains research and engineering artifacts for developing an AI-assisted mod authoring agent for *The Elder Scrolls V: Skyrim Special Edition* and *Anniversary Edition*. The project focuses on safety-first methodologies, converting high-level modding intent into typed, reversible, and evidence-backed operations. ## Core Philosophy The system operates on four principles: 1. **AI decides WHAT**: The LLM/planner determines the desired operation. 2. **Deterministic software decides HOW**: Typed workers execute the actions. 3. **Validators decide WHETHER IT WORKED**: Automated checks ensure integrity. 4. **A human decides WHETHER TO ACCEPT**: Final approval is required before application. The target product is a hybrid orchestrator where the primary path is headless and deterministic. The Creation Kit is treated as a narrow capability rather than the core of the system. ## Current Status **Research + Validated Synthetic Proof of Concept.** This is not yet a general-purpose mod authoring agent, nor does it currently automate the Creation Kit directly. The current Gate-1 verdict is "VIABLE WITH LIMITATIONS". While most record-level operations can plausibly avoid the Creation Kit, several areas remain unresolved (e.g., FaceGen, navmeshes, complex quest semantics). ### Status Vocabulary - `VERIFICADO`: Supported by direct evidence or reproducible test. - `PASS`: Experiment executed and passed defined gates. - `NO VERIFICADO`: Plausible but not reproduced here. - `HIPOTESIS`: Proposed experiment or design claim. - `EXPERIMENTAL`: Implemented only as an experiment. - `BLOQUEADO`: Cannot proceed in the available environment. - `DESCARTADO`: Explicitly rejected. - `LEGAL_REVIEW_REQUIRED`: Technical path exists, but licensing/EULA implications are unresolved. ## Architecture The recommended product shape is a **hybrid orchestrator + headless-first primary path**: ```text User Intent ↓ Intent normalizer ↓ Planner / LLM ↓ Typed ModPlan ↓ Policy / safety engine ↓ Capability router ├─ Headless plugin worker ├─ Papyrus worker ├─ xEdit validator └─ Creation Kit worker [disabled until independently verified] ↓ Candidate workspace ↓ Validator ↓ Human approval ``` The planner must not receive arbitrary shell commands or GUI automation primitives. Operations are routed to specific workers based on type. ## Validated Implementation: POC-002 `research/poc_002/` is the first executable proof of concept: - Uses synthetic TES4 fixtures only. - Implements a strict parser with closed operation enums. - Enforces candidate-only workspaces with path containment. - Ensures fail-closed orchestration and no-overwrite receipts. - Maintains SHA-256 invariants for original files. - Includes 44 automated tests (initial baseline: 43; +1 adversarial regression). To run POC-002: ```bash cd research/poc_002 python -m compileall . python -m unittest test_suite.py -v ``` Note: This does not prove compatibility with arbitrary real Skyrim plugins, Creation Kit runtime behavior, xEdit, PapyrusCompiler, Mutagen, or in-game correctness. ## Discovery Desk Research UI The repository preserves a small Next.js + Drizzle/PostgreSQL research app called "Discovery Desk". - `src/app/`, `src/db/`, and `src/lib/research/` belong to this UI. - It is **not** the runtime of the future authoring agent. - Development requires a `DATABASE_URL` environment variable (see `.env.example`). The build process fails fast if the variable is missing, but no live PostgreSQL server is needed for CI as the connection pool is lazy. ## Safety Rules - Never modify a user's only copy of a plugin. - Originals are immutable inputs; writes go to candidates. - No arbitrary shell commands in AI-generated plans. - No coordinate-click GUI automation as the primary path. - Missing completion evidence is failure, not success. - Never commit Bethesda game/editor binaries, vanilla plugins, or vanilla Papyrus sources. - Process isolation is a technical boundary, not an automatic licensing conclusion. ## Licensing - **Repository-authored core code**: MIT License. - **Mutagen / Synthesis / Spriggit**: GPL-3.0-only. Combined works require GPL compliance. - **xEdit**: MPL-2.0 upstream. Intended for external execution, never vendored. - **CKPE**: LGPLv3 code plus Creation Kit EULA/legal overlay. Status: `LEGAL_REVIEW_REQUIRED`. - **Creation Kit, PapyrusCompiler, vanilla assets**: Proprietary user-installed components. Never redistributed. Third-party npm packages and OFL fonts have separate notices. Imported research ZIPs have unresolved provenance. ## Relationship to Sky-Claw This is a separate repository and research track. It may later integrate with Sky-Claw through a documented protocol but must remain independently testable and not assume Sky-Claw internals as its safety boundary. ## Disclaimer Unaffiliated with Bethesda Game Studios, ZeniMax Media, Valve, Nexus Mods, or third-party tool authors.