@booklib/core 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-04-01
+
+### Breaking
+- **Repo renamed** from `booklib-ai/booklib` to `booklib-ai/booklib`
+- **npm package renamed** from `@booklib/skills` to `booklib` — install with `npm install -g booklib`
+- **Config file generation** completely rewritten — generates 30-60 line files instead of 3,000-10,000 line content dumps. Old config files should be regenerated with `booklib init --reset`
+- **`booklib fetch` and `booklib add` deprecated** — use `booklib install <name>` instead
+
+### Added
+- **Hybrid search pipeline (Spec 2)** — BM25 + vector search + Reciprocal Rank Fusion + cross-encoder reranking. 40-60% precision improvement over vector-only
+- **SRAG metadata prefix embeddings** — each chunk's vector encodes domain context (`[skill:X] [type:Y] [tags:Z]`), 30% QA improvement (arxiv:2603.26670)
+- **Knowledge graph (Spec 3)** — `booklib capture` creates knowledge nodes with typed edges, `--graph` flag augments search with one-hop graph traversal
+- **MCP integration for 10 tools** — auto-configures MCP server for Claude Code, Cursor, Copilot (VS Code), Gemini CLI, Codex, Windsurf, Roo Code, Goose, Zed, Continue
+- **Trigger-oriented MCP tool descriptions** — each tool description says WHEN to use it, not just what it does
+- **Instinct block** — 5-10 lines of behavioral triggers in config files tell agents when to use BookLib tools
+- **5 activity-based profiles** — software-development, writing-content, research-analysis, design, general
+- **Config assembler** — profile template + instinct block + skill table + references = clean config file
+- **Copilot detection** via VS Code extensions directory (`~/.vscode/extensions/github.copilot*`)
+- **`booklib install <name>`** — unified install command with three-tier lookup (installed → bundled → cached)
+- **`booklib doctor` diagnostic engine** — 6 checks (slot overload, oversized configs, missing index, stale skills, orphaned skills, missing config files) + `--cure` flag
+- **`booklib init --reset`** — force re-run setup wizard
+- **Rank-based display scores** — meaningful percentages instead of all-100% reranker saturation
+- **Recommendation explanations** — wizard shows WHY each skill was recommended with matching chunk snippets
+- **Safe config file handling** — `onFileConflict` callback before modifying existing files
+- **Official docs references** — generated config files link to each tool's official documentation
+- **Index progress callback** — `onProgress` in `indexDirectory()` for real-time feedback
+- **Shared readline session** — `createSession()` eliminates race conditions in sequential prompts
+- **@clack/prompts wizard UI** — colors, spinners, arrow-key selection, animated progress
+- **`benchmark/RESEARCH.md`** — maps retrieval quality metrics to arxiv 2602.12430 claims
+
+### Changed
+- **13 supported AI tools** (up from 8): added Roo Code, OpenHands, Junie, Goose, OpenCode, Letta
+- **24 bundled skills** (up from 22)
+- **62 tests** across all modules
+- **Wizard flow reordered** — index build before recommendations (uses search engine for recommendations instead of shallow description embeddings)
+
+## [1.12.0] - 2026-03-30
+
+### Added
+- **`booklib init` Phase 2: MCP server setup** — after writing standards docs, `booklib init` now offers an interactive prompt to wire up the BookLib MCP server for Claude Code, Cursor, Gemini CLI, Codex, Zed, and Continue.dev
+- **MCP config generation** — writes project-level config files: `.claude/settings.json`, `.cursor/mcp.json`, `.gemini/settings.json`, `.codex/config.toml`, `.zed/settings.json`, `.continue/mcpServers/booklib.yaml`; merges safely into existing configs without overwriting other MCP servers
+- **`booklib-mcp` named bin** — `booklib-mcp` is now a first-class binary entry in `package.json`; MCP configs reference it directly by name
+- **`--mcp-tool=X` flag** — skip the interactive prompt and specify tools directly (e.g. `booklib init --mcp-tool=claude,cursor`); selection persisted to `booklib.config.json`
+- **Knowledge Graph** — unified node+edge model where any piece of knowledge (research, notes, decisions) and any part of your project (components, features) is a node; relationships are typed edges stored in `.booklib/knowledge/graph.jsonl`
+- **`booklib note "<title>"`** — create a note node from `$EDITOR`, stdin pipe, or interactive input
+- **`booklib dictate`** — type or dictate a note; AI structures the text, fixes grammar, extracts title and tags; `--raw` flag saves verbatim with no AI processing
+- **`booklib save-chat`** — save the current agent conversation as a knowledge node; `--summarize` flag uses AI to extract key decisions and findings into a clean note with transcript attached
+- **`booklib research "<topic>"`** — create a research stub node pre-populated with a template
+- **`booklib component add <name> "<glob>"`** — define a project component with glob path patterns; component nodes replace `areas.yaml` (additive migration)
+- **`booklib link <node1> <node2> --type <edge-type>`** — add a typed edge between any two nodes; edge types: `implements` · `contradicts` · `extends` · `applies-to` · `see-also` · `inspired-by` · `supersedes` · `depends-on`
+- **`booklib nodes list`** / **`booklib nodes show <id>`** — list and inspect knowledge nodes
+- **`booklib context --file <path>`** — graph-aware context injection: finds the file's owning component, traverses edges via BFS (up to 2 hops), combines with semantic search, injects book wisdom + personal knowledge together
+- **PostToolUse hook** (`hooks/posttooluse-capture.mjs`) — fires after `WebFetch`/`WebSearch` tool calls and suggests saving captured knowledge as a node
+- **`lib/engine/graph.js`** — node CRUD, edge append, BFS traversal with cycle prevention
+- **`lib/engine/capture.js`** — node creation helpers: stdin, `$EDITOR`, interactive readline, Anthropic API structuring
+- **`lib/engine/graph-injector.js`** — injection pipeline: semantic search + BFS graph traversal + dedup + ranking
+- **Knowledge nodes indexed** — `booklib index` now indexes `.booklib/knowledge/nodes/` alongside skills; `booklib search` returns both with `📝` prefix for knowledge hits
+- **`minimatch`** added as a runtime dependency for component path-glob matching
+
+## [1.11.0] - 2026-03-30
+
+### Added
+- **Non-code domain support** — `booklib context` now works for product, writing, strategy, design, and legal domains using the same semantic extraction as code skills
+- **6 new community skills in registry** — `article-writing`, `product-lens`, `market-research`, `investor-materials`, `brand-guidelines`, `web-design-guidelines` with accurate source URLs
+- **`booklib scan --docs` mode** — prose quality checks (passive voice, unresolved placeholders, hedge words, user story completeness) for `.md`/`.txt` files
+- **`writing-plans/audit.json`** — bundled static rules for markdown document scanning
+- **New profiles** — `product`, `writer`, `strategist`, `designer`, `legal` roles added to `booklib profile` and `booklib swarm-config`
+- **`skill-router` extended** — now routes non-code tasks to PM, legal, writing, strategy, brand, and web design skills; added 5 new routing rules and 3 conflict resolution entries
+- **Prose sentence extraction** — `extractItems()` now splits long prose blocks by sentence boundary so non-code skill content surfaces as individual, rankable principles
+
+### Fixed
+- **Self-conflict bug** — `booklib context` no longer shows `skill vs skill` conflict warnings when the same skill name appears in both bundled and community index; deduplication by skill name now runs before conflict resolution
+- **Community skills indexed** — `booklib index` now indexes `~/.booklib/skills/` after rebuilding the bundled index, so community skills appear in `booklib search` and `booklib context` results
+- **YAML parse errors** — `booklib index` now skips malformed skill files with a warning instead of aborting the entire index rebuild
+
+## [1.10.0] - 2026-03-28
+
+### Added
+- **Rules system** — Standalone rule files for Cursor and other AI editors
+- **Standalone `--hooks` flag** — Install hooks independently of skills
+- **Landing page update** — Improved GitHub Pages documentation
+
+### Changed
+- Multi-language README support (中文, 日本語, 한국어, Português)
+- README overhaul for v1.10.0 with improved clarity and examples
+
+### Fixed
+- Book covers now load via Google Books JSON API (eliminates false-positive placeholders)
+- Cover image detection improved to skip 1×1 pixel placeholders
+
+## [1.9.0] - 2026-02-27
+
+### Added
+- **Agents system** — `@python-reviewer`, `@ts-reviewer`, `@architecture-reviewer`, and more
+- **Cursor support** — Install skills and rules to `.cursor/rules/` for Cursor IDE
+- **Installation profiles** — Quick-start profiles for common stacks (python, ts, jvm, rust, architecture, data, ui, lean, core)
+- **Slash commands** — `/effective-python`, `/design-patterns`, etc. for explicit skill invocation
+- **Hook system** — Auto-suggestion when asking for code reviews
+- **GitHub Pages site** — Interactive skill browser with book covers
+
+### Changed
+- AGENTS.md rewritten with profiles and cross-platform setup
+- README structure reorganized around profiles and tiers
+
+### Removed
+- Hardcoded skill count (now dynamic)
+
+## [1.8.0] - 2026-02-26
+
+### Added
+- **Installation profiles** — Platform-specific quick-install (e.g., `--profile=ts`, `--profile=python`)
+- **Benchmark suite** — Performance testing infrastructure
+- **Skill quality checker** — `npx booklib check <skill-name>`
+
+### Changed
+- Project logo added and displayed in README
+- Community health files added
+- NPM ignore list improved
+
+## [1.7.0] - 2026-02-24
+
+### Added
+- **Agents system** — `@booklib-reviewer`, `@python-reviewer`, `@ts-reviewer` for autonomous code review
+- **Skill-router meta-skill** — Auto-routing to best skill based on context
+- **GitHub Actions workflows** — Automated testing and release pipeline
+- **Skill evaluation framework** — `evals.json` test cases for quality assurance
+
+### Changed
+- All skills upgraded to **Platinum** quality (13/13 checks)
+- Scripts added to all skills for practical examples
+- Skill structure standardized with examples/ and references/ directories
+
+## [1.6.0] - 2026-02-20
+
+### Added
+- **Slash commands system** — Explicit skill invocation without relying on auto-trigger
+- **Skill verification** — `npx booklib eval <skill-name>` for running test cases
+
+## [1.5.0] - 2026-02-18
+
+### Added
+- `spring-boot-in-action` skill — Enterprise Java best practices
+- Spring Boot patterns and architecture guidance
+
+## [1.4.0] - 2026-02-16
+
+### Added
+- `effective-typescript` skill — Dan Vanderkam's TypeScript best practices
+- `programming-with-rust` skill — Donis Marshall's practical Rust patterns
+- `rust-in-action` skill — Tim McNamara's systems programming with Rust
+
+### Changed
+- Upgraded to Platinum quality across new skills
+
+## [1.3.0] - 2026-02-15
+
+### Added
+- **Skill-router** — Meta-skill that automatically selects the best skill for your task
+- Improved skill discovery mechanism
+- Better error messages for missing skills
+
+## [1.2.0] - 2026-02-14
+
+### Added
+- GitHub Pages site with skill browser
+- Animated demo GIF
+- Improved README with better visual hierarchy
+
+## [1.1.0] - 2026-02-13
+
+### Added
+- NPM version, downloads, and license badges
+- Better documentation structure
+- CLAUDE.md with project overview
+
+## [1.0.0] - 2026-02-10
+
+### Added
+- **Initial release** with 18 core skills:
+  - `animation-at-work`
+  - `clean-code-reviewer`
+  - `data-intensive-patterns`
+  - `data-pipelines`
+  - `design-patterns`
+  - `domain-driven-design`
+  - `effective-java`
+  - `effective-kotlin`
+  - `effective-python`
+  - `kotlin-in-action`
+  - `lean-startup`
+  - `microservices-patterns`
+  - `refactoring-ui`
+  - `storytelling-with-data`
+  - `system-design-interview`
+  - `using-asyncio-python`
+  - `web-scraping-python`
+  - Plus 4 additional skills
+
+- **Installation system** — NPM-based skill installation
+- **Skill structure** — Standardized SKILL.md format with YAML frontmatter
+- **Auto-triggering** — Skills load automatically based on file context
+- **MIT License** — Open-source and permissive
+- **Security policy** — Responsible disclosure guidelines
+- **Code of Conduct** — Community standards
+
+---
+
+## Release Notes
+
+For detailed release notes, see [GitHub Releases](https://github.com/booklib-ai/booklib/releases).
+
+## Versioning Policy
+
+This project follows **Semantic Versioning**:
+- **MAJOR** — Breaking changes to skill APIs or skill removal
+- **MINOR** — New skills, new features, non-breaking improvements
+- **PATCH** — Bug fixes, documentation improvements, skill enhancements
+
+New skills are added regularly and will increment the MINOR version.

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# BookLib: Claude Operational Guidelines
+
+You are operating within the BookLib repository, a curated library of software architecture and best-practice distillations. Your goal is to apply these high-level principles to the user's codebase using the built-in search engine.
+
+<corrections>
+When the user corrects your approach ("don't do that", "always use X", "stop doing Y"), run immediately:
+`node bin/booklib.js correction add "brief rule"`
+This records the correction. Repeated corrections are promoted automatically into your always-on context.
+</corrections>
+
+<workflow>
+When a user asks you to write, review, or refactor code, you MUST follow this sequence:
+
+1. **Semantic Search**: Use your terminal to query the BookLib index for relevant architectural wisdom:
+   `node bin/booklib.js search "<conceptual query>"`
+   *Example: `node bin/booklib.js search "handling nulls in Kotlin"`*
+
+2. **Retrieve Skill**: If the search points to a specific file (e.g., `skills/effective-kotlin/SKILL.md`), use your file-reading tool to read it for detailed principles.
+
+3. **Apply Principles**: Strictly follow the `<core_principles>` and avoid the `<anti_patterns>` found in the search results and skill files.
+
+4. **Cite Your Source**: When outputting code or reviews, you MUST append a brief citation indicating which book or skill guided your decision. 
+   *Example: "> Refactored per Effective Kotlin: Item 1 (Limit Mutability)"*
+
+<handoff_protocol>
+If you are finishing a planning session and the user wants to switch to a coding agent (or vice-versa), run:
+`node bin/booklib.js save-state --goal "<final goal>" --next "<immediate next task>"`
+This creates a snapshot that the next agent can resume.
+</handoff_protocol>
+</workflow>
+
+<navigation_map>
+- **Kotlin**: `skills/effective-kotlin/`
+- **Java**: `skills/effective-java/`
+- **TypeScript**: `skills/effective-typescript/`
+- **Python**: `skills/effective-python/`
+- **DDD**: `skills/domain-driven-design/`
+- **Clean Code**: `skills/clean-code-reviewer/`
+- **Architecture**: `skills/data-intensive-patterns/`, `skills/system-design-interview/`
+</navigation_map>
+
+<universal_indexer>
+Before using the search tool for the first time, ensure the index is built:
+`node bin/booklib.js index`
+</universal_indexer>
+
+See @.claude/rules/booklib-tools.md for analysis tools (scan, audit, session handoff).
+
+
+<!-- booklib-standards-start -->
+## Stack
+javascript (Node.js >= 18, ES modules)
+
+## Commands
+- Install: `npm install`
+- Build index: `node bin/booklib.js index`
+- Scan codebase: `node bin/booklib.js scan`
+- Audit file: `node bin/booklib.js audit <skill-name> <file-path>`
+
+## BookLib
+BookLib MCP tools are available for code quality guidance.
+- Before answering best-practices questions → search_skills
+- When reviewing or writing code → search_skills for relevant principles
+- When user says "remember/note/capture this" → create_note
+- For deep file review against a skill → audit_content
+- When code quality issues accumulate → suggest running `booklib doctor`
+
+## Active Skills
+| Skill | Focus | Tags |
+|-------|-------|------|
+| clean-code-reviewer | Reviews code against Robert C. Martin's Clean Code principles | all-languages, quality, naming, refactoring |
+| skill-router | Select the 1-2 most relevant booklib for a given file or task | meta, routing, agent-skills |
+
+
+## References
+
+- [How to customize this file](https://docs.anthropic.com/en/docs/claude-code/claude-md)
+- [BookLib documentation](https://booklib-ai.github.io/booklib/)
+- [BookLib skills catalog](https://github.com/booklib-ai/booklib)
+
+<!-- booklib-standards-end -->

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,304 @@
+# Contributing
+
+Thanks for wanting to add a skill. A skill packages expert knowledge from a book into reusable instructions that AI agents can apply to real tasks.
+
+## What makes a good skill?
+
+A skill is worth adding when the source book:
+- Contains specific, actionable advice (not just general philosophy)
+- Covers a topic useful to software engineers or designers
+- Has enough depth to fill a meaningful SKILL.md (300+ lines)
+
+## Adding a new skill
+
+### 1. Create the folder
+
+```
+skills/skill-name/
+├── SKILL.md          # Required
+├── examples/
+│   ├── before.md     # Code or artifact before applying the skill
+│   └── after.md      # The improved version
+└── evals/
+    └── evals.json    # Test cases
+```
+
+The folder name must be lowercase, hyphen-separated, and match the `name` field in `SKILL.md` exactly.
+
+### 2. Write SKILL.md
+
+```markdown
+---
+name: skill-name
+description: >
+  What this skill does and when to trigger it. Include specific
+  keywords agents should look for. Max 1024 characters.
+---
+
+# Skill Title
+
+You are an expert in [domain] grounded in [Book Title] by [Author].
+
+## When to use this skill
+
+[Describe trigger conditions — what user requests or code patterns activate this skill]
+
+## Core principles
+
+[The key ideas from the book, organized for an AI agent to apply]
+
+## How to apply
+
+[Step-by-step process the agent follows]
+
+## Examples
+
+[At least one concrete before/after showing the skill in action]
+```
+
+**Requirements:**
+- `name`: lowercase letters and hyphens only, matches folder name
+- `description`: 1–1024 characters, describes what it does AND when to use it
+- Body: clear instructions an AI agent can follow immediately
+
+**Keep SKILL.md under 500 lines.** Move deep reference material to `references/` and link to it.
+
+### 3. Add before/after examples
+
+`examples/before.md` — code or artifact that violates the book's principles.
+`examples/after.md` — the same thing improved by applying the skill.
+
+These power the `npx booklib demo <name>` command.
+
+### 4. Add evals
+
+`evals/evals.json` — array of test cases verifying the skill works:
+
+```json
+{
+  "evals": [
+    {
+      "id": "eval-01-short-description",
+      "prompt": "The prompt to send to the agent (include code or a scenario)",
+      "expectations": [
+        "The agent should do X",
+        "The agent should flag Y",
+        "The agent should NOT do Z"
+      ]
+    }
+  ]
+}
+```
+
+Aim for 3–5 evals per skill covering:
+1. A clear violation of the book's principles
+2. A subtle or intermediate case
+3. Already-good code (the agent should recognize it and not manufacture issues)
+
+### 5. Run evals and commit results
+
+```bash
+ANTHROPIC_API_KEY=your-key npx booklib eval <name>
+```
+
+This runs each eval **with and without** the skill and writes `evals/results.json`. Commit this file — it is how CI and readers verify the skill actually works.
+
+**Quality thresholds** (calibrated to `claude-haiku-4-5` as judge):
+
+| Metric | Minimum | Good | Excellent |
+|--------|---------|------|-----------|
+| Pass rate (with skill) | ≥ 80% | ≥ 85% | ≥ 90% |
+| Delta over baseline | ≥ 20pp | ≥ 25pp | ≥ 30pp |
+| Baseline (without skill) | any | < 70% | < 60% |
+
+A high delta matters as much as a high pass rate — it proves the skill is doing real work, not just measuring what Claude already knows. A skill with 90% pass rate and 5pp delta is less valuable than one with 85% and 30pp delta.
+
+The 80% threshold is calibrated to the judge model's own noise floor. Consistently hitting 80%+ with haiku as judge means the skill reliably catches what it claims to catch.
+
+### 6. Submit a PR
+
+```bash
+git checkout -b skill/book-name
+# add your skill folder
+git add skills/skill-name/
+git commit -m "feat: add skill-name skill"
+gh pr create --title "feat: add skill-name" --body "..."
+```
+
+PR checklist:
+- [ ] Folder name matches `name` in SKILL.md
+- [ ] `description` is under 1024 characters
+- [ ] SKILL.md is under 500 lines
+- [ ] `examples/before.md` and `examples/after.md` exist
+- [ ] `evals/evals.json` has at least 3 test cases
+- [ ] `evals/results.json` committed (run `npx booklib eval <name>`)
+- [ ] Pass rate ≥ 80% and delta ≥ 20pp in results.json
+- [ ] README.md skills table updated
+
+## Adding an Agent
+
+An agent is a multi-step autonomous reviewer that orchestrates one or more skills. If you are packaging a single book's principles, write a skill. If you need to combine multiple skills, detect code patterns to route between them, or run a full review pipeline across a whole codebase, write an agent.
+
+| Write a skill when... | Write an agent when... |
+|-----------------------|------------------------|
+| You are packaging one book's principles | You need two or more skills applied together |
+| The logic is a single lens on code | You need routing logic (detect language → pick skill) |
+| Instructions fit in one SKILL.md | You need a multi-step process (diff → detect → review → output) |
+
+### 1. Create the file
+
+Agents live in a flat directory at the repo root:
+
+```
+agents/<agent-name>.md
+```
+
+The filename must be lowercase and hyphen-separated. It does not need a matching folder — unlike skills, agents have no `examples/` or `evals/` subdirectories.
+
+### 2. Write the frontmatter
+
+Every agent file starts with YAML frontmatter:
+
+```markdown
+---
+name: agent-name
+description: >
+  When to invoke this agent and what it does. Include language names,
+  domain terms, and trigger conditions. Claude Code uses this field
+  for auto-invocation, so make it specific. Max 1024 characters.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+```
+
+**Required fields:**
+
+- `name` — lowercase, hyphens only, matches filename exactly (without `.md`)
+- `description` — used by Claude Code to decide when to invoke the agent automatically; include what it does, which skills it applies, and when to use it over alternatives
+- `tools` — list of Claude Code tools the agent may call; `["Read", "Grep", "Glob", "Bash"]` covers most reviewers
+- `model` — controls cost and capability (see model selection below)
+
+### 3. Write the body
+
+A good agent body has five parts:
+
+**Opening sentence** — one sentence identifying what the agent is, which books it draws from, and its scope.
+
+**Process** — numbered steps the agent follows every time it runs:
+
+1. **Get the scope** — how to determine what to review (e.g., `git diff HEAD`, specific files passed by the user, or a directory scan)
+2. **Detect signals** — bash commands or grep patterns that route to the right skill(s)
+3. **Apply skill(s)** — one `### Step N` section per skill, each with `HIGH`/`MEDIUM`/`LOW` focus areas
+4. **Output** — the standard output format
+
+**Detection table** — a Markdown table mapping code signals to skills:
+
+```markdown
+| Code contains | Apply |
+|---------------|-------|
+| `async def`, `await`, `asyncio` | `using-asyncio-python` |
+| `BeautifulSoup`, `scrapy` | `web-scraping-python` |
+| General Python | `effective-python` |
+```
+
+**Per-skill focus areas** — for each skill applied, list what to look for under `HIGH`, `MEDIUM`, and `LOW` headings. Pull these from the skills' own SKILL.md files, but trim to what is relevant for this agent's scope.
+
+**Output format** — end the body with the standard output block:
+
+```markdown
+### Step N — Output format
+
+​```
+**Skills applied:** `skill-name(s)`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+​```
+```
+
+### 4. Choose the right model
+
+| Model | When to use |
+|-------|-------------|
+| `haiku` | Fast, cheap; use for simple or narrow tasks with a single skill and little routing logic |
+| `sonnet` | Default for most reviewers; handles multi-skill routing and structured output well |
+| `opus` | Only for architecture or reasoning-heavy agents where depth matters more than cost (e.g., `architecture-reviewer`) |
+
+When in doubt, use `sonnet`.
+
+### 5. Follow naming conventions
+
+| Pattern | Examples | Use for |
+|---------|----------|---------|
+| `<language>-reviewer` | `python-reviewer`, `jvm-reviewer`, `ts-reviewer` | Language-cluster agents combining all relevant skills for a language |
+| `<domain>-reviewer` | `architecture-reviewer`, `data-reviewer`, `ui-reviewer` | Domain-cluster agents cutting across languages |
+| Descriptive name | `booklib-reviewer` | Meta or router agents that don't fit a single language or domain |
+
+### 6. Installation
+
+Agents install to `.claude/agents/` alongside skills:
+
+```bash
+# Install one agent
+npx skills add booklib-ai/booklib --agent=python-reviewer
+
+# Install everything (skills + agents)
+npx skills add booklib-ai/booklib --all
+```
+
+Once installed, Claude Code reads the agent's `description` field and auto-invokes it when a matching request arrives — no slash command needed.
+
+### 7. No eval system (yet)
+
+There is no `evals/` system for agents. Instead:
+
+- Make the `description` accurate — it controls when the agent auto-invokes
+- Check that every `### Step N` section has a clear, testable action
+- Test manually: install the agent locally and run it against a real codebase
+
+### 8. Submit a PR
+
+```bash
+git checkout -b agent/agent-name
+git add agents/agent-name.md
+git commit -m "feat: add agent-name agent"
+gh pr create --title "feat: add agent-name agent" --body "..."
+```
+
+PR checklist:
+- [ ] Filename matches `name` in frontmatter
+- [ ] `description` is under 1024 characters and describes when to invoke it
+- [ ] `model` is appropriate for the agent's complexity
+- [ ] Process steps are numbered and each has a clear action
+- [ ] Detection table covers the signals the agent handles
+- [ ] Output format section matches the standard `HIGH`/`MEDIUM`/`LOW` format
+
+## Requesting a skill
+
+Open an issue titled **"Skill Request: [Book Name]"** and describe why the book would make a good skill. Community members can then pick it up.
+
+## AI disclosure
+
+If you used an AI tool to help write or review your contribution, disclose it in your PR description. This is required — not optional.
+
+**Acceptable examples:**
+- "Written primarily with Claude Code; I reviewed and tested each section manually."
+- "I used Copilot for boilerplate; the examples and evals are hand-written."
+- "No AI tools used."
+
+**Not acceptable:** submitting AI-generated content without reviewing it yourself. Skills are grounded in specific books — the AI can hallucinate citations, misattribute principles, or invent heuristic codes. You are responsible for accuracy.
+
+Trivial fixes (typos, formatting) don't need a disclosure.
+
+## Questions
+
+Use [GitHub Discussions](../../discussions) for questions, ideas, and feedback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.