@booklib/core 2.0.0

package/llms.txt

@@ -0,0 +1,70 @@
+# BookLib Skills
+
+An open knowledge ecosystem for AI coding agents. Packages expert knowledge from canonical programming books as skills, with a discovery engine for community sources, semantic search, automatic context injection, and compatibility with Claude Code orchestrators (obra/superpowers, ruflo).
+
+## Two Layers
+
+**Bundled library**: 22 skills from canonical books, pre-indexed, ready to use.
+**Discovery ecosystem**: finds and fetches skills from GitHub repos, community registries, and npm packages (258+ discoverable).
+
+## Core Commands
+
+- `booklib context "<task>"` — cross-skill context builder: searches all skills + knowledge graph, extracts relevant passages, compiles a sharp ready-to-use system prompt
+- `booklib context "<task>" --file <path>` — also injects graph context for the file's owning component
+- `booklib context "<task>" --prompt-only` — just the compiled prompt (pipe-friendly)
+- `booklib search "<query>"` — semantic search over skill content + knowledge nodes
+- `booklib fetch <skill>` — download and index a community skill
+- `booklib setup` — fetch all trusted skills at once
+- `booklib sync` — sync fetched skills to `~/.claude/skills/` for Skill tool / orchestrator access
+- `booklib audit <skill> <file>` — systematic file review against a skill
+- `booklib scan` — wisdom heatmap across the whole project
+- `booklib profile <role>` — skills by agent role (architect, reviewer, security, tester, ...)
+- `booklib swarm-config [trigger]` — skill map for swarm agent pipelines
+- `booklib init [--orchestrator=obra|ruflo]` — scaffold context files for all AI tools
+- `booklib save-state / resume / recover-auto` — session handoff between agents
+
+## Knowledge Graph Commands
+
+- `booklib note "<title>"` — create a note node (opens $EDITOR or reads stdin)
+- `booklib dictate` — type or dictate → AI structures + saves as a note
+- `booklib dictate --raw` — type or dictate → saved verbatim, no AI processing
+- `booklib save-chat --title "<title>"` — save current conversation as a knowledge node
+- `booklib save-chat --summarize` — AI extracts key decisions + findings → clean note
+- `booklib research "<topic>"` — create a research stub node
+- `booklib component add <name> "<glob>"` — define a project component node with path patterns
+- `booklib link <node1> <node2> --type <edge-type>` — add a typed edge between nodes
+- `booklib nodes list` — list all knowledge nodes
+- `booklib nodes show <id>` — view a specific node
+
+## Bundled Skills (22)
+
+animation-at-work · clean-code-reviewer · data-intensive-patterns · data-pipelines · design-patterns · domain-driven-design · effective-java · effective-kotlin · effective-python · effective-typescript · kotlin-in-action · lean-startup · microservices-patterns · programming-with-rust · refactoring-ui · rust-in-action · skill-router · spring-boot-in-action · storytelling-with-data · system-design-interview · using-asyncio-python · web-scraping-python
+
+## Discovery Sources (booklib.config.json)
+
+- `registry` — bundled skills
+- `manifest` — JSON skill list at a URL or local path (community/registry.json ships 258 skills)
+- `github-skills-dir` — any GitHub repo with a `skills/` subdirectory (obra/superpowers, ruflo included)
+- `github-org` — all repos in a GitHub org
+- `npm-scope` — all packages in an npm scope
+
+## Orchestrator Compatibility
+
+After `booklib sync`, all fetched skills are available at `~/.claude/skills/<name>/SKILL.md`.
+Works with obra/superpowers (`/plugin install superpowers`) and ruflo (`npm install -g ruflo`).
+
+## Activation Mechanisms
+
+- **PreToolUse hook** — automatically injects relevant skill chunks when editing matching files (fine-grained)
+- **Skill tool** — full skill dump on demand, used by orchestrator subagents (coarse)
+- **Search** — semantic vector search returning the most relevant chunks
+
+## Technical
+
+- Format: Markdown with XML tags (`<core_principles>`, `<anti_patterns>`, `<framework>`)
+- Engine: local semantic RAG using `@xenova/transformers` + `vectra`
+- Knowledge Graph: nodes as `.md` files with YAML frontmatter; edges as append-only JSONL
+- Config: `booklib.config.json` (discovery sources), `.booklib/` (local state, gitignored)
+- Runtime deps: `@xenova/transformers`, `vectra`, `gray-matter`, `@modelcontextprotocol/sdk`, `minimatch`
+
+For full skill catalog, see [llms-full.txt](llms-full.txt).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@booklib/core",
+  "version": "2.0.0",
+  "description": "Knowledge bookkeeping for AI agents — expert skills, hybrid search, knowledge graph, MCP tools",
+  "bin": {
+    "skills": "bin/skills.cjs",
+    "booklib": "bin/booklib.js",
+    "booklib-mcp": "bin/booklib-mcp.js"
+  },
+  "type": "module",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "skills",
+    "agent-skills",
+    "mcp",
+    "rag"
+  ],
+  "license": "MIT",
+  "homepage": "https://booklib-ai.github.io/booklib/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/booklib-ai/booklib.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@huggingface/transformers": "^3.4.0",
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "gray-matter": "^4.0.3",
+    "minimatch": "^10.2.4",
+    "vectra": "^0.12.3"
+  },
+  "devDependencies": {
+    "puppeteer": "^24.39.1"
+  },
+  "overrides": {
+    "encoding-sniffer": "1.0.2",
+    "global-agent": "4.1.3",
+    "openai": "6.33.0"
+  }
+}

