Pet product specification

Document version	Date	Summary
v1	2026-07-17	Initial product specification

Status: Draft

Working name: Pet

Document purpose: This document defines the product vision, behaviour, scope, and product requirements. Technical structure and API design belong in the general architecture.

1. Product overview

Pet is a calm virtual companion that lives alongside the user. It provides a small and persistent presence that reacts to time, direct interaction, its environment, and optional real world activities.

The product is not intended to recreate the maintenance loop of a traditional virtual pet. The pet does not die, become permanently ill, or punish the user for being absent. It should make ordinary routines feel warmer without becoming another source of obligation, guilt, or unwanted notifications.

The pet and its world are defined by the Pet Core. Desktop applications, physical devices, mobile applications, and web applications may present the same product through different frontends. Hardware is one possible home for the pet. It is not the definition of the product.

The words pet and companion may both be used in product language. Pet is the primary domain term and is expected to be the basis of C identifiers and public API prefixes.

2. Product vision

The product should feel like a quiet character sharing the user’s day.

It should be:

• present without constantly requesting interaction
• expressive without using distress to drive engagement
• encouraging without judging productivity
• useful without becoming a task manager
• personal without requiring invasive data collection
• capable of developing a distinct identity over time
• suitable for software and physical frontends

The central product promise is:

The pet makes the user’s life a little nicer instead of asking the user to maintain it.

3. Core principles

SPEC-PR-001: companion, not obligation

The user must be able to leave the product for any length of time without permanent loss, punishment, illness, or damage to the relationship.

SPEC-PR-002: real life comes first

The product should support real world activity instead of competing with it. In product rewards may acknowledge focus, movement, reading, rest, or creative work. Constant engagement must not be treated as the main measure of success.

SPEC-PR-003: calm by default

The default experience must avoid attention seeking notifications, urgent warnings, streak pressure, and artificial scarcity. Any reminder capability introduced later must be optional and controlled by the user.

SPEC-PR-004: no punitive survival mechanics

The pet must not die, starve, become permanently ill, or suffer comparable harm because the user was absent. Temporary expressions such as sleepy, curious, calm, playful, dizzy, or surprised may communicate its current experience without acting as failure states.

SPEC-PR-005: positive and non judgemental feedback

The product may celebrate completed activities but must not shame the user for inactivity. Rest and quiet days are valid parts of life.

SPEC-PR-006: local ownership

Core pet behaviour and local persistence must work without a network connection. The authoritative pet data should remain under the user’s control. Accounts, cloud services, device transfer, and synchronisation are not required for the initial product.

SPEC-PR-007: one core and multiple frontends

Pet behaviour must not be defined by SDL, a display type, a mobile operating system, or a specific microcontroller. Frontends may differ in presentation and input capabilities while preserving the same domain rules.

SPEC-PR-008: identity through shared history

The pet should develop a distinct identity through time, interaction, formative events, and shared activities. Development should create attachment and visible history without creating a competitive level system.

SPEC-PR-009: AI is optional

The initial product must provide a meaningful companion experience without generative AI. Any future AI capability must remain optional and must not replace deterministic core behaviour or local ownership.

SPEC-PR-010: respectful product design

The product must not depend on advertisements, manipulative engagement loops, hidden behavioural profiling, or randomised real money rewards.

4. Target users

4.1 Primary users

The primary audience is people who want a small digital presence during everyday life but do not want the responsibility associated with a traditional virtual pet.

This may include students, developers, remote workers, readers, and other users whose days contain periods of focused work and quiet routine.

Primary users may value:

• a calm desktop or desk companion
• gentle acknowledgement of daily activities
• short interactions that do not interrupt work
• a character that becomes more personal over time
• a product that remains useful without a subscription or constant connection

4.2 Secondary users

A later secondary audience may include makers and developers who want to create custom frontends, sensors, activity integrations, or other adapters.

The product may eventually expose a plugin or adapter system. Its distribution and commercial model are undecided. The system may be open source, partly open, or distributed through another model. These decisions must not restrict the initial product design before the product value has been validated.

Supporting developers must not make the ordinary user experience unnecessarily technical.

5. Core experience

5.1 Ambient presence

The pet exists even when the user is not actively interacting with it. It may sleep, read, look around, play, observe its environment, or perform other small autonomous behaviours.

Ambient behaviour should make the pet feel present without demanding a response.

5.2 Brief direct interaction

The user may perform small actions such as greeting the pet, petting it, selecting an activity, giving it an owned item, or navigating a menu.

