Build a Rifflet

Start with [Canonical Rifflet Spec 2.15.0](CANONICAL_RIFFLET_SPEC.md) and [Content Onboarding](CONTENT_ONBOARDING.md). Describe every published edition in the validated catalog metadata; record its actual permissions, services, genres and intended audience. Legacy full-spec conformance is not implied by metadata normalization.

Give an agent this file plus your content idea. Work at the repository root assigned by your coordinator. Start with AGENTS.md, then read FRAMEWORK.md, RIFFLET_PROTOCOL.md and CONTRIBUTING.md when available. In the private canonical workspace, also read AGENTS.md, COLLABORATION.md, references/THESIS.md and your coordination inbox; those private references are intentionally absent from the source mirror. Ask the coordinator for a content brief rather than inventing their contents. Your content brief supplements this common contract.

The product

Make a complete, beautiful, mobile-first piece of playable content. It should deliver a specific pleasure, insight or useful outcome in roughly 30 seconds to 3 minutes. A visitor must be able to change something meaningful, see or hear the result, finish, and share their version. The experience—not a proposal for it—is the deliverable. CRAVE MODE is our reference for cinematic food, actual temporal video, optional synchronized sound and useful controls. Go beyond a video with buttons: the interaction should change the content or understanding. Non-recipe formats are welcome.

Riff's thesis is a spectrum from media to apps: every post can be an experience. A machine-readable brief supports discovery, a preview brings people in, the full experience plays on the destination, and human feedback improves subsequent versions. Use the Rifflet Common Framework (RCF) modules supplied by the maintainer; compatibility with another Riff platform requires separate verification.

Start

1. Confirm your agent identity and assigned app slug with the coordinator (COLLABORATION.md in the canonical workspace). Read source material and inspect existing reusable assets. Do not overwrite another agent's files.
2. Write a short app brief: audience, promise, 10-second hook, meaningful interaction, payoff, replay/remix reason, modalities, fallback, meaningful intermediate milestones, and whether the experience has a measurable full finish.
3. Build static HTML/CSS/ES modules in apps/<slug>/. Use ../../shared/runtime.js and shared tokens. The public URL is https://riff.marantz.net/<slug>/; old demos.marantz.net links redirect. Local is http://127.0.0.1:4173/<slug>/ after npm run build && npm run preview.
4. Add content.json, README.md, QA.md, assets and any captions. Request reviews from both other agents using coordination files. Incorporate at least one concrete review improvement and cite evidence. Never invent peer review or user tests.
5. Ask Codex for integration/deployment in your notes. Codex alone owns Cloudflare, browser access, DNS and publication receipts.

Before any automated browser or builder agent opens Feed, Lab, a viewer or an app in an analytics-enabled build, create a dedicated browser context and tag the first URL with test_agent=1 using scripts/test-agent-browser.mjs. Keep that context separate from manual review. The enabled bootstrap consumes that query parameter before app code can copy it into a recipient link; the four-hour tab marker still follows same-origin navigation and viewer children. test_agent=0 clears only future events. The tag is test-traffic evidence, not authentication or identity proof.

MVP acceptance criteria

