@softspark/ai-toolkit 1.0.0

package/kb/reference/agents-catalog.md

@@ -0,0 +1,124 @@
+---
+title: "AI Toolkit - Agents Catalog"
+category: reference
+service: ai-toolkit
+tags: [agents, catalog, roles, ai-development]
+version: "2.0.0"
+created: "2026-03-23"
+last_updated: "2026-03-25"
+description: "Complete catalog of 47 specialized agents with roles, models, and use cases."
+---
+
+# Agents Catalog (47 agents)
+
+## By Category
+
+### Orchestration & Planning (4)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **orchestrator** | opus | Multi-agent coordination, 3+ agents per task |
+| **project-planner** | opus | Task breakdown, dependency graphs, file structure |
+| **product-manager** | opus | Requirements, user stories, acceptance criteria, backlog prioritization |
+| **tech-lead** | opus | Code quality authority, architecture patterns |
+
+### Development (5)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **backend-specialist** | opus | Node.js, Python, PHP, FastAPI, APIs |
+| **frontend-specialist** | opus | React, Next.js, Vue, Nuxt, Tailwind |
+| **mobile-developer** | opus | React Native, Flutter, native iOS/Android |
+| **game-developer** | opus | Unity, Godot, Unreal, Phaser, Three.js |
+| **database-architect** | opus | Schema design, migrations, query optimization, operations |
+
+### AI/ML (7)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **ai-engineer** | opus | LLM integration, vector databases, RAG, agent orchestration |
+| **ml-engineer** | opus | Model training, MLOps, TensorFlow, PyTorch |
+| **nlp-engineer** | opus | NLP pipelines, NER, text classification, transformers |
+| **data-scientist** | opus | Statistics, visualization, EDA, hypothesis testing |
+| **data-analyst** | sonnet | SQL, analytics, reporting, dashboards |
+| **prompt-engineer** | opus | Prompt design, chain-of-thought, few-shot, optimization |
+| **rag-engineer** | opus | RAG pipelines, document indexing, retrieval optimization |
+
+### Quality & Security (6)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **code-reviewer** | opus | Code review, standards, quality audit |
+| **test-engineer** | opus | Test strategy, TDD, unit/integration/E2E tests |
+| **qa-automation-engineer** | opus | Playwright, Cypress, API testing, performance testing |
+| **security-auditor** | opus | OWASP, CVE analysis, pen testing, vulnerability assessment |
+| **security-architect** | opus | Threat modeling, secure design, AuthN/AuthZ |
+| **system-governor** | opus | Constitution guardian, validates changes, VETO power |
+
+### Infrastructure & DevOps (6)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **devops-implementer** | opus | Terraform, Ansible, Docker, Kubernetes, CI/CD |
+| **infrastructure-architect** | opus | System design, architecture notes, trade-off analysis |
+| **infrastructure-validator** | sonnet | Deployment verification, health checks, rollback |
+| **incident-responder** | sonnet | P1-P4 incidents, emergency fixes, postmortem |
+| **performance-optimizer** | opus | Profiling, bottleneck analysis, latency, scaling |
+| **llm-ops-engineer** | opus | LLM caching, fallback, cost optimization, observability |
+
+### Research & Documentation (6)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **explorer-agent** | sonnet | Codebase discovery (READ-ONLY, never writes) |
+| **research-synthesizer** | opus | Research coordination, synthesis, report generation |
+| **technical-researcher** | opus | Deep technical investigation, feasibility studies |
+| **search-specialist** | sonnet | Search optimization, relevance ranking |
+| **fact-checker** | sonnet | Claim verification, source validation |
+| **documenter** | sonnet | Documentation, KB management, SOPs, API docs, tutorials |
+
+### MCP (3)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **mcp-expert** | opus | MCP protocol expertise, client configuration |
+| **mcp-server-architect** | opus | MCP server design, JSON-RPC, tool definitions |
+| **mcp-testing-engineer** | sonnet | MCP protocol compliance, transport testing |
+
+### Management & Evolution (4)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **chief-of-staff** | sonnet | Executive summaries, daily briefings, noise reduction |
+| **meta-architect** | opus | Self-optimization, agent definition updates |
+| **predictive-analyst** | sonnet | Impact prediction, regression forecasting |
+| **business-intelligence** | sonnet | Opportunity discovery, KPI gaps, value creation |
+
+### Autonomous (2)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **night-watchman** | sonnet | Autonomous maintenance: dependency updates, dead code |
+| **chaos-monkey** | opus | Resilience testing: fault injection, failure verification |
+
+### Specialist (4)
+
+| Agent | Model | Use Case |
+|-------|-------|----------|
+| **debugger** | opus | Root cause analysis, stack traces, intermittent failures |
+| **code-archaeologist** | sonnet | Legacy code investigation, technical debt |
+| **command-expert** | sonnet | CLI commands, bash scripting, build scripts |
+| **seo-specialist** | sonnet | SEO optimization, meta tags, Core Web Vitals |
+
+## Agent Selection Matrix
+
+| Task Type | Primary | Supporting | Validation |
+|-----------|---------|------------|------------|
+| New Feature | backend/frontend-specialist | test-engineer | code-reviewer |
+| Bug Fix | debugger | backend/frontend | test-engineer |
+| Performance | performance-optimizer | database-architect | infrastructure-validator |
+| Security | security-auditor | security-architect | code-reviewer |
+| Architecture | infrastructure-architect | devops-implementer | security-auditor |
+| Documentation | documenter | explorer-agent | tech-lead |
+| AI/ML | ai-engineer | ml-engineer | rag-engineer |
+| Research | research-synthesizer | technical-researcher | fact-checker |

