@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/investor-materials/references/templates.md

@@ -0,0 +1,74 @@
+# Investor materials: templates
+
+Read this when drafting. Replace every `<...>` with the founder's facts; leave a visible `TODO` where a fact is missing instead of guessing.
+
+## Pitch deck slide prompts
+
+| Slide | Headline pattern | Body | Check |
+|---|---|---|---|
+| Title | `<Company>: <what it does for whom>` | Logo, contact, round | Understandable without speaking |
+| Problem | `<Customer> loses <cost> because <cause>` | Quote or data point, current workaround | Specific customer, not "everyone" |
+| Solution | `<Product> lets <customer> <outcome>` | Screenshot or 3-step flow | Shows the product |
+| Why now | `<Change> makes this possible now` | 1-3 changes with dates | Real change, not hype |
+| Traction | `<Metric> grew <x> in <period>` | One chart, 2-3 supporting numbers | Dates, definitions, axes |
+| Market | `<N> <customers> x <price> = <size>` | Bottom-up arithmetic, sources | Shows the calculation |
+| Business model | `We earn <price> per <unit>` | Pricing, margin, unit economics | Matches traction numbers |
+| Competition | `Customers choose us because <reason>` | Matrix or table of alternatives | Includes "do nothing" |
+| Go-to-market | `We acquire customers through <channel>` | Current CAC or conversion if known | Evidence, not plans only |
+| Team | `<Team> has done <relevant thing>` | Founders, key hires, advisers | Relevance to this problem |
+| Ask | `Raising <amount> to reach <milestone>` | Instrument, use of funds, runway | Percentages sum to 100 |
+
+## One-pager
+
+```
+# <Company>: <one-line description>
+<Website> | <Founder name, email> | Raising <amount> <instrument>
+
+**Problem.** <2 sentences>
+**Solution.** <2 sentences>
+**Traction.** <best metric with date>; <2 supporting numbers>
+**Market.** <bottom-up size, one line of arithmetic>
+**Business model.** <how you charge, price>
+**Competition.** <alternatives and why customers pick you>
+**Team.** <founders, one line each>
+**The ask.** <amount>, <use of funds in 3 buckets>, reaching <milestone> with <n> months runway
+```
+
+## Investor update (email)
+
+```
+Subject: <Company> update, <Month Year>: <headline>
+
+Hi all,
+
+TL;DR: <one line>
+
+| Metric | This period | Last period | Change |
+|---|---|---|---|
+| <MRR> | | | |
+| <Active customers> | | | |
+| <Burn / month> | | | |
+| Runway (months) | | | |
+
+Wins
+- <...>
+
+Challenges
+- <problem>, what we are doing: <action>
+
+Asks
+- <specific intro: name or profile, why>
+
+Thanks,
+<Founder>
+```
+
+## Review checklist
+
+- [ ] Narrative fits in five sentences and every slide supports one.
+- [ ] Each metric is defined and dated, and matches across documents.
+- [ ] The ask has an amount, instrument, use of funds and milestone.
+- [ ] Market size includes a bottom-up calculation.
+- [ ] Competition slide names real alternatives.
+- [ ] Projections are labelled as projections.
+- [ ] No claim without a source the founder can show.

