rote-shell

Use for CLI and shell work through rote when command output, files, logs, process state, dependency checks, mixed API/browser evidence, or crystallized CLI plays must be remembered, queried, replayed, or shared.

Jump to install

Repository: modiqo/rote-skills
Last source activity: August 14, 2026 at 11:20
Detected SKILL.md language: English
Stars: 0
Forks: 1

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/modiqo/rote-skills --skill rote-shell

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

SKILL.md

Source instructions · Read-only preview

name	rote-shell
description	Use for CLI and shell work through rote when command output, files, logs, process state, dependency checks, mixed API/browser evidence, or crystallized CLI plays must be remembered, queried, replayed, or shared.

rote-shell

All rote-<name> references in this document — including every name in the Handoff Contract — are companion skills, never CLI commands (rote-shell is not rote shell). Invoke them through the runtime's skill mechanism; only literal rote … commands run in a terminal.

Use rote for shell and CLI work when the result should become workspace memory: commands, outputs, files, logs, process lifecycle, dependencies, and play replay. Raw shell is still fine for tiny inspection commands, but work that matters should pass through rote so it can be queried, audited, and crystallized.

Load the shell guidance when you need the complete command model:

rote guidance shell essential

First Decision

Choose the narrowest rote primitive that preserves evidence:

one-shot command: rote proc run -- <program> [args...]
stdin from a file: rote proc run --stdin-file input.txt -- <program>
declared output file: rote proc run --capture-file label:path -- <program>
moving file/log: rote proc stream follow --file logs/server.log --until READY
long-running process: rote proc run --background --ready-log READY -- <program>
process stream: rote proc stream follow-process proc-1 --stream stdout --until READY
terminal-sensitive command: rote proc pty run -- <program> [args...]
dependency preflight: rote deps check deps.toml

name	rote-shell
description	Use for CLI and shell work through rote when command output, files, logs, process state, dependency checks, mixed API/browser evidence, or crystallized CLI plays must be remembered, queried, replayed, or shared.

rote-shell

Load the shell guidance when you need the complete command model:

rote guidance shell essential

First Decision

Choose the narrowest rote primitive that preserves evidence:

one-shot command: rote proc run -- <program> [args...]
stdin from a file: rote proc run --stdin-file input.txt -- <program>
declared output file: rote proc run --capture-file label:path -- <program>
moving file/log: rote proc stream follow --file logs/server.log --until READY
long-running process: rote proc run --background --ready-log READY -- <program>
process stream: rote proc stream follow-process proc-1 --stream stdout --until READY
terminal-sensitive command: rote proc pty run -- <program> [args...]
dependency preflight: rote deps check deps.toml

# Rote Shell Handoff Summary

- Active skill: `rote-shell`
- Origin skill: `rote` or `rote-...`
- User intent: ...
- Workspace path: ...
- Working directory: ...
- Commands run: ...
- Cached responses: ...
- Process leases: ...
- Captured artifacts: ...
- Requirements: ...
- Current gate: shell execution, dependency approval, background wait, cleanup, save gate, or blocker
- Result: ...
- Save gate: pending, accepted, discarded, or not applicable
- Next skill: `rote-flow-crystallization`, `rote-flow-authoring`, `rote-troubleshooting`, `rote`, or none
- Blockers: ...
- Completion signal: ...

rote browser attach setup --method extension --browser chrome
rote browse <url> --headed --attach-existing --new-tab --no-prompt --no-snapshot
rote browse wait --selector '<ready-selector>' --timeout 30 --quiet-ms 750
rote browse snapshot

