grimoire #

Overview
#

Units of work often cut across repos — a type change ripples through three packages, a new feature needs coordinated planning in four. A grimoire gives those units a home without polluting implementation repos with planning artifacts. It's a markdown meta-repo that holds working understanding: what was decided and why, what's next, what connects to what.

For AI agents, a grimoire is persistent memory across stateless sessions. Each agent arrives fresh, reads the grimoire to orient, does work, and updates it before the session ends. The grimoire bridges what one session learned to the next.

The full skill documentation is at skills/grimoire.

Structure
#

Three core primitives, plus supporting layers that emerge as the grimoire grows:

Primitive	Location	Purpose
Lore	`lore/{project}/`	Per-repo planning projections — decisions, TODOs, cross-cutting concerns. Standard pair: `CLAUDE.md` + `TODO.md`
Quests	`quests/`	Cross-repo goals with dependencies and completion criteria. Single-repo work stays in lore TODOs
Skills	`skills/{name}/`	Agent skill knowledge files — conventions, references, and tooling scripts

grimoire/
├── lore/           # per-repo planning projections
│   └── {project}/
│       ├── CLAUDE.md    # planning context, decisions
│       └── TODO.md      # active work items
├── quests/         # cross-repo goals
│   ├── CLAUDE.md        # quest index
│   └── {slug}.md        # individual quests
├── skills/         # agent knowledge modules
│   └── {name}/
│       └── SKILL.md
└── writing/        # philosophy and vision (not repo-scoped)

writing/ holds ideas that span the whole ecosystem rather than projecting a single repo — design philosophies, conceptual foundations. Supporting directories like scripts/ and scries/ for experimental linting may emerge from need; a new grimoire starts with just lore/ and grows.

Work loop
#

Each agent session reads the grimoire to orient, does the work, then writes back what changed.

Phase	Action
Orient	Read `lore/{project}/` for planning context and TODOs. Check `quests/` for cross-repo goals touching this project. Read the repo's own `CLAUDE.md` for implementation context.
Work	Do the implementation work in the target repo.
Update	Update `TODO.md` for work items. Check off quest tasks. Update `CLAUDE.md` if decisions changed.
Graduate	Should content advance? Done quests synthesize into lore, then get deleted. Ideas that matured into code get removed from TODOs.

Knowledge lifecycle
#

Content flows forward through stages and gets deleted from earlier ones when it graduates — existing in one place at a time, wherever it's most useful right now.

lore → quest → implementation → published → lore
 (ideas)  (goals)    (code)        (docs)     (new understanding)

The cycle turns at different speeds — ideas accumulate slowly in lore, quests can move fast through implementation — but content should exist in one place at a time, wherever it's most useful right now.

Key ideas
#

Taste. A grimoire encodes a developer's preferences — which patterns are valued, which tradeoffs are preferred, what "good" looks like. This is what makes a grimoire yours rather than generic documentation. Agents can apply taste fluidly rather than following rigid rules.

Always slightly wrong. A grimoire is approximate context, not ground truth. It's trying to capture dimensions of a person's entire body of work — too large for any document to represent faithfully. When current state matters, read the actual repo. Past a certain threshold of staleness, a doc misleads more than it helps.

Rewrite, don't just prune. Conceptual staleness — content whose framing no longer matches reality — is more dangerous than old files. A lore doc untouched for months can still be accurate; a freshly-written TODO that assumes yesterday's architecture misleads immediately. Delete what's dead, rewrite what's drifted. The grimoire stays useful by staying accurate, not just lean.

Growth trajectory. A grimoire starts small — one CLAUDE.md, a couple of TODO.md files. Quests appear when work first spans multiple repos. Writing appears when ideas emerge that don't project any single repo. Don't build structure speculatively.

More
#

For full conventions — lore structure, quest format, creating new artifacts, common pitfalls — see the grimoire skill. For coding conventions across the @fuzdev ecosystem, see fuz-stack.