• A finished experience with a hook, agency and payoff; no storyboard, mock phone render, dead-end placeholder or fake counters.
• Mobile layout at 375, 390 and 430 CSS px; usable wide desktop layout. Desktop mobile-viewer loads the exact app in a 375/390/430 px iframe. Viewport QA is not physical-phone QA.
• Two complementary modalities minimum (e.g. interactive visual + optional sound, or cooking motion + readable controls). Use sensors only if they strengthen the experience. Explicit permission after a user gesture; denial, unsupported browsers and desktop all retain equivalent controls. Never require location, microphone or camera by default.
• Keyboard/touch parity, visible focus, named controls, readable contrast, captions/transcript for meaningful audio/video, reduced-motion mode, mute/pause, and static/text fallback. Core content cannot depend on motion or sound.
• Share link with validated, bounded state; Web Share when supported, copy/manual-copy fallback otherwise. Static title, description and preview metadata. No personal data in the URL.
• New Rifflets implement play → personalize → recipient preview → share → riff again using the bounded instance contract. An attributed copied brief may be an additional action; it does not satisfy that loop. Preserve source ID/version and creator credit.
• Structured content.json with schemaVersion, id, version, title, creator, summary, audience, interaction, modalities, durationSeconds, entry, completionEvent, provenance, permissions, remix and status. All predictions/illustrations must be labeled; agents are not human audience evidence.
• Declare and test rifflet.analytics/0.2 under [ANALYTICS.md](ANALYTICS.md): actual semantic start, up to 12 intermediate milestones, final completion or null, attempt boundaries and bounded diagnostic names. milestone() keeps the attempt open; complete() is reserved for finishing the full defined experience. Events stay local by default; the internal-test build collects automatically without disclosure UI and uploads centrally bounded fields plus passive device context. The private collector adds trusted IP, traffic evidence and authorized nickname-to-browser observations. No fingerprinting, relinking after storage clearing, invented metrics, creator authorization or recipient claims. Explicit public feedback and scoreboard names use their separate consent flows.
• Recipe apps use one structured source record, real quantity scaling, consistent steps and yield, timer with pause/reset, packing/allergen notes, actual motion footage when claimed, rights/provenance and AI disclosure. Never invent testing, nutrition, endorsement or safe substitutions.
• No paid services, paid APIs, rendering credits, upgrades or purchases without Dan's explicit permission. Existing subscription use only; stop at quota rather than enabling overages.
• Use literal relative module imports so the build can version the entire script graph. Give replacement media a new filename. Do not hard-code generated cache keys in source.
• Build contains only public app assets. No references, credentials, internal coordination or archives. Core play and bounded authoring run statically; the approved common feedback/history service is the explicit server-backed exception. An unavailable feedback API must not block play or lose the current draft. Keep initial HTML/CSS/JS small; lazy-load media, use posters, and keep each Pages asset below 25 MiB.
• Deliver actual test results, screenshots where useful, media paths, blockers and a peer-review disposition. A green build alone is not visual QA.

Done means

Report whether your app offers state sharing, a collected riff request, or an actual content editor. For a new editor, ask the coordinator to register its pure semantic validator with the hosted API and verify server-side content and lineage rejection. Test optional camera/sensor permissions on both the direct route and embedded viewer; camera background, device orientation and body tracking must be described separately.

A person can open the URL on a phone, understand what to do, use it without permissions, make something happen, reach a payoff, and share/remix it. Both peer reviews are requested and their actual responses tracked. Codex verifies the deployed URL. Record remaining device/hosting/media limitations honestly.

Prompt to paste with your idea

“Read AGENTS.md, then starter_advanced_content.md at this repository root and the available linked project rules. You are [Claude / GrokBot / Codex], assigned [slug]. Build this content idea: [BRIEF]. Own only your app and your coordination notes. Use the shared framework, request reviews from the other two agents, iterate from actual feedback, and follow the coordinator’s existing review loop. Use a supported scheduler only if authorized; never duplicate a loop or bypass a denial. Stop at any spend or access boundary and report it. Leave a tested runnable app and deployment request for Codex.”

Submitting and riffing a Rifflet

Keep source in apps/<slug>/, with an existing-schema content.json and an optional bounded rifflet.data.json contract. Reuse shared/rifflet.js for supported play → personalize → share → riff-again flows. A content-only riff creates a hashed instance with its immediate parent; it does not copy source or change SemVer. A source fork gets its own slug and pinned parent release. Preserve original creator attribution.

Submit a focused branch/patch and tested frozen source commit. The coordinator uses scripts/rifflet-package.mjs to inspect and package the committed app/shared files without executing uploaded code. Do not push private canonical history to the distribution repository. See RIFFLET_PROTOCOL.md for the data, package, review, release and rollback contracts.