Need	Shipped command	Notes
One-shot process capture	`rote proc run -- <program> [args...]`	Direct argv by default.
File stdin	`rote proc run --stdin-file input.txt -- <program>`	Records stdin provenance.
Declared output file	`rote proc run --capture-file label:path -- <program>`	Captures file metadata and artifact pointer.
Saved stdout/stderr files	`rote proc run --stdout-file out.txt --stderr-file err.txt -- <program>`	Use for durable stream files.
Dependency preflight	`rote deps check deps.toml`	No install side effects.
Moving file/log stream	`rote proc stream follow --file app.log --until READY`	Supports offsets, chunks, hashes, and pattern stop.
Background start	`rote proc run --background --ready-log READY -- <program>`	Creates a tracked lease such as `proc-1`.
Background status	`rote proc status proc-1`	Query lease state before acting.
Background wait	`rote proc wait proc-1 --timeout-ms 300000 --poll-ms 500`	Blocks until a tracked finite job exits or times out; records exit plus stdout/stderr observations.
Background stdout/stderr follow	`rote proc stream follow-process proc-1 --stream stdout --until READY`	Reads from background log artifacts.
Background stop and cleanup	`rote proc stop proc-1`	On Unix, stops the process group and records cleanup facts.
One-shot terminal transcript	`rote proc pty run -- <program> [args...]`	Use when the command must see a terminal.

Pattern	SDK call
Durable one-shot	`await rote.exec({ argv: ["git", "status", "--short"], deps: ["git"] })`
Declared stdin/output files	`await rote.exec({ argv, stdin: { file }, capture: { stdout: { file }, files: [{ label, path }] } })`
Dependency preflight	`await rote.depsCheck({ manifest: "deps.toml" })`
Tracked background job / detach-like work	`await rote.execBackground({ argv, readyLog, readyTimeoutMs, capture })`
Long-running job with useful work to do while it runs	`await rote.execBackgroundAndJoin(request, async (job) => { ... }, { timeoutMs, pollMs, stopOnWorkError })`
Lease status	`await rote.execStatus("proc-1")`
Lease wait	`await rote.execWait("proc-1", { timeoutMs: 300_000, pollMs: 500 })` or `await job.wait(...)`
Lease cleanup	`await rote.execStop("proc-1")`
Moving file stream	`await rote.followFile("logs/app.log", { until: "READY" })`
Background process stream	`await rote.followProcess("proc-1", "stdout", { until: "READY" })`
One-shot PTY transcript	`await rote.ptyRun({ argv, cols: 100, rows: 30 })`
Authored ordered fan-out	`await rote.execMany(requests, { stopOnError: false })`

const proc = await rote.exec({ argv: ["git", "status", "--short"], deps: ["git"] });
const text = await proc.stdout.text();   // stderr mirror: proc.stderr.text()
const exit = await proc.exit();          // { kind: "code", code } | { kind: "signal", … }
if (exit.kind !== "code" || exit.code !== 0) {
  throw new Error(`git failed: ${await proc.stderr.text()}`);
}
const files = await proc.files();        // captured file artifacts ([] unless capture requested)

Exploration pattern	Crystallized shape	Author via
One finite command whose output is the fact	Default steps + presentation export with a typed `process.exec` step	No-shape-flag `rote workspace export ~/.rote/flows/<name>/main.ts`
Command writes files that downstream work reads	Default steps + presentation export with declared `process.exec` captures	No-shape-flag `rote workspace export ~/.rote/flows/<name>/main.ts`
A moving file or log must be followed to an until/readiness condition (the stream capability)	Explicit legacy body with `rote.followFile(path, options)`	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Long finite job where other useful work runs mid-lease (the concurrent-work capability)	Explicit legacy body with `rote.execBackgroundAndJoin(request, async (job) => { ... }, options)`	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Long service or daemon the play interacts with while it runs	Explicit legacy body with `rote.execBackground({ readyLog, capture })`, then status/follow/stop	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Need to inspect progress mid-lease, inside a justified background escape	Explicit legacy body with `job.follow(...)` or `rote.followProcess(...)`	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Need completion proof mid-lease, inside a justified background escape — a finite command with no concurrent work is a foreground `process.exec` step with `timeout_ms:`	Explicit legacy body with `job.wait(...)` or `rote.execWait(...)`	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Terminal behavior is the point	Explicit legacy body with `rote.ptyRun({ argv, input, cols, rows })`	Hand-author `main.ts` (legacy example below); run via `rote deno run --allow-all`
Several independent commands run at once	declarative `steps:` with sibling `process.exec` steps, no `depends_on` between them	Export first, then drop the synthesized `depends_on` edges per `rote grammar steps`
Many independent commands share one shape	declarative `steps:` with `process.exec`, `for_each`, and `max_concurrency`	Export first, then add `for_each`/`max_concurrency` per `rote grammar steps`
The item set is discovered at run time by another command or API call	declarative `steps:` fan-out sourced from the upstream step	NOT a legacy trigger; `rote grammar steps` has the bridge example for a process step's JSON stdout
One finite command needs more than the default 30s step budget	`timeout_ms:` on the `process.exec` step, or per-item fan-out so each item gets its own budget	`rote grammar steps` documents the budget

