School Awards Ceremony

School Awards Ceremony

Reuse the preserved product framework; never regenerate the stage page from scratch. Keep event.json as the only editable source of truth; generate runtime data, operating documents, and the finished site from it.

Leading Principle: The Visual System Is First-Class

The value of this framework is the kinetic experience a slide deck cannot deliver. Every event must be animated, never a static page. So the visual system is confirmed before the roster and program are built, and it is an asset that is preserved and reused, not re-authored.

Read references/visual-system.md before any design work. It defines the three hard contracts:

• Motion contract: every scene has an entrance + ambient layer, seamless themed transitions, a same-page one-shot reveal (all roster items appear at once, never in batches), and a gathering closing climax. The framework guarantees these; themes provide the visual style only.
• Layout contract: the award-title anchor is the top-left corner, and every roster/name list uses a fixed framework-level grid (one screen, no scroll). Themes may change color / type / texture but not the layout skeleton.
• Theme contract: a theme is a self-contained themes/<name>/{theme.css,fonts/,images/}. It owns appearance only; it never owns behavior or layout.

General Principles (co-creation, not template-copying)

1. The author decides; the AI proposes. The author owns the event. The AI offers structures, options, and candidates for the visual system, music, copy, and roster — but the author makes the choice.
2. When in doubt, ask. If the AI cannot determine something that would materially change the result, stop and ask the author rather than guessing or borrowing from a previous event. Ask one to a few focused questions.
3. An explicit author instruction is executed decisively. Once the author gives a clear instruction, carry it out fully and faithfully; do not quietly swap in a different plan, default, or "improvement".
4. Reuse method and framework, never content. The skill reuses the engine, the motion / layout / theme contracts, and the workflow. It never copies the previous event's music, wording, imagery, roster, or theme skin verbatim.
5. Source real, licensed assets. Use publicly available free assets (open fonts, CC0 / Mixkit / Pixabay imagery and audio) and record each source + license. Confirm the author's choice before wiring them in.

What to Preserve vs What to Confirm

The skill preserves the framework and method; it never carries an event's content into the next one.

Preserve and reuse without asking (the reusable assets):

• Engine behavior: navigation, M/Esc menu, blackout, fullscreen, music fade-in/out, same-page one-shot reveal (all names at once), scene transitions, the motion contract.
• The layout + motion contract: title anchor top-left, framework-level roster grid, scenes are never static.
• The theme contract and the proven theme skins as swappable visual systems.
• The creation workflow and the component-extension interface.
• The runtime content overlay: site/content.json is a live-editable file the page reads at load and re-reads during setup. It overrides page text (names, teams, honorees, titles, subtitles, totals) and is preserved across rebuilds. Editing it and refreshing updates the page with no rebuild — the operator owns the content file; event.json owns structure.
• The closing hold rule: the closing page stays on screen at least closing_hold_seconds (default 40) before fading out, so the host isn't cut off and the ending isn't rushed.

Confirm with the author before adding (do not copy the previous event):

• Visual system / theme: which theme, or build the author's own visual direction (north star, colors, motif). Never reuse a theme blindly.
• Music: present candidates, let the author pick (or supply tracks), then wire. Never auto-seed the previous event's tracks.
• Sound effects: only add if the author confirms; omit playful / game-style SFX by default.
• Copy / text: opening line, thank-you lines, closing lines, award names come from author data. The framework never hard-codes theme-specific copy (e.g. star imagery).
• Roster / names / media: per-event and private; never packaged into the skill.

Building a Theme From a Reference

• The visual system (theme) is derived from the author's visual reference image (a screenshot, poster, slide deck, previous event page, or mood board). Ask what to preserve and what to avoid; never invent a theme.
• Build the theme from publicly available free assets: open fonts, CC0 / Mixkit / Pixabay imagery and audio, textures. Record each asset's source and license; prefer assets that allow commercial use.
• A theme is not "change a color"; it is a full visual subsystem: colors, typography, background / particle motif, entrance / transition / reveal / closing styles, materials. The framework only triggers them.

Typography

• Fonts must carry artistic intent, especially the title font. Prefer calligraphy / brush display type (e.g. 龙藏 LongCang, 指尖的新 Zhi Mang Xing — open-license Google Fonts) over plain Songti / Kaiti for headline scenes.
• Body and operator text keep a clean sans (PingFang / Microsoft YaHei) for distance readability.
• Provide a reference font for the author to confirm first; only fine-tune glyph choice, weight, and effect after approval.
• Bundle a licensed local display font when the venue computer may lack system calligraphy faces.

Workflow

