@causyne/agent 0.0.0-stage → 1.10.1

package/native-skills/mobile/cross-platform-tradeoffs/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: cross-platform-tradeoffs
+description: Decide between native and cross-platform, or work within Flutter or React Native. Use when choosing a mobile stack, or when a cross-platform app hits a platform limit.
+---
+
+# Cross-Platform Trade-offs
+
+## The honest framing
+
+Cross-platform buys shared business logic and one team. It costs latency on new platform features, a harder time with deep platform integration, and a debugging path that crosses a bridge. Neither answer is universally right; the wrong move is choosing without naming the trade.
+
+## Workflow
+
+1. Name the platform-specific surface first.
+   - Widgets, watch apps, background processing, camera and audio pipelines, accessibility services, deep OS integration. If the product depends on several of these, the shared-code saving is smaller than it looks.
+   - **Done when:** the platform-specific requirements are listed before the framework is chosen.
+
+2. Match the choice to the team, not to the benchmark.
+   - A team fluent in one ecosystem will ship better software in it than in a technically superior one they are learning. This usually dominates the technical comparison.
+   - **Done when:** the decision states the team's existing skills as an input.
+
+3. Isolate the platform boundary.
+   - Whatever the choice, platform-specific code lives behind one interface. This keeps the shared code testable and keeps a future migration bounded.
+   - **Done when:** platform APIs are reached through a single abstraction per capability.
+
+4. Follow each platform's conventions in the UI.
+   - Navigation patterns, back behaviour, share sheets and system fonts differ. An app that ignores this is immediately recognisable as a port, and users read that as low quality.
+   - **Done when:** navigation and system interactions match each platform's convention.
+
+5. Test on both, on real devices.
+   - A simulator hides performance, permissions, and hardware differences. Cross-platform bugs concentrate exactly where the two platforms differ.
+   - **Done when:** every release is exercised on a physical device of each platform.
+
+6. Budget for the bridge.
+   - Frequent crossings — per-frame updates, large payloads, high-rate sensors — are the usual performance cliff. Keep hot paths on one side.
+   - **Done when:** no hot path crosses the boundary per frame.
+
+## Verification
+
+- The decision is written down with the platform-specific requirements that informed it.
+- Platform code sits behind one abstraction per capability.
+- Both platforms are tested on physical hardware.

package/native-skills/mobile/deep-linking/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: deep-linking
+description: Implement deep links or universal links. Use when a link should open the app, when links open the browser instead, or when a link cannot restore a screen directly.
+---
+
+# Deep Linking
+
+## Workflow
+
+1. Use verified links, not custom schemes.
+   - A custom scheme can be claimed by any app and does not work from most messaging clients. Verified HTTP links (app links / universal links) are owned by your domain and fall back to the web when the app is absent.
+   - **Done when:** links use https and are verified against the domain.
+
+2. Publish and verify the association file.
+   - The association file must be served over https, with the right content type, no redirect, and the correct fingerprint or team identifier. Verification failing silently is the single most common cause of links opening the browser.
+   - **Done when:** platform verification reports the domain as verified on a real device.
+
+3. Make every screen reachable by URL.
+   - Design the route table as URLs first. A screen that can only be reached by navigating from the home screen cannot be linked, notified into, or restored.
+   - **Done when:** every meaningful screen has a URL.
+
+4. Rebuild the back stack, do not just push.
+   - Opening a detail screen from a link with an empty back stack traps the user. Synthesise the parent chain so back goes somewhere sensible.
+   - **Done when:** pressing back from a linked screen reaches a reasonable parent, not an exit.
+
+5. Handle the pre-ready link.
+   - A link can arrive before authentication or before data is loaded. Store the pending destination, complete the prerequisite, then navigate. Never drop it.
+   - **Done when:** a link that requires login lands on the target after login, not on the home screen.
+
+6. Validate the parameters.
+   - A link is untrusted input. Validate identifiers and reject anything malformed rather than passing it into a query.
+   - **Done when:** a malformed link shows an error rather than crashing.
+
+## Verification
+
+- Links open the app from a message, a browser and a notification, on a real device.
+- Back from a linked screen behaves correctly.
+- A link requiring authentication survives the login flow.
+- A malformed link fails safely.

