@softspark/ai-toolkit 1.2.0 → 1.3.0

package/AGENTS.md

@@ -36,7 +36,7 @@ gemini --system "$(cat .claude/agents/backend-specialist.md)" "implement the API
 
 ### `ai-engineer`
 
-AI/ML integration specialist. Use for LLM integration, vector databases, RAG pipelines, embeddings, and AI agent orchestration. Triggers: ai, ml, llm, embedding, vector, rag, agent, openai, anthropic.
+AI/ML integration specialist. Use for LLM integration, vector databases, RAG pipelines, embeddings, AI agent orchestration, document indexing, semantic search, hybrid retrieval, and answer generation. Triggers: ai, ml, llm, embedding, vector, rag, agent, openai, anthropic, search, retrieval, indexing, chunking, reranking.
 
 **Tools:** `Read, Write, Edit, Bash, Grep, Glob`
 
@@ -210,19 +210,11 @@ LLM operations expert. Use for LLM caching, fallback strategies, cost optimizati
 
 ---
 
-### `mcp-expert`
+### `mcp-specialist`
 
-MCP integration expert. Use for configuring MCP clients, integrations, troubleshooting MCP connections. Triggers: mcp config, mcp integration, mcp connection, claude desktop, mcp client.
+MCP server design, implementation, client configuration, and integration troubleshooting. Triggers: mcp, model context protocol, json-rpc, sse, stdio, mcp server, mcp config, mcp integration, mcp connection, claude desktop, mcp client.
 
-**Tools:** `Read, Write, Edit, Bash`
-
----
-
-### `mcp-server-architect`
-
-MCP server design and implementation expert. Use for creating MCP servers, JSON-RPC transport, tool definitions, protocol compliance. Triggers: mcp, model context protocol, json-rpc, sse, stdio, mcp server.
-
-**Tools:** `Read, Write, Edit, Bash`
+**Tools:** `Read, Write, Edit, Bash, Grep, Glob`
 
 ---
 
@@ -330,22 +322,6 @@ Test automation and QA specialist. Use for E2E testing, API testing, performance
 
 ---
 
-### `rag-engineer`
-
-RAG systems expert. Use for document indexing, semantic search, hybrid retrieval, CRAG, multi-hop reasoning, and answer generation. Triggers: rag, search, retrieval, indexing, embedding, vector, chunking, reranking.
-
-**Tools:** `Read, Write, Edit, Bash`
-
----
-
-### `research-synthesizer`
-
-Multi-source research coordination and synthesis specialist. Trigger words: synthesize, aggregate, report, executive summary, gap analysis, conflict resolution, findings, research, investigate, multi-source, cross-reference, research planning
-
-**Tools:** `Read, Write, Edit, Bash, Grep, Glob`
-
----
-
 ### `search-specialist`
 
 Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
@@ -396,7 +372,7 @@ Technical authority for code quality, architecture patterns, and stack decisions
 
 ### `technical-researcher`
 
