@causyne/agent 0.0.0-stage → 1.10.1

package/native-skills/database/data-integrity-and-constraints/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: data-integrity-and-constraints
+description: Enforce correctness rules in a database. Use when invalid data has been found in production, when rules live only in application code, or when several services write the same table.
+---
+
+# Data Integrity and Constraints
+
+## Where the rules belong
+
+In the database. Application-level validation is a user-experience feature; it is bypassed by every migration, every background job, every admin script, and every other service that writes the table. If a rule matters, the database enforces it.
+
+## Workflow
+
+1. Find what is already invalid.
+   - Write the constraint as a SELECT first and count the violations. There are almost always some, and adding the constraint blind will fail the migration.
+   - **Done when:** the current violation count is known for each intended constraint.
+
+2. Clean the existing data before constraining.
+   - Decide per violation class: fix, delete, or quarantine. Record the decision — this is a data change, not a schema change.
+   - **Done when:** the violation count is zero.
+
+3. Add the constraint at the right level.
+   - NOT NULL for required. UNIQUE for identity. FOREIGN KEY for references, with an explicit ON DELETE rule — the default is usually not what you want. CHECK for value rules. EXCLUDE for non-overlap, such as bookings.
+   - **Done when:** every rule has a constraint of the appropriate kind.
+
+4. Choose referential actions deliberately.
+   - CASCADE deletes children silently — powerful and dangerous. RESTRICT is the safe default. SET NULL requires the column to be nullable and the meaning of null to be defined.
+   - **Done when:** every foreign key states its action and the reason.
+
+5. Add constraints without locking.
+   - NOT VALID first, then VALIDATE separately. This avoids a full table scan under an exclusive lock.
+   - **Done when:** the constraint is added and validated without a long lock.
+
+6. Test that the constraint actually fires.
+   - Write a test that attempts the invalid write and asserts the failure. An untested constraint may be disabled or wrong.
+   - **Done when:** a test proves invalid data is rejected.
+
+## Verification
+
+- Every stated business rule maps to a database constraint.
+- A test attempts each invalid write and confirms rejection.
+- The constraints were added without a long lock on a production-scale copy.

package/native-skills/database/query-optimisation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: query-optimisation
+description: Make a slow database query fast. Use when an endpoint is slow, when a query times out, or when the database shows high CPU.
+---
+
+# Query Optimisation
+
+## Workflow
+
+1. Read the actual plan, not the estimated one.
+   - `EXPLAIN ANALYZE` runs the query and reports what really happened. The estimate can be wildly wrong, and the difference between estimate and actual is itself the most useful diagnostic — it means the statistics are stale.
+   - **Done when:** you have a real plan with actual row counts and timings.
+
+2. Find the expensive node.
+   - Look for a sequential scan on a large table, a nested loop over many rows, or a sort that spills to disk. One node usually dominates.
+   - **Done when:** you can name the node consuming most of the time.
+
+3. Index what is filtered, joined and ordered.
+   - A composite index's column order matters: equality columns first, then the range or sort column. An index the planner will not use is usually in the wrong order, or the column is wrapped in a function.
+   - **Done when:** the plan shows an index scan and the timing has dropped.
+
+4. Fix the N+1 before optimising the one.
+   - One query in a loop over a hundred rows is a hundred round trips. This is far more common than a genuinely slow query, and no index fixes it. Batch or join instead.
+   - **Done when:** the request issues a bounded number of queries regardless of result size.
+
+5. Select only what you use.
+   - `SELECT *` prevents index-only scans and drags large columns across the wire. Name the columns.
+   - **Done when:** no query in the hot path selects columns the caller ignores.
+
+6. Confirm the statistics are current.
+   - A plan that is wrong by orders of magnitude usually means stale statistics after a bulk load. Analyse the table and re-check before adding an index that was never needed.
+   - **Done when:** estimated and actual row counts are within an order of magnitude.
+
+## Verification
+
+- Report the before and after timing from `EXPLAIN ANALYZE`.
+- The plan shows the intended access path.
+- The request issues a bounded number of queries.

