@causyne/agent 0.0.0-stage → 1.10.1

package/native-skills/ai-engineering/structured-output-and-schemas/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: structured-output-and-schemas
+description: Get reliable structured data out of a language model. Use when parsing model output fails, when JSON is malformed, or when output must feed another system.
+---
+
+# Structured Output and Schemas
+
+## The ordering of defences
+
+1. Use the provider's structured output or tool-calling mode. This constrains generation and is a guarantee, not a request.
+2. Where unavailable, ask for a schema and validate.
+3. Repair or retry on failure.
+4. Never regex your way through malformed output — that fails silently on the case you did not anticipate.
+
+## Workflow
+
+1. Define the schema first, in code.
+   - A single definition generates both the prompt's schema description and the runtime validator. Two hand-written copies drift, and the drift shows up as an unparseable response in production.
+   - **Done when:** the schema has one source and both uses derive from it.
+
+2. Keep the schema shallow and named.
+   - Deep nesting and unions raise the failure rate. Descriptive field names do real work — `total_amount_usd` produces better output than `amt`, because the name is part of the instruction.
+   - **Done when:** nesting is shallow and every field name is self-explanatory.
+
+3. Make the uncertain case representable.
+   - If the model may not know a value, the schema needs a null or an explicit unknown. Without one, it will invent a plausible value — the schema forces a shape, not a truth.
+   - **Done when:** every field the model might not know can express that.
+
+4. Validate, then retry with the error.
+   - On a validation failure, send the error back and ask for a correction. This recovers most failures in one extra call. Bound the retries.
+   - **Done when:** a validation failure triggers a bounded repair loop.
+
+5. Validate semantics, not just shape.
+   - A schema check confirms it is a number, not that it is the right number. Range checks, referential checks, and cross-field consistency belong after parsing.
+   - **Done when:** semantic checks run after schema validation.
+
+6. Log every failure with the raw output.
+   - Failure patterns tell you what to fix in the schema or the prompt. Without the raw text there is nothing to learn from.
+   - **Done when:** raw output is retained on every parse failure.
+
+## Verification
+
+- The evaluation set parses successfully every time.
+- A deliberately impossible request produces an explicit unknown, not an invention.
+- A malformed response is repaired within the retry bound or fails cleanly.

package/native-skills/ai-engineering/tool-calling-agents/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: tool-calling-agents
+description: Build an agent that calls tools. Use when adding function calling, when an agent loops without progressing, or when tool results are mishandled.
+---
+
+# Tool-Calling Agents
+
+## The loop
+
+Model proposes a call → the system validates and executes it → the result returns to the model → repeat until done. Every failure in an agent is in one of those four steps, and the validation step is the one most often skipped.
+
+## Workflow
+
+1. Describe tools for the model, not for a developer.
+   - The description is the model's only documentation. Say when to use it AND when not to. A parameter schema with descriptions and examples per field prevents most malformed calls.
+   - **Done when:** each tool says both when to use it and when not to.
+
+2. Validate every call before executing.
+   - The arguments are model output — untrusted. Parse into a schema, check ranges, and check authorization for the CALLER, not for the agent. An agent running with broad privilege on behalf of a limited user is a privilege escalation.
+   - **Done when:** every call is schema-validated and authorized as the user.
+
+3. Return errors as information, not as exceptions.
+   - A failed call should return a message the model can act on: what was wrong and what to try instead. Throwing ends the loop; a good error lets it recover, which is most of the value of the agent.
+   - **Done when:** every failure returns an actionable message.
+
+4. Bound the loop from three directions.
+   - Maximum steps, maximum wall time, and maximum spend. Also detect repetition: the same call with the same arguments twice means the agent is stuck, and no further iteration will help.
+   - **Done when:** all three bounds exist and repetition is detected.
+
+5. Keep the context from growing without limit.
+   - Tool results accumulate quickly. Summarise or drop old results, but never drop the original instruction. Truncate large outputs and offer a way to read more.
+   - **Done when:** a long run stays within the context window without losing the task.
+
+6. Require approval for irreversible actions.
+   - Deleting, sending, paying, deploying. The human sees what will happen before it happens, and dismissing the question means no.
+   - **Done when:** every irreversible tool requires explicit confirmation.
+
+## Verification
+
+- A malformed call is rejected with a message the model can act on.
+- A deliberately looping task terminates on the step or time bound.
+- An irreversible action cannot execute without confirmation.
+- A tool call cannot exceed the calling user's own permissions.