rote guidance typescript play-creation

Signal	Pattern	Use
Tiny disposable inspection	Raw shell allowed	direct harness shell
Result may be queried, compared, summarized, or replayed	Durable one-shot	`rote proc run --`
Command reads a known file	Declared file input	`rote proc run --stdin-file` or a direct argv path
Command creates a file that matters	Declared file output	`rote proc run --capture-file`
Full stdout/stderr matters	Durable stream files	`--stdout-file`, `--stderr-file`
Required tools or input files matter	Dependency gate	`deps.toml` plus `rote deps check`
Existing log is moving	File stream watch	`rote proc stream follow --file`
Start a server or daemon-like process	Service lease	`rote proc run --background --ready-log`
Long finite non-interactive job	Tracked background job	`rote proc run --background --stdout-file --stderr-file`
Inspect background output	Process stream observation	`rote proc stream follow-process`
Need liveness before acting	Lease status	`rote proc status`
Need cleanup	Lease cleanup	`rote proc stop`
Many independent items share a command shape	Fan-out batch	`steps:` with `process.exec`, `for_each`, and `max_concurrency`
Item set discovered at run time by an upstream step	Fan-out over step output	`steps:` with `for_each` sourced from the upstream step — not a legacy trigger; see `rote grammar steps`
API result feeds CLI or CLI result feeds API	Mixed substrate chain	adapter/browser primitive plus `rote proc run`
Browser snapshot/file feeds local CLI	Browser-file bridge	browser snapshot/file plus `rote proc run`
Release, publish, deploy, or global mutation	Guarded mutation	deps check, tool-native dry-run, approval, then foreground unless background is approved
Command checks whether stdout is a terminal	One-shot PTY transcript	`rote proc pty run --`
Command may prompt interactively and can be scripted safely	One-shot PTY with bounded input	`rote proc pty run --input` or `--stdin-file`
Command needs ongoing human interaction	Foreground or defer	persistent PTY attach is not shipped

rote init cli-work --seq --force
cd ${ROTE_HOME:-$HOME/.rote}/rote/workspaces/cli-work && rote model set <model> --provider <provider> --confirmed-current
cd ${ROTE_HOME:-$HOME/.rote}/rote/workspaces/cli-work && rote workspace sandbox cli-work off

rote proc run -- rg TODO docs

rote proc run -- sh -c 'printf "alpha\n" | tr a-z A-Z'

rote query @1 '.stdout.text' -r
rote query @1 '.stderr.text' -r
rote query @1 '.status.exit' -r
rote query @1 '.files' -r
rote query @2 '.cleanup' -r

rote query @proc.last.stdout '.text' -r
rote query @proc.1.exit '.' -r
rote query @proc.last.transcript '.text' -r

rote proc run \
  --stdin-file input.txt \
  --capture-file summary:out/summary.txt \
  -- python3 scripts/summarize.py

rote proc run --background --ready-log "Listening" --ready-timeout-ms 10000 -- npm run dev
rote proc status proc-1
rote proc stream follow-process proc-1 --stream stdout --until "GET /health"
rote proc stop proc-1
rote query @3 '.cleanup' -r

