Spellbook

Table of Contents

• Quick Install
  • Windows Quickstart
• What Spellbook Does
  • The orchestrator pattern
  • Epistemic rigor
  • Named failure modes
  • Quality gates
  • Composition
  • Self-improvement
• The develop Skill
  • How it works
  • Parallelization
  • What it handles
• What's Included
  • Skills (60 total)
  • Commands (104 total)
  • Agents (16 total)
• Creative Modes
• Platform Support
  • AI Coding Assistants
  • Operating Systems
  • YOLO Mode
• Example Workflows
  • Implementing a Feature
  • Fun Mode in Action
  • Large Feature with Context Exhaustion
  • Test Suite Audit and Remediation
  • Parallel Worktree Development
  • Cross-Assistant Handoff
• Recommended Companion Tools
  • Heads Up Claude
  • MCP Language Server
• Key Skills
• Web Admin Interface
• Development
  • Serve Documentation Locally
  • Run MCP Server Directly
• Documentation
• Contributing
• Acknowledgments
• Attribution
• License

Quick Install

curl -fsSL https://raw.githubusercontent.com/axiomantic/spellbook/main/bootstrap.sh | bash

The installer requires Python 3.10+ and git, then automatically installs uv and configures skills for detected platforms.

Upgrade: cd ~/.local/share/spellbook && git pull && python3 install.py

Uninstall: python3 ~/.local/share/spellbook/uninstall.py

See Installation Guide for advanced options.

Windows Quickstart

irm https://raw.githubusercontent.com/axiomantic/spellbook/main/bootstrap.ps1 | iex

Requirements: Python 3.10+, git, and PowerShell 5.1+.

• Symlinks require Developer Mode enabled in Windows Settings (falls back to junctions or copies otherwise)
• Service management uses Windows Task Scheduler
• Install location: %LOCALAPPDATA%\spellbook

What Spellbook Does

Spellbook is a harness-augmentation layer for AI coding assistants. The harness is the runtime that hosts the agent loop and executes tools (Claude Code, Codex, OpenCode, Gemini CLI, ForgeCode). Spellbook plugs into whichever harness you are running and adds skills, slash commands, hooks, profiles, and a shared MCP server (memory, focus stints, session resume) on top.

Three things distinguish it from harness-native features and from other skill collections:

• Harness-agnostic. The same skills, commands, and memory work across every supported harness on the same project. Switch from Claude Code to OpenCode mid-task and the workflow continues.
• Shared centralized MCP server. Memories, focus stints, and session-resume state live in one place, so context stored from a Claude Code session surfaces in an OpenCode session on the same repo. No individual harness ships this.
• Skills + hooks layer no harness ships natively. Autonomy enforcement, quality gates, parallel subagent dispatch, and a session resume protocol sit on top of whatever the harness provides.

Instead of just telling an assistant about your codebase, Spellbook gives the assistant structured workflows for research, design, implementation, testing, and review, along with guardrails for the specific ways LLMs tend to cut corners.

The orchestrator pattern

The main agent dispatches subagents rather than doing implementation work directly. This keeps the main context window free for strategic coordination instead of filling it with source code, and it means each subagent starts with a fresh perspective rather than carrying accumulated assumptions. Parallel dispatch lets multiple tasks run simultaneously.

Epistemic rigor

The system is designed to distrust its own outputs. Fact-checking treats every claim as a hypothesis to verify. Green mirage auditing asks whether a test would actually fail if the code were broken, which is a different question from whether the test passes. Hunch verification intercepts moments of claimed discovery and requires reframing them as testable hypotheses. Dehallucination names the specific ways LLMs confabulate and provides recovery protocols.

Test-driven development is treated as an epistemic practice: tests written before implementation answer "what should this do?" while tests written after answer "what does this do?" -- and the system's quality gates are designed around that difference.

Hallucination prevention draws on peer-reviewed research. Chain-of-Verification self-interrogation (Dhuliawala et al., 2023) requires verification skills to generate and answer questions about their own claims before finalizing verdicts. Atomic claim decomposition (Min et al., FActScore, EMNLP 2023) breaks compound statements into independently verifiable units. API hallucination detection checklists in code review and quality enforcement catch the specific pattern where LLMs generate syntactically valid but non-existent API calls.