A remix must change something meaningful for its audience, provide a recipient preview, and create a fresh shareable child that another person can riff again. A copied prompt alone does not satisfy this loop. Show release drift honestly; source hashes are not verified author identity. Keep personal names, rosters, secret answers, attempts and progress out of URLs. Test at least parent → child → grandchild in fresh browser contexts, malformed links, keyboard and reduced motion. Record agent review separately from actual human feedback.

Required feedback loop in the product

Hosted on https://riff.marantz.net/ with the user-authorized existing Cloudflare plan. Production feedback retry, history readback and removal, plus child/grandchild riff publication, were verified September 30, 2026 at source 191ad23d2a17f1c35b3402d7894e24574e409249. Automated test entries were removed; these checks are not human engagement evidence. Use the common bottom-right Menu for feedback, ideas, history and making a version. At widths up to 700px the viewer uses the full viewport; audited branding moves as original nodes into About in the flyout, while instructions, first actions, warnings and game controls stay inline. Opening or closing the menu must preserve play state and return keyboard focus. Do not clone IDs/listeners or replace working controls with raster UI. Feedback categories are feedback, bug, feature and riff-idea. Show app ID, release version/commit and optional instance/parent IDs before explicit public consent and submit. No automatic telemetry, sensor frames, microphone recordings or identifying fields are attached. The text and displayed context become public lab history; do not include private information. Actor labels are self-reported human/agent-test/unknown, not verified identity or engagement. Keep drafts locally when storage is available. Submit only on user action; pending means not confirmed delivered. Manual retry reuses the same submission ID, body and deletion capability. Download/import a private receipt to retry or remove an entry; its removal key must never enter a shared URL. If storage is denied, keep the current text and offer receipt export rather than claiming persistence. Acknowledgement, not a local save, changes the item to received. Little Safe, One-Minute Town, Block Party, Pocket Putt and Recall Studio have actual maker editors. The experimental Skeleton Lens also has a bounded challenge editor; its simulated hand/wrist model is not an anatomical validation or body-tracking claim. Other Make a riff actions open a real riff-idea request, not an automatic generator or copied prompt. A prepared validated riff can be published to public lab history only after a separate explicit checkbox. All authored settings become public, including Recall questions and answers; play progress does not. Preserve source release and recorded parent, without claiming verified parent authorship or observed lineage. Public payloads remain until removed or the pilot ends. A private receipt enables removal; minimal tombstones prevent replay and platform backups may retain prior data. The pilot caps lifetime submissions at 5,000 including tombstones and limits each IP/hour to 20 mutations and 120 reads. These are abuse controls, not a zero-cost guarantee. The user authorized enabling hosted feedback on the existing paid plan; unrelated new spend still requires approval. See server/README.md for the exact API and failures. Include consent, pending/retry/removal and keyboard/mobile behavior in acceptance. Human reports feed owner triage and reviewed releases; agent review is separate evidence.

Brief, audience, discovery and learning from feedback

Build for the full intended loop: maker brief → review → approved/editable taste → explainable match → play → human feedback → revision. Supply an accurate summary, meaningful interaction, declared audience, modalities, estimated duration, concrete completion event, permissions, provenance and remix policy in content.json. The coordinator generates catalog makerBrief under rifflet.brief/0.1; do not invent another owner schema or claim platform review. Source revision must be real or explicitly unpinned.

Coordinate the shared discovery classification: interests puzzles, music, food, languages, nature, creativity, calm, arcade, mystery; contexts beginners, curious-learners, makers, groups. Say in plain language what makes the experience good for that audience. Keep unknown classification unknown. Current discovery uses explicit local selections with explanations; it is not behavioral tracking, a private assistant-history import or an approved taste graph. Future assistant-drafted taste must be approved and editable by the person.

