@softspark/ai-toolkit 2.10.1 → 2.12.0

package/AGENTS.md

@@ -448,17 +448,17 @@ Skills are invocable commands or auto-loaded knowledge sources:
 
 - **a11y-validate**: Validate code against accessibility standards: WCAG 2.1 Level AA, EN 301 549, and the European Accessibility Act (EAA / Directive EU 2019/882). Covers semantics, text alternatives, keyboard/focus, color/contrast, forms, media, ARIA, motion, mobile, and EAA documentation requirements. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/React Native/Flutter/static HTML).
 - **agent-creator**: Creates new specialized agents with frontmatter, tool selection, and delegation guidance
-- **analyze**: Analyze code quality, complexity, and patterns
+- **analyze**: Analyze code quality, complexity, and patterns across a codebase. Use when the user asks for a quality report, hotspot scan, or systemic architecture signal — not for fixing bugs or reviewing a single PR.
 - **api-patterns**: REST and GraphQL API design patterns: resource naming, versioning, pagination, error contracts, idempotency, HATEOAS, OpenAPI. Triggers: API design, REST, GraphQL, endpoint, route, OpenAPI, Swagger, pagination, rate limit, versioning, idempotency key. Load when designing or reviewing any HTTP API surface.
 - **app-builder**: Full-stack app scaffolding with stack-selection matrix: Next.js, React+Vite, Nuxt, Astro, FastAPI, Django, Laravel, React Native, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter template, build app, landing page, dashboard, API, mobile app, CLI, e-commerce, game. Load when user wants to start a new project from scratch.
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling. Codex-adapted: uses native subagents and plan tracking.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
 - **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
 - **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
-- **briefing**: Generate executive daily briefing across all agents
-- **build**: Build the project with auto-detected toolchain
-- **chaos**: Inject controlled faults for resilience testing
-- **ci**: Detect and run CI pipeline with status reporting
+- **briefing**: Generate an executive daily briefing that aggregates reports from all agents into a short, decision-focused summary. Use when the user asks for a status update across the whole system — not for one-agent activity reports.
+- **build**: Build the project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Use when the user asks to compile, bundle, or produce artifacts — not to run tests or deploy.
+- **chaos**: Inject controlled faults for resilience testing on non-production targets. Use when the user explicitly asks for a chaos experiment, latency injection, or dependency kill — never implicit.
+- **ci**: Detect, generate, or troubleshoot CI/CD pipeline configuration for the current project type (GitHub Actions, GitLab CI). Use when the user asks to set up, update, or debug a build pipeline — not for running tests locally.
 - **ci-cd-patterns**: CI/CD pipeline and deployment automation: GitHub Actions, GitLab CI, Jenkins, build stages, caching, artifact promotion, blue-green, canary, rollback gates. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, deploy automation, release, artifact, rollout, canary, blue-green. Load when designing or fixing a build/release pipeline.
 - **clean-code**: Code quality principles: meaningful names, single responsibility, DRY, small functions, clear intent, guard clauses, refactoring rules. Triggers: clean code, naming, refactor for clarity, code smell, SRP, DRY, long function, god class, magic number, dead code. Load when reviewing or writing any production code.
 - **command-creator**: Creates new Claude Code slash commands with frontmatter, workflow guidance, and validation
@@ -468,7 +468,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **csharp-patterns**: C# and .NET development patterns: LINQ, async/await, dependency injection, records, nullable reference types, ASP.NET Core minimal APIs, EF Core, MediatR. Triggers: C#, .NET, dotnet, ASP.NET, EF Core, LINQ, IServiceCollection, record type, async C#, nullable reference types. Load when writing or reviewing C#/.NET code.
 - **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
 - **database-patterns**: Database schema design and query optimization: normalization, indexing strategies, joins, N+1, transactions, isolation levels, partitioning, EXPLAIN plans. Triggers: schema, table design, index, slow query, N+1, PostgreSQL, MySQL, SQL Server, SQL, EXPLAIN, query plan, transaction, deadlock. Load when designing tables or tuning queries.
-- **debug**: Debug errors and trace root causes systematically
+- **debug**: Debug errors and trace root causes systematically using logs, health checks, and hypothesis-driven investigation. Use when a bug or error message is in hand — not for architectural questions or when there is no reproducible symptom.
 - **debugging-tactics**: Root-cause debugging with 4-phase method: investigation, hypothesis, validation, fix. No fix without RCA. Triggers: bug, error, exception, stack trace, not working, intermittent, flaky, crash, regression, fails sometimes, why is X happening, broken after. Load when user reports a bug or asks to investigate failing code.
 - **deploy**: Deploy with pre-flight checks and health verification
 - **design-an-interface**: Generate multiple radically different interface designs using parallel sub-agents, then compare on simplicity, depth, and correctness. Based on 'Design It Twice' from Ousterhout. Use when user wants to design an API, explore interface options, compare module shapes, or mentions 'design it twice'. Codex-adapted: uses native subagents and plan tracking.
@@ -477,42 +477,42 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **docs**: Generate and update README, API docs, and architecture notes
 - **documentation-standards**: KB document conventions: YAML frontmatter (7 required fields), 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices), directory-category matching, validate.sh CI rules. Triggers: kb/, KB document, architecture note, SOP, runbook, howto, frontmatter, knowledge base entry, documentation standard. Load when creating or editing any file under kb/.
 - **ecommerce-patterns**: E-commerce domain patterns: cart, checkout flow, payment providers (Stripe/Adyen), order state machine, inventory, promotions, tax, B2B vs B2C. Triggers: cart, checkout, product, SKU, inventory, payment, Stripe, Shopify, Medusa, Magento, order status, promotion, tax calculation, coupon, refund. Load when working on any e-commerce feature.
-- **evaluate**: Evaluate skill quality and RAG retrieval accuracy
+- **evaluate**: Evaluate RAG retrieval accuracy and LLM-as-a-judge quality metrics (faithfulness, relevancy, context precision) against a golden dataset. Use when the user asks to measure RAG quality or detect knowledge gaps — not for evaluating generic LLM outputs.
 - **evolve**: Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures.
-- **explain**: Explain code, architecture, or concepts with diagrams
+- **explain**: Explain code, architecture, or concepts with Mermaid diagrams and sequence flows. Use when the user asks 'what does X do' or 'how does Y work' — not to critique code quality or implement changes.
 - **explore**: Explore codebase structure, stack, and architecture
