@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/rules/css.md

@@ -0,0 +1,52 @@
+---
+name: css
+description: Code style and best practice rules for CSS, SCSS, and Less.
+globs:
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.less"
+---
+
+# CSS Rules
+
+## Style
+- Use BEM naming convention: `.block__element--modifier`; keep class names lowercase with hyphens
+- Use custom properties (`--color-primary: #0066cc`) for all design tokens: colors, spacing, fonts, radii
+- Define custom properties on `:root` for global tokens; scope component tokens on the component selector
+- Use `rem` for font sizes and spacing; use `px` only for borders and fine details like box shadows
+- Order declarations logically: positioning, display/layout, box model, typography, visual, animation
+- Use shorthand properties (`margin`, `padding`, `border`) only when setting all sides; use longhand for single-side overrides
+- Keep selectors under 3 levels of specificity; never use `!important` except for utility overrides
+- One declaration per line; include a space after the colon and before the opening brace
+- Use meaningful class names that describe purpose, not appearance: `.card-header` not `.big-blue-text`
+- In SCSS, limit nesting to 3 levels maximum; flatten deeply nested selectors into new BEM classes
+
+## Patterns
+- Use CSS Grid for two-dimensional layouts (rows and columns); use Flexbox for one-dimensional alignment
+- Use `gap` property on Grid and Flex containers instead of margins on children
+- Use logical properties (`margin-inline-start`, `padding-block-end`) instead of physical properties for internationalization
+- Use `clamp()` for responsive typography: `font-size: clamp(1rem, 2.5vw, 2rem)`
+- Use `@media (prefers-color-scheme: dark)` for dark mode; toggle custom properties rather than rewriting rules
+- Use `@container` queries for component-level responsive design when supported; fall back to media queries
+- Use `aspect-ratio` property instead of the padding-top hack for maintaining element proportions
+- Use `:is()` and `:where()` pseudo-classes to group selectors and reduce repetition
+- Use `@layer` for managing cascade priority across utility classes, components, and third-party styles
+- Use `prefers-reduced-motion: reduce` to disable animations for accessibility; provide static fallbacks
+- Use `will-change` sparingly and only on elements that are about to animate; remove after animation completes
+
+## Avoid
+- Never use ID selectors (`#header`) for styling; IDs are for JavaScript hooks and anchor links
+- Never use inline styles in HTML; all styles belong in stylesheets or CSS-in-JS with class extraction
+- Never use `float` for layout; it is a legacy technique superseded by Grid and Flexbox
+- Never use `@import` in plain CSS for performance; use build tool bundling or `@use` in SCSS
+- Never hardcode color values in component styles; reference custom properties or design tokens
+- Never use `z-index` values above 100 without a documented z-index scale for the project
+- Never use `*` universal selector in component styles; it causes unnecessary style recalculation
+- Never animate `width`, `height`, `top`, or `left`; animate `transform` and `opacity` for GPU-accelerated performance
+
+## Testing
+- Use Stylelint with a shared config in CI; fix all warnings before merging
+- Test responsive layouts at standard breakpoints: 320px, 768px, 1024px, 1440px minimum
+- Verify color contrast meets WCAG 2.1 AA (4.5:1 for text, 3:1 for large text) using automated tools
+- Test dark mode by toggling `prefers-color-scheme` in DevTools; verify all text remains readable
+- Use visual regression testing (Percy, Chromatic, or BackstopJS) for component libraries

package/assets/rules/go.md

@@ -0,0 +1,50 @@
+---
+name: go
+description: Code style and best practice rules for Go.
+globs:
+  - "**/*.go"
+---
+
+# Go Rules
+
+## Style
+- Use `gofmt` and `goimports` on every file; never commit unformatted code
+- Use `MixedCaps` (exported) and `mixedCaps` (unexported); never use underscores in Go names except in test files
+- Keep package names short, lowercase, single-word; the package name should not repeat the import path
+- Place the package comment directly above the `package` declaration in `doc.go` or the primary file
+- Group imports: stdlib, external, internal; separated by blank lines, sorted within each group
+- Declare variables close to where they are first used; avoid package-level `var` unless truly global
+- Keep functions under 50 lines; extract helper functions with descriptive names for complex logic
+- Use named return values only for documentation in short functions; avoid naked returns
+- Receiver names should be one or two letters, consistent across all methods of a type
+- Accept interfaces, return concrete types; define interfaces at the consumer, not the implementer
+
+## Patterns
+- Always check errors immediately after the call; never discard with `_` unless you add a comment explaining why
+- Wrap errors with `fmt.Errorf("operation: %w", err)` to build an error chain; use `%w` not `%v`
+- Pass `context.Context` as the first parameter to functions that perform I/O or may be cancelled
+- Use `defer` for cleanup immediately after acquiring a resource; order defers intentionally
+- Use goroutines only with clear ownership; always ensure every goroutine can terminate
+- Use channels for communication between goroutines; use `sync.Mutex` only for protecting shared state
+- Use `sync.WaitGroup` or `errgroup.Group` to wait for concurrent work to complete
+- Prefer `errors.Is()` and `errors.As()` over type assertions or string matching on error messages
+- Use struct embedding for composition, not inheritance; embed interfaces only in concrete types
+- Use `context.WithTimeout` or `context.WithCancel` for all operations that may hang
+- Use `io.Reader` and `io.Writer` interfaces for streaming data; avoid loading entire files into memory
+
+## Avoid
+- Never use `init()` functions for anything other than registering drivers or codecs
+- Never use `panic` for expected error conditions; reserve it for truly unrecoverable programmer errors
+- Never use `interface{}` or `any` without immediately asserting or switching on the concrete type
+- Never launch a goroutine without a plan for how it will stop (cancellation, done channel, or context)
+- Never use `time.Sleep` in production code for synchronization; use channels, tickers, or context deadlines
+- Never ignore the second return value from map lookups, type assertions, or channel receives
+- Never use global mutable state; pass dependencies explicitly via function parameters or struct fields
+
+## Testing
+- Use table-driven tests with `t.Run` sub-tests for each case; name sub-tests descriptively
+- Use `t.Helper()` in test helper functions so failures report the correct call site
+- Use `t.Parallel()` for tests that do not share state to speed up the test suite
+- Use `testify/assert` or `testify/require` for readable assertions; use `require` for fatal preconditions
+- Use `httptest.NewServer` for HTTP integration tests; never hit real external services
+- Place test fixtures in a `testdata/` directory; Go tooling ignores this directory automatically

