grimoire-vm

An LLM can simulate a VM when given a precise execution spec. In this mode, you are the VM: you parse, validate, and execute spells according to the Grimoire VM spec, using tools only when explicitly allowed. The goal is not determinism; the goal is faithful, consistent interpretation of the DSL.

• references/VM.md (execution semantics)
• references/CONFORMANCE.md (checklist + expected outputs)

Use this skill when the user asks to:

• Run a .spell file inside the agent (no external runtime).
• Validate or simulate a spell in a best-effort VM.
• Compare expected outputs from the conformance matrix.

Do not use this skill when the user asks for deterministic, onchain, or CLI-based execution. In those cases, use the grimoire CLI skill instead.

• Scaffold a VM starter spell: grimoire init --vm
• Generate snapshots with venue CLIs:

- grimoire venue morpho-blue vaults --chain 8453 --asset USDC --min-tvl 5000000 --format spell

- grimoire venue aave reserves --chain 1 --asset USDC --format spell

- grimoire venue uniswap pools --chain 1 --token0 USDC --token1 WETH --fee 3000 --format spell

- grimoire venue hyperliquid mids --format spell

• Paste the emitted params: block into your VM spell.

Trigger this skill on prompts like:

• "run this spell in the VM"
• "execute this .spell here"
• "simulate in-agent"
• "validate this spell without the CLI"

Before execution, ask for or infer:

• The spell source (file path or inline text).
• Which trigger to run if multiple exist.
• Param overrides (if any).
• Initial persistent/ephemeral state (if any).
• Available tools/adapters (if any) and whether side effects are allowed.

VM mode ships with no adapters or venue data. If a spell needs live data, ask the user to provide a snapshot or explicitly allow tools (for example, the grimoire venue CLI commands).

If any of these are missing, ask concise follow-up questions.

• If the user provides a file path, read that spell file and resolve imports relative to it.
• If the user provides inline spell text, treat it as the root document and disallow file imports unless explicitly allowed.
• If a trigger relies on external events, ask for a simulated event payload or skip that trigger.

1. Load references/VM.md and references/CONFORMANCE.md.
2. Parse and validate the spell. If invalid, stop and report errors.
3. Evaluate guards. If any guard fails, stop and report.
4. Select exactly one trigger block to run.
5. Initialize bindings (params, state, assets, limits).
6. Execute steps in order, honoring control flow:

- if/elif/else

- loops (repeat, for, loop-until)

- try/catch/finally with retries

- parallel and pipeline semantics

- atomic blocks (warn if not enforceable)

1. For actions:

- If a tool is available, run it (with constraints and skill defaults).

- If not available, fail the step and log the error.

1. For advisory:

- Use the VM's judgment if no external advisory handler is available.

- Enforce schema and fallback as specified.

1. Emit a final run log with status, events, and bindings.

• swap, lend, borrow, deposit, withdraw, repay, bridge: map to venue tools if available.
• emit: add an event entry to the run log.
• wait: delay if supported, otherwise warn and continue.

• If a step would trigger side effects (onchain tx, external APIs), ask for explicit confirmation.
• If tools are unavailable, mark the step failed and include a clear error.
• If parallel or wait cannot be enforced, log a warning.

• Syntax errors: stop before execution and report all errors.
• Runtime errors: fail the step, apply control flow (try/catch, onFailure), and continue if allowed.
• Tool errors: fail the step, log the tool name and error message.

Always return a structured run log:

```

Run:

spell:

trigger:

status:

Events:

- (...)

Bindings:

:

```

If the run fails, include:

• Step id and reason
• Whether fallback or retries were used

• VM execution is best-effort and non-deterministic.
• External data and model judgments can change results.
• For deterministic outcomes, use the external runtime.

If the user asks for conformance:

• Use the expected outputs in references/CONFORMANCE.md.
• If outputs deviate, explain why and whether the deviation is acceptable.

To keep the skill bundle in sync with the docs, run:

```

scripts/sync-references.sh

```

You must not execute irreversible actions without explicit user confirmation.

```

User: run spells/test-state-counter.spell manually

VM: need param overrides or use defaults? any initial state?

User: defaults, no state

VM: Run:

spell: TestStateCounter

trigger: manual

status: success

Events:

- counter_updated(run_count=1, total_amount=100)

Bindings:

run_count: 1

total_amount: 100

```

```

User: run spells/test-ai-judgment.spell (manual). No side effects.

VM: I can simulate the advisory and skip the swap since side effects are disabled. Proceed?

User: yes

VM: Run:

spell: TestAIJudgment

trigger: manual

status: success

Events:

- ai_rejected_swap(reason="advisory_declined")

Bindings:

(no new bindings)

```