-- **fix**: Auto-fix lint errors, type issues, and simple bugs
+- **fix**: Apply a targeted fix to a known bug or lint error and verify it with the same command that surfaced the problem. Use when the root cause is already identified — not for unknown symptoms or open-ended debugging.
 - **flutter-patterns**: Flutter and Dart development patterns: widget composition, state management (Riverpod/Bloc/Provider), navigation, async, platform channels, performance. Triggers: Flutter, Dart, widget, StatefulWidget, Riverpod, Bloc, Provider, pubspec, Navigator, platform channel, hot reload, StatelessWidget. Load when writing or reviewing Flutter code.
 - **git-mastery**: Advanced Git workflows: interactive rebase, bisect, reflog, cherry-pick, worktrees, history rewriting, submodules, large-file migration (LFS/filter-repo). Triggers: git rebase, bisect, cherry-pick, reflog, force push, history rewrite, detached HEAD, merge conflict, worktree, squash, fixup, submodule. Load when user needs non-trivial Git operations.
 - **grill-me**: Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'. Codex-adapted: uses native subagents and plan tracking.
-- **health**: Report service and infrastructure health status
+- **health**: Report service and infrastructure health status via liveness/readiness checks, resource usage, and quick diagnostics. Use when the user asks whether services are up or degraded — not for deep debugging of a known error.
 - **hipaa-validate**: Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references
 - **hive-mind**: Multi-agent swarm coordination: consensus voting with confidence scores, output aggregation, file ownership, targeted vs broadcast messaging, map-reduce workflows. Triggers: swarm, hive mind, multi-agent, consensus, parallel agents, team of agents, aggregate results, agent voting, distributed agents. Load when orchestrating 3+ agents working in parallel.
-- **hook-creator**: Creates new Claude Code hooks with guided workflow, strict conventions, and validation
-- **index**: Index codebase into the knowledge base
-- **instinct-review**: Review and manage learned instincts from past sessions
+- **hook-creator**: Create a new Claude Code lifecycle hook (PreToolUse, PostToolUse, Stop, SessionStart, etc.) with a bash script and hooks.json registration. Use when the user wants automated behavior tied to a specific event — not for one-off commands.
+- **index**: Reindex the knowledge base for semantic search via the configured vector store (e.g., Qdrant). Use only when the user explicitly asks to reindex — never trigger speculative rebuilds.
+- **instinct-review**: Review, promote, or remove learned instincts extracted from past sessions (`.claude/instincts/*.md`). Use when the user wants to curate the instinct list — not to extract new instincts or edit memory.
 - **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
 - **java-patterns**: Java development patterns: Spring Boot, CompletableFuture, records, sealed types, streams, JPA/Hibernate, Maven/Gradle, virtual threads (Loom). Triggers: Java, Spring, Spring Boot, JPA, Hibernate, Maven, Gradle, CompletableFuture, record type, sealed class, virtual thread. Load when writing or reviewing Java code.
 - **json-mode-patterns**: Loaded when user needs structured JSON output from Claude. Covers tool-use-as-JSON-mode, schema design, parsing, partial recovery, and validation.
 - **kotlin-patterns**: Kotlin development patterns: coroutines, Flow, sealed classes, data classes, extension functions, null safety, Ktor, Jetpack Compose, KMP. Triggers: Kotlin, coroutine, Flow, suspend, Ktor, Android Kotlin, Jetpack Compose, sealed class, data class, KMP, kotlinx. Load when writing or reviewing Kotlin code.
-- **lint**: Lint code with auto-detected tools and fix suggestions
+- **lint**: Run the project's linter and type-checker with auto-detected toolchain (ruff/mypy, eslint/tsc, phpstan, golangci-lint, clippy, dart analyze). Use when the user asks for static-analysis feedback — not to run tests or refactor.
 - **mcp-builder**: Build production-grade MCP (Model Context Protocol) servers from scratch using the 4-phase methodology: research, implement, test, evaluate. Use when creating new MCP integrations for external APIs, databases, or internal services.
 - **mcp-patterns**: MCP (Model Context Protocol) server design: tool schemas, resource patterns, transport selection (stdio/SSE), client configuration, error handling, capability negotiation. Triggers: MCP, Model Context Protocol, MCP server, MCP tool, MCP resource, JSON-RPC, stdio transport, SSE transport, Claude Desktop config, Cursor MCP. Load when building or integrating MCP servers.
 - **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
-- **migrate**: Run database migrations with backup verification
+- **migrate**: Run or create database migrations with the detected tool (Alembic, Prisma, Laravel, Django, Flyway, Drizzle) and verify backups exist first. Use when the user asks to apply, roll back, or generate a migration — not for general schema design.
 - **migration-patterns**: Zero-downtime database migration patterns: expand-contract, double-write, backfill, blue-green schema changes, feature flags, rollback safety, online DDL. Triggers: migration, schema change, zero-downtime, expand-contract, double-write, backfill, ALTER TABLE, column rename, safe deploy, online DDL. Load when planning non-trivial DB schema changes.
 - **model-routing-patterns**: Loaded when user builds multi-model pipelines (Haiku/Sonnet/Opus). Covers cost-optimized routing, escalation, sub-agent delegation, and fallback chains.
-- **night-watch**: Run autonomous maintenance and dependency updates
+- **night-watch**: Run autonomous maintenance tasks (dependency updates, dead code removal, small refactors) in an isolated branch. Use only when the user triggers it explicitly — typically off-hours; never auto-invoked.
 - **observability-patterns**: Observability: structured logging, metrics (RED/USE/four golden signals), distributed tracing (OpenTelemetry), correlation IDs, log aggregation, SLO/SLI. Triggers: logging, log level, metrics, Prometheus, Grafana, OpenTelemetry, trace, span, structured log, observability, monitoring, SLO, SLI, alerting. Load when adding or reviewing logs, metrics, or traces.
-- **onboard**: Generate project onboarding materials
+- **onboard**: Guide setup of ai-toolkit in a new project: install symlinks, create CLAUDE.md, capture undocumented intent via interview. Use when the user starts a fresh project or migrates an existing one to ai-toolkit.
 - **orchestrate**: Coordinate multiple specialized agents in parallel Codex-adapted: uses native subagents and plan tracking.
-- **panic**: Emergency stabilization via system-governor agent
+- **panic**: Emergency kill switch that halts all agent activity via a lockfile gate. Use when agents are looping, misbehaving, or the user wants to stop everything NOW — not for normal workflow interruptions.
 - **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
 - **plan**: Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases.
 - **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