Essential interactions should remain possible on devices with a small number of buttons. A keyboard, pointer, touch screen, or network connection must not be required by the core interaction model.

5.3 Shared real world activity

The user may start or record an optional real world activity. The pet may accompany the activity or respond to its completion.

Examples include:

• reading quietly during a focus session
• finding a small object after a walk
• reacting to recorded reading activity
• acknowledging creative or development work
• resting with the user on a quiet day

Some activities may be entered manually. Others may arrive through adapters such as a Git hook, a mobile activity source, an ebook service, or a local application.

The Core must not depend on the original data source. Adapters translate external information into product level events that the Core understands.

5.4 Long term continuity

The pet retains its identity and relevant history between sessions. Progress should create variety, memories, preferences, habits, appearance details, and new behaviour.

The pet may gain lasting characteristics through formative events. Examples include:

• a small scar from an adventure
• a notch in one ear
• a favourite sleeping position
• a distinctive greeting
• a preference for reading or exploring
• a souvenir associated with a shared activity
• a new expression linked to a memory

These changes represent history rather than damage or statistical superiority. One pet may become bookish while another becomes adventurous or cosy. Neither pet is more valuable or more complete.

Important memories remain part of the pet’s history. Visual marks and cosmetic details should be controllable when permanent presentation would prevent the user from enjoying the pet’s appearance.

5.5 Bounded development

The pet may grow and mature, but it must not continue growing until it loses its intended visual character. It must not become elderly as part of normal progression.

Development may include a small number of stages. Physical size changes should remain limited. Most development should appear through richer behaviour, expressions, preferences, memories, marks, and interactions with the environment.

Development must not regress because of inactivity. The user’s contribution should be visible through shared history rather than through maintenance of a growth meter.

6. Product model

6.1 Pet identity

The pet is a persistent character with its own identity. Its identity belongs to its saved state rather than to a renderer, display, or physical device.

The product should distinguish between:

• stable identity such as name, appearance basis, and creation time
• current state such as activity, expression, and location
• lasting development such as maturity, traits, habits, and visual marks
• shared history such as memories and formative events
• progression such as discovered content and available interactions
• presentation chosen by the active frontend

Presentation must not be the authoritative source of pet state.

6.2 Mood and expression

Mood provides personality and behavioural variety. It must not conceal a health, survival, or neglect meter.

Mood may be influenced by:

• time of day
• recent interaction
• current activity
• recent events
• the environment
• established traits and preferences

Mood must follow these rules:

• it must not cause permanent harm
• inactivity must not reduce permanent progress
• the user must not need to optimise mood values
• reunion behaviour may acknowledge a long absence without blaming the user
• uncomfortable temporary states must resolve safely

6.3 Formative events

A formative event is a meaningful event that may affect the pet’s lasting identity.

A formative event may create one or more of the following:

• a memory
• a trait or preference
• a behavioural habit
• a visual mark
• an expression
• an item or environmental detail

Formative events should be uncommon enough to remain meaningful. They must not be produced mainly by repetitive activity farming.

Large appearance changes should require user control or confirmation. Minor details may emerge naturally when they remain consistent with the product’s visual design.

6.4 World

The world contains the authoritative context required for the pet to exist consistently.

Product level world concepts may include:

• time and day phase
• one active pet
• the current environment or scene
• owned or discovered items
• memories and formative events
• activity records
• queued and recent events
• progression state
• available environment capabilities

V0 supports one world with one pet. Multiple pets, shared households, visits, and pet encounters are future possibilities and are not requirements for V0 or V1.

6.5 Items and discoveries

Items may provide cosmetic variety, environmental decoration, new expressions, or small interactions. They must not become mandatory consumables required to keep the pet alive or healthy.

Activity rewards should favour memories, discoveries, and character development over currencies and numerical optimisation.

6.6 Relationship

The product may represent the history between the user and pet. It must not use relationship decay to punish absence.

The relationship should be visible through accumulated shared experiences, familiar behaviour, and established routines. It should not be reduced to a bar that demands maintenance.

7. Activity model

Real world activities are optional inputs into the pet world. They are not required for the pet to remain valid or usable.

SPEC-FR-001: platform independent activities

The product shall represent a real world activity using a platform independent activity type and relevant activity data.

SPEC-FR-002: manual activity support

An activity shall be recordable without requiring a third party service. Adapters may automate activity reporting in later versions.

SPEC-FR-003: pet participation