package/native-skills/android/app-performance-profiling/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: app-performance-profiling
+description: Diagnose slowness, jank, or battery drain in an Android app. Use when scrolling stutters, when startup is slow, or when users report heat or battery use.
+---
+
+# Android Performance Profiling
+
+## Measure on the device that hurts
+
+A flagship hides everything. Profile on a mid-tier or low-tier device, on a release build with minification on. A debug build's numbers are not related to what users experience.
+
+## Workflow
+
+1. Name the symptom as a metric.
+   - Startup time, frame duration, memory ceiling, or wakeup count. "Feels slow" cannot be verified as fixed.
+   - **Done when:** there is a number and a baseline measurement.
+
+2. For jank, find the long frames.
+   - The system tracing tool shows what ran during a dropped frame. The usual causes: work on the main thread, an unbounded layout pass, a bitmap decoded during scroll, or an over-broad recomposition.
+   - **Done when:** the dropped frames have a named cause in the trace.
+
+3. For startup, separate the phases.
+   - Process creation, application initialisation, first activity, first frame. Library initialisers running eagerly at startup are the most common cause; move them behind lazy initialisation.
+   - **Done when:** each phase has a duration and the largest is identified.
+
+4. Add a baseline profile.
+   - It ships ahead-of-time compilation hints for the startup and scroll paths, typically a double-digit percentage improvement for a small amount of work.
+   - **Done when:** a baseline profile is generated from a realistic journey and included in the release.
+
+5. For memory, look at retention, not allocation.
+   - The heap dump shows what is held and by what. Bitmaps and cached lists dominate. Allocation churn matters less than a growing retained set.
+   - **Done when:** the retained heap returns to baseline after navigating away.
+
+6. For battery, count wakeups and network calls.
+   - Every wakeup costs a radio transition. Batch network work and use scheduling constraints rather than timers.
+   - **Done when:** wakeups during idle are near zero.
+
+## Verification
+
+- The chosen metric has improved against the recorded baseline, with both numbers stated.
+- Measurement was done on a release build on a mid-tier device.
+- Frame duration stays under the budget through the affected interaction.

package/native-skills/android/background-work-scheduling/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: background-work-scheduling
+description: Schedule work that must survive app death on Android. Use when a task must run later, on a network connection, or periodically, and when a service or timer is being considered.
+---
+
+# Android Background Work
+
+## Choosing the mechanism
+
+- **Coroutine in a ViewModel** — work that only matters while the screen is open. Dies with the screen, correctly.
+- **WorkManager** — deferrable work that must complete even across app death and reboot. The default for anything durable.
+- **Foreground service** — user-visible, user-initiated, ongoing work: playback, navigation, an active upload. Requires a notification and a declared type.
+- **Alarm manager** — exact time triggers only, such as an alarm clock. Restricted, and misused for everything else.
+
+Almost every "run this later" is WorkManager. Background execution limits mean a plain background service will simply be killed.
+
+## Workflow
+
+1. State the durability requirement.
+   - Must it survive the screen closing? The app being killed? A reboot? Each answer moves the choice down the list above.
+   - **Done when:** the mechanism is chosen with the requirement written down.
+
+2. Declare constraints instead of polling.
+   - Network type, charging, storage, idle. The system batches constrained work across apps, which is why it costs far less battery than a timer.
+   - **Done when:** the work declares every condition it needs rather than checking and rescheduling.
+
+3. Make the worker idempotent and re-runnable.
+   - It can be stopped and retried at any point. Partial progress must not corrupt state.
+   - **Done when:** running the worker twice produces one effect.
+
+4. Deduplicate with unique work.
+   - Enqueue unique work with an explicit existing-work policy. Without it, a screen that enqueues on every open schedules the same job repeatedly.
+   - **Done when:** repeated enqueues produce one scheduled job.
+
+5. Return the right result.
+   - Success, retry for a transient failure, failure for a permanent one. Returning failure for a network blip loses the work; returning retry for a validation error retries forever.
+   - **Done when:** each failure branch returns the matching result.
+
+6. Respect the observed limits.
+   - Work is deferred, not immediate. Aggressive battery optimisation on some devices delays it further. Never promise the user a precise time.
+   - **Done when:** the UI does not claim work will happen at a specific moment.
+
+## Verification
+
+- The work completes after force-stopping the app and rebooting.
+- Enqueuing repeatedly results in one job.
+- Battery historian or the WorkManager inspector shows no unexpected wakeups.

