# Spock Lang

> Create, inspect, validate, run, debug, and modify Spock v0 backend and framework projects using the published npm distribution. Use when turning product requirements into a Spock program; scaffolding or adopting a framework project; changing tables, records, functions, seed data, actor-aware operations, storage, or refusals; generating contracts, TypeScript, or GraphQL; or verifying Spock-backed Uhura behavior.

- Skill: `gridaco/spock-lang` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add gridaco/spock-lang`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gridaco/spock-lang/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gridaco (https://skillmd.com/u/gridaco)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gridaco/spock-lang

---


# Spock Language

Treat the user's request as an executable engineering task. Produce or modify
the program, run the relevant Spock commands, fix failures within scope, and
finish with concrete verification evidence.

Use only the published `spock` npm package. Do not assume the Spock source
checkout, a Rust toolchain, or source-built web assets are available.

## Establish the environment

1. Locate the target directory, `spock.toml`, and existing `.spock` files.
2. Require Node.js 18 or newer. Run `spock --version`; if the command is
   unavailable, install it once with `npm install --global spock@latest`, then
   record the installed version. Use plain `spock` commands afterward.
3. Classify the target as a framework project or a standalone `.spock`
   program. Framework commands operate on a project; `build`, `run`, and `gen`
   operate on an explicit standalone file.
4. Preserve unrelated user changes and never replace an existing model before
   understanding its tables, functions, constraints, seeds, and consumers.

## Select the source of truth

- Treat the globally installed npm CLI as the executable contract.
- Use the bundled references for concise guidance. Consult the
  [Spock v0.5.2 toolchain specification](https://github.com/gridaco/spock/blob/v0.5.2/docs/spec/v0.md)
  when exact syntax or semantics matter; its RFD 0024 additions are explicitly
  marked experimental and non-normative.
- Use the
  [filter lab schema](https://github.com/gridaco/spock/blob/v0.5.2/examples/filter-lab/schema.spock),
  [Instagram backend](https://github.com/gridaco/uhura/blob/662d5435fe082044814b28a0cc7ee6c1e664417f/examples/instagram/backend/app.spock),
  and
  [standalone Instagram program](https://github.com/gridaco/spock/blob/v0.5.2/examples/instagram/v0.spock)
  as current-toolchain examples.
- Do not copy syntax from the
  [Instagram paper program](https://github.com/gridaco/spock/blob/v0.5.2/examples/instagram/v1.spock),
  [vision RFD](https://github.com/gridaco/spock/blob/v0.5.2/docs/rfd/0000-vision.spock),
  or other proposals. They do not override the published compiler.
- Run the installed toolchain instead of guessing whether a construct is
  accepted. If a bundled reference and the installed CLI disagree, preserve
  the installed version's behavior and report the version difference.

Read the bundled references only as needed:

- Read [references/workflows.md](references/workflows.md) before creating,
  adopting, modifying, or repairing a project.
- Read [references/language.md](references/language.md) before authoring or
  substantially changing a `.spock` program.
- Read [references/tooling.md](references/tooling.md) for global CLI
  installation, framework commands, generated artifacts, HTTP checks, Studio,
  storage, or Uhura integration.
- Read [references/limits.md](references/limits.md) before making security,
  production-readiness, persistence, policy, or unsupported-feature claims.

## Follow the execution loop

1. Convert the request into observable acceptance scenarios before editing:
   required data, reads, writes, refusals, actors, storage, and generated
   consumers.
2. Use `spock new` for a new framework project, `spock init` to adopt an
   existing directory, or create one `.spock` file for a standalone program.
   For an existing target, run a baseline check before changing it whenever it
   is expected to load.
3. Make the smallest coherent change. Keep durable source rows authoritative
   and derive display counts or projections in consumers instead of seeding
   decorative totals.
4. Run `spock check` after each meaningful change. Fix the earliest diagnostic
   first and repeat until the complete target checks successfully.
5. Run `spock build` or `spock gen` when a standalone contract or generated
   consumer changes.
6. Run the target and probe the exact affected behavior. Cover success and
   refusal paths, anonymous and actor-bound paths, or storage paths when
   relevant.
7. For framework projects with Uhura, verify the integrated Editor, Play,
   Studio, and the live provider boundary rather than treating fixture output
   as backend proof.
8. Stop processes started for verification and leave no temporary output in
   the user's project unless requested.
9. Report changed files, exact commands, outcomes, unchecked escape count,
   runtime evidence, and material v0 limitations.

## Preserve the language contract

- Prefer declarative constraints over repeating checks in every function:
  keys, references, `unique`, closed sets, and validator functions belong on
  the data.
- Use references for relationships. A reference stores the target table key
  and cannot target a composite-key table in v0.
- Use `auth table` only for the single identity anchor. Treat
  `X-Spock-Actor` as a forgeable development seam, never authentication.
- Use `= me` only on a reference to the auth table. Seed rows must still
  provide required actor-backed fields because seed replay has no actor.
- Use `storage_object` references for files. Move bytes through `/storage/v1`;
  never inline bytes in Spock values or function payloads.
- Keep each `unchecked sql(...)` escape to one statement. Use `:param`
  placeholders only. The final statement must return columns matching the
  declared return contract.
- In the experimental `0.5.2` RFD 0024 preview, declare each product refusal
  once with top-level `error name`, list it in each function's `!` clause, and
  raise it with `spock_refuse`. Do not fake derived or reserved errors.
- Do not introduce `view`, `role`, `policy`, state-machine syntax, modules,
  native function statements, or other reserved or proposed syntax.

## Validate proportionally

Every created or modified target requires at least a check through the globally
installed npm-distributed CLI:

```sh
spock --version
spock check path/to/project-or-app.spock
```

For runtime work, start the project or standalone program on an available port,
wait for `/~health`, probe the changed read or function path, and stop the
process cleanly. Never treat a rendered Studio screen alone as proof of backend
behavior.

## Handle diagnostics

- Fix the earliest diagnostic first; later errors may be cascades.
- Preserve stable `L...` and `E...` codes in reports.
- If `check` reports unchecked escapes, explain that contracts and loadability
  were checked but SQL business logic remains author-asserted.
- If behavior appears version-dependent, report `spock --version`. Upgrade the
  global package only when the user requests the current release or the task
  requires it.