grimoire

Grimoire CLI スキル

このスキルは、Grimoire の基本的な運用手引きです。

使用する場面

以下を含むタスクで、このスキルを使用します。

• Grimoire ツールのインストール／セットアップ
• .spell ファイルの作成または編集
• DSL の機能に関する構文の質問
• アドバイザリー（advise）の作成、デバッグ、リプレイのワークフロー
• セットアップ／コンパイル／検証／シミュレーション／キャスト／再開のワークフロー
• スペルのコンパイル時または実行時エラーのデバッグ

必ず守る読み込みルール

以下の references/ および docs/ のパスはすべて、このスキルのディレクトリ（skills/grimoire/）からの相対パスです。これらのルールは必須です。作成時のエラーにつながる構文の網羅性不足を解消できます。

停止 — まずこれを読んでください： コードベースを検索したり、構文パターンを grep したり、DSL の構文について記憶に頼ったりしないでください。このスキルに同梱されているリファレンスファイルが唯一の信頼できる情報源です。スペルの内容を書いたり編集したりする前に、以下のファイルをすぐに Read ツールで読み込んでください。

1. .spell の作成／編集を行うタスクでは、ほかの作業に取りかかる前に、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • references/syntax-capabilities.md
   • references/authoring-workflow.md
2. CLI フラグの詳細を確認する場合は、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • references/cli-quick-reference.md
3. アドバイザリー関連のタスク（advise、advisors、リプレイ）では、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • docs/how-to/use-advisory-decisions.md
   • docs/explanation/advisory-decision-flow.md
4. ローカルフォークのプレビューに関するワークフローでは、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • references/anvil-cheatsheet.md
   • docs/how-to/simulate-on-anvil-fork.md
5. ウォレットのセットアップと実行キーのワークフローでは、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • docs/how-to/use-wallet-commands-end-to-end.md
6. RPC／署名者／トランザクションの診断では、Read ツールを使って以下のファイルをすぐに読み込んでください。
   • references/cast-cheatsheet.md

インストール方法の選択

最初に正常に動作する呼び出し方法を選び、そのセッションでは同じ方法を使用してください。

1. グローバル：
   • npm i -g @grimoirelabs/cli
   • コマンドプレフィックス：grimoire
2. インストール不要：
   • コマンドプレフィックス：npx -y @grimoirelabs/cli
3. リポジトリ内：
   • コマンドプレフィックス：bun run packages/cli/src/index.ts --

いずれかの方法で失敗した場合は、自動的に次の方法へ進んでください。

grimoire venue doctor ... が Unknown venue adapter "doctor" で失敗する場合は、リポジトリ内での呼び出し（bun run packages/cli/src/index.ts）を使用するか、グローバル CLI をアップグレードしてください。

リポジトリ内で Bun を実行する場合は、末尾の -- を必ず付けてください。これにより、Bun がフラグを消費せず、Grimoire に渡します。

クイックスタート（すぐに成功する手順）

カスタムスペルを書く前に、以下の手順を実行してください。

1. <grimoire-cmd> --help
2. <grimoire-cmd> setup（対話式の実行オンボーディング）
3. <grimoire-cmd> validate spells/compute-only.spell
4. <grimoire-cmd> simulate spells/compute-only.spell --chain 1

3 つすべてが成功したら、スペルの作成に進んでください。

セットアップ時のセキュリティ／実行環境に関する注意事項：

• セットアップでは非表示のパスワードが求められ、入力内容は画面に表示されません
• RPC の入力を空欄にすると、チェーンのデフォルトのパブリック RPC が使用されます
• --no-save-password-env を使用しない場合、セットアップによって .grimoire/setup.env が書き込まれることがあります
• CLI は起動時に最も近い .grimoire/setup.env を自動で読み込みますが、既存の環境変数は上書きしません

作成と実行に関するポリシー