package/assets/rules/html.md

@@ -0,0 +1,52 @@
+---
+name: html
+description: Code style and best practice rules for HTML.
+globs:
+  - "**/*.html"
+  - "**/*.htm"
+---
+
+# HTML Rules
+
+## Style
+- Use lowercase for all element names, attribute names, and attribute values (except `ARIA` and `data-*` values)
+- Use double quotes for attribute values: `class="container"` not `class='container'`
+- Use 2-space indentation for nested elements; never use tabs
+- Place block-level elements on their own line; inline elements may remain on the same line as their parent
+- Include the `lang` attribute on the `<html>` element: `<html lang="en">`
+- Include `<meta charset="UTF-8">` as the first child of `<head>`
+- Include `<meta name="viewport" content="width=device-width, initial-scale=1">` for responsive design
+- Self-close void elements without a slash in HTML5: `<img>`, `<br>`, `<input>`, `<meta>`, `<link>`
+- Order attributes: `id`, `class`, `name`, `data-*`, `src`/`href`, `type`, `alt`/`title`, ARIA, `role`
+- Keep templates under 150 lines; extract reusable partials or components for repeated markup
+
+## Patterns
+- Use semantic elements: `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<footer>` instead of generic `<div>`
+- Use `<button>` for clickable actions and `<a>` for navigation; never use `<div onclick>`
+- Use the `<picture>` element with `<source>` for art direction and format selection (WebP, AVIF fallbacks)
+- Use `loading="lazy"` on images and iframes below the fold; omit it for above-the-fold hero images
+- Use `<label>` explicitly associated with form controls via `for` attribute matching the input `id`
+- Use `<fieldset>` and `<legend>` to group related form controls; use `<optgroup>` in long `<select>` lists
+- Use `<time datetime="2024-01-15">` for machine-readable dates; use `<abbr title="...">` for abbreviations
+- Use `<details>` and `<summary>` for expandable content instead of JavaScript-driven toggles
+- Use `aria-label`, `aria-labelledby`, and `aria-describedby` when visible text does not sufficiently describe an element
+- Use `role="alert"` for dynamic error messages and `role="status"` for non-critical live updates
+- Provide `alt` text on all `<img>` elements; use `alt=""` for decorative images to hide them from screen readers
+
+## Avoid
+- Never use `<table>` for layout; tables are for tabular data only
+- Never use `<br>` for spacing; use CSS `margin` or `padding` instead
+- Never use `<b>` or `<i>` for styling; use `<strong>` for importance and `<em>` for emphasis, or use CSS
+- Never omit `alt` attributes on `<img>` elements; missing `alt` fails WCAG 2.1 Level A
+- Never use `autofocus` on elements that are not the primary interaction point of the page
+- Never use `tabindex` values greater than 0; use 0 for focusable elements and -1 for programmatic focus only
+- Never use `target="_blank"` without `rel="noopener noreferrer"` to prevent reverse tabnapping
+- Never nest interactive elements (`<a>` inside `<button>`, `<button>` inside `<a>`)
+- Never use `placeholder` as a substitute for `<label>`; placeholders disappear on focus and lack contrast
+
+## Testing
+- Validate HTML with the W3C Markup Validation Service or `html-validate` in CI
+- Run `axe-core` or Lighthouse accessibility audit; fix all critical and serious violations
+- Test keyboard navigation: every interactive element must be reachable with Tab and operable with Enter/Space
+- Test with a screen reader (VoiceOver, NVDA) to verify heading hierarchy, landmark regions, and form labels
+- Verify that the page is functional with CSS disabled; content order and form submission must still work

package/assets/rules/java.md

