ripple

Files (33)

• SKILL.md
• README.md · assets/
• generic-request.json · assets/request-templates/
• pmf-validation-request.json · assets/request-templates/
• social-media-request.json · assets/request-templates/
• README.md · references/
• command-map.md · references/
• history-and-control.md · references/
• input-authoring-guide.md · references/
• safety-and-config.md · references/
• workflow-playbooks.md · references/
• _common.sh · scripts/
• doctor.sh · scripts/
• domain_dump.sh · scripts/
• domain_example.sh · scripts/
• domain_info.sh · scripts/
• domain_list.sh · scripts/
• domain_schema.sh · scripts/
• install_init.sh · scripts/
• job_cancel.sh · scripts/
• job_clean.sh · scripts/
• job_delete.sh · scripts/
• job_list.sh · scripts/
• job_log.sh · scripts/
• job_result.sh · scripts/
• job_run.sh · scripts/
• job_status.sh · scripts/
• job_wait.sh · scripts/
• llm_set.sh · scripts/
• llm_show.sh · scripts/
• llm_test.sh · scripts/
• validate.sh · scripts/
• version.sh · scripts/

SKILL.md (first lines)

# Ripple

This is an OpenClaw orchestration skill. It is not a Ripple domain skill.

Do not confuse this skill with Ripple's internal domain packages under `skills/`, such as `social-media` or `pmf-validation`. Those are simulation domains that Ripple consumes. This skill teaches OpenClaw how to drive Ripple CLI safely.

## Use This Skill For

- installing and initializing Ripple
- checking environment health and current LLM config visibility
- discovering Ripple domains and understanding how to author a request
- validating a request before submission
- submitting a simulation job asynchronously
- polling a running job every 30 seconds by default
- checking job status immediately on demand
- viewing historical jobs, results, and logs
- cancelling a running job
- deleting or cleaning jobs only when the user explicitly asks

## Core Rules

1. Use the bundled scripts in `scripts/` instead of calling raw `ripple-cli` directly whenever a wrapper exists.
2. All OpenClaw-facing Ripple CLI calls must use JSON output. Every bundled wrapper enforces `--json`.
3. Prefer `domain schema` and `domain example` before `domain dump`.
4. Treat `<domain>` as a variable placeholder. Never special-case `pmf-validation`; `pmf-validation` is only one example domain.
5. Default new simulations to asynchronous submission. `scripts/job_run.sh` always adds `--async`.
6. After async submission, explicitly tell the user: polling will happen every 30 seconds by default.
7. Use `scripts/job_status.sh` for the normal polling loop. `scripts/job_wait.sh` exists, but the default orchestration path is explicit status polling every 30 seconds.
8. Do not automatically run `ripple-cli llm setup`. If LLM config is missing, ask the user to edit the Ripple config file or run `ripple-cli llm setup` manually.
9. If the user explicitly provides LLM settings, you may run `scripts/llm_set.sh ...` and then `scripts/llm_test.sh`.
10. `domain dump` is a heavy fallback for deep domain background, not the default discovery path.
11. `job delete` and `job clean` are destructive. Use them only on explicit user intent.
12. Ripple jobs default to `max_llm_calls=800`. For complex simulations, long horizons, or jobs with many waves / deeper deliberation, proactively warn the user to raise this value, otherwise the job may fail after hitting the LLM budget limit.

This skill must preserve the full user-facing Ripple CLI surface for OpenClaw, including `domain schema`, `domain example`, `domain dump`, `job cancel`, `job delete`, and `job clean`.

## Default Workflow

### New Simulation

1. If the environment may be missing or stale, run `scripts/version.sh` and `scripts/doctor.sh`. If Ripple is not installed or broken, run `scripts/install_init.sh`.
2. Identify the likely domain with `scripts/domain_list.sh`.
3. Inspect `scripts/domain_schema.sh <domain>` and `scripts/domain_example.sh <domain>` before asking follow-up questions.
4. Ask only for the missing business facts needed to complete the request.
5. Write a normalized request JSON file. Start from `assets/request-templates/generic-request.json`, `assets/request-templates/social-media-request.json`, or `assets/request-templates/pmf-validation-request.json`.
6. Run `scripts/validate.sh --input <request-file>` plus any explicit selectors such as `--skill`, `--platform`, `--channel`, or `--vertical`.
7. If validation is not ready, do not submit the job. Ask targeted follow-up questions and rewrite the request.
8. If validation passes, run `scripts/job_run.sh --input <request-file>` plus any explicit runtime overrides.
9. If the task looks complex, long-running, or wave-heavy, explicitly recommend a larger `--max-llm-calls` than the default 800 before submission.
10. Report the returned `job_id` and tell the user that polling will happen every 30 seconds by default. Also mention that they can ask for an immediate status check at any time.
11. Poll with `scripts/job_status.sh <job_id>` every 30 seconds until the job reaches `completed`, `failed`, or `cancelled`.
12. On completion, run `scripts/job_result.sh <job_id>`.
13. If the user asks for process detail or wants to inspect how the result was produced, run `scripts/job_log.sh <job_id>`.

### Historical Or Control Intents

- `scripts/job_status.sh <job_id>`: check a running or finished job now.
- `scripts/job_list.sh ...`: inspect historical jobs, optionally with filters.
- `scripts/job_result.sh <job_id> [--summary]`: fetch a historical result.
- `scripts/job_log.sh <job_id>`: fetch a historical compact log.
- `scripts/job_cancel.sh <job_id>`: request cancellation of a running job.
- `scripts/job_delete.sh <job_id>`: delete one historical job only on explicit user intent.
- `scripts/job_clean.sh ...`: batch cleanup only on explicit user intent.

## Domain Guidance Strategy

Use this escalation order:

1. `scripts/domain_list.sh`
2. `scripts/domain_schema.sh <domain>`
3. `scripts/domain_example.sh <domain>`
4. `scripts/domain_info.sh <domain>`
5. `scripts/domain_dump.sh <domain> --section <section>`
6. `scripts/domain_dump.sh <domain>`

Use `domain dump` only when schema/example/info are not enough to coach the user through domain-specific business details.

## LLM Configuration Policy

- Default path: remind the user to configure Ripple secrets themselves.
- Safe recommendations:
  - edit the Ripple config file directly
  - run `ripple-cli llm setup` manually
- Explicit delegation path:
  - `scripts/llm_show.sh`
  - `scripts/llm_set.sh --platform ... --model ... --api-key ... --url ... --api-mode ...`
  - `scripts/llm_test.sh`

## Request Authoring Notes

- `event.seed_text` must exist through at least one domain-appropriate text field.
- For `social-media`, prefer `event.title`, `event.body`, `source.author_profile`, and `platform`.
- For `pmf-validation`, prefer `event.product_name`, `event.differentiators`, `event.validation_question`, `source.summary`, plus `platform`, `channel`, and `vertical` when available.
- When the user is unsure how to structure a request, read the domain schema/example first instead of guessing.

## References

- See [the command map](references/command-map.md) for the full wrapper-to-CLI mapping and deep command coverage.
- See [the workflow playbooks](references/workflow-playbooks.md) for the end-to-end orchestration flow.
- See [the input authoring guide](references/input-authoring-guide.md) for request construction rules.
- See [the history and control guide](references/history-and-control.md) for job status, history, cancel, delete, and clean behavior.
- See [the safety and config guide](references/safety-and-config.md) for secret handling, installation behavior, and destructive-operation boundaries.

From xyskywalker/Ripple, AGPL-3.0.

More from xyskywalker/Ripple