@softspark/ai-toolkit 3.5.1 → 4.0.1

package/AGENTS.md

@@ -472,7 +472,6 @@ 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 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.
@@ -491,7 +490,6 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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, aggregation, file ownership, map-reduce. Triggers: swarm, hive mind, multi-agent, consensus, parallel 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.
@@ -518,7 +516,6 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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. Triggers: implementation plan, pre-mortem, phased plan, task breakdown.
 - **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.
@@ -538,7 +535,6 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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,7 +544,6 @@ 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.

package/CHANGELOG.md

@@ -7,6 +7,66 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.0.1 — CI hotfix: README "What You Get" table counts (2026-05-06)
+
+Patch release. Fixes CI failure on v4.0.0 main branch — three `tests/test_metadata_contracts.bats` cases failed because the `What You Get` table in `README.md` and the skill type table in `kb/reference/architecture-overview.md` still referenced pre-consolidation counts (32 task / 32 hybrid / 48 knowledge).
+
+### Fixed
+
+- **README.md `What You Get` table**: hybrid 32 → 30, knowledge 48 → 45 (task unchanged at 32; total 107).
+- **`kb/reference/architecture-overview.md`**: same correction in the skill type table.
+- **`manifest.json`**: skill subtype description updated from `(30 task + 31 hybrid + 46 knowledge)` to the correct `(32 task + 30 hybrid + 45 knowledge)`.
+
+### Why
+
+v4.0.0 release path missed these three count locations. They are gated by the metadata contract test suite, which I misread locally (the trailing `ok 1047` line is the *last test number*, not a pass count). Confirmed by re-running `bats tests/test_metadata_contracts.bats` directly, which shows three `not ok` failures.
+
+### Process note
+
+Lesson for future releases: always inspect `bats … 2>&1 | grep "^not ok"` rather than trusting tail of npm test. Updating the release-verification SOP separately.
+
+---
+
+## 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.

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,13 +14,28 @@
 
 ---
 
-## What's New in v3.5.1
+## What's New in v4.0.1
 
-Patch release. Continues v3.5.0 description condensation on 20 skills and fixes generator drift in `GEMINI.md` / `.github/copilot-instructions.md` that was missed by the v3.5.0 release.
+CI hotfix for v4.0.0. Corrects skill subtype counts in `README.md` "What You Get" table and `kb/reference/architecture-overview.md` (hybrid 32 → 30, knowledge 48 → 45). The metadata contract tests caught the drift on CI; v4.0.0 release path missed three count locations. No skill catalog changes — see v4.0.0 below for the actual consolidation.
 