package/native-skills/mobile/mobile-storage-security/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mobile-storage-security
+description: Store sensitive data on a mobile device. Use when saving tokens, credentials, or personal data locally, or when a security review flags local storage.
+---
+
+# Mobile Storage Security
+
+## The threat
+
+A lost or stolen device, a backup extracted to a computer, and on a rooted or jailbroken device, another process reading your files. Plain preferences and plain files are readable in all three cases.
+
+## Workflow
+
+1. Classify before choosing storage.
+   - Secrets (tokens, keys, passwords) → the platform keystore or keychain.
+   - Personal data → encrypted database or encrypted files.
+   - Cache and preferences → plain storage is fine.
+   - **Done when:** every stored item has a classification.
+
+2. Put secrets in hardware-backed storage.
+   - The platform keystore keeps key material outside the app's address space, and hardware backing means it cannot be extracted even from a rooted device. Require user authentication for the highest-value keys.
+   - **Done when:** no token or key is written to plain preferences or a plain file.
+
+3. Never ship a secret inside the app.
+   - An API key in the binary is extractable in minutes, whatever the obfuscation. If a key must exist, it belongs on a server that proxies the call.
+   - **Done when:** no long-lived credential exists in the shipped artefact.
+
+4. Control what leaves the device in a backup.
+   - Exclude secrets and caches from automatic cloud backup explicitly. A backup restored to another device must not carry a session token.
+   - **Done when:** the backup rules name what is excluded, and a restore does not carry a live session.
+
+5. Protect data at rest as well as in transit.
+   - Encrypted database for personal data, so a file pulled from a backup is not readable.
+   - **Done when:** the database file alone is not readable without the device key.
+
+6. Clear on logout.
+   - Tokens, cached personal data and derived keys. Leaving them behind means the next user of the device inherits the session.
+   - **Done when:** after logout, no personal data or credential remains on disk.
+
+## Verification
+
+- Pulling the app's data directory yields no readable secret.
+- The shipped artefact contains no long-lived credential.
+- Logout leaves no personal data on disk.
+- A restored backup does not carry a live session.

package/native-skills/mobile/offline-first-sync/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: offline-first-sync
+description: Make a mobile app work without a network connection. Use when the app shows an error offline, when data is lost on a failed request, or when local and server state diverge.
+---
+
+# Offline-First Sync
+
+## The premise
+
+The local store is the source of truth for the UI. The network is a background synchroniser. Every screen reads local data and renders immediately; nothing waits on a request. Getting this backwards is why most apps are unusable on a train.
+
+## Workflow
+
+1. Write locally first, always.
+   - A user action commits to the local database and the UI updates from it. A sync record is queued separately. The user never waits for a round trip to see their own action.
+   - **Done when:** every mutation succeeds and is visible with the network disabled.
+
+2. Queue mutations durably.
+   - The outbox survives app death and reboot. Each entry has a stable identifier so a retry cannot duplicate the server-side effect.
+   - **Done when:** killing the app mid-sync loses nothing and duplicates nothing.
+
+3. Decide the conflict rule per field, not per record.
+   - Last-write-wins is acceptable for a note body and wrong for a counter or a set. State the rule for each field that can be edited on two devices.
+   - **Done when:** every conflict-capable field has a stated resolution rule.
+
+4. Sync incrementally.
+   - Track a server cursor or updated-at watermark and request only what changed. A full re-fetch on every launch is slow, expensive and pointless.
+   - **Done when:** a sync after a small change transfers a small amount of data.
+
+5. Show sync state without blocking.
+   - A subtle indicator for pending and failed items. A modal spinner over the whole screen defeats the entire design.
+   - **Done when:** pending and failed states are visible and non-blocking.
+
+6. Make failure recoverable by the user.
+   - An item that fails permanently needs a visible retry or discard. Silent permanent failure loses user data without telling them.
+   - **Done when:** a permanently failed mutation is surfaced with an action.
+
+## Verification
+
+- Every screen renders and every action succeeds in airplane mode.
+- Reconnecting syncs the queue exactly once.
+- Editing the same record on two devices resolves by the stated rule.