@@ -0,0 +1,51 @@
+---
+name: java
+description: Code style and best practice rules for Java.
+globs:
+  - "**/*.java"
+---
+
+# Java Rules
+
+## Style
+- Use `PascalCase` for classes and interfaces; `camelCase` for methods and variables; `UPPER_SNAKE_CASE` for static final constants
+- One top-level class per file; the file name must match the class name exactly
+- Use `var` for local variables when the type is obvious from the right-hand side
+- Order class members: static fields, instance fields, constructors, public methods, private methods
+- Keep methods under 30 lines; extract private helper methods for complex logic
+- Use `record` types for immutable data carriers instead of classes with manual getters/equals/hashCode
+- Annotate overridden methods with `@Override`; annotate nullable parameters and returns with `@Nullable`
+- Use `sealed` classes and `permits` to restrict class hierarchies for domain modeling
+- Write Javadoc on all public classes and methods; include `@param`, `@return`, and `@throws` tags
+- Use diamond operator (`<>`) for generic type inference; never repeat type parameters on both sides
+
+## Patterns
+- Use `Optional<T>` as a return type for methods that may not produce a value; never use it as a field or parameter type
+- Use `try-with-resources` for all `AutoCloseable` resources: streams, connections, readers
+- Use Stream API for collection transformations; prefer method references over lambdas when the body is a single call
+- Use `switch` expressions (Java 14+) with arrow syntax and exhaustive cases for enum and sealed class dispatch
+- Throw specific checked exceptions for recoverable errors; use unchecked exceptions for programming errors
+- Use `CompletableFuture` for async composition; avoid raw `Thread` creation
+- Use the `java.time` API exclusively for dates and times; never use `java.util.Date` or `Calendar`
+- Use `List.of()`, `Map.of()`, `Set.of()` for immutable collections; use `List.copyOf()` for defensive copies
+- Prefer composition over inheritance; inject dependencies via constructor parameters
+- Use `String.formatted()` or `MessageFormat` for parameterized strings; avoid concatenation in loops
+- Validate method preconditions with `Objects.requireNonNull()` and guard clauses at method entry
+
+## Avoid
+- Never return `null` from a method that returns a collection; return an empty collection instead
+- Never catch `Exception` or `Throwable` broadly; catch the most specific exception type
+- Never use raw types (`List` instead of `List<String>`); always specify generic type parameters
+- Never use `synchronized` methods; use `java.util.concurrent` locks or concurrent collections
+- Never use `finalize()`; use `try-with-resources` or `Cleaner` for cleanup
+- Never use `==` to compare objects; use `.equals()` and override `hashCode` when overriding `equals`
+- Never swallow exceptions with empty catch blocks; log at minimum, rethrow if appropriate
+- Never use `Thread.stop()` or `Thread.suspend()`; use interruption and cooperative cancellation
+
+## Testing
+- Use JUnit 5 (`@Test`, `@BeforeEach`, `@DisplayName`); migrate away from JUnit 4 annotations
+- Name tests with `@DisplayName` using plain English: `@DisplayName("rejects negative withdrawal amounts")`
+- Use `assertThrows` to verify exception type and message; prefer specific assertions over `assertTrue`
+- Use `@ParameterizedTest` with `@CsvSource` or `@MethodSource` for data-driven tests
+- Use Mockito's `verify()` sparingly; prefer testing observable outcomes over interaction verification
+- Use `@Nested` inner classes to group related test cases by scenario

package/assets/rules/kotlin.md

@@ -0,0 +1,50 @@
+---
+name: kotlin
+description: Code style and best practice rules for Kotlin.
+globs:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+
+# Kotlin Rules
+
+## Style
+- Use `PascalCase` for classes, interfaces, and objects; `camelCase` for functions and properties; `UPPER_SNAKE_CASE` for compile-time constants (`const val`)
+- Use `data class` for value objects with structural equality; keep them in their own file or co-located with the primary consumer
+- Prefer expression body syntax (`fun x() = ...`) for single-expression functions
+- Place extension functions in a separate file named `<Type>Extensions.kt` when they are reusable across modules
+- Order class members: companion object, properties, init blocks, constructors, public functions, private functions
+- Use trailing commas in multi-line parameter lists, argument lists, and when-branches for cleaner diffs
+- Keep files under 200 lines; split large classes into focused interfaces and implementations
+- Use `internal` visibility for module-scoped API; default to `private` for implementation details
+- Annotate platform types from Java interop with explicit nullability (`String?` or `String`)
+- Use backtick-quoted test names for readability: `` `should return empty list when no items match` ``
+
+## Patterns
+- Use `sealed class` or `sealed interface` for restricted type hierarchies; use `when` exhaustively without `else`
+- Use `?.let { }`, `?.run { }`, or `?: return` for null handling instead of nested if-null checks
+- Use `require()` for argument validation and `check()` for state validation; both throw descriptive exceptions
+- Use coroutines with structured concurrency (`coroutineScope`, `supervisorScope`); never launch fire-and-forget jobs
+- Use `Flow` for cold asynchronous streams; use `StateFlow` and `SharedFlow` for hot state
+- Use `apply` for object configuration, `let` for null-safe transformations, `also` for side effects, `run` for scoped computation
+- Use `sequence { yield() }` for lazily computed collections instead of building full lists
+- Prefer `List`, `Map`, `Set` (read-only interfaces) in API signatures; use `MutableList` only internally
+- Use `Result<T>` or `runCatching` for operations that may fail; propagate errors with `fold` or `getOrElse`
+- Use `by lazy` for expensive property initialization that should happen at most once
+- Use `typealias` to simplify complex generic signatures at module boundaries
+
+## Avoid
+- Never use `!!` (not-null assertion) except in tests or where a null value is a genuine programmer error with an obvious fix
+- Never use `var` for properties that do not change after initialization; use `val` everywhere possible
+- Never catch `Exception` broadly; catch specific exception types and rethrow `CancellationException` in coroutines
+- Never use Java collection types (`java.util.ArrayList`) directly; use Kotlin stdlib collection functions
+- Never use `companion object` as a namespace for unrelated utility functions; use top-level functions instead
+- Never use string concatenation in loops; use `StringBuilder` or `buildString { }`
+- Never call blocking I/O from coroutines without wrapping in `withContext(Dispatchers.IO)`
+
+## Testing
+- Use JUnit 5 with Kotlin; prefer `kotest` assertions for more idiomatic test code
+- Use `@ParameterizedTest` or Kotest's `forAll` for property-based and data-driven tests
+- Test coroutine code with `runTest` from `kotlinx-coroutines-test`; use `advanceUntilIdle()` for time-based tests
+- Use `mockk` over Mockito for mocking; prefer `coEvery` and `coVerify` for suspending functions
+- Verify sealed-class exhaustiveness in tests by covering every subtype in dedicated test cases

