Define the default starter curriculum and first template tiers

[softmarshmallow]

Status

Important

This is a focused design input to #20, not a competing CLI/template-system proposal.

#20 owns final CLI/template-system decisions and implementation. This issue owns the content, teaching, and compatibility contract: what the default generated project should demonstrate, what patterns it should normalize, which example tiers Spock should ship first, and which immutable bytes a released CLI may safely generate. The distribution recommendation below is a concrete input to #20; this issue still does not accept CLI syntax.

Related surfaces:

• CLI onboarding and template system: RFD study: make the Spock CLI batteries-included and agent-native #20
• Canonical Instagram contributor flow: Contributor guide: run the Spock-backed Instagram demo #10
• Landing-page live demo: Embed a live Uhura Editor/Play demo in the spock.sh landing page #27

Why the default project is product doctrine

Spock is not an SDK layered onto a familiar language. A new user or coding agent cannot bring a mature body of Spock/Uhura conventions to an empty directory.

That makes the generated project more than boilerplate. It is simultaneously:

• the first runnable product experience;
• executable documentation for two new languages and their boundary;
• a small repository of endorsed patterns;
• an architectural hint for agents; and
• a statement about what belongs to the authority, experience machine, UI, evidence, and host.

A good default must be small enough to read end to end and rich enough to produce an “aha”: inputs become semantic events; the machine decides what to request; Spock owns durable truth; settlements reconcile optimistic experience state; and evidence makes success and failure inspectable.

A kitchen-sink starter hides that model. An empty project teaches nothing. A disconnected frontend toy can teach Uhura syntax while accidentally teaching that the Spock authority is optional to a “full-stack” project.

Current baseline

Today, spock new NAME creates one deterministic, embedded, offline scaffold:

NAME/
├── spock.toml
├── backend/
│   └── app.spock
└── client/
    ├── uhura.toml
    ├── host.toml
    ├── machine.uhura
    ├── ui.uhura
    └── evidence.uhura

The implementation lives in crates/spock-project/src/starter.rs and crates/spock-project/templates/minimal-client/.

This baseline has useful properties:

• deterministic bytes and no remote template dependency;
• a complete Uhura machine, UI, evidence corpus, and host entry;
• immediate Editor previews; and
• a clear spock new creation versus spock init adoption boundary.

But the backend is intentionally empty and the client is a local counter. The generated topology is full-stack; its demonstrated behavior is not. It does not teach:

• authoritative observation;
• a real Spock-to-Uhura read/write path;
• port and provider ownership;
• pending versus committed state;
• accepted versus refused settlement;
• rollback/reconciliation; or
• how backend and frontend files describe one product behavior.

Proposed default: one optimistic task

The default Spock framework “hello world” should be one seeded task with one optimistic Complete / Undo action.

Task: Ship the first prototype
Action: Complete / Undo
Behavior: update immediately, then settle to authoritative truth or roll back.

This is counter-sized, but it demonstrates the framework boundary rather than only local arithmetic.

Product behavior

1. The authority starts with one seeded task.
2. Play shows its title and current completion state.
3. Pressing Complete or Undo emits a semantic event.
4. The Uhura machine presents the desired state optimistically and sends one correlated request.
5. The Spock authority applies the write and returns authoritative state, or the bridge delivers a typed refusal.
6. Acceptance commits the returned authority; refusal restores the last confirmed observation and shows a notice.
7. Restarting from seed returns the example to a deterministic baseline.

The starter should not add auth, routing, storage, uploads, clocks, external services, a design system, or multiple records. Those are later patterns.

Ownership contract

Fact or responsibility	Owner
Task title and canonical completion value	Spock authority
Last observed authoritative task	Uhura machine cache, explicitly non-authoritative
Pending desired value and request correlation	Uhura machine
Loading, saving, and refusal notice	Uhura session state
Focus, hover, animation, and caret	Renderer
HTTP/GraphQL translation	Bridge only; no domain state
Example observations and settlements	Evidence fixtures, never a second runtime authority

Review the starter across these axes

Backend / authority