package/native-skills/mobile/push-notifications/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: push-notifications
+description: Implement push notifications. Use when adding push, when notifications do not arrive on some devices, or when permission is requested at launch.
+---
+
+# Push Notifications
+
+## Workflow
+
+1. Ask for permission in context, never at launch.
+   - A permission prompt on first open is denied by most users, and on both platforms a denial is close to permanent. Ask at the moment the value is obvious, after explaining it in your own UI first.
+   - **Done when:** the system prompt appears only after an in-app explanation and a user action.
+
+2. Treat the token as volatile.
+   - It rotates on reinstall, restore, and sometimes on update. Refresh on every launch and on the rotation callback, and send it to the server with a device identifier so old tokens can be replaced rather than accumulated.
+   - **Done when:** reinstalling produces a working token without a duplicate device record.
+
+3. Send data, render locally.
+   - A notification payload containing final display text cannot be localised, personalised, or deduplicated. Send identifiers and render from local data where the platform allows.
+   - **Done when:** the notification respects the device language and the app's current state.
+
+4. Handle all three app states.
+   - Foreground, background, and terminated behave differently on both platforms. The terminated case is the one that is usually missed, and it is the one that matters for a cold launch from a notification.
+   - **Done when:** tapping a notification opens the right screen from all three states.
+
+5. Route the tap deterministically.
+   - The payload carries a deep link. Handle a link that arrives before the app is ready by queueing it until navigation exists.
+   - **Done when:** a cold-start notification tap lands on the correct screen.
+
+6. Respect the user's attention.
+   - Channels or categories so the user can mute a class rather than all notifications. Collapse keys so ten updates do not become ten notifications. Never send a notification with no user value.
+   - **Done when:** every notification type is in a channel the user can control separately.
+
+## Verification
+
+- Delivery works in foreground, background and terminated states on physical devices.
+- Reinstalling refreshes the token and does not duplicate the device.
+- Muting one channel leaves the others working.

package/native-skills/performance/algorithmic-complexity/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: algorithmic-complexity
+description: Fix code that slows down disproportionately as data grows. Use when performance is fine in testing and bad in production, or when a loop contains a lookup.
+---
+
+# Algorithmic Complexity
+
+## Where the real wins are
+
+Constant-factor optimisation buys a few percent. Removing a factor of n buys orders of magnitude. On real data, the difference between a nested loop and a hash lookup dwarfs every micro-optimisation combined — and the nested loop is invisible on a test fixture of ten items.
+
+## Workflow
+
+1. Find the nested iteration.
+   - A loop containing a search, a filter, an `includes`, or a query. This is the single most common cause of "fine in dev, unusable in production".
+   - Fix: build a map or set once, then look up in constant time.
+   - **Done when:** no loop body performs a linear search over another collection.
+
+2. Look for repeated work that could be done once.
+   - A value recomputed on every iteration, a regular expression compiled inside a loop, a sort inside a loop. Hoist it.
+   - **Done when:** nothing invariant is computed inside a loop.
+
+3. Choose the structure for the dominant operation.
+   - Frequent membership tests: a set. Frequent lookup by key: a map. Ordered range queries: a sorted structure or an index. Using an array for membership testing is the same mistake as the nested loop.
+   - **Done when:** the data structure matches the most frequent operation.
+
+4. Push filtering to where the data lives.
+   - Fetching ten thousand rows to keep five is ten thousand rows of transfer, allocation and parsing. Filter in the query.
+   - **Done when:** the volume fetched is proportional to the volume used.
+
+5. Do not process what you will not show.
+   - Paginate, limit, and stream. A list endpoint with no limit is unbounded work triggered by a stranger.
+   - **Done when:** every collection operation has a bound.
+
+6. Verify the complexity empirically.
+   - Time with n, 10n and 100n. Linear growth is fine; quadratic shows up immediately at 100n.
+   - **Done when:** timing scales as the intended complexity predicts.
+
+## Verification
+
+- Timing at three input sizes matches the intended complexity.
+- No loop body contains a linear search.
+- Every collection endpoint is bounded.