package/kb/reference/anti-pattern-registry-format.md

@@ -0,0 +1,221 @@
+---
+title: "Anti-Pattern Registry Format"
+category: reference
+service: ai-toolkit
+description: "Structured JSON format for anti-patterns with severity, auto-fixability, and conflict rules. Used by domain skills with reasoning engines."
+tags: [anti-patterns, skills, reasoning-engine, format]
+created: 2026-04-01
+last_updated: 2026-04-01
+---
+
+# Anti-Pattern Registry Format
+
+## Overview
+
+The anti-pattern registry is a structured JSON format used by domain skills that
+employ reasoning engines. It provides a machine-readable catalog of known
+anti-patterns with severity levels, auto-fix capabilities, and conflict rules.
+
+## When to Use
+
+Use structured JSON registries (this format) when:
+
+- The skill catalogs **more than 50 items** across **more than 3 compatibility
+  dimensions** (e.g., domain, severity, language, framework).
+- Items have relationships (conflicts, prerequisites, alternatives) that must be
+  queryable at runtime.
+- The reasoning engine (`search.py`) needs to filter, score, and exclude
+  conflicting entries programmatically.
+
+Use Markdown tables when:
+
+- Fewer than 50 items with 3 or fewer dimensions.
+- No inter-item relationships.
+- Human readability is the only consumer.
+
+## JSON Schema
+
+Each entry in the registry follows this schema:
+
+```json
+{
+  "id": "string (required)",
+  "name": "string (required)",
+  "domain": "string (required)",
+  "description": "string (required)",
+  "pattern": "string (optional)",
+  "severity": "string (required)",
+  "auto_fixable": "boolean (required)",
+  "conflicts_with": ["string (optional)"],
+  "remediation": "string (required)",
+  "tags": ["string (optional)"]
+}
+```
+
+### Field Definitions
+
+#### `id` (required)
+
+Unique identifier in kebab-case. Must be globally unique across all registry
+files within the same assets directory.
+
+```
+"id": "n-plus-one-query"
+```
+
+#### `name` (required)
+
+Human-readable display name. Used in reports and dashboards.
+
+```
+"name": "N+1 Query Problem"
+```
+
+#### `domain` (required)
+
+The skill domain this anti-pattern belongs to. Used for filtering when a
+reasoning engine serves multiple domains.
+
+Valid domains include: `security`, `database`, `api`, `architecture`,
+`performance`, `testing`, `general`. Skills may define additional domains as
+needed.
+
+```
+"domain": "database"
+```
+
+#### `description` (required)
+
+Clear explanation of what this anti-pattern is and why it is problematic. Should
+be actionable -- a developer reading this should understand the risk.
+
+```
+"description": "Executing one query per item in a loop instead of a single batch query. Causes O(n) database round-trips where O(1) is possible."
+```
+
+#### `pattern` (optional)
+
+A regex pattern for automated detection in source code. When present, tooling
+can scan codebases for occurrences. Omit if the anti-pattern is architectural
+or cannot be detected via regex.
+
+```
+"pattern": "for\\s+.*\\sin\\s+.*:\\s*\\n\\s+.*\\.objects\\.get"
+```
+
+#### `severity` (required)
+
+Impact level. Must be one of:
+
+| Value | Meaning |
+|-------|---------|
+| `critical` | Causes security vulnerabilities, data loss, or production outages. Must fix before merge. |
+| `important` | Degrades performance, maintainability, or reliability significantly. Should fix in current sprint. |
+| `suggestion` | Improvement opportunity. Fix when convenient or during refactoring. |
+
+```
+"severity": "important"
+```
+
+#### `auto_fixable` (required)
+
+Boolean indicating whether tooling can automatically remediate this
+anti-pattern. When `true`, the reasoning engine or a companion script can
+generate a fix.
+
+```
+"auto_fixable": true
+```
+
+#### `conflicts_with` (optional)
+
+List of anti-pattern IDs that conflict with this entry. The reasoning engine
+uses this for mutual exclusion -- if one pattern is selected/detected, the
+conflicting ones are filtered out of results.
+
+This prevents contradictory advice (e.g., "use eager loading" and "use lazy
+loading" simultaneously).
+
+```
+"conflicts_with": ["eager-load-everything"]
+```
+
+#### `remediation` (required)
+
+Concrete instructions for fixing the anti-pattern. Should include a code
+example or reference to a known-good pattern when possible.
+
+```
+"remediation": "Replace loop queries with select_related() or prefetch_related() for Django, or use JOIN/eager loading in your ORM."
+```
+
+#### `tags` (optional)
+
+Freeform tags for cross-cutting search. Useful for filtering by technology,
+language, or concern that does not map to a single domain.
+
+```
+"tags": ["orm", "django", "sqlalchemy", "performance"]
+```
+
+## Complete Example
+
+```json
+[
+  {
+    "id": "n-plus-one-query",
+    "name": "N+1 Query Problem",
+    "domain": "database",
+    "description": "Executing one query per item in a loop instead of a single batch query. Causes O(n) database round-trips where O(1) is possible.",
+    "pattern": "for\\s+.*\\sin\\s+.*:\\s*\\n\\s+.*\\.objects\\.get",
+    "severity": "important",
+    "auto_fixable": false,
+    "conflicts_with": [],
+    "remediation": "Replace loop queries with select_related() or prefetch_related() for Django, or use JOIN/eager loading in your ORM.",
+    "tags": ["orm", "django", "sqlalchemy", "performance"]
+  },
+  {
+    "id": "hardcoded-secrets",
+    "name": "Hardcoded Secrets",
+    "domain": "security",
+    "description": "API keys, passwords, or tokens embedded directly in source code. Exposed in version control history even after removal.",
+    "pattern": "(api_key|secret|password|token)\\s*=\\s*[\"'][^\"']+[\"']",
+    "severity": "critical",
+    "auto_fixable": true,
+    "conflicts_with": [],
+    "remediation": "Move secrets to environment variables or a secrets manager (AWS SSM, Vault, dotenv for local). Reference via os.environ or settings module.",
+    "tags": ["secrets", "env", "vault", "ci"]
+  }
+]
+```
+
+## File Organization
+
+Registry files live in the `assets/` directory alongside the reasoning engine:
+
+```
+templates/reasoning-engine/
+  search.py           # Reasoning engine
+  assets/
+    example.json      # Template/example entries
+    security.json     # Security anti-patterns
+    database.json     # Database anti-patterns
+    api.json          # API anti-patterns
+```
+
+Each file is a JSON array. The reasoning engine loads and merges all `*.json`
+files from `assets/` at startup. Keep files organized by domain to avoid merge
+conflicts and improve discoverability.
+
+## Integration with Reasoning Engine
+
+The `search.py` reasoning engine uses registry entries as follows:
+
+1. **Load**: All JSON files in `assets/` are loaded and merged into a flat list.
+2. **Match**: User query is tokenized and scored against all fields.
+3. **Filter**: `conflicts_with` entries are excluded based on already-selected
+   items via `filter_anti_patterns()`.
+4. **Return**: Top results are returned as JSON to stdout.
+
+Skills that use this pattern should document the `--domain` flag to scope
+searches to their specific domain.

package/kb/reference/architecture-overview.md

@@ -0,0 +1,232 @@
+---
+title: "AI Toolkit - Architecture Overview"
+category: reference
+service: ai-toolkit
+tags: [architecture, overview, design, structure]
+version: "1.0.0"
+created: "2026-03-23"
+last_updated: "2026-04-02"
+description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
+---
+
+# AI Toolkit Architecture
+
+## Purpose
+
+Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, and Aider). Provides 47 specialized agents, 85 skills (slash commands + knowledge), expanded lifecycle hooks, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
+
+## Design Principles
+
+1. **Global install** — one `~/.claude/` install works for all projects; no per-project setup beyond `init`
+2. **Merge-friendly** — per-file symlinks, JSON merge, marker injection; user content never overwritten
+3. **Composable** — agents reference skills; skills invoke agents; hooks validate all work
+4. **Multi-language** — hooks and skills support Python, TypeScript, PHP, Dart, Go
+5. **Cost-optimized** — simpler agents run on `sonnet`, complex reasoning on `opus`
+
+## Directory Structure
+
+```
+ai-toolkit/
+  bin/
+    ai-toolkit.js        # CLI entry point (install, init, add-rule, ...)
+  app/                       # All toolkit components
+    agents/                  # 47 agent definitions (.md + YAML frontmatter)
+    skills/                  # 85 skills: task, hybrid, knowledge
+    rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
+    hooks/                   # Hook scripts (copied to ~/.ai-toolkit/hooks/)
+    hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
+    constitution.md          # Immutable safety rules, 5 articles (marker-injected)
+    ARCHITECTURE.md          # System architecture reference (marker-injected)
+    CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
+    settings.local.json.template
+    .claude-plugin/
+      plugin.json            # Official plugin manifest
+    plugins/                 # Experimental opt-in plugin packs + optional modules
+  scripts/                   # All scripts
+    install.py               # Global installer → ~/.claude/ (--local for project-local setup)
+    uninstall.py             # Removes toolkit components from ~/.claude/
+    inject_rule_cli.py       # Injects a rule into CLAUDE.md (delegates to inject_section_cli.py)
+    inject_section_cli.py    # Marker-based content injection (canonical implementation)
+    _common.py               # Shared helper for generators (frontmatter, agents/skills emission)
+    merge-hooks.py           # JSON merge for hooks into settings.json (inject/strip modes)
+    validate.py              # Toolkit integrity check
+    evaluate_skills.py       # Skill quality report
+    generate_agents_md.py    # Regenerates AGENTS.md
+    generate_cursor_rules.py # Generates .cursorrules (sources _common.py)
+    generate_windsurf.py     # Generates .windsurfrules (sources _common.py)
+    generate_copilot.py      # Generates .github/copilot-instructions.md (sources _common.py)
+    generate_gemini.py       # Generates GEMINI.md (sources _common.py)
+    generate_cline.py        # Generates .clinerules (sources _common.py)
+    generate_roo_modes.py    # Generates .roomodes
+    generate_aider_conf.py   # Generates .aider.conf.yml
+    generate_llms_txt.py     # Generates llms.txt
+    install_git_hooks.py     # Installs fallback pre-commit hook
+    plugin.py                # Plugin pack management (install, remove, list, status)
+    benchmark_ecosystem.py   # Generates ecosystem benchmark snapshot
+    harvest_ecosystem.py     # Writes machine-readable ecosystem harvest JSON
+  tests/                     # Bats test suite
+  benchmarks/                # Benchmark tasks + results
+  kb/                        # Knowledge base
+    reference/               # Catalogs, architecture, usage guides
+    procedures/              # SOPs (install, maintenance)
+    reference/               # architecture, operating models, and usage guides
+```
+
+## Install Model
+
+All components use merge-friendly strategies — user content is never overwritten.
+
+```
+Machine (global)                              Project (local)
+──────────────────────────────────────────    ──────────────────────────────────────
+~/.claude/                                    ~/.ai-toolkit/
+  agents/*.md    → per-file symlinks             rules/     ← registered rules
+  skills/*/      → per-dir symlinks              hooks/     ← hook scripts (copied)
+  settings.json  ← hooks merged here
+  constitution.md ← marker injection            my-project/
+  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project rules
+  CLAUDE.md       ← marker injection (rules)      .claude/
+                                                    settings.local.json  ← MCP, perms
+                                                    constitution.md     ← marker injection
+```
+
+| Component | Strategy | Collision handling |
+|-----------|----------|-------------------|
+| `agents/*.md` | Per-file symlinks | User file with same name wins (toolkit skipped) |
+| `skills/*/` | Per-directory symlinks | User dir with same name wins (toolkit skipped) |
+| `settings.json` hooks | JSON merge via `merge-hooks.py` | User hooks + settings preserved, toolkit entries tagged with `_source` |
+| `constitution.md` | Marker injection via `inject_section_cli.py` | User content outside `<!-- TOOLKIT:* -->` markers untouched |
+| `ARCHITECTURE.md` | Marker injection via `inject_section_cli.py` | Same as above |
+| `CLAUDE.md` | Marker injection via `inject_rule_cli.py` | Same as above |
+
+**`ai-toolkit install`** — run once per machine, merges toolkit into `~/.claude/`. Auto-upgrades old whole-directory symlinks.
+
+**`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
+
+**`ai-toolkit install --local`** (or `update --local`) — run per project, creates `CLAUDE.md` template + `.claude/settings.local.json` (only if missing, initialized with MCP defaults), and injects `constitution.md` + Copilot + Cline + Roo Code + Aider configs into local `.claude/` (preserves existing user content). Installs `--local` git hooks as a fallback for quality gates. Hooks are global-only — not merged into project settings.
+
+## CLI Commands
+
+| Command | Target | What it does |
+|---------|--------|-------------|
+| `install` | `~/.claude/` | First-time: per-file symlinks + JSON merge + marker injection + rules |
+| `install --local` | `./` | Also set up project-local: `CLAUDE.md` + `settings.local.json` + constitution + Copilot + Cline + Roo + Aider + Git Hooks (hooks stay global-only) |
+| `update` | `~/.claude/` | Re-apply after npm update or after add-rule/remove-rule |
+| `update --local` | `./` | Re-apply + refresh project-local configs |
+| `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
+| `add-rule <file>` | `~/.ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
+| `remove-rule <name>` | `~/.ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
+| `validate` | toolkit | Integrity check |
+| `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
+| `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
+| `evaluate` | toolkit | Skill quality report |
+| `cursor-rules` | `./` | Generates `.cursorrules` |
+| `windsurf-rules` | `./` | Generates `.windsurfrules` |
+| `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
+| `gemini-md` | `./` | Generates `GEMINI.md` |
+| `cline-rules` | `./` | Generates `.clinerules` |
+| `roo-modes` | `./` | Generates `.roomodes` |
+| `aider-conf` | `./` | Generates `.aider.conf.yml` |
+| `agents-md` | toolkit | Regenerates `AGENTS.md` |
+| `llms-txt` | `./` | Generates `llms.txt` |
+| `generate-all` | `./` | Generates all platform configs at once |
+
+## Skill Tiers
+
+Three tiers determine how to approach a task:
+
+| Tier | Skills | When to use |
+|------|--------|-------------|
+| **1 — Quick single-agent** | `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain` | One concern, one file area, fast |
+| **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with a known pattern |
+| **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
+
+### `/workflow` types (15)
+
+| Type | Use case |
+|------|----------|
+| `feature-development` | New feature, full stack |
+| `backend-feature` | Backend only: API + logic + tests |
+| `frontend-feature` | UI component + state + tests |
+| `api-design` | New API endpoint design → implement → document |
+| `database-evolution` | Schema change + migration + code update |
+| `test-coverage` | Boost test coverage for a module |
+| `security-audit` | Multi-vector security assessment |
+| `codebase-onboarding` | Understand unfamiliar codebase (read-only) |
+| `spike` | Time-boxed technical research → architecture note |
+| `debugging` | Bug spanning multiple layers |
+| `incident-response` | Production down |
+| `performance-optimization` | Degradation >50% |
+| `infrastructure-change` | Docker, CI/CD, infra |
+| `application-deploy` | Deploy |
+| `proactive-troubleshooting` | Warning / trend |
+
+## Skill Classification
+
+| Type | Field | Invocation | Count |
+|------|-------|-----------|-------|
+| Task | `disable-model-invocation: true` | User via `/skill` only | 27 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 27 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 31 |
+
+## Multi-Agent Execution
+
+Skills that spawn real parallel agents use:
+- `agent: <name>` — delegates to a specialized agent persona
+- `context: fork` — runs in isolated forked context
+- `Agent` tool — spawns subagents in parallel within the agent's response
+
+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
+
+## Component Relationships
+
+```
+Skills (/review, /deploy, /debug, ...)
+    │
+    ▼
+Agents (code-reviewer, debugger, devops-implementer, ...)
+    │
+    ├── load: knowledge skills (clean-code, typescript-patterns, ...)
+    │
+    ├── validated by: hooks in settings.json (SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, Stop, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd)
+    │
+    └── constrained by: constitution.md (5 safety articles)
+```
+
+## Quality Hooks
+
+| Hook | Trigger | Script | Action |
+|------|---------|--------|--------|
+| SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
+| PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
+| PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |
+| UserPromptSubmit | Before user prompt execution | `user-prompt-submit.sh` | Prompt governance reminder |
+| PostToolUse | After edit/write tools | `post-tool-use.sh` | Lightweight validation reminders |
+| Stop | After response | `quality-check.sh` | Multi-language lint |
+| Stop | After response | `save-session.sh` | Persist session context |
+| TaskCompleted | Agent Teams: task done | `quality-gate.sh` | Block completion on errors |
+| TeammateIdle | Agent Teams: idle | *(inline)* | Completeness reminder |
+| SubagentStart | Subagent spawn | `subagent-start.sh` | Scope reminder for subagents |
+| SubagentStop | Subagent completion | `subagent-stop.sh` | Handoff checklist for subagents |
+| PreCompact | Before compaction | `pre-compact.sh` | Save context before compaction |
+| SessionEnd | Session end | `session-end.sh` | Persist handoff note for the next session |
+
+Scripts at `~/.ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
+
+## Constitution (5 Articles)
+
+| Article | Key Rule |
+|---------|----------|
+| I Safety First | No data loss, no blind execution, max 3 loop iterations |
+| II Hierarchy of Truth | KB is source of truth, research protocol mandatory |
+| III Operational Integrity | Green tests = Done, logs are evidence |
+| IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
+| V Resource Governance | No destructive commands without confirmation |
+
+## Agent Model Tiers
+
+| Model | Purpose | Count |
+|-------|---------|-------|
+| opus | Complex reasoning, code generation, security | 32 |
+| sonnet | Documentation, analysis, pattern-following | 15 |