The pet shall be able to enter an appropriate activity or expression while a supported shared activity is in progress.

SPEC-FR-004: positive completion response

Completing an activity may produce a memory, discovery, expression, behaviour, or other non punitive result.

SPEC-FR-005: no inactivity penalty

Failing to start or complete an activity shall not damage the pet, remove permanent progress, or reduce the relationship.

SPEC-FR-006: adapter supplied activities

An adapter shall be able to translate an external action into a product level activity event without receiving direct ownership of mutable Core state.

SPEC-FR-007: bounded activity response

Repeated external events shall be rate limited, grouped, or otherwise bounded where necessary. High activity volume must not produce unbounded rewards or pressure the user to optimise external behaviour.

Candidate activity categories include focus, walking, reading, rest, and creative work. Inclusion in this list does not place every category inside V0.

8. Interaction model

SPEC-FR-008: semantic actions

User intent shall be represented as semantic product actions independent of physical input. A button, keyboard key, touch gesture, or adapter may produce the same action.

SPEC-FR-009: limited input operation

Essential interactions shall be possible using a small number of directional and confirmation actions.

SPEC-FR-010: valid absence

The world shall remain valid when no user input is received for an extended period.

SPEC-FR-011: calm feedback

The product shall communicate changes through concise visual, textual, or optional audio feedback without requiring acknowledgement of routine events.

SPEC-FR-012: capability aware behaviour

The product shall remain valid when a frontend or environment does not provide a particular input, output, sensor, or integration capability.

9. Time and autonomous behaviour

SPEC-FR-013: explicit time progression

The world shall progress through explicit time information supplied by its host environment. Core behaviour must remain testable without relying on the actual system clock.

SPEC-FR-014: autonomous activities

The pet shall be able to select or transition between ambient activities without direct user input.

SPEC-FR-015: session continuity

The product shall account for elapsed time between sessions without simulating every missed update.

SPEC-FR-016: safe clock anomalies

Unexpected clock changes shall not cause permanent harm, invalid world state, or unbounded processing.

SPEC-FR-017: reproducible core behaviour

Given the same initial state, time input, actions, external events, and random seed, Core behaviour should be reproducible for testing.

10. Development and progression

SPEC-FR-018: lasting identity development

The pet shall be able to gain lasting memories, traits, preferences, habits, marks, or discoveries.

SPEC-FR-019: bounded maturity

The pet may progress through a limited maturity model. Development shall stop before the pet loses its intended scale and visual character.

SPEC-FR-020: no ageing requirement

Normal progression shall not require old age, physical decline, or death.

SPEC-FR-021: non destructive progression

Permanent development shall not be removed because of inactivity or failure to complete a routine.

SPEC-FR-022: meaningful causes

Lasting development should reflect time, interaction, formative events, and shared activities. It must not depend only on numerical activity counts.

SPEC-FR-023: cosmetic control

The user should be able to control the presentation of lasting visual details when those details materially affect enjoyment of the pet’s appearance.

SPEC-FR-024: distinct outcomes

Different pets should be able to develop different identities without being ranked as better or worse versions of the same character.

11. Frontends

A frontend provides the presentation and direct user interaction for a particular environment. Examples may include SDL, OLED, e ink, mobile, and web frontends.

SPEC-FR-025: presentation state

A frontend shall receive a read only presentation view derived from authoritative world state.

SPEC-FR-026: varied frontend capabilities

The product shall permit frontends with different resolutions, colour depths, refresh rates, input methods, and output capabilities.

SPEC-FR-027: desktop reference frontend

V0 shall provide a desktop frontend suitable for developing and validating the pet experience without embedded hardware.

SPEC-FR-028: headless operation

The Pet Core shall be usable without a graphical frontend for automated tests and non visual integrations.

SPEC-FR-029: frontend independence

Changing the frontend shall not require redefining pet behaviour, progression, or persistence semantics.

Not every frontend must expose every product capability.

12. Adapters and environment capabilities

Adapters connect external systems and physical inputs to the Pet Core. Candidate sources include sensors, Git hooks, local applications, mobile activity sources, and future plugins.

The architecture may later distinguish physical adapters from digital adapters. This specification does not require separate interfaces before their shared and distinct needs are understood.

SPEC-FR-030: semantic translation

Adapters shall translate source specific data into semantic actions, activities, environment state, or events understood by the Core.

SPEC-FR-031: no direct state mutation

Adapters shall not directly mutate authoritative pet or world state.

SPEC-FR-032: optional capabilities