package/native-skills/performance/concurrency-and-parallelism/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: concurrency-and-parallelism
+description: Make code faster by running work concurrently, or fix a concurrency bug. Use when work is serialised unnecessarily, or when parallel code produces wrong results.
+---
+
+# Concurrency and Parallelism
+
+## The distinction that decides the mechanism
+
+Concurrency is dealing with many things at once; parallelism is doing many things at once. I/O-bound work needs concurrency — async or threads. CPU-bound work needs parallelism — processes or real threads. Applying the wrong one gives no speedup and sometimes a slowdown.
+
+## Workflow
+
+1. Classify the bottleneck before choosing a tool.
+   - Watch CPU during the slow operation. Near 100% on one core is CPU-bound. Low CPU with the process waiting is I/O-bound.
+   - **Done when:** the bottleneck is classified with a measurement.
+
+2. Find the actual serialisation point.
+   - Parallelising around a shared lock, a single database connection, or a rate-limited API gives no improvement — the queue just moves. Find what everything waits on.
+   - **Done when:** the shared resource is identified and shown not to be the limit.
+
+3. Bound the concurrency.
+   - Unbounded parallelism exhausts connections, file descriptors, or memory, and usually performs worse than a sensible limit. Use a semaphore or a worker pool sized from measurement.
+   - **Done when:** peak concurrency is capped at a measured number.
+
+4. Eliminate shared mutable state, do not lock it.
+   - Give each worker its own data and combine at the end. Locks are correct and slow, and every lock is a potential deadlock. Immutability and message passing avoid the whole class.
+   - **Done when:** workers share nothing mutable, or every shared item's protection is documented.
+
+5. Order lock acquisition consistently.
+   - Deadlock is two paths taking the same locks in different orders. A global order — by identifier — removes it structurally.
+   - **Done when:** every multi-lock path acquires in the same order.
+
+6. Test under real contention.
+   - A race that never appears with two workers appears with two hundred. Run the concurrency test with many workers, repeatedly, and with a race detector where the language has one.
+   - **Done when:** a high-contention test passes repeatedly.
+
+## Verification
+
+- Speedup is measured, not assumed, and is close to what the bottleneck class predicts.
+- A high-contention test produces the correct result over many runs.
+- No shared mutable state is accessed without documented protection.