package/kb/reference/benchmark-config.md

@@ -0,0 +1,62 @@
+---
+title: "AI Toolkit - Config Benchmark"
+category: reference
+service: ai-toolkit
+tags: [benchmark, config, comparison, coverage]
+version: "1.0.0"
+created: "2026-03-29"
+last_updated: "2026-03-29"
+description: "Compare your installed ai-toolkit config vs toolkit defaults vs ecosystem competition."
+---
+
+# Config Benchmark
+
+## Usage
+
+```bash
+ai-toolkit benchmark --my-config
+```
+
+## What It Shows
+
+1. **Your Configuration** — counts of installed agents, skills, hooks in `~/.claude/`
+2. **Toolkit Totals** — counts of available assets in the toolkit package
+3. **Coverage** — percentage of toolkit assets you have installed
+4. **Missing Components** — up to 10 agents and skills not yet installed
+5. **Ecosystem Comparison** — your config vs public Claude Code ecosystem repos
+
+## Output Example
+
+```
+AI Toolkit Config Benchmark
+========================
+
+## Your Configuration (~/.claude/)
+  Agents:  47
+  Skills:  80
+  Hooks:   12
+
+## Toolkit Totals
+  Agents:  47
+  Skills:  80
+  Hooks:   12
+
+## Coverage
+  Agents:  100%  (47 / 47)
+  Skills:  100%  (80 / 80)
+  Hooks:   100%  (12 / 12)
+
+## Ecosystem Comparison
+Repo                                     Agents  Skills  Hooks
+--------------------------------------------------------------
+Your config                                  47      80     12
+--------------------------------------------------------------
+anthropics/claude-code                       15      10      5
+affaan-m/everything-claude-code             152     397      2
+```
+
+## Data Sources
+
+- User config: `~/.claude/agents/`, `~/.claude/skills/`, `~/.ai-toolkit/hooks/`
+- Toolkit: `app/agents/`, `app/skills/`, `app/hooks/`
+- Ecosystem: `benchmarks/ecosystem-dashboard.json`