Lobster

Lobster workflow runtime for deterministic pipelines with approval gates. Use when: (1) Running multi-step automations that need human approval before side effects, (2) Monitoring PRs/issues for changes, (3) Processing data through typed JSON pipelines, (4) Email triage or batch operations, (5) Any workflow that should halt and ask before acting. Lobster saves tokens by running deterministic pipelines instead of re-planning each step.

Security Scan

The skill's documentation describes a local CLI workflow runner (reasonable), but the SKILL.md expects shell tooling, persistent state, and Clawdbot credentials while the skill metadata declares no required binaries or environment variables — these gaps are inconsistent and warrant caution.

Purpose & Capability

The stated purpose (deterministic workflow runtime with approval gates) matches the examples and commands in SKILL.md. However, the metadata declares no required binaries or env vars while the instructions clearly expect a Node-based CLI, the GitHub CLI (gh), jq, and optionally clawd.invoke integration. The omission of these requirements is disproportionate to the documented functionality and is an incoherence.

Instruction Scope

Runtime instructions tell the agent to execute arbitrary shell commands (exec --json --shell "...") and to read/write persistent state (~/.lobster/state). They also include examples that run gh and jq, read workflow files, and call clawd.invoke which sends data to an external CLAWD_URL/CLAWD_TOKEN. This grants the skill the ability to run arbitrary commands and transmit data outside the agent — appropriate for a workflow runner but high-risk if the skill's provenance is unknown. The SKILL.md also contains hardcoded path examples (e.g., /home/molt/...) which suggest expectations about local installs.

Install Mechanism

There is no install spec (instruction-only), which minimizes automatic disk writes. The README suggests installing a Node package (npm install -g @clawdbot/lobster) or using a local node script; those are reasonable but not enforced. Because the skill is instruction-only, the scanner had no code to review; this is lower install risk but increases reliance on the user to follow installation guidance safely.

Credentials

Metadata lists no required environment variables, yet SKILL.md explicitly references CLAWD_URL and CLAWD_TOKEN for Clawdbot integration and allows overriding LOBSTER_STATE_DIR. Requesting a service token (CLAWD_TOKEN) is reasonable for Clawdbot calls, but the skill fails to declare it. The absence of declared secrets alongside instructions that use them is an inconsistency that can lead to accidental credential exposure if users assume none are needed.

Persistence & Privilege

The runtime uses persistent state (~/.lobster/state) and implements resume/approval tokens. The skill does not request always:true and does not modify other skills. Persistent state is coherent with the workflow purpose, but users should be aware the agent (when executing the CLI) will read/write files in the user home directory.

What to consider before installing

This skill looks like a legitimate workflow runner, but its metadata does not match its documentation. Before installing or invoking: 1) Verify the source repository (github.com/guwidoe/lobster-skill) and inspect the actual published package; 2) Do not supply CLAWD_TOKEN/CLAWD_URL or other secrets unless you trust the code — the SKILL.md uses these but the skill metadata doesn't declare them; 3) Expect the skill to execute arbitrary shell commands (gh, jq, node) and to read/write ~/.lobster/state — run it in a sandbox or on a dedicated account if possible; 4) Prefer only installing from an official package release (check signatures/maintainer) rather than running unknown scripts; 5) Ask the publisher to update the metadata to declare required binaries and env vars (gh, jq, node, CLAWD_*), and to provide the package source and a reproducible install method. If you cannot validate the source, treat this skill as risky.

Contribute: Source code & PRs welcome at github.com/guwidoe/lobster-skill

Workflow runtime for AI agents — typed pipelines with approval gates.

CLI Location

# Set alias (adjust path to your install location)
LOBSTER="node /home/molt/clawd/tools/lobster/bin/lobster.js"

# Or install globally: npm install -g @clawdbot/lobster
# Then use: lobster '<pipeline>'

Quick Reference

# Run pipeline (human mode - pretty output)
$LOBSTER '<pipeline>'

# Run pipeline (tool mode - JSON envelope for integration)
$LOBSTER run --mode tool '<pipeline>'

# Run workflow file
$LOBSTER run path/to/workflow.lobster

# Resume after approval
$LOBSTER resume --token "<token>" --approve yes|no

# List commands/workflows
$LOBSTER commands.list
$LOBSTER workflows.list

Core Commands

Command	Purpose
exec --json --shell "cmd"	Run shell, parse stdout as JSON
where 'field=value'	Filter objects
pick field1,field2	Project fields
head --n 5	Take first N items
sort --key field --desc	Sort items
groupBy --key field	Group by key
dedupe --key field	Remove duplicates
map --wrap key	Transform items
template --text "{{field}}"	Render templates
approve --prompt "ok?"	Halt for approval
diff.last --key "mykey"	Compare to last run (stateful)
state.get key / state.set key	Read/write persistent state
json / table	Render output

Built-in Workflows

# Monitor PR for changes (stateful - remembers last state)
$LOBSTER "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

# Monitor PR and emit message only on change
$LOBSTER "workflows.run --name github.pr.monitor.notify --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

Approval Flow (Tool Mode)

When a pipeline hits approve, it returns:

{
  "status": "needs_approval",
  "requiresApproval": {
    "prompt": "Send 3 emails?",
    "items": [...],
    "resumeToken": "eyJ..."
  }
}

To continue:

$LOBSTER resume --token "eyJ..." --approve yes

Example Pipelines

# List recent PRs, filter merged, show as table
$LOBSTER 'exec --json --shell "gh pr list --repo owner/repo --json number,title,state --limit 20" | where "state=MERGED" | table'

# Get data, require approval, then process
$LOBSTER run --mode tool 'exec --json --shell "echo [{\"id\":1},{\"id\":2}]" | approve --prompt "Process these?" | pick id | json'

# Diff against last run (only emit on change)
$LOBSTER 'exec --json --shell "gh pr view 123 --repo o/r --json state,title" | diff.last --key "pr:o/r#123" | json'

Workflow Files (.lobster)

YAML/JSON files with steps, conditions, and approval gates:

name: pr-review-reminder
steps:
  - id: fetch
    command: gh pr list --repo ${repo} --json number,title,reviewDecision
  - id: filter
    command: jq '[.[] | select(.reviewDecision == "")]'
    stdin: $fetch.stdout
  - id: notify
    command: echo "PRs needing review:" && cat
    stdin: $filter.stdout
    approval: required

Run: $LOBSTER run workflow.lobster --args-json '{"repo":"owner/repo"}'

Clawdbot Integration

Lobster can call Clawdbot tools via clawd.invoke:

$LOBSTER 'clawd.invoke --tool message --action send --args-json "{\"target\":\"123\",\"message\":\"hello\"}"'

Requires CLAWD_URL and CLAWD_TOKEN environment variables.

State Directory

Lobster stores state in ~/.lobster/state/ by default. Override with LOBSTER_STATE_DIR.