package/native-skills/android/compose-state-and-recomposition/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: compose-state-and-recomposition
+description: Write or fix Jetpack Compose UI. Use when a screen stutters, when state resets on rotation, or when a composable recomposes more than expected.
+---
+
+# Compose State and Recomposition
+
+## The model
+
+A composable is a function of state. When state changes, Compose re-runs the functions that READ it. Performance problems are almost always the wrong scope reading the state, and correctness problems are almost always state stored in the wrong place.
+
+## Workflow
+
+1. Hoist state to the lowest common owner.
+   - A composable that owns state cannot be reused or previewed with different values. Take state as a parameter and emit events upward.
+   - **Done when:** every reusable composable is stateless and driven by parameters.
+
+2. Survive configuration change and process death.
+   - `remember` survives recomposition only. `rememberSaveable` survives configuration change. A ViewModel with a saved-state handle survives process death.
+   - Choose by what the user would be upset to lose.
+   - **Done when:** rotating and restoring from background both preserve what the user expects.
+
+3. Read state as late as possible.
+   - Reading a frequently changing value at the top of a screen recomposes the whole screen. Pass a lambda that reads it, and read inside the small composable that displays it — or use the graphics-layer overload for scroll-driven values so it never recomposes at all.
+   - **Done when:** a high-frequency value recomposes only the element that displays it.
+
+4. Give list items stable keys.
+   - `items(list, key = { it.id })`. Without keys, inserting at the front recomposes every item and loses their internal state.
+   - **Done when:** inserting at the head of a list does not disturb the rest.
+
+5. Keep side effects in effect handlers.
+   - A composable body may run many times, in any order, and be abandoned. Anything with a side effect belongs in `LaunchedEffect`, `DisposableEffect`, or `SideEffect`, keyed correctly.
+   - **Done when:** no network call, no logging and no mutation happens in a composable body.
+
+6. Watch out for unstable parameters.
+   - A parameter Compose cannot prove stable forces recomposition every time. Prefer immutable types and persistent collections; mark types stable only when the guarantee is real.
+   - **Done when:** the compiler's stability report shows the hot composables as skippable.
+
+## Verification
+
+- Layout inspector recomposition counts stay flat during interaction that should not change a given element.
+- Rotation preserves state.
+- Scrolling a long list stays smooth on a mid-tier device.

package/native-skills/android/gradle-build-configuration/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gradle-build-configuration
+description: Configure or repair an Android Gradle build. Use when a build fails after a dependency change, when build times are long, or when version numbers are scattered across files.
+---
+
+# Android Gradle Configuration
+
+## Workflow
+
+1. Centralise versions in the version catalog.
+   - `gradle/libs.versions.toml` holds every version, library and plugin. Versions hardcoded across module build files drift, and a mismatch between two artifacts of the same library produces link errors that name neither.
+   - **Done when:** no module build file contains a literal version string.
+
+2. Keep configuration out of the execution path.
+   - Reading a file or running a command at configuration time runs on every build, including `--dry-run`. Wrap it in a provider so it runs only when the task does.
+   - **Done when:** the configuration phase takes under a second on a warm build.
+
+3. Enable the correctness features deliberately.
+   - Configuration cache and build cache both give large wins and both expose incorrectly declared tasks. Turn them on and fix what breaks — what breaks was already wrong.
+   - **Done when:** a second build with no changes reports mostly up-to-date or cached tasks.
+
+4. Separate build types honestly.
+   - Debug: no minification, debuggable, a distinct application id suffix so it installs alongside release.
+   - Release: minification and resource shrinking on, and a signing config that reads from the environment or a properties file that is not committed.
+   - **Done when:** debug and release can be installed on the same device simultaneously.
+
+5. Keep the minification rules with the code they protect.
+   - Consumer rules belong in the library module that needs them, not in the app's file. A library whose rules live in the app breaks for every other consumer.
+   - **Done when:** each module ships the rules its own code requires.
+
+## Common failures
+
+- **Duplicate class:** two dependencies bundling the same library. Resolve with a dependency constraint, never by excluding blindly.
+- **Manifest merger conflict:** read the merged manifest report; add `tools:replace` only after understanding which value should win.
+- **Method count:** enable multidex or, better, shrink what is actually unused.
+
+## Verification
+
+- A clean build succeeds and an incremental build is substantially faster.
+- Release and debug variants both install and run.
+- No version literal exists outside the catalog.

