@softspark/ai-toolkit 3.5.0 → 4.0.0

package/AGENTS.md

@@ -446,20 +446,20 @@ Specialized agent personas — apply their expertise for relevant tasks:
 
 Skills are invocable commands or auto-loaded knowledge sources:
 
-- **a11y-validate**: Accessibility validator for WCAG 2.1 AA, EN 301 549, EAA. Covers ARIA, contrast, keyboard, forms, media. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard nav, screen reader.
+- **a11y-validate**: Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard, screen reader.
 - **agent-creator**: Creates new specialized agents with frontmatter, tools, delegation. Triggers: new agent, create agent, agent scaffold, specialized agent.
 - **analyze**: Analyzes code quality, complexity, patterns across codebase. Triggers: quality report, hotspot scan, code analysis, architecture signal.
-- **api-patterns**: REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, endpoint, OpenAPI, Swagger, pagination, idempotency key, rate limit.
-- **app-builder**: App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter, build app, landing page, dashboard, mobile app.
-- **architecture-audit**: Audits codebase for architectural friction and shallow modules, proposes deepening refactors as RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling. Codex-adapted: uses native subagents and plan tracking.
+- **api-patterns**: REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit.
+- **app-builder**: App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter. Triggers: scaffold, bootstrap, new project, starter, dashboard, mobile app.
+- **architecture-audit**: Audits codebase for architectural friction, shallow modules; proposes RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling. Codex-adapted: uses native subagents and plan tracking.
 - **architecture-decision**: Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach.
-- **biz-scan**: Scans codebase (schemas, endpoints, events, flags) for revenue opportunities, missing KPIs, monetization gaps. Triggers: business metrics, KPI coverage, analytics gaps, monetization, revenue opportunity.
+- **biz-scan**: Scans codebase for revenue opportunities, KPIs, monetization gaps. Triggers: business metrics, KPI, analytics gaps, monetization, revenue.
 - **brand-voice**: Direct technical voice for docs, README, user-facing text. Concise/strict modes. Triggers: documentation, README, content, output-mode, voice, prose style.
 - **briefing**: Executive daily briefing aggregating reports from all agents into decision-focused summary. Triggers: briefing, daily summary, status across system, executive update.
 - **build**: Builds project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Triggers: build, compile, bundle, produce artifacts.
 - **chaos**: Injects controlled faults for resilience testing on non-prod. Triggers: chaos, fault injection, latency injection, dependency kill, resilience test.
 - **ci**: Detect/generate/debug CI pipeline config (GitHub Actions, GitLab CI). Triggers: CI setup, build pipeline, GitHub Actions config, debug CI, GitLab CI.
-- **ci-cd-patterns**: CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary, rollback gates. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, artifact, canary, rollout.
+- **ci-cd-patterns**: CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, canary, rollout.
 - **clean-code**: Code quality: meaningful names, SRP, DRY, small functions, guard clauses, refactoring. Triggers: clean code, naming, code smell, SRP, DRY, long function, god class, dead code.
 - **command-creator**: Creates new Claude Code slash commands with frontmatter and validation. Triggers: new slash command, create command, command scaffold.
 - **commit**: Creates Conventional Commits with pre-commit validation. Triggers: commit, conventional commit, git commit, message.
@@ -472,26 +472,24 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **dart-rules**: Dart/Flutter coding rules: style, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget.
 - **database-patterns**: DB schema design and query tuning: normalization, indexing, N+1, transactions, EXPLAIN. Triggers: schema, index, slow query, N+1, PostgreSQL, MySQL, EXPLAIN, deadlock, query plan.
 - **debug**: Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.
-- **debugging-tactics**: RCA debugging: investigation, hypothesis, validation, fix. No fix without RCA. Triggers: bug, error, exception, stack trace, intermittent, flaky, crash, regression, broken after.
 - **deploy**: Deploys with pre-flight checks and health verification. Triggers: deploy, deployment, ship, release, push to prod.