Plan honest observation using ANALYTICS.md and FRAMEWORK.md: starts, milestones, final completion, share outcomes and explicit skip have distinct meanings. Pin the running code release and preserve unknown traffic classification when evidence is insufficient. Signed QA contexts identify our tests; actor declarations alone do not prove a person. The pilot does not collect instance/parent IDs or implement recipient analytics. Leaving is not skip; copying is not delivery. Ordinary builds remain off; the user-authorized hosted invited-test profile enables collection and provides private aggregates, browser nickname history and bounded operator-only raw samples. Public feedback/history is separate and has passed hosted write/read/removal verification. Human feedback should produce a recorded owner decision and reviewed revision; automated tests and distribution projections cannot establish demand.

Personalized instances can change audience and intent. Catalog makerBrief currently describes only the base app release. Plan a future instance brief derived from validated authored data and tied to immutable parent/source references; do not imply the derivative inherited the parent’s audience match or review approval.

Immersive defaults and direct controls — September 30 revision

Use Rifflets branding in product UI and new code. In the standalone experience, enable authored sound and motion by default; unlock browser audio on the first deliberate app interaction. Feed covers remain silent and passive. Preserve a readily available mute/pause and honor OS reduced motion and previously chosen comfort settings. Immersive does not mean maximum loudness or overriding sensor permissions. Hide agent synthesis labels from primary play screens; preserve creator credits in About/source. Give touch-first content direct manipulation with visible targets, preview-before-release, pointer cancellation, and equivalent tap/keyboard controls. Initialize animation clocks from the first animation frame, not the preceding click timestamp. Sensors must calibrate to the starting grip, retain touch fallback, and never be described as connected before data arrives.

Illustrated cover and standalone entry

Every published Rifflet and original edition requires a truthful portrait cover and a fast first action. Follow [RIFFLET_COVERS.md](RIFFLET_COVERS.md) for the full-bleed illustrated art, accessible entry link, provenance, performance and acceptance contract. Use useful defaults; move optional configuration into the common Menu → Experience settings through reviewed data-riff-settings containers. Keep primary play, stop/mute, required advisories and received-riff previews accessible. Never trade safety or lineage for fewer taps. Update these common expectations as the feed evolves.

Common infrastructure acceptance — October 2, 2026

All published editions must declare an app-specific rifflet.analytics/0.2 contract: meaningful start, intermediate milestones, final completion or null, and explicit stop/replay boundaries. Never count an answer reveal, loss, bailout, intermediate level or mere page load as finishing the full experience. See docs/COMMON_INFRA_COVERAGE.md for the current edition inventory. Keep private choices, option text, camera data and ballots out of analytics; mark private control regions data-analytics-private.

Listen on window for rifflet:pause, rifflet:resume and rifflet:dispose. Suspend animation, physics and sound while hidden or while the shared star menu is open; resume deliberately without time jumps. The shared lifecycle is cooperative control, not an untrusted-code sandbox. Keep execution client-side and server writes explicit, bounded and idempotent.

Hosted scoreboards require explicit public submission consent, bounded names and scores, stable retry IDs, and an unverified-score label until server-verifiable scoring exists. Private group decisions use separate invitation/organizer/member capabilities, expiry and deletion; never publish individual ballots or imply end-to-end encryption. Prompt-seeded curated libraries must identify themselves as curated, not model-generated. Preserve old saves and patch-bump changed editions.

New app checklist additions: reuse the device-local alias from shared/identity.js; do not upload its opaque ID. Clean up sensors and workers on all lifecycle paths. Use licensed music/media and cite researched content. Show whether a deck is authored or built from a retrieved passage. Update the living collaborator inventory and presentation notes at release; no fabricated adoption, engagement or accuracy claims.

Voice-practice feedback should pair the live measured pitch with the target, an explicit higher/lower cue and a no-signal state. When guide audio plays during microphone analysis, show a prominent headphone recommendation and keep mute reachable; speaker bleed can invalidate a singing estimate. Distinguish transient microphone analysis from recording or saving audio.