package/native-skills/android/lifecycle-and-leaks/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: lifecycle-and-leaks
+description: Fix an Android memory leak or lifecycle crash. Use when the app crashes after rotation, when a callback fires on a destroyed component, or when memory grows across navigations.
+---
+
+# Android Lifecycle and Leaks
+
+## What leaks
+
+Anything long-lived holding a reference to anything short-lived. An activity is short-lived — it dies on every rotation. A singleton, a static field, a running coroutine, or a registered listener that outlives it keeps the whole view tree in memory.
+
+## The recurring causes
+
+1. A non-static inner class or a lambda capturing the activity, held by something longer-lived.
+2. A listener or receiver registered and never unregistered.
+3. A coroutine launched in a scope that is never cancelled.
+4. A singleton constructed with the activity context instead of the application context.
+5. A handler with a delayed message posted from a destroyed component.
+
+## Workflow
+
+1. Confirm the leak before theorising.
+   - LeakCanary in debug names the retaining chain. The chain is the answer; guessing from the symptom rarely is.
+   - **Done when:** you have the retaining reference chain.
+
+2. Match the scope to the lifetime.
+   - `lifecycleScope` for work tied to the screen, `viewModelScope` for work tied to the ViewModel, and `repeatOnLifecycle(STARTED)` for collecting a flow only while visible. Collecting a flow in `onCreate` without it keeps collecting behind a locked screen.
+   - **Done when:** every coroutine and every collection is bound to a lifecycle.
+
+3. Pair every registration with a removal.
+   - Register in `onStart`, unregister in `onStop`. Or use a `DefaultLifecycleObserver` so the pairing cannot be forgotten.
+   - **Done when:** every registration has a matching removal in the symmetric callback.
+
+4. Pick the right context.
+   - Application context for anything stored beyond a screen. Activity context only for UI: inflating, theming, dialogs.
+   - **Done when:** no long-lived object holds an activity context.
+
+5. Never hold a view reference past the view's life.
+   - In a fragment, null the binding in `onDestroyView`. The fragment outlives its view, and that gap is where the classic fragment leak lives.
+   - **Done when:** the binding is nulled and access after destruction is impossible.
+
+## Verification
+
+- LeakCanary reports no leak after rotating and navigating repeatedly.
+- Memory returns to baseline after navigating away and forcing a collection.
+- No crash after rotating during an in-flight network call.

package/native-skills/android/play-store-release/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: play-store-release
+description: Prepare an Android release for the Play Store. Use when building a release bundle, when a submission is rejected, or when setting up signing.
+---
+
+# Play Store Release
+
+## Workflow
+
+1. Build an app bundle, not an APK.
+   - The store requires it and it produces per-device downloads that are substantially smaller. Test the bundle with the bundle tool so you exercise what users will actually install, not a universal APK.
+   - **Done when:** a device-specific APK generated from the bundle installs and runs.
+
+2. Get signing right and keep it recoverable.
+   - Enrol in Play App Signing so the upload key can be rotated if lost. Losing the signing key without it means the app can never be updated — a new listing is the only path.
+   - The keystore and its passwords never enter version control.
+   - **Done when:** signing config reads credentials from outside the repository and the release build is verified signed.
+
+3. Match the version codes to the release.
+   - Version code strictly increasing, version name meaningful to a human. A duplicate code is rejected at upload.
+   - **Done when:** the code is higher than every previously uploaded build.
+
+4. Test the minified build, not the debug one.
+   - Minification removes code reached only by reflection. Serialisation, dependency injection and any reflective library need keep rules, and the crash appears only in release.
+   - **Done when:** the release build has been exercised through every major flow on a real device.
+
+5. Complete the declarations honestly.
+   - Data safety, permissions, target API level, and the declaration for any sensitive permission. These are the most common rejection causes, and an inaccurate data safety form is a policy violation rather than a formatting error.
+   - **Done when:** every declared item matches what the code actually does.
+
+6. Stage the rollout.
+   - Internal testing, then a small percentage. Watch the crash rate before widening. A full rollout of a broken build reaches everyone before the first report arrives.
+   - **Done when:** the release starts below full rollout with a stated widening criterion.
+
+7. Upload the mapping file.
+   - Without it every release crash report is unreadable.
+   - **Done when:** deobfuscation is confirmed on a test crash.
+
+## Verification
+
+- The bundle uploads and passes pre-launch checks.
+- A minified build passes a full manual pass on a physical device.
+- A test crash appears deobfuscated in the console.

