Codex skill for BaZi translation and naming review. It keeps BaZi/Four Pillars terms consistent across Chinese source terms, English display labels, and code identifiers.

The skill is simplified-Chinese-first:

简体 is the concept key.
标准英文 is for UI/docs when an English label is needed.
代码名 is for identifiers, API fields, classes, schemas, and tests.

The source PDF is not included in this repository.

This repository also includes a Nexa BaZi contract checker for programmers. It catches mixed API fields, JSON schema names, prompt variables, and module keys such as Day_Master, DayMaster_Stem, Dominant_Deity, and Primary_Favorite_Element.

Install

Clone the repository and copy it into Codex skills:

git clone git@git.aplexlogic.com:fireparty/bazi_translation.git
mkdir -p ~/.codex/skills
rsync -a --delete bazi_translation/ ~/.codex/skills/bazi-translation/

Validate the skill:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/bazi-translation

Use In Codex

Invoke the skill by name:

Use $bazi-translation to review BaZi naming in src/bazi.

Typical requests:

Use $bazi-translation to translate these terms into approved English and code names: 日主, 天干, 地支, 大运, 用神.

Use $bazi-translation to review API field names in packages/bazi.

For Nexa:

Use $bazi-translation to review Nexa BaZi API fields, prompt variables, and module keys in nexa_bazi-main.

Use The Generic Checker

Run the local checker against files or directories:

python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py <path>

Exploratory review without failing the command:

python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py <path> --no-fail

List approved code names:

python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py --list-approved

Example output:

src/chart.ts:42: dayOwner -> dayMaster
  zh: 日主; standard_en: Day Master
  line: const dayOwner = chart.dayOwner;

Use The Nexa Contract Checker

Run the Nexa-specific checker against code, JSON, prompt files, or docs:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path>

Migration planning mode:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path> --no-fail

CI-style blocking mode, reporting only hard errors:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path> --min-severity error

List loaded Nexa rules:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py --list-rules

Example output:

5 八字详解/5.7 命理符号/2.命理符号-算法与判定规则.md:14: DayMaster_Stem -> day_master_stem [error]
  concept: 日主天干
  reason: mixed case 不适合接口契约
  line: DayMaster_Stem: "辛"

Severity handling:

error: do not add in new code; rename or add a compatibility migration.
warn: likely wrong for new BaZi fields; check whether it is already published.
review: not automatically unsafe, but it may show cross-system leakage or a published key that needs migration planning.

Core Naming Rules

Use dayMaster, not dayOwner or dayLord.
Use heavenlyStem, not skyStem.
Use earthlyBranch, not groundBranch.
Use luckPillar, not fortuneColumn.
Use usefulGod, not useGod.
Use favorableElement in code by default; keep Favourable Element for book-style display text.
Keep Useful God separate from Favourable Element.
For Nexa JSON/API/prompt fields, use snake_case: day_master, day_master_stem, dominant_ten_god, primary_favorite_element.
Do not use deity for Ten Gods in interfaces. Use ten_god.
Do not use astrology terms such as astral_event for BaZi branch relationships or daily BaZi events.

Nexa Contract Files

references/nexa-bazi-contract.md: canonical Nexa BaZi API/JSON/prompt naming contract.
references/nexa-naming-rules.md: practical naming rules and migration guidance.
references/nexa-forbidden-names.md: deterministic bad-name table used by the checker.

Files

SKILL.md: Codex skill trigger and workflow.
references/terms.md: simplified-Chinese-first dictionary.
references/naming-rules.md: review rules and anti-patterns.
references/nexa-bazi-contract.md: Nexa BaZi interface and prompt-variable naming contract.
references/nexa-naming-rules.md: Nexa-specific naming guidance.
references/nexa-forbidden-names.md: Nexa forbidden/legacy name table.
references/pending-terms.md: staging area for terms needing domain review.
scripts/check_bazi_names.py: source-code naming checker.
scripts/check_nexa_bazi_contract.py: Nexa BaZi API/JSON/prompt naming checker.