RFD study: make the Spock CLI batteries-included and agent-native

[softmarshmallow]

Status

Important

This issue records product and tooling research toward a possible public-CLI RFD. It does not accept command spellings, a template format, telemetry, or implementation work.

Roadmap: #1
Maintainer demo baseline: #10
Deployment boundary: #19

This is a pre-v1 priority. The onboarding system is needed to demonstrate and dogfood Spock now; it should not wait for the language to become mature.

Thesis

Spock is new. We should assume an early user—or an agent acting for one—will not know enough Spock and Uhura to assemble a correct project from a blank authority file and a minimal client.

That makes the CLI more than developer convenience. Before an ecosystem, tutorials, and community knowledge exist, the CLI is the primary:

• go-to-market surface;
• first product experience;
• executable documentation;
• demo and evaluation path;
• guardrail around the intended project shape; and
• context source for coding agents.

The public path used by maintainers to demo Spock should be the same path a new user receives. Private setup knowledge, manual file copying, and repository-checkout-only examples are product failures even if the language itself works.

Current baseline and gap

Today, spock new NAME creates one deterministic embedded starter:

• spock.toml;
• an intentionally empty backend/app.spock; and
• a six-file minimal Uhura client.

--backend-only removes the client. spock init [PATH] is deliberately different: it adopts existing sources without moving or overwriting them. That clear new versus init boundary from RFD 0022 should be preserved.

The current embedded starter is visible in starter.rs. It proves safe, deterministic scaffolding, but it does not yet give a new project:

• a meaningful backend and seeded round trip;
• a choice of templates or examples;
• a project README;
• a link to the WIP spock.sh site and version-matched docs;
• project-local agent instructions or skills;
• .gitignore, environment examples, CI, or editor recommendations;
• dependency/toolchain setup and health checks;
• database reset/seed lifecycle commands;
• an upgrade or template migration path; or
• machine-readable creation output for agents and CI.

Spock already publishes spock-lang and uhura-lang skills, but installing them is a separate manual action. The canonical Instagram project proves the full system and should be promoted as a first-class official template rather than remaining repository knowledge.

Desired first-run experience

The exact syntax is open, but the product outcome should feel approximately like this for a human:

npx spock new my-app
# choose a recommended starter or the flagship Instagram template
cd my-app
npx spock dev

And it must have a fully equivalent, non-interactive form for agents and CI:

npx --yes spock@<version> new my-app --template instagram --yes
spock check my-app

A successful run should leave a meaningful, self-explaining, checkable project—not a directory that still requires undocumented design and setup decisions before the user can see why Spock exists.

Batteries to study

1. Runnable project content

Every recommended scaffold should be evaluated for:

• a working Spock authority and Uhura client with at least one visible, end-to-end read/write path;
• representative seed data, fixtures, scripts, and only the assets needed by that template;
• a generated README.md with exact install, edit, check, dev, start, reset, build, and next-step commands;
• links to spock.sh, version-matched reference documentation, and known limitations;
• a generated AGENTS.md plus project-local, version-matched Spock/Uhura Agent Skills;
• .gitignore, safe .env.example files, and a clear secret boundary;
• optional Git initialization and an inspectable initial commit;
• editor recommendations once the Spock extension has a supported installation path;
• a minimal CI workflow that runs the public validation path; and
• generator provenance: CLI version, template identity/version, and any selected options.

The default starter should work immediately. The Instagram template should exercise the real product surface—authority, seeded data, storage, Editor, and Play—without requiring maintainers' private setup steps.

2. Creation and template UX

Study a coherent surface for:

• recommended defaults plus an interactive wizard;
• equivalent --yes and explicit flags for every prompt;
• named-directory and current-directory creation;
• listing, describing, and selecting official templates/examples;
• package-manager detection/selection where dependencies are needed;
• install and --skip-install behavior;
• Git and --no-git behavior;
• dry-run/plan output before writes;
• summarized created/changed files after success;
• atomic failure and exact recovery instructions;
• overwrite, merge, and existing-directory policies;
• template compatibility with the invoking CLI version; and
• an official-template registry model versus templates embedded in the npm package.

Remote templates introduce drift and supply-chain questions. The study must compare bundled templates, release-pinned remote templates, commit-addressed templates, integrity manifests, package-size cost, offline creation, and whether arbitrary third-party templates are in scope at all.

3. Agent-native behavior

“Works with an agent” needs testable meaning:

• no TTY is required when all choices are supplied;
• prompts, progress decoration, and color never corrupt machine-readable output;
• stable exit status and diagnostics distinguish usage, validation, network, install, and filesystem failures;
• a structured result mode can report selected template, generated files, skipped steps, warnings, and next commands;
• generated instructions tell an agent which files are authoritative and which commands prove correctness;
• Agent Skills use the open, portable SKILL.md format rather than one vendor-only rules file;
• skills and instructions match the generated project's Spock/Uhura versions;
• both local and cloud agents receive the same project-scoped guidance; and
• the public CLI—not a source checkout—is sufficient to create, inspect, validate, run, and repair the project.

