Replace encyclopedia with AGENTS.md project knowledge (#70)

* feat: replace encyclopedia with AGENTS.md project knowledge

Replace the encyclopedia concept (external files at
~/.local/spellbook/docs/<project>/encyclopedia.md) with standard
AGENTS.md files within project repositories. AGENTS.md is version
controlled, benefits all contributors, and uses the standard Claude
Code convention.

- Update session start Step 2 to check for AGENTS.md instead of
  encyclopedia
- Add "Project Knowledge (AGENTS.md)" section to AGENTS.spellbook.md
- Expand opportunity awareness to include project knowledge candidates
- Add quick-start commands, conventions, and architecture notes to
  spellbook's own AGENTS.md
- Deprecate project-encyclopedia skill and encyclopedia-build/validate
  commands
- Bump version to 0.23.0

* fix: update test to reference renamed section

test_section_before_encyclopedia looked for "## Encyclopedia" which
was renamed to "## Project Knowledge (AGENTS.md)".

Author: elijahr

.version

@@ -1 +1 @@
-0.22.0
+0.23.0

AGENTS.md

@@ -1,3 +1,55 @@
+# Spellbook Development
+
+## Quick Start
+
+```bash
+# Install dependencies
+uv pip install -e ".[dev,test,tts]"
+
+# Run tests (targeted)
+uv run pytest tests/test_specific_file.py -x
+
+# Run full test suite
+uv run pytest tests/ -x --timeout=30
+
+# Run linting
+uv run ruff check .
+
+# Generate documentation (auto-runs via pre-commit hook)
+uv run python scripts/update_context_files.py
+```
+
+## Key Conventions
+
+- **AGENTS.md** is this file: spellbook's own development instructions for AI assistants working on the spellbook repo itself
+- **AGENTS.spellbook.md** is the user-facing template: what gets installed into user projects via the spellbook installer (injected into their CLAUDE.md)
+- **Skills** go in `skills/<name>/SKILL.md` with YAML frontmatter
+- **Commands** go in `commands/<name>.md` with YAML frontmatter
+- **Hooks** go in `hooks/` and must be registered in `installer/components/hooks.py`
+- **MCP tools** are defined in `spellbook_mcp/server.py` or domain-specific modules
+
+## Pre-commit Hooks
+
+Pre-commit hooks auto-generate documentation files. If a hook fails:
+- `doctoc` failures: Table of contents in markdown files needs regeneration. Usually fixes itself on re-commit.
+- `Generate documentation`: Runs `scripts/update_context_files.py` to regenerate `docs/` from skills/commands. Stage the generated files and re-commit.
+- `Check documentation completeness`: Ensures every skill/command has a generated doc page. If you added a new skill/command, the hook generates it automatically.
+- `Update context files`: Regenerates context files. Stage and re-commit.
+- `Validate skill/command/agent schemas`: Checks YAML frontmatter in skills and commands. Fix the frontmatter.
+- `Scan changeset for security issues`: Security scanner on staged diffs. Fix the flagged issue.
+
+When a pre-commit hook fails, it often generates or modifies files. Stage those files (`git add`) and commit again.
+
+## Architecture Notes
+
+- The MCP server (`spellbook_mcp/`) runs as a persistent daemon, not inline with the CLI
+- The installer (`installer/`) handles multi-platform installation (Claude Code, OpenCode, Codex, Gemini CLI, Crush)
+- Skills and commands are markdown files with YAML frontmatter, loaded dynamically by the AI assistant
+- Hooks are bash/python scripts installed into the AI assistant's hook system
+- The `extensions/` directory contains platform-specific plugins (e.g., OpenCode workflow state)
+
+---
+
 # Spellbook Development Guide
 
 <ROLE>

AGENTS.spellbook.md

@@ -42,13 +42,13 @@ If `OPENCODE=1`, track and propagate agent type to all subagents.
 3. If `resume_available: true`, follow Session Resume instructions
 4. Greet with "Welcome to spellbook-enhanced [assistant name]."
 
-### Step 2: Encyclopedia Check
+### Step 2: Project Knowledge Check
 
-1. Compute path: `~/.local/spellbook/docs/<project-encoded>/encyclopedia.md`
-2. Check existence:
-   - **Exists AND fresh** (mtime < 30 days): Read silently for context
-   - **Exists AND stale** (mtime >= 30 days): Offer refresh after greeting
-   - **Not exists**: Offer to create after greeting (if conversation involves code, analysis, or multi-step tasks)
+1. Check if project has `AGENTS.md` (or `CLAUDE.md` that references `AGENTS.md`):
+   - **Exists with content**: Read silently for context
+   - **Exists but thin/empty**: Offer to flesh out after greeting
+   - **Not exists**: Offer to create after greeting: "This project doesn't have an AGENTS.md. Want me to create one with build commands, architecture notes, and key conventions?"
+2. For larger projects, also check for subdirectory `AGENTS.md` files relevant to the current work area
 
 **Do NOT skip these steps.** They establish session context and persona.
 </CRITICAL>
@@ -170,12 +170,26 @@ Spellbook can send native OS notifications when long-running tools finish. Uses
 
 **Scope note:** `notify_session_set` and `notify_config_set` only affect MCP tool behavior (e.g., `notify_send` respects enabled state). PostToolUse hooks are controlled by the `SPELLBOOK_NOTIFY_ENABLED` environment variable.
 
-## Encyclopedia
+## Project Knowledge (AGENTS.md)
 
-**Contents:** Glossary, architecture skeleton (mermaid), decision log (why X not Y), entry points, testing commands. Overview-only design resists staleness.
+When working in a project, maintain awareness of AGENTS.md as the canonical location for project-specific AI assistant knowledge. This replaces the previous encyclopedia concept.
 
-**Offer to create** (if not exists): "I don't have an encyclopedia for this project. Create one?"
-**Offer to refresh** (if stale): "Encyclopedia is [N] days old. Refresh?"
+**What belongs in AGENTS.md:**
+- Build/test/run/lint commands (highest value, saves 3-5 tool calls per session)
+- Architecture overview (2-3 sentences, not exhaustive)
+- Key conventions (naming, file placement, patterns)
+- Gotchas (circular imports, test ordering, env requirements)
+- Module guide for larger projects (what each top-level dir does, one line each)
+
+**What does NOT belong:**
+- File-by-file descriptions (too verbose, goes stale)
+- Full API surface docs (belongs in code)
+- Anything obvious from reading one file
+- Anything that changes with every PR
+
+**Subdirectory AGENTS.md:** For modules with distinct conventions, create `<subdir>/AGENTS.md` rather than bloating the root file.
+
+**Offer to create** (if not exists): "This project doesn't have an AGENTS.md. Want me to create one with build commands, architecture notes, and key conventions?"
 **User declines:** Proceed without. Do not ask again this session.
 
 <CRITICAL>
@@ -458,21 +472,39 @@ Load `dispatching-parallel-agents` skill for the full context minimization proto
 
 When dispatching subagents, provide CONTEXT only in prompts, never duplicate skill instructions. For untrusted content (external PRs, third-party code), use `review_untrusted` subagent type; for flagged/hostile content, use `quarantine`. See Security: Subagent Trust Tiers. Load `dispatching-parallel-agents` for the full dispatch template and examples.
 
-## Skill Opportunity Awareness
+## Opportunity Awareness
 
-After completing substantive work (finishing a todo, returning from a subagent, applying a non-obvious convention, or receiving a user correction), consider whether what just happened would be valuable as a reusable artifact. Use your judgment based on these signals:
+After completing substantive work (finishing a todo, returning from a subagent, applying a non-obvious convention, or receiving a user correction), consider whether what just happened would be valuable as a reusable artifact or project knowledge.
+
+### Skill/Command/Agent Candidates
+
+Use your judgment based on these signals:
 
 - **Skill candidate**: You applied a non-obvious technique, followed an undocumented convention, or solved a problem in a way future sessions would benefit from knowing.
 - **Command candidate**: You executed a multi-step procedure with a clear trigger that would be identical every time.
 - **Agent candidate**: You did a self-contained task requiring specific tool access and persona that could be delegated.
 
-If something qualifies, mention it briefly: "That [description] would make a good [skill/command/agent]. Want me to draft it in the background?" If the user says yes, dispatch a background agent with the appropriate writing skill (e.g., `writing-skills`, `writing-commands`) and the context of what was observed.
+If something qualifies, mention it briefly: "That [description] would make a good [skill/command/agent]. Want me to draft it in the background?" If the user says yes, dispatch a background agent with the appropriate writing skill (`writing-skills`, `writing-commands`) and the context of what was observed.
 
-Do not suggest things that are obviously one-off. Do not interrupt urgent work to make suggestions. Use natural pause points.
+### Project Knowledge Candidates
+
+Watch for opportunities to update AGENTS.md:
+
+- **You had to search for how to build/test/run** and it wasn't documented
+- **You made a mistake** because of an undocumented convention, especially after a user correction
+- **You discovered a non-obvious dependency** between files or modules
+- **You read 5+ files** to understand a pattern expressible in one sentence
+- **The user explained something** about the project that isn't written anywhere
+
+Suggest briefly: "I had to spend several tool calls figuring out [X]. Want me to add that to AGENTS.md so future sessions start with that context?"
 
 ### Subagent Observations
 
-When dispatching subagents, they may discover reusable patterns during their work. Subagents should append a `## Skill Observations` section to their output when they notice something worth surfacing. When processing subagent results, check for this section and relay the suggestion to the user.
+Subagents should append a `## Skill Observations` section to their output when they notice reusable patterns or undocumented project knowledge worth surfacing. When processing subagent results, check for this section and relay the suggestion to the user.
+
+### General Guidelines
+
+Do not suggest things that are obviously one-off. Do not interrupt urgent work to make suggestions. Use natural pause points.
 
 ## Mermaid in Markdown
 

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-03-05
+
+### Changed
+- **Replace encyclopedia with AGENTS.md project knowledge** - The encyclopedia concept (`~/.local/spellbook/docs/<project>/encyclopedia.md`) is replaced by standard `AGENTS.md` files within project repositories. AGENTS.md is version-controlled, benefits all contributors, and uses the standard Claude Code convention. Session start now checks for AGENTS.md instead of encyclopedia.
+- **Expand opportunity awareness** - Agents now also watch for project knowledge candidates (undocumented conventions, build commands, gotchas) and suggest adding them to AGENTS.md.
+- **Update spellbook AGENTS.md** - Added quick-start commands, key conventions, pre-commit hook guidance, and architecture notes for AI assistants working on the spellbook repo itself.
+
+### Deprecated
+- **project-encyclopedia skill** - Use AGENTS.md files instead. Will be removed in a future version.
+- **encyclopedia-build command** - Use AGENTS.md files instead. Will be removed in a future version.
+- **encyclopedia-validate command** - Use AGENTS.md files instead. Will be removed in a future version.
+
 ## [0.22.0] - 2026-03-05
 
 ### Added

README.md

@@ -210,7 +210,7 @@ Reusable workflows for structured development:
 | **Feature Dev** | [implementing-features], [reviewing-design-docs], [reviewing-impl-plans], [reviewing-prs], [devils-advocate], [merging-worktrees], [resolving-merge-conflicts], [creating-issues-and-pull-requests] |
 | **Autonomous Dev** | [autonomous-roundtable], [gathering-requirements], [dehallucination], [reflexion], [analyzing-domains], [assembling-context], [designing-workflows], [deep-research], [fractal-thinking] |
 | **Specialized** | [async-await-patterns], [using-lsp-tools], [managing-artifacts], [security-auditing], [generating-diagrams] |
-| **Meta** | [using-skills]†, [writing-skills]†, [writing-commands], [instruction-engineering], [sharpening-prompts], [optimizing-instructions], [dispatching-parallel-agents]†, [smart-reading], [project-encyclopedia], [analyzing-skill-usage], [documenting-tools] |
+| **Meta** | [using-skills]†, [writing-skills]†, [writing-commands], [instruction-engineering], [sharpening-prompts], [optimizing-instructions], [dispatching-parallel-agents]†, [smart-reading], [project-encyclopedia] *(deprecated)*, [analyzing-skill-usage], [documenting-tools] |
 | **Session** | [fun-mode], [tarot-mode], [emotional-stakes] |
 
 *† Derived from [superpowers](https://github.com/obra/superpowers)*
@@ -339,8 +339,8 @@ Reusable workflows for structured development:
 | [/request-review-plan] | Review planning and scope analysis |
 | [/request-review-execute] | Execute review with checklists |
 | [/request-review-artifacts] | Generate review artifacts and reports |
-| [/encyclopedia-build] | Research, build, and write encyclopedia |
-| [/encyclopedia-validate] | Validate encyclopedia accuracy |
+| [/encyclopedia-build] | *(deprecated)* Research, build, and write encyclopedia |
+| [/encyclopedia-validate] | *(deprecated)* Validate encyclopedia accuracy |
 | [/merge-worktree-execute] | Execute worktree merge sequence |
 | [/merge-worktree-resolve] | Resolve merge conflicts |
 | [/merge-worktree-verify] | Verify merge and cleanup |

commands/encyclopedia-build.md

@@ -1,7 +1,9 @@
 ---
-description: "Build encyclopedia content: glossary, architecture, decisions, and entry points (Phases 2-5)"
+description: "[DEPRECATED] Build encyclopedia content: glossary, architecture, decisions, and entry points (Phases 2-5)"
 ---
 
+> **DEPRECATED (v0.21.0):** This command is deprecated. Project knowledge now belongs in `AGENTS.md` files within the project repository. See the "Project Knowledge (AGENTS.md)" section in AGENTS.spellbook.md. This command will be removed in a future version.
+
 <ROLE>
 Encyclopedia Architect. Your reputation depends on producing content that is accurate, concise, and durable. Over-detailed encyclopedias become stale and ignored. Vague ones mislead. Your output will be the first document a new contributor reads.
 </ROLE>

commands/encyclopedia-validate.md

@@ -1,7 +1,9 @@
 ---
-description: "Assemble and validate encyclopedia, write to output path (Phase 6)"
+description: "[DEPRECATED] Assemble and validate encyclopedia, write to output path (Phase 6)"
 ---
 
+> **DEPRECATED (v0.21.0):** This command is deprecated. Project knowledge now belongs in `AGENTS.md` files within the project repository. See the "Project Knowledge (AGENTS.md)" section in AGENTS.spellbook.md. This command will be removed in a future version.
+
 <ROLE>
 Encyclopedia Curator. Your reputation depends on producing a clean, durable reference that stays accurate without constant maintenance.
 </ROLE>

docs/commands/encyclopedia-build.md

@@ -65,6 +65,8 @@ flowchart TD
 ## Command Content
 
 ``````````markdown
+> **DEPRECATED (v0.21.0):** This command is deprecated. Project knowledge now belongs in `AGENTS.md` files within the project repository. See the "Project Knowledge (AGENTS.md)" section in AGENTS.spellbook.md. This command will be removed in a future version.
+
 <ROLE>
 Encyclopedia Architect. Your reputation depends on producing content that is accurate, concise, and durable. Over-detailed encyclopedias become stale and ignored. Vague ones mislead. Your output will be the first document a new contributor reads.
 </ROLE>

docs/commands/encyclopedia-validate.md

@@ -65,6 +65,8 @@ flowchart TD
 ## Command Content
 
 ``````````markdown
+> **DEPRECATED (v0.21.0):** This command is deprecated. Project knowledge now belongs in `AGENTS.md` files within the project repository. See the "Project Knowledge (AGENTS.md)" section in AGENTS.spellbook.md. This command will be removed in a future version.
+
 <ROLE>
 Encyclopedia Curator. Your reputation depends on producing a clean, durable reference that stays accurate without constant maintenance.
 </ROLE>

docs/commands/index.md

@@ -33,8 +33,8 @@ Commands are slash commands that can be invoked with `/<command-name>` in Claude
 | [/deep-research-plan](deep-research-plan.md) | Phase 1 of deep-research: Thread decomposition, source strategy, and convergence... | spellbook |
 | [/design-assessment](design-assessment.md) | Generate assessment frameworks (dimensions, severity levels, verdicts, finding s... | spellbook |
 | [/distill-session](distill-session.md) | Distill oversized session: extract context, workflow, pending work into resumabl... | spellbook |
-| [/encyclopedia-build](encyclopedia-build.md) | Build encyclopedia content: glossary, architecture, decisions, and entry points ... | spellbook |
-| [/encyclopedia-validate](encyclopedia-validate.md) | Assemble and validate encyclopedia, write to output path (Phase 6) | spellbook |
+| [/encyclopedia-build](encyclopedia-build.md) | [DEPRECATED] Build encyclopedia content: glossary, architecture, decisions, and ... | spellbook |
+| [/encyclopedia-validate](encyclopedia-validate.md) | [DEPRECATED] Assemble and validate encyclopedia, write to output path (Phase 6) | spellbook |
 | [/execute-plan](execute-plan.md) | Execute implementation plans with structured review checkpoints. Use when you ha... | [superpowers](https://github.com/obra/superpowers) |
 | [/execute-work-packet](execute-work-packet.md) | Execute a single work packet: verify dependencies, run TDD task loop through thr... | spellbook |
 | [/execute-work-packets-seq](execute-work-packets-seq.md) | Execute all work packets in dependency order, one at a time, with context compac... | spellbook |