1. まず構文リファレンスを読みます（上記の必須ルール）。
2. スペルを作成／更新します。
3. 検証の前に format を実行して、レイアウトを標準化します。
4. validate を実行します（注意事項の多いスペルには --strict を使用します）。
5. エラー／警告を修正し、検証に合格するまで再実行します。
6. simulate を実行します。
7. ベニューのメタデータを照会する前、または価値を移転する実行の前に、対象のアダプター／チェーンに対して venue doctor を実行します。
   • 例：<grimoire-cmd> venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json
8. EVM ベニューで価値を移転する実行を行う前に、Foundry Cast のクイックチェック（chain-id、block-number、balance、nonce）でエンドポイントと署名者の状態を確認します。
   • hyperliquid などのオフチェーンベニューには Anvil／Cast のチェックを適用しないでください。
9. 決定論的な実行を目的とするアドバイザリーステップでは、ドライラン／ライブの cast で --advisory-replay <runId> を記録してから使用します。
10. スペルに不可逆なアクションが含まれる場合、ライブ cast の前に cast --dry-run を必須とします。
11. 価値を移転するライブ cast の前に、ユーザーに明示的な確認を求めます。
12. クロスチェーンモードでは、チェーンごとの RPC マッピングを明示的に指定する必要があります。

• --rpc-url <sourceChainId>=<url>
• --rpc-url <destinationChainId>=<url>

13. クロスチェーンの Morpho アクションでは、次のいずれかでマーケットマッピングを明示的に指定する必要があります。

• --morpho-market-id <actionRef>=<marketId>（繰り返し指定可能）、または
• --morpho-market-map <path>

14. Morpho の供給のみを行う戦略では、vault_deposit／vault_withdraw（ボルトアドレスを明示）を優先します。

• ボルトアドレスがない場合は、候補となるボルトを一覧表示し、ユーザーに選択を求めます。自動選択は絶対に行わないでください。

15. Morpho のマーケット戦略（借入／担保／貸付）では、market_id を明示的に指定し、次の明示的なアクションを使用する必要があります。

• morpho_blue.supply_collateral(asset, amount, market_id)
• morpho_blue.withdraw_collateral(asset, amount, market_id)

16. アクションのトークンフィールドには、引用符で囲まない 0x... 形式のアドレスリテラルを使用します。アドレスのように見える文字列を引用符で囲むと QUOTED_ADDRESS_LITERAL が発生します。
17. Morpho doctor の準備状況チェックでは、ウォレット環境変数を明示的に設定します（GRIMOIRE_WALLET_ADDRESS を優先し、設定されていない場合は WALLET_ADDRESS を使用します）。
18. クロスチェーン実行が待機状態のままになった場合は、resume <runId> で続行します（決済状況をポーリングするには --watch を使用します）。
19. パスワード／秘密鍵をエージェントのプロンプトやインラインのコマンド割り当てに含めないでください。
20. ドライラン／ライブの cast では、--private-key より keystore と --password-env の組み合わせを優先します。
21. .grimoire/setup.env は平文のシークレット情報として扱い、ローカルのみに保管し、不要になったらローテーションまたは削除してください。
22. プロジェクトツリーの外でコマンドを実行する場合、必要に応じて GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env を設定します。

コマンド一覧（コア）

• init
• setup
• format
• compile
• compile-all
• validate
• triggers
• simulate
• cast
• venues
• venue
• venue doctor
• history
• log
• resume
• wallet（generate、address、balance、import、wrap、unwrap）

簡潔なコマンドシグネチャと安全性に関わる重要なフラグについては、references/cli-quick-reference.md を参照してください。

ランタイムの動作モデル

