@softspark/ai-toolkit 3.0.2 → 3.1.1

package/AGENTS.md

@@ -465,8 +465,11 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **commit**: Create Conventional Commits with pre-commit validation
 - **content-moderation-patterns**: Loaded when user builds content moderation, safety filters, or policy enforcement with Claude. Covers pre-filter vs LLM-classify, category design, confidence thresholds, and human-in-the-loop.
 - **council**: 4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'. Codex-adapted: uses native subagents and plan tracking.
+- **cpp-rules**: C++ coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy. Load when writing, reviewing, or editing C++ code.
 - **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.
+- **csharp-rules**: C#/.NET coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cs, .csproj, .sln, ASP.NET, ASP.NET Core, EF Core, LINQ, NUnit, xUnit, dotnet. Load when writing, reviewing, or editing C#/.NET code.
 - **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
+- **dart-rules**: Dart/Flutter coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget. Load when writing, reviewing, or editing Dart/Flutter code.
 - **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 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.
@@ -484,6 +487,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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.
+- **golang-rules**: Go coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt. Load when writing, reviewing, or editing Go code.
 - **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 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
@@ -493,11 +497,14 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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.
+- **java-rules**: Java coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle. Load when writing, reviewing, or editing 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.
+- **kotlin-rules**: Kotlin coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx. Load when writing, reviewing, or editing Kotlin code.
 - **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.
+- **medplum-rules**: Medplum (FHIR healthcare) coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire. Load when writing, reviewing, or editing Medplum (FHIR healthcare) code.
 - **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
 - **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.
@@ -509,6 +516,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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
+- **php-rules**: PHP coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .php, composer.json, Laravel, Symfony, PHPUnit, PSR-12, Composer. Load when writing, reviewing, or editing PHP code.
 - **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
@@ -517,6 +525,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **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.
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
+- **python-rules**: Python coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy. Load when writing, reviewing, or editing Python code.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session. Codex-adapted: uses native subagents and plan tracking.
 - **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
 - **refactor**: Refactor code for quality and maintainability
@@ -526,7 +535,9 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **review**: Review code for quality, security, and correctness
 - **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.
+- **ruby-rules**: Ruby coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop. Load when writing, reviewing, or editing 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.
+- **rust-rules**: Rust coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test. Load when writing, reviewing, or editing Rust code.
 - **search**: Search the knowledge base with semantic and hybrid modes
 - **security-patterns**: Application security: OWASP Top 10, authN/authZ, input validation, secrets management, TLS, CSRF/XSS/SQLi, session handling, JWT, rate limiting, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, encryption, TLS, authentication, authorization, CSP, CORS, password hashing. Load when touching auth code, handling user input, or doing security review.
 - **seo-validate**: Validate code against SEO best practices: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Supports React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML.
@@ -535,12 +546,14 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks. Codex-adapted: uses native subagents and plan tracking.
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms Codex-adapted: uses native subagents and plan tracking.
 - **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.
+- **swift-rules**: Swift coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest. Load when writing, reviewing, or editing 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 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.
+- **typescript-rules**: TypeScript/JavaScript coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint. Load when writing, reviewing, or editing TypeScript/JavaScript code.
 - **ubiquitous-language**: Extract a DDD-style ubiquitous language glossary from the conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, or mentions DDD or domain model.
 - **verification-before-completion**: Loaded when agent is about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before assertions, always.
 - **workflow**: Start and manage autonomous agent workflows Codex-adapted: uses native subagents and plan tracking.

package/CHANGELOG.md

