@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/csharp-testing/references/integration-tests.md

@@ -0,0 +1,77 @@
+# .NET integration tests
+
+Read this when testing an ASP.NET Core app end to end in memory, or against a real database in a container.
+
+## WebApplicationFactory
+
+Package: `Microsoft.AspNetCore.Mvc.Testing`. The test project uses the Web SDK or references the app project.
+
+With top-level statements, the generated `Program` class may not be visible to the test project. If `WebApplicationFactory<Program>` doesn't compile, add this to the end of `Program.cs`:
+
+```csharp
+public partial class Program;
+```
+
+Custom factory that swaps services:
+
+```csharp
+public sealed class ApiFactory : WebApplicationFactory<Program>
+{
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        builder.UseEnvironment("Testing");
+        builder.ConfigureTestServices(services =>
+        {
+            services.RemoveAll<IEmailSender>();
+            services.AddSingleton<IEmailSender, FakeEmailSender>();
+        });
+    }
+}
+
+public sealed class OrdersApiTests(ApiFactory factory) : IClassFixture<ApiFactory>
+{
+    [Fact]
+    public async Task Get_unknown_order_returns_404()
+    {
+        var client = factory.CreateClient();
+        var response = await client.GetAsync("/orders/999");
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+    }
+}
+```
+
+- `RemoveAll<T>()` is in `Microsoft.Extensions.DependencyInjection.Extensions`.
+- Auth: register a test authentication handler in `ConfigureTestServices` (`services.AddAuthentication("Test").AddScheme<AuthenticationSchemeOptions, TestAuthHandler>("Test", _ => { })`) rather than disabling authorization.
+- `CreateClient()` follows redirects by default; pass `new WebApplicationFactoryClientOptions { AllowAutoRedirect = false }` to assert on a 302.
+
+## Testcontainers
+
+Packages: `Testcontainers.PostgreSql` (or `Testcontainers.MsSql`, `Testcontainers.MySql`, `Testcontainers.Redis`). Needs Docker or a compatible engine.
+
+```csharp
+public sealed class PostgresFixture : IAsyncLifetime
+{
+    // If your Testcontainers version marks this constructor obsolete, pass the image to it instead.
+    public PostgreSqlContainer Db { get; } = new PostgreSqlBuilder()
+        .WithImage("postgres:16-alpine")
+        .Build();
+
+    // xUnit v2 signatures; in xUnit v3 both methods return ValueTask.
+    public Task InitializeAsync() => Db.StartAsync();
+    public Task DisposeAsync() => Db.DisposeAsync().AsTask();
+}
+```
+
+- Pin the image tag to the version production uses; never `latest`.
+- Share one container per collection: `[CollectionDefinition("db")] public class DbCollection : ICollectionFixture<PostgresFixture>;` and mark test classes `[Collection("db")]`.
+- Apply schema once per container: run EF Core migrations (`await db.Database.MigrateAsync()`) in the fixture, not `EnsureCreated` if production uses migrations.
+- Isolate tests: wrap each in a transaction you roll back, or reset data between tests (the Respawn library is a common choice). Don't depend on test order.
+- Combine with WebApplicationFactory by overriding the connection string in `ConfigureWebHost` with `builder.UseSetting("ConnectionStrings:Default", fixture.Db.GetConnectionString())`.
+
+## NUnit and MSTest equivalents
+
+| xUnit | NUnit | MSTest |
+|---|---|---|
+| `IClassFixture<T>` | `[OneTimeSetUp]` / `[OneTimeTearDown]` | `[ClassInitialize]` / `[ClassCleanup]` |
+| constructor / `IDisposable` | `[SetUp]` / `[TearDown]` | `[TestInitialize]` / `[TestCleanup]` |
+| `ICollectionFixture<T>` | `[SetUpFixture]` | `[AssemblyInitialize]` |

