@softspark/ai-toolkit 1.2.0 → 1.3.0

package/app/skills/council/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: council
+description: "4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'."
+user-invocable: true
+effort: high
+argument-hint: "[decision question or proposal to evaluate]"
+agent: orchestrator
+context: fork
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Decision Council
+
+$ARGUMENTS
+
+Evaluate a decision from 4 distinct perspectives using parallel sub-agents, then synthesize a weighted recommendation.
+
+## Usage
+
+```
+/council [decision question or proposal to evaluate]
+```
+
+## What This Command Does
+
+1. **Parses** the decision question from user input
+2. **Gathers** codebase context relevant to the decision
+3. **Spawns** 4 parallel sub-agents — each analyzing from a different perspective
+4. **Synthesizes** all perspectives into a structured recommendation with decision matrix
+
+## MANDATORY: You MUST use the Agent tool
+
+**DO NOT analyze the decision yourself.** Your job is to parse the question, spawn 4 sub-agents in parallel via the `Agent` tool, and synthesize their outputs. If you attempt to provide all perspectives inline, you have failed.
+
+## Process
+
+### 1. Parse the Decision
+
+Extract from the user's input:
+
+- **The proposal** — what is being considered
+- **The alternatives** — what the options are (if not stated, infer the implicit alternative: status quo)
+- **The context** — what project/codebase/situation this applies to
+
+If the question is too vague to evaluate, ask ONE clarifying question before proceeding.
+
+### 2. Gather Context
+
+Before spawning agents, quickly scan the codebase for relevant context:
+
+- Current tech stack, dependencies, patterns in use
+- Existing code related to the decision area
+- Configuration, infrastructure, or architectural choices already made
+
+Include this context in each sub-agent prompt so perspectives are grounded in reality.
+
+### 3. Spawn 4 Sub-Agents in Parallel (REQUIRED)
+
+Call the `Agent` tool **4 times in a single response** — all agents MUST launch in the same message to run in parallel.
+
+| Agent | Role | Directive |
+|-------|------|-----------|
+| **Advocate** | Case FOR | Present the strongest case FOR the proposal. Find evidence, benefits, success stories. Reference relevant code/patterns in the codebase. Be persuasive but honest. |
+| **Critic** | Case AGAINST | Present the strongest case AGAINST. Find risks, hidden costs, failure modes, alternatives that might be better. Be thorough but fair. |
+| **Pragmatist** | Trade-offs | Evaluate practical trade-offs: implementation cost, timeline, team capacity, maintenance burden, migration risk, operational complexity. Ground estimates in the actual codebase size and patterns. |
+| **User-Proxy** | User impact | Consider end-user and customer impact: UX changes, downtime during migration, performance implications, breaking changes, adoption friction, documentation needs. |
+
+Each agent prompt MUST include:
+
+1. The original decision question
+2. The codebase context gathered in step 2
+3. The specific perspective this agent owns
+4. Instruction to search the codebase for supporting evidence
+5. Constraint: 200-400 words, concrete evidence over abstract arguments
+
+### 4. Synthesize
+
+After all 4 agents complete, combine their outputs into the structured format below. Do NOT simply concatenate — identify agreements, contradictions, and conditional factors across perspectives.
+
+## Output Format
+
+```markdown
+## Decision Council: [Question]
+
+### Advocate (FOR)
+[Summary of arguments for — key benefits and evidence]
+
+### Critic (AGAINST)
+[Summary of arguments against — key risks and alternatives]
+
+### Pragmatist (TRADE-OFFS)
+[Practical considerations — cost, timeline, complexity]
+
+### User-Proxy (USER IMPACT)
+[End-user perspective — UX, performance, breaking changes]
+
+### Synthesis
+**Recommendation:** [FOR / AGAINST / CONDITIONAL]
+**Confidence:** [HIGH / MEDIUM / LOW]
+**Key condition:** [Primary factor that would change the recommendation]
+
+**Where perspectives agree:** [Common ground across agents]
+**Where perspectives conflict:** [Key disagreements and why]
+
+### Decision Matrix
+| Factor | Weight | FOR score (1-5) | AGAINST score (1-5) |
+|--------|--------|-----------------|---------------------|
+| Technical merit | [H/M/L] | [score] | [score] |
+| Risk | [H/M/L] | [score] | [score] |
+| Cost | [H/M/L] | [score] | [score] |
+| Timeline | [H/M/L] | [score] | [score] |
+| User impact | [H/M/L] | [score] | [score] |
+| **Weighted total** | | **[total]** | **[total]** |
+```
+
+## Rules
+
+- Each sub-agent must search the codebase for relevant evidence — no purely abstract arguments
+- Sub-agents must be honest within their role — the Advocate should acknowledge weaknesses, the Critic should acknowledge strengths
+- Keep each perspective to 200-400 words — density over length
+- The synthesis must add value beyond summarizing — identify the decisive factor
+- If the decision is clearly one-sided after analysis, say so — don't manufacture false balance
+
+## Anti-Patterns
+
+- Don't skip the codebase scan — ungrounded opinions are worthless
+- Don't let all 4 perspectives say the same thing — enforce distinct angles
+- Don't give a wishy-washy "it depends" synthesis — commit to a recommendation with conditions
+- Don't ignore the status quo — "do nothing" is always an alternative
+
+## READ-ONLY
+
+This skill evaluates decisions. It does NOT implement changes.

