Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Data & analytics

run

Executes a plan step by step in an explicit cluster workspace, confirming each step with the user and updating journal.md as work proceeds. Use when the user says "run a plan", "execute the plan", "run this plan.md", "start/resume the lab run", or otherwise asks to run, execute, or resume a lab plan, benchmark, or database experiment.

rustyrazorblade · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add rustyrazorblade/skills --skill run

About this skill


name: run description: Executes a plan step by step in an explicit cluster workspace, confirming each step with the user and updating journal.md as work proceeds. Use when the user says "run a plan", "execute the plan", "run this plan.md", "start/resume the lab run", or otherwise asks to run, execute, or resume a lab plan, benchmark, or database experiment. argument-hint: " [step N] OR <plan.md path> [--binary ] [--jdk ] [step N]" user-invocable: true

Easy DB Lab — Run Plan

You execute a plan step by step in an explicit cluster workspace, reading the plan from <cluster-dir>/docs/plan.md.

Environment

Load ../../references/environment.md for details on the AWS environment, k3s, and SSH access.

Session Log

Load ../../references/journal.md for instructions on maintaining the journal. Once the cluster dir is established, read <cluster-dir>/docs/journal.md before taking any action — it tells you what has already been done.

Issues Log

Load ../../references/issues.md for instructions on maintaining the issues file. Add an entry to <cluster-dir>/docs/issues.md whenever you hit friction, an undocumented behavior, or a skill/doc gap.

Discover the Command Surface First

After setting up $EDB in the Before Starting section, start with the task-oriented guides, then read the flag-level reference.

$EDB help lists task-oriented topic guides; $EDB help <topic> prints one. Each guide gives the intended workflow for a topic as an ordered command sequence, plus its prerequisites and gotchas — how the tool is meant to be used. Read the guide for any topic a plan step touches (for example, stress-testing before running load, cassandra before a version or config change) so your command sequence matches the intended one.

# List the available topic guides
$EDB help

# Read the guide for a topic before you act on it
$EDB help <topic>

If $EDB help errors with Unmatched argument at index 0: 'help', the binary predates the topic guides. Skip this step and rely on commands below.

Then read the flag-level reference:

$EDB commands

Use this output as the authoritative source for flag names and available options. Never guess flags. If $EDB is not yet available, load ../../references/commands.md as a fallback.

Kit commands are only visible after installation. If you need to look up the commands, flags, or endpoints for a kit that is not yet installed, use kit info instead of relying on commands:

$EDB kit info <name>

state.json Is Internal — Never Read It

state.json is an internal file of the easy-db-lab tool. It is not a documented interface. Its shape can change at any time. Never read it, never parse it, and never quote its contents to the user.

To learn the cluster state, run a command instead:

$EDB status

The one exception is a file-existence check. detect-cluster-layout.sh tests only whether the file is present, to set STATE=provisioned. That is allowed. Reading the contents is not.

Run Commands to Completion

Every cluster action goes through an easy-db-lab command. Run the command and wait for it to finish before you do anything else.

  • Do not run an easy-db-lab command in the background.
  • Do not stop a command early with a short timeout.
  • Do not poll $EDB status while another command is still running.
  • Do not report a step as complete until the command exits.

Some commands are slow. $EDB init ... --up provisions AWS instances; it takes a few minutes to finish. This is normal. Set the Bash tool timeout to its maximum (600000 ms) for these commands, and let them run.

If a command does exceed the maximum timeout, do not retry it blindly. Run $EDB status first to see what the command already did, then write an entry to <cluster-dir>/docs/issues.md.

Before Starting

1. Determine the invocation mode

The skill is invoked in one of two ways:

First run — <plan.md path> <cluster directory> [step N] The cluster directory does not exist yet (or has no docs/plan.md). Full scaffolding is required.

Resume — <cluster directory> [step N] The cluster directory already exists and contains docs/plan.md. Skip scaffolding entirely.

Detect which case applies by checking for docs/plan.md inside the provided directory. If the directory doesn't exist or has no docs/plan.md, treat it as a first run and require a plan path. If docs/plan.md exists, treat it as a resume.

If a required argument is missing, ask the user for it before continuing.


First run

Read the plan. Extract the cluster name and datacenter configuration directly from the plan file:

  • Cluster name — value under ## Cluster Name
  • Datacenters — if ## Datacenters is single, it is a single-DC cluster; otherwise each - <dc>: <cidr> line defines a DC name and CIDR

Ask the user only for anything missing:

  • easy-db-lab binary path (--binary) — check for bin/easy-db-lab in the current directory first, then try which easy-db-lab; only ask if neither is found.
  • Java 21 JDK home (--jdk) — leave blank to inherit the system default.

Scaffold the cluster workspace — run the script, never do this manually:

NEVER create workspace files or directories by hand, and NEVER read setup-cluster.sh and perform its steps yourself. You MUST execute it as a script via bash. The tool requires a strict directory structure that only the script produces correctly. Any manual recreation will produce a broken workspace.

Use this plugin's setup-cluster.sh (from this plugin's bin/) — nothing else. The easy-db-lab product repo also ships a similarly named bin/create-easy-db-lab-wrapper script for developer convenience. It only creates the easy-db-lab wrapper and does not create the docs/ report scaffold (book.toml, SUMMARY.md, Makefile) or copy plan.md. Running i

Read the complete source ↗