-- **pr**: Create pull requests with pre-flight validation
+- **pr**: Create a GitHub pull request after running pre-flight checks (lint, typecheck, tests) and generating a structured summary from commit history. Use when the branch is ready to merge — not for drafting work-in-progress.
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets. Codex-adapted: uses native subagents and plan tracking.
 - **predict**: Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff.
@@ -524,7 +524,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **repeat**: Run a prompt or slash command on a recurring interval until task complete or limits reached. Use when user wants to set up a recurring task, poll for status, or run something repeatedly on an interval. Codex-adapted: uses native subagents and plan tracking.
 - **research-mastery**: Hierarchical information retrieval following strict order: KB first (smart_query/crag_search), then MCP/Context7, then web search, then LLM knowledge as last resort. Triggers: research, find information, verify fact, synthesize sources, fact-check, cross-reference, multi-source, cite sources, investigate topic. Load when any task requires external or cross-source knowledge.
 - **review**: Review code for quality, security, and correctness
-- **rollback**: Roll back a deployment safely with verification
+- **rollback**: Roll back a git commit, database migration, or deployment to a previous known-good state with safety checks and health verification. Use when the user wants to revert recent changes safely — not to undo local edits or halt the whole system.
 - **ruby-patterns**: Ruby and Rails development patterns: blocks, metaprogramming, ActiveRecord, Sidekiq, RSpec, Sorbet/RBS, Hanami, Roda, Rack middleware. Triggers: Ruby, Rails, ActiveRecord, Sidekiq, RSpec, gem, Gemfile, bundler, rake, Hanami, Sorbet. Load when writing or reviewing Ruby code.
 - **rust-patterns**: Rust development patterns: ownership, borrowing, lifetimes, async (Tokio), error handling (Result/anyhow/thiserror), traits, macros, zero-cost abstractions, unsafe boundaries. Triggers: Rust, borrow checker, lifetime, Tokio, async Rust, cargo, trait, impl, Result, unsafe, lifetime annotation, clippy. Load when writing or reviewing Rust code.
 - **search**: Search the knowledge base with semantic and hybrid modes
@@ -537,7 +537,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation. Codex-adapted: uses native subagents and plan tracking.
 - **teams**: Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task. Codex-adapted: uses native subagents and plan tracking.
-- **test**: Run tests with coverage analysis and reporting
+- **test**: Run the project's test suite with coverage reporting, auto-detecting the framework (pytest, vitest, jest, flutter test, go test, cargo test, phpunit). Use when the user asks to run existing tests — not to author new ones test-first.
 - **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan. Codex-adapted: uses native subagents and plan tracking.
 - **typescript-patterns**: TypeScript type safety patterns: strict mode, generics, conditional types, template literals, discriminated unions, branded types, Zod, satisfies operator, const assertions. Triggers: TypeScript, TS, generics, conditional type, utility type, strict, Zod, satisfies, discriminated union, type safety, type narrowing, template literal type. Load when writing or reviewing TypeScript code.

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.12.0 — Skill Quality Pass (Rules + Gotchas + When NOT to Use) (2026-04-23)
+
+### Added
+- **Meta-architect audit criteria across 62 skills** — every previously low-scoring skill (2-3/5 on the 5-criterion meta-architect audit) gained three new sections:
+  - `## Rules` — prescriptive MUST / NEVER / CRITICAL / MANDATORY markers for non-negotiable process constraints
+  - `## Gotchas` — Anthropic-recommended section for environment-specific traps and domain surprises (only where genuine traps exist; not padded)
+  - `## When NOT to Use` — explicit boundary with 2-5 adjacent skills to prevent over-triggering
+- **`meta-architect.md` mutation strategy taxonomy extended** — added `add_gotcha` as a fifth strategy alongside `add_example`, `add_constraint`, `add_edge_case`, `restructure`. Clarifies that Rules (prescriptive) and Gotchas (environment-specific) are distinct semantic buckets.
+- **`skill-creator/SKILL.md` and `command-creator/SKILL.md` templates updated** — new skills now default to the three-section pattern (Rules + optional Gotchas + When NOT to Use). Quality checklist extended to match.
+- **`scripts/evaluate_skills.py` — `_meta_architect_audit()` function** — non-failing advisory scoring per skill against the 5 binary criteria (description ≥50 chars, example, constraint, edge_case, length). Surfaces bottom-10 watchlist in every evaluation run.
+- **rag-mcp KB integration**: new document `kb/troubleshooting/rag-failure-patterns.md` (12-pattern taxonomy P01-P12) adapted from `awesome-llm-apps/rag_tutorials/rag_failure_diagnostics_clinic/`. New planning doc `kb/planning/toon-output-format-spike.md` proposes a timeboxed benchmark of TOON vs JSON output format for search tool responses.
+
+### Changed
+- **14 task skills (wave-1)** upgraded from 2/5 to 5/5 audit score: `analyze`, `chaos`, `ci`, `debug`, `evaluate`, `health`, `index`, `mem-search`, `night-watch`, `onboard`, `panic`, `performance-profiling`, `pr`, `test`. Short frontmatter descriptions extended with trigger hints; hard-rule markers added; explicit sibling-skill boundaries documented.
+- **48 task and knowledge skills (wave-2)** upgraded from 3/5 to 5/5: `agent-creator`, `api-patterns`, `app-builder`, `architecture-audit`, `architecture-decision`, `biz-scan`, `brand-voice`, `briefing`, `build`, `ci-cd-patterns`, `content-moderation-patterns`, `database-patterns`, `design-engineering`, `docker-devops`, `ecommerce-patterns`, `evolve`, `explain`, `explore`, `fix`, `git-mastery`, `grill-me`, `hipaa-validate`, `hook-creator`, `instinct-review`, `introspect`, `lint`, `mcp-builder`, `migrate`, `migration-patterns`, `observability-patterns`, `persona`, `plan`, `plan-writing`, `plugin-creator`, `prd-to-issues`, `prd-to-plan`, `predict`, `qa-session`, `rag-patterns`, `refactor`, `refactor-plan`, `rollback`, `security-patterns`, `skill-audit`, `swift-patterns`, `testing-patterns`, `triage-issue`, `ubiquitous-language`.
+- **`swift-patterns/SKILL.md` restructured** — 108-line `Common Frameworks` section moved to `reference/frameworks.md` (progressive disclosure per Anthropic spec), room reclaimed for Rules/Gotchas/When NOT to Load. SKILL.md now 420 lines (under 500 limit).
+
+### Notes
+- Score distribution: `{2: 14, 3: 48, 4: 32, 5: 5}` → `{4: 33, 5: 66}`. Zero skills remain below 4/5.
+- Approach validated against official Anthropic guidance (`agentskills.io/skill-creation/best-practices.md`): Gotchas section is Anthropic-recommended; prescriptive negative instructions (MUST/NEVER) and default-plus-escape-hatch (When NOT to Use) map to documented patterns.
+- Changes are **additive** — no existing skill content removed; sections appended or, in the case of `swift-patterns`, relocated to a reference subdirectory. Test count unchanged (669). No new skills or agents added, so counts unchanged (44 agents, 99 skills).
+
+---
+
+## v2.11.0 — JSON Wire Format Rules (2026-04-21)
+
+### Added
+- **`app/rules/common/coding-style.md` v1.2.0 — JSON Wire Format Conventions section** — `camelCase` for field names (JSON:API, Google JSON Style, Symfony Serializer + `json_serializable` defaults), `UPPER_SNAKE_CASE` for enum/status/permission values (Protocol Buffers style guide, Google AIP-126 / api-linter, Zalando Rule #240, Java/Kotlin/C++/Python consensus). Explicit call-out that `camelCase` for enum VALUES is an anti-pattern with no major public API precedent.
+- **`app/rules/php/frameworks.md` v1.1.0 — Symfony Serializer section** — documents the `property-names-used-as-is` default, the global-override side effect of `api_platform.name_converter` ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)), pragmatic `#[SerializedName]` usage (only when justified), and the Symfony 7.3.5+ `ObjectNormalizer` `isXxx` behavior change ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)) that makes pre-7.3.5 `SerializedName` aliases redundant. API Platform section extended with `operation_name` metadata note.
+- **`app/rules/dart/frameworks.md` v1.1.0 — JSON Serialization section** — `json_serializable` `FieldRename.none` default + Effective Dart `lowerCamelCase` = `camelCase` JSON keys without configuration; community recommendation to prefer class-level `fieldRename` over per-field `@JsonKey(name:)`; enum value strategy (`UPPER_SNAKE_CASE` on wire, Dart case names stay `lowerCamelCase`).
+- **`tests/test_rules_content.bats` (3 bats cases)** — smoke tests guarding the three new rule sections (`JSON Wire Format Conventions`, `Symfony Serializer`, `JSON Serialization`). Heading-only checks, intentionally non-brittle. Test count: 666 → 669.
+
+### Notes
+- Changes are additive — no existing rule text removed or reworded. Projects that ran `ai-toolkit install --local` before v2.11.0 will pick up the new sections on next re-run (install is idempotent — existing TOOLKIT markers get replaced, not duplicated).
+- Rules codify documented facts + widely-cited community consensus, not project-specific enforcement. Project-level SOPs (grep gates, migration workflows, whitelists) remain in each project's `kb/procedures/`.
+
+---
+
 ## v2.10.1 — Art. VI Enforcement Drift Repair (2026-04-21)
 
 ### Fixed