package/app/skills/introspect/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: introspect
+description: "Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing."
+user-invocable: true
+effort: low
+argument-hint: "[symptom or 'stuck']"
+agent: debugger
+context: fork
+allowed-tools: Read, Grep
+---
+
+# Agent Self-Debugging
+
+$ARGUMENTS
+
+Structured self-analysis for when the agent is stuck, looping, or producing degraded output.
+
+---
+
+## Step 1: Capture Failure State
+
+Before diagnosing, gather the facts. Answer each question concisely:
+
+| Question | Answer |
+|----------|--------|
+| **Last goal/task** | What was the agent trying to accomplish? |
+| **Actions taken** | List the last 3-5 actions in order |
+| **Errors or unexpected results** | What went wrong? What was expected vs actual? |
+| **Attempt count** | How many times has this been tried? |
+| **Time spent** | Rough estimate of effort so far |
+
+---
+
+## Step 2: Classify the Failure Pattern
+
+Identify which pattern matches the current situation:
+
+| Pattern | Symptoms | Common Cause |
+|---------|----------|--------------|
+| **Loop** | Same action repeated 3+ times | Missing exit condition, wrong approach |
+| **Drift** | Actions diverge from original goal | Lost context, scope creep |
+| **Assumption Error** | Working with wrong mental model | Didn't read code, assumed behavior |
+| **Tool Misuse** | Wrong tool for the job | Grep when should Read, Bash when should Edit |
+| **Context Overflow** | Forgetting earlier findings | Too much context, need compaction |
+| **Wrong Abstraction** | Over-engineering simple task | Premature abstraction, YAGNI violation |
+| **Missing Information** | Can't proceed without data | Need to ask user, read more code |
+
+Pick the **single best match**. If multiple apply, pick the root cause pattern (the one that, if fixed, would resolve the others).
+
+---
+
+## Step 3: Diagnose Root Cause
+
+Answer these three questions:
+
+1. **What assumption was wrong?** — Identify the specific belief that led to failure.
+2. **What information was missing?** — What would have prevented the failure if known earlier?
+3. **What would a fresh start look like?** — If starting over with current knowledge, what would the first action be?
+
+---
+
+## Step 4: Select Recovery Action
+
+Apply the **smallest possible fix** — do not restart from scratch unless absolutely necessary:
+
+| Pattern | Recovery Action |
+|---------|----------------|
+| **Loop** | Stop. Change approach entirely — different tool, different strategy, different angle. |
+| **Drift** | Re-read the original user request verbatim. Reset scope to exactly what was asked. |
+| **Assumption Error** | Read the actual code, file, or docs. Do not guess. Verify the mental model. |
+| **Tool Misuse** | Switch to the correct tool. Read instead of Grep for full context. Edit instead of Bash for file changes. |
+| **Context Overflow** | Summarize all findings so far in 5 bullet points. Compact and continue. |
+| **Wrong Abstraction** | Delete the abstraction. Do the simplest, most direct thing that works. |
+| **Missing Information** | Ask the user exactly ONE specific question. Do not guess. |
+
+---
+
+## Step 5: Produce the Introspection Report
+
+Output exactly this format:
+
+```markdown
+## Introspection Report
+
+**Pattern:** [Loop|Drift|Assumption Error|Tool Misuse|Context Overflow|Wrong Abstraction|Missing Information]
+**Root Cause:** [1-2 sentence diagnosis]
+**Recovery Action:** [Specific next step]
+**Confidence:** [HIGH|MEDIUM|LOW]
+
+### What happened
+[Brief timeline of actions taken — 3-5 bullet points max]
+
+### What went wrong
+[Specific diagnosis — what assumption failed, what was missed]
+
+### What to do next
+[ONE concrete action — not a plan, a single next step]
+```
+
+---
+
+## Self-Correction Rules
+
+These rules are non-negotiable during recovery:
+
+1. **Never retry the exact same action.** If it failed once, it will fail again. Change something.
+2. **Never continue a loop "hoping it will work this time."** Hope is not a strategy.
+3. **Prefer reading code over guessing behavior.** Open the file. Read the function. Check the types.
+4. **When in doubt, ask the user** rather than making assumptions. One specific question beats three wrong guesses.
+5. **A 2-line fix is better than a 50-line refactor.** Solve the immediate problem first.
+6. **Check if the goal is still correct** before optimizing the approach. Sometimes the task itself needs clarification.
+7. **If stuck for more than 3 attempts, escalate.** Tell the user what you tried, what failed, and what you need.
+
+---
+
+## Quick Self-Check (Use Before Retrying Anything)
+
+Before taking the next action after introspection, answer:
+
+- [ ] Is this action **different** from what I already tried?
+- [ ] Am I working on the **original goal**, not a tangent?
+- [ ] Do I have **enough information** to succeed, or am I guessing?
+- [ ] Is this the **simplest** approach that could work?
+
+If any answer is "no", stop and address that first.