package/native-skills/android/room-and-persistence/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: room-and-persistence
+description: Add or fix local persistence on Android. Use when adding a database, when a schema change crashes on upgrade, or when database work runs on the main thread.
+---
+
+# Room and Persistence
+
+## Invariants
+
+1. Every schema change needs a migration. Destructive fallback in a shipped app deletes the user's data.
+2. No database access on the main thread. Room enforces this by default — that enforcement must not be disabled.
+3. Queries return `Flow` so the UI updates when the data changes, rather than re-querying manually.
+
+## Workflow
+
+1. Commit the schema to version control.
+   - Set the schema export directory. The exported JSON is what makes migrations testable and what tells a reviewer the schema changed.
+   - **Done when:** the schema JSON is committed and updated with every version bump.
+
+2. Write the migration with the version bump, in the same commit.
+   - A version bump without a migration crashes every existing install on first launch. Automated migrations handle simple cases; anything renaming or transforming data needs an explicit one.
+   - **Done when:** every version has a migration path from the previous one.
+
+3. Test the migration against real data.
+   - `MigrationTestHelper` creates the old schema, inserts rows, runs the migration and asserts on the result. An untested migration is a hypothesis.
+   - **Done when:** a test migrates a populated old-version database and asserts the data survived.
+
+4. Index what you filter and sort on.
+   - Room warns about a missing index on a foreign key. A full table scan on a list screen is invisible on a test database and unusable at ten thousand rows.
+   - **Done when:** every column in a WHERE or ORDER BY has an index, or its absence is justified.
+
+5. Keep transactions narrow but complete.
+   - Multi-step writes are annotated as a transaction so a crash cannot leave a half-state. Do not hold a transaction open across a network call.
+   - **Done when:** no multi-step write can be interrupted into an inconsistent state.
+
+## Verification
+
+- Migration tests pass from every previous version.
+- Strict mode reports no disk access on the main thread.
+- A list screen with ten thousand rows scrolls smoothly.

package/native-skills/backend/authentication-and-sessions/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: authentication-and-sessions
+description: Implement login, sessions, or token handling. Use when authentication is being added, when tokens are stored in local storage, or when passwords are being hashed.
+---
+
+# Authentication and Sessions
+
+## Non-negotiables
+
+1. Passwords are hashed with a memory-hard function — argon2id, or bcrypt where argon2 is unavailable. Never a general-purpose hash, salted or not: those are designed to be fast, which is precisely the wrong property.
+2. Tokens live in `HttpOnly`, `Secure`, `SameSite` cookies. A token in local storage is readable by any script on the page, which turns any cross-site scripting bug into full account takeover.
+3. Every authentication decision happens on the server. A client-side check is a display convenience, never a control.
+
+## Workflow
+
+1. Use a library or a provider.
+   - Authentication has many correct-looking implementations that are subtly broken. Prefer an established library or an identity provider over hand-rolling.
+   - **Done when:** the approach is named and its security assumptions are stated.
+
+2. Get session lifetime right.
+   - Short-lived access token, longer-lived refresh token, and rotation on every refresh. Detect reuse of a rotated refresh token and revoke the whole family — that is the signal a token was stolen.
+   - **Done when:** replaying an old refresh token invalidates the session.
+
+3. Make logout actually revoke.
+   - A stateless token cannot be revoked, so either keep server-side session state or maintain a denylist until expiry. Deleting the cookie alone leaves a valid token in the attacker's hands.
+   - **Done when:** a captured token stops working after logout.
+
+4. Rate-limit and lock out.
+   - Per-account and per-address limits on login and on password reset. Without them, credential stuffing runs unimpeded.
+   - **Done when:** repeated failures are throttled and the throttle is tested.
+
+5. Keep the error messages uniform.
+   - "Invalid email or password" for both cases. Distinguishing them enumerates accounts. The same applies to password reset: always report that a mail was sent.
+   - **Done when:** the response and its timing are the same for a known and an unknown account.
+
+6. Regenerate the session identifier on privilege change.
+   - On login and on role elevation. Without this, an identifier planted before login remains valid after it.
+   - **Done when:** the identifier differs before and after login.
+
+## Verification
+
+- Password hashes use a memory-hard function with sensible parameters.
+- The auth cookie has HttpOnly, Secure and SameSite set.
+- A revoked refresh token fails and invalidates its family.
+- Login responses are indistinguishable for unknown and wrong-password accounts.