package/assets/rules/php.md

@@ -0,0 +1,51 @@
+---
+name: php
+description: Code style and best practice rules for PHP.
+globs:
+  - "**/*.php"
+---
+
+# PHP Rules
+
+## Style
+- Follow PSR-12 coding style; enforce with PHP-CS-Fixer or PHP_CodeSniffer in CI
+- Use `PascalCase` for classes, interfaces, traits, and enums; `camelCase` for methods and properties; `UPPER_SNAKE_CASE` for class constants
+- Declare `strict_types=1` at the top of every file: `declare(strict_types=1);`
+- Add type declarations to all function parameters, return types, and class properties; never omit types
+- One class per file; the file name must match the class name and follow PSR-4 autoloading
+- Use `readonly` properties (PHP 8.1+) for immutable data; prefer constructor promotion for brevity
+- Order `use` imports alphabetically; group classes, functions, and constants with blank lines
+- Keep methods under 25 lines; extract private methods for complex logic
+- Use `enum` (PHP 8.1+) backed by `string` or `int` instead of class constants for finite value sets
+- Place the opening brace on the same line for control structures, next line for classes and methods (PSR-12)
+
+## Patterns
+- Use `match` expressions instead of `switch` for value-returning conditionals; `match` is strict and exhaustive
+- Use named arguments for functions with boolean flags or multiple optional parameters: `array_slice(array: $a, offset: 2)`
+- Use PHP 8 attributes (`#[Route('/api')]`) instead of docblock annotations for metadata
+- Use `null` coalescing (`??`) and nullsafe operator (`?->`) for null handling chains
+- Use constructor property promotion to reduce boilerplate in value objects and DTOs
+- Use `array_map`, `array_filter`, `array_reduce` with arrow functions (`fn($x) => $x * 2`) for collection operations
+- Throw specific domain exceptions extending a base exception; catch at the boundary layer
+- Use dependency injection via constructor; never use service locators or global `app()` helpers in domain code
+- Use generators (`yield`) for processing large datasets without loading everything into memory
+- Use `DateTimeImmutable` exclusively; never use mutable `DateTime`
+- Use `Stringable` interface and `__toString()` for objects that represent displayable values
+
+## Avoid
+- Never use `@` error suppression operator; handle errors explicitly or configure error reporting
+- Never use `eval()`, `extract()`, or `compact()` in application code
+- Never compare with `==` for type-sensitive values; always use `===` (strict equality)
+- Never use global variables or the `global` keyword; pass dependencies through function parameters
+- Never use `array` when a typed collection class or DTO would be clearer
+- Never concatenate user input into SQL queries; use prepared statements with parameter binding
+- Never use `die()` or `exit()` in library code; throw an exception instead
+- Never suppress PHPStan/Psalm errors without a documented justification
+
+## Testing
+- Use PHPUnit with `#[Test]` attributes (PHPUnit 10+); name methods descriptively: `testRejectsExpiredToken()`
+- Use `#[DataProvider]` for parameterized tests instead of loops inside test methods
+- Assert specific exception classes and messages with `$this->expectException()` and `$this->expectExceptionMessage()`
+- Use `setUp()` for shared fixtures; avoid shared state between test methods
+- Mock interfaces at boundaries with PHPUnit mocks or Mockery; never mock the class under test
+- Run tests with `--strict-coverage` and `--fail-on-risky` to catch untested code paths

package/assets/rules/python.md