package/skills/invoicing-and-tax/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: invoicing-and-tax
+description: Guides software teams through issuing legally usable invoices and charging sales tax, VAT or GST correctly, covering required invoice fields and sequential numbering, choosing a tax calculation service or merchant of record over hand-rolled rate tables, registration thresholds and nexus at a high level, reverse charge for B2B, tax-inclusive versus exclusive pricing, line-level rounding, and national e-invoicing mandates such as Peppol, KSeF and Factur-X, with a firm handoff to a qualified accountant for anything that is a tax position. Use when building or fixing invoice generation, adding VAT or sales tax to checkout, deciding whether to integrate Avalara, Stripe Tax or a merchant of record, or preparing for an e-invoicing deadline in a country you sell into.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral. Tax thresholds, rates and mandate dates change often; the agent must check official sources before quoting them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Invoicing and tax
+
+Produce invoices that a tax authority would accept and tax amounts a customer can re-add by hand, while keeping every tax *decision* with a qualified person. You build the machinery; an accountant or tax adviser decides where you are registered, what is taxable and at which rate.
+
+## What this skill does not cover
+
+- It is not tax or legal advice. It does not decide whether a product is taxable, whether you have nexus or a VAT obligation somewhere, which rate or exemption applies, or how to file returns.
+- It does not cover payroll tax, income or corporate tax, customs duties (see `customs-trade-compliance` if installed), or revenue recognition policy.
+- Thresholds, rates and deadlines in this skill and its references are orientation only and may be out of date. Before relying on one, check the tax authority's own site and say which source and date you used.
+
+**Stop and ask for a qualified accountant or tax adviser** before: registering or not registering somewhere, choosing a product tax code or exemption, applying reverse charge or zero rating, issuing invoices in a new country, changing how past invoices were taxed, or answering a customer's tax dispute.
+
+## Ground rules
+
+1. **Never hand-roll rate tables** for more than a single jurisdiction you are registered in. Rates, product taxability and US local jurisdictions change constantly. Use a tax engine (Avalara AvaTax, Stripe Tax, Anrok, TaxJar, Quaderno and similar) or a merchant of record (Paddle, Lemon Squeezy and similar), which becomes the seller and takes on the tax liability.
+2. **Store the tax decision on the invoice line**, not just the result: jurisdiction, rate, tax code, taxable amount, tax amount, and the engine's transaction or calculation ID. You must be able to explain an old invoice after rates change.
+3. **Invoices are immutable once issued.** Correct with a credit note that references the original and reverses its tax in proportion. Never edit, renumber or delete.
+4. **Numbering**: one sequential series per legal entity (and per series type if the jurisdiction allows), assigned at finalisation inside a transaction, no reuse. Many VAT regimes require a unique sequential number; gaps need an explanation.
+5. **Money is integer minor units plus currency.** Round with the method the jurisdiction specifies, at the level it specifies (line or invoice total). Details in `references/rounding.md`.
+6. **Customer location evidence** is stored with each sale (billing address, IP country, payment method country, VAT ID validation result) because B2C digital sales in many regimes are taxed where the customer is.
+7. **Validate B2B tax IDs** before applying reverse charge: EU VAT numbers via the EU [VIES](https://ec.europa.eu/taxation_customs/vies/) service, UK VAT numbers via HMRC's [check a UK VAT number](https://www.gov.uk/check-uk-vat-number) service, and store the check result and timestamp.
+
+## Workflow
+
+1. **Inventory.** Search the codebase for invoice generation, PDF templates, numbering, tax calculation, the checkout price display, and credit notes. List which legal entity issues invoices and where customers are.
+2. **Ask the user for the tax position** (from their accountant): where they are registered, products' tax codes, whether prices are tax-inclusive per market, B2B vs B2C mix. If unknown, stop; don't guess.
+3. **Pick the approach** with the table below and confirm with the user.
+4. **Required fields.** Check the invoice against the jurisdiction's list. EU baseline is in `references/invoice-fields.md`; others vary.
+5. **Integrate the engine**: calculate at quote/checkout with the full address and tax IDs, commit (record) the transaction when the invoice is finalised, and void or refund it in the engine when you issue a credit note. Calculate-only calls without commits leave the engine's reports empty.
+6. **Prices display**: show tax-inclusive prices to consumers where that is the norm (EU, UK, Australia) and tax-exclusive plus tax at checkout where that is the norm (US). Decide per market with the user.
+7. **E-invoicing**: check whether any country you invoice in mandates structured e-invoices for your customer type; see `references/e-invoicing.md`. Usually this means an accredited provider or Peppol access point, not building the transmission yourself.
+8. **Test** with fixtures: one domestic B2C, one domestic B2B, one cross-border B2B with a valid tax ID (reverse charge), one with an invalid tax ID, one US address in a taxing state, a refund producing a credit note, a multi-line invoice that stresses rounding.
+
+## Choose the approach
+
+| Situation | Usually |
+|---|---|
+| One country, registered there, simple products | Engine is optional; a reviewed, tested rate config for that one country is acceptable |
+| Selling to consumers in many countries, small team | Merchant of record, or a tax engine plus registrations your adviser sets up |
+| US sales across states | Tax engine; economic nexus thresholds differ by state |
+| Marketplace or platform paying out to sellers | Stop and ask; marketplace facilitator rules may make you the collector |
+| Large B2B, ERP-driven | Tax engine integrated with the ERP; invoices issued from one system only |
+
+## Thresholds at a high level
+
+Registration duty depends on where you are established, what you sell and to whom. Orientation only, all to be verified with the authority before use:
+
+- **US sales tax**: since [*South Dakota v. Wayfair*](https://www.supremecourt.gov/opinions/17pdf/17-494_j4el.pdf) (2018), states can require remote sellers to collect once they cross an economic nexus threshold. The South Dakota law upheld there used more than 100,000 USD of sales or 200 transactions a year into the state; each state sets its own figures and tests, so check that state's revenue department. Taxability of SaaS and digital goods differs by state.
+- **EU VAT**: a seller established in only one EU member state has a 10,000 EUR EU-wide annual threshold (current and preceding calendar year) for cross-border B2C telecoms, broadcasting and electronic services and intra-EU distance sales of goods; above it, VAT is due in the customer's country, usually declared via the [One Stop Shop](https://vat-one-stop-shop.ec.europa.eu/one-stop-shop_en) (OSS). Sellers not established in the EU have no threshold for B2C services and use the non-Union OSS.
+- **UK VAT**: [registration threshold](https://www.gov.uk/register-for-vat) 90,000 GBP of taxable turnover over the last 12 months, or expected within the next 30 days, for UK-established businesses; [non-established taxable persons](https://www.gov.uk/government/publications/vat-notice-7001-should-i-be-registered-for-vat/vat-notice-7001-should-i-be-registered-for-vat) must register on their first UK taxable supply, with no threshold.
+- **Others** (Australia, Canada, India, Norway, Switzerland, Singapore, many more) have their own regimes for foreign digital sellers. Look them up per country.
+
+## Never
+
+- Never present computed tax as advice, or tell a user they don't need to register somewhere.
+- Never silently apply 0% because a tax ID field is non-empty; validate it.
+- Never recalculate tax on an issued invoice with today's rates.
+- Never compute tax on floats or round the total separately from lines without a defined rule.
+- Never generate invoices from two systems for the same sale (for example, both the payment provider and your app).
+
+## Report format
+
+When reviewing or designing, return:
+
+```
+Issuing entity and series: <entity, numbering scheme>
+Approach: <engine | merchant of record | single-country config>
+Markets checked: <country: B2B/B2C, registered?, inclusive/exclusive, e-invoice mandate?, source + date checked>
+Field gaps: <missing required fields per market>
+Rounding rule: <method, level>
+Needs accountant decision: <list>
+```

package/skills/invoicing-and-tax/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our generated PDF invoices are missing the customer's VAT number and the reverse charge note for EU business customers",
+    "Should we integrate Avalara or Stripe Tax, or switch to a merchant of record like Paddle for selling SaaS worldwide?",
+    "Belgium now requires Peppol e-invoices for B2B; what do we need to change in our invoicing system?",
+    "Tax on our invoices is off by a cent compared with the total; should VAT be rounded per line or per invoice?",
+    "We start selling to US customers in several states. How do we figure out where we need to collect sales tax?",
+    "Make our invoice numbers sequential and gap-free per legal entity, they currently use random IDs"
+  ],
+  "should_not_trigger": [
+    "Implement mid-cycle proration when a customer upgrades from the monthly to the annual plan",
+    "Classify our product under the right HS code for importing into the EU",
+    "Sync invoices from our app into Xero with the right account codes",
+    "Check our payroll setup for the right employer tax withholding",
+    "Review this pull request that changes how invoice totals are calculated"
+  ]
+}

package/skills/invoicing-and-tax/references/e-invoicing.md

@@ -0,0 +1,24 @@
+# E-invoicing mandates
+
+An e-invoice here means a structured, machine-readable invoice (XML such as UBL or CII), often sent through a network or a government platform. A PDF by email is not one.
+
+**Dates below were checked against the national authorities' own pages in October 2026 (linked in the table) and change often. Check the authority again before acting, and record the source and date you used.**
+
+| Country | Status as reported | Format / channel |
+|---|---|---|
+| Italy ([Agenzia delle Entrate](https://www.agenziaentrate.gov.it/portale/web/guest/schede/comunicazioni/fatture-e-corrispettivi/faq-fe/risposte-alle-domande-piu-frequenti-categoria/emissione-delle-fatture-elettroniche-imprese)) | Domestic B2B and B2C via SDI since 1 Jan 2019 (consumers can get a paper or PDF copy) | FatturaPA XML through Sistema di Interscambio |
+| Germany ([BMF FAQ](https://www.bundesfinanzministerium.de/Content/DE/FAQ/e-rechnung.html)) | Domestic B2B: all businesses must be able to receive e-invoices since 1 Jan 2025. Other invoice types allowed until 31 Dec 2026, or until 31 Dec 2027 for issuers with prior-year turnover up to 800,000 EUR. So issuing is mandatory from 1 Jan 2027 for larger issuers and from 1 Jan 2028 for all | EN 16931 formats such as XRechnung or ZUGFeRD/Factur-X |
+| Belgium ([einvoice.belgium.be](https://einvoice.belgium.be/en/article/structured-electronic-invoices-between-companies-are-compulsory-2026)) | Structured e-invoices mandatory between Belgian VAT-registered businesses since 1 Jan 2026; not for consumers; cross-border out of scope until ViDA | Peppol network, Peppol BIS as the reference format |
+| Poland ([ksef.podatki.gov.pl](https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/)) | Receiving via KSeF mandatory for all from 1 Feb 2026; issuing from 1 Feb 2026 for taxpayers with 2024 sales over 200m PLN, from 1 Apr 2026 for others; those invoicing at most 10,000 PLN gross a month have until the end of 2026 | National KSeF platform, structured XML |
+| France ([impots.gouv.fr](https://www.impots.gouv.fr/facturation-electronique-et-plateformes-agreees)) | Receiving for all businesses, and issuing plus e-reporting for large and mid-size (GE, ETI), from 1 Sep 2026; issuing for SMEs and micro-businesses from 1 Sep 2027 | Via approved platforms (plateformes agréées); check DGFiP's specifications for the accepted formats |
+| EU-wide ([ViDA](https://taxation-customs.ec.europa.eu/taxation/vat/vat-digital-age-vida_en)) | VAT in the Digital Age package adopted 11 Mar 2025; mandatory e-invoicing with digital reporting for intra-EU B2B transactions from 1 Jul 2030; national systems to align by 1 Jan 2035 | EN 16931 baseline |
+
+Outside the EU, mandates exist in many countries (for example India, Mexico, Saudi Arabia, Malaysia, Türkiye, Brazil) with their own schemas and clearance steps.
+
+## What it means for a software team
+
+1. List where your customers are and which are businesses. Mandates mostly target domestic B2B first.
+2. Most teams connect to an accredited provider or a Peppol access point rather than implementing the network or government API directly.
+3. Your invoice data must already contain everything the format needs: buyer tax ID, structured address, per-line tax category codes, unit codes, payment means. Gaps here are the usual blocker.
+4. Archive the structured invoice as sent, for the retention period the country requires.
+5. Receiving is also a mandate in some countries; check whether you must accept supplier e-invoices in your accounts payable process.

package/skills/invoicing-and-tax/references/invoice-fields.md

@@ -0,0 +1,38 @@
+# Invoice fields
+
+## EU VAT invoice baseline
+
+The EU VAT Directive ([2006/112/EC](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:02006L0112-20250414), Article 226) lists what a full VAT invoice must show. Member states implement it in national law and may add rules, so check the country's guidance too. Summary of the list:
+
+1. Date of issue
+2. Sequential number that uniquely identifies the invoice
+3. Supplier's VAT identification number
+4. Customer's VAT identification number where the customer is liable for the tax (reverse charge) or for intra-EU supplies of goods
+5. Full name and address of supplier and customer
+6. Quantity and nature of goods, or extent and nature of services
+7. Date of supply or payment, if different from the issue date
+8. Taxable amount per rate or exemption, unit price excluding VAT, and any discounts not included in the unit price
+9. VAT rate applied
+10. VAT amount payable
+11. Where exempt or reverse charged, a reference to the provision or the wording such as "Reverse charge"
+12. Other mentions where they apply: "Self-billing", "Cash accounting", the margin scheme wording, new means of transport details, a tax representative's VAT number, name and address
+
+The invoice may be in any currency, but the VAT payable must also be expressed in the national currency of the member state (Article 230).
+
+Simplified invoices with fewer fields (Article 226b) are allowed for low amounts; the limit is set nationally within the Directive's rules.
+
+## Fields that help everywhere
+
+- Legal entity name, registered address, company number where local law requires it
+- Payment terms, due date, how to pay
+- Purchase order number when the customer gives one
+- Service period for subscriptions (`1 Apr 2026 – 30 Apr 2026`)
+- For credit notes: "Credit note", own number, and the original invoice number and date
+
+## United States
+
+There is no federal invoice format. States set what a sales tax invoice or receipt must show; the tax amount is commonly shown separately. A tax engine's documentation usually lists state requirements.
+
+## Elsewhere
+
+Many countries (for example Mexico CFDI, India GST e-invoicing, Brazil NF-e, Saudi Arabia, Türkiye) require government-validated electronic invoices with specific schemas and IDs. Don't generate a PDF and assume it is valid there; use an accredited provider and check the authority's rules.

package/skills/invoicing-and-tax/references/rounding.md

@@ -0,0 +1,26 @@
+# Tax rounding
+
+## Pick and document
+
+- **Level**: per line (compute tax per line, round, sum) or per invoice (sum taxable amounts per rate, compute tax once, round). Some authorities specify one. EN 16931 e-invoices compute VAT per VAT category and rate: the category taxable amount is the sum of line net amounts plus charges minus allowances ([BR-S-08](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/BR-S-08/) for standard rate), and the category tax amount must equal taxable amount × rate, rounded to two decimals ([BR-CO-17](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/BR-CO-17/)). Per-line-rounded tax can fail that check; if you issue e-invoices, use per-invoice-per-rate. Ask the accountant which applies.
+- **Method**: half-up is the usual commercial default; some regimes specify otherwise. Use a decimal type, never binary floats.
+- **Inclusive prices**: tax = gross × rate ÷ (1 + rate). Round tax, then net = gross − tax, so net + tax always equals the advertised gross.
+
+## Example of the difference
+
+Three lines of 0.99 (minor units: 99) at 20% VAT, tax-exclusive:
+
+```
+per line:    round(99 * 0.20) = round(19.8) = 20 per line → 60 total
+per invoice: round(297 * 0.20) = round(59.4) = 59
+```
+
+A one-unit difference per invoice adds up and makes tax returns disagree with ledgers. Whatever you choose, the tax engine, your invoice PDF and the accounting system must use the same rule.
+
+## Tests worth having
+
+- Many small lines at a rate that produces .5 fractions
+- A tax-inclusive price where `gross / (1 + rate)` has a repeating decimal
+- Mixed rates on one invoice (summed per rate)
+- A credit note for one line of a multi-line invoice: its tax must equal the tax originally charged on that line
+- Zero-decimal (JPY) and three-decimal (KWD) currencies

package/skills/java-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: java-patterns
+description: Idiomatic modern Java (17 and 21 LTS and later) for writing and restructuring code with records, sealed interfaces, switch pattern matching, Optional, streams, checked versus unchecked exceptions, immutable collections, virtual threads and a standard Maven or Gradle layout. Use when writing new Java classes, modernising pre-17 Java code, choosing between a record, enum or sealed hierarchy, or deciding how to run blocking work concurrently on the JVM.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK 17 or newer and the project's Maven or Gradle build.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Modern Java patterns
+
+Write Java that the compiler checks for you: model data with types, make illegal states unrepresentable, and keep mutation local.
+
+## 0. Before you write
+
+1. Find the language level the build actually uses: `maven.compiler.release` or `<release>` in `pom.xml`, or `java { toolchain { languageVersion = ... } }` / `options.release` in `build.gradle(.kts)`. Use only features that level allows. Never raise it without asking the user.
+2. Match the codebase: if it already uses Lombok, Vavr, Guava or a null-annotation library (JSpecify, JetBrains, Checker Framework), follow that convention rather than mixing styles.
+3. Feature floor, by release: records (16), sealed classes (17), pattern matching for `switch` and record patterns (21), virtual threads (21), unnamed variables `_` (22), scoped values (25). Preview features need `--enable-preview`; don't introduce them unless the project already does.
+
+## 1. Model data
+
+| Need | Use |
+|---|---|
+| Immutable value with fields, equality by value | `record` |
+| Fixed set of constants | `enum` |
+| One of several shapes with different data | `sealed interface` + `record` implementations |
+| Mutable entity with identity (JPA entity, builder state) | ordinary class |
+
+- Validate in the record's compact constructor and copy mutable inputs: `this.items = List.copyOf(items);`.
+- A record's `equals`, `hashCode` and `toString` are generated. If a record holds an array, they compare by reference; prefer a `List`.
+- Don't use records for JPA entities: they need a no-arg constructor, mutability and proxying.
+- Keep sealed hierarchies in one package (or one module) and list `permits` only when the subtypes live in other files.
+
+```java
+sealed interface Payment permits Card, MobileMoney, Cash {}
+record Card(String last4, Money amount) implements Payment {}
+record MobileMoney(String msisdn, Money amount) implements Payment {}
+record Cash(Money amount) implements Payment {}
+
+String describe(Payment p) {
+    return switch (p) {                      // exhaustive: no default needed
+        case Card c -> "card ending " + c.last4();
+        case MobileMoney(var msisdn, var amt) -> "MoMo " + msisdn;
+        case Cash cash -> "cash";
+    };
+}
+```
+
+Leave `default` out of a switch over a sealed type, so adding a subtype becomes a compile error at every switch that must handle it.
+
+## 2. Null and Optional
+
+1. Return `Optional<T>` from methods where "no result" is a normal outcome (lookups). Never return `null` from a method declared to return `Optional`.
+2. Don't use `Optional` for fields, parameters or collection elements. Return an empty collection, never `null`.
+3. Consume with `map`, `filter`, `orElse`, `orElseGet` (when the default is expensive), `orElseThrow`. Avoid `isPresent()` + `get()`.
+4. Check arguments at public boundaries: `Objects.requireNonNull(x, "x")`.
+5. `Map.get` returns `null` for missing keys; use `getOrDefault`, `computeIfAbsent` or `containsKey` deliberately.
+
+## 3. Collections and streams
+
+- Prefer `List.of`, `Set.of`, `Map.of` and `List.copyOf` for immutable results. They reject `null` elements and throw on mutation.
+- `stream().toList()` (16+) returns an unmodifiable list; `Collectors.toList()` makes no such promise. Pick deliberately when callers mutate the result.
+- Use a stream when the pipeline reads clearly (filter, map, collect). Use a loop when you need early exit with side effects, checked exceptions, or index arithmetic.
+- Never mutate shared state from inside `map` or `forEach` in a stream. Collect instead.
+- `Collectors.toMap` throws on duplicate keys; pass a merge function when duplicates are possible.
+- Don't add `.parallel()` without measuring; it runs on the common ForkJoinPool and rarely helps I/O-bound work.
+
+## 4. Exceptions
+
+1. Throw unchecked exceptions for programming errors and for failures callers can't reasonably recover from. Use checked exceptions only when the caller must handle the case.
+2. Never swallow: an empty `catch`, or `catch (Exception e) { log.error(e.getMessage()); }`, hides the stack trace. Log the exception object, or rethrow wrapped with the cause: `throw new OrderException("charge failed for " + id, e);`.
+3. Catch the narrowest type. Don't catch `Throwable` or `Error`.
+4. Use try-with-resources for anything `AutoCloseable` (streams, JDBC connections, `ExecutorService` on 19+).
+5. On `InterruptedException`, restore the flag (`Thread.currentThread().interrupt()`) before rethrowing or returning.
+
+## 5. Immutability and equality
+
+- Make fields `final` by default. Expose no setters unless a framework needs them.
+- If you override `equals`, override `hashCode` with the same fields. Never use mutable fields in either for objects stored in a `HashSet` or as `HashMap` keys.
+- Compare strings and boxed numbers with `equals`, never `==`. Compare `BigDecimal` values with `compareTo`, because `equals` also compares scale.
+- Use `BigDecimal` (or integer minor units) for money, never `double`.
+
+## 6. Concurrency
+
+Choose by workload:
+
+| Workload | Use |
+|---|---|
+| Many blocking tasks (HTTP calls, JDBC, file I/O) on 21+ | virtual threads: `Executors.newVirtualThreadPerTaskExecutor()` |
+| CPU-bound work | a fixed pool sized near `Runtime.getRuntime().availableProcessors()` |
+| Composing async results | `CompletableFuture` with an explicit executor |
+| Shared counters / maps | `AtomicLong`, `LongAdder`, `ConcurrentHashMap` |
+
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Quote>> futures = suppliers.stream()
+        .map(s -> executor.submit(() -> s.fetchQuote(order)))
+        .toList();
+    // close() waits for all tasks
+}
+```
+
+Virtual thread rules:
+
+1. Create one per task; never pool them.
+2. Limit access to scarce resources (database connections, rate-limited APIs) with a `Semaphore`, not by shrinking a pool.
+3. Avoid large `ThreadLocal` caches; with millions of threads they multiply memory.
+4. On JDK 21 to 23, blocking inside `synchronized` pins the carrier thread; use `ReentrantLock` around blocking calls. JDK 24+ removed most of that pinning (JEP 491).
+5. Virtual threads don't make CPU-bound code faster.
+
+General rules: guard every piece of shared mutable state with one lock or make it immutable; never call `Thread.stop`; never block inside a `CompletableFuture` callback on the common pool; give threads and executors names for diagnostics.
+
+## 7. Build layout
+
+- Maven and Gradle share the layout: `src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`. Packages follow reversed domain names (`com.example.orders`).
+- Use the wrapper the repo ships (`./mvnw`, `./gradlew`), never a globally installed version.
+- Set the language level with `release` (Maven `maven.compiler.release`, Gradle toolchains) rather than `source`/`target`, so the compiler also checks the JDK API level.
+- Pin dependency versions in one place: Maven `<dependencyManagement>` or a BOM; Gradle version catalogs (`gradle/libs.versions.toml`) or platforms.
+- Common commands: `./mvnw -q verify`, `./gradlew build`, `./mvnw dependency:tree`, `./gradlew dependencies --configuration runtimeClasspath`.
+
+## Never
+
+- Return `null` for a collection or an `Optional`.
+- Use raw types (`List` instead of `List<String>`).
+- Catch an exception just to log and continue as if it succeeded.
+- Add a dependency for something the JDK already does (`java.net.http.HttpClient`, `java.time`, `HexFormat`).
+- Use `java.util.Date` or `Calendar` in new code; use `java.time` (`Instant`, `LocalDate`, `ZonedDateTime`).
+
+## Stop and ask the user
+
+- Before raising the Java release level, adding Lombok, or enabling preview features.
+- Before changing a public API's signature that other modules or services call.
+- When moving existing thread-pool code to virtual threads in a service that holds locks or `ThreadLocal` state you can't fully trace.
+
+## Finish
+
+Compile and run the tests with the project's build command. Report what changed, the Java level you targeted, and anything you left on an older pattern on purpose.

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

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Convert these Java DTO classes to records and use a sealed interface for the payment types",
+    "What's the idiomatic way to handle a lookup that may return nothing in Java 21, Optional or null?",
+    "Our Spring service makes 200 blocking HTTP calls per request, should I use virtual threads?",
+    "Modernise this Java 8 code to Java 17: switch expressions, streams, immutable collections",
+    "Should this Java hierarchy be an enum, a record or a sealed interface?"
+  ],
+  "should_not_trigger": [
+    "Write JUnit 5 tests with Mockito for the OrderService class",
+    "Maven fails with 'package javax.annotation does not exist' after upgrading to JDK 21, fix the build",
+    "Review my Java pull request for resource leaks and equals/hashCode bugs",
+    "Convert this Java data class to an idiomatic Kotlin data class",
+    "Set up Spring Boot auto-configuration and a REST controller for orders",
+    "Map this JPA entity with a lazy OneToMany and fix the N+1 queries in the order list"
+  ]
+}

package/skills/java-testing/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: java-testing
+description: Writes and repairs JVM tests in Java with JUnit Jupiter, AssertJ assertions, Mockito mocks, parameterized cases, Testcontainers-backed integration tests and Spring Boot test slices, and tracks down flaky tests. Use when adding unit or integration tests to a Java project, choosing between a mock and a real database container, speeding up a slow Java test suite, or diagnosing a JUnit test that passes locally and fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Maven or Gradle build; Testcontainers needs a running Docker-compatible engine.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Java testing
+
+Tests that state behaviour, fail for one reason, and run the same way on every machine.
+
+## 0. Before you start
+
+1. Find the test stack in the build file: `junit-jupiter` (JUnit 5, or JUnit 6 which needs Java 17+), `junit:junit` (JUnit 4), `assertj-core`, `mockito-core` / `mockito-junit-jupiter`, `org.testcontainers`, `spring-boot-starter-test`. Use what is there; don't add a second assertion or mocking library.
+2. Find how tests run: `./mvnw test` (Surefire, unit), `./mvnw verify` (Failsafe, `*IT` classes), `./gradlew test`. Run one class with `./mvnw test -Dtest=OrderServiceTest` or `./gradlew test --tests 'com.example.OrderServiceTest'`.
+3. Run the suite once and record the result. If it already fails, stop and tell the user which tests fail before you change anything.
+
+## 1. Pick the test level
+
+| What you're testing | Level | Tools |
+|---|---|---|
+| Pure logic, value objects, mappers | unit | JUnit + AssertJ, no mocks |
+| A class with collaborators you own | unit | Mockito for the collaborators at the boundary |
+| SQL, migrations, repository queries | integration | Testcontainers with the real database engine |
+| HTTP layer only (Spring) | slice | `@WebMvcTest` + `MockMvc` |
+| JPA repositories only (Spring) | slice | `@DataJpaTest` + Testcontainers |
+| Whole service wiring | integration | `@SpringBootTest`, used sparingly |
+
+Rules: don't mock what you don't own (wrap the third-party client and mock the wrapper, or use a fake server); don't mock value objects or records; don't test a database with H2 when production runs PostgreSQL or MySQL, because dialect differences hide bugs.
+
+## 2. Write the test
+
+```java
+class PriceCalculatorTest {
+    private final PriceCalculator calc = new PriceCalculator(new FixedTaxRate("0.15"));
+
+    @Test
+    void appliesTaxToSubtotal() {
+        Money total = calc.total(List.of(item("10.00"), item("5.00")));
+        assertThat(total).isEqualTo(Money.of("17.25"));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"0, 0.00", "1, 1.15", "100, 115.00"})
+    void scalesLinearly(int qty, String expected) {
+        assertThat(calc.total(List.of(item("1.00", qty)))).isEqualTo(Money.of(expected));
+    }
+
+    @Test
+    void rejectsEmptyCart() {
+        assertThatThrownBy(() -> calc.total(List.of()))
+            .isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("empty");
+    }
+}
+```
+
+- One behaviour per test; name it for the behaviour (`rejectsEmptyCart`), or use `@DisplayName`.
+- Arrange, act, assert, in that order, with no logic (loops, ifs) in the test.
+- Prefer AssertJ (`assertThat(list).containsExactly(...)`, `extracting`, `satisfies`) over bare `assertTrue`, so failures print the values.
+- Parameterize instead of copy-pasting: `@ValueSource`, `@CsvSource`, `@MethodSource`, `@EnumSource`.
+- Test classes and methods can be package-private in JUnit Jupiter; don't add `public`.
+
+## 3. Mockito
+
+```java
+@ExtendWith(MockitoExtension.class)
+class CheckoutServiceTest {
+    @Mock PaymentGateway gateway;
+    @InjectMocks CheckoutService service;
+
+    @Test
+    void chargesOnceForOrderTotal() {
+        when(gateway.charge(any())).thenReturn(ChargeResult.ok("ref-1"));
+        service.checkout(order("25.50"));
+        verify(gateway).charge(argThat(c -> c.amount().equals(Money.of("25.50"))));
+        verifyNoMoreInteractions(gateway);
+    }
+}
+```
+
+- `MockitoExtension` uses strict stubs: an unused `when(...)` fails the test. Remove the stub rather than switching to lenient.
+- Stub return values for queries; `verify` only commands (calls whose side effect is the point).
+- Use `ArgumentCaptor` when you need to assert several fields of an argument.
+- Mockito 5 uses the inline mock maker by default, so final classes and records can be mocked; mock them only when there is no simpler real instance.
+- On JDK 21+, Mockito's self-attaching agent prints a dynamic agent loading warning; the fix is to pass the `mockito-core` jar as `-javaagent` in the Surefire `argLine` or Gradle `jvmArgs`. Check Mockito's current docs for the exact snippet.
+
+## 4. Integration tests with Testcontainers
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+    @Container
+    static PostgreSQLContainer db = new PostgreSQLContainer("postgres:16-alpine");
+    // connect with db.getJdbcUrl(), db.getUsername(), db.getPassword()
+}
+```
+
+- Testcontainers 2.x renamed module artifacts (`org.testcontainers:testcontainers-postgresql`) and moved classes (`org.testcontainers.postgresql.PostgreSQLContainer`, no type parameter); 1.x uses `org.testcontainers:postgresql` and `org.testcontainers.containers.PostgreSQLContainer<?>`. Match the version in the build file.
+- Pin the image tag to the version production runs; never use `latest`.
+- `static` containers start once per class; instance containers restart per test (slow).
+- In Spring Boot 3.1+, annotate the container field with `@ServiceConnection` instead of wiring `@DynamicPropertySource` by hand.
+- With `@DataJpaTest`, if the test still connects to an embedded database, add `@AutoConfigureTestDatabase(replace = Replace.NONE)`.
+- Run the real migrations (Flyway, Liquibase) against the container so schema and code are tested together.
+- Clean data between tests (truncate tables, or a transaction rolled back per test) so order doesn't matter.
+- If Docker isn't available, stop and tell the user; don't fall back to H2 silently.
+
+## 5. Flaky tests
+
+Reproduce first: rerun the single test many times (a `@RepeatedTest(50)` locally, or a loop over the single-test command), then the whole class, then with the CI's JVM flags and parallelism.
+
+| Symptom | Usual cause | Fix |
+|---|---|---|
+| Fails only with other tests | shared static state, leftover DB rows, test order | reset state in `@BeforeEach`; isolate data |
+| Fails on slow CI | `Thread.sleep` waits, fixed timeouts | poll with Awaitility (`await().atMost(...).until(...)`) |
+| Fails near midnight or in other zones | `LocalDate.now()`, default time zone | inject a `java.time.Clock`; use `Clock.fixed` in tests |
+| Fails on assertion order | `HashMap`/`HashSet` iteration | `containsExactlyInAnyOrder`, or sort |
+| Port already in use | hard-coded ports | random ports; Testcontainers mapped ports |
+
+Never fix flakiness by adding retries, raising timeouts blindly, or `@Disabled`. If you can't find the cause, report what you tried and leave the test enabled.
+
+## 6. Coverage and speed
+
+- If the project uses JaCoCo, run its report goal and look at uncovered branches in the code you changed, not the global number.
+- Keep unit tests free of Spring context and containers. Reuse one Spring context across tests by keeping configuration identical; each distinct `@MockBean`/`@MockitoBean` set forces a new context.
+
+## Never
+
+- Delete, skip or weaken an existing test to make the suite pass without the user's agreement.
+- Assert on log output or `toString()` when a real return value or state is available.
+- Use `Thread.sleep` to wait for asynchronous work.
+- Leave `System.out.println` debugging in tests.
+
+## Finish
+
+Run the test command for the classes you touched, then the full suite. Report the tests added or changed, the command and its result, and any flaky test you could not fix.

package/skills/java-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write JUnit 5 tests with Mockito for the OrderService class",
+    "Replace H2 with Testcontainers PostgreSQL in our Java repository tests",
+    "This JUnit test passes on my laptop but fails randomly in the CI pipeline, help me find out why",
+    "Turn these five copy-pasted Java test methods into a parameterized test with AssertJ assertions",
+    "Mockito says UnnecessaryStubbingException in my CheckoutServiceTest, what's wrong?"
+  ],
+  "should_not_trigger": [
+    "Convert these Java DTO classes to records and use a sealed interface for the payment types",
+    "Gradle build fails: Could not resolve org.junit.jupiter:junit-jupiter after bumping versions",
+    "Write Playwright end-to-end tests for the checkout page",
+    "Add pytest fixtures and parametrize the tests for the billing module",
+    "Write Kotest specs with MockK for the Kotlin payment service"
+  ]
+}