Reuse the shared alias confirmation flow: show old/new names before applying a reset, preserve cancel, and explain browser-local scope and unchanged previous posts/progress. Do not add an immediate one-click alias reset.

For compact invitations, use the shared optional shareShortRiff service with visible90-day storage notice and full-link fallback; never invent a separate URL shortener. Keep every fullscreen control reachable in portrait/landscape, including fallback mode. Default authored game sound on, unlock on interaction, and preserve deliberate mute preferences.

For simultaneous co-building, reuse the registered shared-room component described in FRAMEWORK.md and docs/collaboration/FRAMEWORK_COMPONENT.md. Keep core play local; make cloud room creation explicit. Supply a pure bounded state/command adapter and verify multiple clients, conflicts, reconnect, persistence, revocation, expiry and immutable snapshots. State exactly which storage bindings are active. Do not present snapshot copies as the versioned Rifflet ancestry loop.

Analytics QA must include a real semantic start and final or milestone, offline diagnostic saturation, replay/session boundaries and legacy-release comparisons. Preserve each reviewed release's analytics contract in release history; do not interpret unrecorded historical finishes as zero. The shared collector may explicitly reject diagnostic samples at its budget threshold while preserving journey capacity. These are data-quality limits, never an app failure or proof of user disengagement.

Feed preview and standalone entry — adopted October 5

Canonical Rifflet Spec 2.15.0 uses the Rifflet Common Framework (RCF) for a passive illustrated cover → same-tab standalone experience → return-to-feed flow. Cover art fills the phone, with a transparent header and profile/Heart/Share icons over the artwork; there is no dedicated social rail, visible “Tap to enter” button or footer CTA. Keep a named, keyboard-accessible entry link and visible focus feedback. A truthful visual metaphor may illustrate the key mechanic without matching the first gameplay frame; use little or no text, with large readable type when text is needed. Keep essential subjects clear of header, footer and icon hitboxes. Background cropping is allowed; essential subjects must remain intact.

Only the active cover animates; pause it while the page is hidden or a modal is open. Reduced motion is static, and Menu → Pause cover animation persists the visitor's choice. Before deliberate entry, fetch or instantiate no app code, iframe, gameplay timer, media, worker, model or sensor; licensed cover artwork alone is allowed. Never simulate gameplay events, consent or results. Tapping the entry link opens the actual app in the same tab. Browser Back and Menu → Back to feed restore the selected card and applicable filters. Inside the app, preserve first actions, essential rules, received content, consent and Start/Stop/Mute; move optional instructions/settings into Menu. Desktop arrows sit outside the phone; mobile uses swipe without visible arrows, with keyboard and assistive alternatives. Every published edition needs a cover: the current 40 editions use 31 main artworks plus family variants. Derive the static 900×1200 WebP Lab cover from the same artwork and preserve each edition's identity.

Product terminology: ready to play UI means an animated, passive invitation in /feed that opens the actual standalone experience on tap. Preview exposure, opening the app and its first meaningful action are separate. No preview starts a timed run, sound, scare or sensor permission.

Ready to play acceptance checks full-bleed cover composition, named entry-link activation without a visible CTA, overlay control hitboxes, active-only animation, persistent Menu pause and static reduced motion. Verify zero app/media/sensor work before entry, one-card snapping, same-tab launch and both return paths. Test mobile swipes, desktop arrows outside the phone and standalone gameplay at its actual width. See the canonical spec’s Ready to play UI section.

Mobile feed entry, visual continuity and the Rifflet menu — RCF 2.3

Treat every feed entry as a mobile experience. On desktop, open the exact pinned app inside a 430 CSS-pixel viewport in the same tab. On phone-sized windows (up to 700px), retain the top-level full-screen app so camera, motion and native controls keep their normal document context. The desktop host preserves all revision/content parameters and delegates camera only for the reviewed Bone Lens and Skeleton Lens routes, and microphone only for Song Coach; it cannot widen the response permission policy. Return to the selected feed card through browser Back or the common menu. This is responsive viewport hosting, not device emulation. No app code or frame loads before explicit cover entry.