package/native-skills/performance/load-testing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: load-testing
+description: Find out how a system behaves under load. Use before a launch, before a traffic event, or after a capacity-related incident.
+---
+
+# Load Testing
+
+## What you are looking for
+
+Not the maximum throughput. The point at which latency degrades, and what happens beyond it. A system that quietly falls over at 2× normal traffic is the problem; the exact breaking number is secondary.
+
+## Workflow
+
+1. Define the scenario from real traffic.
+   - Endpoint mix, think time, payload sizes and the cache-hit ratio, taken from production logs. A test hammering one endpoint with no think time measures something no user will ever do.
+   - **Done when:** the scenario's mix is derived from observed traffic.
+
+2. Test against production-like infrastructure and data.
+   - Same instance sizes, same database size, same cache state. A test against an empty database measures the empty database.
+   - **Done when:** the environment's differences from production are listed and their effect stated.
+
+3. Ramp rather than spike.
+   - Increase load gradually and watch where latency turns upward. That knee is the useful number. A spike test is a separate scenario for autoscaling behaviour.
+   - **Done when:** the latency knee is identified.
+
+4. Watch the system, not just the client.
+   - CPU, memory, connection pool saturation, database load, queue depth, and error rate. The client only sees the symptom; the cause is inside.
+   - **Done when:** the first resource to saturate is named.
+
+5. Push past the knee deliberately.
+   - Graceful degradation — shedding load, returning 429, serving stale — is a design property, not an accident. Confirm the system does something sensible rather than collapsing.
+   - **Done when:** behaviour beyond capacity is characterised and acceptable.
+
+6. Soak at a sustainable level.
+   - Several hours at a realistic load finds leaks, connection exhaustion, and log-disk growth — none of which appear in a ten-minute run.
+   - **Done when:** a multi-hour run shows flat memory and stable latency.
+
+## Verification
+
+- The latency knee and the first saturating resource are both reported.
+- Behaviour beyond capacity is documented.
+- A soak run shows no resource growth over time.

package/native-skills/performance/memory-and-leak-hunting/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: memory-and-leak-hunting
+description: Diagnose growing memory or an out-of-memory failure. Use when a process grows over time, when it is killed by the platform, or when garbage collection pauses become long.
+---
+
+# Memory and Leak Hunting
+
+## Growth versus leak
+
+A leak is unbounded retention: memory that is reachable but never used again. High usage that plateaus is not a leak — it is a cache or a pool doing its job. Distinguish these before investigating, because they need opposite responses.
+
+## Workflow
+
+1. Establish the shape of the growth.
+   - Plot resident memory over hours. Linear with traffic suggests per-request retention. Stepwise suggests a cache without a bound. A plateau is not a leak.
+   - **Done when:** the growth pattern is characterised.
+
+2. Take two heap snapshots and compare.
+   - One after warm-up, one after a period of load, having returned to the same logical state. The DIFFERENCE is the leak; a single snapshot mostly shows normal working set.
+   - **Done when:** you have the object types that grew between snapshots.
+
+3. Follow the retaining path.
+   - The profiler shows what holds the object. The answer is almost always one of: a module-level collection that only grows, a listener never removed, a closure capturing a large scope, a cache with no eviction, or a timer holding its context.
+   - **Done when:** the retaining reference is named.
+
+4. Bound every cache.
+   - A map used as a cache with no maximum size and no eviction is the most common leak in any language. Give it a bound and a policy.
+   - **Done when:** every long-lived collection has a maximum size.
+
+5. Pair every registration with a removal.
+   - Listeners, subscriptions, intervals, and observers. Where the language supports it, use a scope guard so the pairing cannot be forgotten.
+   - **Done when:** every registration has a guaranteed removal.
+
+6. Re-measure over the same window.
+   - **Done when:** memory returns to baseline after load, over the duration that previously showed growth.
+
+## Verification
+
+- Memory plateaus rather than growing over a long soak test.
+- The retained set returns to baseline after load stops.
+- Every cache has a stated bound.

