bg3-dnd55e-russian-localization/AGENTS.md

AGENTS.md

Execution Model (MUST)

• Read this file first; treat as system-level constraints.
• Priority:
  1. User instructions
  2. AGENTS.md
  3. Existing code/style
  4. Best practices
• Prefer minimal, non-breaking changes.
• Do not introduce unnecessary abstractions.

---

Communication (MUST)

• Answer first, then request approval if needed.
• Concise, meaningful, no filler.
• Do not end response with only procedural choice.

Approval/clarification:

• ask once, no repetition

• binary → yes/no

• multiple → numbered options + brief context

• File links in repo docs/checklists: relative paths, /, spaces as %20.

• In assistant UI responses, use the link format required by the execution environment; include relative path text when possible.

---

Git Workflow (MUST)

• Never commit/push without explicit user approval.
• After approval → commit + push immediately.
• Commit messages: Russian, factual (what was done).
• Branch (fix/* or feat/*): ask once before the first file-changing task that may lead to commit; reuse decision for all subsequent tasks in same dialogue.

After work in fix/* or feat/*:

1. MR → main
2. merge → main + delete branch

Push failure:

• retry ≤2 times, 3s delay

Release link:

• provide [version](url) immediately after tag push, without waiting for CI

---

Scope (MUST)

• Repo = Russian localization mod only.

Allowed:

• localization content
• packaging/release metadata

Forbidden:

• gameplay logic

• Script Extender

• unrelated assets

• Repo must remain source-only.

• Never commit .pak or build artifacts.

---

Paths (MUST)

• Mod: Mods/DnD 5.5e AIO Russian
• Localization: Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml
• Metadata: Mods/DnD 5.5e AIO Russian/meta.lsx
• Build: scripts/build.ps1 (single source of build truth)
• CI: .gitea/workflows/build.yml
• Glossary: glossary/glossary.normalized.json (primary terminology reference)
• Actions: ACTIONS.md
• Upstream EN reference: https://github.com/Yoonmoonsik/dnd55e/blob/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml

---

Packaging (MUST)

• .pak contains ONLY Mods/...

Required:

• meta.lsx
• russian.xml

Forbidden in .pak:

• .git, .gitea
• scripts, tools, .tools
• build, staging dirs

Staging:

• use %TEMP%
• not inside repo

---

Build & CI (MUST)

Flow:

1. prepare
2. download Divine
3. run scripts/build.ps1
4. publish

Outputs:

• build/*.pak
• build/info.json
• build/*.zip (tag only)

Release ZIP:

• only .pak + info.json

Triggers:

• automatic: push tag v*
• manual: workflow_dispatch
• branch pushes without tag MUST NOT publish release artifacts

---

Versioning (CRITICAL)

Source of truth: ModuleInfo/Version64 — read via explicit XML parsing: save/region[@id="Config"]/node[@id="root"]/children/node[@id="ModuleInfo"]/attribute[@id="Version64"]

Rules:

• do not change PublishVersion
• tag MUST match version

Before tag:

1. if version already changed → use it
2. if same as last → bump: scripts/set-version.ps1 -VersionTag <tag>

build.ps1:

• derives version from tag
• writes to info.json + staged meta.lsx

Conflict resolution (MUST):

• before release, Version64 in meta.lsx MUST equal target tag version
• if mismatch, run scripts/set-version.ps1 -VersionTag <tag> and re-check
• if still mismatch, release is blocked

---

info.json (MUST)

Root:

• Mods, MD5

Per mod:

• Author, Name, Folder, Version
• Description, UUID, Created
• Dependencies (array), Group

Dependency UUID: 897914ef-5c96-053c-44af-0be823f895fe

---

Guardrails (MUST)

Before commit:

• scope valid (localization/metadata only)
• no forbidden content
• no build artifacts (.pak, build/, staging)
• no temp/debug artifacts; ignored patterns MUST be present in .gitignore: build/, build-stage*, .tools/, *.pak
• packaging invariants intact
• version consistent (if applicable)

Before push:

• explicit user approval
• commit message valid (RU, factual)

Before release:

• version == tag
• version bumped if needed
• CI/build contract valid
• outputs correct (no extra files)

---

Release & Changelog (MUST)

• Every release MUST include changelog.

Changelog:

• language: Russian
• concise, user-facing
• describe WHAT changed
• group logically

Sources:

• prefer diff over commits

Diff rules:

• inspect real file changes

Localization (russian.xml):

• added / changed / removed strings
• summarize user-visible impact (UI, spells, descriptions)

Metadata / CI:

• describe effect, not raw edits

Large diff:

• group + summarize

If no visible changes:

• state "техническое обновление"

Before release:

• generate changelog draft
• ask for approval

Approval gates:

• Gate A: explicit approval for commit/push (code/content changes)
• Gate B: explicit approval for release publish (after changelog draft)

Release message:

• version
• changelog
• [version](url) if derivable

Do not:

• invent changes
• include internal noise

---

Rules Maintenance (MUST)

• Changes to AGENTS.md / ACTIONS.md: prefer compressed, machine-readable edits.
• Keep updates minimal and non-duplicative: merge overlapping points, remove redundancy, preserve intent.