package/native-skills/backend/background-jobs-and-queues/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: background-jobs-and-queues
+description: Move work out of a request or add a job queue. Use when a request handler does slow work inline, when a job can be lost on restart, or when retries cause duplicate effects.
+---
+
+# Background Jobs and Queues
+
+## The two properties that matter
+
+Delivery is AT-LEAST-ONCE in every real queue, so every job must be idempotent. And a job that fails forever must end up somewhere a human will look, or it will fail silently for months.
+
+## Workflow
+
+1. Move only what is safe to defer.
+   - The user must not need the result to complete their action. If they do, the work belongs in the request, and the fix is to make it faster.
+   - **Done when:** the request returns something meaningful without waiting for the job.
+
+2. Enqueue an identifier, never a payload.
+   - Pass the record id and let the worker read the current state. A serialised payload is stale by the time it is processed, and it bloats the queue.
+   - **Done when:** job arguments are identifiers and primitives only.
+
+3. Make every handler idempotent.
+   - Running twice must equal running once. Key side effects on a stable identifier, or record completion transactionally with the effect.
+   - **Done when:** running the same job twice produces one effect, verified by test.
+
+4. Set retry policy per failure class.
+   - Transient (network, lock timeout): retry with exponential backoff and jitter. Permanent (validation, missing record): fail immediately to the dead-letter queue. Retrying a permanent failure burns capacity forever.
+   - **Done when:** the handler distinguishes the two and behaves differently.
+
+5. Give the dead-letter queue an owner.
+   - Alert on its depth. A dead-letter queue nobody watches is a directory where work goes to be forgotten.
+   - **Done when:** a non-zero depth raises an alert.
+
+6. Enqueue only after the transaction commits.
+   - Enqueuing inside a transaction that later rolls back leaves a job for a record that does not exist. Use a transactional outbox or an after-commit hook.
+   - **Done when:** a rolled-back transaction enqueues nothing.
+
+## Verification
+
+- Running a job twice produces one effect.
+- A permanently failing job reaches the dead-letter queue without retrying indefinitely.
+- Killing a worker mid-job leaves the job re-runnable.

package/native-skills/backend/caching-strategy/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: caching-strategy
+description: Add or fix caching. Use when a cache serves stale data, when a cache miss storm overloads a database, or when caching is being introduced to fix a slow endpoint.
+---
+
+# Caching Strategy
+
+## Before adding a cache
+
+A cache is a correctness risk taken deliberately in exchange for speed. Confirm the slowness is real, measured, and not a missing index — an index fixes the cause; a cache hides it and adds a staleness bug.
+
+## Workflow
+
+1. Decide the invalidation before the caching.
+   - Time-based expiry: simple, and the staleness window must be acceptable to the product, not just to you.
+   - Event-based: invalidate on write. Correct, and every write path must remember. One that forgets is a bug that only appears in production.
+   - **Done when:** the invalidation rule is written down and every write path honours it.
+
+2. Build the key deliberately.
+   - Include everything the value depends on: identifier, version, locale, and the viewer's permissions. A cache key missing the permission dimension serves one user's data to another. This is the most damaging caching bug and it is common.
+   - **Done when:** two users with different permissions cannot share a key.
+
+3. Prevent the stampede.
+   - When a hot key expires, every concurrent request misses and hits the origin at once. Use a lock so one request refills while others serve the stale value, or refresh ahead of expiry.
+   - **Done when:** expiring a hot key under load produces one origin call, not many.
+
+4. Cache negatives too, briefly.
+   - A missing record queried repeatedly bypasses the cache entirely. Cache the absence with a short expiry.
+   - **Done when:** repeated lookups of a nonexistent key do not reach the origin each time.
+
+5. Fail open.
+   - If the cache is unreachable the application serves from the origin, more slowly. A cache outage must not be an application outage.
+   - **Done when:** stopping the cache leaves the application working.
+
+6. Measure the hit rate.
+   - A cache below roughly 80% hit rate is usually keyed wrongly or expiring too fast, and is adding complexity for little gain.
+   - **Done when:** the hit rate is instrumented and reported.
+
+## Verification
+
+- Hit rate is measured and reported.
+- Stopping the cache degrades performance without breaking correctness.
+- A write invalidates every affected key, verified by test.
+- Two users with different permissions receive different data.

