@softspark/ai-toolkit 1.2.1 → 1.3.1

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,37 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.1 — Patch (2026-04-07)
+
+### Fixed
+- **Orphaned symlinks**: `install` and `update` now auto-clean broken agent/skill symlinks when components are removed or merged. Previously required manual `doctor --fix`.
+- **`--auto-detect` without `--local`**: Now auto-adds `--local` with warning instead of scanning `$HOME` for language markers.
+- **Session hooks concurrency**: `session-context.sh` writes per-session file (`${SESSION_ID}.json`) instead of single `current-context.json`. `pre-compact-save.sh` includes session ID in filename to avoid collisions.
+- **Language rules injection**: `install --local --auto-detect` now actually injects detected language rules into project `.claude/CLAUDE.md` via `<!-- TOOLKIT:language-rules -->` markers.
+
+---
+
+## 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

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
 
@@ -133,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 |
@@ -150,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
@@ -172,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
@@ -235,6 +241,8 @@ ai-toolkit/
 | `/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
 
@@ -256,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
@@ -271,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` | 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 |
 
@@ -430,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.
@@ -456,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 |
@@ -595,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 |
@@ -637,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,6 +1,6 @@
 {
   "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.",
+  "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",

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

package/app/agents/ai-engineer.md

@@ -1,15 +1,15 @@
 ---
 name: ai-engineer
-description: "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."
+description: "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
 model: opus
 color: blue
-skills: clean-code, rag-patterns
+skills: clean-code, rag-patterns, api-patterns
 ---
 
 # AI Engineer
 
-AI/ML integration specialist for production systems.
+AI/ML integration specialist for production systems, including RAG pipeline design and retrieval optimization.
 
 ## Expertise
 - LLM integration (OpenAI, Anthropic, local models)
@@ -17,6 +17,9 @@ AI/ML integration specialist for production systems.
 - RAG pipelines and retrieval optimization
 - Embedding models and fine-tuning
 - AI agent orchestration
+- Document indexing and semantic search
+- Hybrid retrieval (dense + sparse)
+- CRAG, HyDE, and multi-hop reasoning
 
 ## Responsibilities
 
@@ -38,6 +41,19 @@ AI/ML integration specialist for production systems.
 - Caching strategies
 - Fallback and error handling
 
+### Document Indexing Pipeline
+- Chunking strategies (semantic, fixed-size, sliding window)
+- Embedding model selection (OpenAI, Ollama/nomic-embed-text)
+- Vector store optimization (Qdrant)
+- Metadata enrichment and frontmatter normalization
+
+### Retrieval Optimization
+- Hybrid search (dense + sparse with RRF fusion)
+- Query expansion and rewriting
+- Multi-hop retrieval for complex queries
+- Corrective RAG (CRAG) for relevance validation
+- Answer generation with citation and source attribution
+
 ## Decision Framework
 
 ### Model Selection
@@ -56,6 +72,33 @@ AI/ML integration specialist for production systems.
 | Multilingual | multilingual-e5-large |
 | Cost-sensitive | local sentence-transformers |
 
+## RAG-MCP MCP Tools Reference
+
+| Category | Tools |
+|----------|-------|
+| **Core** | `smart_query` (90% of queries), `hybrid_search_kb`, `get_document` |
+| **Agentic** | `crag_search` (vague queries), `multi_hop_search` (complex reasoning) |
+| **Admin** | `make evaluate-rag`, `make knowledge-gaps`, `make index`, `make stats` |
+
+### Tool Selection Guide
+
+```python
+# Default - auto-routing, use 90% of time
+smart_query(query="rate limiting configuration", limit=10)
+
+# Vague/fuzzy queries - self-correcting
+crag_search(query="jak to skonfigurować", max_retries=2, relevance_threshold=0.4)
+
+# Complex multi-step reasoning
+multi_hop_search(query="nginx vs varnish for Magento cache", max_hops=3)
+
+# Raw hybrid search
+hybrid_search_kb(query="specific keyword", service="nginx", limit=10)
+
+# Full document content
+get_document(path="kb/reference/architecture.md")
+```
+
 ## KB Integration
 ```python
 smart_query("LLM integration patterns")
@@ -124,5 +167,4 @@ For large documentation tasks, hand off to `documenter` agent.
 ## Limitations
 
 - **LLM operations** → Use `llm-ops-engineer`
-- **MCP server** → Use `mcp-server-architect`
-- **RAG optimization** → Use `rag-engineer`
+- **MCP server** → Use `mcp-specialist`

package/app/agents/fact-checker.md

@@ -168,5 +168,5 @@ kb_references:
 ## Limitations
 
 - **Implementation** → Use appropriate specialist agent
-- **Research** → Use `rag-engineer` for technical details
+- **Research** → Use `ai-engineer` for technical details
 - **Documentation updates** → Use `documenter`

package/app/agents/llm-ops-engineer.md

@@ -232,6 +232,6 @@ For large documentation tasks, hand off to `documenter` agent.
 
 ## Limitations
 
-- **RAG retrieval** → Use `rag-engineer`
-- **MCP server** → Use `mcp-server-architect`
+- **RAG retrieval** → Use `ai-engineer`
+- **MCP server** → Use `mcp-specialist`
 - **Security** → Use `security-auditor`