package/native-skills/performance/network-and-payload-efficiency/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: network-and-payload-efficiency
+description: Reduce time spent on the network. Use when an app is slow on a mobile connection, when payloads are large, or when a screen makes many requests.
+---
+
+# Network and Payload Efficiency
+
+## What dominates on a real connection
+
+Round trips, not bandwidth. On a mobile network each round trip costs tens to hundreds of milliseconds regardless of payload size. Eliminating a request is worth far more than shrinking one.
+
+## Workflow
+
+1. Count the requests on the critical path.
+   - Waterfall view. Look for sequential chains — a request whose response is needed to start the next. Each link is a full round trip.
+   - **Done when:** the length of the longest sequential chain is known.
+
+2. Break the chains.
+   - Return what the screen needs in one response, or issue independent requests in parallel. A screen that fetches a user, then their orders, then each order's items is three round trips deep before anything renders.
+   - **Done when:** no chain on the critical path is longer than two.
+
+3. Send only what is used.
+   - A response with forty fields where the screen shows four wastes serialisation, transfer and parsing. Support field selection, or provide a purpose-built endpoint.
+   - **Done when:** responses contain no field the client ignores.
+
+4. Compress and cache correctly.
+   - Compression on for text responses. `Cache-Control` with a real max-age for anything stable, and `ETag` for anything revalidatable. A correct 304 costs one round trip and no body.
+   - **Done when:** repeat loads are served from cache or revalidated without a body.
+
+5. Paginate and stream large results.
+   - Cursor pagination for lists, streaming for large payloads so the client can begin before the end arrives.
+   - **Done when:** no endpoint returns an unbounded body.
+
+6. Move the data closer.
+   - A CDN for static assets and cacheable responses. Geography is a fixed cost that no amount of optimisation removes.
+   - **Done when:** static assets are served from an edge location.
+
+## Verification
+
+- Requests on the critical path are counted before and after.
+- Repeat loads produce 304 responses or cache hits.
+- The app is tested on a throttled connection with added latency, not on the local network.

package/native-skills/performance/profiling-methodology/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: profiling-methodology
+description: Investigate a performance problem. Use whenever something is slow, before optimising anything, and when an optimisation did not help.
+---
+
+# Profiling Methodology
+
+## The rule that saves the most time
+
+Measure first. Developer intuition about where time goes is wrong most of the time, and an optimisation applied to the wrong place costs the effort plus the added complexity plus the bug it introduces, for no gain.
+
+## Workflow
+
+1. State the goal as a number.
+   - "p95 under 200ms", not "faster". Without a target there is no way to know when to stop, and optimisation has no natural end.
+   - **Done when:** the target and the current value are both written down.
+
+2. Measure the right layer.
+   - A slow page can be the network, the server, the database, or the client. Establish which before profiling inside one of them. The waterfall or a distributed trace answers this in a minute.
+   - **Done when:** the dominant layer is identified.
+
+3. Profile under realistic conditions.
+   - Production-scale data, realistic concurrency, a release build, and a representative device or instance. A profile on ten rows on a workstation finds nothing that matters.
+   - **Done when:** the profile was taken under conditions resembling production.
+
+4. Read the profile for self time and for the call tree.
+   - Self time finds a slow function. The tree finds a fast function called a million times, which is the more common and more valuable finding.
+   - **Done when:** you can name the specific call path consuming the time.
+
+5. Change one thing and re-measure.
+   - Several changes at once make attribution impossible, and one of them may have made things worse.
+   - **Done when:** each change has a before and after number.
+
+6. Stop at the target.
+   - Beyond it, further optimisation buys complexity nobody asked for.
+   - **Done when:** the target is met and the work has stopped.
+
+## The usual suspects, in order
+
+Repeated work in a loop, an N+1 query, a missing index, unnecessary serialisation, a synchronous call in an async path, and an unbounded collection.
+
+## Verification
+
+- Before and after numbers are reported for the stated metric.
+- The measurement conditions are described.
+- The change is attributable to one modification.