@@ -7,6 +7,41 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.1.1 — Windows install fix (2026-04-29)
+
+Patch release. `ai-toolkit install --local` crashed on Windows before doing any work because `scripts/install_steps/project_registry.py` imported `fcntl` (POSIX-only) at module load, raising `ModuleNotFoundError: No module named 'fcntl'`.
+
+### Fixed
+
+- **Windows install crash** — `project_registry` now imports `fcntl` and `msvcrt` defensively (try/except → `None`) and `_registry_lock()` selects between `fcntl.flock` (POSIX) and `msvcrt.locking` (Windows) at runtime. POSIX semantics unchanged; Windows acquires the lock with `LK_NBLCK` + 30 s deadline + 10 ms retry backoff.
+
+### Added
+
+- **Windows compat regression test** — `tests/test_windows_support.bats` now blocks `import fcntl` via a custom `meta_path` finder, stubs `msvcrt`, and forces the Windows branch of `_registry_lock` so future regressions are caught on the POSIX CI runners without needing a Windows machine.
+
+## v3.1.0 — Global Editor Install Alignment (2026-04-28)
+
+Minor release aligning global and project-local editor configuration with the current documented surfaces for all supported editors.
+
+### Added
+
+- **Global Cline rules** — `ai-toolkit install --editors cline` now writes documented global rules under `~/Documents/Cline/Rules/ai-toolkit-*.md`.
+- **Global Roo Code rules** — `ai-toolkit install --editors roo` now writes documented global rules under `~/.roo/rules/ai-toolkit-*.md`.
+- **Safe global Aider bootstrap** — `ai-toolkit install --editors aider` now creates `~/.aider.conf.yml` only when absent and refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`; existing user YAML is preserved.
+- **Project Roo MCP sync** — `ai-toolkit mcp install --editor roo --scope project ...` and `install --local --editors roo` now mirror canonical `.mcp.json` servers into `.roo/mcp.json`.
+
+### Changed
+
+- **Global editor target policy** — global install now uses only documented, file-based targets: `aider`, `augment`, `cline`, `codex`, `gemini`, `opencode`, `roo`, and `windsurf`.
+- **Cursor rules scope** — Cursor rule generation is now explicitly project-local. Cursor still supports project/global MCP via `.cursor/mcp.json` and `~/.cursor/mcp.json`, but global rule writes are not emitted because Cursor's global user rules are settings-managed rather than a stable merge-safe file.
+- **Release and registry docs** — updated the supported-tools registry, MCP compatibility tables, global install model, release SOP, README platform matrix, and ecosystem doctor snapshot for the April 28, 2026 upstream baseline.
+- **Release SOP meta-generator gate** — registry/generator drift checks now exclude `generate_language_rules_skills.py` alongside docs/index meta-generators, keeping the editor registry focused on editor config generators.
+
+### Fixed
+
+- **SOP compliance gap** — Cline, Roo Code, and Aider global surfaces are now used where documented, while Cursor/Copilot/Antigravity rules remain local-only where no safe global rule file exists.
+- **Release metadata drift** — test count is now synced to 973 across README and validation metadata.
+
 ## v3.0.2 — Validation, Windows, Telemetry, and generate:all parity (2026-04-24)
 
 Patch release that closes known validation gaps, expands the hook-surface contracts, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI so registered custom rules reach every editor.

package/README.md

@@ -1,42 +1,25 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 99 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, 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.
 
 [![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-99-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-112-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-960%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-974%20passing-success)](tests/)
 
----
-
-## What's New in v3.0.2
-
-**3.0.2 is a patch release** that closes known validation gaps, expands the validated hook surface, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI.
-
-- `validate.py` now checks hook handler types, required handler fields, prompt/agent event compatibility, and structured language-rule frontmatter/category coverage.
-- Hook docs and validation now cover `PostToolUseFailure`, `PostToolBatch`, `UserPromptExpansion`, plus `command`, `http`, `prompt`, `agent`, and `mcp_tool` handler types.
-- `ai-toolkit stats --summary` reports local product telemetry: total invocations, unique skills used, catalog coverage, unused skills, recent activity, and top skills.
-- Windows dependency detection now emits package hints for `winget`, Chocolatey, and Scoop; WSL remains the recommended runtime for Bash hooks.
-- `npm run generate:all` now invokes every directory-based rule generator, so registered custom rules in `~/.softspark/ai-toolkit/rules/` propagate to every editor that supports per-rule module files.
+<p align="center">
+  <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
+</p>
 
-### Carried from v3.0.0 (feature release)
-
-- **Deep coverage: every editor at 100% of its native surface.** New generators emit hooks, sub-agents, custom commands, and skill pointers per editor: `generate_cursor_agents.py`, `generate_cursor_hooks.py`, `generate_windsurf_hooks.py`, `generate_gemini_commands.py`, `generate_gemini_hooks.py`, `generate_gemini_skills.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`, `generate_augment_skills.py`, `generate_codex_skills.py`.
-- **`--profile full`** turns on every native surface across all supported editors in one flag. `minimal` / `standard` / `strict` retain prior semantics but `standard` now also wires Gemini hooks and the Copilot directory layout (see Breaking Changes).
-- **Opt-in Codex skill mirroring** via `--codex-skills`. Codex gets the full skill catalog materialized under `.agents/skills/`; other editors stay on pointer-skill or compat-read.
-- **58 new bats tests** covering native surface generators plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
-- **Skill quality pass** (folded in from the 2.12 work that is now skipped): 62 skills upgraded to 4-5 / 5 on the meta-architect audit; `add_gotcha` added as a fifth mutation strategy.
-
-### Breaking changes (from 3.0.0)
+---
 
-- `--profile standard` now installs **Gemini hooks** automatically. To opt out, use `--profile minimal` or pass `--skip gemini-hooks`.
-- Copilot now uses the **directory layout** (`.github/copilot/`) instead of a single monolithic file. Existing single-file installs are preserved but new installs emit the directory form.
-- `2.13.0` is skipped. Upgrade path is `2.12.x` → `3.0.0`.
+## What's New in v3.1.1
 
-### Non-breaking additions (opt-in)
+Patch release fixing the Windows install crash introduced when project registration started using a POSIX-only file lock.
 
-- `.windsurf/hooks.json`, `.cursor/hooks.json`, `.cursor/agents/`, `.augment/agents/`, `.augment/commands/`, `.gemini/commands/`, and `.codex/skills/` are **only emitted when you opt in** via `--profile full` (or `--codex-skills` for the Codex mirror). Existing projects that upgrade to 3.0.0 without changing their install flags will see no new files in those directories — the native surfaces stay dormant until you ask for them.
+- **Windows install no longer crashes** — `ai-toolkit install --local` on Windows hit `ModuleNotFoundError: No module named 'fcntl'` before doing any work. The project registry now selects `fcntl` (POSIX) or `msvcrt.locking` (Windows) at runtime; POSIX semantics are unchanged.
+- **Regression test on POSIX CI** — `tests/test_windows_support.bats` simulates the missing-`fcntl` scenario and exercises the Windows lock branch via a stubbed `msvcrt`, so this regression is caught without a Windows runner.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -53,6 +36,9 @@ See [CHANGELOG.md](CHANGELOG.md) for full history.
 - [Getting Started](#getting-started)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
+- [Security](#security)
+- [License](#license)
+- [Changelog](#changelog)
 
 ---
 
@@ -67,7 +53,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 99 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 112 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).
 
@@ -119,14 +105,14 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Platform | Config Files | Scope |
 |----------|-------------|-------|
 | Claude Code | `~/.claude/` | global |
-| Cursor | `~/.cursor/rules` + `.cursor/rules/*.mdc` | global + project |
+| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` | project (`~/.cursor/mcp.json` for MCP only) |
 | Windsurf | `~/.codeium/.../global_rules.md` + `.windsurf/rules/*.md` | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | global |
 | GitHub Copilot | `.github/copilot-instructions.md` | project |
-| Cline | `.clinerules/*.md` | project |
-| Roo Code | `.roomodes` + `.roo/rules/*.md` | project |
-| Aider | `.aider.conf.yml` + `CONVENTIONS.md` | project |
-| Augment | `.augment/rules/ai-toolkit-*.md` | project |
+| Cline | `~/Documents/Cline/Rules/*.md` + `.clinerules/*.md` | global + project |
+| Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | global rules + project |
+| Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | global + project |
+| Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | global + project |
 | Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | project |
 | Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | project + global plugin |
 | opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | project + global (`~/.config/opencode/`) |
@@ -141,7 +127,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 36 | Domain knowledge auto-loaded by agents |
+| `skills/` (knowledge) | 49 | 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) |
@@ -157,7 +143,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 99 skills (task / hybrid / knowledge)
+│   ├── skills/          # 112 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)
@@ -166,7 +152,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (960 tests)
+├── tests/               # Bats test suite (974 tests)
 └── CHANGELOG.md
 ```
 
@@ -176,7 +162,7 @@ ai-toolkit/
 
 ## Key Features
 
-**Machine-enforced constitution** — 5-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
+**Machine-enforced constitution** — 6-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
 
 **21 lifecycle hooks** — Executable scripts across 12 events (SessionStart → SessionEnd). Guards, governance, quality gates, session persistence, MCP health checks. See [Hooks Catalog](kb/reference/hooks-catalog.md).
 
@@ -198,7 +184,7 @@ ai-toolkit/
 
 **Config inheritance** — Enterprise `extends` system with constitution immutability and enforcement constraints. See [Enterprise Config Guide](kb/reference/enterprise-config-guide.md).
 
-**68 language rules** — 13 languages, 5 categories each. Auto-detected or explicit `--lang`. See [Language Rules](kb/reference/language-rules.md).
+**70 language rules** — 13 languages + common, 5 categories each. Auto-detected or explicit `--lang`. See [Language Rules](kb/reference/language-rules.md).
 
 **26 MCP templates** — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See [MCP Templates](kb/reference/mcp-templates.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": "3.0.2",
+  "version": "3.1.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/cpp-rules/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: cpp-rules
+description: "C++ coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy. Load when writing, reviewing, or editing C++ code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# C++ Rules
+
+These rules come from `app/rules/cpp/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in C++. Apply them when writing or
+reviewing C++ code.
+
+# C++ Coding Style
+
+## Naming
+- PascalCase: classes, structs, enums, type aliases, concepts.
+- camelCase or snake_case: functions, methods, variables (be consistent per project).
+- UPPER_SNAKE: macros, compile-time constants.
+- Prefix member variables with `m_` or suffix with `_` (pick one convention).
+- Namespace names: lowercase, short (`namespace io`, `namespace util`).
+
+## Modern C++ (17/20/23)
+- Use `auto` for iterator types and complex template deductions.
+- Use `std::optional<T>` instead of sentinel values or pointers for optional returns.
+- Use `std::variant` over union types. Use `std::visit` for dispatch.
+- Use `std::string_view` for non-owning string parameters.
+- Use structured bindings: `auto [key, value] = *map.begin();`.
+- Use `constexpr` for compile-time evaluation. Prefer over macros.
+
+## Memory Management
+- Use RAII exclusively. Every resource acquisition is an initialization.
+- Use `std::unique_ptr` for exclusive ownership (default choice).
+- Use `std::shared_ptr` only when ownership is genuinely shared.
+- Never use raw `new`/`delete`. Use `std::make_unique` / `std::make_shared`.
+- Use `std::span<T>` (C++20) for non-owning views over contiguous data.
+
+## Functions
+- Pass small types by value. Pass large types by `const&`.
+- Use `[[nodiscard]]` on functions whose return value must not be ignored.
+- Use `noexcept` on functions that do not throw (move constructors, destructors).
+- Limit function parameters to 4. Use structs for configuration objects.
+- Use trailing return types for complex template return deductions.
+
+## Includes and Dependencies
+- Use `#pragma once` or include guards. Prefer `#pragma once` for simplicity.
+- Order: corresponding header, C++ stdlib, third-party, project headers.
+- Forward-declare in headers when possible to reduce compile times.
+- Minimize header dependencies. Use the Pimpl idiom for ABI stability.
+
+## Avoid
+- Raw pointers for ownership. Use smart pointers.
+- C-style casts. Use `static_cast`, `dynamic_cast`, `const_cast`.
+- Macros for constants or functions. Use `constexpr` and templates.
+- `using namespace std;` in headers. Acceptable in .cpp files with caution.
+- `std::endl` -- use `'\n'` (endl flushes the buffer unnecessarily).
+
+## Formatting
+- Use clang-format with a committed `.clang-format` file.
+- Use clang-tidy for static analysis and automated modernization.
+- Max line length: 100-120 characters.
+- Braces: use Allman or K&R consistently per project.
+
+# C++ Frameworks
+
+## CMake
+- Use modern CMake (3.14+): target-based, not directory-based.
+- Use `target_link_libraries` with `PUBLIC`/`PRIVATE`/`INTERFACE` visibility.
+- Use `FetchContent` for dependency management. Avoid manual submodule vendoring.
+- Set `CMAKE_CXX_STANDARD 20` (or 23) at the project level.
+- Use `target_compile_options` for per-target flags, not global `add_compile_options`.
+- Export targets with `install(TARGETS ... EXPORT ...)` for library consumers.
+
+## Boost
+- Use Boost.Asio for async networking and I/O.
+- Use `boost::beast` for HTTP/WebSocket built on Asio.
+- Use `boost::json` or `nlohmann/json` for JSON parsing.
+- Prefer C++ stdlib equivalents when available (e.g., `std::optional` over `boost::optional`).
+- Link only the Boost libraries you actually use. Many are header-only.
+
+## Qt
+- Use signals and slots for event-driven communication.
+- Use `QObject` parent-child ownership for automatic memory management.
+- Use `QML` for declarative UI. Keep business logic in C++ backend.
+- Use `QThread` with worker objects (moveToThread), not subclassing QThread.
+- Use smart pointers for non-QObject resources. QObject children are auto-deleted.
+
+## gRPC
+- Define services in `.proto` files. Generate C++ stubs with `protoc`.
+- Use async server with `CompletionQueue` for high-throughput services.
+- Use `grpc::ClientContext` for per-call deadlines and metadata.
+- Use interceptors for logging, auth, and metrics.
+- Set deadlines on every RPC call to prevent hanging.
+
+## Networking (Asio)
+- Use `io_context` as the event loop. Run from one or more threads.
+- Use `co_await` (C++20 coroutines) with Asio for clean async code.
+- Use `strand` for serializing access to shared state across handlers.
+- Use `steady_timer` for timeouts and periodic tasks.
+- Handle errors via `error_code` parameter, not exceptions, in async callbacks.
+
+## Database
+- Use `libpq` (PostgreSQL) or `SOCI` for database access.
+- Use prepared statements exclusively. Never concatenate SQL strings.
+- Use connection pooling for multi-threaded server applications.
+- Use `SQLite` via `sqlite3` C API with RAII wrappers for embedded use cases.
+
+## Package Management
+- Use `vcpkg` or `Conan 2` for dependency management.
+- Pin dependency versions in `vcpkg.json` or `conanfile.py`.
+- Use CI caching for build artifacts and dependency downloads.
+- Prefer pre-built binary packages for CI speed.
+
+# C++ Patterns
+
+## Error Handling
+- Use exceptions for truly exceptional conditions. Use return types for expected failures.
+- Use `std::expected<T, E>` (C++23) or `Result<T, E>` pattern for recoverable errors.
+- Use `std::error_code` / `std::error_category` for system-level errors.
+- Use `noexcept` on functions that must not throw (destructors, move operations).
+- Catch by `const&`. Never catch by value (slicing) or pointer.
+
+## RAII Patterns
+- Wrap every resource (memory, file, lock, socket) in an RAII type.
+- Use `std::lock_guard` or `std::scoped_lock` for mutex management.
+- Use `std::unique_lock` when deferred locking or condition variables are needed.
+- Use `std::fstream` (auto-closes) instead of `fopen`/`fclose`.
+- Write custom RAII wrappers for C library resources (file descriptors, handles).
+
+## Smart Pointer Patterns
+- `unique_ptr`: default ownership model. Transfer with `std::move`.
+- `shared_ptr`: use only for genuinely shared ownership graphs.
+- `weak_ptr`: break cycles in `shared_ptr` graphs. Use `lock()` to access.
+- Factory functions should return `unique_ptr`. Let callers upgrade to `shared_ptr`.
+- Never pass smart pointers by reference. Pass `T&` or `T*` to non-owning consumers.
+
+## Concurrency
+- Use `std::thread` with `std::jthread` (C++20) for auto-joining threads.
+- Use `std::mutex` + `std::scoped_lock` for shared data protection.
+- Use `std::atomic<T>` for lock-free single-variable synchronization.
+- Use `std::condition_variable` for producer-consumer patterns.
+- Use `std::async` / `std::future` for simple parallel computation.
+- Use `std::counting_semaphore` (C++20) for resource pool limiting.
+
+## Template Patterns
+- Use CRTP for compile-time polymorphism (static dispatch).
+- Use `concepts` (C++20) to constrain template parameters with clear error messages.
+- Use `if constexpr` for compile-time branching in templates.
+- Use variadic templates and fold expressions for parameter packs.
+- Prefer `constexpr` functions over template metaprogramming when possible.
+
+## Design Patterns
+- Use `std::variant` + `std::visit` for type-safe visitor pattern.
+- Use `std::function` for type-erased callbacks and strategy pattern.
+- Use Pimpl idiom (`unique_ptr<Impl>`) for ABI stability and compilation firewall.
+- Use Builder pattern with method chaining for complex object construction.
+- Use `std::move` semantics in move constructors for efficient resource transfer.
+
+## Anti-Patterns
+- Raw `new`/`delete`: use smart pointers and containers.
+- Returning raw pointers from factory functions: return `unique_ptr`.
+- `const_cast` to remove constness: redesign the interface.
+- Deep inheritance hierarchies: prefer composition and templates.
+- Premature optimization over readability: profile first, optimize second.
+
+# C++ Security
+
+## Buffer Overflow Prevention
+- Use `std::string`, `std::vector`, `std::array` instead of C arrays and `char[]`.
+- Use `std::span` (C++20) for safe, bounds-checked views over contiguous data.
+- Never use `strcpy`, `strcat`, `sprintf`. Use `std::string` operations or `snprintf`.
+- Enable `-D_FORTIFY_SOURCE=2` in release builds for runtime buffer checks.
+- Use `at()` for bounds-checked container access in untrusted input paths.
+
+## Memory Safety
+- Use smart pointers exclusively. Zero raw `new`/`delete` in application code.
+- Enable AddressSanitizer (`-fsanitize=address`) in development and CI builds.
+- Enable UndefinedBehaviorSanitizer (`-fsanitize=undefined`) in test builds.
+- Use `-fstack-protector-strong` for stack buffer overflow detection.
+- Use Valgrind for memory leak detection in integration tests.
+
+## Integer Safety
+- Check for overflow before arithmetic on untrusted integers.
+- Use `std::numeric_limits<T>::max()` for boundary checks.
+- Use unsigned types only for bit manipulation. Prefer signed for arithmetic.
+- Use `static_cast` explicitly. Never rely on implicit narrowing conversions.
+- Enable `-Wconversion` and `-Wsign-conversion` warnings.
+
+## Input Validation
+- Validate all external input: file data, network packets, command-line arguments.
+- Use `std::stoi` / `std::stol` with exception handling for string-to-number conversion.
+- Set maximum sizes for dynamic allocations based on untrusted input.
+- Validate file paths to prevent directory traversal (`../`).
+- Use allowlist validation for format specifiers and command strings.
+
+## Secure Coding
+- Use `std::fill` or `explicit_bzero()` to zero sensitive memory before deallocation.
+- Use constant-time comparison for secrets (avoid timing side-channels).
+- Use `mlock()` to prevent sensitive memory from being swapped to disk.
+- Compile with `-fPIE -pie` for position-independent executables (ASLR).
+- Enable `-Werror` in CI to prevent warnings from becoming vulnerabilities.
+
+## Dependencies
+- Audit third-party C libraries for known CVEs before inclusion.
+- Use `vcpkg` or `Conan` with pinned versions for reproducible builds.
+- Prefer well-maintained libraries with active security response teams.
+- Minimize C library usage. Prefer C++ standard library equivalents.
+
+## Concurrency Safety
+- Use `std::mutex` with `std::scoped_lock` for all shared data access.
+- Use `std::atomic` for lock-free single-variable operations.
+- Enable ThreadSanitizer (`-fsanitize=thread`) in test builds for race detection.
+- Avoid `volatile` for synchronization. It does not provide atomicity or ordering.
+- Use RAII lock guards. Never manually `lock()`/`unlock()`.
+
+## Compiler Hardening
+- Enable all warnings: `-Wall -Wextra -Wpedantic`.
+- Use `-D_GLIBCXX_ASSERTIONS` for debug iterator and container checks.
+- Use `-fno-exceptions` only when exception safety is not required.
+- Link with `-Wl,-z,relro,-z,now` for full RELRO (GOT hardening).
+
+# C++ Testing
+
+## Framework
+- Use GoogleTest (gtest) as the primary test framework.
+- Use GoogleMock (gmock) for mocking interfaces and virtual classes.
+- Use Catch2 as a lightweight alternative (header-only, BDD-style).
+- Use CTest for test discovery and execution via CMake.
+
+## File Naming
+- Test files: `foo_test.cpp` or `test_foo.cpp` in a dedicated `tests/` directory.
+- Mirror source directory structure in test directory.
+- One test file per source file or logical component.
+- Use `CMakeLists.txt` with `add_test()` to register tests.
+
+## Structure (GoogleTest)
+- Use `TEST(SuiteName, TestName)` for simple tests.
+- Use `TEST_F(FixtureName, TestName)` for tests sharing setup/teardown.
+- Use `SetUp()` / `TearDown()` in fixtures for per-test initialization.
+- Keep tests focused: one logical assertion per test case.
+
+## Assertions
+- Use `EXPECT_*` (non-fatal) by default. Use `ASSERT_*` only when continuation is meaningless.
+- `EXPECT_EQ`, `EXPECT_NE`, `EXPECT_LT`, `EXPECT_GT` for comparisons.
+- `EXPECT_TRUE`, `EXPECT_FALSE` for boolean conditions.
+- `EXPECT_THROW(expr, ExceptionType)` for exception testing.
+- `EXPECT_THAT(value, matcher)` with gmock matchers for complex assertions.
+
+## Parameterized Tests
+- Use `INSTANTIATE_TEST_SUITE_P` with `testing::Values(...)` for value-parameterized tests.
+- Use `testing::Combine()` for multi-dimensional parameterization.
+- Use `TYPED_TEST_SUITE` for type-parameterized tests across template types.
+- Prefer parameterized tests over copy-pasting similar test bodies.
+
+## Mocking (GoogleMock)
+- Define mock classes: `MOCK_METHOD(ReturnType, MethodName, (Args), (Qualifiers))`.
+- Use `EXPECT_CALL(mock, Method(matchers)).WillOnce(Return(value))`.
+- Use `NiceMock<T>` to suppress uninteresting call warnings.
+- Use `StrictMock<T>` to fail on any unexpected call.
+- Use dependency injection (constructor) to pass mock objects.
+
+## Build Integration
+- Use `FetchContent` or `find_package` to integrate gtest in CMake.
+- Enable `BUILD_TESTING` option to conditionally include tests.
+- Use `ctest --output-on-failure` for CI runs.
+- Use sanitizers in test builds: `-fsanitize=address,undefined`.
+
+## Best Practices
+- Test edge cases: empty input, max values, null pointers, boundary conditions.
+- Use RAII test fixtures for resource cleanup (no manual teardown).
+- Avoid testing private methods directly. Test through public API.
+- Use `valgrind` or ASan/UBSan in CI to detect memory errors.
+- Keep tests fast: mock I/O and external dependencies.