Skip to content

Latest commit

 

History

History
79 lines (54 loc) · 6.33 KB

PRD.md

File metadata and controls

79 lines (54 loc) · 6.33 KB

Hatch Pet: Public Product Requirements

1. Purpose and status

Hatch Pet is a workflow for producing a coherent animated pet that can be installed in a Codex client supporting the v2 pet format. This repository currently publishes the product requirements only. It does not distribute the private implementation or any completed pet.

The product should turn an owner-approved concept, descriptive prompt, or reference image into an animation package with a traceable review trail. A visually attractive single frame is not sufficient: identity, frame boundaries, movement meaning, transparency, and directional semantics must survive the whole atlas.

2. Audience and use cases

  • Pet owner: creates an original character from text or approved art and reviews the final identity.
  • Maintainer: upgrades an existing compatible pet while preserving approved animation rows.
  • Reviewer: inspects contact sheets, motion previews, and directional poses before packaging.

The first release targets one pet at a time. Batch publishing, public asset galleries, and a hosted upload service are out of scope.

3. Inputs and outputs

Inputs

  • A text concept and optional pet name, description, and style direction.
  • Optional owner-approved visual references or an existing atlas.
  • An explicit declaration that submitted references may be used for generation and that the owner has the necessary rights.

Missing name or description may be inferred from the concept, but the owner can change them before packaging. When no image is provided, the workflow first establishes one canonical character reference.

Outputs

  • A transparent PNG or WebP sprite atlas measuring 1536 x 2288 pixels.
  • An 8-column x 11-row grid of 192 x 208 pixel cells.
  • Nine standard animation rows and 16 clockwise look directions across the last two rows.
  • A pet.json manifest declaring spriteVersionNumber: 2 and referring to the packaged atlas.
  • Review artifacts describing deterministic checks, visual decisions, accepted warnings, and unresolved limitations.

The 8 x 9 atlas used while assembling standard animations is an intermediate, never a final v2 package.

4. Functional requirements

ID Requirement Acceptance signal
HP-01 Establish one canonical visual identity before generating animation rows. Face, silhouette, palette, material, and props remain recognizable across rows.
HP-02 Generate distinct rows for idle, directional drag, waving, jumping, failed, waiting, active task work, and review. Each state conveys its intended meaning in a normal-size loop; no row is silently substituted for another state.
HP-03 Create 16 look poses in clockwise 22.5-degree steps, using approved cardinal directions as anchors. Up, right, down, and left are unambiguous; intermediate directions form a coherent loop.
HP-04 Register generated poses to fixed cells with transparent unused cells. No clipping, cross-cell fragments, accidental interior holes, or hidden color under fully transparent pixels.
HP-05 Validate deterministic atlas and manifest constraints before packaging. Dimensions, row counts, used-cell content, transparency, and v2 manifest validation pass.
HP-06 Provide visual review of standard motion and look directions. Contact sheet and motion previews receive independent review; hard failures block packaging.
HP-07 Preserve provenance and review decisions. The final package can be traced to approved inputs and recorded QA results without exposing private references publicly.
HP-08 Repair the smallest failing coherent row or deterministic assembly step. Approved rows stay intact; one-off generated replacement cells are not mixed into a look row.

5. Direction and state semantics

The first nine rows cover idle, running-right, running-left, waving, jumping, failed, waiting, running, and review. Here, running means active task work, not literal foot-running; directional running is reserved for drag movement.

Look row one spans 0 through 157.5 degrees; look row two spans 180 through 337.5 degrees. Zero degrees means up, not neutral. A no-direction input uses the neutral idle state. Cardinal directions are hard gates. Subtle intermediate uncertainty may be documented as a warning only when ordered-loop review confirms the intended direction and there is no visible reversal.

6. Quality gates

  1. Rights and grounding: all references are owner-approved; every generated row is grounded in the canonical character reference.
  2. Per-row checks: frame boundaries, identity, state meaning, transparent background, and motion cadence are reviewed before final assembly.
  3. Direction checks: cardinal anchors, labeled 16-direction review, continuity inspection, and an independent blind axis check are recorded.
  4. Atlas checks: final geometry, alpha/transparency, used and unused cells, and spriteVersionNumber: 2 are validated deterministically.
  5. Final review: hard visual failures block packaging; any accepted minor warning has a written rationale. A package is not called complete merely because its files exist.

7. Privacy and publication policy

  • Treat personal photos, likenesses, private prompts, customer material, generated pet assets, run logs, local paths, and credentials as private by default.
  • Never copy private reference or generated media into this public repository without a separate rights and privacy decision.
  • Do not publish raw prompts or QA artifacts if they reveal personal information, private source locations, or third-party material.
  • Use synthetic, rights-cleared examples for any future public demonstration.
  • Keep the private skill repository separate; publishing this PRD does not grant permission to publish its scripts or other contents.

8. Release milestones

  • M0: Public specification -- this PRD and a clear status statement.
  • M1: Audited prototype -- reviewed source and synthetic fixtures, with no private assets.
  • M2: Reproducible package flow -- deterministic validators and documented installation.
  • M3: Example gallery -- only consented, rights-cleared sample pets with review evidence.

Each milestone must be reported separately. An internal working skill, a local package, or a passing validator is not evidence that this public repository already ships an implementation or that a pet is installed for users.