• One table, one seed row, and the smallest honest write surface.
• Durable product facts live in Spock; the UI does not become a second authority.
• Success and failure surfaces are explicit and machine-readable.
• Seed replay makes the first run and every test deterministic.
• No accidental pattern such as a decorative materialized counter, hidden global, or client-trusted invariant is normalized.
• Any unchecked authority escape is minimal, explained, and visible in the check ledger.

Frontend machine and state

• Separate last confirmed authority from the pending optimistic overlay.
• Use a semantic ToggleRequested-style event, not a DOM-shaped click event.
• Allow at most one request in flight.
• Correlate settlements by request ID; stale settlements cannot mutate current state.
• Acceptance adopts the authoritative result rather than assuming the optimistic value.
• Refusal rolls back to confirmed truth and records a user-visible notice.
• A newer authority observation has defined behavior while a request is pending.

UI authoring

• One semantic page, one task card, and one action.
• Show loading, ready, pending, accepted, and refused states without introducing a component system.
• Disable or otherwise serialize the action while pending.
• Include accessible labeling and an aria-live status/notice.
• Keep styling deliberately small so structure and state remain legible.

Event and effect handling

• UI emits product events.
• The machine decides commands.
• A declared port carries requests and settlements.
• The bridge translates protocol data but contains no product decisions.
• Duplicate input, late settlement, refusal, and retry behavior are intentional rather than incidental.

Evidence and previews

At minimum, ship checked examples for:

1. loading;
2. ready and incomplete — the default;
3. saving complete — optimistic;
4. saved complete — accepted; and
5. save refused — rollback plus notice.

The evidence should also prove the exact emitted request, duplicate suppression, settlement correlation, accepted-authority adoption, and stale-settlement behavior. Visible examples should derive from scenarios rather than copy another set of hand-maintained state fixtures.

Human and agent readability

• A reader should understand the whole vertical slice in roughly ten minutes.
• Each source file has one obvious responsibility.
• Comments explain ownership and tradeoffs, not syntax that the code already states.
• A short generated README maps product flow to files, lists exact check/dev commands, and suggests one safe extension per axis.
• Set and justify a source budget; a useful starting target is about 200 authored lines total and no file over 100 lines.
• Generated project/module identities must derive from the requested project name rather than silently remaining spock.starter.

Critical integration prerequisite

The default must not require a newcomer to understand or maintain a large handwritten TypeScript provider before they can understand Spock.

The current real integration uses an application-owned app.provider bridge, and unchecked provider ownership is reported by spock check. Before the task flow replaces the counter as the default, choose one of these honest paths:

1. provide a first-party or generated checked Spock↔Uhura adapter for this small read/write contract; or
2. make the bridge tiny, generated, mechanically validated, and warning-free under the supported project check.

Until that prerequisite exists, retain the current counter as the temporary default and expose the integrated task only as an experimental candidate. Do not call an empty-backend plus local-counter behavior the final framework hello world.

Proposed template and example tiers

Do not make every example a CLI template.

Tier	Initial recommendation	Purpose
Default starter	One optimistic task	Smallest endorsed full-stack vertical slice; bundled/offline and generated by default.
Backend-only profile	Preserve the existing explicit opt-out	Empty authority project for backend work; this is a profile, not the teaching default.
Pattern catalog	Begin with bounded reservation after the starter	Small focused, checked examples for one concept at a time. Reservation teaches guarded writes, capacity, named refusal, atomicity, and concurrency better than the default task should.
Flagship product template	Instagram, once publicly reproducible	A complete product-shaped reference for routing, components, actors, media/storage, and many optimistic flows. It must not define normative language syntax.
Future product template	Uber only when runnable and maintained	Keep it as product requirements/design pressure until a complete supported project exists; do not ship a paper or partial harness as onboarding material.

The initial public template set should therefore stay deliberately small:

• the default integrated task starter;
• the existing backend-only creation profile; and
• Instagram as an explicit full template only after the published CLI can create, check, and run it without repository-private setup.

The local counter can remain an Uhura kernel fixture or documentation example. It does not need to become another selectable project template.

A patterns catalog should be curated by concept, not volume. Each pattern should state the problem, ownership rule, tradeoff, exact runnable command, and evidence. It should not compete with the independently grounded product-harness doctrine in examples/README.md.

Template identity, release coupling, and repository drift

A repository page is useful human-facing provenance. It is not, by itself, a stable distribution coordinate.