package/README.md

@@ -6,16 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-666%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-669%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.10.1
+## What's New in v2.12.0
 
-- **Art. VI enforcement drift repaired** — `IMMUTABLE_ARTICLES` in `config_merger.py` and `config_validator.py` extended to include Article 6, so downstream `extends:` configs can no longer override Repair Discipline. Enterprise config schema, CLI diff label, and doc surfaces updated to match.
-- **Generator emits Article VI** — `scripts/emission.py::generate_quality_standards()` now includes Article VI's four clauses; `AGENTS.md`, `GEMINI.md`, `llms-full.txt`, and editor rule files (`.clinerules`, `.roo`, `.windsurf`, `.augment`, `.agents`, `.github/copilot-instructions.md`) all regenerated.
-- **Constitution self-consistency** — Article I.3 "Max 3" aligned to Section 4's "maximum 5 iterations". `validate.py --strict` now fails on article-count drift between `app/constitution.md` and downstream catalogs; the lint parses `## Article <roman>:` headings and fails on stale count or roman-range literals elsewhere.
-- **SKILL.md improvements from #8** (merged from @rohan-tessl) — `biz-scan`, `evolve`, `plan`, `predict`, and `teams` got richer descriptions, executable protocol steps, and structured report templates; team preset details moved to `teams/reference/presets.md` for progressive disclosure. 5 skills total, totals unchanged: 44 agents, 99 skills, 666 tests.
+- **Skill quality pass across 62 skills (14 wave-1 at 2/5 + 48 wave-2 at 3/5)** — every previously low-scoring skill now ships with a `## Rules` section (MUST / NEVER / CRITICAL markers), an optional `## Gotchas` section (Anthropic-recommended environment-specific traps), and a `## When NOT to Use` section naming 2-5 adjacent skills. Score distribution shifted from `{2: 14, 3: 48, 4: 32, 5: 5}` to `{4: 33, 5: 66}` — zero skills below 4/5.
+- **Meta-architect mutation strategy extended** — `add_gotcha` added as a fifth strategy alongside `add_example`, `add_constraint`, `add_edge_case`, `restructure`. Rules and Gotchas are distinct semantic buckets; `skill-creator` and `command-creator` templates now default to the three-section pattern.
+- **`scripts/evaluate_skills.py` — `_meta_architect_audit()` advisory** — non-failing per-skill scoring against 5 binary criteria (description ≥50 chars, example, constraint, edge_case, length). Bottom-10 watchlist surfaced on every `npm run evaluate`.
+- **`swift-patterns` restructured** — 108-line `Common Frameworks` section extracted to `reference/frameworks.md` (progressive disclosure per Anthropic spec). SKILL.md now fits under 500 lines with room for the new sections.
+- **rag-mcp KB** gained `kb/troubleshooting/rag-failure-patterns.md` (12-pattern failure taxonomy P01-P12) and `kb/planning/toon-output-format-spike.md` (timeboxed TOON vs JSON benchmark plan).
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -143,7 +144,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (666 tests)
+├── tests/               # Bats test suite (669 tests)
 └── CHANGELOG.md
 ```
 

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": "2.10.1",
+  "version": "2.12.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/meta-architect.md

@@ -56,3 +56,47 @@ Recurring failure in `backend-specialist` regarding timezone handling.
 ### Expected Impact
 Timezone bugs reduced by 90%.
 ```
