Spellbook

Specification-driven control layer for AI coding agents.

SolidSpire Spellbook is not a coding agent. It is the control layer around coding agents you already use - it turns source truth, invariants, allowed scope, tests, gates, and evidence requirements into a bounded execution loop where agents can produce changes that humans can actually review.

Status: early. This repository is the core-loop and auth-v0 reference demo. It is built for evaluation and feedback — not production. Spellbook is meant to be shaped in the open.

Bring your agent

Spellbook does not replace Claude Code, Cursor, Codex, or any other agent. It wraps them.

• Bring your agent — Spellbook governs the work your agent writes the code.
• Multi-model — model-agnostic by design. Choose the model per task.
• Language- and framework-agnostic — the control layer is designed to be stack-neutral. auth-v0 is TypeScript because it is the reference demo, not because Spellbook is TypeScript-only.

What Is Spellbook

• Specification-driven control layer for coding agents
• Spec graph vs repo graph
• Deterministic verification
• Evidence reports
• Human review with proof
• Spellbook is not the coding agent

Spellbook For Spellbook

This repository is Spellbook’s own first real customer: Spellbook uses a root .spellbook/ context to describe, generate, observe, and verify the Spellbook system itself.

That is the “Spellbook for Spellbook” idea: the core project is governed by the same source-truth, generated-artifact, observed-fact, task-boundary, verification, and evidence model that it offers to other projects.

The root context describes the Spellbook control layer. The auth-v0 example has its own independent context under examples/auth-v0/.spellbook/.

Repository Layout

.spellbook/                 Root Spellbook-for-Spellbook context
app/spellbook/cli/          Spellbook CLI implementation
app/spellbook/tools/        Reusable tool boundary for core engines
examples/auth-v0/           Example application and demo Spellbook context
scripts/sb                  Public command dispatcher
docs/                       Root Spellbook documentation

The auth-v0 example is documented separately:

• examples/auth-v0/README.md
• examples/auth-v0/docs/

Spellbook Context Layout

Each Spellbook context is intentionally small at the top level:

.spellbook/
  source/        authored canonical truth (six layers: context, domain,
                 architecture, local-conventions, tests, release)
  generated/     derived artifacts: docs, specs, trace, spec-graph,
                 planning, facts, tasks, reports
  verification/  authored verification policy: file-parsers/ (static),
                 file-probes/ (dynamic), schemas/, registry.yaml
  profile/       context-owned configuration (task profile JSON)
  spellbook.yaml context manifest

See:

• Source folder
• Generated folder
• Generated tasks
• Generated reports
• Verification folder

Core Loop

init -> specify -> collect -> plan -> build -> verify -> report

specify projects source truth into generated specs, docs, traces, and graph files. collect records observed repository facts. plan, build, verify, and report operate from that combined truth and evidence surface.

Quickstart

npm install
npm run build:all

bash scripts/sb --root . specify --check
bash scripts/sb --root . collect
bash scripts/sb --root . verify

The equivalent package shortcut is:

npm run verify:root

Task-specific root evidence is available through the current root task:

bash scripts/sb --root . verify --task V001-spellbook-implementation-consistency
bash scripts/sb --root . probe spellbook-cli-clean-checkout

The auth-v0 example uses the same dispatcher with a different context root. See examples/auth-v0/docs/planning.md for the canonical P002 task flow.

Why This Exists

AI coding agents can generate useful code, but teams still need answers to the engineering questions that make code trustworthy:

• Did the agent change the right thing?
• Did it stay inside the task?
• Did it satisfy the domain rule?
• Did tests actually prove the behavior?
• What evidence should a human reviewer inspect?

Spellbook does not replace engineers. It gives engineers a more disciplined review packet: intended truth, bounded scope, observed facts, deterministic checks, and evidence.

Source-of-truth chain

The canonical evidence report trace:

intent
→ capability
→ invariant
→ architecture component
→ implementation surface
→ file / symbol
→ test case
→ release gate
→ evidence report

auth-v0 example:

intent.auth.prevent_deactivated_user_login
→ capability.auth.login
→ invariant.auth.deactivated_user_cannot_login
→ component.auth_application_service
→ symbol.AuthApplicationService.login
→ file.app/src/application/AuthApplicationService.ts
→ test.security.deactivated_user_login_rejected
→ gate.release.deactivated_user_login_rejected
→ gate_result.P002.verify
→ evidence.P002.evidence_report

Documentation

• Project model
• Command dispatcher
• Spellbook tools
• Context config
• Context isolation
• Generated boundaries
• Verification folder
• Verification pipeline
• Example package boundary follow-up
• Source graph
• Planning
• Evidence
• Testing and verification

Current status

Spellbook is early.
This repository is the auth-v0 reference demo for the v5 control-layer loop.
The goal is to make AI-generated code changes bounded, verifiable, and reviewable.

This repository ships v6. Highlights:

• root Spellbook-for-Spellbook source truth and a runnable CLI under app/spellbook/cli/;
• reusable context, source, normalizer, and verification-support surfaces under app/spellbook/tools/;
• an independent auth-v0 example under examples/auth-v0/;
• generated task, report, fact, trace, probe, and evidence outputs;

For the canonical v6 changelog, gate matrix, and snapshot:

• docs/release6-notes.md — what changed in v6.
• repository-summary-v6.md — one-page snapshot.

If you try the auth-v0 demo, we would especially like to hear:

• where the setup breaks

• where the README is unclear

• whether the evidence report helps you trust the agent output

• what your current AI-code-review workflow looks like

v7 roadmap

— the .sb file migration to multi-document YAML + kind-led ids + ${ctx.*} references + a typed two-pass compile — is planned in next sequence update

• Bounded Execution For A Coding Agent. Drive sessions using skills, hooks, agents, commands.
• Sandboxed execution
• Hardening the deterministic verification
• Better assumption mapping
• More verification gates
• Improved evidence reports
• Cleaner project seed intake
• More real-world demo tasks
• Spellbook UI — coming soon
• Spellbook Cloud — coming soon

Current limitations are explicit: some reusable engines still live under app/spellbook/cli/src/, the .sb corpus is pre-migration, and the spec graph is regex-mined rather than typed. None are regressions; all are tracked.

Demo-oriented package shortcuts are documented in docs/scripts-sb.md.

Questions, suggestions, and partnerships

Contacts:

- Questions, suggestions and partnerships: max@solidspire.com

Licence

Spellbook is licensed under the Apache License 2.0.

Copyright 2026 SolidSpire.

Commercial services, hosted infrastructure, enterprise integrations, managed verification environments, and proprietary plugins may be offered separately by SolidSpire.

More Reading

• Site docs