Archived: This was a learning project. Active development has moved to bcbeidel/wos.
Dewey is a Claude Code plugin that helps you build, curate, and maintain structured knowledge bases. It implements a specification for role-specific knowledge bases that serve both AI agents and humans.
AI agents produce better outputs when they have access to curated, relevant knowledge. But knowledge bases serve two consumers: the agent (who needs structured, token-efficient context) and the human (who needs readable, navigable content). Dewey defines a standard for what a well-formed knowledge base looks like and provides skills to create and maintain one.
Dewey currently runs as a Claude Code plugin. The knowledge base output format is designed to be provider-agnostic -- cross-provider support (Codex, Gemini CLI, Cursor, etc.) is a future goal.
Requires Claude Code v1.0.33 or later.
Add the marketplace and install:
# Add the Dewey marketplace
/plugin marketplace add bcbeidel/dewey
# Install the plugin
/plugin install dewey@bcbeidel-deweyOr browse and install interactively:
# Open the plugin manager, then go to the Discover tab
/pluginChoose an installation scope when prompted:
- User -- available across all your projects
- Project -- shared with collaborators via
.claude/settings.json - Local -- just you, just this repo
After installing, restart Claude Code. Dewey's skills will be available as /dewey:curate, /dewey:health, and /dewey:report-issue.
| Skill | Purpose |
|---|---|
/dewey:curate |
Single entry point for all knowledge-base content operations: discover domains, scaffold structure, add/update topics, ingest URLs, manage proposals and curation plan |
/dewey:health |
Validate quality, check freshness, analyze coverage gaps, generate reports |
/dewey:report-issue |
Submit bug reports, feature ideas, or feedback to the Dewey GitHub repo |
The curate skill uses free-text intake -- describe what you want and Claude routes to the right workflow. No subcommands needed.
Workflows:
- discover -- Guided conversation to identify what knowledge domains matter for a role, then scaffold the structure
- setup -- Bootstrap a new knowledge base with directory structure, AGENTS.md, and templates
- add -- Research a topic, draft working-knowledge and reference files, update all indexes (also supports updating existing topics)
- propose -- Submit a topic proposal for review before committing
- promote -- Move a validated proposal into a domain area
- ingest -- Ingest an external URL, evaluate source quality, then propose new content or update existing topics
- plan -- Create or update a curation plan that tracks coverage goals
# Just tell it what you want:
/dewey:curate I want to start a knowledge base for platform engineering
/dewey:curate add a topic about dependency injection in python-foundations
/dewey:curate ingest https://example.com/article-about-observability
/dewey:curate what's in my curation plan?
Three-tier health model for knowledge base validation:
Tier 1 -- Deterministic (Python): 18 validators in validators.py plus 6 cross-file validators in cross_validators.py. Checks frontmatter, section ordering, cross-references, size bounds, coverage gaps, freshness, source URLs, readability (Flesch-Kincaid), duplicate content, naming conventions, and more. Auto-fix available for common issues.
Tier 2 -- LLM-Assisted (Claude): Pre-screener with 9 triggers in tier2_triggers.py flags files needing deeper review. Claude evaluates: source drift, depth accuracy, why-quality, in-practice concreteness, source primacy, citation quality, source authority, provenance completeness, recommendation coverage.
Tier 3 -- Human Judgment: Surfaces decisions requiring human input: relevance questions, scope decisions, pending proposals, conflict resolution.
/dewey:health check my knowledge base
/dewey:health what's gone stale?
/dewey:health run a full audit
A Dewey-conformant knowledge base looks like:
project-root/
AGENTS.md # Role persona + topic manifest
.claude/rules/dewey-kb.md # KB instructions + domain area index
docs/
<domain-area>/
overview.md # Area orientation (depth: overview)
<topic>.md # Working knowledge (depth: working)
<topic>.ref.md # Expert reference (depth: reference)
_proposals/ # Staged additions pending review
.dewey/
health/ # Quality scores and tier 2 reports
history/ # Health check snapshots over time
utilization/ # Reference tracking log
Every knowledge file carries YAML frontmatter: sources, last_validated, relevance, and depth.
Twelve principles grounded in agent context research (Anthropic, OpenAI) and cognitive science (Sweller, Vygotsky, Paivio, Bjork, Pirolli, Kalyuga, Dunlosky).
- Source Primacy -- The knowledge base is a curated guide, not a replacement for primary sources. Every entry points to one. When an agent or human needs to go deeper, the path is always clear.
- Dual Audience -- Every entry serves the agent (structured, token-efficient context) and the human (readable, navigable content). When these conflict, favor human readability -- agents are more adaptable readers.
- Three-Dimensional Quality -- Content quality measured across relevance, accuracy/freshness, and structural fitness simultaneously.
- Collaborative Curation -- Either the human or an agent can propose additions, but all content passes through validation. The human brings domain judgment. The agent brings systematic coverage. Neither is sufficient alone.
- Provenance & Traceability -- Every piece of knowledge carries metadata about where it came from, when it was last validated, and why it's in the knowledge base.
- Domain-Shaped Organization -- Organized around the domain's natural structure, not file types or technical categories. The taxonomy should feel intuitive to a practitioner.
- Right-Sized Scope -- Contains what's needed to be effective in the role, and no more. The curation act is as much about what you exclude as what you include.
- Empirical Feedback -- Observable signals about knowledge base health: coverage gaps, stale entries, unused content. Proxy metrics inform curation decisions.
- Progressive Disclosure -- Layered access so agents can discover what's available without loading everything. Metadata -> summaries -> full content -> deep references.
- Explain the Why -- Causal explanations produce better comprehension and retention than stating facts alone. Every entry explains not just what to do, but why.
- Concrete Before Abstract -- Lead with examples and worked scenarios, then build toward the abstraction. Concrete concepts create stronger memory traces.
- Multiple Representations -- Important concepts should exist at multiple levels of depth (overview, working knowledge, reference). Material that helps novices can hinder experts and vice versa -- label each level clearly so readers self-select.
See the design principles reference for detailed rationale and research sources.
- Python 3.9+ (stdlib only -- zero dependencies)
- Markdown with YAML frontmatter
- Claude Code skills framework
git clone https://github.com/bcbeidel/dewey.git
cd dewey
# Load the plugin from your local clone for development
claude --plugin-dir ./dewey
# Run tests
python3 -m pytest tests/ -vdewey/
.claude-plugin/plugin.json # Plugin manifest
skills/
curate/ # All knowledge-base content operations
SKILL.md
scripts/create_topic.py, propose.py, promote.py, scaffold.py, templates.py, config.py
workflows/curate-discover.md, curate-setup.md, curate-add.md, curate-propose.md,
curate-promote.md, curate-ingest.md, curate-plan.md
references/knowledge-base-spec-summary.md, source-evaluation.md
health/ # Quality validation
SKILL.md
scripts/validators.py, cross_validators.py, auto_fix.py, check_knowledge_base.py,
tier2_triggers.py, history.py, utilization.py, log_access.py,
hook_log_access.py
workflows/health-check.md, health-audit.md, health-review.md,
health-coverage.md, health-freshness.md
references/validation-rules.md, quality-dimensions.md, design-principles.md
report-issue/ # GitHub issue submission
SKILL.md
workflows/report-issue-submit.md
tests/ # Test suite (536 tests)
| Feature | Status |
|---|---|
| Knowledge base scaffolding | Complete |
| Domain discovery | Complete |
| Content lifecycle (add, propose, promote) | Complete |
| URL ingestion with source evaluation | Complete |
| Curation plan management | Complete |
| Tier 1 deterministic health checks | Complete (18 validators + 6 cross-validators) |
| Tier 2 LLM-assisted health assessments | Complete (9 triggers + audit workflow) |
| Readability and duplicate content detection | Complete |
| Auto-fix for common issues | Complete |
| Health history and baselines | Complete |
| Utilization tracking | Infrastructure complete, auto-capture pending (#3) |
| Tier 3 human decision queue | Designed, not yet tested (#2) |
| CI/CD eval pipeline | Planned (#4) |
| Cross-provider support | Planned — MCP server, Cursor, Copilot/Codex, Gemini CLI, Windsurf |
| Research: design principle validation | Planned — context effectiveness, cognitive load, information foraging, source provenance, multi-agent sharing |
- Three-tier validation model -- Deterministic checks are cheap and catch most issues. LLM-assisted checks add judgment but need a pre-screener to avoid waste. Human judgment is the hardest tier to operationalize.
- Skill consolidation -- Started with separate explore/init/curate skills, converged to one free-text intake skill (curate) that routes internally. Simpler UX, same power.
- Stdlib-only constraint -- Zero dependencies kept the project portable and easy to test, but the document type system research pushed toward Pydantic for schema validation -- a sign the project was outgrowing the constraint.
- Design principles grounded in research -- The 12 principles (cognitive science + agent context research) gave the project a backbone that guided every content decision. Worth the upfront investment.
- Agent + human dual audience -- Writing for both consumers is the core tension. Favor human readability since agents adapt more easily.
- Knowledge base as curation problem -- What you exclude matters as much as what you include. The hardest part isn't adding content, it's deciding what doesn't belong.
- Design Principles -- The twelve principles guiding knowledge base content
- Knowledge Base Spec Summary -- Structural specification reference
- CHANGELOG -- Release history