package/native-skills/backend/graceful-shutdown/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: graceful-shutdown
+description: Make a service shut down cleanly. Use when a restart drops requests, when jobs are lost on deploy, or when a container takes the full termination grace period to exit.
+---
+
+# Graceful Shutdown
+
+## The sequence
+
+Stop accepting new work → finish work in flight → release resources → exit. A process that exits on the signal drops every live request, and under a rolling deploy that is a burst of user-visible errors on every release.
+
+## Workflow
+
+1. Handle the termination signal, and the interrupt too.
+   - The orchestrator sends the termination signal and then waits a grace period before killing. Handle both signals; a container ignoring the signal always takes the full grace period.
+   - **Done when:** the process exits on signal in well under the grace period.
+
+2. Fail readiness before you stop listening.
+   - Mark the instance unready first, then wait for the load balancer to notice — typically a few seconds — and only then stop accepting connections. Closing the listener immediately means the balancer is still routing to a closed socket.
+   - **Done when:** there is a deliberate delay between failing readiness and closing the listener.
+
+3. Drain in-flight work with a deadline.
+   - Wait for open requests to finish, but not forever. A deadline shorter than the orchestrator's grace period, then force the close.
+   - **Done when:** shutdown completes within the deadline whether or not work finished.
+
+4. Stop background workers cleanly.
+   - Stop pulling new jobs, let the current one finish or return it to the queue. A job abandoned mid-flight must be re-runnable — which is why job handlers are idempotent.
+   - **Done when:** no job is lost or half-applied when a worker stops.
+
+5. Release resources in reverse order of acquisition.
+   - Close the server, then the queue consumers, then the database pool. Closing the pool first fails the requests still draining.
+   - **Done when:** shutdown logs show the reverse order and no error.
+
+6. Never exit non-zero on a clean shutdown.
+   - The orchestrator reads a non-zero exit as a crash and may back off the whole deploy.
+   - **Done when:** a signalled shutdown exits 0.
+
+## Verification
+
+- A rolling restart under load produces zero failed requests.
+- The process exits well inside the grace period.
+- Stopping a worker mid-job leaves the job re-runnable.

package/native-skills/backend/rate-limiting-and-quotas/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: rate-limiting-and-quotas
+description: Add rate limiting or usage quotas to a service. Use when an endpoint can be called without bound, when one client can degrade service for others, or when abuse is suspected.
+---
+
+# Rate Limiting and Quotas
+
+## Workflow
+
+1. Choose the dimension before the algorithm.
+   - Per user for fairness, per address for anonymous abuse, per endpoint for cost control, and globally for capacity protection. Most services need several at once.
+   - **Done when:** each limit names its dimension and the abuse it prevents.
+
+2. Pick the algorithm to match the traffic.
+   - Token bucket: allows bursts up to the bucket size, refills steadily. The right default for user-facing APIs.
+   - Sliding window: smoother, no burst allowance, more storage.
+   - Fixed window: cheapest, but allows double the limit across a boundary.
+   - **Done when:** the choice is stated and the burst behaviour is acceptable.
+
+3. Enforce where the state is shared.
+   - Per-instance counters mean the effective limit is multiplied by the instance count. Use a shared store with an atomic increment.
+   - **Done when:** scaling out does not change the effective limit.
+
+4. Answer with the right status and headers.
+   - 429, with `Retry-After` and the `RateLimit` headers. A limit a client cannot see is a limit they will hit repeatedly.
+   - **Done when:** a limited response tells the client exactly when to retry.
+
+5. Identify the client honestly.
+   - Behind a proxy, the connecting address is the proxy. Read the forwarded header only from a trusted proxy — otherwise a client can spoof it and bypass the limit entirely.
+   - **Done when:** the address is taken from a trusted hop and spoofing is tested.
+
+6. Fail closed at the edge, open in the middle.
+   - If the limiter store is down, an authentication endpoint should reject; an internal read path should allow. State which each one does.
+   - **Done when:** the behaviour when the store is unavailable is decided per endpoint.
+
+## Verification
+
+- Exceeding the limit returns 429 with `Retry-After`.
+- The limit holds when the service runs on several instances.
+- A spoofed forwarded header does not raise the limit.