Sokqa Pack Generator

日本語の仕様・使い方

Sokqa Pack Generator is a Codex Skill for designing, generating, resuming, and validating Japanese standard-mode Sokqa learning packs. It turns a course request into approved blueprints, document and four-choice quiz JSON, Japanese TTS text, and an ordered pack manifest.

Scope

Version 1 focuses on Japanese standard learning packs with language: ja.

It supports:

• document and four-choice quiz packs;
• off, selective, or explicitly approved complete Japanese TTS, with selective as the default;
• none, dictionary-only, or dictionary-plus-AI TTS correction, with a shared allowlist and AI as the Japanese standard-mode default;
• resumable generation state;
• JSON Schema and semantic validation;
• duplicate detection and manifest generation;
• draft-first publication safeguards.
• structured source rendering with objective and source-unit coverage;
• balanced deterministic answer positioning and unchanged-output skipping.

It does not yet support multilingual language-learning mode, tagged multi-language TTS segments, or language-learning-specific choice validation.

Learning design

New profile-2 generations recommend one internal material type from the learning goal rather than exposing a large style menu:

• listen builds a coherent spoken path from orientation and concept through reason, example, application, and recap;
• keyPoints creates distinct retrieval targets for memorization and rapid review of terms, contrasts, conditions, numbers, sequences, and exceptions.

The approved material type, reason, one pack-wide primary style, and at most one supporting style are persisted in the blueprint, course source, and generation state. They are not added to public Sokqa pack JSON. Existing profile-1 structured sources remain supported.

Workflow

1. Normalize the request with ttsMode: selective and outputMode: draft defaults.
2. Present every normalized setting in one preflight proposal and obtain one approval.
3. Complete each learning block as three documents followed by its block-scoped quiz.
4. Render structured sources into deterministic pack JSON and skip unchanged outputs.
5. Generate Japanese TTS according to the approved mode.
6. Build the ordered manifest.
7. Run structural, coverage, TTS, quiz-logic, and duplicate checks.
8. Fact-check externally verifiable claims.
9. Keep output in a draft location until publication is explicitly approved.

Repository layout

.
├─ README.md
├─ LICENSE
├─ .agents/skills/sokqa-pack-generator/  # repository discovery entry
├─ .github/
└─ sokqa-pack-generator/
   ├─ SKILL.md
   ├─ agents/
   ├─ references/
   ├─ schemas/
   ├─ scripts/
   ├─ assets/
   └─ tests/

The installable Skill is the nested sokqa-pack-generator/ directory. The .agents/skills/sokqa-pack-generator/ entry lets Codex discover that canonical skill automatically while working in this repository.

Install

Copy the nested sokqa-pack-generator/ directory into your Codex skills directory, preserving its folder name. Then invoke it as $sokqa-pack-generator, or ask Codex naturally to create or revise a Japanese Sokqa learning pack. In this repository, the .agents/skills discovery entry supports implicit invocation without installation.

Validate

The validators use the Python standard library and require no third-party packages.

New generation jobs use one 16-character Crockford Base32 token shared by all top-level IDs and filenames. Resume operations reuse the recorded token. Document items use compact s1, s2, ... IDs and quiz items use q1, q2, ... IDs scoped to each file.

python -m unittest discover -s sokqa-pack-generator/tests -v

Individual validators can also be run directly:

python sokqa-pack-generator/scripts/validate_pack.py sokqa-pack-generator/packs/_drafts/{theme}/{generationToken}
python sokqa-pack-generator/scripts/validate_course_structure.py sokqa-pack-generator/packs/_drafts/{theme}/{generationToken} --scale standard
python sokqa-pack-generator/scripts/validate_quiz_logic.py path/to/quiz.json --strict-warnings
python sokqa-pack-generator/scripts/validate_source_alignment.py sokqa-pack-generator/packs/_drafts/{theme}/{generationToken}/course-source.json --strict-warnings
python sokqa-pack-generator/scripts/validate_tts.py --mode selective --correction-mode ai sokqa-pack-generator/packs/_drafts/{theme}/{generationToken}
python sokqa-pack-generator/scripts/detect_duplicates.py sokqa-pack-generator/packs/_drafts/{theme}/{generationToken} --fail-on-near
python sokqa-pack-generator/scripts/validate_fact_check.py sokqa-pack-generator/packs/_drafts/{theme}/{generationToken} --strict-warnings

Render approved structured sources:

python sokqa-pack-generator/scripts/render_course_sources.py path/to/draft/course-source.json
python sokqa-pack-generator/scripts/render_course_sources.py path/to/draft/course-source.json --through-block 1

Default quizzes are block-scoped: quiz 1 uses documents 1-3, quiz 2 uses documents 4-6, and quiz 3 uses documents 7-9. Cumulative quizzes require explicit approval and are added separately.

Generate a new job token before creating pack files:

python sokqa-pack-generator/scripts/generate_generation_token.py path/to/existing/packs

Automated checks complement semantic review. They cannot prove factual accuracy, natural Japanese, pedagogical progression, or that a quiz has only one defensible answer.

Safety

The Skill generates into a draft location and does not publish, overwrite production packs, or change app registration without explicit approval.

Roadmap

Language-learning mode should be added only after its public data contract is defined, including pack and learning languages, choice-language behavior, tagged TTS segments, and mode-specific quality rules.

License

MIT License. See LICENSE.