+
+## Skill Mutation Strategies
+
+When iterating on a skill or agent prompt, pick **exactly one** of the five strategies below per round. Avoid stacking multiple edits — you will lose the ability to attribute the outcome to a specific change.
+
+| Strategy         | When to apply                                                                            | Example                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `add_example`    | Failures show the model misunderstanding the intended shape of the output                | Add a worked `Input → Output` pair demonstrating the correct pattern    |
+| `add_constraint` | Failures show the model doing extra or wrong things that are not explicitly forbidden    | Add a `MUST NOT` / `CRITICAL` rule to a `## Rules` section              |
+| `add_gotcha`     | Failures show the model making reasonable assumptions that are wrong for THIS environment | Add a concrete trap to a `## Gotchas` section (Anthropic's recommended pattern) |
+| `restructure`    | Failures are spread across many cases and the prompt reads as a wall of equal-weight text | Reorganize into sections with priorities, or split into two sub-skills |
+| `add_edge_case`  | Failures cluster on a specific boundary (empty input, 1 item, 100 items, unicode, etc.)  | Add an explicit rule or example covering that edge case                 |
+
+**Rules vs Gotchas:** `add_constraint` writes prescriptive process rules (always-true MUST / NEVER). `add_gotcha` writes environment-specific facts the agent would miss without being told (e.g., *"the `/health` endpoint returns 200 even when the DB is down — use `/ready` for full health"*). Both land in the skill body but under different headers.
+
+If the score does not improve after a mutation, **revert** and try a different strategy. Never keep a change that reduced the score.
+
+## Binary Evaluation Criteria
+
+Prefer **binary yes/no criteria** over Likert scales when scoring skill or agent outputs. Binary is:
+
+- Cheaper (one boolean per criterion vs. fuzzy 1-5 scale).
+- Deterministic across multiple judge runs.
+- Easier to attribute to a specific prompt rule.
+
+A good binary criterion is testable from the output alone:
+
+- ✅ "Does the output include a `[PATH: ...]` citation?"
+- ✅ "Is the list exactly 5 items or fewer?"
+- ❌ "Is the answer helpful?" (not testable, too fuzzy)
+
+Aim for **4-6 criteria per skill** during evaluation. Score = criteria-passed / criteria-total.
+
+## Iterative Optimization Loop
+
+When optimizing a skill, follow the **Executor / Analyst / Mutator** loop (adapted from Karpathy's autoresearch and the `awesome-llm-apps` self-improving-skills template):
+
+1. **Baseline** — run the skill against all test scenarios, score each output against all binary criteria.
+2. **Analyze** — examine failing criteria, pick the dominant failure pattern, select one mutation strategy.
+3. **Mutate** — apply exactly one edit from the strategy table above.
+4. **Re-score** — run again, compare to baseline. Keep if score improved, revert otherwise.
+5. **Repeat** until target pass rate reached or max rounds (default 10) hit.
+
+This is not a new agent or script — it is a **protocol**. Apply it by hand when you update a skill, or delegate the execution loop to a `/workflow` run if the skill is critical.

package/app/rules/common/coding-style.md

@@ -1,7 +1,7 @@
 ---
 language: common
 category: coding-style
-version: "1.1.0"
+version: "1.2.0"
 ---
 
 # Universal Coding Style
@@ -69,6 +69,13 @@ version: "1.1.0"
   `1. [Step] → verify: [check]`
 - Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.
 
+## JSON Wire Format Conventions
+- Field names (keys): `camelCase`. Aligns with JSON:API spec, Google JSON Style Guide, and framework defaults (Symfony Serializer, Spring Jackson, `json_serializable` for Dart). No public major API uses `snake_case` keys in modern designs except ecosystem-bound cases (Rails/Django APIs defaulting to ecosystem convention).
+- Enum / status / permission / domain values: `UPPER_SNAKE_CASE`. Community consensus: [Protocol Buffers style guide](https://protobuf.dev/programming-guides/style/) (mandatory), [Google AIP-126 / api-linter](https://linter.aip.dev/126/upper-snake-values) (enforced), [Zalando Rule #240](https://opensource.zalando.com/restful-api-guidelines/), Java/Kotlin/C++/Python enum convention. `lowercase snake_case` (Stripe-style) is a legitimate outlier but not consensus.
+- Avoid `camelCase` for enum values — no major public API uses it, loses visual distinction between keys and values.
+- Pick one convention per project and enforce it with a CI grep gate. Mixing conventions inside a single API surface is the worst outcome.
+- External contracts (Stripe, GitHub, webhooks you receive) follow their own convention — map to your project convention at the adapter boundary, do not leak their keys past it.
+
 ## Anti-Patterns to Avoid
 - God classes/modules with 500+ lines and multiple responsibilities.
 - Deep nesting (>3 levels): use early returns and extract functions.

package/app/rules/dart/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: dart
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # Dart Frameworks
@@ -27,6 +27,14 @@ version: "1.0.0"
 - Set timeouts on every request: `connectTimeout`, `receiveTimeout`.
 - Use `CancelToken` for cancelling in-flight requests on navigation.
 
+## JSON Serialization
+- Use `json_serializable` (+ `build_runner`) for generated `fromJson`/`toJson`. Default `fieldRename: FieldRename.none` uses Dart property names as-is — combined with Effective Dart `lowerCamelCase`, this produces `camelCase` JSON keys with zero configuration.
+- Flutter docs recommend: *"best if both server and client follow the same naming strategy"* ([Flutter — JSON and serialization](https://docs.flutter.dev/data-and-backend/serialization/json)). When they do, no mapping is needed.
+- When server uses a different convention, prefer `@JsonSerializable(fieldRename: FieldRename.snake)` at the class level (or globally in `build.yaml`) over sprinkling `@JsonKey(name:)` on every field. Community recommendation from the `json_serializable` docs and pub.dev guides.
+- Use individual `@JsonKey(name: '...')` only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (`class`, `is`, `new`), or legacy field rename during deprecation window. Document the reason in a comment.
+- For enum / status / permission values on the wire: `UPPER_SNAKE_CASE` is the cross-language community consensus (see `common/coding-style.md` — JSON Wire Format Conventions). Dart enum case names themselves stay `lowerCamelCase` per Effective Dart; map them to uppercase strings in `fromJson`/`toJson` (`value.toUpperCase()` + `switch`).
+- Write unit tests asserting both directions (`fromJson` + `toJson`) with explicit expected keys. Catches contract drift at CI time.
+
 ## Local Storage
 - Use `shared_preferences` for simple key-value persistence.
 - Use `drift` (formerly Moor) for type-safe SQLite with reactive queries.

package/app/rules/php/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: php
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # PHP Frameworks
@@ -36,12 +36,21 @@ version: "1.0.0"
 - Use migrations: `bin/console doctrine:migrations:diff` and `migrate`.
 - Use lifecycle callbacks (`@PrePersist`, `@PostUpdate`) for entity events.
 
+## Symfony Serializer
+- Default behavior uses property names as-is. Combined with PSR-12 `camelCase` property names, JSON output is `camelCase` with zero configuration.
+- Avoid adding `api_platform.name_converter: CamelCaseToSnakeCaseNameConverter` globally. Known side-effect ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)): overrides the project-wide `MetadataAwareNameConverter`, affecting Messenger serializers, custom normalizers, and CLI JSON output — not just the HTTP API.
+- Use `#[SerializedName]` only when justified: legacy field alias during rename, external contract mapping, ObjectNormalizer cross-version stabilization. Community practice ([Symfony docs](https://symfony.com/doc/current/serializer.html), Sylius, SymfonyCasts): prefer clean property/getter naming over aliases. When using, document the reason next to the attribute.
+- Symfony 7.3.5+ `ObjectNormalizer` produces `isActive` natively for a `isActive(): bool` getter ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)). Older `#[SerializedName('isActive')]` aliases added for pre-7.3.5 `ObjectNormalizer` (which produced `active`) are redundant after upgrade — remove them.
+- Avoid duplicate getters like `isActive()` + `getIsActive()` on the same property — `ObjectNormalizer` treats them as two fields and serializes ambiguously. Keep one (`isXxx()` for booleans, `getXxx()` otherwise).
+
 ## API Platform
 - Use API Platform for rapid REST/GraphQL API generation from entities.
 - Use `#[ApiResource]` attribute for automatic CRUD endpoint generation.
 - Use custom state providers and processors for business logic.
 - Use serialization groups for controlling response shape.
 - Use filters for query parameter support: pagination, search, ordering.
+- Property names on `ApiResource` DTOs drive JSON keys directly (see Symfony Serializer above). Write them in `camelCase` — that is both the Symfony default and the dominant JSON API convention.
+- Use `operation_name` in `extraProperties` for dispatch metadata (e.g., `extraProperties: ['operation_name' => 'club_activate']`). The key `operation_name` and its `snake_case` values are framework metadata, not JSON wire keys — keeping them `snake_case` is expected.
 
 ## Livewire (Laravel)
 - Use Livewire components for reactive UI without JavaScript.

package/app/skills/agent-creator/SKILL.md

@@ -37,12 +37,13 @@ skills: skill-one, skill-two
 
 ## Authoring Rules
 
-- Match filename and `name` exactly using lowercase-hyphen format
-- Keep the description trigger-rich and operational
-- Give the agent a clear boundary: what it owns and what it should escalate
-- Prefer specialized, narrow responsibility over generic “do everything” agents
-- Reference only existing skills unless the task also includes creating the missing skill
-- Avoid tool bloat; every extra tool increases risk and ambiguity
+- **MUST** match filename and `name:` using lowercase-hyphen format — drift breaks routing
+- **MUST** include an explicit `Triggers:` list in the description so the router can dispatch deterministically
+- **NEVER** reference skills that do not exist — either create the dependency first or drop the reference
+- **NEVER** grant write access to `.claude/agents/` — that authority belongs to `meta-architect` alone
+- **CRITICAL**: avoid tool bloat. Every extra tool widens blast radius; start from `Read` and justify additions one by one
+- Give the agent a clear boundary: what it owns and what it must escalate
+- Prefer specialized, narrow responsibility over generic "do everything" agents
 
 ## Agent Skeleton
 
@@ -80,3 +81,18 @@ You are a specialized agent for {domain}.
 - [ ] Model choice matches expected complexity
 - [ ] `scripts/validate.py` passes after adding the agent
 
+## Gotchas
+
+- The `description` is the **only** content the model sees at routing time (progressive disclosure, tier 1). Adding triggers to the body without putting them in `description` means the agent is invisible to the router.
+- `tools:` parser acceptance varies between Claude Code, ai-toolkit adapters, and downstream consumers — some accept comma-separated, some space-separated, some YAML lists. Stick to one style consistent with neighbouring agents in the repo and let `scripts/validate.py` catch drift.
+- Agent `name` is capped at 64 chars; some consumers silently truncate longer names, which then **fail to match** the filename at load time. Keep names short and unambiguous.
+- `skills:` can reference skills inside plugin packs; if the user has not enabled that pack, the agent fails on first invocation with an opaque "skill not found" error. Either reference only in-tree skills, or document the plugin prerequisite in the agent body.
+
+## When NOT to Use
+
+- For a **skill** (slash command or knowledge doc) — use `/skill-creator` instead
+- For a **slash command** that is *not* an agent delegate — use `/command-creator`
+- For a **plugin pack** bundling multiple agents and skills — use `/plugin-creator`
+- To *modify* an existing agent — delegate to the `meta-architect` agent; this skill is create-only
+- When the task is really a workflow (orchestrator + N specialists) — reach for `/orchestrate` or `/workflow` before minting a new agent
+

package/app/skills/analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze
-description: "Analyze code quality, complexity, and patterns"
+description: "Analyze code quality, complexity, and patterns across a codebase. Use when the user asks for a quality report, hotspot scan, or systemic architecture signal — not for fixing bugs or reviewing a single PR."
 user-invocable: true
 effort: medium
 argument-hint: "[path or pattern]"
@@ -100,6 +100,26 @@ Reports file counts by type, largest files, TODO/FIXME counts, and total code li
 | Go | golangci-lint |
 | Rust | clippy |
 
+## Rules
+
+- **MUST** report measured values — never assert "this is fine" without numbers
+- **NEVER** modify source files (read-only skill)
+- **CRITICAL**: if the requested analysis type is unsupported for the detected language, say so explicitly and stop — do not fake metrics
+
+## Gotchas
+
+- Linters that exit `0` still may have **skipped** files (gitignore rules, no-match patterns, parse errors). Always read the "N files checked" line before reporting "clean".
+- Coverage percentages silently exclude generated code, migrations, and `__init__.py` by default. Report coverage with the exclude list, not the headline number alone.
+- `ruff` and `pylint` disagree on several rules (line length, import order) — pick one as the source of truth for the project and note the choice in the report.
+- `mypy --strict` on a codebase that was not authored under strict mode will return hundreds of spurious findings. Start with `--ignore-missing-imports` and a file allowlist before claiming the codebase is untyped.
+
+## When NOT to Use
+
+- For a single-PR code review — use `/review` instead
+- For fixing a specific bug — use `/debug` or `/fix`
+- For architectural friction and module design — use `/architecture-audit`
+- For a vulnerability scan of dependencies — use `/cve-scan`
+
 ## Related Skills
 - Found quality issues? → `/refactor` to fix them systematically
 - Security issues detected? → `/cve-scan` for dependency audit

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

@@ -302,6 +302,16 @@ Accept: application/vnd.myapi.v1+json
 | "Error messages are just for debugging" | Error responses are your API's UX — clients depend on consistent, parseable errors |
 | "PATCH and PUT are the same thing" | PUT replaces the resource, PATCH modifies it — wrong semantics cause data loss |
 
+## Hard Rules
+
+- **MUST** version the API from day one (URL path or Accept header) — unversioned APIs break clients on every change
+- **MUST** validate every input at the API boundary, not inside business logic
+- **MUST** use PUT for full replacement and PATCH for partial update — confusing the two causes silent data loss
+- **NEVER** return unbounded list responses — pagination (offset or cursor) is mandatory
+- **NEVER** expose stack traces or internal error details in 5xx responses — clients get a `code`, `message`, and optional `details[]`
+- **CRITICAL**: idempotency on POST/PUT/PATCH is non-negotiable when retries are possible — accept an `Idempotency-Key` header or design the endpoint to be naturally idempotent
+- **CRITICAL**: rate limits exist from the first deploy, not "later" — unprotected endpoints get abused within hours
+
 ## Best Practices
 
 - [ ] Use HTTPS only
@@ -314,3 +324,20 @@ Accept: application/vnd.myapi.v1+json
 - [ ] Document with OpenAPI/Swagger
 - [ ] Log requests for debugging
 - [ ] Set reasonable timeouts
+
+## Gotchas
+
+- CDN and load-balancer caches key on the full URL by default. If you version via both URL path and `Accept` header (e.g., `/api/v1/...` + `Accept: application/vnd.myapi.v2+json`), the edge returns the wrong payload for non-path versioning. Pick one versioning axis and stick to it.
+- OpenAPI `additionalProperties: false` is **not** enforced by most JSON Schema validators unless you explicitly enable strict mode (`ajv({strict: true})`, Pydantic `Config.extra = "forbid"`). An API marked "strict" in the spec silently accepts unknown fields.
+- `Idempotency-Key` only works if the server persists the mapping from key to response — purely in-memory implementations forget it on restart. Back it with Redis or the primary DB.
+- HTTP methods are **case-sensitive** per RFC 7230 (all uppercase); some clients and proxies normalize, some don't. A `post` method reaches the server as-is through some edge proxies and hits a 405 instead of the POST route.
+- `429 Too Many Requests` without a `Retry-After` header leaves clients guessing — most libraries back off exponentially from zero and hammer the server. Always include `Retry-After` on 429 and 503.
+
+## When NOT to Load
+
+- For **MCP protocol** (JSON-RPC over stdio/SSE) specifics — use `/mcp-patterns`; this skill covers generic JSON-RPC only
+- For **gRPC, GraphQL subscriptions, or message queues** — outside scope; this skill is REST-first with a JSON-RPC aside
+- For **language-specific idioms** (Fastify middleware chains, ASP.NET minimal APIs, etc.) — pair this skill with `/typescript-patterns`, `/csharp-patterns`, etc.
+- For **OpenAPI schema authoring** as the primary task — use `/docs` with OpenAPI output; this skill is design-only
+- For **authentication deep-dives** beyond the starter API-key and JWT snippets — use `/security-patterns`
+

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

@@ -186,3 +186,27 @@ project/
 - ❌ Don't hardcode config
 - ❌ Don't ignore accessibility
 - ❌ Don't over-engineer early
+
+## Rules
+
+- **MUST** confirm the stack selection with the user before scaffolding — the matrix above is a default, not a verdict
+- **MUST** include `.gitignore`, `.env.example`, a README, a linter config, and a working test harness in every scaffold
+- **NEVER** overwrite an existing project directory without the user's explicit go-ahead
+- **NEVER** scaffold Create React App or other EOL starters — steer to Vite, Next.js, or Astro instead
+- **CRITICAL**: prefer the team's existing expertise over trend-chasing. If the team ships Laravel, scaffolding FastAPI "because it's faster" creates training debt that outweighs the runtime gain.
+
+## Gotchas
+
+- Next.js App Router (`app/`) and Pages Router (`pages/`) can coexist technically, but middleware, layouts, and loading-state conventions diverge. Pick one router per project and never mix inside a single feature — debugging the overlap wastes hours.
+- Expo Router (file-based, Expo SDK 49+) and React Navigation (imperative) use completely different navigation APIs. Tutorials mix freely; an agent copying code across the split produces uncompilable projects.
+- Prisma on SQLite silently ignores features that work on Postgres: no `CHECK` constraints, no deferrable foreign keys, no array columns, limited `enum` support. Dev-on-SQLite / prod-on-Postgres teams hit this at deploy time.
+- FastAPI `--reload` uses a file watcher that rebuilds Pydantic models on every edit — startup time doubles and benchmark numbers are unreliable. Disable reload for perf tests.
+- `npm create vite@latest` respects `--template` but `npx create-next-app@latest` prompts interactively even with flags. Fully unattended scaffolds need `--ts --tailwind --eslint --app --src-dir --import-alias` spelled out.
+
+## When NOT to Load
+
+- For modifying an **existing** project's stack — use `/migrate` or `/refactor-plan`
+- For adding a feature to a running app — use `/plan` and the relevant language-pattern skill (`/typescript-patterns`, etc.)
+- For onboarding to an unfamiliar codebase — use `/onboard` or `/explore`
+- For deciding between 2-3 specific stacks under stated constraints — use `/architecture-decision`
+- For plugin or agent scaffolding inside ai-toolkit itself — use `/plugin-creator`, `/agent-creator`

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

@@ -139,3 +139,27 @@ Durable guidance NOT coupled to file paths:
 ## Testing Principle
 
 **Replace, don't layer.** Old unit tests on shallow modules are waste once boundary tests exist — delete them. Tests assert on observable outcomes through public interface, not internal state.
+
+## Rules
+
+- **MUST** explore the codebase organically (Explore sub-agent) before proposing deepening targets — do not anchor on what you already know
+- **MUST** present numbered candidates to the user and wait for selection before step 3 — auto-picking skips the product decision
+- **NEVER** design interfaces in step 2; interface work only happens in step 4 after the problem space is framed
+- **CRITICAL**: step 4 spawns **parallel** sub-agents with genuinely different constraints (minimize / maximize-flexibility / optimize-common / ports-adapters). Sequential variations of the same idea defeat the purpose.
+- **MANDATORY**: deliverable is a GitHub issue RFC created via `gh issue create`. Never open a PR from this skill.
+
+## Gotchas
+
+- "Depth" is measured against **actual call patterns**, not the method count. A module exporting 20 functions where callers only use 2 is effectively 2-deep — the other 18 are dead interface, not richness.
+- Shared TypeScript types and Python protocols count as coupling. A "just types" file imported by 30 modules creates a deep blast radius; deleting or renaming it is structurally significant even though no runtime code moves.
+- Parallel sub-agents collapse into echo chambers when their constraints are not sharply different. Spell out the **opposing** tensions ("minimize interface" vs "maximize flexibility") — soft variations produce near-identical designs.
+- `gh issue create` without `--body` or `--body-file` opens `$EDITOR`. In automated flows this hangs the skill indefinitely. Always pass the body explicitly.
+- Ports & Adapters introduces indirection that IDE "find references" and static analysis sometimes miss (dynamic dispatch via interface). Count on broken tooling during the transition period and compensate with runtime smoke tests.
+
+## When NOT to Use
+
+- For executing a known refactor plan — use `/refactor` (direct edits) or `/refactor-plan` (incremental)
+- For designing a single module's interface from scratch — use `/design-an-interface`
+- For deciding between 2-3 named architectural options — use `/architecture-decision`
+- For code-quality metrics (complexity, duplication, coverage) — use `/analyze`
+- For understanding a codebase without proposing changes — use `/explore`

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

@@ -53,3 +53,27 @@ We will use PostgreSQL 16.
 - **Maintainability** (Simple vs Easy, Ecosystem)
 - **Security** (AuthN/Z, Encryption)
 - **Cost** (Infrastructure, License, Cognitive load)
+
+## Rules
+
+- **MUST** present at least 3 viable options, including "status quo / do nothing" when relevant
+- **MUST** state constraints (budget, time, team skillset, legacy) **before** enumerating options — options without constraints are arbitrary
+- **NEVER** recommend an option without explicitly naming its failure mode and what would trigger revisiting the decision
+- **CRITICAL**: the output is a document (ADR / RFC / RFD), not code changes. Code work belongs in `/plan` or `/refactor-plan`.
+- **MANDATORY**: `Consequences` section names both Positive and Negative effects. A decision with only upside is not honestly analysed.
+
+## Gotchas
+
+- "Status quo" is a genuine option and often the right one for constrained teams. Omitting it biases the analysis toward change for change's sake.
+- ADRs are **append-only**. A reversed decision gets a new ADR with `Status: Supersedes ADR-N`, not an in-place edit of the original — the history of thinking matters more than the current state.
+- Qualitative scales (High / Medium / Low) without anchors are hand-waving. When scoring, pin each level to a measurable threshold (e.g., "High scalability = 10k req/s at p95 < 100ms on 2 nodes").
+- "We might use X" and "We will try X" are not decisions — they are deferrals. A valid ADR states the chosen option unconditionally; if you cannot, the decision is not ready.
+- Political constraints (team expertise, vendor relationships, executive preferences) are first-class constraints. Hiding them behind technical language produces ADRs that get silently ignored — name them explicitly in the Constraints section.
+
+## When NOT to Load
+
+- To find **what** architectural problems exist — use `/architecture-audit` (discovery) before this skill (decision)
+- To plan implementation of an already-decided option — use `/plan` or `/refactor-plan`
+- To design a single module's interface — use `/design-an-interface`
+- When fewer than 2 options exist — there is no decision to make; document the constraint instead
+- For runtime configuration choices (flag values, timeouts) — those are operational, not architectural

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

@@ -84,3 +84,27 @@ Output a structured markdown report:
 ### Data Exposure Gaps
 - [Entity] has [N fields] not exposed via any API endpoint
 ```
+
+## Rules
+
+- **MUST** tie every opportunity to a concrete business metric or KPI name — "improve onboarding" is not an opportunity, "increase trial-to-paid conversion" is
+- **MUST** rank the opportunity list by estimated impact (rough order of magnitude is enough) — alphabetical order hides the signal
+- **NEVER** propose a new tracking event without first checking for an existing one — duplicate events corrupt analytics pipelines
+- **CRITICAL**: output is advisory. Do not modify tracking code in the scan. The product owner decides what ships.
+- **MANDATORY**: when the codebase has no analytics layer at all, say so explicitly and stop — the gap is "no instrumentation", not "no opportunities".
+
+## Gotchas
+
+- ORM models and TypeScript/Zod types often drift. An entity may exist in the DB schema but be invisible to the API layer (and vice-versa) — grep both sides before declaring "no tracking coverage".
+- Feature flags without analytics wiring are invisible to most scans. A flag can gate a feature with zero rollout data; treat a flag-without-exposure as its own gap category.
+- "No tracking event on entity X" often means X is tracked via a parent event (e.g., `order_items` piggybacking on `order_completed`). Walk the event taxonomy one level up before calling a gap.
+- Revenue attribution in multi-tenant apps often splits client-side (page views, clicks) from server-side (conversions). Scanning only one side produces systematically wrong conclusions about monetization coverage.
+- Migration files may show deleted columns that live code no longer references — always check the current schema (`alembic current`, `prisma migrate status`) before treating a migration-declared field as live.
+
+## When NOT to Use
+
+- For **implementing** a tracking change — use `/fix` or the relevant language skill
+- For dashboard design or SQL queries — delegate to the `data-analyst` agent
+- For generic code-quality metrics — use `/analyze`
+- For security or CVE scans — use `/cve-scan` or `/security-patterns`
+- When the project has no product-analytics layer configured — document the gap, do not speculate on events