package/native-skills/database/safe-migrations/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: safe-migrations
+description: Change a production database schema. Use before any ALTER on a live table, when a migration might lock, or when a deploy includes a schema change.
+---
+
+# Safe Migrations
+
+## The two rules
+
+1. Every migration must be safe while the OLD code is still running, because during a deploy it is.
+2. Nothing may hold a long lock on a table that is serving traffic.
+
+## The operations that lock, and their safe form
+
+- **Add a column with a default** — safe on modern PostgreSQL; on older versions it rewrites the table. Add nullable, backfill in batches, then set the default.
+- **Add NOT NULL** — add a CHECK constraint as NOT VALID, validate it separately, then convert. The direct form scans the whole table under an exclusive lock.
+- **Add an index** — always CONCURRENTLY. The plain form blocks writes for the duration.
+- **Rename a column** — never in one step. Add the new one, write to both, migrate readers, then drop.
+- **Change a type** — usually a rewrite. Add a new column, backfill, switch, drop.
+- **Add a foreign key** — add NOT VALID, then validate separately.
+
+## Workflow
+
+1. Classify the migration as additive or destructive.
+   - **Done when:** every statement is labelled, and no destructive statement ships alongside the code that stops using it.
+
+2. Set a lock timeout before the statement.
+   - `SET lock_timeout = '3s'`. Without it, a migration waiting on a lock queues every subsequent query behind it and takes the site down — the lock queue, not the migration, is what causes the outage.
+   - **Done when:** every migration sets a lock timeout and fails fast rather than queueing.
+
+3. Backfill in batches, outside the migration.
+   - A single UPDATE over millions of rows holds a long transaction and bloats the table. Batch with a delay, as a job.
+   - **Done when:** no migration updates an unbounded number of rows in one statement.
+
+4. Test on a copy with production-scale data.
+   - A migration that takes 3ms on a hundred rows can take twenty minutes on fifty million. Only a realistic copy tells you which.
+   - **Done when:** the migration has been timed against production-scale data.
+
+5. Write the reversal.
+   - Additive migrations reverse cleanly. Destructive ones cannot — which is why they ship last, separately, after the new path is proven.
+   - **Done when:** every migration has a tested down path, or is explicitly marked irreversible and shipped alone.
+
+## Verification
+
+- Timed against a production-scale copy.
+- Applied against a running old-code instance with no errors.
+- Lock timeout set; the migration fails rather than queueing.

package/native-skills/database/schema-design/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: schema-design
+description: Design a database schema or add tables. Use when modelling new data, when a table has grown many nullable columns, or when queries need many joins to answer a simple question.
+---
+
+# Schema Design
+
+## Workflow
+
+1. Normalise first, denormalise on evidence.
+   - Third normal form is the default. Denormalise only after a measured query problem, and write down which query justified it — otherwise the duplication outlives its reason and starts drifting.
+   - **Done when:** every denormalised column names the query it exists for.
+
+2. Choose keys deliberately.
+   - A surrogate key (integer or UUIDv7) for identity, a unique constraint on the natural key for correctness. UUIDv4 as a clustered primary key destroys insert locality; UUIDv7 is time-ordered and does not.
+   - **Done when:** every table has a primary key and a unique constraint on any natural identifier.
+
+3. Let the database enforce the invariants.
+   - NOT NULL, foreign keys, CHECK constraints, and unique indexes. An invariant enforced only in application code will be violated by a migration, a background job, or the second service that writes the table.
+   - **Done when:** every stated invariant has a constraint, not just a validation.
+
+4. Pick types precisely.
+   - Timestamps with time zone, never a naive local time. Decimal for money, never floating point. An enumerated type or a CHECK for a fixed set, not free text.
+   - **Done when:** no money column is floating point and no timestamp is zone-naive.
+
+5. Treat many nullable columns as a modelling smell.
+   - A table where different rows use different subsets of columns is usually several entities. Split it, or use a properly typed variant column.
+   - **Done when:** each table has one clear meaning per row.
+
+6. Plan for soft deletion or do not do it.
+   - A `deleted_at` column means every query must filter on it, and one that forgets leaks deleted data. If you need it, add a view or partial indexes so the filter cannot be forgotten.
+   - **Done when:** deleted rows cannot appear through a normal query path.
+
+## Verification
+
+- Every table has a primary key and appropriate foreign keys.
+- Inserting data that violates a business rule is rejected by the database itself.
+- A representative query runs without an unexpected join.

