Fran Algaba
001b16258c
* migrate .spell DSL from indentation to brace-delimited syntax (SPEC-001)
Replace Python-style 2-space indentation with Rust/Go curly-brace
blocks across the entire codebase. This is a breaking syntax change
that improves agent authorship — LLMs handle braces far better than
whitespace-significant formats.
Tokenizer: remove INDENT/DEDENT tokens, split bracketDepth into
parenDepth (suppresses newlines) and braceDepth (preserves newlines),
remove IndentationError.
Parser: replace all INDENT/DEDENT patterns with LBRACE/RBRACE across
~22 methods. New parseBraceBlock() helper replaces parseStatementBlock().
Two patterns: label blocks (label: { }) and keyword blocks (keyword { }).
AST, transformer, IR generator, and runtime are unchanged — indentation
was purely a lexical/parse concern.
Updated 86 .spell fixture files, 15 test files, 20 documentation files,
README, AGENTS.md, VM spec references, and compiler-pipeline docs.
620 tests pass, 0 fail.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add changeset
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Grimoire Documentation
This documentation follows the Diátaxis framework. If you're new, start with the execution mode you want to use.
Start here
Grimoire uses the same spell syntax in both environments. The differences are guarantees and tooling.
- VM mode (in-agent, best-effort): run spells inside an agent session with snapshot data and no adapters. For quick protocol prototyping, use venue CLI snapshots. Start with Getting started and Run spells in VM mode.
- Deterministic runtime (CLI): compile, simulate, and cast with adapters and state persistence. Start with Getting started and Run spells with the CLI.
If you want the full comparison, see Execution modes.
Advisory steps (**...** and advise) call Pi when a model is configured (spell model, CLI model/provider, or Pi defaults). If no model is available, the runtime uses the spell fallback. See CLI reference and Pi advisory execution spec.
Suggested flow: explore in VM → record advisory in CLI simulate → replay deterministically in cast. See Run spells with the CLI.
If you are contributing to the repo, see CONTRIBUTING.md and Run tests and checks.
Updating (user view)
- Update the CLI:
npm i -g @grimoirelabs/cli@latest - Use
npxfor latest without install:npx -y @grimoirelabs/cli@latest <command> - Update packages in your project:
npm i @grimoirelabs/core@latest @grimoirelabs/venues@latest - Update the VM skill: re-install with
npx skills add https://github.com/franalgaba/grimoire(or copyskills/grimoire-vminto your agent skills directory again)
Tutorials
Step-by-step guides for newcomers.
How-to guides
Task-focused recipes.
- Run spells with the CLI
- Run spells in VM mode
- VM quickstart (snapshot-driven)
- Transition to deterministic execution
- Configure slippage and constraints
- Bridge with Across
- Add and organize spells
- Add a new venue adapter
- Build spells programmatically
- Run tests and checks
- Publish packages
Reference
Authoritative specifications.
- Spell syntax reference
- Grimoire DSL spec
- Core API reference
- Venues package reference
- CLI reference
- IR schema reference
- Action constraints reference
- Grimoire VM spec
- Grimoire VM conformance
- Pi advisory execution spec
Explanation
Background and design rationale.