package/bin/ai-toolkit.js

@@ -35,7 +35,6 @@ const GENERATORS = {
  */
 const SCRIPT_COMMANDS = {
   'install':              { script: 'install.py' },
-  'update':               { script: 'install.py' },
   'uninstall':            { script: 'uninstall.py' },
   'validate':             { script: 'validate.py',           toolkitCwd: true },
   'doctor':               { script: 'doctor.py',             toolkitCwd: true },
@@ -52,11 +51,14 @@ const SCRIPT_COMMANDS = {
 /** @type {Record<string, string>} */
 const COMMANDS = {
   install: 'First-time global install into ~/.claude/ (use --local to also set up project configs)',
-  update: 'Re-apply toolkit after npm update (use --local to also refresh project configs)',
+  update: 'Re-apply toolkit with saved modules from state.json (use --local to also refresh project configs)',
+  status: 'Show installed modules, version, and profile from state.json',
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
   'add-rule': 'Register a rule file in ~/.ai-toolkit/rules/ (applied on every install/update)',
   'remove-rule': 'Unregister a rule from ~/.ai-toolkit/rules/ and remove its block from CLAUDE.md',
+  'inject-hook': 'Inject external hooks into ~/.claude/settings.json (tagged with _source for idempotent updates)',
+  'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json',
   validate: 'Verify toolkit integrity',
   doctor: 'Check install health, hooks, and artifact drift',
   eject: 'Export standalone config (no symlinks, no toolkit dependency)',
@@ -65,6 +67,7 @@ const COMMANDS = {
   evaluate: 'Run skill evaluation suite',
   stats: 'Show skill usage statistics (--reset to clear, --json for raw output)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
+  mcp: 'Manage MCP server templates (list, show, add, remove)',
   plugin: 'Manage plugin packs (install, remove, update, clean, list, status)',
   sync: 'Sync config to/from GitHub Gist (--export, --push, --pull, --import)',
   'cursor-rules': 'Generate .cursorrules for Cursor IDE',
@@ -180,6 +183,8 @@ function showHelp() {
   console.log('  --skip <list>   Skip listed components');
   console.log('  --local         Also set up project-local configs (CLAUDE.md, settings, constitution, copilot, cline, roo, aider, git hooks)');
   console.log('  --profile <p>   Install profile: minimal (agents+skills), standard (default), strict (all+git hooks)');
+  console.log('  --modules <list>  Install specific modules (e.g. core,agents,rules-typescript)');
+  console.log('  --auto-detect   Detect project languages and install matching rule modules');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
   console.log('\nOptions for create:');
   console.log('  skill <name> --template=<type>  Scaffold skill (types: linter, reviewer, generator, workflow, knowledge)');
@@ -194,6 +199,12 @@ function showHelp() {
   console.log('\nOptions for remove-rule:');
   console.log('  <rule-name>     Name of rule to unregister (filename without .md)');
   console.log('  [target-dir]    Target dir containing .claude/CLAUDE.md (default: $HOME)');
+  console.log('\nOptions for inject-hook:');
+  console.log('  <hooks-file>    Path to JSON file with {"hooks": {"EventName": [...]}} format');
+  console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
+  console.log('\nOptions for remove-hook:');
+  console.log('  <source-name>   Source tag to remove (derived from hooks filename stem)');
+  console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
   console.log('  <rule-file>     Path to .md rule file to register globally');
   console.log('  [rule-name]     Override rule name (default: filename without .md)');
@@ -207,6 +218,11 @@ function showHelp() {
   console.log('  remove --all    Remove all installed plugins');
   console.log('  list            Show available plugin packs with install status');
   console.log('  status          Show currently installed plugins with data stats');
+  console.log('\nOptions for mcp:');
+  console.log('  list                          List available MCP templates');
+  console.log('  show <name>                   Show template details');
+  console.log('  add <name> [names..] [--target <path>]  Add servers to .mcp.json');
+  console.log('  remove <name>                 Remove a server from .mcp.json');
   console.log('\nOptions for doctor:');
   console.log('  --fix           Auto-repair detected issues');
   console.log('\nOptions for eject:');
@@ -300,6 +316,47 @@ function handleAddRule(args) {
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);
 }
 
+/**
+ * Handle `ai-toolkit inject-hook` -- injects external hooks into settings.json.
+ * @param {string[]} args
+ */
+function handleInjectHook(args) {
+  const hooksFile = args[0];
+  if (!hooksFile) {
+    console.error('Usage: ai-toolkit inject-hook <hooks-file.json> [target-dir]');
+    process.exit(1);
+  }
+  const absHooksFile = path.resolve(CWD, hooksFile);
+  const targetDir = args[1] || process.env.HOME;
+  run(scriptPath('inject_hook_cli.py'), [absHooksFile, targetDir]);
+}
+
+/**
+ * Handle `ai-toolkit remove-hook` -- removes injected hooks by source name.
+ * @param {string[]} args
+ */
+function handleRemoveHook(args) {
+  const sourceName = args[0];
+  if (!sourceName) {
+    console.error('Usage: ai-toolkit remove-hook <hook-source-name> [target-dir]');
+    process.exit(1);
+  }
+  const targetDir = args[1] || process.env.HOME;
+  run(scriptPath('inject_hook_cli.py'), ['--remove', sourceName, targetDir]);
+}
+
+/**
+ * Handle `ai-toolkit mcp` -- delegates to mcp_manager.py with subcommand.
+ * @param {string[]} args
+ */
+function handleMcp(args) {
+  if (args.length === 0) {
+    console.error('Usage: ai-toolkit mcp <list|show|add|remove> [args..]');
+    process.exit(1);
+  }
+  run(scriptPath('mcp_manager.py'), args);
+}
+
 /**
  * Handle `ai-toolkit generate-all` -- runs every generator plus llms-txt.
  * @param {string[]} _args - Unused, kept for signature consistency
@@ -311,15 +368,59 @@ function handleGenerateAll(_args) {
   generateLlmsTxt();
 }
 
+/**
+ * Handle `ai-toolkit status` -- shows installed modules from state.json.
+ * @param {string[]} _args
+ */
+function handleStatus(_args) {
+  run(scriptPath('install.py'), ['--status']);
+}
+
+/**
+ * Handle `ai-toolkit update` -- re-runs install with saved state.
+ * Reads state.json to find previously installed modules and profile,
+ * then re-runs install.py with those flags to perform an incremental update.
+ * @param {string[]} args
+ */
+function handleUpdate(args) {
+  const statePath = path.join(process.env.HOME, '.ai-toolkit', 'state.json');
+  let stateArgs = [];
+
+  if (fs.existsSync(statePath)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      const modules = state.installed_modules;
+      const profile = state.profile;
+
+      // If we have recorded modules, pass them to install.py
+      if (Array.isArray(modules) && modules.length > 0) {
+        stateArgs.push('--modules', modules.join(','));
+      } else if (profile) {
+        stateArgs.push('--profile', profile);
+      }
+    } catch (_err) {
+      // State file is corrupt or unreadable -- fall through to plain install
+    }
+  }
+
+  // User-provided args override state-derived args
+  run(scriptPath('install.py'), [...stateArgs, ...args]);
+}
+
 /** @type {Record<string, (args: string[]) => void>} */
 const SPECIAL_HANDLERS = {
+  'status':       handleStatus,
+  'update':       handleUpdate,
   'reset':        handleReset,
   'benchmark':    handleBenchmark,
   'create':       handleCreate,
   'sync':         handleSync,
+  'mcp':          handleMcp,
   'plugin':       (args) => run(scriptPath('plugin.py'), args),
   'remove-rule':  handleRemoveRule,
   'add-rule':     handleAddRule,
+  'inject-hook':  handleInjectHook,
+  'remove-hook':  handleRemoveHook,
   'llms-txt':     (_args) => generateLlmsTxt(),
   'generate-all': handleGenerateAll,
 };

package/kb/reference/agents-catalog.md

@@ -6,10 +6,10 @@ 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."
+description: "Complete catalog of 44 specialized agents with roles, models, and use cases."
 ---
 
-# Agents Catalog (47 agents)
+# Agents Catalog (44 agents)
 
 ## By Category
 
@@ -32,17 +32,16 @@ description: "Complete catalog of 47 specialized agents with roles, models, and
 | **game-developer** | opus | Unity, Godot, Unreal, Phaser, Three.js |
 | **database-architect** | opus | Schema design, migrations, query optimization, operations |
 
-### AI/ML (7)
+### AI/ML (6)
 
 | Agent | Model | Use Case |
 |-------|-------|----------|
-| **ai-engineer** | opus | LLM integration, vector databases, RAG, agent orchestration |
+| **ai-engineer** | opus | LLM integration, vector databases, RAG pipelines, 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)
 
@@ -66,23 +65,21 @@ description: "Complete catalog of 47 specialized agents with roles, models, and
 | **performance-optimizer** | opus | Profiling, bottleneck analysis, latency, scaling |
 | **llm-ops-engineer** | opus | LLM caching, fallback, cost optimization, observability |
 
-### Research & Documentation (6)
+### Research & Documentation (5)
 
 | 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 |
+| **technical-researcher** | opus | Deep technical investigation, research synthesis |
 | **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)
+### MCP (2)
 
 | Agent | Model | Use Case |
 |-------|-------|----------|
-| **mcp-expert** | opus | MCP protocol expertise, client configuration |
-| **mcp-server-architect** | opus | MCP server design, JSON-RPC, tool definitions |
+| **mcp-specialist** | opus | MCP server design, client config, troubleshooting |
 | **mcp-testing-engineer** | sonnet | MCP protocol compliance, transport testing |
 
 ### Management & Evolution (4)
@@ -120,5 +117,5 @@ description: "Complete catalog of 47 specialized agents with roles, models, and
 | 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 |
+| AI/ML | ai-engineer | ml-engineer | data-scientist |
+| Research | technical-researcher | search-specialist | fact-checker |

package/kb/reference/architecture-overview.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [architecture, overview, design, structure]
 version: "1.0.0"
 created: "2026-03-23"
-last_updated: "2026-04-02"
+last_updated: "2026-04-07"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
 ---
 
@@ -13,7 +13,7 @@ description: "Architecture of ai-toolkit: directory layout, global install model
 
 ## Purpose
 
-Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment). Provides 47 specialized agents, 87 skills (slash commands + knowledge), expanded lifecycle hooks, persona presets, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
+Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment). Provides 44 specialized agents, 90 skills (slash commands + knowledge), expanded lifecycle hooks, persona presets, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
 
 ## Design Principles
 
@@ -30,8 +30,8 @@ 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/                  # 87 skills: task, hybrid, knowledge
+    agents/                  # 44 agent definitions (.md + YAML frontmatter)
+    skills/                  # 90 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)
@@ -166,8 +166,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 28 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 28 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 31 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 32 |
 
 ## Multi-Agent Execution
 
@@ -195,14 +195,22 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
+21 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|
 | SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
+| SessionStart | Session start | `session-context.sh` | Capture environment snapshot |
 | 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 |
+| PreToolUse | Before Edit/Write/MultiEdit | `guard-config.sh` | Block config file edits without explicit acknowledgment |
+| PreToolUse | Before Bash (git commit) | `commit-quality.sh` | Advisory Conventional Commits format check |
 | UserPromptSubmit | Before user prompt execution | `user-prompt-submit.sh` | Prompt governance reminder |
+| UserPromptSubmit | Before user prompt execution | `track-usage.sh` | Record skill invocations to stats.json |
 | PostToolUse | After edit/write tools | `post-tool-use.sh` | Lightweight validation reminders |
+| PostToolUse | After any tool | `governance-capture.sh` | Log security-sensitive operations |
 | 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 |
@@ -210,6 +218,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | 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 prioritized context: instincts > tasks > git state > decisions |
+| PreCompact | Before compaction | `pre-compact-save.sh` | Timestamped context snapshot to audit trail |
 | 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.
@@ -253,3 +262,17 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 |-------|---------|-------|
 | opus | Complex reasoning, code generation, security | 32 |
 | sonnet | Documentation, analysis, pattern-following | 15 |
+
+## Extension Points
+
+### MCP Templates
+`app/plugins/mcp-templates/` contains 25 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+
+### Language Rules
+`app/rules/` provides 70 rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`.
+
+### Extension API (`inject-hook`)
+`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content.
+
+### Manifest Install (`--modules`, `--auto-detect`)
+`manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or enable auto-detection to select language rules based on files found in the project.

package/kb/reference/commands-catalog.md

@@ -13,9 +13,9 @@ description: "DEPRECATED: All slash commands are implemented as skills. See skil
 
 All slash commands have been migrated to skills.
 
-See **[Skills Catalog](skills-catalog.md)** for the complete list of 85 skills, including:
-- **27 Task Skills** — formerly standalone commands and creator workflows (e.g., `/commit`, `/test`, `/deploy`, `/hook-creator`, `/plugin-creator`)
-- **27 Hybrid Skills** — slash commands that also provide agent knowledge (e.g., `/review`, `/debug`, `/plan`, `/tdd`, `/write-a-prd`)
-- **31 Knowledge Skills** — domain patterns auto-loaded by agents
+See **[Skills Catalog](skills-catalog.md)** for the complete list of 90 skills, including:
+- **28 Task Skills** — formerly standalone commands and creator workflows (e.g., `/commit`, `/test`, `/deploy`, `/hook-creator`, `/plugin-creator`)
+- **30 Hybrid Skills** — slash commands that also provide agent knowledge (e.g., `/review`, `/debug`, `/plan`, `/tdd`, `/write-a-prd`, `/council`, `/introspect`)
+- **32 Knowledge Skills** — domain patterns auto-loaded by agents (e.g., `brand-voice`, `clean-code`, `testing-patterns`)
 
 Slash command syntax (`/command`) continues to work. The underlying implementation moved from `app/commands/` to `app/skills/`.