Documentation/02 · Work with plays

Work with plays

Where you are in the journey: you can run a play from a URI. Now plays become part of how you work — you find them instead of re-deriving work, you trust them because you can inspect them, and you share them because a URI travels anywhere text does.

The habit that pays for everything

The core loop of this product is a question you learn to ask before doing repeatable work:

"Has someone already crystallized this?"

Search answers it:

ROTE/bash2 lines
rote play search "dns propagation"rote play search "vulnerability lockfile"

Search covers the plays you have locally and the registry you're signed into. When a play covers your task, running it beats re-doing the work every single time: the play version is tested, parallelized, resumable, and honest about what it couldn't reach. When no play covers it — that's the signal you're about to do work worth crystallizing (section 3).

Reading a play card

rote play inspect <uri> is your due-diligence tool. A card looks like this:

ROTE/text17 lines
ROTE PLAY play-dagmodiqo · public organization play Parses the rote frontmatter of any play and draws its step DAG in threeformats at once — an ASCII layer view for the terminal, Mermaid for anythingthat renders markdown, and a canonical JSON graph for machines. … ACCESSServices           noneWrites             none declaredAuthentication     nonePrivileged access  process PARAMETERSplay               (required) Path, owner/name, or canonical https play URI

Read the ACCESS block the way you'd read a mobile app's permission prompt:

  • Services — which external endpoints/adapters it calls
  • Writes — whether it mutates anything (most good plays are read-only; destructive plays gate mutations behind an explicit flag like apply=true)
  • Authentication — what credentials it needs, if any
  • Privileged access — process means it runs local processes on your machine

Versions: pin or float

ROTE/bash2 lines
rote play run https://play.modiqo.ai/modiqo/hello              # latest released versionrote play run https://play.modiqo.ai/modiqo/hello@0.2.0        # this exact version, forever

Published versions are immutable — @0.2.0 will serve the same bytes next year. The versionless URI floats to the newest release. Rule of thumb: float in interactive use, pin in runbooks and CI.

Where plays live on your machine

Running or pulling a play materializes it under ~/.rote/flows/<owner>/<name>/:

ROTE/text4 lines
~/.rote/flows/modiqo/dns-propagation-check/  main.ts         # the play itself — frontmatter contract + presentation  deps.toml       # the tools it needs (and how to install them)  manifest.json   # generated metadata

Plays are source-visible by design. main.ts is right there; the frontmatter at the top is the executable specification. Suspicious? Read it. Curious how it parallelizes? Read it. That transparency is why the inspect-then-run habit is cheap.

rote registry play pull modiqo/hello        # fetch without running

X-ray any play: play-dag

One of the best ways to understand a play — before running it, or while learning to write your own — is to visualize its step graph. There's a play for that:

ROTE/bash2 lines
rote play run https://play.modiqo.ai/modiqo/play-dag \  play=https://play.modiqo.ai/modiqo/email-domain-readiness
ROTE/text14 lines
PLAY DAG  …/email-domain-readiness/main.ts10 steps · 3 layers EXECUTION LAYERS (what the runner parallelizes)  layer 1  validate_input  layer 2  check_caa · check_dkim · check_dmarc · check_dnssec · check_mta_sts · check_mx · check_spf · check_tls_rpt  layer 3  assess_readiness EDGES  validate_input  ──ordering──▶  check_mx  validate_input  ──value {$.stdout.text | fromjson | .domain}──▶  check_mx  … MERMAID (paste anywhere that renders markdown)

It emits an ASCII layer view, a Mermaid graph, and canonical JSON — three renderings of one model, so what you see in the terminal is exactly what a machine gets from --output=json. (That guarantee has a name — representation parity — and section 6 shows how it's kept.)

Sharing: the URI is the deliverable

When you want a teammate to have what you have, you don't send a script, a gist, or a "works on my machine" tarball. You send the URI:

ROTE/text1 line
https://play.modiqo.ai/modiqo/website-launch-readiness

Opening it in a browser describes the play; handing it to rote play run executes it. Same string, both audiences.

Visibility controls who that works for:

ROTE/bash2 lines
rote registry play visibility modiqo/archive-analytics private   # org members onlyrote registry play visibility modiqo/archive-analytics public    # anyone can resolve it
  • public — anyone can read the card and pull it; running an org's play can still require org membership.
  • private — only the owner and org members see it exists.

Flipping visibility doesn't retract copies people already pulled — treat it as access control for the future, not a recall mechanism.

Your inventory

rote play run https://play.modiqo.ai/agent-operations/registry-play-inventory

Lists the plays visible to your profile, ranked by downloads and grouped by organization — a quick map of what your org has already crystallized, which is often the fastest answer to "has someone done this?".

*You are now a play user in full.* You can find, vet, pin, and share. The natural next step is the other side of the loop: the day your search comes up empty.

Next: 3 · Create your first play →