create-background

name	create-background
description	Create or revise reusable webtoon location records and approved versioned multi-angle background asset sets. Use when defining a story location, generating its canonical main view plus grounded reverse and oblique views, repairing background continuity, or linking approved background assets into backgrounds/*.md and episode panels.

Create Background

Create location canon and a reusable four-view visual set without letting camera changes alter the architecture.

Required reading

Read references/background-contract.md before preparing or approving a set. Read the linked project.md, style/artwork-style.md, style/000.storytelling-guide.md, style/visual-style-guide.md, relevant world/plot/episode files, and the existing backgrounds/<id>.md when revising a location.

For every generated view, load and follow $imagegen. Use its built-in image generation path by default, one call per view, and label each attached image by its job role. Do not call an image API, CLI, or local renderer for artwork. Copy selected project-bound results into the declared workspace paths; never leave a referenced background only under the built-in generated-images location. Bundled scripts may prepare guides and metadata, build a contact sheet, and validate artifacts; they must not generate or redraw the background.

Runtime

Before running bundled scripts, call load_workspace_dependencies and set PYTHON to the returned executable. Run scripts through the repository lock as uv run --frozen --python "$PYTHON" python ...; the lock supplies Pillow and PyYAML. Stop and report a missing runtime or lock dependency.

Workflow

1. Define location canon. Confirm the background ID, story function, era, architecture, layout, visual style, and at least one stable spatial anchor. Prefer doors, windows, stairs, counters, columns, major furniture, or fixed light sources. Record side relationships and distances, not only an object list.

2. Prepare an immutable version. Run:

   uv run --frozen --python "$PYTHON" python .agents/skills/create-background/scripts/prepare_background_run.py \
     --project-root /absolute/path/to/webtoonista \
     --background-id <lowercase-slug> \
     --title "<location title>" \
     --description "<physical layout and story use>" \
     --style-notes "<canonical art direction>" \
     --artwork-manifest assets/style-references/v001/artwork-manifest.json \
     --anchor "entrance=<where it is and what it faces>" \
     --anchor "window-bank=<position relative to entrance>"
   

   Omit --version to select the next unused vNNN. Never reuse or overwrite an approved version. The approved $create-artwork manifest is authoritative; preparation verifies all five anchor hashes and attaches them to every imagegen job. Location notes may specialize architecture and mood but may not redefine line, palette, light, perspective, materials, effects, or rendering language. Inspect the reported run directory and imagegen-jobs.json.

3. Generate the canonical main view. Give $imagegen prompts/main.md and every input_images item for the main job, with role labels. Copy the selected project-bound output to the job's output_path; never leave it only under $CODEX_HOME. Check the spatial layout, anchor identities, architecture, palette, and camera before continuing. Mark the job complete only after the copied file exists.

4. Generate grounded angle views. Generate reverse, left-oblique, and right-oblique as separate $imagegen calls. Attach the approved views/main.png as the authoritative geometry/identity reference and the prepared layout guide as layout-only input. Preserve anchor topology, scale cues, materials, lighting logic, and style. Do not mirror, crop, warp, or locally synthesize the main image to fake another camera.

5. Review incrementally. For each angle, compare fixed anchors to the main view. An anchor may be occluded or out of frame only when the camera geometry explains it. Reject added/removed doors, shifted windows, impossible room topology, prop teleportation, style drift, or a purported reverse/oblique view that is only a restyled main view.

6. Build QA evidence. Run:

   uv run --frozen --python "$PYTHON" python .agents/skills/create-background/scripts/make_background_contact_sheet.py \
     --run-dir /absolute/path/to/assets/backgrounds/<id>/vNNN
   

   Have an independent visual reviewer inspect only the four approved view files/contact sheet plus the location contract. Fill qa/spatial-anchor-review.json: all view-level verdicts and every anchor verdict must be pass, with concrete visual evidence. pending, warning, or fail blocks approval.

7. Validate twice. Mark all four jobs complete with source_path and completed_at, then run:

   uv run --frozen --python "$PYTHON" python .agents/skills/create-background/scripts/validate_background_set.py \
     --run-dir /absolute/path/to/assets/backgrounds/<id>/vNNN \
     --json-out /absolute/path/to/assets/backgrounds/<id>/vNNN/qa/validation.json
   

   After it passes, change only manifest.md frontmatter status: draft to status: final, rerun validation with --require-final, and do not edit approved view files afterward.

8. Link canon. Create or minimally update backgrounds/<id>.md only after approval. Copy all repository-relative fields from the printed background_links block, including the exact artwork_version and artwork_manifest; do not let a background silently use another style version. Update world/continuity sources if the imagery establishes a new canonical fact.

Repair rules

• Repair a failed angle by regenerating that complete view with the same main reference and stronger anchor instructions.
• Regenerate the main view and all dependent angles in a new version if the canonical geometry is wrong.
• Never patch architecture by compositing unrelated generated fragments or by editing an approved version in place.
• Treat deterministic failures as pipeline failures; fix paths, dimensions, metadata, job state, or QA records before requesting new art.

Acceptance

• main, reverse, left-oblique, and right-oblique are opaque PNGs at the declared common dimensions.
• Every non-main job was generated from the approved main view and has recorded source provenance.
• The set preserves the same location identity, anchor topology, architecture, palette, and style across all views.
• qa/contact-sheet.png, a complete passing spatial-anchor review, and a passing qa/validation.json exist.
• manifest.md is final, its paths exist, and the linked backgrounds/*.md record pins this exact version.