package/skills/css-architecture/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: css-architecture
+description: Organises stylesheets so they stay maintainable as a codebase grows, using design tokens in CSS custom properties, cascade layers to control specificity, grid and flexbox for layout, container queries for component-level responsiveness, one consistent naming or utility-first convention, and token-driven theming including dark mode. Use when setting up or refactoring a project's CSS, introducing a design system or theme, fighting specificity wars and !important, or deciding between BEM, CSS Modules and Tailwind.
+license: MIT
+compatibility: Any Agent Skills host. Plain CSS, Sass, CSS Modules, Tailwind or CSS-in-JS. Cascade layers and container queries need evergreen browsers; check the project's browser targets.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# CSS architecture
+
+Make the cascade predictable: tokens for values, layers for order, components that style only themselves.
+
+## 0. Before you start
+
+1. Identify the current approach: global CSS, Sass partials, CSS Modules, Tailwind (`tailwind.config.*` or `@import "tailwindcss"`), CSS-in-JS, or a mix. Check `browserslist` or the framework's targets.
+2. Keep the approach the project already uses. Changing methodology (for example BEM to Tailwind) is a project decision: **stop and ask the user** before starting one.
+3. Look for an existing token file or theme before adding values.
+
+## 1. Design tokens
+
+Three tiers, all as custom properties on `:root`:
+
+```css
+:root {
+  /* primitives: raw palette and scale, never used directly in components */
+  --blue-600: oklch(52% 0.18 255);
+  --space-4: 1rem;
+  /* semantic: what the value is for; components use these */
+  --color-bg: white;
+  --color-text: #1a1a1a;
+  --color-accent: var(--blue-600);
+  --space-gap: var(--space-4);
+  --radius-control: 0.375rem;
+}
+```
+
+- Components reference semantic tokens only, so theming changes one place.
+- Scales, not one-offs: spacing, type sizes, radii, shadows, z-index each have a short named scale. A new raw value in a component is a review flag.
+- Use `rem` for type and spacing so user font size settings apply; `clamp()` for fluid type (`font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)`).
+- If the design team exports tokens (Figma, Tokens Studio, Style Dictionary), generate the CSS from that source instead of hand-editing.
+- In Tailwind v4, define tokens with `@theme { --color-accent: ...; }`; in v3, in `theme.extend` in `tailwind.config.js`. Check which version the project runs.
+
+## 2. Cascade layers
+
+Declare the order once, at the top of the entry stylesheet:
+
+```css
+@layer reset, vendor, tokens, base, layout, components, utilities, overrides;
+@import url("vendor.css") layer(vendor);
+```
+
+- Later layers win regardless of selector specificity, so utilities beat components without `!important`.
+- Unlayered styles beat all layers, so put third-party CSS in a layer named early in the order statement. A layer not named there is appended last and beats everything before it.
+- `@import` must come before every other rule except `@layer` order statements, or the browser ignores it.
+- `!important` inside a layer reverses the order (earlier layers' important rules win). Avoid `!important` except in `utilities` that must always apply, such as `.visually-hidden`.
+
+## 3. Selectors and naming
+
+Pick one convention per project and apply it everywhere:
+
+| Approach | Use when | Rules |
+|---|---|---|
+| BEM (`.card`, `.card__title`, `.card--featured`) | global CSS or Sass | one class per selector, no element or ID selectors in components, max one level of nesting |
+| CSS Modules / scoped styles (Vue `scoped`, Svelte, Angular) | component frameworks | class names local by default; share through tokens, not `:global` |
+| Utility-first (Tailwind) | team already uses it | extract a component (not `@apply` soup) when a class list repeats; keep tokens in the theme |
+
+General rules:
+- Keep specificity flat: one class. Avoid IDs and `#id .x .y div` chains.
+- Use `:where()` to zero out specificity in base and reset styles; `:is()` keeps the highest.
+- Native nesting is fine for states and children, but no deeper than two levels.
+- Style states with attributes the markup already has: `[aria-expanded="true"]`, `[aria-current="page"]`, `:disabled`, `[data-state="open"]`.
+- Components never set their own outer margin or position on the page; the parent layout does.
+
+## 4. Layout
+
+Decision rule: two dimensions (rows and columns) → grid. One dimension (a row of items) → flexbox.
+
+- Responsive grid without media queries: `grid-template-columns: repeat(auto-fill, minmax(min(16rem, 100%), 1fr));`
+- Spacing between children: `gap`, not margins on children.
+- Use logical properties (`margin-inline`, `padding-block`, `inset-inline-start`) so RTL layouts work.
+- Avoid fixed heights on content; use `min-height` and let text wrap.
+- `subgrid` for aligning nested card contents across a row, where browser targets allow.
+
+## 5. Container queries vs media queries
+
+- Media queries for page-level layout (sidebar collapses, navigation changes) and user preferences (`prefers-color-scheme`, `prefers-reduced-motion`, `prefers-contrast`).
+- Container queries for components that live in slots of different widths:
+
+```css
+.card-list { container-type: inline-size; container-name: cards; }
+@container cards (min-width: 40rem) {
+  .card { grid-template-columns: 12rem 1fr; }
+}
+```
+
+- An element cannot query its own size: set `container-type` on a wrapper and style the children. `inline-size` containment also stops the container sizing to its content's width, so don't put it on shrink-to-fit elements.
+- Container query units (`cqi`) for type that scales with the container.
+
+## 6. Theming and dark mode
+
+1. Themes only redefine semantic tokens; components don't change.
+2. Respect the OS by default and allow an explicit override:
+
+```css
+:root { color-scheme: light dark; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --color-bg: #121212; --color-text: #e8e8e8; }
+}
+:root[data-theme="dark"] { --color-bg: #121212; --color-text: #e8e8e8; }
+```
+
+3. `light-dark(var(--a), var(--b))` is a shorter option where browser targets support it.
+4. Set the theme attribute before first paint (inline script in `<head>` reading the saved choice) to avoid a flash of the wrong theme.
+5. Check text and UI contrast in every theme (4.5:1 for text, 3:1 for UI parts). Dark mode is not inverted colours: lower elevation surfaces are darker, avoid pure black behind large text blocks.
+
+## 7. Refactoring existing CSS
+
+1. Find unused and duplicate rules (Coverage panel in Chrome DevTools, search for class usage in the codebase). Remove only what search proves unused; dynamic class names (`"btn-" + size`) need a manual check.
+2. Replace repeated raw values with tokens, one token group per change.
+3. Introduce layers by wrapping existing files in the layer that matches their role, then delete the `!important` and specificity hacks they made unnecessary.
+4. After each step, compare key pages visually (screenshot diff or manual check in both themes and at mobile and desktop widths).
+
+## Never
+
+- Never add `!important` to win a specificity fight; fix the layer or selector.
+- Never hard-code colours or spacing inside components when a token exists.
+- Never style by DOM structure (`.sidebar > div > ul li a`).
+- Never remove `:focus-visible` styles or set `outline: none` without a replacement.
+- Never mix two naming methodologies in new code.
+
+## Report back
+
+```
+Approach:  <methodology and tooling found/kept>
+Changes:   <file> — <tokens/layers/layout/theme change>   (one line each)
+Removed:   <rules or !important count removed>
+Checked:   <pages, widths and themes compared>
+Decisions needed: <anything that changes the methodology or design>
+```

package/skills/css-architecture/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our stylesheet is full of !important and nested selectors, restructure it so it is maintainable",
+    "Set up design tokens as CSS custom properties with a dark mode toggle that respects the OS setting",
+    "Should we use BEM, CSS Modules or Tailwind for this new project?",
+    "Make this card component change layout based on its container width instead of the viewport",
+    "Introduce cascade layers so third-party CSS stops overriding our component styles"
+  ],
+  "should_not_trigger": [
+    "Design a new landing page with a bold visual style for our coffee brand",
+    "The web fonts are causing layout shift and slowing down LCP",
+    "Check that our focus outlines and text colours meet WCAG contrast requirements",
+    "Convert this Vue options API component to the composition API",
+    "Build a responsive SwiftUI layout for iPad and iPhone"
+  ]
+}

