arcana
justinlavi/arcana
A framework for building grimoires — structured, AI-navigable knowledge bases with deterministic routing and slash-command skills for Claude, Codex, and more.
Instalação
npx convez-ai justinlavi/arcana1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
![]()

A framework for building grimoires — structured, AI-navigable knowledge bases the LLM keeps current.
Give your AI agent a map, not a maze.
Most knowledge lives in scattered files that AI has to search through, interpolate between, and ultimately guess at. Grimoires give AI agents an explicit routing map: a layered hub structure that leads from any question to the exact document that answers it — deterministically, every time. And the LLM owns the maintenance: it imports new sources, updates cross-references, flags stale claims, and keeps the wiki compounding.
Arcana is the engine you install once to build and maintain grimoires for any subject.
What's a Grimoire?
A grimoire is a structured knowledge base built around a single subject — personal recipes, team runbooks, HR policies, research notes, a campaign's lore.
Deterministic routing through hubs
Every folder has a hub — a markdown file named after the folder. Each hop narrows the search; the agent stops at the leaf that answers the question.
"What's the cure time for sourdough?" (shallow - 2 hops)
cooking-grimoire.md -> breads.md -> sourdough.md
"What's the windowpane test for laminated dough?" (deeper - 4 hops)
cooking-grimoire.md -> techniques.md -> lamination.md -> windowpane_test.md
Both paths are deterministic. The structure stays only as deep as the topic warrants. Full rules in operating model.
Storage layers
A grimoire keeps four kinds of content side-by-side: sources/ holds immutable artifacts the wiki cites; chapters/ holds the LLM-authored wiki; inbox/ is a transient drop zone for things waiting to be classified; log.md is an append-only record of every mutation. See operating model for ownership rules and the validator-enforced contracts.
Skills
Every grimoire ships its own slash-command skills — commands prefixed by that grimoire:
| Grimoire | Skill | What it does |
|---|---|---|
cooking-grimoire | /cook-recipe-add | Creates a new recipe from the grimoire's own template |
cooking-grimoire | /cook-meal-plan | Builds a plan from your documented ingredient inventory |
hr-grimoire | /hr-onboarding-checklist | Walks through the onboarding process step by step |
hr-grimoire | /hr-policy-lookup | Routes to the right policy document for a situation |
Knowledge and skills compound: the better your documentation, the smarter your skills.
The LLM does the maintenance
Arcana ships universal operations every grimoire inherits:
/grm-import <source>— file a source undersources/, scan existing chapters, propose page updates, apply them, append tolog.md./grm-add— add knowledge to the grimoire as a page or a chapter, written fresh or distilled from the current chat session (so a good answer doesn't evaporate into chat history)./grm-health-check— health-check the wiki: orphans, stale claims (>90 days unverified), ghost references (entities mentioned often but lacking a page), contradictions, missing cross-references./grm-validate [selector]— run the full deterministic validator profile for the active grimoire, or a targeted mechanical check./grm-update— bring Arcana and every grimoire in the library back to a current, validated, synchronized state./grm-sync— refresh Arcana skills plus the active grimoire's own skills./grm-help— list every grimoire command you can run.
Arcana command families are prefix-explicit: /arc-* acts on Arcana and platform surfaces (the engine, the home library ~/grimoires/library.json, agent files, and agent skill directories); /grm-* acts on the active grimoire. Full rules live in skill schema.
The human curates sources and asks questions. The LLM does the bookkeeping.
What's Arcana?
Arcana is the engine that powers all your grimoires. You install it once; your grimoires reference it forever.
Arcana provides (shared across every grimoire):
/arc-*platform skills and/grm-*universal grimoire skills- The page schema (
type,authority,sources,last_verifiedfrontmatter) that makes wikis machine-checkable - Formula templates for scaffolding new grimoires, chapters, and pages
- Validation rites: structure, naming, format, links, frontmatter, orphans, provenance, security, semantics, and skill-refs; audit playbooks for judgment checks such as boundaries
- Library management automation
- Framework documentation and governance
Your grimoires contribute:
- Their
chapters/(LLM-authored content) andsources/(immutable sources) - Their own
/<skill prefix>-*skills — actionable, domain-specific commands - Their
grimoire.jsonmanifest declaring their identity and skill prefix - Their
log.md— the append-only activity record
When you update Arcana, all your grimoires benefit — because they reference it rather than copy from it.
Supported Agents
Arcana automatically configures the agents it can safely write to. The current target matrix lives in agent targets:
- Claude Code — full skill registration; Arcana's
/arc-*and/grm-*commands plus each grimoire's own commands - Codex / ChatGPT — pointer-only registration from the same source files
- GitHub Copilot, Cursor, hosted ChatGPT, and other agents — manual instruction-block setup; see agent configuration for setup notes
Install
Before you start. Arcana runs inside an AI coding agent — its /grm-* and /arc-* commands are typed into that agent, not into a plain terminal. So you need three things first:
- A terminal with
git— to run the one-line installer below. (No terminal? See Install without a terminal.) - One supported AI agent, installed and signed in — Claude Code or Codex / ChatGPT CLI. This is the program you will type
/grm-createinto. See Supported Agents. - About five minutes.
curl -fsSL https://raw.githubusercontent.com/justinlavi/arcana/main/rites/summon.sh | bash
This installs into ~/grimoires/ and configures the AI agents you already have; it asks before installing any optional dependency and does not run as root. (On Arch-based systems, an accepted dependency prompt may use sudo pacman to install python-pip first.)
The summoning rite installs Arcana — the framework — configures your AI agents, and registers the /arc-* and /grm-* skill sets. If you have existing grimoires hosted on GitHub or GitLab, the rite can discover and clone them too. Otherwise, skip straight to building your first grimoire from scratch after Arcana is up.
Detailed installer mode rules live in summoning contract.
Open a new session inside your AI agent (not a plain terminal) and run /grm-create to start your first grimoire. (Maintainers: /arc-help lists the full platform catalog.)
Out of date, or something seems wrong? Update brings Arcana and every grimoire in the library back to a current, validated, synchronized state. Two ways to start it:
-
Run the skill:
/grm-update(or/arc-updatewhen maintaining Arcana directly). -
Or tell your AI agent:
Pull the latest Arcana, then read
arcana/UPDATE.mdfrom that checkout and follow its instructions exactly.
Both paths use UPDATE.md as the canonical source of truth.
If something stops working — skills vanished, the agent can't find a grimoire, or it's guessing instead of reading files — open a new session in your agent and run /grm-update.
-> installation - 5-minute smoke test - troubleshooting
Layout
~/grimoires/
|-- arcana/ # The engine - install once, reference forever
| |-- arcana.md # Root hub
| |-- UPDATE.md # Update & skill-less self-update entry point
| |-- invocations/ # AI-guided workflows
| |-- formulae/ # Templates for hubs, chapters, pages, sources
| |-- rites/ # Python automation scripts
| |-- skills/ # Slash-command source files
| |-- docs/ # Framework documentation (page_schema.md is canonical)
| |-- resources/ # Branding assets
|
|-- cooking-grimoire/ # A personal grimoire
| |-- cooking-grimoire.md # Root hub
| |-- grimoire.json # skill_prefix: cook -> /cook-* skills
| |-- log.md # Activity log
| |-- sources/ # Articles, transcripts, recipe screenshots
| |-- inbox/ # Drop zone for content awaiting classification
| |-- chapters/ # recipes/, techniques/, equipment/, ...
| | |-- recipes/recipes.md # Chapter hub (folder-name convention)
| | |-- recipes/sourdough.md # Leaf
| | |-- techniques/
| | |-- techniques.md # Chapter hub
| | |-- lamination/ # Sub-chapter (nests as deep as needed)
| | |-- lamination.md # Sub-chapter hub (same convention)
| | |-- book_folds.md # Leaf
| | |-- windowpane_test.md
| |-- skills/ # Grimoire skills
|
|-- hr-grimoire/ # A workplace grimoire
| |-- hr-grimoire.md # Root hub
| |-- grimoire.json # skill_prefix: hr -> /hr-* skills
| |-- log.md
| |-- sources/
| |-- inbox/
| |-- chapters/ # onboarding/, policies/, benefits/, ...
| |-- skills/
|
|-- library.json # Local registry of installed grimoires and their paths
Create as many grimoires as you need. Arcana provides the framework; each grimoire supplies its own knowledge, skills, and source artifacts.
Documentation
For everyone
| Update | Skill-less entry point to bring Arcana and every grimoire current |
| Installation | Before you start, one-command setup, install without a terminal, manual setup, smoke test, troubleshooting |
| Agent Configuration | Per-agent setup: Claude Code, Codex, Copilot, Cursor |
| Operating Model | Storage layers and routing |
| Page Schema | Frontmatter spec for every page |
| Obsidian | Open as a vault; graph-view color groups |
| VS Code | VS Code wikilink setup |
| Skills | Every command with descriptions |
| Reference | Plain-language terms, then full terminology and conventions |
Maintainer reference
| Summoning Contract | Summoning Rite installer contract: install/update modes, drift detection, fallbacks |
| Agent Targets | Supported agent target registry |
| Skill Schema | Command-family naming rules |
| Script Vs Ai | When to use rites vs invocations |
| Evals | Model-in-the-loop behavioral coverage for invocations |
| Governance | Maintaining and versioning Arcana |
| Command Surface | Public slash-command contract |
| Rite Profiles | Mutating-rite plan/apply/append contract |
| Release | Release and publish workflow |
| Architecture Backlog | Deferred architecture work queue |
| Contributing | How to contribute to Arcana |
| Arcana | Navigate everything |