avav25/ralph
plugin/skills/ralph/SKILL.md
Use this skill when iterating a task until a binary success condition holds (test passes, schema validates, output matches a regex) and a power user wants a standalone RALF (Read-Act-Learn-Feedback) iteration loop — to wrap the task in a feedback loop with a mechanically-verifiable oracle and a kill-on signal. Not for open-ended exploration — use /spike for that.
$ install --global
skillsauthnpx skillsauth add avav25/ai-assets ralphInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 23, 2026, 4:35 AM78.0s2 files scanned
SKILL.md
- name:
- ralph
- description:
- Use this skill when iterating a task until a binary success condition holds (test passes, schema validates, output matches a regex) and a power user wants a standalone RALF (Read-Act-Learn-Feedback) iteration loop — to wrap the task in a feedback loop with a mechanically-verifiable oracle and a kill-on signal. Not for open-ended exploration — use /spike for that.
- context:
- fork
- argument-hint:
- <task description>
/ralph — RALF Iteration Loop
Standalone Read-Act-Learn-Feedback loop. Iterate any task until a mechanically-verifiable success signal triggers, or a kill-on signal halts the loop. Caps prevent runaway cost.
When to use
- "Write code until
cargo testexits 0" - "Generate test cases until rubric scores ≥ 4.0"
- "Refactor until linter is clean"
- "Convert this YAML to JSON until schema validates"
Not for: open-ended exploration (use /spike), code where you'd rather review the plan first (use /plan then /develop), or anything without a binary success oracle.
Invocation
/ralph "<task>" --oracle <type:value> --kill-on <type:value> [--max-iterations N] [--token-budget N] [--time-cap-minutes N]
Examples:
/ralph "write a Rust CLI that parses CSV" --oracle cli:./test-cli.sh --kill-on oracle-pass
/ralph "generate 100 test cases for /develop rubric" --oracle judge:test-case-rubric.md --kill-on oracle-pass --max-iterations 8
/ralph "fix flaky test in src/api/login.test.ts" --oracle cli:./run-tests.sh --kill-on same-error-repeats:3
Required arguments
Both required — skill rejects invocation if either is missing per ralph-budget.md rule.
--oracle <type:value>
| Type | Format | Pass condition |
|---|---|---|
| cli | cli:./script.sh | Exit 0 |
| judge | judge:rubric-name.md | eval-judge agent score ≥ rubric threshold |
| regex | regex:./out.log:^DONE$ | Pattern matches in named file |
| python | python:./check.py | Exit 0 |
--kill-on <type:value>
| Type | Format | Trigger |
|---|---|---|
| oracle-pass | (no value) | Happy stop on first oracle success |
| same-error-repeats | same-error-repeats:N | Same error string N iterations in a row |
| regex | regex:PATTERN | Pattern matches in latest model output |
| python | python:./kill.py | Custom predicate exits 2 |
| no-progress | no-progress:N | N iterations with no file diff |
Caps (defaults from userConfig)
| Cap | Default | userConfig override |
|---|---|---|
| --max-iterations | 10 | ralph_default_max_iter |
| --token-budget | 200_000 | ralph_default_token_budget |
| --time-cap-minutes | 120 | ralph_default_time_cap_minutes |
Session-aggregate caps from ralph-budget.md HIGH-3 also apply (20 iter / 400K tokens / 180 min across all RALF runs in one session).
State and logs
Every run writes to <repo>/.ai-skills-memory/ralph/<run-id>/:
config.json— caps + oracle + kill-on as locked at startactive.lock— presence = run is in progressinitial-prompt.md— full init prompt (G10)iter-NNN/— one dir per iteration:prompt.md,output.md,diff.patch,oracle-result.json,tokens.jsonbudget.json— final totals on exit
Per-iteration tokens.json (v0.1.6) records tokens spent that iteration plus runaway: true when a single iteration exceeds 3× the fair share (token_budget / max_iterations). Runaway warnings also append to .ai-skills-memory/ralph-warnings.log.
Init vs continuation prompts
- Iter 1 (init): full task brief — goal, constraints, evidence, output contract, oracle definition, kill-on signal. Typically 5–15K tokens
- Iter ≥ 2 (continuation): state delta only — last-iter diff + oracle failure summary + top-3 active constraints + kill-on countdown. Typically 1–3K tokens (~70% savings)
Continuation template at ${CLAUDE_PLUGIN_ROOT}/skills/ralph/templates/continuation-prompt.md — applied automatically by ralph-stop.py hook.
Memory writes
| Layer | When | Shape |
|---|---|---|
| L4 | RALF terminal state | .ai-skills-memory/ralph/<run-id>/budget.json (iterations, tokens, exit reason) |
| L4 | After kill or oracle-pass | .ai-skills-memory/ralph-history.jsonl summary line |
Failure modes
- Missing
--oracleor--kill-on: rejected at arg validation with clear error - Oracle script crashes (exit ≠ 0 AND ≠ 2): treated as
ORACLE_ERROR, loop killed, diagnostic surfaced - Hard cap hit: soft warn at threshold, hard pause at cap, user prompted to confirm continuation, raise budget, or abort
- Buggy
ralph-stop.pyhook: hook fails open perfailure-recovery.md; never blocks Stop
Integration
- Hooks:
ralph-stop.py(Stop event) drives the loop, writes per-iter state, enforces budgets;ralph-iter-meter.py(PostToolUse, v0.1.6) estimates per-iter token spend - Rule:
ralph-budget.md(caps, oracle/kill-on contract, failure modes) - Schemas:
plugin/schemas/spawn-payload.schema.jsonif RALF spawns subagents - Templates:
plugin/skills/ralph/templates/continuation-prompt.md(G10) - Used by:
/feature-design,/develop,/bugfix,/refactor,/migratefor embedded RALF segments
Related Skills
avav25/knowledge-sync
development
VerifiedTrustedCommunity
Use this skill when running the recurring (daily) knowledge-base rescan for a repo that already has knowledge/.knowledge-sync.yml — the main-thread dispatcher that reads the config, computes the git delta since last_scanned_sha, maps changed paths to affected doc areas, early-exits cheaply when nothing changed, then fans out one Agent(content-writer) per affected area, applies the propose/direct update policy, advances the baseline only on success, and writes an L4 run log — all with the G1 untrusted-content choke-point, secret-scan, deny-list, and budget controls woven in. For first-time setup use /knowledge-sync-init.
1SKILL.mdUpdated May 24, 2026
avav25/knowledge-sync-init
development
VerifiedTrustedCommunity
Use this skill when bootstrapping scheduled knowledge-base sync for a repo that has no knowledge/.knowledge-sync.yml yet — to run one-time setup that detects the knowledge_root from CLAUDE.md/AGENTS.md, maps doc areas to source globs, records opt-in external sources (Linear/Notion/WebFetch, all disabled by default), captures a baseline last_scanned_sha, sets the per-area update policy, generates or seeds knowledge/CONVENTIONS.md, provisions the L4 memory dir, and offers to register the daily routine. Routes ongoing recurring sync operations to /knowledge-sync.
1SKILL.mdUpdated May 24, 2026
avav25/ai-skills-init
tools
VerifiedTrustedCommunity
Use this skill when bootstrapping a target repository to be ai-skills-aware — on the first run of any ai-skills workflow in a fresh repo, when adopting the ai-skills plugin in an existing repo, or after upgrading to a plugin version that adds new memory paths or templates, including when the user does not say "init" but asks to "set up" or "onboard" the repo — to detect codebase type, create CLAUDE.md + AGENTS.md scaffolding, initialize the .ai-skills-memory/ directory tree from L1 templates, and configure .gitignore. Idempotent — safe to re-run. Accepts `--codebase-type <type>` and `--overwrite`. Not for re-initializing only memory — use `/memory-init` instead.
1SKILL.mdUpdated May 18, 2026
avav25/plugin-author
tools
VerifiedTrustedCommunity
Use this skill when extending, repairing, or improving plugin assets, when ingesting a `/feedback` report as a fix-cycle backlog, or when you do not remember which lower-level command is right for the job — the umbrella workflow for ai-skills plugin-asset authoring and maintenance: creating, auditing, fixing, improving, refactoring, and migrating skills, agents, rules, hooks, prompts, schemas, and rubrics inside the plugin. Auto-classifies the request, loads the right knowledge skills (`@prompt-engineering`, `@context-engineering`, `@team-protocols`), and spawns the right subagents (`prompt-engineer`, `system-architect`, `python-engineer`, `software-engineer`, `qa-engineer`, `eval-judge`) via the `Agent` tool.
1SKILL.mdUpdated May 14, 2026