package/skills/customs-trade-compliance/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: customs-trade-compliance
+description: Cross-border shipping groundwork for software and operations teams, covering Harmonized System product codes, choosing and reading Incoterms 2020 rules, estimating duties, import taxes and landed cost, the data a commercial invoice needs, and screening buyers against restricted-party and sanctions lists, with a firm line on which decisions a licensed customs broker or trade lawyer must make. Use when adding international shipping to a store or ERP, building a landed-cost calculator or export documents, or deciding who pays duties and when goods need a broker.
+license: MIT
+compatibility: Any Agent Skills host. Tariff and screening lookups need network access to government sites or a provider API. Not legal or customs advice.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Customs and trade compliance
+
+Get product, party and shipment data right in the system so a broker can file cleanly, landed cost is no surprise, and no order ships to a party you may not deal with. This skill prepares and checks; it does not make binding classification or licensing decisions.
+
+## Boundary: when a licensed person must decide
+
+**Stop and tell the user to involve a licensed customs broker, customs authority ruling or trade lawyer** when any of these apply:
+
+- Final tariff classification used on a filed entry, especially where duty differs a lot between candidate codes, or for chemicals, food, medical devices, textiles and steel/aluminium.
+- Origin claims for a free trade agreement preference, or anti-dumping/countervailing duty exposure.
+- Valuation questions: related-party prices, royalties, assists, free samples, or goods sold below cost.
+- Export control: anything military, dual-use, encryption beyond mass-market, or a licence question (US EAR/ITAR, EU dual-use regulation).
+- Any possible restricted-party or sanctions match, or a shipment to an embargoed or comprehensively sanctioned destination.
+- Filing an entry or export declaration on someone else's behalf (in the US, transacting customs business for others requires a licensed broker).
+
+Write that boundary into any tool you build: a "needs broker review" status that blocks automated shipping.
+
+## 1. HS classification
+
+1. Collect for each product: what it is, material composition (percent), function, how it is used, whether it is a part or a finished good, and photos or spec sheets.
+2. The first 6 digits are the international Harmonized System maintained by the World Customs Organization; countries extend it (US HTS 10 digits, EU CN 8 digits and TARIC 10 digits, UK commodity codes 10 digits). Store the 6-digit code per product and the national code per destination.
+3. Classify by the General Rules of Interpretation, headings and section/chapter notes first, not by keyword search. Record the reasoning and the source.
+4. Use official tools to propose a code: the US HTS search (hts.usitc.gov), EU TARIC, the UK Trade Tariff (trade-tariff.service.gov.uk), or the destination's tariff. Check the current HS edition the destination uses.
+5. Mark every proposed code as `proposed` until a broker or binding ruling confirms it.
+
+Never pick a code because its duty is lower.
+
+## 2. Incoterms 2020
+
+Incoterms (ICC, 2020 edition) decide where risk passes, who pays which costs, and who clears export and import. They do not decide when title passes or the payment terms. Always write the rule plus a named place and the edition, for example `FCA Seller's warehouse, Leeds, Incoterms 2020`.
+
+Rule summaries and a selection guide are in `references/incoterms-2020.md`. Key decisions:
+
+- Containerised or multimodal shipments: use FCA, CPT, CIP, DAP, DPU or DDP, not FOB or CIF.
+- DDP makes the seller the importer of record and liable for import duty and taxes; only use it if the seller can register and pay in the destination.
+- EXW leaves export clearance to the buyer, which often does not work for the seller's own export reporting; FCA is usually the better minimum.
+
+## 3. Duties, taxes and landed cost
+
+```
+landed cost = product cost + freight + insurance + duty + import VAT/GST/sales tax + broker and carrier fees + other fees
+```
+
+- Customs value basis differs: many countries use CIF value (goods + freight + insurance to the border); the US uses transaction value excluding international freight and insurance. Confirm for the destination.
+- Duty = rate for the national code and origin x customs value (or a specific rate per unit). Check preferential rates only if the origin rules are met and documented.
+- Import VAT/GST is usually charged on value + duty. Treat VAT registration, IOSS and reverse-charge questions as a tax topic for the invoicing-and-tax skill and a tax adviser.
+- Low-value thresholds have changed fast: the US suspended de minimis duty-free entry for all countries from 29 August 2025, and from 1 July 2026 the EU removed its EUR 150 customs duty relief and applies a temporary flat duty of EUR 3 per tariff line in a low-value consignment (Council Regulation (EU) 2026/382; scope and counting rules are set in implementing acts). Always check the destination's current rules before relying on a threshold.
+- Additional duties (Section 232/301-type tariffs, retaliatory or emergency tariffs) change often; fetch current rates at calculation time and store the date and source with every quote.
+
+## 4. Commercial invoice
+
+Minimum fields to generate from your data:
+
+- Seller/exporter and buyer/consignee names and addresses; importer of record if different; tax or EORI numbers where required.
+- Invoice number and date, Incoterm with named place, currency, payment terms.
+- Per line: clear description (what it is and what it is made of, not "parts" or "gift"), HS code, country of origin, quantity and unit, unit price, line total.
+- Totals, freight and insurance shown separately if charged, gross and net weight, number of packages.
+- Reason for export (sale, sample, return, repair), and a signed declaration if the destination requires one.
+
+Values must be the real transaction value. Never undervalue or mark goods as a gift to cut duty; it is customs fraud.
+
+## 5. Restricted-party and sanctions screening
+
+1. Screen buyer, consignee, end user, and their banks or intermediaries where known, at order time and again before shipping.
+2. Sources: the US Consolidated Screening List from the International Trade Administration (search API at developer.trade.gov, which needs a subscription key, or a downloadable file), which combines lists including OFAC SDN and the BIS Entity List; the EU consolidated list of financial sanctions; the UK Sanctions List (the single UK source since 28 January 2026); plus lists for your other markets. Many teams use a commercial screening provider instead.
+3. Use fuzzy matching on names and aliases, plus address and country, and log every check with list version, timestamp and result.
+4. Possible match: hold the order, do not tell the customer why, and send it to the compliance owner. Never auto-clear a match in code.
+5. Block destinations under comprehensive embargo at checkout, using a list the compliance owner maintains.
+
+## Rules
+
+- Never present a proposed HS code, duty estimate or screening result as a final determination.
+- Never ship a held or "needs broker review" order automatically.
+- Never undervalue, misdescribe or misstate origin on documents.
+- Do not state a tariff rate, threshold or list rule you have not checked against the official source on the day.
+
+## Report
+
+```
+product | description | material | proposed HS6 | national code (dest) | origin | source/rationale | status (proposed | broker-confirmed)
+```
+
+For a shipment or calculator: Incoterm and named place, customs value basis, duty and tax lines with rate, source and date, landed cost per unit, screening result with list version, and the list of items that need broker or lawyer review.

