@agentyx/core 0.1.1 → 0.3.0

package/skills/test-strategy/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: test-strategy
+description: Choose the right test level and scope before writing tests.
+---
+
+# Test strategy
+
+Decide what a test is for before writing it. Most wasted test effort comes from testing at the wrong
+level, not from writing tests badly.
+
+## Choose the level
+
+Cover business rules and edge cases with unit tests, module boundaries and wiring with integration
+tests, and only critical user journeys end to end. Push detail down: if a case can be covered one
+level lower, cover it there.
+
+## Test behavior, not structure
+
+Assert on observable behavior through the public interface. A test that breaks when an
+implementation detail changes, while behavior stays the same, is a liability.
+
+## Keep tests independent
+
+Each test sets up the state it needs and passes in any order, alone or in parallel. Shared mutable
+fixtures produce failures that depend on execution order.
+
+## Name for the case
+
+State the scenario and the expected outcome. A failing test name should identify the broken behavior
+without opening the file.
+
+## Cover the boundaries
+
+Prioritize empty input, a single element, maximum size, null and undefined, concurrent access, and
+failure of every external dependency.

package/skills/transactions-and-consistency/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: transactions-and-consistency
+description: Choose transaction boundaries and handle concurrent writes correctly.
+---
+
+# Transactions and consistency
+
+Concurrency defects are rare in testing and constant in production. Decide the boundary and the
+isolation deliberately.
+
+## Scope transactions tightly
+
+A transaction should cover exactly the writes that must succeed or fail together. Long transactions
+hold locks and connections, and turn one slow operation into a system-wide stall.
+
+## Keep external calls outside
+
+Never hold a transaction open across a network request to another service. The remote call cannot be
+rolled back, and its latency becomes lock duration.
+
+## Know your isolation level
+
+The default isolation of your database determines which anomalies are possible. Read-modify-write
+sequences need explicit locking or a compare-and-set, because reading and then writing is not atomic.
+
+## Make retries safe
+
+Give operations an idempotency key so a retried request cannot apply twice. Clients, queues and
+proxies all retry, and at-least-once delivery is the normal case.
+
+## Prefer atomic operations to read-then-write
+
+Let the database compute the new value in one statement instead of reading it into the application
+and writing it back. That closes the window where another writer intervenes.

package/skills/typescript-modeling/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: typescript-modeling
+description: Model TypeScript domains with unions, readonly data, satisfies, and useful generics.
+---
+
+# TypeScript modeling
+
+Use the type system to express relationships that matter at runtime.
+
+## Shapes
+
+Choose `type` or `interface` for local semantics and ecosystem fit, not dogma. Use discriminated
+unions for variants and exhaustive switches where missing cases would be a bug.
+
+## Contracts
+
+Annotate exported APIs and external boundaries. Let inference handle obvious locals. Use `satisfies`
+when a value should be checked against a contract without widening away useful literal information.
+
+## Mutability and generics
+
+Mark data `readonly` when mutation is not part of the contract. Use generics only when they express
+a real relationship between inputs and outputs; avoid type puzzles that make maintenance harder.

package/skills/typescript-modern/SKILL.md

@@ -1,41 +1,29 @@
 ---
 name: typescript-modern
-description: Modern TypeScript conventions - strict types, inference, small explicit APIs.
+description: Use current TypeScript module, syntax, import, and async patterns.
 ---
 
 # Modern TypeScript
 
-Write types that describe the domain, and let the compiler do the rest.
+Use current platform and language features without making code clever.
 
-## Typing
+## Modules
 
-Keep `strict` on and treat `any` as a defect. When a value really is unknown, type it `unknown` and
-narrow it — with `typeof`, `instanceof`, a discriminant check, or a validator that returns a typed
-result.
+Prefer ESM. Use type-only imports and exports when a symbol is erased at runtime. Keep module
+boundaries explicit and avoid circular dependencies.
 