The concrete failure mode is:

1. spock@X is released with one Uhura grammar, host protocol, sidecar, and framework contract.
2. spock new --template instagram fetches uhura/main/examples/instagram.
3. main later adopts newer syntax, manifests, providers, or runtime assets.
4. The unchanged released CLI now generates a project it cannot check or run.

A new templates repository does not solve this if the CLI still reads spock-templates/main. A plain tag is also only a name unless mutation is prevented. An exact commit identifies source, but a verified assembled artifact is a better public distribution unit when the template spans Spock plus the pinned Uhura submodule.

Reference policy

Source presented to the CLI	Reproducibility	Policy
Bytes embedded in the released CLI/package	Exact and offline	Required for the default starter and backend-only profile.
Immutable release asset plus archive SHA-256	Exact after download; cacheable	Recommended for large official templates such as Instagram.
Exact 40-character commit plus archive/content digest	Immutable source identity, but weaker as a cross-repository assembled product	Supported as a maintainer/debug escape hatch, not the primary official channel.
Immutable release tag plus digest	Acceptable only when the release locks both tag and assets	Human-readable release identity; digest remains authoritative.
main, master, canary, latest, or an unqualified movable tag	Silently changes for an unchanged CLI	Never valid for a supported official template.
Arbitrary URL/repository	User-selected trust and compatibility	Possible future experimental/third-party lane only; never an implicit fallback.

Proposed Spock model: release-coupled hybrid

1. Keep the default embedded. The current starter is already compiled with include_bytes!, so the installed CLI owns exact, deterministic, offline bytes. Give it an explicit template identity/revision and keep the backend-only profile in the same release boundary.
2. Publish rich templates as immutable snapshots. At each supporting Spock release, assemble Instagram from the clean Spock tag and its exact Uhura gitlink, then publish the resulting archive as an immutable asset of that Spock release. A versioned npm artifact is an equivalent transport if package size later makes that preferable; do not fetch an authoring branch.
3. Ship the resolution manifest with the CLI. An official template ID resolves through metadata frozen into that CLI release, not through a live catalog. Reuse the provenance and integrity discipline already implemented by npm/scripts/sidecar.mjs and the npm release workflow: exact Spock and Uhura commits, protocol/schema identity, complete sorted file inventory, per-file size/SHA-256, and an archive digest.
4. Cache by content digest. Download to a temporary location, enforce safe path/file/size rules, verify the complete manifest and archive digest, then atomically install under a content-addressed cache. Bundled templates always work offline. A rich template works offline only when already cached; a cache miss must fail clearly and must never fall back to main, latest, or a different revision.
5. Retain and identify old bytes. Publishing a fix creates a new template revision and release artifact; it does not replace or delete an old artifact. A generated project records the CLI version, template ID/revision, source commits, and digest in machine-readable provenance so humans and agents can reconstruct its origin.
6. Test the packed artifact, not only source. Release CI must extract each published template and run the supported spock check, bounded spock start/spock dev, and browser smoke against the exact packaged CLI/sidecar combination.

An illustrative frozen entry is:

{
  "protocol": "spock-template/1",
  "id": "instagram",
  "template_version": 1,
  "spock_version": "0.6.0",
  "spock_commit": "<40-hex>",
  "uhura_commit": "<40-hex>",
  "artifact": "https://github.com/gridaco/spock/releases/download/v0.6.0/spock-template-instagram-v1.tar.zst",
  "sha256": "<64-hex>",
  "files": [{ "path": "spock.toml", "size": 123, "sha256": "<64-hex>" }]
}

The exact manifest and generated provenance filenames remain #20 implementation decisions. The invariant is that the same released CLI plus template ID/revision resolves to the same verified source bytes, aside from explicitly specified substitutions such as the project name.

Do we need a separate repository?

Not initially. Keep authoring ownership with the product that validates the source: the framework starter in Spock and the canonical Instagram project in the pinned Uhura submodule. Let the Spock release own the assembled, supported artifact.

Create a repository such as gridaco/spock-templates only when independent maintainers, a distinct release cadence, third-party intake, or a large catalog creates a real ownership boundary. Even then, its main branch is authoring source—not a CLI endpoint. Spock must still consume an immutable release asset or exact commit plus digest.