package/native-skills/database/transactions-and-isolation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: transactions-and-isolation
+description: Reason about database transactions or fix a concurrency bug. Use when two operations interfere, when a balance or counter goes wrong under load, or when deadlocks appear.
+---
+
+# Transactions and Isolation
+
+## What the default does not protect you from
+
+Most databases default to read committed. That prevents dirty reads and nothing else. Under it, a read-then-write sequence is a race: two transactions both read the old value, both write, and one update vanishes. Almost every "the counter is wrong" bug is this.
+
+## Workflow
+
+1. Identify read-modify-write sequences.
+   - Any code that SELECTs a value, computes from it, and UPDATEs. These are the races.
+   - **Done when:** every such sequence is listed.
+
+2. Fix each one with the cheapest sufficient tool.
+   - **Atomic update:** `UPDATE ... SET n = n + 1` — no read, no race. Always prefer this.
+   - **Pessimistic lock:** `SELECT ... FOR UPDATE` — locks the row for the transaction. Correct, and it serialises.
+   - **Optimistic lock:** a version column, and `UPDATE ... WHERE version = ?` with a retry on zero rows. Best under low contention.
+   - **Serializable isolation:** the database detects the anomaly and aborts one transaction. Correct and simple, but you MUST handle the serialisation failure by retrying.
+   - **Done when:** each sequence uses one of these and the choice is stated.
+
+3. Keep transactions short and free of external calls.
+   - A network request inside a transaction holds locks for the duration of someone else's outage. Do the external work outside and commit the result.
+   - **Done when:** no transaction contains a network call.
+
+4. Order locks consistently to avoid deadlocks.
+   - A deadlock is two transactions taking the same locks in different orders. Always acquire in a fixed order — by primary key, for example.
+   - **Done when:** every multi-row write takes locks in a defined order.
+
+5. Retry serialisation and deadlock failures.
+   - These are expected, not exceptional. Retry with backoff, with a bounded count.
+   - **Done when:** the retry path exists and is tested.
+
+## Verification
+
+- A concurrency test with many parallel workers produces the correct final value.
+- No transaction performs I/O outside the database.
+- Deadlock and serialisation failures are retried rather than surfaced.

package/native-skills/design/colour-system-construction/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: colour-system-construction
+description: Build a colour palette for an interface. Use when colours were chosen individually, when a dark mode is being added, or when contrast is failing.
+---
+
+# Colour System Construction
+
+## Build roles, not colours
+
+A palette is a set of ROLES — background, surface, border, muted text, body text, accent, and the status colours. Components ask for a role. This is the only way a theme can be swapped, a dark mode can be added, or a brand colour can be changed without editing every file.
+
+## Workflow
+
+1. Start from the neutrals.
+   - Most of an interface is grey. Build a ramp of seven to nine steps from near-background to near-foreground, then assign roles to steps. Getting the neutrals right is most of the work, and it is the step most often skipped.
+   - **Done when:** a neutral ramp exists and every structural element uses a step from it.
+
+2. Add one accent, then stop.
+   - A single accent used consistently reads as intentional. Three accents read as decoration. Add a second only when a genuine second meaning exists.
+   - **Done when:** the number of accents equals the number of distinct meanings.
+
+3. Check contrast as you assign, not afterwards.
+   - Body text against its background: at least 4.5:1. Large text and UI borders: at least 3:1. A palette that fails here needs rebuilding, not adjusting.
+   - **Done when:** every text-on-background pair in the design meets its ratio.
+
+4. Never encode meaning in hue alone.
+   - Error, success and warning must also differ by icon, text, or position. Roughly one in twelve men cannot distinguish red from green.
+   - **Done when:** every status is identifiable in greyscale.
+
+5. Define the dark theme by redefining ROLES.
+   - Not by inverting the values. Dark mode wants desaturated accents and lighter surfaces raised above the background, which an inversion gets backwards.
+   - **Done when:** both themes are defined as role assignments and neither is derived by inversion.
+
+## Verification
+
+- Every colour used is a named role, not a literal value.
+- Contrast checks pass for every text pair in both themes.
+- The interface remains usable rendered in greyscale.