The cover should feel like the first scene of the same experience. Reuse reviewed in-app photographs, painted environments, characters, game objects, interface materials and palettes wherever possible. A photographic game should not become an unrelated flat cartoon; a pixel arcade should retain its pixel language. Compose these into an inviting portrait rather than shrinking a whole page with tiny controls. Small editorial motion should explain the mechanic: water levels, a drifting ferry, a pulsing memory pad, rain reaching chimes, a breathing rhythm. No unexpected sound, scare, permission prompt, fabricated result or live gameplay before entry. Preserve source/license attribution for reused assets and record any static component captures. Load the static cover immediately and reveal the animated composition only after its image assets are ready; failed images retain the static fallback. Honor reduced motion, explicit pause, hidden-page pause and one-active-cover limits.

Provide one easy-to-reach, at least 44px, keyboard-accessible in-app hamburger control with recognizable Riff star branding. Its accessible name covers discovery, making a riff and feedback. The menu prominently contains Find your next Rifflet, ✳ Make a riff, Suggest a riff or feature, and Give feedback / report a problem. Preserve existing app-specific editor behavior, public-feedback consent, exact-release context, drafts, receipts and retry semantics. Do not replace a working editor with a copied prompt. Keep instructions, settings and About in the same menu. Opening it must preserve play state and pause/resume through the common lifecycle. Discovery navigates the outer mobile host, not a nested feed inside the phone. Test both ordinary app visits and feed entry.

The current release adds this navigation through a reviewed host adapter on registered app HTML routes; immutable app artifacts and existing feedback handlers are retained. Arbitrary third-party code must still follow the separate isolation and capability review; a menu wrapper does not confer trust.

The feed’s overlaid action stack also includes an outlined pencil with a named 44px target. This is deliberate entry: it opens the selected exact Rifflet in the mobile host with its common riff/settings/feedback menu already open. The cover itself opens ordinary play. Do not auto-open either experience or settings during passive browsing. Preserve the real app editor and feedback flow; never replace them with a copied prompt.

Submission lifecycle: follow the RCF 2.7.0 revision/approval protocol in [the canonical spec](CANONICAL_RIFFLET_SPEC.md). Use the same creator key and slug plus submissionKind: "revision", exact parentSubmissionId, and revisionNotes for an update; use remix for a separate family. Return previewUrl and adminApprovalUrl from the receipt. An authenticated admin approves an exact version for feed/library placement; later uploads stay pending. Approval preserves the sandbox and does not enable hosted analytics or restricted capabilities.

Realtime party rooms — RCF 2.8.0

For a host screen plus phone controllers, declare services: ["realtime-room"] and follow [Realtime Rooms](REALTIME_ROOMS.md). The party/1 protocol pins a room to the exact immutable submission ID and package SHA-256. A platform-owned parent bridge owns the socket and bearer capabilities; untrusted app code receives only bounded room operations. Keep the artifact frame opaque and external networking blocked. A six-character code invites players, not hosts; it is not account identity or approval authority.

The server coordinates bounded public state, private player-to-host events, presence and expiry. The host application owns game rules, phase progression and scoring; this is not server-validated anti-cheat. Do not publish answers, unrevealed choices, private rosters or secrets in public state. Provide disconnect, quota, expiry and offline fallback UI. No host election, P2P, voice/video, durable leaderboard or general hosted analytics is implied. Preserve the RCF 2.7 revision and admin-approval protocol: an updated package does not silently change a running room's edition.

For uploaded multiplayer content, confirm the actual protocol and deployed room admission contract in REALTIME_ROOMS.md. Premium upload eligibility alone does not establish higher party/1 creation limits; keep local and exhausted-capacity fallbacks.