-Annotate what forms a contract: exported functions, public fields, and the boundaries where outside
-data enters. Let inference handle everything else; restating an obvious type is noise that drifts
-out of date.
+## Syntax
 
-Avoid assertions. `as` and `!` silence the compiler without changing the value, so each one is an
-unchecked claim. Prove it with a real check instead.
+Use modern syntax when it clarifies intent: optional chaining, nullish coalescing, object
+destructuring, `const`, `for...of`, and `async`/`await`. Avoid transpiler-era patterns when the
+runtime supports the native feature.
 
-## Modelling
+## Platform
 
-Use discriminated unions for values that come in variants: a `kind` field plus the data that
-variant carries beats one wide object of optional properties, and it lets the compiler prove a
-`switch` is exhaustive.
+Prefer native platform APIs where they are stable and already available in the project runtime. Do
+not add a dependency for behavior the platform provides clearly.
 
-Make illegal states unrepresentable where it is cheap — required fields instead of optional ones, a
-union instead of two booleans, `readonly` on data that is not meant to change.
+## Async
 
-Derive types instead of duplicating them. When a schema or a constant already describes a shape,
-infer from it; two declarations of the same thing will disagree eventually.
-
-## Modules and APIs
-
-Use ESM. Export the smallest surface callers need and keep helpers module-private — every export is
-a contract you have to keep.
-
-Prefer plain functions and plain objects. Classes earn their place when there is real state or
-identity; factories, containers, and single-implementation interfaces usually do not.
+Use `async`/`await` for sequential asynchronous flow and `Promise.all` for independent work. Handle
+rejections at boundaries with useful context.

package/skills/typescript-strict/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: typescript-strict
+description: Use TypeScript strictness, narrowing, and validation for safe boundaries.
+---
+
+# TypeScript strictness
+
+Keep strict mode valuable by treating escapes as design decisions.
+
+## Unknown data
+
+Use `unknown` for untrusted values, then narrow with control flow, discriminants, predicates, or a
+schema validator. Validate external input at the boundary before it enters domain code.
+
+## Avoid unsafe escapes
+
+Avoid `any`, unsafe casts, and non-null assertions. If a value can be absent, model that possibility
+and handle it. Prefer checks that prove the value exists over assertions that silence the compiler.
+
+## Optional semantics
+
+When exact optional behavior matters, distinguish an omitted property from a property whose value is
+`undefined`. Do not use optional fields as a substitute for a clear variant model.

package/skills/web-vitals/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: web-vitals
+description: Optimize loading, interactivity and layout stability for real users.
+---
+
+# Web performance
+
+Perceived speed is decided by what the user sees and can do, not by total bytes.
+
+## Protect the critical path
+
+Identify what must load before the page is useful and defer everything else. Render-blocking scripts
+and stylesheets delay first paint more than their size suggests.
+
+## Ship less JavaScript
+
+Split by route, load heavy features on demand, and remove unused dependencies. JavaScript costs
+twice: once to download and again to parse and execute, and the second cost dominates on low-end
+devices.
+
+## Reserve space for content
+
+Give images, embeds and injected banners explicit dimensions so later loads do not move what is
+already visible. Layout shift is most damaging exactly when the user is about to act.
+
+## Keep interactions responsive
+
+Break long tasks, move heavy work off the main thread, and give immediate feedback to input. A
+response that is visibly acknowledged tolerates far more latency than one that appears frozen.
+
+## Measure real users
+
+Field data from actual devices and networks decides whether the site is fast. Lab measurements are
+for diagnosis, not for judging success.

package/skills/worktree-workflow/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: worktree-workflow
+description: Use git worktrees for isolated parallel implementation when the work warrants it.
+---
+
+# Worktree workflow
+
+Use worktrees when isolation reduces risk for parallel or experimental implementation.
+
+Check repository status before creating one. Use deterministic branch and directory names tied to
+the task. Keep user changes safe: never overwrite or clean files you do not own. After integration,
+remove temporary worktrees only when their work is preserved and no uncommitted changes remain.