package/native-skills/design/design-direction-brief/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: design-direction-brief
+description: Choose a visual direction before building any UI, landing page, or graphic. Use at the start of any design work, and whenever output risks looking like a generic template.
+---
+
+# Design Direction Brief
+
+## Why this comes first
+
+Without a stated direction, generated design converges on the same defaults every time: a centred hero, a purple-to-blue gradient, three feature cards with outline icons, a rounded sans-serif. It is recognisable on sight and it reads as unconsidered. The direction is what prevents that, and it must be chosen BEFORE any markup is written.
+
+## Workflow
+
+1. Write the brief in four lines.
+   - **Audience:** who reads this, in what state of mind.
+   - **Feeling:** three adjectives, and three the design must NOT be. The negative list does more work than the positive one.
+   - **Reference:** a named movement or era, not "modern" or "clean" — those are not directions.
+   - **Constraint:** one rule that forces a decision. "No gradients." "Exactly two typefaces." "The grid is visible."
+   - **Done when:** all four lines are written and the reference names something specific.
+
+2. Pick the reference from an actual vocabulary.
+   - Swiss/International (grid, Helvetica-lineage, flush-left, generous whitespace), Brutalist (raw structure, system fonts, hard edges, visible borders), Editorial (serif display, strong hierarchy, wide measure columns), Bauhaus (primary colours, geometric forms), Memphis (asymmetry, pattern, clashing colour), Japanese minimalism (asymmetric balance, negative space, restrained palette), Art Deco (symmetry, metallic accents, high-contrast geometry), Terminal/technical (monospace, fixed grid, minimal chrome).
+   - **Done when:** one is named and the others are consciously rejected.
+
+3. Derive the system from the direction, not from habit.
+   - Type scale, spacing scale, palette and border treatment all follow from the reference. Swiss does not get rounded corners. Brutalist does not get soft shadows.
+   - **Done when:** each system decision can be traced to the reference.
+
+4. Check the negative list before finishing.
+   - Read the three "must not be" adjectives and look at the result. If any of them fits, the direction was not followed.
+   - **Done when:** none of the negative adjectives applies.
+
+## The default trap
+
+If the output has a centred hero with a gradient headline, three equal cards below it, and rounded everything — the brief was skipped. Go back to step one.
+
+## Verification
+
+- The brief exists in writing.
+- Every system decision traces to the named reference.
+- None of the three negative adjectives describes the result.

package/native-skills/design/motion-and-transitions/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: motion-and-transitions
+description: Add animation or transitions to an interface. Use when a UI changes state abruptly, when animations feel slow, or when motion is being added for its own sake.
+---
+
+# Motion and Transitions
+
+## What motion is for
+
+Explaining a change. Where something came from, where it went, what is loading. Motion that explains nothing is decoration, and decoration on a screen someone uses fifty times a day becomes an irritation.
+
+## Workflow
+
+1. Justify each animation in one sentence.
+   - "This shows the panel came from the button." If the sentence cannot be written, remove the animation.
+   - **Done when:** every transition has a stated purpose.
+
+2. Set duration by distance and size.
+   - Small local changes 100–150ms. Panels and modals 200–300ms. Full-page transitions up to 400ms. Anything over 400ms feels broken, however smooth.
+   - **Done when:** no interaction feedback exceeds 400ms.
+
+3. Choose easing by direction.
+   - Entering: ease-out — fast start, gentle settle. Leaving: ease-in — the element is going, so get on with it. Moving between two on-screen positions: ease-in-out. Never `linear` for anything physical.
+   - **Done when:** entrances and exits use different curves.
+
+4. Animate only compositor-friendly properties.
+   - `transform` and `opacity` do not trigger layout. Animating `width`, `height`, `top` or `margin` forces layout on every frame and drops to a visible stutter on a mid-tier device.
+   - **Done when:** the performance panel shows no layout recalculation during the animation.
+
+5. Honour the reduced-motion preference.
+   - `@media (prefers-reduced-motion: reduce)` must remove or shorten motion. For some people, motion causes nausea — this is an accessibility requirement, not a nicety.
+   - **Done when:** with the preference set, transitions are instant or minimal and nothing breaks.
+
+## Verification
+
+- Every animation has a stated purpose.
+- The performance panel shows no layout thrash during motion.
+- With reduced motion enabled the interface is fully functional.