package/skills/customs-trade-compliance/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We start shipping to the US and UK next month, add HS codes and country of origin to our product catalog",
+    "Build a landed cost calculator that adds duty, import VAT and freight for each destination country",
+    "Should we sell to European distributors on FCA or DAP, and what does each mean for us?",
+    "Generate commercial invoices for our international orders from the order data",
+    "Add restricted-party screening against the Consolidated Screening List before orders are released to the warehouse"
+  ],
+  "should_not_trigger": [
+    "Our container from Shanghai is two weeks late, help me update customers and chase the forwarder",
+    "Add VAT and GST calculation to our SaaS invoices for customers in 20 countries",
+    "Plan safety stock for imported parts that have a 12 week ocean lead time",
+    "Review our GDPR data processing agreement with a US vendor",
+    "Run a dependency audit for packages with known vulnerabilities"
+  ]
+}

package/skills/customs-trade-compliance/references/incoterms-2020.md

@@ -0,0 +1,42 @@
+# Incoterms 2020 quick reference
+
+Published by the International Chamber of Commerce (ICC). Eleven rules. This is a summary for building systems; the ICC text governs. The parties may still contract a different arrangement, so read the sales contract.
+
+## Rules for any mode of transport
+
+| Rule | Seller delivers / risk passes | Main carriage paid by | Export clearance | Import clearance and duties |
+|---|---|---|---|---|
+| EXW Ex Works | Goods at seller's premises, not loaded | Buyer | Buyer | Buyer |
+| FCA Free Carrier | Handed to buyer's carrier at named place (loaded if at seller's premises) | Buyer | Seller | Buyer |
+| CPT Carriage Paid To | Handed to the first carrier | Seller (to named destination) | Seller | Buyer |
+| CIP Carriage and Insurance Paid To | Handed to the first carrier | Seller, plus insurance | Seller | Buyer |
+| DAP Delivered at Place | At named destination, ready for unloading | Seller | Seller | Buyer |
+| DPU Delivered at Place Unloaded | At named destination, unloaded | Seller | Seller | Buyer |
+| DDP Delivered Duty Paid | At named destination, cleared for import | Seller | Seller | Seller |
+
+## Rules for sea and inland waterway only
+
+| Rule | Seller delivers / risk passes | Main carriage paid by | Export | Import |
+|---|---|---|---|---|
+| FAS Free Alongside Ship | Alongside the vessel at port of shipment | Buyer | Seller | Buyer |
+| FOB Free On Board | On board the vessel at port of shipment | Buyer | Seller | Buyer |
+| CFR Cost and Freight | On board the vessel at port of shipment | Seller (to destination port) | Seller | Buyer |
+| CIF Cost, Insurance and Freight | On board the vessel at port of shipment | Seller, plus insurance | Seller | Buyer |
+
+## Points that cause mistakes
+
+- In C rules (CPT, CIP, CFR, CIF) the seller pays carriage to the destination, but **risk passes at shipment**. Damage in transit is the buyer's risk.
+- Insurance: CIP requires cover at the level of Institute Cargo Clauses (A) (all risks, subject to exclusions); CIF requires the minimum, Clauses (C). Both at least 110% of the contract value. Parties may agree otherwise.
+- DPU replaced DAT in 2020 and can be any place, not only a terminal.
+- FCA in 2020 lets the parties agree that the buyer's carrier issues an on-board bill of lading to the seller, which matters for letters of credit.
+- Under DDP, VAT or GST at import is the seller's cost unless the contract says otherwise; the seller may need a tax registration in the destination.
+- Incoterms say nothing about title transfer, payment, or which law applies.
+
+## Choosing a rule (default guidance, confirm with the user)
+
+| Situation | Usually |
+|---|---|
+| E-commerce to consumers, seller wants a no-surprise delivery | DDP if registered for import taxes in the destination, otherwise DAP and tell the customer duties are due on delivery |
+| B2B, buyer has its own forwarder | FCA at seller's premises or a named hub |
+| B2B, seller arranges freight | CPT or CIP (container) / CFR or CIF (bulk sea cargo only) |
+| Buyer collects and seller cannot do export filings | EXW only if the buyer can legally act as exporter; otherwise FCA |

