convez.ai
Skill
justinlavi

arcana

justinlavi/arcana

Ver no GitHub
InicialPluginScore · de 0 a 100

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/arcana

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
v1.7.0
Issues abertas
1
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

arcana_icon

arcanaheader

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:

GrimoireSkillWhat it does
cooking-grimoire/cook-recipe-addCreates a new recipe from the grimoire's own template
cooking-grimoire/cook-meal-planBuilds a plan from your documented ingredient inventory
hr-grimoire/hr-onboarding-checklistWalks through the onboarding process step by step
hr-grimoire/hr-policy-lookupRoutes 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 under sources/, scan existing chapters, propose page updates, apply them, append to log.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_verified frontmatter) 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) and sources/ (immutable sources)
  • Their own /<skill prefix>-* skills — actionable, domain-specific commands
  • Their grimoire.json manifest 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:

  1. A terminal with git — to run the one-line installer below. (No terminal? See Install without a terminal.)
  2. One supported AI agent, installed and signed in — Claude Code or Codex / ChatGPT CLI. This is the program you will type /grm-create into. See Supported Agents.
  3. 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:

  1. Run the skill: /grm-update (or /arc-update when maintaining Arcana directly).

  2. Or tell your AI agent:

    Pull the latest Arcana, then read arcana/UPDATE.md from 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

UpdateSkill-less entry point to bring Arcana and every grimoire current
InstallationBefore you start, one-command setup, install without a terminal, manual setup, smoke test, troubleshooting
Agent ConfigurationPer-agent setup: Claude Code, Codex, Copilot, Cursor
Operating ModelStorage layers and routing
Page SchemaFrontmatter spec for every page
ObsidianOpen as a vault; graph-view color groups
VS CodeVS Code wikilink setup
SkillsEvery command with descriptions
ReferencePlain-language terms, then full terminology and conventions

Maintainer reference

Summoning ContractSummoning Rite installer contract: install/update modes, drift detection, fallbacks
Agent TargetsSupported agent target registry
Skill SchemaCommand-family naming rules
Script Vs AiWhen to use rites vs invocations
EvalsModel-in-the-loop behavioral coverage for invocations
GovernanceMaintaining and versioning Arcana
Command SurfacePublic slash-command contract
Rite ProfilesMutating-rite plan/apply/append contract
ReleaseRelease and publish workflow
Architecture BacklogDeferred architecture work queue
ContributingHow to contribute to Arcana
ArcanaNavigate everything
Ver o original no GitHub

Bom para

Relacionados