1. Pick the visual system first. Confirm the visual north star and one concrete visual reference. Read references/visual-system.md. If reusing a preserved theme, select assets/themes/<name>; if the event needs a new theme, build a self-contained theme per assets/themes/THEME-CONTRACT.md. Tooling must run before any data build; do not use a generic theme as a stand-in.
2. Confirm foundation facts: event title, date, venue, duration, audience, whether the event is a grade-transition or entrance ceremony.
3. Intake the complete segment list in the author's desired order. Accept ordinary language such as “开场—颁奖—学生发言—抽奖—表演—惊喜—谢幕”; do not require program-type names. Read references/program-intake.md.
4. Map each segment to an existing component (type) whose behavior matches. If the event needs a behavior no component covers, add a component (renderer + data contract + optional music slot + optional asset slots) as an extension; do not rewrite the engine or the motion/navigation experience.
5. Define one event mainline. Give every segment a purpose such as recognition, student presentation, interaction, transition, or closure. Preserve every author-requested segment unless the author agrees to remove or merge it.
6. Record the confirmed event info, program (order preserved), assets (music + media paths), and creative direction (visual system + music decision) in event.json. Keep a status pending until the author confirms.
7. Import award/roster data with scripts/import_awards.py. Stop on count mismatches or duplicate names within one award; never guess or silently repair a name. If an import changes program nodes, ask the author to reconfirm the resulting order.
8. Wire music. Assign a track to every confirmed segment's music slot in assets, and record sources in audio/SOURCES.md. If background music is confirmed, a slot left empty is a build error, not a silent gap.
9. Build with scripts/build_event.py — it copies the preserved framework into site/, applies the selected theme, injects generated data, and wires media. Then validate with scripts/validate_event.py. Treat errors as delivery blockers and warnings as explicit rehearsal decisions.
10. Run the visual QA gate. Render at least three representative scenes, compare them to the reference for composition / color / motif; confirm the page is dynamic (not static), the title anchor is top-left, rosters fit one screen, and scene transitions are smooth. Read references/visual-system.md §5.
11. Rehearse navigation, media playback, blackout, menu jumps, the one-shot reveal, and closing. Read references/qa-checklist.md for the complete gate.
12. Put final artifacts in deliverables/, raw inputs in materials/, and retired process files in archive/. Keep each event's event.json, roster, theme copy, and media in the event project; do not store per-event names, photos, or private media inside the skill.

Commands

Set the skill path explicitly; do not assume CODEX_HOME is configured.

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/create_event.py \
  --output /absolute/path/to/new-event \
  --title "学段成长表彰会" --date "2026-09-01" \
  --venue "学校报告厅" --duration-minutes 80

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/import_awards.py \
  --event /absolute/path/to/new-event/event.json \
  --xlsx /absolute/path/to/awards.xlsx

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/build_event.py \
  --event /absolute/path/to/new-event/event.json \
  --theme campus-light   # optional; defaults to event.json visual.theme, then space-gold

python3 /Users/wuyue/.codex/skills/school-awards-ceremony/scripts/validate_event.py \
  --event /absolute/path/to/new-event/event.json

create_event.py scaffolds the event workspace (no runtime site); build_event.py copies the preserved assets/framework/, applies the selected assets/themes/<name>/, injects generated data.js / game-data.js, wires music, and enforces the music_scope rule (e.g. award_only requires the award slot and errors if it is empty). validate_event.py runs the delivery checks.

If the environment provides a bundled Python runtime, prefer it when the default python3 is unavailable. The scripts use only the Python standard library.

Decision Rules

• Preserve confirmed names, counts, award order, and fixed school requirements exactly.
• Let the author decide which segments exist and their order. Translate the list into technical configuration; do not make the author adapt the event to the template.
• Whenever a segment is added, removed, merged, or reordered, set program_confirmation.status back to pending and ask the author to confirm the complete order again.
• Do not reject an author-requested lottery, surprise, announcement, countdown, or other unfamiliar segment merely because no current renderer exists. Record its intended现场动作 and extend the framework before final build.
• Ask only for missing decisions that materially change the event. Record all other gaps in the QA report.
• Ask the author for a visual-system sample before designing the interface. Accept a screenshot, website, slide deck, poster, previous event page, or other concrete reference; ask what to preserve and what to avoid.
• Ask the author what kind of background music they want before selecting tracks. Accept mood words or reference tracks and confirm whether vocals are allowed; "no background music" is a valid confirmed decision.
• Ask whether simulated rehearsal is needed. If no, run the normal technical and delivery checks without requesting a host script.
• If simulated rehearsal is needed, require a host script supplied by the author. Use it as evidence; do not invent missing host lines, including emergency transitions. Mark gaps and ask whether the author wants help drafting them.
• Use the plain term “突发情况演练”, not “故障注入”. Include it only when the author opts in, and select three to five real high-risk situations rather than creating an exhaustive disaster list.
• Continue roster cleanup and factual flow work while creative direction is pending, but do not present a generic theme or arbitrary music choice as a finished design.
• Keep framework, event data, and media separate. Change the framework only when the requested segment cannot be represented by the existing program types.
• Do not package student names, teacher photos, private media, or one-off event data into this skill.
• For an ordinary awards ceremony, use the general workflow only. For a grade-transition or entrance ceremony, also read references/entrance-ceremony-rules.md.
• 屏幕显示的文字与名单以 site/content.json 为现场唯一编辑口（保存即实时生效，需通过 打开仪式页面.command 提供的 http 服务打开）。event.json 只作构建配方；改结构/顺序/媒体/主题走 event.json 后重建，改现场文字/名单直接改 content.json。
• Generate an event package before polishing visual details. A polished screen does not compensate for an incorrect roster or an unworkable run of show.

References

• Read references/workflow.md when planning the activity, assigning roles, or defining deliverables.
• Read references/program-intake.md before creating or changing the program.
• Read references/creative-direction.md before creating the visual system or selecting background music.
• Read references/rehearsal-simulation.md before requesting a host script or preparing role-based rehearsal materials.
• Read references/data-contract.md before changing event.json or adding a program type.
• Read references/qa-checklist.md before rehearsal, delivery, or archive handoff.
• Read references/entrance-ceremony-rules.md only when the ceremony includes a formal grade transition or identity change.

Completion Standard

Finish only when the author has confirmed the complete segment list and order, confirmed or explicitly waived the visual reference, confirmed the background-music decision, answered whether simulated rehearsal is needed, the generated site loads, all referenced media exists, award counts reconcile with source data, no unknown program type remains, rehearsal and live-operation sheets are current, and validation returns no errors. When simulation is requested, also require the author-supplied host script, complete selected-role cues, and current simulation documents.