package/skills/dart-patterns/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: dart-patterns
+description: Writes and refactors idiomatic Dart 3 code that keeps sound null safety intact, models data with records, pattern matching and sealed class hierarchies, handles async/await, Streams and isolates without leaks or dropped futures, and manages pub dependencies and analysis_options.yaml lint sets. Use when writing or restructuring plain Dart (CLI, server, package or the non-widget layers of a Flutter app), replacing nullable soup or enum switches with sealed types and patterns, or tightening analyzer rules for a Dart codebase.
+license: MIT
+compatibility: Any Agent Skills host. Needs the Dart SDK 3.0 or newer (or Flutter, which bundles it) to run dart analyze and dart test.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "dart"
+  kete-loom/owner: "Kete-org"
+---
+
+# Dart patterns
+
+Write Dart that the analyzer can prove correct: no null escapes, exhaustive switches, every future accounted for. Widget composition and Flutter state management belong to `flutter-patterns`; this skill covers the language, async model, packages and lints underneath.
+
+## 0. Before you write
+
+1. Read `pubspec.yaml`: the `environment: sdk:` lower bound decides which language features you may use (records, patterns, sealed and class modifiers need `>=3.0.0`; extension types need 3.3). Don't raise the SDK bound without asking the user.
+2. Read `analysis_options.yaml` and follow the lint set already in force.
+3. Run `dart analyze` (or `flutter analyze`) first so you know which warnings were already there.
+
+## 1. Null safety
+
+- Make a type nullable only when absence is a real state. Prefer a non-null default or a required parameter.
+- Promote instead of asserting: `if (x == null) return;` then use `x`. Fields don't promote unless they are private and final (Dart 3.2+); copy to a local first: `final user = _user; if (user != null) ...`.
+- Use `??`, `?.`, `??=` and `if (value case final v?)` for optional values.
+- `!` is allowed only where an invariant the analyzer can't see is guaranteed and documented on the line above. Never use `!` to silence an error.
+- `late` is a promise checked at runtime. Use it only for fields set in `initState`/constructor bodies or lazy computed values (`late final x = compute();`). An unset `late` throws `LateInitializationError`.
+- Never call `.cast<T>()` or `as T` on decoded JSON without validating it; parse with patterns instead (section 2).
+
+## 2. Records and patterns
+
+- Return several values with a record instead of a throwaway class: `(int count, String label) summarize()` or named `({int count, String label})`.
+- Destructure at the call site: `final (count, label) = summarize();`.
+- Validate untyped data with a map pattern, which checks type and shape in one step:
+
+```dart
+User parseUser(Object? json) {
+  if (json case {'id': int id, 'name': String name, 'email': String? email}) {
+    return User(id: id, name: name, email: email);
+  }
+  throw FormatException('Invalid user JSON: $json');
+}
+```
+
+- A map pattern fails if a key is missing, even when its value pattern is nullable (`String? email` above needs `'email'` present). For optional keys, read `json['email']` separately after the match.
+- Use switch expressions for value mapping, with guards (`when`) for conditions. Prefer them to `if/else` ladders.
+- Wildcard `_` matches anything; don't add a `_` case to a switch over a sealed type or enum, because it hides new cases from the exhaustiveness check.
+
+## 3. Sealed classes and class modifiers
+
+Model closed sets of states with `sealed`; the compiler then forces every `switch` to handle each subtype.
+
+```dart
+sealed class LoadState<T> {}
+final class Loading<T> extends LoadState<T> {}
+final class Loaded<T> extends LoadState<T> { Loaded(this.value); final T value; }
+final class Failed<T> extends LoadState<T> { Failed(this.error); final Object error; }
+
+String describe(LoadState<String> s) => switch (s) {
+  Loading() => 'loading',
+  Loaded(:final value) => 'got $value',
+  Failed(:final error) => 'failed: $error',
+};
+```
+
+- Subtypes of a sealed class must live in the same library (file or `part`s).
+- Pick modifiers deliberately in public packages: `final` (no subclassing or implementing outside the library), `interface` (implement only), `base` (extend only), `mixin class`. Adding a modifier to a published type is a breaking change.
+- Prefer immutable value types: `final` fields, `const` constructors, and `==`/`hashCode` (or a code generator such as `freezed` if the project already uses one; don't introduce one unasked).
+
+## 4. Async and Futures
+
+- Every `Future` is awaited, returned, or explicitly handed off with `unawaited(...)` from `dart:async` with a comment saying why. A dropped future swallows its error.
+- Mark functions `async` only when they await. Return `Future<void>`, never `void`, from async functions (except overrides that require `void`).
+- Run independent work concurrently: `final (a, b) = await (fetchA(), fetchB()).wait;` or `Future.wait([...])`.
+- Add timeouts at I/O boundaries: `await request.timeout(const Duration(seconds: 10))`, and handle `TimeoutException`.
+- In Flutter code, after any `await` inside a `State`, check `if (!mounted) return;` (or `context.mounted`) before touching `context` or calling `setState`.
+
+## 5. Streams
+
+- Know the kind: single-subscription streams (most I/O) allow one listener; use `asBroadcastStream()` or a `StreamController.broadcast()` only when several listeners are really needed.
+- Every `listen` returns a `StreamSubscription`; store it and `cancel()` it in the owner's `dispose`/`close`. Prefer `await for` when the consumer is a single async function, because it cancels on `break` or exception automatically.
+- Every `StreamController` you create is closed by its owner (`await controller.close()`), and `add` is never called after close (check `isClosed`).
+- Pass `onError` to `listen` or the error goes to the zone and can crash the app.
+- Use `async*` with `yield` for generated streams instead of hand-managed controllers.
+
+## 6. Isolates
+
+- Move CPU-heavy work (large JSON decode, image processing, crypto) off the main isolate with `await Isolate.run(() => heavy(input))` (Flutter's `compute` is equivalent).
+- Messages are copied; pass plain data, not objects holding sockets, open files or closures over large state.
+- For long-lived workers use `Isolate.spawn` with `SendPort`/`ReceivePort`, and close the ports when done.
+- Don't use isolates for I/O-bound work; async already handles it.
+
+## 7. Errors
+
+- Throw `Exception` subtypes for recoverable conditions callers should handle; `Error` subtypes (`ArgumentError`, `StateError`, `UnsupportedError`) signal programmer bugs and should not be caught in normal flow.
+- Catch narrowly: `on FormatException catch (e, st)`. A bare `catch (e)` is allowed only at a top-level boundary that logs and reports.
+- Keep the stack trace: `rethrow`, or `Error.throwWithStackTrace(MyException(...), st)` when wrapping.
+- For expected failures in domain code, a sealed `Result` type (section 3) is often clearer than exceptions. Follow what the codebase already does.
+
+## 8. Packages (pub)
+
+- Add dependencies with `dart pub add <pkg>` (`dev:<pkg>` for dev dependencies) so constraints are written correctly; use caret constraints (`^1.4.0`).
+- Inspect before upgrading: `dart pub outdated`, `dart pub deps`. Major upgrades (`dart pub upgrade --major-versions`) need the user's agreement.
+- Commit `pubspec.lock` for applications; don't commit it for regular (reusable) packages.
+- `dependency_overrides` is a temporary diagnostic tool, never a permanent fix. Stop and ask before leaving one in.
+- Code generation: `dart run build_runner build` (or `watch`). Commit or ignore generated `*.g.dart` files the way the project already does.
+
+## 9. Lints and analysis
+
+Start from the official sets (`lints` for Dart, `flutter_lints` for Flutter, added as dev dependencies) and add rules that catch real bugs. On an existing codebase add one rule at a time and run `dart analyze` after each.
+
+```yaml
+include: package:lints/recommended.yaml   # Flutter apps: package:flutter_lints/flutter.yaml
+analyzer:
+  language:
+    strict-casts: true        # no implicit downcasts from dynamic
+    strict-inference: true    # no silently inferred dynamic
+    strict-raw-types: true    # no List without a type argument
+  exclude:
+    - "**/*.g.dart"
+linter:
+  rules:
+    - unawaited_futures
+    - discarded_futures
+    - cancel_subscriptions
+    - close_sinks
+    - avoid_dynamic_calls
+    - only_throw_errors
+```
+
+| Rule | Catches |
+|---|---|
+| `unawaited_futures` | a `Future` in an `async` function neither awaited nor wrapped in `unawaited(...)` |
+| `discarded_futures` | a `Future`-returning call dropped inside a synchronous function |
+| `cancel_subscriptions` / `close_sinks` | a `StreamSubscription` never cancelled / a `StreamController` or sink never closed |
+| `avoid_dynamic_calls` | method calls on `dynamic`, which skip type checking |
+| `only_throw_errors` | throwing strings or other non-`Exception`/`Error` objects |
+
+The strict language modes can produce hundreds of errors in a large codebase; ask the user before enabling them beyond new code.
+
+- Fix warnings rather than suppressing them. An `// ignore: rule_name` needs a reason on the same line, and `// ignore_for_file` needs the user's agreement.
+- `dart fix --dry-run` then `dart fix --apply` handles many lint fixes mechanically; review the diff.
+- Format with `dart format .`; don't hand-format against it.
+
+## Never do
+
+- Use `dynamic` to get past a type error, or `as` casts on unvalidated data.
+- Add `!` or `late` to silence the analyzer.
+- Leave a `StreamSubscription`, `StreamController`, `Timer` or `ReceivePort` without a cancel/close path.
+- Raise the SDK constraint, add a code generator or change the lint set without asking.
+
+## Finish
+
+Run `dart format --output=none --set-exit-if-changed .`, `dart analyze` (or `flutter analyze`) and the test command. Report: files changed, the commands run with results, and any new warnings you could not fix with the reason.

package/skills/dart-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Refactor this Dart class hierarchy into a sealed class so the switch is exhaustive",
+    "How should I parse this JSON map in Dart 3 without casting everything to dynamic?",
+    "Return two values from this Dart function, should I use a record?",
+    "Set up analysis_options.yaml with stricter lints for our Dart server package",
+    "My Dart code is full of ! operators, help me restructure it so null safety actually works",
+    "Move this heavy JSON decoding off the main isolate in my Dart app"
+  ],
+  "should_not_trigger": [
+    "Write unit tests with mocktail for my Dart repository class",
+    "Review this Flutter widget for setState after dispose and other bugs",
+    "flutter analyze fails with 47 errors after I upgraded packages, fix it",
+    "Build a responsive Flutter layout with a bottom navigation bar and Riverpod state",
+    "Refactor this Kotlin sealed interface into idiomatic Kotlin",
+    "Add golden tests for my Flutter login screen"
+  ]
+}