Strategy
Determines which reusable advantage matters.
System 04 · Reusable capability & leverage
The Platform System
The reusable capability layer that converts validated implementation into stable foundations multiple products, games, and contributors can safely consume.
Knowledge
Defines the platform contracts.
Execution
Builds and proves capabilities.
Platform
Preserves, evolves, and distributes reuse.
01 · Responsibilities
Ten questions every reusable capability must answer
The output is not merely shared code. It is a governed set of versioned capabilities, interfaces, assets, tools, tests, and documentation.
A capability with a valid platform purpose.
Current and anticipated consumers.
Behavior, interfaces, limits, and errors.
Product policy, content, and meaning.
Candidate through retired.
Maintainer, steward, approval authority.
API, configuration, assets, or tooling.
Contract, compatibility, and hardware tests.
Versioning, migration, and deprecation.
Adoption, reliability, and delivery efficiency.
02 · Qualification
Reuse lives between two failure modes
The Platform System avoids duplicated behavior in every game and premature frameworks built before a credible second consumer exists.
Duplicate everything
Each game rebuilds lifecycle, input, rendering, and diagnostics. Delivery slows; defects and incompatible patterns multiply.
Platform
discipline
discipline
Generalize too early
The team creates costly abstractions around imagined needs. Interfaces harden before real consumers reveal the right boundary.
Solves a recurring problem
Has a product-independent contract
Has a real and credible second consumer
Carries measurable quality expectations
Keeps game rules outside the boundary
Includes ownership, tests, and adoption guidance
03 · Artifacts
A connected Platform Package
Every supported capability carries its mandate, contract, proof, consumption path, compatibility promise, and accountable ownership.
| Artifact | Purpose | Required content |
|---|---|---|
| Platform Charter | Defines the mandate | Consumers, value, boundaries, owners, success measures |
| Capability Catalog | Lists supported capabilities | Status, owner, version, consumers, dependencies |
| Capability Contract | Defines reusable behavior | API, states, guarantees, limits, errors, configuration |
| Architecture Model | Defines platform structure | Layers, dependency rules, extension points |
| Compatibility Policy | Controls change | Versioning, guarantees, migrations |
| Platform Decision Record | Preserves reasoning | Decision, alternatives, consequences, affected consumers |
| Reference Implementation | Demonstrates correct use | Minimal consumer and recommended patterns |
| Conformance Suite | Proves compliance | Contract, regression, compatibility, hardware tests |
| Integration Guide | Enables adoption | Setup, configuration, examples, failure modes |
| Release Manifest | Identifies a reproducible release | Commit, toolchain, modules, targets, evidence |
| Deprecation Record | Manages retirement | Replacement, migration, dates, affected consumers |
| Platform Health Report | Measures value | Adoption, stability, duplication, delivery impact |
04 · Capability contract
Implementation alone is incomplete
A reusable capability needs explicit behavior, stable interfaces, bounded configuration, a quality envelope, evidence, ownership, and consumers.
Reusable promise
Game Lifecycle · v1.0.0
The platform owns lifecycle mechanism and guarantees; each game owns its content, rules, and presentation policy.
- Stable public interface
- Controlled configuration
- Measurable transition quality
- Semantic compatibility policy
- Conformance and target-board evidence
- Two independent consumers
capability_id: CAP-GAME-LIFECYCLE
version: 1.0.0
status: stable
owner: engine-steward
consumers:
- sock-rescue
- lifecycle-reference-harness
public_interfaces:
- lifecycle_initialize
- lifecycle_dispatch
- lifecycle_current_state
guarantees:
- invalid transitions rejected
- paused simulation does not advance
- resume preserves simulation boundary
prohibited_configuration:
- consumer-defined lifecycle states
- direct state mutation
quality:
transition_latency_frames: 1
repeated_cycle_target: 100
dynamic_allocation: false
compatibility: semantic-versioning
target: feather-rp2350-hstx05 · Architecture
Dependencies point downward
Lower layers must never import or make decisions based on a specific game. Stable APIs separate reusable mechanism from product meaning.
Games & experiencesRules, content, progression, presentation policyNo direct hardware access
Game-facing APIsStable reusable contracts and extension pointsNo individual game logic
Runtime servicesLifecycle, timing, graphics, audio, input, assetsNo product-specific content
Hardware abstractionBoard and peripheral differencesNo gameplay policy
RP2350 hardwareMCU, HDMI display, audio, input, storageNo software-level meaning
↓ dependency direction ↓
Tools & asset pipeline → game-facing APIs
Diagnostics & test harnesses → runtime services
06 · Maturity lifecycle
Working once does not mean stable
Maturity communicates support obligations, evidence, compatibility commitments, and whether new consumers should adopt the capability.
Candidate
Incubating
Supported
Stable
Deprecated
Retired
Evidence branch: An incubating candidate may be rejected if the boundary is not reusable, the quality cost is too high, or no credible second consumer emerges.
07 · Promotion
Successful features earn platform status
Execution can identify a reusable candidate. Promotion is a deliberate review of recurring need, boundary quality, evidence, ownership, and net leverage.
Will this problem appear again?
Can another game, harness, or tool use it?
Can product policy remain outside?
Is behavior independent of implementation?
Are reliability and performance measured?
Who maintains compatibility?
Does reuse exceed abstraction cost?
Can the first consumer adopt it cleanly?
The reference harness is the critical second consumer
It proves the capability works independently of Sock Rescue without requiring the team to build an entire second game merely to validate reuse.
Capability authorization
Platform Gate
Promotion remains blocked until the contract, independent consumption, target evidence, ownership, compatibility, and adoption path are complete.
Reusable problem and product boundary are explicit
Public capability contract exists
Real consumer and independent reference consumer pass
Interface, regression, and target tests pass
Performance and memory costs are measured
Failure behavior is defined
Ownership and compatibility policy assigned
Integration and migration guidance exists
gate: platform-promotion
decision: approved
authorized_next_stage: supported-release
capability:
id: CAP-GAME-LIFECYCLE
version: 1.0.0
maturity: supported
consumers:
- sock-rescue
- lifecycle-reference-harness
validation:
contract_tests: passed
target_board_tests: passed
pause_resume_cycles: 100
unresolved_failures: 0
boundaries:
game_specific_dependencies: 0
direct_hardware_dependencies: 008 · Governance
The Engine Steward protects long-term leverage
The steward does not own every implementation. The role owns the integrity, usability, and evolution of the platform as a system.
Stewardship responsibilities
Protect coherence without becoming a delivery bottleneck.
Own boundary policyReview candidatesPrevent game leakageRequire reuse evidenceManage interface stabilityCoordinate migrationFind duplicationProtect contributor usability
“The platform provides the mechanism. The product provides the meaning.”
Agents and teams may execute within approved contracts and recommend improvements. Changes to public guarantees, platform boundaries, compatibility, or accepted risk require authorized human approval.
09 · Extension
Specialize without forking the platform
Games extend stable mechanism through approved seams. Fundamental changes to guarantees, states, timing, ownership, or public interfaces return through platform change control.
| Consumer need | Appropriate response |
|---|---|
| Custom pause overlay | Configuration or presentation callback |
| Mute rather than duck audio | Approved audio pause policy |
| Game-specific Inventory mode | Game state layered above platform lifecycle |
| New universal lifecycle state | Platform change proposal |
| Direct controller hardware access | Reject; extend the input abstraction |
| Scoring stored inside lifecycle | Reject; retain game ownership |
ConfigurationEvent handlersPolicy interfacesAsset packagesData-driven rulesAdaptersOptional modules
10 · Compatibility
Version more than API shape
On embedded systems, compatibility includes timing, memory, binary size, peripheral behavior, supported boards, and asset formats.
Correct behavior without changing the public contract.
Add backward-compatible capability.
Change or remove a public contract.
Record hardware-specific compatibility separately.
Version content contracts independently.
Every breaking change includes
Decision recordAffected-consumer listMigration instructionsCompatibility test resultsDeprecation windowHuman contract approval
11 · Quality envelope
Platform promises must be measurable
A capability is not evaluated in isolation if its cost makes the complete RP2350 game infeasible.
Target cadence under a defined workload.
Event recognition within an approved bound.
RAM, stack, and binary budgets remain viable.
Repeated use remains stable.
No stuck audio or unstable supported display modes.
Reproducible state where required.
Actionable failures and reproducible releases.
New users integrate correctly from documentation.
System budget rule: Timing, RAM, flash, stack, audio, and HDMI costs are allocated by subsystem and assessed against the complete game—not celebrated in isolation.
12 · Release
A reproducible, consumable platform release
Each release identifies exact boards, SDK versions, display modes, input devices, and optional peripherals that are supported.
Delivery is a complete adoption package
Consumers receive more than libraries. They receive the supported interface, working example, validation, documentation, compatibility rules, and a path forward.
Supported means the team accepts ongoing ownership and compatibility obligations.
Runtime librariesPublic headers / APIsHardware definitionsAsset schemas & toolsReference configurationReference harnessConformance testsRelease notesMigration instructionsKnown limitationsBuild manifestEvidence references
13 · System relationship
Platform is a governed destination, not a shortcut
A capability begins as strategy or knowledge when intent changes, passes through execution for proof, and enters Platform only after promotion approval.
Defines reusable advantage and investment boundaries.
Defines contracts, decisions, and quality requirements.
Implements, validates, and proposes candidates.
Owns supported reusable capability and compatibility.
Controls promotion, exceptions, risk, and release.
Improves standards, templates, and playbooks.
Routes work and evidence through gates.
14 · Platform value
Measure leverage instead of assuming it
Platform investment is justified by repeatable delivery advantage, not by the elegance or size of the abstraction.
Active consumersAdoption by capability
Time to first playableNew-game delivery speed
Reuse rateNew work using supported capability
Duplication eliminatedSeparate implementations retired
Regression rateStability by platform release
Integration timeEffort per consumer
Breaking-change frequencyContract predictability
Correct bounded change timeNew agent or engineer usability
Platform Leverage
=
Duplicated effort avoided
÷
Creation + maintenance effort
=
Duplicated effort avoided
÷
Creation + maintenance effort
The estimate need not be financially precise; it forces an honest comparison between reuse value and abstraction cost.
15 · RP2350 capability map
The initial reusable foundation
Maturity should vary by evidence. Lifecycle may become Supported while advanced asset streaming remains Candidate.
Main loop, lifecycle, scheduling, timing
Device abstraction, mapping, debounce, reconnect
HDMI init, surfaces, sprites, text, overlays
Playback, channels, volume, lifecycle policy
Conversion, validation, packaging, lookup
Runtime state, deterministic resume, configuration
Board, display, controller, audio, storage adapters
Logging, assertions, counters, fault handling
Host harness, conformance, HIL protocols
Build, flash, asset conversion, package validation
Initial posture: promote only capabilities whose contract and quality envelope are proven on the target Feather RP2350 HSTX configuration.
16 · Boundary example
Sock Rescue consumes the platform; it does not define it
The platform owns durable mechanism. Sock Rescue owns gameplay meaning, creative identity, tuning, and product policy.
Platform-owned
- Running, Paused, and Game Over lifecycle
- Input event abstraction
- Frame and simulation timing
- Sprite and overlay primitives
- Audio-state transition mechanism
- Deterministic random-number service
- Asset-format validation
- Test and diagnostic infrastructure
Game-owned
- Sock spawning
- Consecutive-sock scoring
- Golden-sock probability and bonus
- Dog movement and difficulty
- Lives and end conditions
- Artwork and animation
- Level tuning
- Game-specific sound and music
The platform provides the mechanism. Sock Rescue provides the meaning and policy.
17 · Repository
Supported capability has a durable home
Platform implementation, contracts, governance, tests, releases, and documentation remain separate from individual game content and validation evidence.
Preserve boundaries in Git
The platform tree contains reusable runtime and support assets. Games integrate through a narrow adapter. Evidence remains traceable outside the implementation tree.
Next design step: define the Platform Capability Contract and Promotion Policy.
platform/
├── charter/
├── architecture/
│ ├── platform-layers.md
│ ├── dependency-rules.md
│ └── decisions/
├── capabilities/
│ ├── catalog.yaml
│ ├── lifecycle/
│ ├── input/
│ ├── graphics/
│ ├── audio/
│ ├── assets/
│ ├── timing/
│ └── diagnostics/
├── hardware/
├── include/ src/
├── examples/
├── tests/
│ ├── contract/
│ ├── conformance/
│ ├── compatibility/
│ └── regression/
├── releases/
├── governance/
└── docs/
games/sock-rescue/
├── game/ content/
├── configuration/
└── platform-adapter/
validation/evidence/platform/