mufeng-bilingual-storybook

Files (11)

• README.md
• SKILL.md
• openai.yaml · agents/
• icon.png · assets/
• platforms.md · references/
• product-overview.md · references/
• revision-release.md · references/
• usage.md · references/
• workflow.md · references/
• mufeng_storybook.py · scripts/
• test_mufeng_storybook.py · tests/

SKILL.md (first lines)

# Mufeng Bilingual Storybook

## Resource Paths

Set the shell variable `SKILL_DIR` to the directory containing the **loaded** `SKILL.md` before running the commands below. Resolve supporting paths from that directory, not the working directory or a fixed user/platform installation path. `$SKILL_DIR` is a shell variable you set, not a host-provided macro.


## Image Tool Selection

Read [references/platforms.md](references/platforms.md) before generating artwork.
Prefer Codex built-in `image_gen` when available. In Claude Code, use an explicitly
configured image skill/tool with generation, reference-image and editing support.
Do not switch providers automatically. The helper itself does not call an image API.
If no image tool is configured, complete the scene/prompt plan and report the missing
dependency; do not claim that illustrations or final PDFs were produced.

For Codex, the default image source is `${CODEX_HOME:-$HOME/.codex}/generated_images/`.
For another configured image tool, set `MUFENG_IMAGE_ROOT` to its dedicated, actual
output directory. Import the exact PNG produced by the call and keep all quality gates.

## Image Persistence Rule

The helper script does not generate artwork. It only prepares deterministic
scene, prompt, manifest, generation-task, progress, and PDF layout files.
`--prompts-only` and `--dry-run` must never be described as having produced
final illustrations.

Treat these files as the generation contract:

- `manifest.json`: frozen scene plan and `plan_sha256`
- `generation_tasks.json`: stable task IDs, exact prompts, expected filenames,
  exact reference paths/hashes, local reference payload bytes, current
  filesystem status, and concurrency mapping mode
- `reference_manifest.json`: the hash-locked reference subset used by this
  output, when scenes use references
- `quality_gate.json`: append-only candidate QA decisions bound to task,
  candidate hash, scene QA-contract hash, and reviewer
- `progress.jsonl`: append-only timing and failure events
- `candidates/<task-id>/<sha256>.png`: project-local, unapproved artwork
- `qa_reports/<task-id>/<sha256>.json`: frozen structured visual reviews
- `pdf_validation.json`: final PDF hashes, page count, footers, and preview root

Use the selected image tool directly, one call per attempt. Record
`generation_started` immediately before the call and `generation_returned` or
`generation_failed` immediately after it. For a new quality-gated final
manifest, import the call-scoped persisted PNG with `--import-candidate`, never
`--import-image`. The candidate command requires a complete start/return event
pair, validates provenance and PNG bytes, and copies the attempt into the
project-local candidate area. It does not make the image PDF-eligible.

Open each candidate at original detail with the image-viewing tool, compare it
against that task's exact reference images, and fill the emitted QA template.
Use the actual reviewer identity, not the pending template value.
Record the report with `--qa-report ... --candidate-sha256 ...`. Only a report
whose verdict is `pass` and whose every required check is `pass` atomically
promotes the candidate to the exact final `images/` filename. A failed report
archives the bytes and returns a reason-targeted retry prompt.

Always resume from the existing manifest with `--resume`; never re-infer scenes
from possibly changed Markdown. A non-symlink, decodable, non-placeholder PNG
at the exact expected project path is complete and must be skipped without
touching it. Missing, corrupt, truncated, symlinked, or dry-run placeholder
files remain pending.

The helper refuses `generation_started` when that task already has a valid
project PNG. After each successful or skipped import,
`generation_tasks.json` is refreshed immediately; a later `--resume` still
revalidates all files independently.

Require a valid `plan_sha256` for manifest v2 and later. For a pre-v2 manifest, migrate
once with `--resume --migrate-legacy-manifest --prompts-only`; never silently
adopt a hashless manifest.

If the selected tool displays an image but exposes no readable persisted PNG,
stop and report the persistence failure. Do not substitute screenshots, placeholders
or SVGs for artwork. Immediately import each attempt into the project-local candidate
area, verify the copy, then proceed to the next image. A configured source directory
and timing events bound the import; they do not independently prove which provider
created the image. Report the actual tool and call evidence separately.

## Reference Traffic Control

Store each adopted reference inside the story or series project. For a series,
pass its root with `--reference-root` so every chapter uses one shared ID/hash
catalog instead of silently creating chapter-local identities. The helper
maintains the library at `<reference-root>/.mufeng-storybook/references/`:

- `master/`: byte-for-byte original copies protected by a SHA-256 contract
- `upload/`: metadata-stripped RGB JPEG proxies, longest edge at most 1024px,
  quality 85
- `catalog.json`: the project-wide ID-to-hash contract

This is a hash lock, not an OS-level immutable flag. If an existing ID's source
bytes change, the helper refuses the change; use a new ID deliberately.

Scene-plan `references` must contain stable IDs from `--reference-spec`.
Duplicates are rejected and each scene has a hard maximum of three references;
prefer two. For Codex ImageGen, pass only that task's exact `referenced_image_paths`
from `generation_tasks.json` and omit `num_last_images_to_include`. Never use master originals or rejected attempts as canonical references,
or attach the whole project or implicit conversation images. An inspected
project-local candidate may be an explicit localized-edit target; it does not
become an approved identity/style reference.

`reference_payload_bytes` and progress field
`local_reference_payload_bytes` are local file-size accounting, not measured
network traffic. They exclude multipart/base64 overhead, retries, client-added
context, downloads, cloud sync, and other Codex sessions. Do not promise a
200–500MB total from these numbers.

## Revision And Release Workflow

Read [references/revision-release.md](references/revision-release.md) for an
existing chapter, any single-page change, or final PDF delivery.

- Freeze scene meaning and bilingual captions first. Run `--preflight-text`
  before artwork generation. Resolve overflow by editing narration without
  losing story facts; never silently truncate captions or shrink fonts.
- For an otherwise approved image with a local defect, use a localized ImageGen
  edit. Pass the inspected project-local original as the edit target alongside

From ichangyou/mf-ai-skills, MIT.

More from ichangyou/mf-ai-skills