If release assets are the transport, enable GitHub immutable releases so the tag and assets are locked and attested, while retaining digest verification in the CLI.

Prior art and the lesson for Spock

• Flutter ships named templates inside the installed SDK, coupling scaffold bytes to the SDK release.
• Vite includes its template-* directories in the versioned create-vite package, giving the default scaffold the package release boundary.
• Expo distinguishes SDK-versioned templates such as default@sdk-57 from live examples. That supported-template versus evolving-example split maps well to Spock.
• Next.js keeps its default templates in the CLI but downloads named repository examples from its moving canary archive. This is convenient discovery, not the compatibility guarantee Spock should copy for official templates.
• Astro templates resolve a repository branch and permit an explicit --ref; without a frozen ref and digest, that remains a moving-example model.
• Rails bundles its normal generator templates but allows an explicit local or HTTP application template. That explicit user-controlled customization is a reasonable future lane, separate from supported defaults.

The policy to copy is Flutter/Vite/Expo for official supported templates: release-coupled defaults and explicit version identities. The Next/Astro/Rails remote forms are useful only as future example or user-controlled extension lanes, not as the implicit source of Spock's product doctrine.

Alternatives to record

The study should explicitly compare at least:

• local counter — smallest Uhura syntax sample, but no authority boundary;
• optimistic task — proposed default; one boolean and a full settlement loop;
• bounded reservation — stronger invariant/refusal lesson, but introduces capacity, attendee identity, guarded mutation, and currently more backend/bridge machinery;
• todo list or guestbook — familiar, but collections, forms, validation, and CRUD can obscure the first framework idea; and
• Instagram — excellent flagship proof, too large to be the default reading surface.

The final choice should be based on teaching value per line and correctness of the product boundary, not familiarity alone.

Expected outcome

This issue should produce:

• a written default-starter product and ownership contract;
• the exact generated tree and file-by-file teaching purpose;
• a reviewed backend/frontend/event/evidence behavior matrix;
• a decision on the provider prerequisite;
• a small initial template/pattern/showcase taxonomy;
• a readability and dependency budget;
• an immutable template identity and release-coupling recommendation;
• a manifest, cache/offline, retention, and generated-provenance contract;
• release-CI conformance requirements for every supported artifact;
• explicit alternatives and reasons for rejection; and
• concrete inputs for RFD study: make the Spock CLI batteries-included and agent-native #20's template-system and CLI decisions.

Acceptance criteria for the eventual default

• From a clean supported machine, spock new demo, spock check demo, and spock dev demo work without manual source edits or private repository knowledge.
• Play demonstrates a real read/write path across Uhura → bridge → Spock authority → settlement.
• The generated project has no unresolved link warnings, handwritten provider requirement, remote assets, credentials, or extra package-install step.
• Checked evidence covers loading, ready, optimistic, accepted, refused/rollback, duplicate input, and stale settlement.
• A browser smoke test proves optimistic update, accepted settlement, and rollback.
• The starter remains understandable as one vertical slice and respects the agreed source budget.
• Project names are substituted consistently across manifests and module identities.
• Scaffold snapshots, quickstart/docs, public skills, website project tree, and packaged-CLI smoke tests stay synchronized with the canonical starter.
• spock init remains adoption-only.
• The same released CLI plus template ID/revision resolves to the same verified bytes, except for documented substitutions such as project name.
• No supported official template resolves main, master, canary, latest, or another movable ref.
• Every non-embedded official template has a frozen manifest containing compatibility/schema identity, exact Spock and Uhura commits, archive digest, and complete file inventory.
• The default starter works offline; rich-template cache hits and cache misses have explicit behavior with no compatibility fallback.
• Release CI validates the extracted artifact with the exact packaged CLI and runtime assets before publication.

Non-goals

• selecting final command flags or interactive prompts;
• implementing the downloader, registry, cache, upgrade UX, or arbitrary third-party template support in this issue; the final mechanism remains RFD study: make the Spock CLI batteries-included and agent-native #20;
• turning spock init into a scaffold command;
• shipping a large template marketplace;
• teaching auth, routing, storage, deployment, or a design system in the default;
• treating Instagram or Uber as the language specification; or
• implementing the starter before its bridge and ownership contract can be honest.