package/native-skills/design/responsive-strategy/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: responsive-strategy
+description: Make an interface work across screen sizes. Use when a layout breaks on mobile, when breakpoints are copied from a framework, or when a design was built for one width.
+---
+
+# Responsive Strategy
+
+## Breakpoints come from the content
+
+The right breakpoint is the width at which THIS layout stops working — found by resizing until it breaks. Device-named breakpoints copied from a framework describe hardware that no longer exists and produce layouts that are wrong on real screens.
+
+## Workflow
+
+1. Design the narrow case first.
+   - A single column forces a decision about priority: what does the user need first. Widening then adds; narrowing from a wide design only ever removes, and the removal is arbitrary.
+   - **Done when:** the interface is complete and usable at 320px.
+
+2. Prefer intrinsic sizing to breakpoints.
+   - `clamp()` for type and spacing, `minmax()` with `auto-fit` for grids, `flex-wrap` for rows. Each of these removes a breakpoint entirely and adapts continuously rather than in jumps.
+   - **Done when:** the count of media queries is as low as the layout allows.
+
+3. Use container queries for components.
+   - A card in a sidebar and the same card in a main column should lay out differently. That depends on the CONTAINER width, not the viewport, and a media query cannot express it.
+   - **Done when:** components respond to their own container.
+
+4. Respect touch and pointer differences.
+   - Touch targets at least 44px. Hover-only affordances need a tap equivalent. Test with a real finger, not a narrow browser window.
+   - **Done when:** every action is reachable by touch without hovering.
+
+5. Handle the vertical axis too.
+   - Landscape phones and split-screen windows are short. A hero sized in `100vh` is unusable there. Use `100dvh` or a `min-height` with content-driven growth.
+   - **Done when:** the interface works at 320×480 as well as 1920×1080.
+
+## Verification
+
+- No horizontal scroll from 320px to 2560px.
+- Every interactive target is at least 44px on touch.
+- Zooming text to 200% neither clips nor overlaps content.
+- The layout is usable in a short landscape viewport.

package/native-skills/design/spacing-and-rhythm/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: spacing-and-rhythm
+description: Set spacing and alignment in an interface. Use when padding values look arbitrary, when a layout feels cramped or loose, or when elements do not line up.
+---
+
+# Spacing and Rhythm
+
+## The single rule
+
+Every space is a step on one scale. The moment an arbitrary value appears — `padding: 13px` — the rhythm is broken, and the eye reads the whole layout as slightly wrong without being able to say why.
+
+## Workflow
+
+1. Define the scale once.
+   - A geometric-ish ramp from a 4px or 8px base: 4, 8, 12, 16, 24, 32, 48, 64, 96. Name them and use only these.
+   - **Done when:** no spacing value in the codebase is outside the scale.
+
+2. Space by relationship, not by taste.
+   - Elements that belong together get less space than elements that do not. This proximity grouping carries more meaning than borders or boxes ever will, and it costs no ink.
+   - **Done when:** the grouping is readable from spacing alone, with all borders removed.
+
+3. Give sections room proportional to their weight.
+   - A page section needs several times the space of an element within it. Uniform spacing everywhere flattens the structure.
+   - **Done when:** the top-level structure is visible when scrolling quickly.
+
+4. Space in one direction.
+   - Set margin on one side only (`margin-block-end`, or a flex/grid `gap`). Margins on both sides collapse unpredictably and make spacing impossible to reason about.
+   - **Done when:** no element sets both a top and a bottom margin.
+
+5. Align to a small number of edges.
+   - Every element should line up with something. Multiple near-but-not-equal left edges is the most visible sign of an unconsidered layout.
+   - **Done when:** drawing vertical lines through the layout shows few distinct alignment edges.
+
+## Verification
+
+- Grep the stylesheet for spacing values not on the scale — there should be none.
+- With all borders and backgrounds removed, the grouping is still legible.
+- Overlaying a vertical rule at each alignment edge produces a small number of lines.