@@ -0,0 +1,51 @@
+---
+name: python
+description: Code style and best practice rules for Python.
+globs:
+  - "**/*.py"
+---
+
+# Python Rules
+
+## Style
+- Use `snake_case` for functions, variables, and modules; `PascalCase` for classes; `UPPER_SNAKE_CASE` for module-level constants
+- Add type hints to all function signatures including return types; use `-> None` explicitly for procedures
+- Use `dataclasses` or `attrs` for data containers instead of plain dicts or tuples with index access
+- Keep imports grouped: stdlib, third-party, local; one import per line, sorted alphabetically within each group
+- Limit line length to 88 characters (Black default); use implicit line continuation inside brackets
+- Place module docstrings at the top; use Google-style docstrings for public functions and classes
+- Use `__all__` in modules to declare the public API explicitly
+- Define constants at module level, never inside functions unless scoped for performance
+- One class per file for major classes; group small related classes together
+- Use f-strings for all string formatting; never use `%` formatting or `.format()` in new code
+
+## Patterns
+- Use `pathlib.Path` instead of `os.path` for all filesystem operations
+- Use context managers (`with` statements) for all resource acquisition: files, locks, database connections
+- Prefer list/dict/set comprehensions over `map()` and `filter()` for simple transformations
+- Use `match`/`case` statements (Python 3.10+) for structural pattern matching on complex data
+- Use `Enum` or `StrEnum` for finite sets of related constants instead of bare strings
+- Raise specific exceptions with descriptive messages; create custom exception classes per domain
+- Use `functools.lru_cache` or `functools.cache` for expensive pure computations
+- Use `typing.Protocol` for structural subtyping instead of ABC when only method signatures matter
+- Return early from functions to reduce nesting; guard clauses go at the top
+- Use `itertools` and generator expressions for lazy evaluation of large sequences
+- Use `collections.defaultdict` instead of manual key-existence checks when building aggregations
+
+## Avoid
+- Never use mutable default arguments (`def f(items=[])`); use `None` and assign inside the function
+- Never use bare `except:` or `except Exception:`; catch the most specific exception type
+- Never use `global` or `nonlocal` for state management; pass state explicitly or use a class
+- Never use `type()` for type checks; use `isinstance()` with a tuple of types
+- Never use wildcard imports (`from module import *`); import specific names
+- Never store secrets or credentials in source code; use environment variables or a secrets manager
+- Never use `eval()` or `exec()` on untrusted input
+- Never ignore return values of functions that indicate success/failure
+
+## Testing
+- Use `pytest` with fixtures; avoid `unittest.TestCase` unless integrating with legacy code
+- Name test files `test_<module>.py` and test functions `test_<behavior>_<scenario>`
+- Use `pytest.raises` as a context manager to test exceptions, checking both type and message
+- Use `pytest.mark.parametrize` for data-driven tests instead of loops inside test functions
+- Use `tmp_path` fixture for filesystem tests; never write to the real filesystem
+- Mock external services with `unittest.mock.patch` at the call site, not the definition site

package/assets/rules/ruby.md

@@ -0,0 +1,51 @@
+---
+name: ruby
+description: Code style and best practice rules for Ruby.
+globs:
+  - "**/*.rb"
+---
+
+# Ruby Rules
+
+## Style
+- Use `snake_case` for methods, variables, and file names; `PascalCase` for classes and modules; `SCREAMING_SNAKE_CASE` for constants
+- Add `# frozen_string_literal: true` magic comment to the top of every file
+- Keep methods under 15 lines; extract private methods with descriptive names for complex logic
+- Use 2-space indentation; never use tabs
+- Prefer `do...end` for multi-line blocks and `{ }` for single-line blocks
+- Define one class or module per file; nest modules to match the directory structure
+- Use keyword arguments for methods with more than two parameters or when parameter meaning is ambiguous
+- Document public methods with YARD (`@param`, `@return`, `@raise`) comments
+- Limit line length to 120 characters; break long method chains with trailing dots
+- Order class contents: constants, includes/extends, attribute accessors, class methods, public methods, protected methods, private methods
+
+## Patterns
+- Use pattern matching (`case...in`) for destructuring hashes and arrays (Ruby 3.0+)
+- Use `Struct` or `Data.define` (Ruby 3.2+) for simple value objects; use full classes only when behavior is needed
+- Use `Enumerable` methods (`map`, `select`, `reduce`) instead of manual loops with `each` and mutation
+- Use `begin...rescue...ensure` for error handling; rescue specific exception classes, not `StandardError` broadly
+- Use `Module#prepend` for method wrapping instead of `alias_method_chain` or monkey patching
+- Return `nil` only when absence is meaningful; raise an exception for error conditions
+- Use `Comparable` and `<=>` for custom ordering; implement `hash` and `eql?` for hash key usage
+- Use `StringIO` for in-memory I/O in tests; use `Tempfile` for filesystem tests
+- Prefer `fetch` over `[]` for hash access when the key must exist; use `fetch` with a default for optional keys
+- Use `freeze` on constants that are arrays or hashes to prevent accidental mutation
+- Use `tap` for object initialization chains that return the object itself
+
+## Avoid
+- Never use `eval`, `class_eval`, or `instance_eval` with string arguments; use block forms if metaprogramming is necessary
+- Never rescue `Exception`; rescue `StandardError` or a more specific subclass
+- Never use `and`/`or` for control flow; use `&&`/`||` for boolean logic and `if`/`unless` for control flow
+- Never mutate method arguments; return a new value instead
+- Never use `for...in` loops; use `each` or other `Enumerable` methods
+- Never use global variables (`$foo`); pass state explicitly through method parameters
+- Never open classes to monkeypatch in library code; use `Refinements` if modification is required
+- Never use `Thread` directly for concurrency; use `Concurrent::Ruby` primitives or Ractors
+
+## Testing
+- Use RSpec with `describe`/`context`/`it` blocks; write expectations as `expect(result).to eq(expected)`
+- Use `let` for lazy fixtures and `let!` for eager fixtures; avoid `before` blocks that build too much state
+- Use `shared_examples` for behavior shared across multiple contexts; include them with `it_behaves_like`
+- Use `instance_double` and `class_double` for type-checked mocks; avoid `allow_any_instance_of`
+- Use `aggregate_failures` to report all assertion failures in a single example, not just the first
+- Use Sorbet type signatures (`sig { params(...).returns(...) }`) for public API methods and verify in CI with `srb tc`

