Spellbook Docs

Overview

Spellbook helps teams define what should be built, how it should behave, what constraints must be respected, and how generated code should be verified before it is trusted.

Spellbook is infrastructure for disciplined AI-native development.

The problem

AI coding agents can produce code quickly, but speed alone is not enough for serious engineering.

• clear intent
• domain correctness
• architecture consistency
• local repo conventions
• safety checks
• reviewable changes
• audit logs
• repeatable workflows

The Spellbook approach

Spellbook places coding agents inside a structured engineering loop.

init -> specify -> architecture -> local conventions -> plan -> build -> test -> review -> ship -> verify -> monitor -> learn

What Spellbook provides

• A project control layer
• A specification repository
• Requirements and quality gates
• Agent onboarding rules
• Controlled execution workspaces
• Task state tracking
• Test and verification reports
• Audit-ready artifacts

What Spellbook is not

Spellbook is not a replacement for engineers. Spellbook is not just a prompt template. Spellbook is not only a code generator. Spellbook is not magic.

Minimal flow

The quickest path is to initialize the project, capture intent, create a task, run the task, and verify the output.

spellbook init
spellbook specify
spellbook requirements add
spellbook task create "Add disabled-user login rejection"
spellbook plan task-001
spellbook build task-001
spellbook test task-001
spellbook verify task-001
spellbook review task-001

What to check

A successful first run should produce a plan, changed files, test output, a diff summary, and a review report linked back to requirements.

Initialize

spellbook init

The initialization step should create onboarding files, a project manifest, and folders for context, requirements, architecture, tasks, and reports.

First files

Start with `AGENTS.md`, `PEOPLE.md`, `spellbook.yaml`, and a short product context file. These files tell agents how to behave and tell humans what review evidence to expect.

Create and plan

spellbook task create "Reject disabled-user login"
spellbook plan task-001

Execute and review

After execution, review the task record before accepting the diff. The report should show why the change exists, which requirement it satisfies, and what still needs human judgment.

Install

Install the Spellbook command line in the environment where agents will plan and execute work.

Commands

spellbook init
spellbook specify
spellbook requirements add
spellbook architecture init
spellbook conventions init

spellbook task create "Add disabled-user login rejection"
spellbook plan task-001
spellbook build task-001
spellbook test task-001
spellbook verify task-001
spellbook review task-001

Prompt-driven vs specification-driven

Goal

The goal is not to make agents more creative. The goal is to make their work more constrained, inspectable, and trustworthy.

Loop steps

1. init
2. specify
3. architecture
4. local conventions
5. plan
6. build
7. test
8. review
9. ship
10. verify
11. monitor
12. learn

Boundaries

Agents should know which tools are allowed, which actions need approval, which commands validate the work, and which shortcuts are forbidden.

When to use packs

Use packs when a task crosses a known engineering boundary, such as authentication, payments, authorization, audit logging, or production change management.

Examples

• Disabled users cannot log in.
• Transfers require a source account, destination account, and settled ledger entry.
• Audit events must preserve actor, action, target, and timestamp.

Suggested format

invariant: PasswordHashNeverReturned
must_hold_for:
  - GET  /me
  - POST /login
forbidden_shortcuts:
  - return user model directly
  - skip response serialization

Examples

Conventions should tell agents where tests live, how errors are represented, how logs are structured, and when a change requires approval.

Common gates

• tests pass
• requirements have evidence
• architecture constraints are respected
• security rules pass
• review report is produced

States

created -> planned -> running -> testing -> review_ready -> approved -> shipped
created -> planned -> blocked
running -> failed -> retry_planned

Definitions

Directory tree

.spellbook/
├── AGENTS.md
├── PEOPLE.md
├── spellbook.yaml
├── context/
├── domain/
├── requirements/
├── architecture/
├── local-conventions/
├── runner/
├── tasks/
└── reports/

Reference

What belongs here

Goals, actors, workflows, non-goals, boundaries, success metrics, product intent, and stable product language.

What belongs here

Entities, states, events, effects, invariants, forbidden shortcuts, contracts, failure modes, and risk maps.

What belongs here

Acceptance criteria, requirement IDs, security requirements, quality bars, compliance mappings, and evidence expectations.

What belongs here

Architecture decisions, integration patterns, ownership, component boundaries, and mappings between domain concepts and implementation.

What belongs here

Naming, test style, error handling, observability, code layout, logging, commit rules, and approval-required agent behavior.

What belongs here

Sandboxing, timeouts, allowed tools, captured logs, artifacts, retry behavior, task state machine, and verification commands.

What belongs here

Task intent, scope, plan, changed files, verification, artifacts, risk flags, retry history, and review status.

What belongs here

Test results, verification results, risk summaries, diff summaries, task timelines, cost and latency metrics, and learning notes.

Spec

Intent:
  Users can register, log in, log out, and access their profile.

Domain:
  User
  Session

States:
  User: PendingEmailVerification | Active | Disabled
  Session: Active | Revoked | Expired

Invariants:
  DisabledUserCannotLogin
  SessionBelongsToExistingUser
  SessionHasExpiry
  PasswordHashNeverReturned
  OnlyActiveSessionAuthorizesProtectedRoutes

Runtime:
  AuthController
  UserRepository
  SessionRepository
  PasswordHasher
  TokenIssuer
  AuditLogger

Routes:
  POST /register
  POST /login
  POST /logout
  GET /me

Tests:
  Disabled user login is rejected
  Expired session is rejected
  Password hash is never returned
  Token is not issued before password validation

Useful checks

• Transfer has source and destination accounts.
• Ledger entries balance.
• Retries are idempotent.
• Failed transfers preserve audit evidence.

Pattern

Capture current behavior first, map risky modules, define forbidden shortcuts, then migrate behind tests and evidence reports.

Suggested gates

• authentication checks
• authorization checks
• input validation
• error response policy
• audit logging

Evidence

Ask the task report to show which requirement each test covers and which requirements still lack coverage.

Expected capabilities

created -> planned -> running -> testing -> review_ready
failed -> retry_planned -> running
blocked -> human_input_required

Example

gate: auth-boundary-review
requires:
  - npm test
  - security-policy-check
  - human approval

Guidance

Keep plugins narrow. They should add a capability without hiding task evidence from reviewers.

Examples

• Reject destructive commands unless approved.
• Require human approval for auth, payment, and production-change boundaries.
• Reject skipped tests unless a task report explains why.

Signals

Track success rate, time to success, retries, failed attempts, human interventions, requirements satisfied, requirements missed, cost, latency, diff size, review corrections, and spec gaps.

Pattern

Run `spellbook validate`, execute required test commands, attach reports to pull requests, and fail the build when required evidence is missing.

Metrics

Measure requirements coverage, test pass rate, retry count, review corrections, security findings, cost per task, and spec gaps discovered.