-- **20 skills further trimmed** — `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`. Removes redundant trigger keywords already implied by the summary.
-- **Platform artifacts re-synced** — `AGENTS.md`, `llms-full.txt`, `GEMINI.md`, `.github/copilot-instructions.md` regenerated to match the condensed source descriptions.
-- **`/audit.sarif` ignored** — build artifact from `audit_skills.py --ci` no longer pollutes `git status`.
+## What's New in v4.0.0
+
+**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.
+
+- **`/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.
 
@@ -54,7 +69,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).
 
@@ -127,8 +142,8 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Component | Count | Description |
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
-| `skills/` (hybrid) | 32 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 48 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
+| `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
+| `skills/` (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
@@ -144,7 +159,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.1",
+  "version": "4.0.1",
   "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/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/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/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/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/persona/SKILL.md

@@ -69,6 +69,6 @@ Unlike `--persona` at install time (which injects into CLAUDE.md permanently), `
 ## When NOT to Use
 
 - For **permanent** persona injection at install time — use `ai-toolkit install --persona <name>` (project or global)
-- For multi-agent parallel work with different specialists — use `/orchestrate` or `/teams`
+- For multi-agent parallel work with different specialists — use `/orchestrate` or `/workflow`
 - For a specific language or framework context (not a general engineering stance) — use the language-pattern skills (`/typescript-patterns`, etc.)
 - To edit or create a persona file — edit `app/personas/<name>.md` directly; this skill only switches between existing ones

package/app/skills/plan/SKILL.md

@@ -46,6 +46,28 @@ smart_query("project template: {type}")
 hybrid_search_kb("architecture {pattern}")
 ```
 
+## Estimation & Templates
+
+### T-shirt sizing (use for >1 day work)
+
+| Size | Effort | Example |
+|------|--------|---------|
+| XS | <2h | typo, add field |
+| S | 2-4h | simple component, basic API |
+| M | 1-2 days | feature with tests |
+| L | 3-5 days | complex feature |
+| XL | 1-2 weeks | major subsystem |
+
+Avoid hour-precise estimates beyond a week — they are false confidence (cone of uncertainty: 4× variance at idea, 1.5× at design).
+
+### SMART tasks vs phase outcomes
+
+Plan-level tasks should be **phase-aligned outcomes** ("authentication ships behind a feature flag"), not SMART implementation steps ("add JWT middleware"). The latter belongs in the issue tracker after `/prd-to-issues`.
+
+### Pre-mortem (mandatory for >1 day plans)
+
+List ≥5 named failure modes with mitigation. A 2-bullet pre-mortem is theater. Risk register cap: 10 entries ranked by (probability × impact); below line 10 is noise.
+
 ## Related Skills
 
 - Plan approved? -> `/orchestrate` or `/workflow` to execute with agents

package/app/skills/refactor-plan/SKILL.md

@@ -126,5 +126,5 @@ What is explicitly NOT part of this refactor.
 - For **executing** a refactor directly — use `/refactor`
 - For architecture-level audit without a specific refactor in mind — use `/architecture-audit`
 - For creating a PRD (product requirements) — use `/write-a-prd`
-- For a plan without the GitHub RFC step — use `/plan` or `/plan-writing`
+- For a plan without the GitHub RFC step — use `/plan`
 - For interface design of a single module — use `/design-an-interface`

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

@@ -43,6 +43,18 @@ You MUST search in this order. Do not skip steps.
 **Why**: Fallback for general programming concepts.
 **Rule**: Use only for generic syntax/logic, NEVER for project specifics.
 
+## Local Fallback (No MCP Available)
+
+If `rag-mcp` is not configured, fall back to filesystem tools — still inside `kb/`:
+
+```
+Grep   pattern="your query"   path="kb/"   # search file contents
+Glob   pattern="kb/**/*.md"                # list KB files
+Read   "kb/reference/architecture.md"      # full document
+```
+
+Always cite sources as `[PATH: kb/...]` regardless of which method retrieved them.
+
 ## 🛑 Validation Protocol
 Before acting on information:
 1. **Cite the Source**: "According to `kb/architecture.md`..."

package/app/skills/swarm/SKILL.md

@@ -30,7 +30,7 @@ Agent(subagent_type="...", prompt="sub-task 2 — own files: path/b/")
 Agent(subagent_type="...", prompt="sub-task N — own files: path/n/")
 ```
 
-After all complete: aggregate results with `hive-mind` skill, produce synthesis report.
+After all complete: aggregate results (see Aggregation section below), produce synthesis report.
 
 ### Consensus
 Same problem, 3 independent agents from different angles. Launch all 3 **in a single response**.
@@ -75,10 +75,15 @@ Agent(
 
 ## Aggregation (after all agents complete)
 
-1. Collect all agent outputs
-2. De-duplicate identical findings
-3. Synthesize unique insights
-4. Generate final swarm report
+1. **Collect** all agent outputs into a uniform format (JSON or Markdown sections)
+2. **De-duplicate** identical findings across agents
+3. **Synthesize** unique insights into one report
+4. **For Consensus mode**: weighted voting — each agent returns confidence 0.0–1.0, winner is highest-confidence solution; record dissents from agents that scored below winner
+5. **Generate** final swarm report
+
+### File ownership during aggregation
+
+When agents touch overlapping paths despite ownership rules: do NOT auto-merge. Escalate to user citing which two agents touched the same hunk. Use `--worktree` mode to prevent this proactively (see below).
 
 ## KB-First Mode (`--with-kb`)
 

package/kb/procedures/release-verification-sop.md

@@ -201,7 +201,7 @@ python3 scripts/audit_skills.py --ci
 **Verify audit_skills.py:**
 - [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
 - [ ] `WARN: 0`
-- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, teams)
+- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, workflow)
 
 ---
 

package/kb/reference/architecture-overview.md

@@ -186,8 +186,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 32 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 48 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 45 |
 
 ## Multi-Agent Execution
 

package/kb/reference/codex-cli-compatibility.md

@@ -80,7 +80,6 @@ The main adapted group is multi-agent orchestration:
 - `/orchestrate`
 - `/workflow`
 - `/swarm`
-- `/teams`
 - `/subagent-development`
 
 The adapter also covers skills that previously depended only on Claude's

package/kb/reference/opencode-compatibility.md

@@ -129,7 +129,7 @@ User-authored opencode files and user-authored `opencode.json` keys are never de
 ## Behavioral Limits
 
 - opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
-- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/teams`, `/subagent-development`) run through the Codex adaptation layer — they use opencode subagents and explicit file ownership instead of Claude's `Agent`/`TaskCreate` primitives.
+- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/subagent-development`) run through the Codex adaptation layer — they use opencode subagents and explicit file ownership instead of Claude's `Agent`/`TaskCreate` primitives.
 
 ## Verification
 

package/kb/reference/skills-catalog.md

@@ -23,7 +23,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (32)
+## Task Skills (30)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -76,13 +76,11 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **analyze** | `/analyze` | medium | Analyze code quality, complexity, and patterns |
 | **cve-scan** | `/cve-scan` | medium | Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, ruby, dart) |
 | **docs** | `/docs` | high | Generate/update docs: README, API docs, architecture notes, changelogs (Tier 1 — single agent) |
-| **search** | `/search` | medium | Search knowledge base (MCP tools with local fallback) |
 | **explain** | `/explain` | medium | Explain architecture of a file/module using Mermaid diagrams |
 | **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, native in Claude, Codex-adapted to `spawn_agent` workflows |
 | **swarm** | `/swarm` | max | Massive parallelism: map-reduce, consensus, relay — Tier 3 |
 | **workflow** | `/workflow` | max | 15 predefined multi-agent workflow types — Tier 2, Codex-adapted to native subagent orchestration |
 | **instinct-review** | `/instinct-review` | low | Review, curate, and manage learned instincts from past sessions |
-| **teams** | `/teams` | max | Launch pre-configured Agent Teams compositions for common workflows |
 | **write-a-prd** | `/write-a-prd` | high | Create PRD through interactive interview, codebase exploration, and module design |
 | **prd-to-plan** | `/prd-to-plan` | high | Convert PRD into phased implementation plan using tracer-bullet vertical slices |
 | **tdd** | `/tdd` | high | Test-driven development with red-green-refactor loop and vertical slices |
@@ -163,24 +161,16 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **content-moderation-patterns** | `skills/content-moderation-patterns/` | Two-stage moderation: pre-filter + LLM classifier; categories; thresholds |
 | **model-routing-patterns** | `skills/model-routing-patterns/` | Haiku/Sonnet/Opus routing; escalation; sub-agent delegation; fallback |
 
-## Knowledge Skills - Process (7)
+## Knowledge Skills - Process (5)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
-| **plan-writing** | `skills/plan-writing/` | Implementation plans, success criteria, pre-mortem |
-| **debugging-tactics** | `skills/debugging-tactics/` | Iron Law 4-phase debugging: root cause → pattern → hypothesis → fix |
 | **git-mastery** | `skills/git-mastery/` | Git workflows, branching, conflict resolution |
 | **architecture-decision** | `skills/architecture-decision/` | Architecture notes, trade-off analysis, alternatives |
 | **performance-profiling** | `skills/performance-profiling/` | Profiling, bottleneck analysis, optimization |
 | **research-mastery** | `skills/research-mastery/` | Multi-source research, synthesis, fact-checking |
 | **verification-before-completion** | `skills/verification-before-completion/` | Iron Law: evidence-before-claims, no completion without fresh verification |
 
-## Knowledge Skills - Orchestration (1)
-
-| Skill | Directory | Domain |
-|-------|-----------|--------|
-| **hive-mind** | `skills/hive-mind/` | Multi-agent aggregation, consensus, swarm patterns |
-
 ## Quality Guardrails
 
 ### Anti-Rationalization Tables
@@ -272,7 +262,6 @@ Common adapted skills:
 - `/orchestrate`
 - `/workflow`
 - `/swarm`
-- `/teams`
 - `/subagent-development`
 - `/tdd`