package/assets/rules/rust.md

@@ -0,0 +1,49 @@
+---
+name: rust
+description: Code style and best practice rules for Rust.
+globs:
+  - "**/*.rs"
+---
+
+# Rust Rules
+
+## Style
+- Use `snake_case` for functions, variables, and modules; `PascalCase` for types, traits, and enums; `SCREAMING_SNAKE_CASE` for constants and statics
+- Run `cargo fmt` on every file before committing; configure `rustfmt.toml` for the project
+- Run `cargo clippy -- -D warnings` and fix all lints; do not suppress lints without a `#[allow()]` comment explaining why
+- Keep functions under 40 lines; extract helper functions or closures for complex logic
+- Use module files (`mod.rs` or `module_name.rs`) to organize code by responsibility; re-export public API from `lib.rs`
+- Place `use` statements at the top: `std`, external crates, internal modules; sorted alphabetically within groups
+- Document all public items with `///` doc comments; include examples in `# Examples` sections that compile as doctests
+- Prefer turbofish (`::<Type>`) only when inference fails; let the compiler infer types when unambiguous
+- Use `pub(crate)` for items shared within the crate but not part of the public API
+
+## Patterns
+- Use `Result<T, E>` for fallible operations; define domain error types with `thiserror::Error` for libraries, use `anyhow::Result` for applications
+- Use `Option<T>` instead of sentinel values; chain operations with `.map()`, `.and_then()`, `.unwrap_or_default()`
+- Use the `?` operator for early error propagation; avoid manual match-on-Result boilerplate
+- Implement traits for shared behavior; prefer trait bounds (`impl Trait` or `where T: Trait`) over dynamic dispatch (`dyn Trait`) unless object safety requires it
+- Use `enum` with variants carrying data for state machines; implement methods on the enum to enforce valid transitions
+- Use iterators and combinators (`.filter()`, `.map()`, `.collect()`) over manual loops for transformations
+- Use `Arc<Mutex<T>>` for shared mutable state across threads; prefer channels (`mpsc`, `crossbeam`) for message passing
+- Use `#[derive(...)]` for `Debug`, `Clone`, `PartialEq`, and `Eq` on data types; derive `Serialize`/`Deserialize` for I/O boundaries
+- Use builder pattern for types with many optional configuration fields
+- Use `Cow<'_, str>` when a function may or may not need to allocate a new string
+- Use `impl Into<T>` for function parameters to accept both owned and borrowed values ergonomically
+
+## Avoid
+- Never use `unwrap()` or `expect()` in library code; reserve them for tests and provably infallible cases with a comment
+- Never use `unsafe` without a `// SAFETY:` comment proving the invariant; prefer safe abstractions
+- Never use `clone()` to fix borrow checker errors without understanding the ownership model; restructure the code instead
+- Never leak resources by holding `MutexGuard` across `.await` points; restructure to drop the guard before awaiting
+- Never use `String` where `&str` suffices in function parameters; accept the borrowed form
+- Never ignore compiler warnings; treat `#[deny(warnings)]` as the baseline for CI
+- Never use `Box<dyn Error>` as a return type in libraries; use a concrete error enum
+
+## Testing
+- Place unit tests in a `#[cfg(test)] mod tests` block at the bottom of each source file
+- Place integration tests in the `tests/` directory; each file compiles as a separate crate
+- Use `#[should_panic(expected = "message")]` for panic tests; use `assert!(result.is_err())` for Result tests
+- Use `proptest` or `quickcheck` for property-based testing of pure functions
+- Use `mockall` for trait mocking; define traits at boundaries (HTTP, DB) to enable testability
+- Run `cargo test --all-features` in CI to ensure no feature flag combination breaks

package/assets/rules/shell.md