package/native-skills/design/type-scale-and-hierarchy/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: type-scale-and-hierarchy
+description: Set typography for an interface or document. Use when text sizes were picked ad hoc, when headings and body are hard to tell apart, or when long text is hard to read.
+---
+
+# Type Scale and Hierarchy
+
+## What makes typography read as designed
+
+A small number of sizes, related by a ratio, with weight and space doing the rest of the work. Interfaces look amateurish when every element gets its own size, and when hierarchy is expressed only by making things bigger.
+
+## Workflow
+
+1. Build a scale, do not pick sizes.
+   - Choose a base (16px for body on the web) and a ratio: 1.2 for dense interfaces, 1.25 for general use, 1.333 or 1.5 for editorial with few levels.
+   - Round to whole pixels and keep five to seven steps total. More than that and the steps stop being distinguishable.
+   - **Done when:** every size in the design is a step on the scale.
+
+2. Set the measure before the size.
+   - 45–75 characters per line for body text. Longer and the eye loses the return; shorter and it breaks rhythm. `max-width: 65ch` is the direct expression of this.
+   - **Done when:** body text sits between 45 and 75 characters per line at every breakpoint.
+
+3. Set line height inversely to size.
+   - Body 1.5–1.6. Headings 1.1–1.25. A heading at body line height looks loose and disconnected from itself.
+   - **Done when:** each level has a line height appropriate to its size.
+
+4. Express hierarchy with three tools, not one.
+   - Size, weight, and colour or space. Two levels that differ only in size need a large gap to read as different; two that differ in weight and space can be one step apart.
+   - **Done when:** hierarchy survives a squint test — the reading order is obvious out of focus.
+
+5. Restrain the families.
+   - One typeface with a real range of weights beats two chosen for contrast. If two, make them genuinely different in category (a serif display against a sans body), never two similar sans faces.
+   - **Done when:** the design uses at most two families, with a stated reason for the second.
+
+## Verification
+
+- Every text size in the rendered page is a step on the declared scale.
+- Body measure is within 45–75 characters at all breakpoints.
+- The page passes a squint test: the reading order is clear when blurred.

package/native-skills/design/visual-qa-loop/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: visual-qa-loop
+description: Check that a built interface actually looks right. Use after implementing any UI, and before declaring visual work finished.
+---
+
+# Visual QA Loop
+
+## The rule
+
+Look at it. A human developer opens the browser; anything building an interface must do the same. Code that compiles and tests that pass say nothing about whether the result is usable or whether it looks like a template.
+
+## Workflow
+
+1. Render it and capture the result.
+   - Take a screenshot at a realistic width. Reading the markup is not a substitute — spacing, contrast and hierarchy are only visible when rendered.
+   - **Done when:** a screenshot of the actual rendered page exists.
+
+2. Run the squint test.
+   - Blur the image mentally or literally. The reading order should be obvious, the primary action should stand out, and the grouping should be visible. If everything has equal weight, the hierarchy failed.
+   - **Done when:** the intended reading order survives blurring.
+
+3. Check against the design brief.
+   - Re-read the direction that was chosen. Does the result match the named reference and avoid the three negative adjectives?
+   - **Done when:** the result matches the brief, or the mismatch is named and fixed.
+
+4. Check the states, not just the happy path.
+   - Empty, loading, error, one item, and far too many items. Long names, long text, missing images. Most visual bugs live in the states nobody screenshots.
+   - **Done when:** every state has been rendered and looks deliberate.
+
+5. Check both themes and both extremes of width.
+   - Light and dark, 320px and 2560px. A design checked at one width in one theme is checked at a quarter of its surface.
+   - **Done when:** all four combinations are rendered and correct.
+
+6. If it looks generic, rebuild rather than adjust.
+   - A centred hero, a gradient headline, three equal cards and rounded everything is the default shape, not a design. Adjusting its padding does not fix it.
+   - **Done when:** the result would not be mistaken for a template.
+
+## Verification
+
+- Screenshots exist for every state, both themes, and both width extremes.
+- The squint test passes.
+- The result traces to the design brief.

