run-runbook

name	run-runbook
description	Use when the user wants to launch a runbook, run an audit, review, or analysis task via Jetty, or says "run the X runbook". Also triggers on "launch runbook", "execute runbook", "run dedup-audit", "run security-reviewer", or any request to run a task from runbooks/.

Run Runbook

Launch runbooks from runbooks/ via Jetty using run-runbook.sh.

Workflow

1. Create or update runbook-params.json with any parameter overrides the user requested
2. Run ./run-runbook.sh <task-name>
3. Report the trajectory ID and workflow ID

Parameters File

If runbook-params.json is missing, create it locally at repo root before launching. The repo .gitignore excludes both runbook-params.json and run-runbook.sh, so these runbook helper files may exist only in your local checkout.

NEVER write secrets or tokens into runbook-params.json. The run-runbook.sh script injects GITHUB_TOKEN automatically via gh auth token at launch time. Do not add a GITHUB_TOKEN field to the JSON file — it is unnecessary and risks leaking credentials.

{
  "repository": "ahrav/gossip-rs",
  "pr_number": "312",
  "base_branch": "main",
  "CARGO_HOME": "/Users/<you>/.cargo",
  "timeout_sec": 3600
}

Common Overrides

Parameter	Default	Override for
timeout_sec	3600 (1 hr)	Long audits: 7200 (2 hr), 10800 (3 hr)
pr_number	varies	PR-specific runbooks (reviews, comment response)
base_branch	main	Auditing a different branch

Use the Edit tool to update runbook-params.json before running the script. Restore the original value immediately after launching if the override was one-time — the runbook runs remotely and does not re-read the local file.

Run the Script

./run-runbook.sh <task-name>

The <task-name> matches the filename in runbooks/ without the .md extension.

List Available Runbooks

if [ -d runbooks ] && ls runbooks/*.md >/dev/null 2>&1; then
  ls runbooks/*.md | sed 's|runbooks/||;s|\.md$||'
else
  echo "No local runbooks found. Ensure local runbook assets are provisioned."
fi

Output

The script prints trajectory and workflow IDs on success:

Run launched successfully:
  Task:          <task-name>
  Trajectory ID: <id>
  Workflow ID:   <id>

Report these to the user so they can track progress in Jetty.

Common Mistakes

Mistake	Fix
Using RemoteTrigger API directly	Use run-runbook.sh — it handles param injection and Jetty API
Forgetting to update timeout for long tasks	User-requested timeout goes in runbook-params.json timeout_sec
Passing wrong task name	Name must match a file in runbooks/ without .md. The script lists available names on error.
Not reporting trajectory ID	Always show the trajectory and workflow IDs in your response
Not knowing which runbook to run	Use the guarded runbook-listing command above and ask the user to pick one
Writing GITHUB_TOKEN into runbook-params.json	Never. run-runbook.sh injects the token via gh auth token automatically. Writing tokens into files risks credential leaks.