@@ -0,0 +1,52 @@
+---
+name: shell
+description: Code style and best practice rules for Shell scripts.
+globs:
+  - "**/*.sh"
+  - "**/*.bash"
+  - "**/*.zsh"
+---
+
+# Shell Rules
+
+## Style
+- Start every script with a shebang: `#!/usr/bin/env bash` for portability; use `#!/usr/bin/env zsh` only for zsh-specific scripts
+- Set strict mode at the top: `set -euo pipefail` to fail on errors, unset variables, and pipe failures
+- Use `snake_case` for function names and local variables; `UPPER_SNAKE_CASE` for exported environment variables and constants
+- Indent with 2 spaces; never use tabs
+- Keep scripts under 200 lines; split complex workflows into multiple scripts or functions
+- Add a usage comment block at the top of every script describing purpose, arguments, and examples
+- Use `local` keyword for all variables inside functions to avoid polluting the global scope
+- Quote all variable expansions: `"${var}"` not `$var`; this prevents word splitting and glob expansion
+- Place `main()` function at the bottom of the script; call it with `main "$@"` as the last line
+- Group related functions together; define utility functions before the functions that call them
+
+## Patterns
+- Use `readonly` for constants: `readonly CONFIG_DIR="/etc/myapp"`
+- Use `trap` for cleanup on exit: `trap cleanup EXIT` with a cleanup function that removes temp files and restores state
+- Use `mktemp` for temporary files and directories: `tmpdir=$(mktemp -d)` instead of hardcoded `/tmp/foo`
+- Use `"${variable:-default}"` for default values; use `"${variable:?error message}"` for required variables
+- Use `[[ ]]` for conditionals instead of `[ ]`; it handles empty strings and regex without quoting issues
+- Use `printf` instead of `echo` for portable, format-controlled output; `echo` behavior varies across shells
+- Use `command -v` to check if a program exists instead of `which`; it is POSIX-compliant
+- Use `while IFS= read -r line` for reading files line by line; never use `for line in $(cat file)`
+- Use arrays for lists of items: `files=("a.txt" "b.txt")` and iterate with `for f in "${files[@]}"`
+- Use `getopts` or a manual `case` loop for argument parsing; document every flag
+- Use `shellcheck` as a mandatory CI lint step; fix all warnings before merging
+
+## Avoid
+- Never use backticks for command substitution; use `$(command)` for nesting and readability
+- Never use `eval`; it creates injection vulnerabilities and makes code impossible to reason about
+- Never parse `ls` output; use globbing (`for f in *.txt`) or `find` with `-print0` and `xargs -0`
+- Never use unquoted variables in conditionals, assignments, or command arguments
+- Never hardcode paths like `/home/user/`; use `$HOME`, `$(dirname "$0")`, or environment variables
+- Never write to files without checking if the target directory exists; create with `mkdir -p` first
+- Never pipe `find` results into `xargs` without `-print0` and `-0`; filenames may contain spaces or newlines
+- Never use `cd` without checking return value; use `cd /path || exit 1` or `pushd`/`popd`
+
+## Testing
+- Use `bats` (Bash Automated Testing System) for structured shell testing; one `.bats` file per script
+- Test exit codes explicitly: `run my_command; [ "$status" -eq 0 ]`
+- Use `setup()` and `teardown()` functions in bats for fixture creation and cleanup
+- Test error conditions by providing invalid input and asserting non-zero exit codes and stderr messages
+- Run `shellcheck --severity=warning` on all scripts in CI; treat warnings as errors

package/assets/rules/sql.md

@@ -0,0 +1,49 @@
+---
+name: sql
+description: Code style and best practice rules for SQL.
+globs:
+  - "**/*.sql"
+---
+
+# SQL Rules
+
+## Style
+- Write SQL keywords in uppercase: `SELECT`, `FROM`, `WHERE`, `JOIN`, `INSERT`, `UPDATE`, `DELETE`
+- Use `snake_case` for table names, column names, indexes, and constraints; never use spaces or mixed case
+- Name tables as plural nouns (`users`, `orders`); name join tables as `left_right` (`user_roles`)
+- Prefix boolean columns with `is_`, `has_`, or `can_`: `is_active`, `has_subscription`
+- Name primary keys `id`; name foreign keys `<referenced_table_singular>_id`: `user_id`, `order_id`
+- Place each major clause (`SELECT`, `FROM`, `WHERE`, `JOIN`, `GROUP BY`, `ORDER BY`) on its own line
+- Indent joined tables and sub-conditions by 2 or 4 spaces consistently throughout the project
+- Name constraints explicitly: `pk_users`, `fk_orders_user_id`, `uq_users_email`, `idx_orders_created_at`
+- Use `-- comment` for single-line comments above the clause they describe; avoid inline comments after code
+- Add a trailing semicolon to every statement; separate statements with a blank line
+
+## Patterns
+- Use Common Table Expressions (CTEs) with `WITH` instead of nested subqueries for readability
+- Use explicit `JOIN ... ON` syntax; never use implicit joins with comma-separated tables in `FROM`
+- Use `COALESCE()` to provide default values for nullable columns in result sets
+- Use `EXISTS` instead of `IN` with subqueries for better query plan optimization on large tables
+- Use parameterized queries (`$1`, `?`, or `:name`) for all user-supplied values; never interpolate strings
+- Use `RETURNING` clause (PostgreSQL) on `INSERT`, `UPDATE`, `DELETE` to avoid a separate `SELECT`
+- Use `ON CONFLICT ... DO UPDATE` (upsert) instead of check-then-insert patterns to avoid race conditions
+- Use window functions (`ROW_NUMBER()`, `RANK()`, `LAG()`, `LEAD()`) instead of self-joins for row-relative calculations
+- Use `LIMIT` with `OFFSET` only for small result sets; use keyset pagination (`WHERE id > $last_id`) for large tables
+- Add `NOT NULL` constraints to every column unless null has an explicit domain meaning
+- Use `TIMESTAMP WITH TIME ZONE` (`TIMESTAMPTZ`) for all datetime columns; store times in UTC
+
+## Avoid
+- Never use `SELECT *` in application queries; list columns explicitly to avoid breakage on schema changes
+- Never store comma-separated values in a single column; normalize into a related table
+- Never use `FLOAT` or `DOUBLE` for monetary values; use `NUMERIC(precision, scale)` or `DECIMAL`
+- Never use `TRUNCATE` or `DELETE` without a `WHERE` clause unless intentionally clearing the entire table
+- Never rely on implicit type coercion; cast explicitly with `CAST(column AS type)` when types differ
+- Never create indexes on every column; index only columns used in `WHERE`, `JOIN`, and `ORDER BY` clauses
+- Never use reserved words (`user`, `order`, `group`) as unquoted identifiers; rename or quote them
+
+## Testing
+- Write migration rollback (`DOWN`) scripts for every `UP` migration; test both directions
+- Use a dedicated test database seeded with deterministic fixture data; never test against production
+- Verify query plans with `EXPLAIN ANALYZE` for queries on tables expected to exceed 10,000 rows
+- Test constraints by asserting that invalid inserts raise the expected constraint violation error
+- Use transactions with `ROLLBACK` in test harnesses to isolate tests without leaving residual data