package/native-skills/python/async-correctness/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: async-correctness
+description: Write or debug asyncio code. Use when async code runs slower than sync, when a coroutine is never awaited, or when the event loop appears to block.
+---
+
+# Asyncio Correctness
+
+## The failure that causes most of the others
+
+A blocking call inside a coroutine stops the ENTIRE event loop, not just that task. `time.sleep`, `requests.get`, a synchronous file read, or a CPU-heavy loop will serialise everything the program is doing. Async code that is slower than sync code almost always has one of these.
+
+## Workflow
+
+1. Find the blocking calls.
+   - Any synchronous I/O library, any `time.sleep`, any long pure-Python computation.
+   - Fix: use the async equivalent (`httpx` over `requests`, `aiofiles` or a thread for files), or push the work off the loop with `asyncio.to_thread` for I/O and a process pool for CPU.
+   - **Done when:** no coroutine performs synchronous I/O or long computation.
+
+2. Make concurrency explicit.
+   - `await` in sequence is sequential. To run concurrently, use `asyncio.TaskGroup` (3.11+), which also propagates exceptions and cancels siblings correctly.
+   - `asyncio.gather` without `return_exceptions` leaves siblings running after one fails.
+   - **Done when:** work intended to be concurrent uses a TaskGroup and finishes in roughly the time of the slowest item.
+
+3. Never create a task without keeping a reference.
+   - The loop holds only a weak reference; a bare `asyncio.create_task(...)` can be garbage-collected mid-flight and the work silently vanishes. Hold the task, or use a TaskGroup.
+   - **Done when:** every created task is owned by something.
+
+4. Handle cancellation as a normal path.
+   - `CancelledError` must propagate. Catching it broadly makes a task uncancellable and hangs shutdown. Cleanup belongs in `finally`, and must not await anything slow.
+   - **Done when:** cancelling the top-level task exits promptly.
+
+5. Bound the concurrency.
+   - Ten thousand simultaneous requests will exhaust file descriptors or get the client blocked. Use a `Semaphore`.
+   - **Done when:** peak concurrency is capped at a stated number.
+
+## Verification
+
+- Run with `PYTHONASYNCIODEBUG=1`; there are no "coroutine was never awaited" or slow-callback warnings.
+- Concurrent work completes in about the time of the slowest item, not the sum.
+- Interrupting the program exits cleanly rather than hanging.

package/native-skills/python/cli-tool-construction/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: cli-tool-construction
+description: Build a Python command-line tool. Use when a script parses sys.argv by hand, when it has no help output, or when it cannot be used in a pipeline.
+---
+
+# Python CLI Construction
+
+## What separates a tool from a script
+
+Discoverable help, correct exit codes, stdout carrying only the result, and behaviour that composes with other tools. A script that prints progress to stdout cannot be piped, and that is usually the first thing a user tries.
+
+## Workflow
+
+1. Use a parser, not manual argument handling.
+   - `argparse` is in the standard library and sufficient. `typer` or `click` add ergonomics at the cost of a dependency.
+   - Every option gets a help string. `--help` is the tool's primary documentation.
+   - **Done when:** `--help` alone explains how to use the tool.
+
+2. Separate the streams.
+   - Results to stdout. Progress, warnings and errors to stderr. Mixing them makes the tool unpipeable and its output unparseable.
+   - **Done when:** `tool ... > out.txt` leaves a file containing only results, with progress still visible on the terminal.
+
+3. Exit with meaning.
+   - 0 for success, non-zero for failure. A tool that exits 0 after failing breaks every script that calls it.
+   - **Done when:** a deliberate failure produces a non-zero exit code.
+
+4. Read from stdin when no file is given.
+   - `-` conventionally means stdin. This makes the tool a filter and lets it compose.
+   - **Done when:** `cat file | tool` behaves as `tool file`.
+
+5. Keep the logic out of the entry point.
+   - `main()` parses arguments and calls a function that takes plain values. That function is testable without spawning a process.
+   - **Done when:** the core behaviour has tests that do not invoke the CLI.
+
+6. Handle interruption quietly.
+   - Catch the keyboard interrupt at the top level and exit 130 without a traceback. A stack trace on Ctrl+C looks like a crash.
+   - **Done when:** interrupting prints nothing alarming and exits 130.
+
+## Verification
+
+- `--help` documents every option.
+- Redirecting stdout captures only results.
+- A failure path exits non-zero.
+- The core logic has tests that bypass argument parsing.