The absence of an adapter or environment capability shall not invalidate the world or prevent basic use.

SPEC-FR-033: physical interaction support

The product model should permit physical inputs such as proximity, motion, orientation, touch, and ambient light to influence pet behaviour through adapters.

SPEC-FR-034: digital integration support

The product model should permit digital sources such as Git hooks, focus tools, reading services, or local scripts to report activities through adapters.

SPEC-FR-035: capability discovery

The Core should be able to receive a description of available environment capabilities so that it can avoid selecting interactions that the active environment cannot support.

SPEC-FR-036: input validation

Adapter supplied data shall be validated, bounded, and safe to ignore when unsupported or malformed.

Sensor thresholds, calibration, filtering, and source specific interpretation belong outside domain behaviour. For example, an accelerometer adapter may report a semantic shake event instead of exposing raw hardware readings to the Core.

13. Persistence and ownership

SPEC-FR-037: local persistence

The pet and world state shall be saveable and restorable locally.

SPEC-FR-038: state validation

Invalid, unsupported, or corrupted save data shall be rejected safely instead of being partially applied to the active world.

SPEC-FR-039: format identification

Persisted data shall identify its schema or format version so that compatibility can be handled explicitly.

SPEC-FR-040: minimal personal data

The Pet Core shall not require personally identifying information, location history, private repository access, or continuous behavioural telemetry.

SPEC-FR-041: future transfer

Pet export, device transfer, local network discovery, peer interaction, and synchronisation may be introduced after V1. They are not requirements for V0 or V1.

SPEC-FR-042: device independent identity

The persistence model should avoid defining pet identity as a permanent property of one display or device. This requirement preserves future options without requiring transfer support in the initial versions.

14. Functional summary

The intended product model supports:

1. one persistent pet in one world for the initial versions
2. deterministic time based world updates
3. semantic user actions independent of input hardware
4. autonomous pet expressions and activities
5. optional real world activity events
6. lasting identity development through shared history
7. limited maturity without old age or death
8. read only presentation state for different frontends
9. adapters for physical and digital sources
10. local save and restore
11. headless execution and automated testing
12. future expansion without making network services part of the initial product

The milestone plan determines when each capability becomes deliverable.

15. Non functional requirements

SPEC-NFR-001: portability

The Pet Core shall avoid unnecessary dependencies on operating system services, graphics frameworks, network stacks, threads, and specific hardware platforms.

SPEC-NFR-002: resource awareness

Core data structures and update work shall remain suitable for eventual use on constrained embedded devices. Capacity limits should be known at compile time where practical. State that depends on configuration shall be bounded and prepared during initialisation. Runtime behaviour shall avoid dynamic allocation, unbounded growth, and avoidable setup work.

The initial Core shall use fixed-capacity inline storage or caller-owned storage. This requirement does not permit hidden file scope mutable state. Exact hardware limits will be refined when a target hardware class is selected.

SPEC-NFR-003: testability

Time, randomness, input, persistence, and adapter event delivery shall be controllable in automated tests.

SPEC-NFR-004: robustness

Malformed actions, invalid saves, unexpected time values, and unsupported capabilities shall fail safely without corrupting authoritative state.

SPEC-NFR-005: responsiveness

Normal interaction and presentation shall feel immediate on supported platforms. Missed time processing and adapter input must remain bounded.

SPEC-NFR-006: maintainability

Product rules, frontends, persistence, and adapters shall have explicit boundaries. A platform specific feature must not silently become a Core requirement.

SPEC-NFR-007: compatibility awareness

Public data and API contracts shall evolve deliberately. Compatibility promises for each release belong in milestone and release documentation.

SPEC-NFR-008: privacy

External integrations shall be optional, request the minimum required data, and make their effect on the pet understandable to the user.

SPEC-NFR-009: accessibility

Core interactions should not depend only on colour, audio, precise pointer input, or rapid reaction. Each frontend is responsible for suitable accessible presentation.

SPEC-NFR-010: language and terminology

Code, documentation, public API names, and developer facing text shall use British English. Domain code written in C is expected to use the pet prefix unless architecture documentation defines a more specific internal prefix.

16. Product constraints

• V0 is a software only milestone
• V0 must not depend on purchasing or selecting final hardware
• the reference frontend may use SDL but SDL must not define Core behaviour
• the initial product must remain useful without generative AI
• network connectivity must not be required for Core behaviour or local persistence
• V0 and V1 do not require pet transfer, local network discovery, or synchronisation
• Core interactions must remain representable on limited input hardware
• the world must remain valid after long periods without user interaction
• sensors and digital services must communicate through adapters
• hardware optimisation must not fragment domain behaviour across frontends
• V0 supports one active pet in one world