package/assets/rules/swift.md

@@ -0,0 +1,50 @@
+---
+name: swift
+description: Code style and best practice rules for Swift.
+globs:
+  - "**/*.swift"
+---
+
+# Swift Rules
+
+## Style
+- Use `PascalCase` for types, protocols, and enum cases; `camelCase` for functions, properties, and variables
+- Use `struct` by default for data models; use `class` only when reference semantics or inheritance is required
+- Keep functions under 30 lines; extract helper functions with clear names for complex logic
+- Place extensions in the same file as the type for protocol conformance; use separate files for large extensions
+- Mark access levels explicitly: `private` for implementation details, `internal` (default) for module-scoped, `public` for API
+- Use trailing closure syntax when the last parameter is a closure; use labeled arguments for multiple closure parameters
+- Group properties at the top of a type: stored properties first, then computed properties, then methods
+- Use `// MARK: -` comments to organize sections within large files
+- Prefer `let` over `var` everywhere; use `var` only when mutation is necessary
+- Limit files to 400 lines; split large types into extensions organized by protocol conformance
+
+## Patterns
+- Use protocol-oriented design: define protocols for shared behavior, provide default implementations in extensions
+- Use `guard` clauses for early exits instead of nested `if` statements; place guards at the top of the function
+- Use `async`/`await` for all asynchronous work; prefer structured concurrency with `TaskGroup` over unstructured `Task { }`
+- Use `Codable` with custom `CodingKeys` for JSON serialization; use `JSONDecoder`/`JSONEncoder` with `keyDecodingStrategy`
+- Use `Result<Success, Failure>` when a function needs to return success or a typed error; use `throws` for simple cases
+- Use `@MainActor` for UI-related code; use `Sendable` conformance for types passed across concurrency boundaries
+- Use `enum` without cases as a namespace for static utility functions and constants
+- Use `weak self` in closures that capture `self` and may outlive the owner; use `[weak self]` capture lists explicitly
+- Use `map`, `compactMap`, `filter`, `reduce` on collections instead of manual loop-and-append
+- Use `@Published` and `ObservableObject` for SwiftUI state management; keep view models as separate classes
+- Use `defer` for cleanup code that must run regardless of how a scope exits
+
+## Avoid
+- Never force-unwrap (`!`) optionals outside of tests or `IBOutlet` declarations; use `guard let` or `if let`
+- Never use `Any` or `AnyObject` when a protocol or generic constraint can express the requirement
+- Never use `class` inheritance hierarchies deeper than two levels; prefer composition with protocols
+- Never use `NSNotificationCenter` string-based notifications; use `Combine` publishers or `async` streams
+- Never perform synchronous I/O on the main thread; use `Task` or `DispatchQueue.global()` for background work
+- Never use singletons for testable dependencies; inject them through initializers
+- Never use implicitly unwrapped optionals (`String!`) except for `@IBOutlet` or two-phase initialization
+
+## Testing
+- Use XCTest with descriptive names: `func testLogin_withExpiredToken_returnsAuthError()`
+- Use `XCTAssertEqual` with specific values; avoid `XCTAssertTrue` for equality checks
+- Use `async` test methods for testing async code; use `XCTestExpectation` only for callback-based APIs
+- Test SwiftUI views with `ViewInspector` or snapshot tests; test view models independently with unit tests
+- Use protocol-based dependency injection to swap real services for test doubles
+- Use `throws` in test methods and `XCTUnwrap` instead of force-unwrapping in test assertions