-Deep technical investigation specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix
+Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
 
 **Tools:** `Read, Write, Edit, Bash, Grep, Glob`
 

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.0 — Competitive Features Release (2026-04-07)
+
+### Added
+- **Language Rules System**: 70 language-specific coding rules across 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby) + 5 common rules. 5 categories per language: coding-style, testing, patterns, frameworks, security.
+- **MCP Templates**: 25 ready-to-use MCP server configuration templates (GitHub, PostgreSQL, Slack, Sentry, Context7, etc.) with CLI management (`ai-toolkit mcp add/list/show/remove`).
+- **Extension API**: `inject-hook` / `remove-hook` commands for external tools to inject hooks into settings.json with unique `_source` tags. Parallels existing `inject-rule` / `remove-rule`.
+- **Manifest-Driven Install**: Module-level install granularity (`--modules`), language auto-detection (`--auto-detect`), install state tracking (`~/.ai-toolkit/state.json`), `status` and `update` commands.
+- **6 new hooks**: `guard-config.sh` (config file protection), `mcp-health.sh` (MCP server health check), `governance-capture.sh` (security audit logging), `commit-quality.sh` (conventional commits advisory), `session-context.sh` (environment snapshot), `pre-compact-save.sh` (pre-compaction backup).
+- **`/council` skill**: 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) for architectural decisions.
+- **`/introspect` skill**: Agent self-debugging with 7 failure pattern classification and recovery actions.
+- **`brand-voice` knowledge skill**: Anti-trope list preventing generic LLM rhetoric, auto-loaded when writing documentation.
+- **KB reference docs**: extension-api.md, language-rules.md, mcp-templates.md, manifest-install.md.
+
+### Changed
+- Agent count: 47 → 44 (merged 3 overlapping pairs: rag-engineer into ai-engineer, research-synthesizer into technical-researcher, mcp-expert + mcp-server-architect into mcp-specialist)
+- Hook count: 14 → 20 global hooks across 12 lifecycle events
+- Skill count: 87 → 90 (28 task + 30 hybrid + 32 knowledge)
+- Updated hooks-catalog.md, skills-catalog.md with new entries
+
+---
+
+## [1.2.1] - 2026-04-03
+
+### Changed
+- **README.md** — added full documentation for all v1.2.0 features:
+  - `/persona` runtime switching with usage examples
+  - `audit_skills.py` CI pipeline integration with `--json` and `--ci` flags
+  - Skill Security Auditing section (severity levels, detection patterns)
+  - Persona Presets section (table with focus areas and key skills per role)
+  - Smart compaction description in hooks table
+  - Fixed section numbering (was duplicated at 4, skipped 10)
+- **CLAUDE.md** — added CRITICAL note: documentation/count accuracy is non-negotiable, must run validate + audit before every commit
+- **skills-catalog.md** — fixed stale frontmatter (was 85 skills/v1.0.0, now 87 skills/v1.2.1)
+- Version bump: 1.2.0 → 1.2.1 (package.json, plugin.json)
+
+[1.2.1]: https://github.com/softspark/ai-toolkit/releases/tag/v1.2.1
+
+---
+
 ## [1.2.0] - 2026-04-03
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 87 skills, 47 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 90 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-87-brightgreen)](app/skills/)
-[![Agents](https://img.shields.io/badge/agents-47-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-310%20passing-success)](tests/)
+[![Skills](https://img.shields.io/badge/skills-90-brightgreen)](app/skills/)
+[![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
+[![Tests](https://img.shields.io/badge/tests-327%20passing-success)](tests/)
 
 ---
 
@@ -21,7 +21,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 87 skills, 47 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 90 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 ### Update
 
@@ -61,7 +61,9 @@ ai-toolkit install --profile strict     # full install + git hooks even without
 
 ### Persona Presets
 
-Inject role-specific communication style and skill preferences:
+Personas adjust communication style, preferred skills, and code review priorities per engineering role.
+
+**Install-time (persistent — injected into CLAUDE.md):**
 
 ```bash
 ai-toolkit install --persona backend-lead    # system design, API stability, data integrity
@@ -70,6 +72,14 @@ ai-toolkit install --persona devops-eng      # infra-as-code, CI/CD, rollback sa
 ai-toolkit install --persona junior-dev      # step-by-step explanations, learning focus
 ```
 
+**Runtime (session-scoped — no reinstall needed):**
+
+```bash
+/persona backend-lead     # activate for this session
+/persona --list           # show available personas
+/persona --clear          # reset to default
+```
+
 ### Selective Install / Update
 
 ```bash
@@ -123,10 +133,10 @@ Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies cons
 | Component | Count | Description |
 |-----------|-------|-------------|
 | `skills/` (task) | 28 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
-| `skills/` (hybrid) | 28 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 31 | Domain knowledge auto-loaded by agents |
-| `agents/` | 47 | Specialized agents across 10 categories |
-| `hooks/` | 15 global + 5 skill-scoped | Quality gates, path safety, CLAUDE.md enforcement, notifications, prompt governance, subagent lifecycle, session-end handoff, usage tracking |
+| `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
+| `skills/` (knowledge) | 32 | Domain knowledge auto-loaded by agents |
+| `agents/` | 44 | Specialized agents across 10 categories |
+| `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, CLAUDE.md enforcement, notifications, prompt governance, subagent lifecycle, session-end handoff, usage tracking, config protection, MCP health, governance audit |
 | `plugins/` | 11 experimental opt-in packs | Domain bundles for security, research, frontend, enterprise, and 6 language packs (not part of the default install) |
 | `output-styles/` | 1 style | System prompt output style overrides (e.g. Golden Rules) |
 | `constitution.md` | 5 articles | Machine-enforced safety rules |
@@ -140,21 +150,22 @@ Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies cons
 ```
 ai-toolkit/
 ├── app/
-│   ├── agents/          # 47 agent definitions
+│   ├── agents/          # 44 agent definitions
 │   │   ├── orchestrator.md
 │   │   ├── backend-specialist.md
 │   │   ├── security-architect.md
-│   │   └── ... (44 more)
-│   ├── skills/          # 87 skills (task / hybrid / knowledge)
+│   │   └── ... (41 more)
+│   ├── skills/          # 90 skills (task / hybrid / knowledge)
 │   │   ├── commit/      # /commit slash command
 │   │   ├── review/      # /review slash command
 │   │   ├── clean-code/  # knowledge skill (auto-loaded)
-│   │   └── ... (82 more)
+│   │   └── ... (87 more)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
 │   ├── hooks/           # Hook scripts (copied to ~/.ai-toolkit/hooks/)
 │   │   ├── session-start.sh      # MANDATORY reminder + session context
 │   │   ├── guard-destructive.sh  # Block rm -rf, DROP TABLE, etc.
 │   │   ├── guard-path.sh         # Block wrong-user path hallucination
+│   │   ├── guard-config.sh       # Block edits to linter/formatter configs
 │   │   ├── user-prompt-submit.sh # Prompt governance reminder
 │   │   ├── quality-check.sh      # Multi-language lint on stop
 │   │   ├── quality-gate.sh       # Block task completion on errors
@@ -162,8 +173,13 @@ ai-toolkit/
 │   │   ├── subagent-start.sh     # Subagent scope reminder
 │   │   ├── subagent-stop.sh      # Subagent completion checklist
 │   │   ├── pre-compact.sh        # Save context before compaction
+│   │   ├── pre-compact-save.sh   # Timestamped backup before compaction
 │   │   ├── session-end.sh        # Session handoff snapshot
-│   │   └── post-tool-use.sh      # Lightweight feedback after edits
+│   │   ├── post-tool-use.sh      # Lightweight feedback after edits
+│   │   ├── mcp-health.sh         # MCP server availability check
+│   │   ├── governance-capture.sh # Security-sensitive op logging
+│   │   ├── commit-quality.sh     # Conventional commit advisory
+│   │   └── session-context.sh    # Environment snapshot on start
 │   ├── hooks.json       # Hook definitions (merged into settings.json)
 │   ├── plugins/         # Experimental plugin packs (opt-in, not part of default install)
 │   ├── output-styles/   # System prompt output style overrides
@@ -224,6 +240,9 @@ ai-toolkit/
 | `/subagent-development` | Execute plans with 2-stage review (spec + quality) per task | high |
 | `/repeat` | Autonomous loop with safety controls (Ralph Wiggum pattern) | medium |
 | `/mem-search` | Search past coding sessions via natural language (memory-pack) | medium |
+| `/persona` | Switch engineering persona at runtime (session-scoped) | low |
+| `/council` | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) | high |
+| `/introspect` | Agent self-debugging with 7 failure pattern classification and recovery actions | medium |
 
 ### `/workflow` Types
 
@@ -245,6 +264,17 @@ ai-toolkit/
 /workflow proactive-troubleshooting  # Warning / trend analysis
 ```
 
+### Multi-Agent Skill Selection
+
+```
+Need multi-agent coordination?
+├── Know your domains? → /orchestrate (ad-hoc, 3-6 agents)
+├── Have a known pattern? → /workflow <type> (15 templates)
+├── Need consensus/map-reduce? → /swarm <mode>
+├── Want Agent Teams API? → /teams (experimental)
+└── Executing a plan? → /subagent-development
+```
+
 ---
 
 ## Unique Differentiators
@@ -260,23 +290,29 @@ Unlike other toolkits that put safety rules in documentation only, ai-toolkit en
 
 Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
 
-**12 lifecycle events / 15 global hook entries:**
+**12 lifecycle events / 21 global hook entries:**
 
 | Event | Script | Action |
 |-------|--------|--------|
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
+| SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
+| SessionStart | `session-context.sh` | Capture environment snapshot (pwd, git branch, versions) to `~/.ai-toolkit/sessions/current-context.json` |
 | Notification | *(inline)* | macOS desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
+| PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
+| PreToolUse | `commit-quality.sh` | Advisory validation of git commit messages (conventional commits, length, no WIP) |
 | UserPromptSubmit | `user-prompt-submit.sh` | Prompt governance reminder for planning, research, and safe execution |
 | UserPromptSubmit | `track-usage.sh` | Record skill invocations to local stats |
 | PostToolUse | `post-tool-use.sh` | Lightweight validation reminders after edits |
+| PostToolUse | `governance-capture.sh` | Log security-sensitive operations to `~/.ai-toolkit/governance.log` (JSONL) |
 | Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
 | Stop | `save-session.sh` | Persist session context for cross-session continuity |
 | TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
 | SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
 | SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |
-| PreCompact | `pre-compact.sh` | Preserve context and instincts before compaction |
+| PreCompact | `pre-compact.sh` | Smart compaction: prioritized context (instincts > tasks > git state > decisions) |
+| PreCompact | `pre-compact-save.sh` | Save timestamped context backup before compaction to `~/.ai-toolkit/compactions/` |
 | SessionEnd | `session-end.sh` | Persist a session-end handoff note |
 | TeammateIdle | *(inline)* | Completeness reminder |
 
@@ -290,7 +326,29 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | `/migrate` | Pre | Backup verification |
 | `/rollback` | Post | State verification |
 
-### 3. Effort-Based Model Budgeting
+### 3. Skill Security Auditing
+
+Scan all skills and agents for security risks — both interactively and in CI:
+
+```bash
+# Interactive (Claude provides remediation suggestions)
+/skill-audit
+
+# Deterministic Python scanner for CI pipelines
+python3 scripts/audit_skills.py           # human-readable report
+python3 scripts/audit_skills.py --json    # machine-readable JSON
+python3 scripts/audit_skills.py --ci      # exit 1 on any HIGH finding
+```
+
+**What it detects:**
+- Dangerous code: `eval()`, `exec()`, `subprocess(shell=True)`, `pickle.loads`
+- Hardcoded secrets: AWS keys, GitHub PATs, private keys, API tokens
+- Permission issues: knowledge skills with Bash, missing `allowed-tools`
+- Bash risks: `curl | bash`, `chmod 777`, unquoted variables
+
+**Severity levels:** HIGH (blocks CI), WARN (should fix), INFO (review)
+
+### 4. Effort-Based Model Budgeting
 
 Every skill declares an effort level used for model token budgeting:
 - `low` — lint, build, fix (fast, cheap)
@@ -298,7 +356,7 @@ Every skill declares an effort level used for model token budgeting:
 - `high` — review, plan, refactor, docs
 - `max` — orchestrate, swarm, workflow
 
-### 4. Multi-Language Quality Gates
+### 5. Multi-Language Quality Gates
 
 The `Stop` hook runs after every response across 5 languages:
 
@@ -310,7 +368,7 @@ The `Stop` hook runs after every response across 5 languages:
 | Dart | dart analyze | dart analyze |
 | Go | go vet | go vet |
 
-### 5. Iron Law Enforcement
+### 6. Iron Law Enforcement
 
 Three skills enforce non-negotiable quality gates with anti-rationalization tables:
 
@@ -320,7 +378,7 @@ Three skills enforce non-negotiable quality gates with anti-rationalization tabl
 | `debugging-tactics` | `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST` | 4-phase debugging: root cause → pattern → hypothesis → fix. 3+ failed fixes → question architecture. |
 | `verification-before-completion` | `NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE` | Gate function: IDENTIFY → RUN → READ → VERIFY → CLAIM. "Should work now" is not evidence. |
 
-### 6. Two-Stage Review (`/subagent-development`)
+### 7. Two-Stage Review (`/subagent-development`)
 
 Per-task review pipeline inspired by [obra/superpowers](https://github.com/obra/superpowers):
 
@@ -333,7 +391,7 @@ Implementer → Spec Compliance Review → Code Quality Review → Next Task
 - Quality reviewer checks: SOLID, naming, error handling, tests, security
 - Prompt templates included: `reference/implementer-prompt.md`, `spec-reviewer-prompt.md`, `code-quality-reviewer-prompt.md`
 
-### 7. Ralph Wiggum Loop (`/repeat`)
+### 8. Ralph Wiggum Loop (`/repeat`)
 
 Autonomous agent loop with safety controls:
 
@@ -352,7 +410,7 @@ Autonomous agent loop with safety controls:
 
 Constitution Article I, Section 4 enforces these limits.
 
-### 8. Visual Brainstorming Companion
+### 9. Visual Brainstorming Companion
 
 Optional browser-based companion for `/write-a-prd` and `/design-an-interface`:
 
@@ -361,7 +419,7 @@ Optional browser-based companion for `/write-a-prd` and `/design-an-interface`:
 - Per-question routing: mockups/diagrams → browser, text/conceptual → terminal
 - Consent-based: offered once as its own message, never forced
 
-### 9. Persistent Memory (`memory-pack` plugin)
+### 10. Persistent Memory (`memory-pack` plugin)
 
 SQLite-based session memory (opt-in plugin pack):
 
@@ -375,7 +433,20 @@ SQLite-based session memory (opt-in plugin pack):
 
 
 
-### 11. KB Integration Protocol
+### 11. Persona Presets
+
+4 engineering personas that adjust Claude's communication style per role:
+
+| Persona | Focus | Key Skills |
+|---------|-------|------------|
+| `backend-lead` | System design, scalability, data integrity | `/workflow backend-feature`, `/tdd` |
+| `frontend-lead` | Component architecture, a11y, Core Web Vitals | `/design-an-interface`, `/review` |
+| `devops-eng` | IaC, CI/CD, blast radius, rollback safety | `/workflow infrastructure-change`, `/deploy` |
+| `junior-dev` | Step-by-step explanations, learning focus | `/explain`, `/explore`, `/debug` |
+
+Persistent via `--persona` at install time, or session-scoped via `/persona` runtime command.
+
+### 12. KB Integration Protocol
 
 Agents follow a research-before-action protocol enforced via rules:
 1. `smart_query()` or `hybrid_search_kb()` before any technical answer
@@ -384,6 +455,67 @@ Agents follow a research-before-action protocol enforced via rules:
 
 ---
 
+## MCP Templates
+
+25 ready-to-use MCP server configuration templates. Install any with a single command:
+
+```bash
+ai-toolkit mcp add github slack           # add GitHub + Slack MCP servers
+ai-toolkit mcp list                       # browse all 25 templates
+ai-toolkit mcp show postgres              # inspect config before adding
+```
+
+Templates include: GitHub, PostgreSQL, Slack, Sentry, Context7, Brave Search, Supabase, Cloudflare, Vercel, and 16 more. Each is a validated JSON config fragment merged into `.mcp.json`.
+
+---
+
+## Language Rules
+
+70 language-specific coding rules across 13 languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, plus 5 common rules. Each language has 5 rule categories: coding-style, testing, patterns, frameworks, security.
+
+```bash
+ai-toolkit install --local --auto-detect  # detect project language, install matching rules
+ai-toolkit install --local --lang typescript  # explicit language selection
+ai-toolkit install --local --lang go,python   # multiple languages
+```
+
+Rules are injected into `CLAUDE.md` and auto-updated on `ai-toolkit update`.
+
+---
+
+## Extension API
+
+Generic API for external tools to inject rules and hooks into the toolkit:
+
+```bash
+# Rules — injected into CLAUDE.md with HTML markers
+ai-toolkit inject-rule ./jira-rules.md    # idempotent, source-tagged block
+ai-toolkit remove-rule jira-rules
+
+# Hooks — injected into settings.json with _source tags
+ai-toolkit inject-hook ./my-hooks.json    # idempotent, _source tagged
+ai-toolkit remove-hook my-hooks
+```
+
+Injection is idempotent — re-running updates only the marked block, never touching content outside it. See [`kb/reference/extension-api.md`](kb/reference/extension-api.md).
+
+---
+
+## Manifest Install
+
+Module-level install granularity. Install only what you need:
+
+```bash
+ai-toolkit install --modules core,agents,rules-typescript
+ai-toolkit install --auto-detect          # detect project language and pick modules
+ai-toolkit status                         # show installed modules and versions
+ai-toolkit update                         # incremental re-install (only changed modules)
+```
+
+Install state is tracked in `~/.ai-toolkit/state.json`. See [`kb/reference/manifest-install.md`](kb/reference/manifest-install.md).
+
+---
+
 ## Plugin Packs (Opt-in)
 
 11 experimental plugin packs — domain bundles not part of the default install. Each pack bundles agents, skills, hooks, and/or rules for a specific domain.
@@ -410,8 +542,8 @@ All packs have `status: experimental`. Each has a `plugin.json` manifest and `RE
 
 | Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
 |---------|---------------|----------------------|-----------------|-------|
-| Skills | 85 | 100+ | 146 | 20+ |
-| Agents | 47 | 30+ | 112 | 20+ |
+| Skills | 90 | 100+ | 146 | 20+ |
+| Agents | 44 | 30+ | 112 | 20+ |
 | Machine-enforced constitution | **Yes** | No (docs only) | No | No |
 | Skill-scoped lifecycle hooks | **Yes** | No | No | No |
 | Effort-based model budgeting | **Yes** | No | No | No |
@@ -549,6 +681,14 @@ Usage: ai-toolkit <command> [options]
 | `reset --local` | Wipe all project-local configs and recreate from scratch (clean slate) |
 | `add-rule <rule.md> [name]` | Register rule in `~/.ai-toolkit/rules/` — auto-applied on every `update` |
 | `remove-rule <name> [dir]` | Unregister rule from `~/.ai-toolkit/rules/` and remove its block from `CLAUDE.md` |
+| `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
+| `remove-hook <name>` | Remove injected hooks by source name |
+| `mcp list` | List available MCP server templates (25 templates) |
+| `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
+| `mcp show <name>` | Show MCP template config details |
+| `mcp remove <name>` | Remove MCP server from `.mcp.json` |
+| `status` | Show installed modules and version |
+| `update` | Re-install with saved modules (incremental) |
 | `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
 | `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
 | `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
@@ -591,6 +731,9 @@ ai-toolkit install --persona backend-lead # persona preset: backend-lead | front
 ai-toolkit install --local               # also set up project-local configs (CLAUDE.md, settings, constitution, Copilot, Cline, Roo, Aider, Git Hooks, MCP Defaults)
 ai-toolkit update --local                # re-apply + refresh project-local configs
 ai-toolkit install --list                # dry-run: show what would be applied
+ai-toolkit install --modules core,agents,rules-typescript  # selective module install
+ai-toolkit install --auto-detect         # detect project language and install matching rules
+ai-toolkit install --lang typescript     # explicit language for rules install
 ```
 
 ---

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
-  "description": "Professional-grade Claude Code toolkit: 87 skills, 47 agents, persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.2.0",
+  "description": "Professional-grade Claude Code toolkit: 90 skills, 44 agents, persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
+  "version": "1.2.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -6,13 +6,13 @@ Universal multi-agent system for software development. Works across all reposito
 
 | Component | Count |
 |-----------|-------|
-| Agents | 47 |
-| Skills | 87 |
-| Hooks | 12 events / 15 entries (SessionStart, Notification, PreToolUse ×2, UserPromptSubmit ×2, PostToolUse, Stop ×2, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd) |
+| Agents | 44 |
+| Skills | 90 |
+| Hooks | 12 events / 21 entries (SessionStart, Notification, PreToolUse ×2, UserPromptSubmit ×2, PostToolUse, Stop ×2, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd) |
 
 ---
 
-## Agents (47)
+## Agents (44)
 
 ### Orchestration & Planning (4)
 | Agent | Model | Purpose |
@@ -31,16 +31,15 @@ Universal multi-agent system for software development. Works across all reposito
 | `game-developer` | opus | Unity, Godot, Unreal, Phaser |
 | `database-architect` | opus | Schema design, migrations, query optimization, operations |
 
-### AI/ML (7)
+### AI/ML (6)
 | Agent | Model | Purpose |
 |-------|-------|---------|
-| `ai-engineer` | opus | LLM integration, vector search |
+| `ai-engineer` | opus | LLM integration, vector search, RAG pipelines |
 | `ml-engineer` | opus | Model training, MLOps |
 | `nlp-engineer` | opus | NLP pipelines, text processing |
 | `data-scientist` | opus | Statistics, analysis, visualization |
 | `data-analyst` | sonnet | SQL, analytics, reporting |
 | `prompt-engineer` | opus | Prompt design, optimization |
-| `rag-engineer` | opus | RAG pipelines, retrieval |
 
 ### Quality & Security (6)
 | Agent | Model | Purpose |
@@ -62,12 +61,11 @@ Universal multi-agent system for software development. Works across all reposito
 | `performance-optimizer` | opus | Performance tuning |
 | `llm-ops-engineer` | opus | LLM operations, monitoring |
 
-### Research & Documentation (6)
+### Research & Documentation (5)
 | Agent | Model | Purpose |
 |-------|-------|---------|
 | `explorer-agent` | sonnet | Codebase discovery (READ-ONLY) |
-| `research-synthesizer` | opus | Research coordination, synthesis, reports |
-| `technical-researcher` | opus | Deep technical investigation |
+| `technical-researcher` | opus | Deep technical investigation, research synthesis |
 | `search-specialist` | sonnet | Search optimization |
 | `fact-checker` | sonnet | Verification, source checking |
 | `documenter` | sonnet | Documentation, KB management, SOPs, API docs |
@@ -86,11 +84,10 @@ Universal multi-agent system for software development. Works across all reposito
 | `night-watchman` | sonnet | Autonomous maintenance: dependency updates, dead code |
 | `chaos-monkey` | opus | Resilience testing: fault injection, failure verification |
 
-### MCP (3)
+### MCP (2)
 | Agent | Model | Purpose |
 |-------|-------|---------|
-| `mcp-expert` | opus | MCP protocol expertise |
-| `mcp-server-architect` | opus | MCP server design |
+| `mcp-specialist` | opus | MCP server design, client config, troubleshooting |
 | `mcp-testing-engineer` | sonnet | MCP testing |
 
 ### Specialist (4)
@@ -103,7 +100,7 @@ Universal multi-agent system for software development. Works across all reposito
 
 ---
 
-## Skills (87)
+## Skills (90)
 
 ### Task Skills (28)
 | Skill | Slash Command | Purpose |
@@ -137,7 +134,7 @@ Universal multi-agent system for software development. Works across all reposito
 | `prd-to-issues` | `/prd-to-issues` | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | `skill-audit` | `/skill-audit` | Scan skills and agents for security risks, dangerous patterns, secrets |
 
-### Hybrid Skills (28)
+### Hybrid Skills (30)
 | Skill | Slash Command | Purpose |
 |-------|---------------|---------|
 | `explore` | `/explore` | Codebase exploration and tech stack discovery |
@@ -168,8 +165,10 @@ Universal multi-agent system for software development. Works across all reposito
 | `repeat` | `/repeat` | Autonomous loop with safety controls (Ralph Wiggum pattern) |
 | `mem-search` | `/mem-search` | Search past coding sessions via natural language (memory-pack) |
 | `persona` | `/persona` | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
+| `council` | `/council` | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) with synthesis |
+| `introspect` | `/introspect` | Agent self-debugging: classify failure pattern, suggest recovery action, emit introspection report |
 
-### Knowledge Skills - Development (15)
+### Knowledge Skills - Development (16)
 | Skill | Purpose |
 |-------|---------|
 | `app-builder` | Project scaffolding, tech stack |
@@ -187,6 +186,7 @@ Universal multi-agent system for software development. Works across all reposito
 | `kotlin-patterns` | Coroutines, DSLs, sealed classes, Ktor, MockK |
 | `swift-patterns` | Protocol-oriented, SwiftUI, async/await, SPM |
 | `ruby-patterns` | Blocks, Rails conventions, RSpec, ActiveRecord |
+| `brand-voice` | Anti-trope list, voice principles, LLM rhetoric prevention |
 
 ### Knowledge Skills - Infrastructure (6)
 | Skill | Purpose |
@@ -245,7 +245,7 @@ Phase 2: IMPLEMENTATION
 | Bug Fix | debugger | backend/frontend, test-engineer |
 | Performance | performance-optimizer | database-architect |
 | Security | security-auditor | code-reviewer |
-| Research | research-synthesizer | technical-researcher, search-specialist |
+| Research | technical-researcher | search-specialist, fact-checker |
 | Documentation | documenter | explorer-agent |
 
 ---
@@ -255,9 +255,9 @@ Phase 2: IMPLEMENTATION
 ```
 .claude/
 ├── ARCHITECTURE.md      # This file
-├── agents/              # Agent definitions (47)
+├── agents/              # Agent definitions (44)
 ├── hooks.json           # Quality gate hooks (multi-language)
-├── skills/              # All skills: task, hybrid, knowledge (87)
+├── skills/              # All skills: task, hybrid, knowledge (90)
 ├── output-styles/       # System prompt output style overrides (e.g. golden-rules)
 ├── constitution.md      # Immutable safety rules (5 articles)
 └── settings.local.json  # Local settings + Agent Teams config
@@ -297,6 +297,22 @@ Lead Session (You)
 
 ---
 
+## Extension Points
+
+### MCP Templates (25)
+`app/plugins/mcp-templates/` ships 25 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+
+### Language Rules (70 files, 13 languages)
+`app/rules/` contains per-language coding rules injected into `CLAUDE.md`. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.
+
+### Extension API (`inject-hook`)
+The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers.
+
+### Manifest Install (`--modules`, `--auto-detect`)
+`manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or let the installer detect which language rules to add based on project files (e.g. `package.json` → `rules-typescript`, `go.mod` → `rules-golang`).
+
+---
+
 ## Principles
 
 1. **Universal**: No project-specific references