-- **design-an-interface**: Generates multiple alternative interface designs in parallel and compares them (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice. Codex-adapted: uses native subagents and plan tracking.
+- **design-an-interface**: Generates and compares parallel interface designs (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice. Codex-adapted: uses native subagents and plan tracking.
 - **design-engineering**: UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish.
-- **docker-devops**: Docker/K8s/DevOps: Dockerfile, multi-stage builds, compose, manifests, Helm, image hardening. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod, deployment yaml.
+- **docker-devops**: Docker/K8s: Dockerfile, multi-stage, compose, manifests, Helm. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod.
 - **docs**: Generates/updates README, API docs, architecture notes. Triggers: docs, README, API docs, architecture note, documentation.
 - **documentation-standards**: KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
 - **ecommerce-patterns**: E-commerce: cart, checkout, payments (Stripe/Adyen), order state, inventory, promos, tax. Triggers: cart, checkout, SKU, payment, Stripe, Shopify, Medusa, Magento, coupon, refund.
 - **evaluate**: Evaluates RAG retrieval and LLM-as-judge metrics (faithfulness, relevancy, context precision). Triggers: measure RAG quality, knowledge gap, RAG eval, golden dataset.
-- **evolve**: Analyzes failure patterns in agents/skills and drafts targeted prompt/permission improvements. Triggers: improve agent, refine skill, update system prompt, optimize agent, fix failure pattern.
+- **evolve**: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.
 - **explain**: Explains code/architecture with Mermaid diagrams and sequence flows. Triggers: what does X do, how does Y work, explain code, sequence diagram.
 - **explore**: Explores codebase structure, stack, and architecture. Triggers: explore codebase, project structure, stack overview, architecture map.
 - **fix**: Applies targeted fix to known bug/lint error, verifies with same command that surfaced it. Triggers: fix, apply fix, fix bug, fix lint, targeted fix.
-- **flutter-patterns**: Flutter/Dart: widget composition, state mgmt (Riverpod/Bloc/Provider), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, Navigator, hot reload.
-- **git-mastery**: Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, history rewriting, LFS. Triggers: git rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree, submodule.
+- **flutter-patterns**: Flutter/Dart: widgets, state mgmt (Riverpod/Bloc), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, hot reload.
+- **git-mastery**: Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, LFS. Triggers: rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree.
 - **golang-rules**: Go coding rules: style, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt.
 - **grill-me**: Stress-tests a plan via Socratic questioning down each decision branch. Triggers: stress-test, grill me, validate assumptions, challenge plan, socratic review. Codex-adapted: uses native subagents and plan tracking.
 - **health**: Service/infra health via liveness/readiness checks, resource usage, quick diagnostics. Triggers: health check, services up, system status, infra health, degraded service.
 - **hipaa-validate**: HIPAA validator: PHI exposure, audit logging, encryption, access control, BAA refs. Triggers: HIPAA, PHI, healthcare compliance, audit log, BAA.
-- **hive-mind**: Multi-agent swarm: consensus voting, output aggregation, file ownership, map-reduce. Triggers: swarm, hive mind, multi-agent, consensus, parallel agents, team of agents, agent voting.
 - **hook-creator**: Create new Claude Code lifecycle hook (PreToolUse/PostToolUse/Stop/SessionStart) with bash + hooks.json. Triggers: create hook, lifecycle hook, PreToolUse, PostToolUse, hook event.
 - **index**: Reindexes KB for semantic search via vector store (Qdrant). Triggers: reindex KB, rebuild index, vector reindex, refresh embeddings.
 - **instinct-review**: Reviews/promotes/removes instincts from `.claude/instincts/*.md`. Triggers: instinct review, curate instincts, manage instincts, promote instinct.
@@ -503,22 +501,21 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **kotlin-rules**: Kotlin coding rules: style, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx.
 - **lint**: Runs linter+typechecker with auto-detected toolchain (ruff/mypy, eslint/tsc, phpstan, golangci-lint, clippy). Triggers: lint, typecheck, static analysis.
 - **mcp-builder**: Builds production MCP servers via 4-phase methodology: research, implement, test, evaluate. Triggers: build MCP, new MCP, MCP integration, MCP server scaffold.
-- **mcp-patterns**: MCP server design: tool schemas, resources, stdio/SSE transports, capability negotiation. Triggers: MCP, Model Context Protocol, MCP server, JSON-RPC, stdio, SSE, Claude Desktop config.
+- **mcp-patterns**: MCP server design: tool schemas, resources, stdio/SSE, capability negotiation. Triggers: MCP, Model Context Protocol, JSON-RPC, stdio, SSE, Claude Desktop.
 - **medplum-rules**: Medplum (FHIR healthcare) coding rules: style, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire.
 - **mem-search**: Searches past coding sessions for observations, decisions, context. Triggers: mem-search, recall session, past work, prior decisions, session history.
-- **migrate**: Run/create DB migrations with detected tool (Alembic, Prisma, Laravel, Django, Flyway, Drizzle), checks backup. Triggers: apply migration, rollback, generate migration, db migration.
-- **migration-patterns**: Zero-downtime DB migrations: expand-contract, double-write, backfill, blue-green schema. Triggers: migration, schema change, zero-downtime, backfill, ALTER TABLE, online DDL, safe deploy.
+- **migrate**: Run/create DB migrations (Alembic, Prisma, Laravel, Django, Flyway, Drizzle); checks backup. Triggers: apply migration, rollback, generate migration.
+- **migration-patterns**: Zero-downtime DB migrations: expand-contract, double-write, backfill, blue-green. Triggers: migration, schema change, backfill, ALTER TABLE, online DDL.
 - **model-routing-patterns**: Multi-model pipelines (Haiku/Sonnet/Opus): cost routing, escalation, fallback chains. Triggers: model routing, Haiku, Sonnet, Opus, escalation, fallback chain.
 - **night-watch**: Autonomous maintenance (dep updates, dead code, small refactors) in isolated branch, off-hours. Triggers: night watch, autonomous maintenance, dep updates.
-- **observability-patterns**: Observability: structured logs, metrics (RED/USE), tracing (OpenTelemetry), SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, span, monitoring, alerting.
+- **observability-patterns**: Observability: structured logs, metrics (RED/USE), tracing, SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, monitoring.
 - **onboard**: Sets up ai-toolkit in a project: symlinks, CLAUDE.md, intent interview. Triggers: onboard, setup project, install ai-toolkit, migrate project.
 - **orchestrate**: Coordinates multiple specialized agents in parallel. Triggers: orchestrate, multi-agent, parallel agents, coordinate agents. Codex-adapted: uses native subagents and plan tracking.
 - **panic**: Emergency kill switch — halts all agents via lockfile gate. Triggers: panic, stop everything, kill switch, halt agents, agents looping.
-- **performance-profiling**: Performance: golden signals (latency/traffic/errors/saturation), p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, load test, memory leak.
+- **performance-profiling**: Performance: golden signals, p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, memory leak.
 - **persona**: Switches engineering persona at runtime. Triggers: persona, switch role, backend-lead, frontend-lead, devops-eng, junior-dev.
 - **php-rules**: PHP coding rules: style, patterns, security, testing. Triggers: .php, composer.json, Laravel, Symfony, PHPUnit, PSR-12, Composer.
 - **plan**: Breaks features/goals into phased plans with task lists, agent assignments, dependencies. Triggers: plan feature, implementation roadmap, break down task, project phases.
-- **plan-writing**: Implementation plans + pre-mortems: phases, success criteria, risks, rollback, acceptance tests. Triggers: implementation plan, pre-mortem, phased plan, task breakdown, risk register.
 - **plugin-creator**: Creates opt-in plugin packs with manifests + module scaffolding for Claude/Codex. Triggers: new plugin, plugin pack, plugin scaffold.
 - **pr**: Creates GitHub PR after pre-flight checks (lint/typecheck/tests), structured summary from commits. Triggers: pr, pull request, create PR, ready to merge.
 - **prd-to-issues**: Splits a PRD into vertical-slice GitHub issues with HITL/AFK tagging and dependencies. Triggers: PRD to issues, create tickets, break down PRD, work items.
@@ -531,14 +528,13 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **refactor**: Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize.
 - **refactor-plan**: Creates detailed refactor plan with tiny commits via interview, files as GitHub RFC. Triggers: refactor plan, refactoring RFC, incremental refactor, safe steps. Codex-adapted: uses native subagents and plan tracking.
 - **repeat**: Runs prompt/slash command on recurring interval until done or limit. Triggers: repeat, recurring task, poll status, run every N minutes, interval. Codex-adapted: uses native subagents and plan tracking.
-- **research-mastery**: Hierarchical retrieval: KB first (smart_query/crag_search), then MCP/Context7, then web. Triggers: research, fact-check, verify, synthesize, cross-reference, multi-source, investigate, cite sources.
+- **research-mastery**: Hierarchical retrieval: KB → MCP/Context7 → web. Triggers: research, fact-check, verify, synthesize, cross-reference, multi-source, cite sources.
 - **review**: Reviews code for quality, security, correctness. Triggers: code review, quality review, security review, review PR, review branch.
 - **rollback**: Rolls back git commit, DB migration, or deploy to known-good with safety + health checks. Triggers: rollback, revert deploy, revert migration, rollback commit, git revert.
 - **ruby-patterns**: Ruby/Rails: blocks, metaprogramming, ActiveRecord, Sidekiq, RSpec, Sorbet, Hanami. Triggers: Ruby, Rails, ActiveRecord, Sidekiq, RSpec, Gemfile, bundler, Hanami, Sorbet.
 - **ruby-rules**: Ruby coding rules: style, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop.
 - **rust-patterns**: Rust: ownership, lifetimes, async (Tokio), Result/anyhow/thiserror, traits, unsafe. Triggers: Rust, borrow checker, lifetime, Tokio, cargo, trait, impl, Result, unsafe, clippy.
 - **rust-rules**: Rust coding rules: style, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test.
-- **search**: Searches the KB with semantic + hybrid modes. Triggers: search KB, semantic search, hybrid search, knowledge base query.
 - **security-patterns**: App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS.
 - **seo-validate**: SEO validator: meta/OG, Schema.org, hreflang, Core Web Vitals, crawlability. Triggers: SEO, meta tags, Schema.org, hreflang, LCP, INP, CLS, Core Web Vitals, sitemap, crawlability.
 - **skill-audit**: Scans skills/agents for security risks: dangerous patterns, secrets, excessive perms. Triggers: skill audit, security scan, agent audit, dangerous pattern.
@@ -548,11 +544,10 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **swift-patterns**: Swift/iOS: SwiftUI, Combine, async/await, actors, SPM, Core Data, UIKit interop. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, Core Data, @MainActor, @State.
 - **swift-rules**: Swift coding rules: style, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest.
 - **tdd**: TDD with red-green-refactor loop and vertical slices. Triggers: TDD, test-first, red-green-refactor, test driving development. Codex-adapted: uses native subagents and plan tracking.
-- **teams**: Launches multi-agent teams for review, debugging, feature dev, security audits, migrations. Triggers: multi-agent workflow, agent teams, team review, parallel agent collaboration. Codex-adapted: uses native subagents and plan tracking.
 - **test**: Runs project test suite with coverage, auto-detects framework (pytest, vitest, jest, flutter, go, cargo, phpunit). Triggers: run tests, test suite, coverage report.
 - **testing-patterns**: Testing strategy: pyramid, AAA, mocks/fakes/stubs, flaky tests, coverage. Triggers: test, fixture, mock, stub, e2e, TDD, Playwright, Cypress, flaky, coverage, property-based.
 - **triage-issue**: Bug triage: explores codebase for root cause, files GitHub issue with TDD fix plan. Triggers: triage, investigate bug, fix plan, root cause, file issue, bug report. Codex-adapted: uses native subagents and plan tracking.
-- **typescript-patterns**: TypeScript type safety: generics, conditional types, discriminated unions, Zod, satisfies, branded types. Triggers: TypeScript, TS, generics, Zod, satisfies, type narrowing, strict mode.
+- **typescript-patterns**: TypeScript types: generics, discriminated unions, Zod, satisfies, branded types. Triggers: TypeScript, TS, generics, Zod, satisfies, strict mode.
 - **typescript-rules**: TypeScript/JavaScript coding rules: style, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint.
 - **ubiquitous-language**: Extracts DDD ubiquitous language glossary, flags ambiguities, saves to UBIQUITOUS_LANGUAGE.md. Triggers: define domain terms, build glossary, harden terminology, DDD, domain model.
 - **verification-before-completion**: Forces verification commands before success claims. Evidence before assertions. Triggers: complete, fixed, passing, done, ready, verified.

package/CHANGELOG.md

@@ -7,6 +7,66 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.0.0 — Skill consolidation: 112 → 107, removes 5 overlapping skills (2026-05-06)
+
+**Breaking release.** Five redundant skills removed; their substantive knowledge migrated into the surviving targets. Resolves the `/skills` listing truncation that v3.5.x partially addressed and removes user-facing overlap that made dispatch ambiguous.
+
+### Removed (BREAKING)
+
+- **`/search`** (task skill) — `/research-mastery` is the superset, now includes local Grep/Glob fallback for the no-MCP case.
+- **`/teams`** (task skill) — `/workflow` covers all preset scenarios (debug, feature, security, migration, etc.) without requiring `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+- **`plan-writing`** (knowledge skill) — estimation patterns and pre-mortem rules merged into `/plan`.
+- **`debugging-tactics`** (knowledge skill) — Iron Law, 4-phase methodology, and "5 Whys" merged into `/debug`.
+- **`hive-mind`** (knowledge skill) — consensus voting and aggregation rules merged into `/swarm`.
+
+### Changed
+
+- **`/plan`** — added Estimation & Templates section (T-shirt sizing, cone of uncertainty, SMART vs phase-aligned outcomes, mandatory pre-mortem ≥5 failure modes).
+- **`/debug`** — added Methodology section (Iron Law, 4 phases, "5 Whys" depth gate, architecture escalation after 3 failed fixes).
+- **`/swarm`** — Aggregation section now covers consensus weighted voting and file-ownership escalation rules previously in `hive-mind`.
+- **`/research-mastery`** — added Local Fallback section for Grep/Glob when `rag-mcp` is unavailable.
+- **Agent `skills:` field** — `orchestrator`, `product-manager`, `chief-of-staff` switched from `plan-writing` to `plan`. `meta-architect`, `night-watchman`, `predictive-analyst` switched from `debugging-tactics` to `debug`.
+- **`research-pack` plugin** — dropped `search`, `plan-writing` from skill list; added `plan`.
+- **Cross-references** — `/refactor-plan`, `/persona`, `/explore`, `/mem-search`, `/explain`, `/index` updated to reference surviving skills.
+- **`scripts/codex_skill_adapter.py`** — removed dead `teams`-specific branch; `_adapt_body` no longer takes `skill_name`.
+- **Documentation counts** — `README.md`, `package.json`, `manifest.json`, `app/ARCHITECTURE.md`, `kb/reference/skills-catalog.md` updated from 112 → 107.
+
+### Migration
+
+| Before | After |
+|--------|-------|
+| `/search <query>` | `/research-mastery <query>` |
+| `/teams <preset>` | `/workflow <type>` |
+| Agent `skills: plan-writing` | Agent `skills: plan` |
+| Agent `skills: debugging-tactics` | Agent `skills: debug` |
+| Agent `skills: hive-mind` | Agent `skills: swarm` |
+
+### Why
+
+`/skills` listing reported 2.1%/2% truncation in Claude Code 2.1.131 — 5 descriptions silently dropped. v3.5.x trimmed individual descriptions; v4.0.0 removes the underlying overlap (5 skills with knowledge already covered elsewhere). Net effect: smaller listing, no lost knowledge, clearer dispatch.
+
+---
+
+## v3.5.1 — Description trim follow-up + GEMINI/Copilot drift fix (2026-05-06)
+
+Patch release. Continues v3.5.0 condensation on 20 skills and re-syncs platform artifacts that v3.5.0 forgot to regenerate.
+
+### Changed
+
+- **20 skills with further trimmed descriptions** — `a11y-validate`, `api-patterns`, `app-builder`, `architecture-audit`, `biz-scan`, `ci-cd-patterns`, `design-an-interface`, `docker-devops`, `evolve`, `flutter-patterns`, `git-mastery`, `hive-mind`, `mcp-patterns`, `migrate`, `migration-patterns`, `observability-patterns`, `performance-profiling`, `plan-writing`, `research-mastery`, `typescript-patterns`. Drops redundant trigger keywords already implied by the summary.
+- **`AGENTS.md`, `llms-full.txt`** regenerated to match the new descriptions.
+
+### Fixed
+
+- **`GEMINI.md` and `.github/copilot-instructions.md`** were not regenerated by the v3.5.0 release commit — they still carried pre-v3.5.0 verbose descriptions. Both now refreshed via `npm run generate:all`.
+- **`/audit.sarif`** added to `.gitignore` so output from `audit_skills.py --ci` does not pollute `git status`.
+
+### Why
+
+Drift in two generated platform files was visible only after running `npm run generate:all` on a clean v3.5.0 checkout. The fix is mechanical and contains no behavior change beyond the description tweaks.
+
+---
+
 ## v3.5.0 — Skill description condensation: 33% smaller, consistent pattern (2026-05-06)
 
 Minor release. All 112 skill descriptions rewritten into a single consistent pattern: short summary, then `Triggers: <comma-separated keywords>.` Drops the verbose "Load when..." tail entirely. Consequence: Claude Code's skill listing fits in ~2% context budget without truncation, and the trigger lists stay intact for accurate auto-loading.

package/README.md

@@ -1,10 +1,10 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 112 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, Augment, Google Antigravity, Codex CLI, and opencode, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 107 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, Augment, Google Antigravity, Codex CLI, and opencode, 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-112-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
 [![Tests](https://img.shields.io/badge/tests-1047%20passing-success)](tests/)
 
@@ -14,14 +14,24 @@
 
 ---
 
-## What's New in v3.5.0
+## What's New in v4.0.0
 
-Minor release. All 112 skill descriptions rewritten into a single consistent pattern.
+**Breaking release.** Skill catalog consolidated from 112 → 107: removes 5 redundant skills, merges their substantive knowledge into the surviving targets. Eliminates `/skills` truncation and removes overlap that confused agent dispatch.
 
-- **33% reduction in skill listing size** — 26 465 → 17 837 chars (~2 157 tokens saved). All 112 skills now fit in Claude Code's 2% `skillListingBudgetFraction` budget without truncation.
-- **Consistent description pattern** — every skill follows `<short summary>. Triggers: <comma-separated keywords>.` Verbose "Load when..." tails dropped.
-- **Trigger keywords preserved** — auto-loading on the same keywords as before, no behavior change.
-- **Generator template updated** — `scripts/generate_language_rules_skills.py` emits the new pattern, so `<lang>-rules` skills stay consistent on regeneration.
+- **`/search` removed** — `/research-mastery` is the superset (KB → MCP/Context7 → web with hierarchy of truth). Local Grep/Glob fallback is now part of `/research-mastery`.
+- **`/teams` removed** — `/workflow` covers the same scenarios without the experimental `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag.
+- **`plan-writing` knowledge skill removed** — estimation patterns (T-shirt sizing, cone of uncertainty) and pre-mortem rules are now part of `/plan`.
+- **`debugging-tactics` knowledge skill removed** — Iron Law, 4-phase methodology, and "5 Whys" are now part of `/debug`.
+- **`hive-mind` knowledge skill removed** — consensus voting and aggregation merged into `/swarm`.
+
+### Migration
+
+| Before | After |
+|--------|-------|
+| `/search <query>` | `/research-mastery <query>` |
+| `/teams <preset>` | `/workflow <type>` |
+| Agent `skills: plan-writing` | Agent `skills: plan` |
+| Agent `skills: debugging-tactics` | Agent `skills: debug` |
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -55,7 +65,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 112 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 107 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 **Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
 
@@ -145,7 +155,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 112 skills (task / hybrid / knowledge)
+│   ├── skills/          # 107 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)

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

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

package/app/ARCHITECTURE.md

@@ -200,7 +200,6 @@ The toolkit is organised as five stacked layers. Higher layers depend on lower l
 | `swarm` | `/swarm` | Massive parallelism via Agent Teams |
 | `workflow` | `/workflow` | Run agent workflow |
 | `instinct-review` | `/instinct-review` | Review, curate, and manage learned instincts |
-| `teams` | `/teams` | Launch pre-configured Agent Teams compositions |
 | `write-a-prd` | `/write-a-prd` | Create PRD through interactive interview and module design |
 | `prd-to-plan` | `/prd-to-plan` | Convert PRD into phased vertical-slice implementation plan |
 | `tdd` | `/tdd` | Test-driven development with red-green-refactor loop |
@@ -258,22 +257,15 @@ The toolkit is organised as five stacked layers. Higher layers depend on lower l
 | `content-moderation-patterns` | Two-stage moderation: pre-filter + LLM classifier |
 | `model-routing-patterns` | Haiku/Sonnet/Opus routing, escalation, fallback |
 
-### Knowledge Skills - Process (7)
+### Knowledge Skills - Process (5)
 | Skill | Purpose |
 |-------|---------|
-| `plan-writing` | Task breakdown, planning |
-| `debugging-tactics` | Iron Law 4-phase debugging: root cause → pattern → hypothesis → fix |
 | `git-mastery` | Safe history rewriting, bisect, complex merges |
 | `architecture-decision` | Trade-off analysis, architecture note templates |
 | `performance-profiling` | CPU, memory, I/O, database bottleneck profiling |
 | `research-mastery` | Hierarchy of Truth protocol |
 | `verification-before-completion` | Iron Law: evidence-before-claims, no completion without fresh verification |
 
-### Knowledge Skills - Orchestration (1)
-| Skill | Purpose |
-|-------|---------|
-| `hive-mind` | Swarm intelligence: Consensus, Aggregation |
-
 ---
 
 ## Orchestration Model

package/app/agents/chief-of-staff.md

@@ -4,7 +4,7 @@ description: "Executive Summary agent. Aggregates reports from all other agents
 model: sonnet
 color: purple
 tools: Read, Write, Bash
-skills: research-mastery, plan-writing
+skills: research-mastery, plan
 ---
 
 # Chief of Staff Agent

package/app/agents/meta-architect.md

@@ -4,7 +4,7 @@ description: "Self-Optimization agent. Analyzes system performance and mistakes
 model: opus
 color: purple
 tools: Read, Write, Edit, Bash, Grep
-skills: research-mastery, debugging-tactics
+skills: research-mastery, debug
 ---
 
 # Meta-Architect Agent

package/app/agents/night-watchman.md

@@ -4,7 +4,7 @@ description: "Autonomous maintenance agent. Use for automated dependency updates
 model: sonnet
 color: orange
 tools: Read, Write, Edit, Bash, Grep
-skills: clean-code, git-mastery, debugging-tactics
+skills: clean-code, git-mastery, debug
 ---
 
 # Night Watchman Agent

package/app/agents/orchestrator.md

@@ -4,7 +4,7 @@ description: "Multi-agent coordination and task orchestration. Use when a task r
 tools: Read, Grep, Glob, Bash, Write, Edit, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate
 model: opus
 color: purple
-skills: clean-code, app-builder, plan-writing
+skills: clean-code, app-builder, plan
 ---
 
 # Orchestrator - Multi-Agent Coordination

package/app/agents/predictive-analyst.md

@@ -4,7 +4,7 @@ description: "Precognition agent. Analyzes code changes to predict impact, regre
 model: sonnet
 color: cyan
 tools: Read, Write, Bash, Grep, Glob
-skills: debugging-tactics, git-mastery, testing-patterns
+skills: debug, git-mastery, testing-patterns
 ---
 
 # Predictive Analyst Agent

package/app/agents/product-manager.md

@@ -4,7 +4,7 @@ description: "Product management and value maximization expert. Use for requirem
 tools: Read, Write, Grep, Glob
 model: opus
 color: purple
-skills: clean-code, plan-writing
+skills: clean-code, plan
 ---
 
 # Product Manager

package/app/plugins/research-pack/plugin.json

@@ -11,7 +11,7 @@
   },
   "includes": {
     "agents": ["technical-researcher", "fact-checker", "search-specialist"],
-    "skills": ["search", "docs", "research-mastery", "plan-writing"],
+    "skills": ["docs", "research-mastery", "plan"],
     "rules": [],
     "hooks": ["user-prompt-submit.sh"]
   },

package/app/skills/a11y-validate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: a11y-validate
-description: "Accessibility validator for WCAG 2.1 AA, EN 301 549, EAA. Covers ARIA, contrast, keyboard, forms, media. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard nav, screen reader."
+description: "Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard, screen reader."
 user-invocable: true
 effort: medium
 disable-model-invocation: true

package/app/skills/api-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-patterns
-description: "REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, endpoint, OpenAPI, Swagger, pagination, idempotency key, rate limit."
+description: "REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/app-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-builder
-description: "App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter, build app, landing page, dashboard, mobile app."
+description: "App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter. Triggers: scaffold, bootstrap, new project, starter, dashboard, mobile app."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/architecture-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: architecture-audit
-description: "Audits codebase for architectural friction and shallow modules, proposes deepening refactors as RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling."
+description: "Audits codebase for architectural friction, shallow modules; proposes RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling."
 user-invocable: true
 effort: high
 argument-hint: "[area to audit or 'full codebase']"

package/app/skills/biz-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: biz-scan
-description: "Scans codebase (schemas, endpoints, events, flags) for revenue opportunities, missing KPIs, monetization gaps. Triggers: business metrics, KPI coverage, analytics gaps, monetization, revenue opportunity."
+description: "Scans codebase for revenue opportunities, KPIs, monetization gaps. Triggers: business metrics, KPI, analytics gaps, monetization, revenue."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[area]"

package/app/skills/ci-cd-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci-cd-patterns
-description: "CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary, rollback gates. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, artifact, canary, rollout."
+description: "CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, canary, rollout."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/debug/SKILL.md

@@ -44,6 +44,34 @@ Use the parsed output to focus investigation on the right files and hypotheses.
 
 ---
 
+## Methodology — The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues. Complete each phase before proceeding to the next.
+
+### Phase 1 — Root Cause Investigation
+Read error messages and stack traces completely. Reproduce reliably (or gather more data — don't guess). Check recent changes (`git diff`, new deps, config). For multi-component systems: log boundary in/out at each layer, identify WHERE it breaks before WHY.
+
+### Phase 2 — Pattern Analysis
+Find similar working code in the same codebase. Compare against references **completely**, not skimming. List every difference, however small.
+
+### Phase 3 — Hypothesis & Testing
+Form a single hypothesis ("X is the root cause because Y"). Test minimally — smallest possible change, one variable at a time. Verify before continuing — if it didn't work, form a NEW hypothesis. Don't stack fixes on top of fixes.
+
+### Phase 4 — Implementation
+Write a failing test case FIRST (use `/tdd`). Implement single fix at root cause. No "while I'm here" improvements.
+
+### "5 Whys" — depth gate
+Ask "Why?" at least 5 times to find the real issue. Stop at the first plausible answer = symptom fixing. Example: crash → null pointer → user object null → API 404 → invalid user ID → **frontend allowed negative IDs** (root cause).
+
+### Architecture escalation (3+ failed fixes)
+If three hypotheses failed and each fix reveals new shared state in different places, the architecture is wrong, not your hypothesis. STOP. Discuss with user before more attempts.
+
+---
+
 ## Debugging Workflow
 
 ### 1. Check Logs

package/app/skills/design-an-interface/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-an-interface
-description: "Generates multiple alternative interface designs in parallel and compares them (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice."
+description: "Generates and compares parallel interface designs (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice."
 user-invocable: true
 effort: high
 argument-hint: "[module or interface to design]"

package/app/skills/docker-devops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docker-devops
-description: "Docker/K8s/DevOps: Dockerfile, multi-stage builds, compose, manifests, Helm, image hardening. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod, deployment yaml."
+description: "Docker/K8s: Dockerfile, multi-stage, compose, manifests, Helm. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/evolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evolve
-description: "Analyzes failure patterns in agents/skills and drafts targeted prompt/permission improvements. Triggers: improve agent, refine skill, update system prompt, optimize agent, fix failure pattern."
+description: "Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent."
 effort: medium
 disable-model-invocation: true
 context: fork

package/app/skills/explain/SKILL.md

@@ -73,7 +73,7 @@ python3 ${CLAUDE_SKILL_DIR}/scripts/dependency-graph.py src/auth.py
 ## When NOT to Use
 
 - To critique or improve the code — use `/review` or `/refactor`
-- To find a specific function across the codebase — use `/search` or `/explore`
+- To find a specific function across the codebase — use `/explore` or `Grep`
 - To write the documentation that the explanation turns into — use `/docs`
 - For a full architecture audit or redesign — use `/architecture-audit`
 - When the user asks "why is this broken" — use `/debug`, not `/explain`

package/app/skills/explore/SKILL.md

@@ -131,7 +131,7 @@ hybrid_search_kb("project structure {framework}")
 ## When NOT to Use
 
 - To explain a specific module's design — use `/explain`
-- To find a specific identifier or symbol — use `Grep` directly or `/search`
+- To find a specific identifier or symbol — use `Grep` directly or `/research-mastery`
 - To audit architecture for deepening candidates — use `/architecture-audit`
 - To scaffold a new project — use `/app-builder`
 - When the user already knows the codebase — skip the overview and jump to the concrete task

package/app/skills/flutter-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flutter-patterns
-description: "Flutter/Dart: widget composition, state mgmt (Riverpod/Bloc/Provider), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, Navigator, hot reload."
+description: "Flutter/Dart: widgets, state mgmt (Riverpod/Bloc), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, hot reload."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/git-mastery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-mastery
-description: "Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, history rewriting, LFS. Triggers: git rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree, submodule."
+description: "Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, LFS. Triggers: rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree."
 effort: medium
 user-invocable: false
 allowed-tools: Read, Grep, Glob

package/app/skills/index/SKILL.md

@@ -89,7 +89,7 @@ last_updated: "YYYY-MM-DD"
 
 ## When NOT to Use
 
-- For searching the KB — use `/search` or call `smart_query()` via the rag-mcp tool
+- For searching the KB — use `/research-mastery` or call `smart_query()` via the rag-mcp tool
 - For fixing indexing bugs — use `/debug` on the indexer pipeline
 - To evaluate RAG quality after reindexing — use `/evaluate`
 - When no vector store is configured — document the gap, do not invent one

package/app/skills/mcp-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-patterns
-description: "MCP server design: tool schemas, resources, stdio/SSE transports, capability negotiation. Triggers: MCP, Model Context Protocol, MCP server, JSON-RPC, stdio, SSE, Claude Desktop config."
+description: "MCP server design: tool schemas, resources, stdio/SSE, capability negotiation. Triggers: MCP, Model Context Protocol, JSON-RPC, stdio, SSE, Claude Desktop."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/mem-search/SKILL.md

@@ -104,7 +104,7 @@ Found 3 results across 2 sessions.
 
 ## When NOT to Use
 
-- To search the KB or documentation — use `/search` or `smart_query()`
+- To search the KB or documentation — use `/research-mastery` or `smart_query()`
 - To find a specific commit — use `git log --grep` or `/git-mastery`
 - To list agent tasks — use `TaskList` or `/plan`
 - When memory-pack hooks are not installed — direct the user to install them first

package/app/skills/migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate
-description: "Run/create DB migrations with detected tool (Alembic, Prisma, Laravel, Django, Flyway, Drizzle), checks backup. Triggers: apply migration, rollback, generate migration, db migration."
+description: "Run/create DB migrations (Alembic, Prisma, Laravel, Django, Flyway, Drizzle); checks backup. Triggers: apply migration, rollback, generate migration."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[direction]"

package/app/skills/migration-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migration-patterns
-description: "Zero-downtime DB migrations: expand-contract, double-write, backfill, blue-green schema. Triggers: migration, schema change, zero-downtime, backfill, ALTER TABLE, online DDL, safe deploy."
+description: "Zero-downtime DB migrations: expand-contract, double-write, backfill, blue-green. Triggers: migration, schema change, backfill, ALTER TABLE, online DDL."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/observability-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability-patterns
-description: "Observability: structured logs, metrics (RED/USE), tracing (OpenTelemetry), SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, span, monitoring, alerting."
+description: "Observability: structured logs, metrics (RED/USE), tracing, SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, monitoring."
 effort: medium
 user-invocable: false
 allowed-tools: Read

package/app/skills/performance-profiling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: performance-profiling
-description: "Performance: golden signals (latency/traffic/errors/saturation), p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, load test, memory leak."
+description: "Performance: golden signals, p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, memory leak."
 effort: medium
 allowed-tools: Read, Grep
 user-invocable: false