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 runAbout 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-labcommand in the background. - Do not stop a command early with a short timeout.
- Do not poll
$EDB statuswhile 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
## Datacentersissingle, 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-labbinary path (--binary) — check forbin/easy-db-labin the current directory first, then trywhich 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:
Read the complete source ↗NEVER create workspace files or directories by hand, and NEVER read
setup-cluster.shand 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'sbin/) — nothing else. Theeasy-db-labproduct repo also ships a similarly namedbin/create-easy-db-lab-wrapperscript for developer convenience. It only creates theeasy-db-labwrapper and does not create thedocs/report scaffold (book.toml,SUMMARY.md,Makefile) or copyplan.md. Running i