package/native-skills/devops/docker-multi-stage-builds/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: docker-multi-stage-builds
+description: Build a Dockerfile for a compiled or bundled project. Use when adding containerisation, when an image exceeds a few hundred megabytes, or when a build copies source into the runtime layer.
+---
+
+# Docker Multi-Stage Builds
+
+## Invariants
+
+1. Compiled and bundled languages get a build stage and a runtime stage. Never one stage.
+2. The final image never runs as `root`.
+3. Secrets never enter a layer. `COPY .env` is a leak even if a later stage deletes it — layers are additive and readable with `docker history`.
+
+## Workflow
+
+1. Read the existing build.
+   - Identify the build command, the artefact directory, and the runtime entrypoint.
+   - **Done when:** you can name the exact directory the runtime needs and nothing else.
+
+2. Split the stages.
+   - Stage one installs every dependency and builds. Stage two starts from a clean base and copies only the artefact plus production dependencies.
+   - Order layers by change frequency: manifest first, `install` second, source last. A source edit must not invalidate the dependency layer.
+   - **Done when:** editing one source file rebuilds only the final layers.
+
+3. Drop privileges.
+   - Create a user in the runtime stage and switch to it before `CMD`.
+   - **Done when:** `docker run --rm IMAGE id -u` prints a non-zero uid.
+
+4. Add a `.dockerignore`.
+   - At minimum `node_modules`, `.git`, `.env*`, build output, and test fixtures. Without it the whole working tree enters the build context and slows every build.
+   - **Done when:** `docker build` reports a context under a few megabytes for a typical app.
+
+## Node template
+
+```dockerfile
+FROM node:24-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:24-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -S app && adduser -S app -G app
+COPY package*.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+COPY --from=build /app/dist ./dist
+USER app
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+## Verification
+
+- `docker build -t app .` succeeds.
+- `docker image ls app` shows a size in line with the base image plus the artefact.
+- `docker history app` shows no layer containing a secret file.
+- The container starts and answers a request.

package/native-skills/devops/github-actions-ci/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: github-actions-ci
+description: Write or repair a GitHub Actions workflow for build, test, or release. Use when a repository has no CI, when a workflow is slow, or when a job fails only in CI and not locally.
+---
+
+# GitHub Actions CI
+
+## Workflow
+
+1. Establish what must be true before a merge.
+   - Usually: install, lint, test, build. Ask which of those already exist as scripts rather than inventing commands.
+   - **Done when:** every gate maps to a command that already runs locally.
+
+2. Pin the trigger narrowly.
+   - `pull_request` plus `push` on the default branch. A workflow that runs on every push to every branch burns minutes and teaches people to ignore red.
+   - **Done when:** the trigger block names specific branches or paths.
+
+3. Cache the dependency layer.
+   - `actions/setup-node` and `actions/setup-python` take a `cache` input; use it rather than hand-rolling `actions/cache`.
+   - **Done when:** a second run reports a cache hit and installs in a fraction of the first run's time.
+
+4. Make failure legible.
+   - Upload test reports and build logs as artifacts on failure. A red check with no artefact costs someone a local reproduction.
+   - **Done when:** a deliberately failing run leaves an artefact that explains the failure.
+
+5. Lock down the token.
+   - Set `permissions:` explicitly at the workflow level. The default grant is far wider than a test job needs.
+   - **Done when:** `permissions` names only what the job writes, typically `contents: read`.
+
+## Template
+
+```yaml
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm test
+```
+
+## Verification
+
+- Push a branch and confirm the workflow runs and passes.
+- Confirm a second run hits the cache.
+- Confirm `concurrency` cancels a superseded run rather than queueing it.

package/native-skills/devops/incident-triage/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: incident-triage
+description: Respond to a production incident or a failing deployment. Use when a service is down, error rates have spiked, or a release must be assessed under time pressure.
+---
+
+# Incident Triage
+
+## Order of operations
+
+Stop the bleeding, then find the cause. Diagnosis while users are down is the most common way an incident doubles in length.
+
+## Workflow
+
+1. Establish the blast radius before touching anything.
+   - What is failing, for whom, since when, and what changed in that window. The last question resolves most incidents on its own.
+   - **Done when:** you can state the start time and the last change before it.
+
+2. Mitigate with the fastest reversible action.
+   - Roll back, disable the feature flag, or shift traffic. Do not fix forward under pressure — a hurried fix is a second incident.
+   - **Done when:** the user-visible symptom is gone, whether or not the cause is known.
+
+3. Preserve the evidence.
+   - Capture logs, metrics windows and a heap or thread dump before restarting anything. A restart usually destroys the only copy of the state that explains the failure.
+   - **Done when:** the evidence is saved somewhere that survives the restart.
+
+4. Confirm recovery against a signal, not a feeling.
+   - Watch the same error-rate and latency series that showed the problem, for long enough to cover a full request cycle.
+   - **Done when:** the series has returned to its pre-incident band and stayed there.
+
+5. Write the timeline while it is fresh.
+   - Times, actions, and what each one changed. Blameless: the target is the system that allowed it, not the person who triggered it.
+   - **Done when:** someone who was not present can follow the sequence.
+
+## Verification
+
+- The symptom is gone and confirmed by the original alerting signal.
+- Evidence is captured.
+- A follow-up action exists for the cause, separate from the mitigation.