Rote Shell

rote-shell

Use rote for shell and CLI work when the result should become workspace memory: commands, outputs, files, logs, process lifecycle, dependencies, and flow 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 exec -- [args...]
• stdin from a file: rote exec --stdin-file input.txt --
• declared output file: rote exec --capture-file label:path --
• moving file/log: rote stream follow --file logs/server.log --until READY
• long-running process: rote exec --background --ready-log READY --
• process stream: rote stream follow-process proc-1 --stream stdout --until READY
• terminal-sensitive command: rote pty run -- [args...]
• dependency preflight: rote deps check deps.toml
• crystallized replay: rote deno run --allow-all ~/.rote/flows//main.ts

Do not replace these with ad hoc command > file, tail -f, or ps | grep when the evidence should be durable. Rote already stores typed responses, artifacts, hashes, offsets, process leases, and command-log provenance.

Browser Intent Router

If the user says "browse", "open this site", "attach to my browser", "use the page", "click", "type", "snapshot", "extract from the page", "extract social profiles", "Gmail in browser", or otherwise asks for live web UI state, stop shell routing and invoke /rote-browse.

Do not satisfy browser intent with rote exec, raw Playwright, native web search, WebFetch, open, curl, or a saved non-browser flow unless the user explicitly switches substrate. Native search may help discover a URL only when the user asked for search/discovery or the browser route cannot identify a URL; it is not a substitute for browsing and extracting the page with rote.

Browse intent has precedence over the domain noun. For example, "browse my calendar", "browse Gmail", "browse HubSpot", or "browse Salesforce" means the user wants browser-state access even though those domains may also have APIs. You may still run rote flow search "" first, but only use an adapter/flow if it is installed, healthy, and completes the request. If the adapter/flow is missing, stale, unauthenticated, or fails setup, do not ask the user to build an adapter before trying the browser route. Hand off to /rote-browse and use an existing headed browser when the task depends on the user's logged-in profile.

For public profile extraction, such as "browse each committer's social profile", use GitHub/CLI/API data to collect candidate URLs and identities, then use /rote-browse to visit and extract the public pages. Do not replace that browse step with native web search summaries.

Default browser decision:

• Existing login, Gmail, SSO, MFA, extensions, active tabs, or profile state:

ask to attach to an existing headed browser.

• Public read-only page, CI, or replay-like work: ask whether headless

new-session is acceptable.

• The user says "browse" without choosing mode: ask headed vs headless; if

headed, ask attach-existing vs new rote-managed headed browser.

For active browser attach, hand off to /rote-browse and use its sequence:

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

For browser plus shell work, keep both in the same workspace. Use /rote-browse for page leases, snapshots, slices, refs, auth state, and readiness. Use /rote-shell only after browser state has been materialized as a saved response, snapshot, slice, or file that a local CLI should process.

Current Capability Map

Use only shipped commands. Do not invent aliases from the roadmap.

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

Deferred or not shipped as commands yet:

• rote exec attach
• rote exec log
• explicit detach
• persistent PTY sessions: start, send, snapshot, stop, attach
• non-log readiness probes such as HTTP, TCP, file, or command probes
• direct OS-pipe stream handles before background output reaches log artifacts
• non-Unix process-group cleanup guarantees

If a task needs a deferred feature, say so and use the nearest shipped primitive instead. For example, use rote exec wait for finite tracked jobs, use rote stream follow-process ... --until for log observation or readiness, and use rote exec status plus rote exec stop instead of raw ps/kill when the process is tracked.

TypeScript SDK Pattern Map

For authored TypeScript flows, use first-class SDK wrappers instead of hand-assembling command arrays. The SDK surface mirrors the shipped shell patterns:

| 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 parallel work | 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 }) |

Use rote.shell(). when you want the shell namespace explicitly; the top-level rote. forms are convenience aliases for authored flows.

Do not invent SDK methods for deferred roadmap items. There is no rote.detach, persistent PTY send, or direct OS-pipe stream handle yet. The current detach-like pattern is a tracked background lease with stdout/stderr files, execWait, followProcess, execStatus, and execStop.

rote.execMany preserves workspace response ordering by running process requests serially. For true parallel shell fan-out, generate declarative frontmatter steps: with type: process.exec, for_each, and max_concurrency so the DAG runner owns the scheduling and provenance.

For long-running finite jobs in authored TypeScript, prefer execBackgroundAndJoin or job.join when there is useful adapter, browser, process, file, or explicit stream work to do while the lease runs. The callback creates normal semantic DAG evidence; the final exec wait is the join point. Do not generate heartbeat or polling loops as DAG work. rote.execBackground(...) already prints the lease and poll commands to stderr. Do not duplicate that announcement in crystallized flows. Use announce: false only for deliberately quiet flows.

Crystallization Router

When the user asks to turn shell exploration into a reusable flow, choose the flow shape from the work pattern:

| Exploration pattern | Crystallized shape | | --- | --- | | One finite command whose output is the fact | rote.exec({ argv, deps, capture }) | | Command writes files that downstream work reads | rote.exec({ capture: { files: [...] } }) plus typed file paths | | Existing file or log is the source of truth | rote.followFile(path, options) | | Long finite job where other useful work can run | rote.execBackgroundAndJoin(request, async (job) => { ... }, options) | | Long service or daemon with readiness | rote.execBackground({ readyLog, capture }), then status/follow/stop | | Need to inspect progress from a tracked lease | job.follow(...) or rote.followProcess(...) | | Need completion proof from a tracked lease | job.wait(...) or rote.execWait(...) | | Terminal behavior is the point | rote.ptyRun({ argv, input, cols, rows }) | | Many independent commands share one shape | declarative steps: with process.exec, for_each, and max_concurrency |

Crystallize causality, not waiting. Do not encode heartbeat loops, repeated status polling, or sleep/retry scaffolding as business DAG nodes. Those are observation mechanics. The reusable flow should expose semantic actions and joins: start work, observe meaningful artifacts or streams, wait for completion, then summarize.

Before authoring a TypeScript shell flow, read:

rote guidance typescript flow-creation

That guide owns frontmatter, deps.toml, FlowOutput, release QA, and the shell SDK wrapper contract.

Strategy Pattern Library

Map the user's vague request to the smallest shipped pattern that preserves evidence:

| Signal | Pattern | Use | | --- | --- | --- | | Tiny disposable inspection | Raw shell allowed | direct harness shell | | Result may be queried, compared, summarized, or replayed | Durable one-shot | rote exec -- | | Command reads a known file | Declared file input | rote exec --stdin-file or a direct argv path | | Command creates a file that matters | Declared file output | rote exec --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 stream follow --file | | Start a server or daemon-like process | Service lease | rote exec --background --ready-log | | Long finite non-interactive job | Tracked background job | rote exec --background --stdout-file --stderr-file | | Inspect background output | Process stream observation | rote stream follow-process | | Need liveness before acting | Lease status | rote exec status | | Need cleanup | Lease cleanup | rote exec stop | | Many independent items share a command shape | Fan-out batch | steps: with process.exec, for_each, and max_concurrency | | API result feeds CLI or CLI result feeds API | Mixed substrate chain | adapter/browser primitive plus rote exec | | Browser snapshot/file feeds local CLI | Browser-file bridge | browser snapshot/file plus rote exec | | 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 pty run -- | | Command may prompt interactively and can be scripted safely | One-shot PTY with bounded input | rote pty run --input or --stdin-file | | Command needs ongoing human interaction | Foreground or defer | persistent PTY attach is not shipped |

--dry-run, --resume, --force-resume, and --max-concurrency are DAG runner controls for frontmatter steps: flows. They are not universal rote exec flags. For a single command, use the tool's own dry-run/check mode when available.

Workspace Setup

CLI work must happen inside a rote workspace:

rote init cli-work --seq --force
rote workspace sandbox cli-work off
cd ~/.rote/rote/workspaces/cli-work

Keep commands simple and literal. Avoid shell control operators, command substitution, and long && chains unless the user explicitly needs shell semantics. Prefer direct argv:

rote exec -- rg TODO docs

Use shell parsing only when it is the real subject of the work:

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

Query After Every Meaningful Step

Treat every @N as the handle for what just happened. The handle is saved evidence, not always the raw business payload. Route by type.

After a command finishes, read @@result first:

• response_id is the saved evidence handle
• response_kind tells you how to query the evidence
• primary_query, primary_stdout_query, primary_stderr_query, or

artifact_query are exact typed queries for the saved response

• @@next remains the immediate next-action guide

For one-shot process output, prefer the typed query fields from @@result:

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

Use @proc addresses when inspecting process responses:

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

When @@result gives an exact query such as rote query @proc.4.transcript '.text' -r, prefer it over @proc.last if any other command may run before you query. Use rote @N . for full provenance inspection, not as a shortcut for stdout or PTY transcript text.

Do not summarize from terminal scrollback when a structured query exists.

Files And Artifacts

Declare file inputs and outputs instead of relying on memory:

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

This records stdin provenance, file change state, media type, hashes when available, and artifact paths under .rote/artifacts/processes/@N/.

Background Processes

Start servers as leases, not mystery PIDs:

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

On Unix, rote starts background commands in a process group and stops the group with TERM followed by KILL if needed. Inspect .cleanup before claiming a process stopped.

Long-Running Finite Jobs

For long-running but finite commands, use a tracked background lease instead of an untracked detach. rote exec detach is not shipped yet. The current detached-like primitive is:

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

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

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [modiqo](https://github.com/modiqo)
- **Source:** [modiqo/skillspec](https://github.com/modiqo/skillspec)
- **License:** Apache-2.0
- **Homepage:** https://skillspec.sh

Install and usage instructions live in the source repository linked above.