package/research-reports/2026-04-01-current-architecture.md

@@ -0,0 +1,160 @@
+# BookLib — Value Map & Research Alignment
+*April 1, 2026*
+
+---
+
+## What BookLib Is
+
+A local knowledge engine that gives AI agents access to expert knowledge from real books and personal captured insights. It runs locally with zero cloud dependencies, integrates with 13 AI tools via MCP, and produces concise, research-backed context injection.
+
+---
+
+## Value Propositions — Research Validation
+
+### 1. Expert knowledge the model doesn't have
+
+The model knows general programming but not "Item 7 of Effective Java" or "Clean Code Chapter 3: a function should do one thing." BookLib's 24 bundled skills are distilled from specific books — the agent applies them with citations.
+
+**Research alignment:** The ETH Zurich AGENTS.md study (arxiv:2602.11988) validates that context files work — but only when they contain **non-inferable details** the model can't derive on its own. Book-specific principles (item numbers, author-specific frameworks, curated anti-patterns) are exactly this. Generic "write clean code" advice hurts performance; specific "apply the Rule of Three from Refactoring" helps it.
+
+**Current status:** Implemented and validated. 24 skills with XML-tagged structure that separates core principles from examples from anti-patterns — enabling selective injection.
+
+**Gap:** Skills should be audited for conciseness per the ETH Zurich finding. Oversized sections dilute the signal. A `--compact` mode (P1 in backlog) would return only high-signal tags.
+
+---
+
+### 2. Hybrid search
+
+Natural language queries find the most relevant principles across all skills and personal knowledge.
+
+**Research alignment:** The hybrid approach (BM25 + vector + reranking) is grounded in arxiv:2602.12430 which shows 40-60% precision improvement over dense-only baselines. The SRAG metadata prefix approach (arxiv:2603.26670) encodes domain separation directly into the vector space — a 30% QA improvement with p-value 2e-13. Both findings are implemented.
+
+**Current status:** Fully implemented. Five-stage pipeline: query expansion → BM25 + vector search → Reciprocal Rank Fusion → cross-encoder reranking → results. SRAG prefixes active on all indexed chunks.
+
+**Gap:** Embeddings are generated with `all-MiniLM-L6-v2` on Transformers.js v3. Upgrading to v4 (P1) gives ~4x speedup — same model, same results, faster runtime. Late chunking (arxiv:2409.04701, P2) would add another +24% retrieval improvement but requires a model swap and custom pooling.
+
+---
+
+### 3. Personal knowledge graph
+
+Users capture their own insights — architecture decisions, discovered patterns, team conventions — and link them to book skills. These become searchable alongside expert knowledge.
+
+**Research alignment:** The Codified Context paper (arxiv:2602.20478) formalizes exactly this pattern: "hot memory" (always-on skills), "domain agents" (reviewers), and "cold memory" (knowledge base). BookLib's knowledge graph is the cold memory layer. The KG²RAG paper (arxiv:2502.06864, NAACL 2025) shows that organizing search results by graph distance improves coherence — BookLib implements one-hop graph-augmented search.
+
+**Current status:** Implemented. Nodes (markdown + frontmatter), edges (typed JSONL), graph-augmented search with `--graph` flag, `booklib capture` for intentional knowledge creation.
+
+**Gap:** The graph is manually curated (by design — the Spec 3 decision was "no auto-ingestion"). Graph density depends on user engagement. The KG²RAG chunk expansion technique requires denser graphs than BookLib currently has — deferred until capture usage grows.
+
+---
+
+### 4. MCP integration
+
+For 10 out of 13 supported tools, BookLib exposes 8 MCP tools that the agent can call directly. The agent discovers them via MCP protocol, no config file instructions needed for tool discovery.
+
+**Research alignment:** MCP is the industry-standard protocol for agent-tool communication, adopted by Anthropic, OpenAI, Microsoft, Google, and others. BookLib's trigger-oriented tool descriptions ("Use WHEN the user says X" rather than "This tool does Y") align with the OpenDev lazy tool discovery pattern (arxiv:2603.05344) — agents should discover capabilities contextually, not load everything upfront.
+
+**Current status:** Implemented. 8 tools, 10 tool configs, trigger-oriented descriptions. Config files contain a 5-10 line "instinct block" that tells the agent WHEN to use each tool — behavioral triggers, not content dumps.
+
+**Gap:** The `instructions` field in the MCP `initialize` handshake could deliver project context automatically on connect — eliminating the need for config file instinct blocks entirely. Not yet implemented; needs per-client testing to verify support.
+
+---
+
+### 5. Concise config file generation
+
+One `booklib init` generates 30-60 line config files per tool — profile template + skill table + behavioral triggers + reference links. The user owns the file; BookLib adds a small auto-generated section.
+
+**Research alignment:** Directly implements the ETH Zurich finding. Previous BookLib versions generated 3,000-10,000 line config files by dumping raw skill content — exactly the pattern the study shows HURTS agent performance. The new architecture injects metadata only (skill names + descriptions + tags), delegates detail retrieval to MCP search.
+
+**Current status:** Implemented. 5 activity-based profiles (software-development, writing, research, design, general). Config files include official documentation links for each tool so users know how to customize.
+
+**Gap:** None significant. The architecture is research-aligned and tested.
+
+---
+
+### 6. Setup wizard
+
+Interactive guided setup with project detection, skill recommendation, tool configuration, and health diagnostics.
+
+**Research alignment:** Not directly research-driven — this is product UX. However, the recommendation engine uses the same hybrid search pipeline (Section 2), so skill recommendations benefit from the SRAG and retrieval improvements.
+
+**Current status:** Implemented with `@clack/prompts` for modern CLI UX. Detects 13 agents including VS Code extensions. Offers cleanup when users have too many skills installed.
+
+**Gap:** Recommendation quality depends on search index accuracy. With all skills scoring 100% (reranker saturation), differentiation relies on rank-based display scores — functional but not intuitive.
+
+---
+
+### 7. Doctor diagnostic + repair
+
+Detects and fixes problems: too many skills, oversized config files, missing index, stale installs.
+
+**Research alignment:** The ETH Zurich study's finding that oversized context hurts performance directly motivates the "oversized config files" diagnostic. The doctor can detect and cure the exact problem the research identifies.
+
+**Current status:** Implemented. 6 diagnostic checks, `--cure` flag for auto-repair.
+
+**Gap:** The "cure" for oversized config files depends on the new config assembler (Section 5) being the default path — which it now is.
+
+---
+
+### 8. Session management + multi-agent handoff
+
+Agents save progress and hand off to other agents across sessions.
+
+**Research alignment:** The Codified Context paper describes session continuity as essential for multi-agent workflows. BookLib's session system (save, resume, recover, merge, lineage) implements the "persistent memory across agent boundaries" pattern.
+
+**Current status:** Implemented. 14 subcommands covering save/resume, multi-agent merge, lineage tracking, encrypted sessions.
+
+**Gap:** Heavily featured but potentially over-engineered for current usage. No evidence of significant adoption of the advanced coordination features (merge, compare, lineage). May benefit from simplification.
+
+---
+
+## Honest Assessment
+
+### What's strong and research-backed
+- **Hybrid search pipeline** — grounded in retrieval research, measurably better than vector-only
+- **SRAG metadata prefixes** — validated technique, unique to BookLib in the CLI skill space
+- **Concise config generation** — directly implements ETH Zurich findings (less = better)
+- **MCP integration** — industry-standard protocol, broad tool coverage
+- **Structured skill format** — XML tags enable selective disclosure, validated by research
+
+### What's functional but unvalidated
+- **Knowledge graph** — works, but value depends on user engagement. No metrics on actual usage
+- **Session management** — comprehensive but possibly over-built. Needs usage data
+- **Setup wizard** — works but recommendations could be sharper
+- **Doctor** — good diagnostics, limited auto-repair
+
+### What's claimed but not true
+- **"Auto-injection via PreToolUse hook"** — not implemented. MCP replaces this for 10/13 tools. Should be removed from website and README.
+- **"258+ discoverable skills"** — discovery engine exists but returns empty by default. No external sources configured.
+
+### What's missing (validated by research, not yet built)
+- **Compact mode** — ETH Zurich says less context is better. We should support `--compact` output (P1)
+- **Transformers.js v4** — free 4x speedup on indexing (P1)
+- **Progressive disclosure** — deliver skills in layers, not all at once (P2)
+- **MCP Server Cards** — ecosystem discoverability (P2)
+
+---
+
+## Research Sources Referenced
+
+### Peer-reviewed / high-confidence
+| Paper | Source Quality | What it validates | Status |
+|-------|--------------|-------------------|--------|
+| arxiv:2602.11988 — ETH Zurich AGENTS.md study | **4/5** — ETH Zurich SRI Lab, rigorous methodology. Preprint, not yet peer-reviewed, but institution reputation is strong. | Less context = better agent performance | ✅ Implemented (config assembler) |
+| arxiv:2502.06864 — KG²RAG (NAACL 2025) | **5/5** — Peer-reviewed at NAACL, top NLP venue | Graph-organized search results | ⚠️ Partially (one-hop only) |
+| SIGIR 2025 — SEE Early Exit | **5/5** — Peer-reviewed at SIGIR, top IR venue | Early-exit cross-encoder reranking | ❌ Backlog (GPU requirement) |
+| HuggingFace Transformers.js v4 | **5/5** — First-party release announcement | 4x embedding speedup | ❌ P1 backlog |
+
+### Established techniques (no specific paper needed)
+| Technique | Status | Notes |
+|-----------|--------|-------|
+| BM25 + vector hybrid retrieval | ✅ Implemented | Standard IR practice, widely adopted |
+| Reciprocal Rank Fusion | ✅ Implemented | Standard IR fusion technique |
+| Cross-encoder reranking | ✅ Implemented | Standard re-ranking approach |
+
+### Preprints — use with caveats
+| Paper | Source Quality | What it claims | Status | Caveat |
+|-------|--------------|----------------|--------|--------|
+| arxiv:2603.26670 — SRAG | **3/5** — Recent preprint, not peer-reviewed | Metadata prefixes improve retrieval 30% | ✅ Implemented | Promising but unverified by independent replication |
+| arxiv:2602.20478 — Codified Context | **2/5** — Single author, single project, not peer-reviewed | Hot/cold memory + domain agents pattern | Architecturally aligned | Do NOT cite in user-facing materials. Fine for internal reference only |
+| arxiv:2603.05344 — OpenDev | **3/5** — System description, not controlled experiment | Progressive/lazy tool discovery | Design pattern adopted | Describes architecture, doesn't prove it outperforms alternatives |
+| arxiv:2409.04701 — Late Chunking | **4/5** — Jina AI research team, reproducible | Contextual embeddings +24% | ❌ P2 backlog | Real technique, complex implementation for BookLib's stack |