17. Out of scope for V0 and V1

The following are outside V0 and V1 unless milestone planning explicitly changes the scope:

• generative AI conversation
• voice recognition and speech synthesis
• mandatory accounts
• cloud synchronisation
• transfer of a pet between devices
• local network discovery
• peer interaction between pets
• multiple active pets in one world
• shared household simulation
• public profiles and social networks
• competitive leaderboards
• advertisements and engagement driven monetisation
• permanent death and irreversible neglect mechanics
• real money randomised rewards
• medical and mental health claims
• continuous surveillance of user activity
• final custom hardware and mass production engineering
• support for every proposed frontend
• support for every proposed sensor or integration
• a general purpose task manager, calendar, or habit tracking suite

18. Version vision

This section provides direction. The authoritative deliverables and exit criteria belong in milestones.

V0: software pet foundation

V0 is the first milestone. It validates that a meaningful pet can exist in a software reference application while its world, behaviour, input, presentation state, time handling, and persistence remain independent of SDL and future hardware.

V0 should establish the smallest complete pet loop. It should be possible to run and test the Pet Core without a renderer, observe the pet through a desktop frontend, perform a small set of semantic interactions, see early identity development, and preserve state between sessions.

V0 does not need physical sensors, external digital integrations, multiple pets, networking, or device transfer. Adapter boundaries may be represented and tested without shipping a complete plugin system.

Later direction

Later milestones may introduce richer identity development, real world activity adapters, physical sensor adapters, an embedded frontend, mobile support, and additional content.

Pet transfer, peer discovery, multi pet interaction, shared households, and synchronisation belong after V1 at the earliest. Their inclusion depends on product value and technical cost observed in earlier milestones.

19. Success criteria

The product direction is successful if:

• users perceive the pet as pleasant company rather than another responsibility
• absence does not create guilt or irreversible loss
• the pet develops a recognisable identity through shared history
• maturity provides progression without making the pet old or visually oversized
• real world activities feel acknowledged rather than judged
• sensor and digital integrations can add interaction without entering Core domain logic
• different frontends can present the same product rules
• the software version is worthwhile before custom hardware exists
• the system remains understandable, testable, and portable as content grows

V0 acceptance criteria will be defined in milestones and traced to epics and PBIs.

20. Open questions

The following questions are intentionally unresolved:

1. what is the final product name
2. what creature and appearance options are available in V0
3. how many maturity stages should exist
4. what physical size change is acceptable during maturity
5. which traits, habits, and visual marks can emerge in V0
6. which visual changes happen naturally and which require confirmation
7. how can the user hide or manage lasting cosmetic details
8. which formative events are sufficient to validate identity development
9. which autonomous activities make V0 feel alive
10. which real world activity should first validate shared activity
11. what form of progression creates attachment without optimisation pressure
12. how should long offline periods be summarised
13. what are the exact rules for clock and time zone changes
14. what persistence format and compatibility promise should V0 provide
15. what minimum display and input assumptions should future hardware use
16. how much behaviour should be data driven
17. should physical and digital adapters use separate interfaces
18. how should adapter permissions and event rate limits work
19. what parts of the project may become open source
20. what commercial model could support plugins or physical products

21. Glossary

Pet: The persistent character that accompanies the user. This is the primary domain term.

Companion: A product description for the role of the pet. It may be used as a synonym in user facing language.

Pet Core: The platform independent domain and simulation layer that owns authoritative behaviour and world state.

World: The authoritative product state containing the pet and its persistent context.

Frontend: A platform specific presentation and direct interaction layer.

Adapter: A boundary that translates physical or digital source data into semantic Core input.

Semantic action: A platform independent representation of user intent.

Activity: A real world or in world action that may involve the user, the pet, or both.

Formative event: A meaningful event that may create a lasting memory, trait, habit, mark, expression, or discovery.

Trait: A lasting tendency that influences pet behaviour without ranking its value.

Visual mark: A lasting appearance detail associated with the pet’s history.

Maturity: Bounded development that increases identity and behavioural richness without requiring old age.

Mood: A temporary and non punitive influence on expression and behaviour.

Discovery: Content revealed through time, interaction, formative events, or shared activity.

Presentation state: A read only frontend view derived from authoritative world state.