package/native-skills/python/data-processing-pipelines/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: data-processing-pipelines
+description: Process files or datasets in Python. Use when a script loads an entire file into memory, when processing is slow, or when a pipeline fails partway through with no recovery.
+---
+
+# Data Processing Pipelines
+
+## The two failures
+
+Loading everything into memory, and having no way to resume. Both are invisible on the sample file and fatal on the real one.
+
+## Workflow
+
+1. Stream rather than load.
+   - Iterate the file; do not read it whole. `csv.reader` over a file object, `json` lines one per line, `pandas.read_csv(chunksize=...)`, or Polars in lazy mode.
+   - **Done when:** peak memory is roughly constant regardless of input size.
+
+2. Make the pipeline a chain of generators.
+   - Each stage takes an iterable and yields an iterable. Nothing materialises a list. This composes, stays constant-memory, and is testable stage by stage.
+   - **Done when:** no stage builds a list of the whole dataset.
+
+3. Validate at the boundary and quarantine the failures.
+   - Bad rows are normal in real data. Validate on entry, write rejects to a separate file with the reason, and continue. A pipeline that stops on row 400,000 wastes the previous 399,999.
+   - **Done when:** a deliberately malformed row lands in the reject file and processing continues.
+
+4. Make the whole thing resumable and idempotent.
+   - Checkpoint progress, and key output by a stable identifier so re-running overwrites rather than duplicates. Write to a temporary path and rename on completion so a partial file is never mistaken for a finished one.
+   - **Done when:** interrupting mid-run and restarting produces the same result as an uninterrupted run.
+
+5. Parallelise only after measuring.
+   - Find out whether the bottleneck is I/O or CPU. Threads help I/O; processes help CPU; neither helps if the bottleneck is a single slow query upstream.
+   - **Done when:** the bottleneck is named and the chosen mechanism matches it.
+
+## Verification
+
+- Peak memory stays flat as input size grows tenfold.
+- A malformed row is quarantined, not fatal.
+- Killing the process mid-run and restarting yields the same output.

package/native-skills/python/environment-isolation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: environment-isolation
+description: Install Python dependencies or run a Python script. Use before any pip install, when no virtual environment is active, or when a project has no dependency manifest.
+---
+
+# Python Environment Isolation
+
+## The rule that has no exceptions
+
+Never install into the system interpreter. On macOS and most Linux distributions the system Python is a dependency of the operating system, and a global install can break packaging tools, the desktop, or the boot path. Modern pip refuses by default (PEP 668) — that refusal is correct and must not be defeated with `--break-system-packages`.
+
+## Workflow
+
+1. Detect what is already there before creating anything.
+   - Active environment: the `VIRTUAL_ENV` variable is set.
+   - Project-local: a `.venv/` or `venv/` directory.
+   - Managed: `poetry.lock`, `uv.lock`, `Pipfile.lock`, or `environment.yml` — each implies its own tool and its own commands.
+   - **Done when:** you know which manager the project uses, or that it has none.
+
+2. Use the project's manager if it has one.
+   - `uv sync`, `poetry install`, `pipenv install`, `conda env create -f environment.yml`. Mixing plain pip into a managed project desynchronises the lock file.
+   - **Done when:** dependencies are installed through the project's own tool.
+
+3. Create an environment if none exists.
+   - `python3 -m venv .venv` then activate. `uv venv` is faster where uv is available.
+   - Add `.venv/` to `.gitignore`.
+   - **Done when:** `VIRTUAL_ENV` is set and points into the project.
+
+4. Chain activation into every command you run.
+   - A tool invocation is a fresh shell, so activation does not persist between them. Every command must carry it: `source .venv/bin/activate && pytest`. On Windows: `.venv\Scripts\activate`.
+   - **Done when:** every command that touches Python includes activation.
+
+5. Record what you installed.
+   - Add the dependency to `pyproject.toml` or `requirements.txt`. An install that is not recorded disappears on the next clean checkout.
+   - **Done when:** a fresh clone plus an install reproduces the environment.
+
+## Verification
+
+- `which python` resolves inside the project directory.
+- `python -c "import sys; print(sys.prefix)"` prints the environment path, not the system path.
+- The new dependency appears in the manifest.