• ランタイムのセマンティクスは一貫しており、まずプレビューを行い、実行パスでのみコミットします。
• simulate と cast --dry-run はプレビュー専用のフローです。
• ライブ cast は、ポリシーとランタイムのチェックに合格すると、不可逆なアクションをコミットできます。
• simulate は明示的な --rpc-url をサポートし、優先順位は --rpc-url -> RPC_URL_<chainId> -> RPC_URL です。
• フェーズ 1 のクロスチェーン実行では、2 つのスペルをオーケストレーションし（--destination-spell）、1 つの論理的な run id と再開機能を使用します。
• 対象を絞った実行の前に、triggers <spell> を使用して、安定したハンドラー ID をネイティブに確認します。
• simulate と cast は、--trigger-id、--trigger-index、および旧式の --trigger によるトリガー選択実行をサポートします。
• 複数のハンドラーを含むスペルでは、--trigger-id を優先します。--trigger はラベルベースで、曖昧になる場合があります。
• クロスチェーンの simulate／cast では、チェーンごとの実行にも同じ選択済みトリガーを引き継ぐ必要があります。
• --json モードでは stdout のみを解析します。stderr には進行状況やスピナーの出力が表示される場合があります。

クエリ関数（価格／残高／APY／指標）

構造化データの取得には、常にアドバイザリーよりクエリ関数を優先してください。 これらは決定論的かつ高速で、LLM の呼び出しも必要ありません。

• price(BASE, QUOTE[, SOURCE]) — クエリプロバイダー経由でトークンの現在価格を取得します（Alchemy RPC URL が必要です）
• balance(ASSET[, ADDRESS]) — RPC 経由でオンチェーントークン残高を取得します（任意の RPC URL を使用できます）
• apy(VENUE, ASSET[, SELECTOR]) — プロトコルに基づく APY 情報を取得します（例：Aave、Morpho）
• metric(SURFACE, VENUE[, ASSET[, SELECTOR]]) — 汎用プロトコル指標情報を取得します
• セレクターの使い方：
• マーケット／Vault ID セレクター：apy(morpho, USDC, "wbtc-usdc-86")
• Vault セレクター（Morpho）：metric("vault_net_apy", morpho, USDC, "vault=0xVaultAddress")
• Morpho の vault_apy／vault_net_apy には明示的なセレクターが必要です。暗黙のデフォルトには依存しないでください。
• キー／値セレクター：metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")
• 価格、残高、APY、その他の構造化指標を取得するだけの目的で、アドバイザリー（advise）を使用しないでください

タスクで LLM による判断、推論、または解釈が必要な場合に限り、アドバイザリーを使用してください。

アドバイザリーの運用ルール

• アドバイザリーは明示的なステートメント形式にしてください：x = advise advisor: "prompt" { ... }。
• アドバイザリーの出力は型付きコントラクトとして扱い、output でスキーマを適用してください。
• すべてのアドバイザリーブロックで timeout と fallback を必須にしてください。
• アドバイザリーのロジックが価値を移動するアクションを制御する場合は、validate --strict を優先してください。
• プレビュー／ドライランからライブ実行に移行する際は、決定性を確保するためにリプレイを使用してください。
• 実行時のデバッグには、詳細なアドバイザリートレースをストリーミングする --advisory-trace-verbose（非 JSON モード）を使用してください。

プロトコルのメタデータとスナップショット

スナップショットのパラメーターと市場メタデータには、以下のプロトコルスキルを使用してください。

• grimoire-aave
• grimoire-uniswap
• grimoire-morpho-blue
• grimoire-hyperliquid
• grimoire-pendle
• grimoire-polymarket

プロトコル CLI の出力形式に関する方針：

• 自動化やネストされたペイロードには、--format json を優先してください
• 人が読みやすい概要には、--format table を使用してください

参考資料

• references/syntax-capabilities.md
• references/authoring-workflow.md
• references/anvil-cheatsheet.md
• references/cast-cheatsheet.md
• references/cli-quick-reference.md
• docs/how-to/simulate-on-anvil-fork.md
• docs/how-to/use-wallet-commands-end-to-end.md
• docs/how-to/use-advisory-decisions.md
• docs/how-to/compare-protocol-metrics.md
• docs/explanation/advisory-decision-flow.md
• docs/reference/cli.md
• docs/reference/spell-syntax.md
• docs/reference/grimoire-dsl-spec.md
• docs/reference/compiler-runtime.md