Named failure modes

LLMs fail in predictable ways, and Spellbook names those patterns so it can build mechanical countermeasures. Seven rationalization patterns are catalogued and blocked. Three consecutive fix failures trigger architectural reassessment instead of a fourth attempt. Research stagnation triggers a plateau breaker. A devil's advocate review that finds zero issues is flagged as incomplete.

Quality gates

Every substantial skill runs as a sequence of phases with mandatory gates between them. Tests must pass, code review must clear, claims must verify against source, and tests must actually catch regressions. These gates cannot be bypassed by YOLO mode or autonomy settings -- YOLO grants permission to act without asking, but not to skip verification.

Composition

Skills invoke skills. develop orchestrates design-exploration, writing-plans, test-driven-development, requesting-code-review, fact-checking, auditing-green-mirage, and finishing-a-development-branch. debugging invokes verifying-hunches and isolated-testing. When a skill outgrows its scope, it splits into a thin orchestrator and supporting commands.

Self-improvement

Some skills exist to improve other skills. Usage analytics measure completion and correction rates. The skill-writing skill applies TDD to skill creation itself. Instruction engineering codifies prompt research into technique, and prompt sharpening audits for ambiguity. A/B testing compares skill versions against each other so improvements can be measured rather than assumed.

The develop Skill

You say "add dark mode" or "migrate the auth system to OAuth2" or "build a webhook delivery pipeline with retry logic." The develop skill orchestrates the full feature lifecycle through 20+ specialized skills and commands. The first question it asks is how involved you want to be:

Fully autonomous. Describe the feature and walk away. It researches your codebase, surfaces ambiguities, resolves them, designs the architecture, writes a detailed implementation plan, builds with test-driven development, reviews its own code, fact-checks its claims, audits its tests for false confidence, and opens a PR. Each step runs in a fresh subagent with its own quality gate.

Highly interactive. The same pipeline with the same rigor, but you stay in the conversation. Ambiguities become specific questions grounded in what it found in your code, and architectural tradeoffs come with evidence. Checkpoints pause for your input.

Or anywhere between. You can run mostly autonomous with pauses only for critical decisions, and set the level once at the start.

How it works

The system classifies your request by complexity using mechanical heuristics -- file count, behavioral change, test impact, structural change, integration points. Trivial changes exit the skill entirely. Simple changes follow a lightweight path with automatic upgrade if they turn out harder than expected. Standard and complex features get the full pipeline:

1. Research -- Subagent explores your codebase. Answers come with confidence levels and file:line evidence. Every unknown is catalogued.
2. Discovery -- Each ambiguity becomes a specific question. In autonomous mode, it answers its own questions with further research. A devil's advocate reviews the understanding document before design begins.
3. Design -- Architecture design exploration with tradeoff analysis. A design doc auditor checks whether someone could implement from the doc without guessing, and flags every gap.
4. Planning -- Atomic implementation plan with TDD steps. A plan auditor verifies interface contracts, behavior assumptions, and cross-task dependencies.
5. Implementation -- Test-driven execution with per-task code review, fact-checking, and completion verification. Parallel tracks can run in isolated git worktrees with dependency-ordered smart merge.
6. Verification -- Green mirage audit: would these tests catch real regressions? Comprehensive claim validation against design and plan. Full test suite.
7. Finish -- PR with branch-relative description, local merge, or keep the branch. Worktree cleanup.

For features too large for one context window, it generates self-contained work packets and hands them off to separate sessions.

Parallelization

Three strategies, chosen at the start:

• Conservative -- Sequential execution. Safest, simplest.
• Maximize parallel -- Independent tasks dispatch as concurrent subagents with conflict detection and integration testing.
• Per-track worktrees -- One git worktree per parallel track, running simultaneously, merged in dependency order with three-way conflict analysis and per-round test verification.

What it handles

Complete feature implementation, greenfield project creation, refactoring (with automatic behavior-preservation mode), and migrations. Bug fixes route to the dedicated debugging skill. Simple changes get a lightweight path; complex multi-track features get work packets and parallel sessions.

What's Included

Skills (60 total)

Reusable workflows for structured development:

† Derived from superpowers

Commands (104 total)

† Derived from superpowers