package/research-reports/IDEAS.md

@@ -0,0 +1,93 @@
+# BookLib — Validated Feature Ideas Backlog
+
+> Auto-maintained by the daily research validator. Each idea has been reviewed against the actual source material, validated for feasibility, and mapped to a specific implementation path.
+
+## Status Legend
+- 🆕 **New** — Just validated, not yet prioritized
+- 🔥 **Hot** — High impact + low/medium effort, should be picked up soon
+- 📋 **Backlog** — Validated and valuable, but not urgent
+- ✅ **Done** — Implemented
+- ❌ **Rejected** — Reviewed and decided against (with reason)
+
+---
+
+## Ideas
+
+### [2026-03-31] SRAG: Prepend structured metadata to chunks before embedding
+**Status:** ✅ Done | **Source:** [arxiv:2603.26670](https://arxiv.org/abs/2603.26670) (preprint, not peer-reviewed) | **Priority:** P1 | **Spec:** 2
+**Summary:** Prefix each chunk with `[skill:{name}] [type:{xml_tag}] [tags:{...}]` before embedding to encode domain separation into the vector space. Claims 30% QA improvement — promising but unverified by independent replication.
+**Work estimate:** 1 day | **Files:** `lib/engine/indexer.js`, `lib/engine/parser.js`
+**Acceptance criteria:**
+- Chunk text prefixed with structured metadata before embedding
+- `parseSkillFile()` passes metadata to indexer
+- Cross-domain noise in search results is measurably reduced
+- No new dependencies required
+- Re-index command handles new format cleanly
+
+### [2026-03-31] MCP Server Cards: Add .well-known/mcp/server-card.json
+**Status:** 🆕 New | **Source:** [MCP 2026 Roadmap](https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/) + [SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649) | **Priority:** P2 | **Spec:** 1
+**Summary:** Generate an MCP Server Card alongside the existing .well-known/skills/ endpoint so BookLib's MCP server is discoverable by the entire MCP ecosystem.
+**Work estimate:** 0.5 days | **Files:** CI pipeline, `docs/.well-known/`
+**Acceptance criteria:**
+- `booklib build-wellknown` also generates `server-card.json`
+- Card follows the SEP-1649 draft format
+- Hosted via GitHub Pages alongside existing skill index
+
+### [2026-03-31] Cite "Codified Context" paper in positioning materials
+**Status:** ❌ Rejected | **Source:** [arxiv:2602.20478](https://arxiv.org/abs/2602.20478) (source quality 2/5 — single author, single project, not peer-reviewed) | **Priority:** — | **Spec:** —
+**Summary:** ~~Reference the Codified Context paper to position BookLib.~~ **Rejected:** Source quality too low for user-facing citation. Single-author preprint on one project. The taxonomy is useful internally but should not be cited in README or marketing. Kept in internal research notes only.
+**Work estimate:** 2 hours | **Files:** `README.md`, `benchmark/RESEARCH.md`
+**Acceptance criteria:**
+- README references the paper's terminology
+- RESEARCH.md maps BookLib's architecture to the paper's taxonomy
+- Framing says "aligns with" not "validated by" (single-author preprint)
+
+### [2026-03-31] Late Chunking: Contextual embeddings via long-context model
+**Status:** 📋 Backlog | **Source:** [arxiv:2409.04701](https://arxiv.org/abs/2409.04701) | **Priority:** P2 | **Spec:** 2
+**Summary:** Switch to jina-embeddings-v2-small-en (8192 tokens) and implement late chunking — embed full skill file first, then chunk. +24% retrieval improvement. Requires custom pooling in transformers.js and full re-index.
+**Work estimate:** 3-5 days | **Files:** `lib/engine/indexer.js`, `lib/engine/searcher.js`
+**Acceptance criteria:**
+- Embedding model swapped to jina-embeddings-v2-small-en
+- Token-level embeddings extracted before pooling
+- Chunked mean pooling applied per skill section
+- Full re-index migration path documented
+- Benchmark shows improvement over baseline
+**Note:** Implement after hybrid pipeline (Spec 2) is stable. Depends on custom transformers.js pooling — not a drop-in change.
+
+### [2026-04-01] Upgrade to Transformers.js v4 for ~4x embedding speedup
+**Status:** 🔥 Hot | **Source:** [HuggingFace Blog](https://huggingface.co/blog/transformersjs-v4) | **Priority:** P1 | **Spec:** 2
+**Summary:** Upgrade from @xenova/transformers v3 to @huggingface/transformers v4. ~4x speedup on BERT embeddings via optimized ONNX operators. Same model, same API, dramatically faster indexing. Package renamed, model ID updated, optional WebGPU for GPU users.
+**Work estimate:** 0.5–1 day | **Files:** `package.json`, `lib/engine/indexer.js`, `lib/engine/searcher.js`
+**Acceptance criteria:**
+- Package updated to @huggingface/transformers v4
+- Model ID updated to onnx-community/all-MiniLM-L6-v2-ONNX
+- Identical index output (same embeddings, same search results)
+- Measurable indexing speedup benchmarked
+- All existing tests pass
+
+### [2026-04-01] Research-backed skill content guidelines + audit command
+**Status:** 🔥 Hot | **Source:** [arxiv:2602.11988](https://arxiv.org/abs/2602.11988) (ETH Zurich SRI Lab) | **Priority:** P1 | **Spec:** Core + Spec 1
+**Summary:** ETH Zurich study shows LLM-generated context files reduce agent success rates while increasing cost 20%+. Update skill authoring guidelines to recommend "non-inferable details only." Add `booklib audit` to flag oversized sections. Add `--compact` parser mode for minimal injection.
+**Work estimate:** 0.5–1 day | **Files:** docs, `lib/engine/parser.js`, `bin/cli.js`
+**Acceptance criteria:**
+- Authoring docs cite study and recommend concise, non-inferable content
+- `booklib audit` reports per-section token counts with threshold warnings
+- `parser.js` supports --compact mode (core_principles + anti_patterns only)
+- README positions BookLib's format as research-backed
+**Note:** Reinforced by OpenDev paper (arxiv:2603.05344) which demonstrates progressive disclosure pattern. BookLib's XML tags are natural disclosure layers.
+
+### [2026-04-01] Progressive skill disclosure via --progressive flag
+**Status:** 📋 Backlog | **Source:** [arxiv:2603.05344](https://arxiv.org/abs/2603.05344) (OpenDev) + [arxiv:2602.11988](https://arxiv.org/abs/2602.11988) (ETH Zurich) | **Priority:** P2 | **Spec:** 1
+**Summary:** Add `booklib context --progressive` that outputs skills in layers (metadata → core_principles → full). Inspired by OpenDev's lazy tool discovery pattern, validated by ETH Zurich's finding that less context performs better. Uses BookLib's existing XML-tagged structure.
+**Work estimate:** 1 day | **Files:** `lib/engine/parser.js`, `bin/cli.js`
+**Acceptance criteria:**
+- `--progressive` flag outputs three disclosure levels
+- Hook injection can use compact mode for first injection, expand on demand
+- No breaking changes to existing parsing
+**Note:** Implement through existing BookLib mechanisms (--compact flag, parser modes) rather than non-standard MCP protocol extensions. MCP contract changes carry adoption risk.
+
+### [2026-04-01] SEE: Early-exit cross-encoder reranking
+**Status:** 📋 Backlog | **Source:** [SIGIR 2025](https://dl.acm.org/doi/10.1145/3726302.3729962) | **Priority:** P3 | **Spec:** 2
+**Summary:** Cross-encoder reranking with similarity-based early exit — terminate forward pass when intermediate layers already provide confident ranking. Peer-reviewed at SIGIR. But: PyTorch/GPU only, no ONNX path, and BookLib has no cross-encoder yet. Long-term backlog item.
+**Work estimate:** 2-3 weeks (including prerequisite cross-encoder work) | **Files:** `lib/engine/reranker.js` (new), `lib/engine/searcher.js`
+**Note:** Blocked on Spec 2 cross-encoder implementation. Current impl is PyTorch+GPU only — would need custom ONNX layer-by-layer export for transformers.js. Defer until hybrid pipeline is stable.

package/rules/common/clean-code.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Clean Code standards from Robert C. Martin. Apply to all code regardless of language.
+---
+
+# Clean Code Standards
+
+Apply these principles from *Clean Code* (Robert C. Martin) to all code you write or review.
+
+## Names
+
+- Use intention-revealing names — if the name needs a comment to explain it, rename it
+- Avoid abbreviations unless universally understood (`url`, `id`, `ctx` are fine; `mgr`, `proc` are not)
+- Classes and types are nouns; methods and functions are verb phrases
+- Avoid noise words that add no meaning: `Manager`, `Data`, `Info`, `Handler` in type names usually signal a missing concept
+- Boolean variables and functions read as assertions: `isEnabled`, `hasPermission`, `canRetry`
+
+## Functions
+
+- Functions do one thing; if you can extract a meaningful sub-function with a non-trivial name, the function does too much
+- Keep functions short — aim for under 20 lines; over 40 is a smell
+- Max 3 parameters; group related parameters into a value object when you need more
+- Avoid boolean flag parameters — they signal the function does two things; split it
+- No side effects in functions that return values
+
+## Comments
+
+- Comments compensate for failure to express intent in code — prefer renaming over commenting
+- Never commit commented-out code; use version control
+- `// TODO:` is acceptable only when tracked in an issue; delete stale TODOs
+- Document *why*, not *what* — the code shows what; the comment explains a non-obvious reason
+
+## Structure
+
+- Group related code together; put high-level concepts at the top, details below
+- Functions in a file should be ordered so callers appear before callees
+- Avoid deep nesting — if `if`/`else` chains exceed 3 levels, extract or invert conditions
+
+## Error handling
+
+- Prefer exceptions over error codes for exceptional conditions
+- Handle errors at the appropriate abstraction level — don't catch and re-throw unless you add context
+- Never swallow exceptions silently; at minimum log before ignoring

package/rules/java/effective-java.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective Java standards from Joshua Bloch. Apply when writing or reviewing Java code.
+---
+
+# Effective Java Standards
+
+Apply these principles from *Effective Java* (Joshua Bloch, 3rd edition) to all Java code.
+
+## Object creation
+
+- Prefer static factory methods over constructors — they have names, can return subtypes, and can cache instances
+- Use a builder when a constructor or factory would have more than 3 parameters
+- Never create unnecessary objects; reuse `String` literals, prefer `Boolean.valueOf(x)` over `new Boolean(x)`
+
+## Classes and mutability
+
+- Minimize mutability — all fields `private final` by default; add setters only when needed
+- Favor composition over inheritance; explicitly document classes designed for extension or mark them `final`
+- Override `@Override` on every method that overrides or implements; the annotation catches typos at compile time
+
+## Methods
+
+- Validate parameters at entry; throw `IllegalArgumentException`, `NullPointerException`, or `IndexOutOfBoundsException` with a message
+- Return empty collections or `Optional`, never `null`, from methods with a non-primitive return type
+- Use `Optional` for return values that may be absent; don't use it for fields or parameters
+
+## Exceptions
+
+- Use checked exceptions for recoverable conditions; unchecked (`RuntimeException`) for programming errors
+- Prefer standard exceptions: `IllegalArgumentException`, `IllegalStateException`, `UnsupportedOperationException`, `NullPointerException`
+- Don't swallow exceptions — at minimum log with context before ignoring; never `catch (Exception e) {}`
+
+## Generics and collections
+
+- Use generic types and methods; avoid raw types (`List` → `List<E>`)
+- Use bounded wildcards (`? extends T` for producers, `? super T` for consumers — PECS)
+- Prefer `List` over arrays for type safety; use arrays only for performance-sensitive low-level code
+
+## Concurrency
+
+- Synchronize all accesses to shared mutable state; prefer `java.util.concurrent` utilities over `synchronized`
+- Prefer immutable objects and thread confinement over shared mutable state

package/rules/kotlin/effective-kotlin.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Effective Kotlin standards from Marcin Moskała. Apply when writing or reviewing Kotlin code.
+---
+
+# Effective Kotlin Standards
+
+Apply these principles from *Effective Kotlin* (Marcin Moskała, 2nd edition) to all Kotlin code.
+
+## Safety
+
+- Prefer `val` over `var`; use `var` only when mutation is genuinely required
+- Use nullable types explicitly (`T?`); avoid `!!` — narrow with `?.`, `?:`, `let`, or `checkNotNull()`
+- Use `require()` for argument preconditions and `check()` for state preconditions at function entry
+
+## Functions
+
+- Use named arguments when passing more than 2 parameters, especially when they share the same type
+- Use default arguments instead of overloads for optional behavior
+- Prefer extension functions over utility classes for domain operations on a type you own
+
+## Classes and design
+
+- Use data classes for value objects — they get `equals`, `hashCode`, `copy`, and `toString` for free
+- Prefer sealed classes over open hierarchies when the set of subtypes is finite and known
+- Use `object` for singletons, `companion object` for factory methods and class-level constants
+
+## Collections
+
+- Use functional operators (`map`, `filter`, `fold`, `groupBy`) over manual loops
+- Prefer `Sequence` for large collections or multi-step pipelines — avoids intermediate lists
+- Use `buildList { }` / `buildMap { }` instead of a mutable variable followed by `.toList()`
+
+## Coroutines
+
+- Launch coroutines in a structured `CoroutineScope`; never use `GlobalScope` in production
+- Use `withContext(Dispatchers.IO)` for blocking I/O; never block the main/UI thread
+- Prefer `Flow` over callbacks for asynchronous streams; use `StateFlow` for observable state

package/rules/python/effective-python.md

@@ -0,0 +1,38 @@
+---
+description: Always-on Effective Python standards from Brett Slatkin. Apply when writing or reviewing Python code.
+---
+
+# Effective Python Standards
+
+Apply these principles from *Effective Python* (Brett Slatkin, 3rd edition) to all Python code.
+
+## Pythonic style
+
+- Use `enumerate()` over `range(len(...))` for indexed iteration
+- Use f-strings for interpolation; avoid `%` formatting and `.format()`
+- Prefer unpacking over indexing: `first, *rest = items` instead of `items[0]` and `items[1:]`
+- Use `zip()` to iterate two sequences together; use `zip(strict=True)` when lengths must match
+
+## Data structures
+
+- Use `list` for ordered mutable sequences, `tuple` for immutable positional data, `set` for membership tests
+- Use `collections.defaultdict` or `Counter` instead of manual dict initialization
+- Prefer `dataclasses` over plain dicts or namedtuples for structured data with methods
+
+## Functions
+
+- Use keyword-only arguments (`def f(a, *, b)`) for optional parameters that benefit from names at the call site
+- Never use mutable default arguments — use `None` and assign inside the function body
+- Prefer generator expressions `(x for x in ...)` over list comprehensions when you don't need the full list in memory
+
+## Type annotations
+
+- Annotate all public functions and class attributes
+- Use `X | None` (Python 3.10+) or `Optional[X]` for nullable types; never return `None` silently from a typed function
+- Avoid `Any` except at system boundaries (external APIs, deserialized JSON)
+
+## Error handling
+
+- Catch specific exception types; never use bare `except:`
+- Use `contextlib.suppress(ExceptionType)` for intentionally ignored exceptions — makes the intent explicit
+- Use `__all__` in every module to declare its public API

package/rules/rust/rust.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Rust standards from Programming with Rust and Rust in Action. Apply when writing or reviewing Rust code.
+---
+
+# Rust Standards
+
+Apply these principles from *Programming with Rust* (Donis Marshall) and *Rust in Action* (Tim McNamara) to all Rust code.
+
+## Ownership and borrowing
+
+- Use owned values (`String`, `Vec<T>`) for data you own; borrow (`&str`, `&[T]`) when you only need to read
+- Prefer passing `&T` or `&mut T` over cloning; clone only when ownership transfer is required
+- Use `Rc<T>` for single-threaded shared ownership, `Arc<T>` for multi-threaded; use `RefCell<T>` / `Mutex<T>` for interior mutability
+
+## Error handling
+
+- Return `Result<T, E>` from all fallible functions; propagate with `?`
+- Use `thiserror` to define library errors with `#[derive(Error)]`; use `anyhow` for application-level error context
+- Avoid `.unwrap()` in library code; use `.expect("clear message")` in application code where panicking is intentional
+
+## Types and traits
+
+- Use `struct` for data, `enum` for variants with payloads, `trait` for shared behaviour
+- Implement standard traits where appropriate: `Debug` always, `Display` for user-facing types, `Clone`, `PartialEq`, `Hash` as needed
+- Use `impl Trait` in argument position for static dispatch; `Box<dyn Trait>` only when you need runtime dispatch
+
+## Idiomatic patterns
+
+- Use `Iterator` adapters (`map`, `filter`, `flat_map`, `collect`) over manual loops — the compiler optimizes them equally
+- Use `Option` methods (`map`, `unwrap_or`, `and_then`, `ok_or`) over `match` for simple transformations
+- Use `if let` for single-variant matching; use `match` for exhaustive handling
+
+## Naming and style
+
+- Types: `PascalCase`; functions, variables, modules: `snake_case`; constants and statics: `SCREAMING_SNAKE_CASE`
+- Lifetime names: `'a`, `'b` for simple cases; descriptive names (`'arena`, `'cx`) for complex lifetimes
+- Mark all public items in a library crate with doc comments (`///`)

package/rules/typescript/effective-typescript.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective TypeScript standards from Dan Vanderkam. Apply when writing or reviewing TypeScript or JavaScript code.
+---
+
+# Effective TypeScript Standards
+
+Apply these principles from *Effective TypeScript* (Dan Vanderkam, 2nd edition) to all TypeScript code.
+
+## Types
+
+- Prefer union types over enums for simple sets of values: `type Direction = 'N' | 'S' | 'E' | 'W'`
+- Use `interface` for extensible object shapes that others may augment; use `type` for unions, intersections, and computed types
+- Avoid `any`; use `unknown` when the type is genuinely unknown, then narrow with guards before use
+- Avoid type assertions (`as T`) — prefer type narrowing, overloads, or generics
+
+## Type inference
+
+- Let TypeScript infer return types on internal functions; explicitly annotate public API return types
+- Annotate a variable at declaration if it cannot be initialized immediately
+- Use `as const` to preserve literal types; don't use it just to silence widening errors
+
+## Null safety
+
+- Enable `strict` mode (which includes `strictNullChecks`) — treat every `T | undefined` as requiring explicit handling
+- Use optional chaining `?.` and nullish coalescing `??` over `&&` and `||` chains
+- Never use non-null assertion (`!`) — narrow instead
+
+## Structural typing
+
+- TypeScript checks shapes, not nominal types — understand that duck typing applies
+- Use discriminated unions with a `kind` or `type` literal field for exhaustive `switch` / narrowing
+- Avoid class hierarchies for data shapes — prefer interfaces and composition
+
+## Generics
+
+- Constrain generics to the minimum required: `<T extends string>` not `<T>`
+- Use descriptive generic names for complex types (`<TItem, TKey>`) and single letters for simple transforms (`<T>`, `<K, V>`)
+
+## Functions
+
+- Prefer function overloads over union parameter types to express the relationship between input and output
+- Keep functions pure where possible; extract side effects to the call site