rote proc run \
  --background \
  --stdout-file logs/job.stdout.log \
  --stderr-file logs/job.stderr.log \
  -- cargo test --all-targets --all-features

rote proc status proc-1
rote proc wait proc-1 --timeout-ms 600000 --poll-ms 1000
rote proc stream follow-process proc-1 --stream stdout --from-start --max-bytes 65536
rote proc stream follow-process proc-1 --stream stderr --from-start --max-bytes 65536

const joined = await rote.execBackgroundAndJoin(
  { argv: ["cargo", "test"], deps: ["cargo"] },
  async (job) => {
    const checks = await rote.exec({ argv: ["gh", "pr", "checks"], deps: ["gh"] });
    const stderr = await job.follow("stderr", { fromStart: true, maxBytes: 65536 });
    return { checks, stderr };
  },
  { timeoutMs: 600_000, pollMs: 1_000, stopOnWorkError: true },
);

rote proc pty run --cols 100 --rows 30 -- script-that-checks-tty
rote proc pty run --input "yes\n" -- interactive-but-scriptable-command
rote query @proc.last.transcript '.text' -r

const proc = await rote.ptyRun({ argv: ["sh", "-c", "test -t 1 && echo interactive || echo piped"], cols: 100, rows: 30 });
const transcript = await proc.transcript.text(); // raw transcript, ANSI escapes included
const exit = await proc.exit();                  // { kind: "code", code } | { kind: "signal", … }
if (exit.kind !== "code" || exit.code !== 0) throw new Error("capture failed");

schema_version = 1

[[tools]]
id = "github-cli"
command = "gh"
required = true
version_requirement = ">=2.0.0"

[files]
required = ["input.txt"]

cd ~/.rote/flows/<name>
rote deps check deps.toml

The play needs these missing tools before replay:
- gh: required for GitHub PR and Actions checks

I can install/provision them using one of these scopes:
- rote-managed/project-local: preferred when available; keeps replay isolated
- user/global package manager: broader machine mutation; requires explicit approval

Do you want me to install/provision the missing tools, or should I leave the
play in draft until you install them?

cd ~/.rote/flows/<name>
rote deps check deps.toml

rote POST /github '{"method":"GET","path":"/repos/$owner/$repo"}' -t -s
rote proc run -- gh repo view "$owner/$repo" --json name,visibility
rote query @1 '.' -r
rote query @2 '.stdout.text' -r

# Any play with frontmatter steps
rote play run ~/.rote/flows/<name>/main.ts param=value

# Explicit legacy body with no steps
rote deno run --allow-all ~/.rote/flows/<name>/main.ts [args]

@repo_adapter{.full_name}

rote-shell

Install options

Review the source files

rote-shell

First Decision

rote-shell

First Decision

Adapter-First Boundary

Handoff Contract

Handoff Packet

Handoff Summary

Browser Intent Router

Current Capability Map

TypeScript SDK Pattern Map

Crystallization Router

Play Runtime Boundary

Strategy Pattern Library

Workspace Setup

Query After Every Meaningful Step

Files And Artifacts

Background Processes

Long-Running Finite Jobs

One-Shot PTY

Dependency Manifests

Mixed Workflows

Crystallization Handoff

Step Reference Rules For Mixed DAGs

rote-shell

Source facts

Install options

Review the source files

More from this repository

More from this repository

rote-shell

First Decision

rote-shell

First Decision

Adapter-First Boundary

Handoff Contract

Handoff Packet

Handoff Summary

Browser Intent Router

Current Capability Map

TypeScript SDK Pattern Map

Crystallization Router

Play Runtime Boundary

Strategy Pattern Library

Workspace Setup

Query After Every Meaningful Step

Files And Artifacts

Background Processes

Long-Running Finite Jobs

One-Shot PTY

Dependency Manifests

Mixed Workflows

Crystallization Handoff

Step Reference Rules For Mixed DAGs