yuhaiming/water
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: plan Omen cat Codex pet

Browse Source
This commit is contained in:
yuhaiming
2026-07-16 14:23:35 +08:00
parent 85bc979445
commit 4a4aabf19e
2 changed files with 634 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

538
docs/superpowers/plans/2026-07-16-omen-cat-pet.md Normal file
View File

@@ -0,0 +1,538 @@
# Omen Cat Codex Pet Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build, validate, and locally install a complete Codex v2 animated pet named `幽喵`, grounded in the approved Omen-cat reference and dark character design.
**Architecture:** The installed `hatch-pet` scripts own deterministic layout, extraction, atlas assembly, chroma cleanup, and validation. The installed `imagegen` skill is the only visual generation layer; each visual job runs in an isolated worker and returns one selected source path. The parent copies approved outputs into a durable workspace run, updates the structured job manifest, runs every deterministic gate, and installs only the validated v2 WebP and manifest.
**Tech Stack:** Codex `hatch-pet` skill, Codex `imagegen` skill, bundled Python 3 with Pillow, PowerShell, JSON manifests, PNG/WebP/GIF assets.
## Global Constraints
- Design spec: `D:/code/water/docs/superpowers/specs/2026-07-16-omen-cat-pet-design.md`.
- Canonical source: `C:/Users/admin/AppData/Local/Temp/codex-clipboard-ecce7d4b-e0a8-495f-98ba-9bf2f2d030b4.png`.
- Durable work root: `D:/code/water/tmp/hatch-pet/omen-cat`.
- Run directory: `D:/code/water/tmp/hatch-pet/omen-cat/run`.
- Installed skill directory: `C:/Users/admin/.codex/skills/hatch-pet`.
- Bundled Python: `C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe`.
- Pet id: `youmiao`; display name: `幽喵`; sprite contract: `spriteVersionNumber: 2`.
- Style: dark flat illustration with restrained cel shading; preserve purple cat-eared hood, black void face, three cyan face marks, compact paws, long attached tail, broad armor, and bandage wraps.
- Never add text, logos, weapons, scenery, floor shadows, smoke, particles, detached effects, thin fragments, blur, or bloom.
- Use `imagegen` for every normal visual job. Do not replace missing generated rows with local drawing, tiling, or procedural synthesis.
- The final atlas must be exactly `1536x2288`, based on `192x208` cells, and pass all v2 deterministic and visual gates.
- The dirty repository worktree is user-owned. Stage or commit only the design and plan documents after Git write approval succeeds.
---
### Task 1: Preserve The Reference And Prepare The Run
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/reference/omen-cat-source.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/pet_request.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/imagegen-jobs.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/prompts/**`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/references/layout-guides/**`
**Interfaces:**
- Consumes: the approved design spec and the clipboard PNG.
- Produces: a durable source image, prepared pet request, prompt set, layout guides, and dependency-aware visual job manifest.
- [ ] **Step 1: Verify the temporary source still exists**
Run:
```powershell
Test-Path -LiteralPath 'C:/Users/admin/AppData/Local/Temp/codex-clipboard-ecce7d4b-e0a8-495f-98ba-9bf2f2d030b4.png'
```
Expected: `True`. If it is `False`, stop and ask the user to attach the image again; do not substitute the web-search image.
- [ ] **Step 2: Copy the source into the durable work root**
Run:
```powershell
New-Item -ItemType Directory -Force -Path 'D:/code/water/tmp/hatch-pet/omen-cat/reference'
Copy-Item -LiteralPath 'C:/Users/admin/AppData/Local/Temp/codex-clipboard-ecce7d4b-e0a8-495f-98ba-9bf2f2d030b4.png' -Destination 'D:/code/water/tmp/hatch-pet/omen-cat/reference/omen-cat-source.png'
Get-FileHash -Algorithm SHA256 -LiteralPath 'D:/code/water/tmp/hatch-pet/omen-cat/reference/omen-cat-source.png'
```
Expected: the destination exists and `Get-FileHash` prints one SHA-256 value.
- [ ] **Step 3: Prepare the hatch-pet run**
Run:
```powershell
$PYTHON = 'C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe'
$SKILL_DIR = 'C:/Users/admin/.codex/skills/hatch-pet'
& $PYTHON "$SKILL_DIR/scripts/prepare_pet_run.py" --pet-name '幽喵' --pet-id 'youmiao' --display-name '幽喵' --description '一只披着暗紫幽影兜帽、以冷青面纹观察任务的沉静猫形伙伴。' --reference 'D:/code/water/tmp/hatch-pet/omen-cat/reference/omen-cat-source.png' --output-dir 'D:/code/water/tmp/hatch-pet/omen-cat/run' --pet-notes 'Dark Omen-inspired cartoon cat; oversized angular purple cat-eared hood; black void face with three cyan energy marks; compact feline body; broad charcoal armor and bandage wraps; long attached tail; no weapons, logos, text, scenery, shadows, smoke, particles, detached effects, blur, or bloom.' --style-preset 'flat-vector' --style-notes 'Dark flat illustration with restrained cel shading, broad readable armor shapes, crisp opaque cyan marks, compact sprite-safe silhouette.' --force
```
Expected: exit code `0`; the run contains `pet_request.json`, `imagegen-jobs.json`, prompts, and layout guides.
- [ ] **Step 4: Verify prepared identity and v2 job graph**
Run:
```powershell
$request = Get-Content -Raw -LiteralPath 'D:/code/water/tmp/hatch-pet/omen-cat/run/pet_request.json' | ConvertFrom-Json
$jobs = Get-Content -Raw -LiteralPath 'D:/code/water/tmp/hatch-pet/omen-cat/run/imagegen-jobs.json' | ConvertFrom-Json
$request | Select-Object pet_id, display_name, description, chroma_key
$jobs.jobs | Select-Object id, kind, status, depends_on, output_path
```
Expected: `pet_id` is `youmiao`; display name is `幽喵`; jobs include `base`, all nine standard states, `look-cardinals`, `look-row-9`, and `look-row-10`.
- [ ] **Step 5: Checkpoint the design documents when Git approval is available**
Run only after Git write approval succeeds:
```powershell
git add -- docs/superpowers/specs/2026-07-16-omen-cat-pet-design.md docs/superpowers/plans/2026-07-16-omen-cat-pet.md
git commit -m "docs: plan Omen cat Codex pet"
```
Expected: one commit containing only the two documentation files. If the approval service still returns `404`, record the environment blocker and continue the asset run without staging unrelated files.
---
### Task 2: Generate And Approve The Canonical Base
**Files:**
- Consume: `D:/code/water/tmp/hatch-pet/omen-cat/run/prompts/base-pet.md`
- Consume: `D:/code/water/tmp/hatch-pet/omen-cat/run/imagegen-jobs.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/base.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/references/canonical-base.png`
**Interfaces:**
- Consumes: the durable Omen-cat source with the role recorded in the base job.
- Produces: one approved full-body chroma-key base that every row worker uses as the identity source of truth.
- [ ] **Step 1: Dispatch one isolated base worker**
Give the worker exactly this task, with every `input_images` entry from the `base` manifest job attached and role-labeled:
```text
Generate the hatch-pet base image.
Run dir: D:/code/water/tmp/hatch-pet/omen-cat/run
Job id: base
Prompt file: D:/code/water/tmp/hatch-pet/omen-cat/run/prompts/base-pet.md
Use imagegen only. Preserve the canonical reference's purple cat-eared hood, black void face, three cyan marks, compact feline paws, and attached tail. Apply the approved darker layered mantle and broad bandage armor. Return one centered full-body pet on the exact flat chroma background with no text, scenery, shadows, smoke, particles, detached effects, blur, or bloom.
Return exactly two lines. The first line starts with `selected_source=` followed by the absolute PNG path produced by imagegen. The second starts with `qa_note=` followed by one sentence confirming the visible identity and background checks.
```
Expected: exactly two output lines and a visually coherent single pet.
- [ ] **Step 2: Copy the selected file and establish canonical identity**
Copy the exact `selected_source` returned by the worker to both paths below; do not transform it:
```text
D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/base.png
D:/code/water/tmp/hatch-pet/omen-cat/run/references/canonical-base.png
```
Expected: both files exist and have identical SHA-256 hashes.
- [ ] **Step 3: Validate the base visually before marking it complete**
Require all of the following: one centered whole body, both cat ears readable, three cyan face marks in the correct arrangement, complete paws and tail, broad attached armor, flat uniform key background, and no forbidden effects. Reject identity drift or a cropped tail.
Expected: a pass note grounded in visible identity landmarks.
- [ ] **Step 4: Mark only `base` complete in the JSON manifest**
Update the `base` object in `imagegen-jobs.json` with `status: "complete"`, the exact `source_path`, and an ISO-8601 UTC `completed_at`. Preserve every other job and field.
Expected: `idle` and `running-right` become dependency-ready; no other visual job is marked complete.
---
### Task 3: Generate And Incrementally Validate Standard Rows
**Files:**
- Consume: `D:/code/water/tmp/hatch-pet/omen-cat/run/prompts/rows/*.md`
- Consume: `D:/code/water/tmp/hatch-pet/omen-cat/run/references/layout-guides/*.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/{idle,running-right,running-left,waving,jumping,failed,waiting,running,review}.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/rows/*/review.json`
**Interfaces:**
- Consumes: the canonical base and each job's exact manifest-listed inputs.
- Produces: nine separately approved row strips with deterministic frame-extraction evidence.
- [ ] **Step 1: Generate `idle` and `running-right` in parallel isolated workers**
Use one worker per job. Each worker reads its exact prompt and retry prompt, attaches every manifest input image, and returns only `selected_source` plus `qa_note`.
Expected: `idle` has visible micro-variation; `running-right` faces screen-right and visibly alternates its gait without dust, speed lines, or shadow.
- [ ] **Step 2: Copy and validate each selected row before manifest completion**
For each copied row, run:
```powershell
$PYTHON = 'C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe'
$SKILL_DIR = 'C:/Users/admin/.codex/skills/hatch-pet'
$RUN_DIR = 'D:/code/water/tmp/hatch-pet/omen-cat/run'
$JOB_ID = 'idle'
& $PYTHON "$SKILL_DIR/scripts/extract_strip_frames.py" --decoded-dir "$RUN_DIR/decoded" --output-dir "$RUN_DIR/qa/rows/$JOB_ID/frames" --states $JOB_ID --method auto
& $PYTHON "$SKILL_DIR/scripts/inspect_frames.py" --frames-root "$RUN_DIR/qa/rows/$JOB_ID/frames" --json-out "$RUN_DIR/qa/rows/$JOB_ID/review.json" --states $JOB_ID --require-components
```
Repeat with `$JOB_ID = 'running-right'`, then later with each remaining standard row id.
Expected: both commands exit `0`; review JSON has no errors. Inspect warnings before acceptance.
- [ ] **Step 3: Decide whether `running-left` can be mirrored**
Mirror only when hood, cyan marks, armor, bandage wraps, tail construction, and cel lighting are symmetrical and retain their meaning after flipping. When safe, run:
```powershell
& 'C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe' 'C:/Users/admin/.codex/skills/hatch-pet/scripts/derive_running_left_from_running_right.py' --run-dir 'D:/code/water/tmp/hatch-pet/omen-cat/run' --confirm-appropriate-mirror --decision-note 'The approved base and running-right row use symmetric face marks, armor, wraps, tail construction, and cel lighting; per-frame mirroring preserves identity and temporal order.'
```
If any listed feature is asymmetric, dispatch a normal `running-left` imagegen worker instead.
Expected: `running-left` faces screen-left, preserves frame timing, and passes its incremental frame inspection.
- [ ] **Step 4: Generate the remaining six rows with up to three workers active**
Jobs: `waving`, `jumping`, `failed`, `waiting`, `running`, and `review`. Backfill a worker slot as soon as another job becomes dependency-ready.
Expected state gates:
- `waving`: forepaw gesture only; no wave marks.
- `jumping`: body-height motion only; no floor cue.
- `failed`: lowered ears, dimmed cyan marks, inward tail; no floating symbols.
- `waiting`: expectant, alert pose distinct from idle.
- `running`: focused task activity without literal locomotion.
- `review`: narrowed marks and deliberate head tilt without new props.
- [ ] **Step 5: Copy, inspect, and complete each remaining row individually**
After each source is copied, run the same `extract_strip_frames.py` and `inspect_frames.py` pair with that row's exact id. Mark a job complete only after deterministic inspection and visual state review pass.
Expected: all nine standard jobs are `complete`; every per-row review JSON has no errors.
---
### Task 4: Assemble And Review The Standard Atlas
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/frames/**`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/review.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/final/spritesheet.webp`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/contact-sheet.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/previews/*.gif`
**Interfaces:**
- Consumes: nine approved standard strips.
- Produces: the reviewed intermediate 8x9 atlas and motion evidence required before look-direction generation.
- [ ] **Step 1: Extract all standard frames and inspect them together**
Run:
```powershell
$PYTHON = 'C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe'
$SKILL_DIR = 'C:/Users/admin/.codex/skills/hatch-pet'
$RUN_DIR = 'D:/code/water/tmp/hatch-pet/omen-cat/run'
New-Item -ItemType Directory -Force -Path "$RUN_DIR/final", "$RUN_DIR/qa"
& $PYTHON "$SKILL_DIR/scripts/extract_strip_frames.py" --decoded-dir "$RUN_DIR/decoded" --output-dir "$RUN_DIR/frames" --states all --method auto
& $PYTHON "$SKILL_DIR/scripts/inspect_frames.py" --frames-root "$RUN_DIR/frames" --json-out "$RUN_DIR/qa/review.json" --require-components
```
Expected: exit code `0` and no errors in `qa/review.json`.
- [ ] **Step 2: Compose the intermediate atlas, contact sheet, and previews**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/compose_atlas.py" --frames-root "$RUN_DIR/frames" --output "$RUN_DIR/final/spritesheet.png" --webp-output "$RUN_DIR/final/spritesheet.webp"
& $PYTHON "$SKILL_DIR/scripts/make_contact_sheet.py" "$RUN_DIR/final/spritesheet.webp" --output "$RUN_DIR/qa/contact-sheet.png"
& $PYTHON "$SKILL_DIR/scripts/render_animation_previews.py" --frames-root "$RUN_DIR/frames" --output-dir "$RUN_DIR/qa/previews"
```
Expected: an intermediate `1536x1872` atlas, contact sheet, and one preview per standard state.
- [ ] **Step 3: Run standard visual review**
Inspect the contact sheet and all GIFs for identity drift, cropped parts, reversed or static gait, wrong facing, size popping, and incorrect state semantics. Key-color fringe is not a failure at this stage.
Expected: all nine rows pass. If extraction alone causes popping and source strips are stable, rerun extraction with `--method stable-slots`, then rerun inspection with `--allow-stable-slots`, atlas composition, contact sheet, and previews.
---
### Task 5: Define Look Mechanics And Approve Cardinal Anchors
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/look-mechanics.md`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/look-cardinals.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/look-anchors/{000,090,180,270}.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/look-anchors-approved.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/cardinal-anchors.json`
**Interfaces:**
- Consumes: approved standard contact sheet, canonical base, and design look mechanics.
- Produces: four semantically approved direction anchors in fixed order: up, screen-right, down, screen-left.
- [ ] **Step 1: Write the pet-specific look mechanics note**
Use this exact decision:
```markdown
# Look Mechanics
The paws and lower torso remain anchored. The three cyan face marks lead the gaze inside the black face plane; the hood opening and head turn follow. Cat ears tilt with restrained follow-through. The layered mantle and attached tail lag by one small visual step without changing attachment points. Screen-left and screen-right require the hood opening and face plane to turn visibly, not only the cyan marks. Up and down combine face-mark placement, hood pitch, ear angle, and upper-body compression. The complete sprite never rotates, skews, or tilts to fake direction.
```
Expected: `qa/look-mechanics.md` exists before cardinal generation.
- [ ] **Step 2: Generate the four-cardinal strip in one isolated worker**
The worker reads the cardinal prompt and `qa/look-mechanics.md`, attaches all manifest inputs, and returns only `selected_source` plus a landmark-based `qa_note` covering `000`, `090`, `180`, and `270`.
Expected: four separated poses in that order; `090` unmistakably points to the viewer's right and `270` to the viewer's left.
- [ ] **Step 3: Extract and compose approved anchors**
Run:
```powershell
$request = Get-Content -Raw -LiteralPath "$RUN_DIR/pet_request.json" | ConvertFrom-Json
$CHROMA_KEY = $request.chroma_key.hex
& $PYTHON "$SKILL_DIR/scripts/extract_cardinal_anchors.py" --strip "$RUN_DIR/decoded/look-cardinals.png" --output-dir "$RUN_DIR/decoded/look-anchors" --chroma-key $CHROMA_KEY --json-out "$RUN_DIR/qa/cardinal-anchors.json"
& $PYTHON "$SKILL_DIR/scripts/compose_cardinal_anchor_strip.py" --anchors-dir "$RUN_DIR/decoded/look-anchors" --output "$RUN_DIR/decoded/look-anchors-approved.png"
```
Expected: extraction report passes and all four anchor files are complete and unclipped.
- [ ] **Step 4: Approve cardinal semantics before row 9**
Inspect all four at normal pet size. For left/right, record the cyan marks and hood opening relative to head center; for up/down, record vertical mark placement, hood pitch, and ear angle.
Expected: all four pass. If one fails, regenerate only that cardinal anchor with its prepared repair prompt, recompose the approved strip, and repeat semantic review.
---
### Task 6: Generate, Register, And Approve Look Row 9
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/look-row-9.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/look-row-9-registered.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/look-row-9-registration.json`
**Interfaces:**
- Consumes: approved cardinal strip, canonical base, standard contact sheet, layout guide, and look mechanics.
- Produces: eight registered poses for `000` through `157.5` with one shared scale and baseline.
- [ ] **Step 1: Generate row 9 as one coherent eight-pose family**
The isolated worker uses the manifest prompt and retry prompt plus every listed input. It must synthesize exactly `000, 022.5, 045, 067.5, 090, 112.5, 135, 157.5` in order.
Expected: eight separated pose groups, no overlap or outer clipping, stable identity, and evenly progressing head, marks, ears, mantle, and tail.
- [ ] **Step 2: Register row 9 using the final assembly transform**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/assemble_extended_atlas.py" --base-atlas "$RUN_DIR/final/spritesheet.webp" --look-row-9 "$RUN_DIR/decoded/look-row-9.png" --neutral-cell "$RUN_DIR/frames/idle/00.png" --chroma-key $CHROMA_KEY --chroma-threshold 96 --registered-row-output "$RUN_DIR/qa/look-row-9-registered.png" --registration-manifest-output "$RUN_DIR/qa/look-row-9-registration.json"
```
Expected: deterministic pose recovery, registration, and post-registration edge checks pass.
- [ ] **Step 3: Review row-9 semantics and adjacent continuity**
Inspect all eight registered cells at normal pet size. Require correct quadrants, stable paws and lower torso, continuous hood and face-mark motion, and attached mantle and tail.
Expected: no hard semantic or continuity failure. Regenerate the complete row for a wrong quadrant, reversal, conspicuous snap, identity drift, or broken attachment.
- [ ] **Step 4: Mark `look-row-9` complete**
Update only the row-9 manifest object with its exact source path and completion timestamp.
Expected: `look-row-10` becomes ready only after this completion.
---
### Task 7: Generate Row 10 And Assemble The V2 Atlas
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/decoded/look-row-10.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/final/spritesheet-extended.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/final/spritesheet-extended.webp`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/final/spritesheet-extended.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/chroma-despill-extended.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/final/validation-extended.json`
**Interfaces:**
- Consumes: approved cardinals, completed row 9, row-9 registration, and standard atlas.
- Produces: the cleaned, validated `1536x2288` v2 atlas.
- [ ] **Step 1: Generate row 10 as one coherent eight-pose family**
The isolated worker must attach the approved cardinal strip and completed row 9 and generate exactly `180, 202.5, 225, 247.5, 270, 292.5, 315, 337.5` in order.
Expected: `180` continues one even step after `157.5`, and `337.5` lands one even step before the row-9 `000` pose.
- [ ] **Step 2: Assemble the complete v2 atlas**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/assemble_extended_atlas.py" --base-atlas "$RUN_DIR/final/spritesheet.webp" --registered-row-9 "$RUN_DIR/qa/look-row-9-registered.png" --row-9-registration "$RUN_DIR/qa/look-row-9-registration.json" --look-row-10 "$RUN_DIR/decoded/look-row-10.png" --neutral-cell "$RUN_DIR/frames/idle/00.png" --chroma-key $CHROMA_KEY --chroma-threshold 96 --output "$RUN_DIR/final/spritesheet-extended.png" --webp-output "$RUN_DIR/final/spritesheet-extended.webp" --manifest-output "$RUN_DIR/final/spritesheet-extended.json"
```
Expected: eight row-10 pose groups are recovered under the persisted row-9 scale and all normalized-cell edge checks pass.
- [ ] **Step 3: Run the single authoritative chroma cleanup pass**
Run exactly once:
```powershell
& $PYTHON "$SKILL_DIR/scripts/despill_chroma_edges.py" "$RUN_DIR/final/spritesheet-extended.png" --output "$RUN_DIR/final/spritesheet-extended.png" --webp-output "$RUN_DIR/final/spritesheet-extended.webp" --chroma-key $CHROMA_KEY --json-out "$RUN_DIR/qa/chroma-despill-extended.json"
```
Expected: `qa/chroma-despill-extended.json` has `ok: true`. Do not run a second cleanup pass.
- [ ] **Step 4: Validate the v2 atlas contract**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/validate_atlas.py" "$RUN_DIR/final/spritesheet-extended.webp" --json-out "$RUN_DIR/final/validation-extended.json" --chroma-key $CHROMA_KEY --require-v2
```
Expected: exit code `0`, dimensions `1536x2288`, used cells non-empty, unused cells transparent, and no opaque chroma-key errors.
---
### Task 8: Run Direction QA And Final Visual Review
**Files:**
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/contact-sheet-extended.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/look-directions.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-blind-pairs.png`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-blind-answer-key.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-blind-verdicts-{1,2,3}.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-blind-verdicts.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-blind-validation.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/look-continuity.json`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/direction-semantics.json`
**Interfaces:**
- Consumes: the finalized v2 atlas plus standard previews and validation reports.
- Produces: independent blind evidence, labeled per-direction semantics, continuity evidence, and final visual acceptance.
- [ ] **Step 1: Create final review media**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/make_contact_sheet.py" "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/contact-sheet-extended.png"
& $PYTHON "$SKILL_DIR/scripts/make_direction_qa_sheet.py" "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/look-directions.png"
& $PYTHON "$SKILL_DIR/scripts/make_direction_blind_qa_sheet.py" "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/direction-blind-pairs.png" --answer-key "$RUN_DIR/qa/direction-blind-answer-key.json"
& $PYTHON "$SKILL_DIR/scripts/measure_direction_continuity.py" "$RUN_DIR/final/spritesheet-extended.webp" --json-out "$RUN_DIR/qa/look-continuity.json"
```
Expected: all four commands exit `0` and create their declared outputs.
- [ ] **Step 2: Dispatch three fresh isolated blind reviewers**
Each reviewer receives only `qa/direction-blind-pairs.png`, never the atlas, prompt, degree order, labeled sheet, hidden key, or another verdict. Each returns exactly one JSON object classifying every shown A/B pair on the named horizontal or vertical axis.
Expected: three separate valid verdict files with all pairs present.
- [ ] **Step 3: Combine and validate blind verdicts**
Run:
```powershell
& $PYTHON "$SKILL_DIR/scripts/combine_direction_blind_verdicts.py" --verdicts "$RUN_DIR/qa/direction-blind-verdicts-1.json" --verdicts "$RUN_DIR/qa/direction-blind-verdicts-2.json" --verdicts "$RUN_DIR/qa/direction-blind-verdicts-3.json" --json-out "$RUN_DIR/qa/direction-blind-verdicts.json"
& $PYTHON "$SKILL_DIR/scripts/validate_direction_blind_verdicts.py" --answer-key "$RUN_DIR/qa/direction-blind-answer-key.json" --verdicts "$RUN_DIR/qa/direction-blind-verdicts.json" --json-out "$RUN_DIR/qa/direction-blind-validation.json"
```
Expected: `direction-blind-validation.json` has `ok: true`; both cardinal pairs pass. Intermediate warnings proceed to labeled review.
- [ ] **Step 4: Run one independent final visual QA worker**
The worker inspects the standard and extended contact sheets, all standard GIFs, focused direction sheet, blind validation, continuity JSON, frame review JSON, and v2 validation. It must report all 16 direction verdicts and concrete horizontal/vertical evidence.
Expected: `visual_qa=pass`, no repair rows, and no wrong or ambiguous cardinal.
- [ ] **Step 5: Persist all 16 labeled semantic verdicts**
Write `qa/direction-semantics.json` as structured JSON with one entry for each exact label: `000`, `022.5`, `045`, `067.5`, `090`, `112.5`, `135`, `157.5`, `180`, `202.5`, `225`, `247.5`, `270`, `292.5`, `315`, and `337.5`. Every entry contains `verdict`, `expected`, `observed`, and `reason` from the independent worker.
Expected: no `fail` verdict. A `warning` is allowed only for an intermediate direction whose labeled loop remains coherent.
- [ ] **Step 6: Resolve failures at row scope**
For a major failure, regenerate the smallest complete failing row, then repeat that row's deterministic checks and all downstream assembly and QA. Never patch an individual final look cell. For a minor intermediate blind disagreement, record an accepted evidence-based resolution in `qa/blind-review-resolution.json` only when labeled review confirms the correct quadrant and continuity.
Expected: all hard gates pass before packaging.
---
### Task 9: Install The Pet And Retain QA Evidence
**Files:**
- Create outside workspace: `C:/Users/admin/.codex/pets/youmiao/pet.json`
- Create outside workspace: `C:/Users/admin/.codex/pets/youmiao/spritesheet.webp`
- Create: `D:/code/water/tmp/hatch-pet/omen-cat/run/qa/run-summary.json`
**Interfaces:**
- Consumes: the fully validated extended WebP and all required QA reports.
- Produces: one locally installed Codex v2 pet and a durable run summary.
- [ ] **Step 1: Request the required out-of-workspace write approval**
Request approval specifically for creating `C:/Users/admin/.codex/pets/youmiao` and writing only `pet.json` plus `spritesheet.webp` there.
Expected: explicit approval before any installation write.
- [ ] **Step 2: Install the validated WebP and manifest**
After approval, run:
```powershell
$PET_DIR = 'C:/Users/admin/.codex/pets/youmiao'
New-Item -ItemType Directory -Force -Path $PET_DIR
Copy-Item -LiteralPath 'D:/code/water/tmp/hatch-pet/omen-cat/run/final/spritesheet-extended.webp' -Destination "$PET_DIR/spritesheet.webp"
$petManifest = [ordered]@{ id = 'youmiao'; displayName = '幽喵'; description = '一只披着暗紫幽影兜帽、以冷青面纹观察任务的沉静猫形伙伴。'; spriteVersionNumber = 2; spritesheetPath = 'spritesheet.webp' }
$petManifest | ConvertTo-Json | Set-Content -Encoding utf8 -LiteralPath "$PET_DIR/pet.json"
```
Expected: both files exist together and `pet.json` declares `spriteVersionNumber: 2`.
- [ ] **Step 3: Validate the installed copy**
Run:
```powershell
& 'C:/Users/admin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/python.exe' 'C:/Users/admin/.codex/skills/hatch-pet/scripts/validate_atlas.py' 'C:/Users/admin/.codex/pets/youmiao/spritesheet.webp' --json-out 'D:/code/water/tmp/hatch-pet/omen-cat/run/final/validation-installed.json' --chroma-key $CHROMA_KEY --require-v2
Get-Content -Raw -LiteralPath 'C:/Users/admin/.codex/pets/youmiao/pet.json' | ConvertFrom-Json | Select-Object id, displayName, spriteVersionNumber, spritesheetPath
```
Expected: validation passes; printed values are `youmiao`, `幽喵`, `2`, and `spritesheet.webp`.
- [ ] **Step 4: Write the run summary and clean disposable intermediates**
Write `qa/run-summary.json` with `ok: true`, `spriteVersionNumber: 2`, and absolute paths for the run, spritesheet, validation, despill report, contact sheet, direction sheet, semantics, blind validation, continuity, review, and installed package.
Keep the source copy, `pet_request.json`, final WebP, final and installed validation JSON, chroma report, extended contact sheet, focused direction sheet, direction semantics, blind sheets/verdicts/validation, continuity report, standard GIF previews, frame review, and run summary. Remove prompts, layout guides, decoded row strips, extracted frames, PNG intermediates, 8x9 atlas, and job manifest only after installation and summary validation pass.
Expected: the installed pet remains intact and the retained QA set is sufficient to audit every acceptance gate.
- [ ] **Step 5: Final completion report**
Report the installed pet directory, retained run directory, final atlas dimensions, manifest version, deterministic validation result, blind cardinal result, final visual QA result, and any accepted intermediate warnings.
Expected: no completion claim without fresh passing evidence from the installed copy.

96
docs/superpowers/specs/2026-07-16-omen-cat-pet-design.md Normal file
View File

@@ -0,0 +1,96 @@
# Omen Cat Codex Pet Design
## Goal
Create a Codex-compatible v2 animated pet inspired by the user-provided cartoon Omen cat reference. The pet should preserve the reference's feline silhouette and recognizable Omen cues while moving toward a darker, more detailed game-character interpretation that remains readable in a `192x208` sprite cell.
The working display name is `幽喵`. The package id will use an ASCII-safe derivative chosen by the hatch pipeline.
## Source Reference
Canonical input:
`C:/Users/admin/AppData/Local/Temp/codex-clipboard-ecce7d4b-e0a8-495f-98ba-9bf2f2d030b4.png`
The source is an identity reference, not an atlas. It must be copied into the pet run before generation so the temporary clipboard path is not a long-term dependency.
## Visual Direction
Use a dark flat-illustration style with restrained cel shading. Preserve these identity invariants across every animation row:
- oversized purple cat-eared hood with a layered, angular Omen silhouette
- black void face framed by the hood
- three cyan facial energy marks, with the center mark slightly longer
- compact feline body, short paws, and a long attached tail
- dark charcoal armor and bandage-like limb wraps
- deep violet, charcoal, cool gray, and luminous cyan palette
- heavy upper silhouette balanced by a compact grounded lower body
Compared with the source, add a segmented shoulder mantle, layered scarf or short cape panels, and readable foreleg wraps. Keep all added armor broad and simple enough to survive reduction to pet size.
Do not include readable logos, text, weaponry, scenery, floor shadows, smoke, floating particles, detached energy effects, or thin decorative fragments. Cyan glow should be represented by opaque hard-edged color shapes rather than blur or bloom.
## Animation Language
The standard animation rows follow the Codex v2 contract:
- `idle`: subtle breathing, ear twitch, and slow tail sway
- `running-right` and `running-left`: low feline dash with alternating paws and cape follow-through
- `waving`: one forepaw wave without motion marks
- `jumping`: compact crouch, lift, apex, and landing pose without a floor cue
- `failed`: ears lower, cyan face marks dim, body slumps, and tail curls inward
- `waiting`: alert seated pose with raised ears and an expectant head angle
- `running`: focused task pose using quick paw and eye activity, not literal locomotion
- `review`: narrowed cyan marks, deliberate head tilt, and restrained paw movement
`running-left` may be derived from `running-right` only when the generated armor, face marks, and lighting are fully symmetrical. Otherwise it must be generated independently.
## Look Mechanics
The body base and paws remain anchored. Direction is carried by a coordinated motion family:
1. The cyan face marks lead and shift within the black face plane.
2. The hood opening and head turn follow the target direction.
3. The cat ears tilt with restrained follow-through.
4. The upper mantle and tail lag slightly while remaining attached.
Cardinal directions must be unmistakable at normal pet size. Left and right require visible head and hood-opening turns, not only moving the cyan marks. Up and down use face-mark position, hood pitch, ear angle, and upper-body compression. Intermediate directions interpolate continuously without rotating or tilting the complete sprite.
## Production Flow
The `hatch-pet` workflow owns production:
1. Copy the canonical source into a durable run directory and prepare prompts plus layout guides.
2. Generate a grounded base image through `imagegen`.
3. Generate and incrementally validate all nine standard animation rows.
4. Define the final look-mechanics note, generate four cardinal anchors, and approve their semantics.
5. Generate coherent look rows 9 and 10 with deterministic registration and edge checks.
6. Assemble the `1536x2288` v2 atlas, remove the chroma key once, and validate the final WebP.
7. Run contact-sheet review, motion previews, three isolated blind direction reviews, labeled direction semantics, and continuity review.
8. Install `pet.json` and `spritesheet.webp` together with `spriteVersionNumber: 2`.
Generated row strips are always grounded by the canonical reference and the relevant layout guide. Repairs replace the smallest failed complete row rather than patching individual cells.
## Failure Handling
- Identity drift, missing cat features, replacement face marks, or materially changed armor require row regeneration.
- Clipping, extraction, registration, and chroma failures use deterministic corrections first.
- A wrong or ambiguous cardinal direction blocks packaging.
- Minor intermediate-direction uncertainty may be accepted only when labeled normal-size review confirms the intended quadrant and the ordered loop remains coherent.
- Detached effects, accidental transparent body holes, reversed gait, visible size popping, or broken tail attachment are hard failures.
## Acceptance Criteria
- The final pet visibly matches the source cat and the selected dark Omen interpretation.
- All nine standard animation rows communicate their intended state without text or detached effects.
- All 16 look directions form a continuous clockwise family with unmistakable cardinals.
- The final atlas is exactly `1536x2288`; used cells are non-empty and unused cells are transparent.
- Deterministic atlas validation, chroma despill validation, frame inspection, direction blind review, semantic review, continuity review, and final visual QA pass.
- The installed manifest declares `spriteVersionNumber: 2` and points to the packaged `spritesheet.webp`.
## Out Of Scope
- Reproducing an exact in-game model or official Riot asset
- Adding weapons, readable VALORANT branding, UI, or game environments
- Creating alternate skins or multiple pet variants in this run
- Publishing or distributing the resulting pet outside the local Codex installation