Initial release: context-aware knowledge router for AI agents

Dispatch table format, frontmatter spec, keyword matcher, token estimator,
and index validator. The reusable routing layer that powers claude-rules
and future agent knowledge systems.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mcp-tool-shop

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "package.json"
+      - "tsconfig.json"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "src/**"
+      - "package.json"
+      - "tsconfig.json"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm audit --audit-level=moderate
+      - run: npm pack --dry-run

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0 — 2026-03-06
+
+Initial release.
+
+- `LoadoutIndex` schema — dispatch table for agent knowledge
+- `parseFrontmatter()` / `serializeFrontmatter()` — payload file metadata
+- `matchLoadout()` — deterministic keyword + pattern matcher
+- `lookupEntry()` — explicit entry lookup by ID
+- `validateIndex()` — structural linter for index integrity
+- `estimateTokens()` — chars/4 heuristic for budget dashboards
+- Three priority tiers: core / domain / manual
+- Trigger phases: task / plan / edit
+- Zero production dependencies

README.md

@@ -0,0 +1,181 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ai-loadout/readme.png" width="400" alt="ai-loadout">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/ai-loadout"><img src="https://img.shields.io/npm/v/@mcptoolshop/ai-loadout" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+</p>
+
+Context-aware knowledge router for AI agents.
+
+`ai-loadout` is the dispatch table format and matching engine that lets AI agents load the right knowledge for the task at hand. Instead of dumping everything into context, you keep a tiny index and load payloads on demand.
+
+Think of it like a game loadout — you equip the agent with exactly the knowledge it needs before each mission.
+
+## Install
+
+```bash
+npm install @mcptoolshop/ai-loadout
+```
+
+## Core Concepts
+
+### The Dispatch Table
+
+A `LoadoutIndex` is a structured index of knowledge payloads:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-03-06T12:00:00Z",
+  "entries": [
+    {
+      "id": "github-actions",
+      "path": ".rules/github-actions.md",
+      "keywords": ["ci", "workflow", "runner"],
+      "patterns": ["ci_pipeline"],
+      "priority": "domain",
+      "summary": "CI triggers, path gating, runner cost control",
+      "triggers": { "task": true, "plan": true, "edit": false },
+      "tokens_est": 680,
+      "lines": 56
+    }
+  ],
+  "budget": {
+    "always_loaded_est": 320,
+    "on_demand_total_est": 8100,
+    "avg_task_load_est": 520,
+    "avg_task_load_observed": null
+  }
+}
+```
+
+### Priority Tiers
+
+| Tier | Behavior | Example |
+|------|----------|---------|
+| `core` | Always loaded | "never skip tests to make CI green" |
+| `domain` | Loaded when task keywords match | CI rules when editing workflows |
+| `manual` | Never auto-loaded, explicit lookup only | Obscure platform gotchas |
+
+### Payload Frontmatter
+
+Each payload file carries its own routing metadata:
+
+```markdown
+---
+id: github-actions
+keywords: [ci, workflow, runner, dependabot]
+patterns: [ci_pipeline]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# GitHub Actions Rules
+CI minutes are finite...
+```
+
+Frontmatter is the source of truth. The index is derived from it.
+
+## API
+
+### `matchLoadout(task, index)`
+
+Match a task description against a loadout index. Returns entries that should be loaded, ranked by match strength.
+
+```typescript
+import { matchLoadout } from "@mcptoolshop/ai-loadout";
+
+const results = matchLoadout("fix the CI workflow", index);
+// [{ entry: { id: "github-actions", ... }, score: 0.67, matchedKeywords: ["ci", "workflow"] }]
+```
+
+- Core entries always included (score 1.0)
+- Manual entries never auto-included
+- Domain entries scored by keyword overlap + pattern bonus
+- Results sorted by score descending
+
+### `lookupEntry(id, index)`
+
+Look up a specific entry by ID. For manual entries or explicit access.
+
+```typescript
+import { lookupEntry } from "@mcptoolshop/ai-loadout";
+
+const entry = lookupEntry("github-actions", index);
+```
+
+### `parseFrontmatter(content)`
+
+Parse YAML-like frontmatter from a payload file.
+
+```typescript
+import { parseFrontmatter } from "@mcptoolshop/ai-loadout";
+
+const { frontmatter, body } = parseFrontmatter(fileContent);
+if (frontmatter) {
+  console.log(frontmatter.id, frontmatter.keywords);
+}
+```
+
+### `serializeFrontmatter(fm)`
+
+Serialize a `Frontmatter` object back to a string.
+
+### `validateIndex(index)`
+
+Validate structural integrity of a `LoadoutIndex`. Returns an array of issues.
+
+```typescript
+import { validateIndex } from "@mcptoolshop/ai-loadout";
+
+const issues = validateIndex(index);
+const errors = issues.filter(i => i.severity === "error");
+if (errors.length > 0) {
+  console.error("Index has errors:", errors);
+}
+```
+
+Checks: required fields, unique IDs, kebab-case format, summary bounds, keyword presence for domain entries, valid priorities, non-negative budgets.
+
+### `estimateTokens(text)`
+
+Estimate token count from text. Uses chars/4 heuristic.
+
+```typescript
+import { estimateTokens } from "@mcptoolshop/ai-loadout";
+
+const tokens = estimateTokens(fileContent); // ~250
+```
+
+## Types
+
+```typescript
+import type {
+  LoadoutEntry,
+  LoadoutIndex,
+  Frontmatter,
+  MatchResult,
+  ValidationIssue,
+  Priority,       // "core" | "domain" | "manual"
+  Triggers,       // { task, plan, edit }
+  Budget,
+} from "@mcptoolshop/ai-loadout";
+```
+
+## Consumers
+
+- **[@mcptoolshop/claude-rules](https://github.com/mcp-tool-shop-org/claude-rules)** — CLAUDE.md optimizer for Claude Code. Uses ai-loadout for the dispatch table and matching.
+
+## Security
+
+This package is a pure data library. It does not access the filesystem, make network requests, or collect telemetry. All I/O is the consumer's responsibility.
+
+---
+
+Built by [MCP Tool Shop](https://mcp-tool-shop.github.io/)

package-lock.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mcptoolshop/ai-loadout",
+  "version": "1.0.0",
+  "description": "Context-aware knowledge router for AI agents. Dispatch table, frontmatter spec, keyword matcher, token estimator.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "verify": "tsc --noEmit && node --test dist/tests/*.test.js",
+    "test": "node --test dist/tests/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "loadout",
+    "knowledge",
+    "routing",
+    "dispatch",
+    "context",
+    "frontmatter",
+    "mcp"
+  ],
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}