The study should decide whether skills are copied into the project, installed through the existing skills catalog, referenced by a lock/manifest, or refreshed by a later upgrade command.

4. Ongoing lifecycle

A batteries-included CLI does not end after file creation. Evaluate:

• info for environment and project facts useful in bug reports;
• doctor for toolchain, manifest, generated-provider, asset, port, version, and common setup failures;
• reproducible seed/reset commands;
• upgrade and non-destructive template/config migrations with dry-run and diff;
• a composable add or profile mechanism for optional capabilities;
• shell completion and discoverable examples;
• exact remediation links in diagnostics; and
• transparent, documented opt-out if anonymous telemetry is proposed at all.

Deployment profiles and generated CI/deploy adapters depend on #19. This issue should define the onboarding and extension seams without deciding the hosting architecture in advance.

Prior art

Mature ecosystems converge on a runnable default, official templates, explicit non-interactive controls, and lifecycle tooling:

Ecosystem	Relevant precedent
create-next-app	Recommended defaults, interactive customization, --yes, package-manager selection, official/GitHub examples, skip-install, and Git controls.
Rails	A runnable application with README and project structure by default; generators and application templates provide coherent configuration. Rails generators also support preview/force/skip behavior.
Supabase CLI	Project init/start plus migrations, seeds, reset, linked environments, and generated types. Its Agent Skills install at project scope by default so contributors and cloud agents share guidance.
Expo	Recommended templates and a separate examples catalog, non-interactive creation, package-manager setup, and—by default—generated AGENTS.md plus agent configuration tied to the project version.
Astro	Guided creation, official or GitHub templates, and integrations selected during creation without losing a short default path.
shadcn CLI	Separate init/add lifecycle, presets, registries, search/view, dry-run, and diff. Its GitHub registries can distribute docs, rules, tests, workflows, and conventions—not just source components.
Storybook CLI	Feature-aware creation, doctor, dry-run automigrations, environment info, and ai setup, which emits project-aware Markdown instructions for an agent.
Cloudflare Wrangler	Detects an existing project, proposes adapters/config/scripts, supports dry-run and non-interactive setup, and keeps generated changes reviewable.

These are patterns to compare, not a mandate to copy every command.

Decisions this study must produce

1. What is the smallest recommended project that demonstrates Spock's value immediately?
2. Is Instagram the default, a named flagship template, or one layer above a smaller working starter?
3. Which files belong in every generated project, and which are template/profile-specific?
4. How are official templates authored, tested, versioned, distributed, cached, and retired?
5. How do new, adoption-only init, and any future add surface stay conceptually distinct?
6. What exact compatibility promise connects a CLI release, template version, generated project, skills, and documentation?
7. What is the project-scoped skill layout, and how are skills updated without overwriting user customizations?
8. Which structured outputs and stable diagnostics make the CLI reliable for agents and CI?
9. Which lifecycle commands are genuinely required before v1: doctor, info, reset/seed, upgrade/migrate, template listing, or others?
10. Which parts must work offline, and which may fetch versioned remote material?
11. What telemetry, if any, is justified for measuring onboarding failure, and what privacy/opt-out contract governs it?
12. Can the existing spock command own this coherently, or does template/lifecycle complexity justify a dedicated generator or subsystem?

Constraints and non-goals

• Do not implement or accept CLI syntax through this issue.
• Do not make users or agents author a full project from blank files before seeing a working result.
• Do not overload adoption-oriented spock init with destructive scaffolding.
• Do not make the Instagram template normative language syntax or the only supported project shape.
• Do not make one agent vendor's configuration the sole source of project guidance.
• Do not execute arbitrary remote template code or overwrite existing work without an explicit, reviewable policy.
• Do not require a Spock source checkout for the supported onboarding path.
• Do not hide setup failures behind a successful exit code.
• Do not decide self-hosting or provider-specific deployment in this issue; coordinate that work through RFD study: self-hostable artifacts and user-owned deployment #19.
• Do not defer the public onboarding path until v1.

Expected outcome

The study should produce:

• a written default-project contract;
• a template and versioning model;
• an agent-skill packaging/update model;
• a human and non-interactive CLI UX;
• the minimum pre-v1 lifecycle command set;
• security, atomicity, offline, compatibility, and telemetry policies;
• conformance fixtures for every official template; and
• a prioritized implementation sequence that maintainers can dogfood through the published npm CLI.

Success means:

• a new human reaches a populated, working Editor/Play experience from a clean supported machine with one documented creation flow and no private knowledge;
• an agent can reproduce the same result without a TTY, understand the generated repository, make a change, run the right checks, and report structured evidence;
• CI can recreate and validate every official template deterministically;
• the generated repository explains how to run, validate, extend, upgrade, and seek help;
• the Instagram demo is creatable through the public product rather than copied from the source tree; and
• maintainers use this same path for demos before v1.

Only after these decisions are sufficiently studied should the project decide whether they require a sponsored repository RFD or an ordinary tooling implementation plan.