@agentyx/core 0.2.0 → 0.3.0

package/skills/refactoring-safely/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: refactoring-safely
+description: Change structure without changing behavior, in reversible steps.
+---
+
+# Refactoring safely
+
+Refactoring changes structure while behavior stays identical. The moment behavior changes it is no
+longer refactoring, and it needs its own review and its own tests.
+
+## Secure the behavior first
+
+Ensure tests cover the current behavior before restructuring. Without that net, a refactor is an
+untested rewrite and any difference goes unnoticed.
+
+## Separate the commits
+
+Never mix refactoring with a feature or a fix in one commit. Mixed changes make review hard and make
+a clean revert impossible when something breaks.
+
+## Move in small steps
+
+Take one transformation at a time and keep the suite green between steps. A long sequence of
+unverified edits is where the untraceable regression enters.
+
+## Follow the pain
+
+Refactor where change is actually difficult and where work is actually happening. Restructuring
+stable code nobody touches spends risk with no return.
+
+## Know when to stop
+
+Stop when the code is clear enough for the change you came to make. Refactoring is preparation for
+work, not the work itself.

package/skills/schema-migrations/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: schema-migrations
+description: Evolve a live schema without downtime or data loss.
+---
+
+# Schema migrations
+
+A migration runs once against real data that cannot be recreated. Treat it with more care than the
+code that prompted it.
+
+## Make migrations additive first
+
+Add columns and tables before anything reads them, and remove old structures only after nothing
+references them. During deployment both versions of the application run at once.
+
+## Expand, migrate, contract
+
+Add the new shape, backfill it, switch reads and writes over, then drop the old shape in a later
+release. Attempting all three at once forces downtime and leaves no safe point to stop.
+
+## Backfill in batches
+
+Update large tables in bounded chunks with pauses between them. A single statement over millions of
+rows holds locks and can stall the application entirely.
+
+## Keep them reversible
+
+Provide a tested rollback, or design the change so the previous version still works against the new
+schema. A migration you cannot undo turns a small mistake into an incident.
+
+## Test against production-like data
+
+Verify on a realistic copy for both correctness and duration. Migrations that finish instantly in
+development regularly run for hours in production.

package/skills/secrets-handling/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: secrets-handling
+description: Keep credentials out of source, logs and client bundles.
+---
+
+# Secrets handling
+
+A secret in version control is compromised the moment it is pushed, and rewriting history does not
+undo it.
+
+## Keep secrets out of the repository
+
+Load credentials from environment variables or a secret manager. Commit a documented example file
+with placeholder values, never the real ones.
+
+## Rotate on exposure
+
+Treat any secret that reached a repository, log, ticket or chat message as leaked. Rotate it before
+removing it — deletion without rotation leaves the credential valid.
+
+## Never log or serialize them
+
+Redact credentials, tokens and keys in logs, error messages and crash reports. Review debug output
+and third-party error reporters, which capture more surrounding context than expected.
+
+## Understand the client boundary
+
+Anything shipped to a browser or mobile app is public, regardless of build-time substitution. Only
+publishable identifiers belong in client code; every real secret stays server side.
+
+## Scan continuously
+
+Run secret scanning in pre-commit hooks and in CI. Detection after the fact is far cheaper than an
+incident, and cheaper still before the push.

package/skills/secure-coding/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: secure-coding
+description: Apply input validation, output encoding and least privilege by default.
+---
+
+# Secure coding
+
+Treat every input crossing a trust boundary as hostile, including input from your own other services.
+
+## Validate at the boundary
+
+Validate structure, type, range and length where untrusted data enters, and reject what does not
+conform. Allow-lists beat deny-lists: enumerate what is valid rather than guessing what is dangerous.
+
+## Never build queries or commands by concatenation
+
+Use parameterized queries and argument arrays. String interpolation into SQL, shell commands,
+templates or file paths is the root of injection.
+
+## Encode for the destination
+
+Escaping depends on where the value lands: HTML body, attribute, URL, SQL, shell and JSON all differ.
+Encode at the point of output, not on the way in.
+
+## Apply least privilege
+
+Give every process, token and database role the narrowest permissions that let it work. Scope
+credentials per environment so a leak in one does not compromise the others.
+
+## Fail closed
+
+On error, deny access and log the reason. An exception path that falls through to permitted access is
+a vulnerability, not a bug.

package/skills/semantic-html/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: semantic-html
+description: Use native elements and structure so accessibility works by default.
+---
+
+# Semantic markup
+
+The accessible behavior of a native element is free and correct. Recreating it is expensive and
+rarely complete.
+
+## Use the element that means it
+
+Buttons, links, form controls, lists and headings carry role, keyboard behavior and state to
+assistive technology. A styled container with a click handler carries none of it.
+
+## Distinguish links from buttons
+
+A link navigates, a button performs an action. Choosing by appearance breaks expectations for
+keyboard, screen reader and browser features such as opening in a new tab.
+
+## Structure with headings and landmarks
+
+Use one descriptive page title, a logical heading order without skipped levels, and landmark regions
+for navigation, main content and complements. Many users navigate by these alone.
+
+## Label every control
+
+Associate a visible label with each input. Placeholders disappear on entry and are not labels;
+icon-only controls need an accessible name.
+
+## Describe meaningful images
+
+Give informative images alt text conveying their purpose, and mark decorative images as such. Alt
+text should say what the image communicates, not what it depicts.

package/skills/structured-logging/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: structured-logging
+description: Emit machine-readable logs with the context needed to diagnose incidents.
+---
+
+# Structured logging
+
+Logs exist to answer questions during an incident. Write them for the person querying at three in
+the morning.
+
+## Log structured events, not sentences
+
+Emit key-value fields rather than interpolated prose. Structured records can be filtered, aggregated
+and correlated; free text can only be searched by substring.
+
+## Carry correlation identifiers
+
+Propagate a request or trace identifier through every layer, including asynchronous work. Without
+it, reconstructing one operation across services is guesswork.
+
+## Use levels with discipline
+
+Error means someone must act, warn means a degraded path was taken, info records significant state
+changes, and debug is for development. When everything is an error, the level conveys nothing.
+
+## Never log sensitive data
+
+Credentials, tokens, personal data and payment details must not reach logs, which are widely
+readable and long-lived. Redact at the logging boundary rather than trusting call sites.
+
+## Log decisions, not control flow
+
+Record what was decided and why — inputs, chosen branch, outcome. Tracing every function entry
+produces volume without insight and buries the events that matter.

package/skills/technical-writing/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: technical-writing
+description: Write documentation that answers the reader's question quickly.
+---
+
+# Technical writing
+
+Documentation is read under pressure by someone trying to accomplish something. Optimize for their
+task, not for completeness.
+
+## Lead with the answer
+
+Put the conclusion, the command or the decision first, then the explanation. Readers stop as soon as
+they have what they need, and background before the answer wastes that attention.
+
+## Write for a specific reader
+
+Decide whether the audience is a newcomer, an integrator or a maintainer, and commit. Text that
+serves everyone equally usually serves nobody.
+
+## Separate the kinds
+
+A tutorial teaches, a how-to solves one problem, a reference describes the surface, an explanation
+gives context. Mixing them in one document makes it useless for all four purposes.
+
+## Show the real thing
+
+Include commands and examples that run as written. An example that has drifted from the code is
+worse than no example, because it is trusted.
+
+## Prune on every change
+
+Delete what is obsolete rather than appending corrections. Documentation loses value through
+accumulation, and stale instructions cost more than missing ones.

package/skills/test-doubles/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: test-doubles
+description: Use fakes, stubs and mocks deliberately instead of mocking everything.
+---
+
+# Test doubles
+
+Replace a real dependency only when using it makes the test slow, non-deterministic, or impossible
+to run.
+
+## Prefer the real thing
+
+Use the real implementation when it is fast and deterministic. In-memory databases, temporary
+directories and local fakes usually beat a mock, because they exercise the actual contract.
+
+## Match the double to the need
+
+Use a stub to supply input, a fake for a working lightweight implementation, and a mock only when
+the interaction itself is the behavior under test. Asserting on calls to a dependency that is not
+the subject couples the test to implementation.
+
+## Double boundaries you own
+
+Replace your own abstraction over a third-party client rather than the client internals. When the
+library changes shape, one adapter moves instead of every test.
+
+## Keep doubles honest
+
+A double that accepts calls the real dependency would reject turns a passing test into false
+confidence. Verify the contract against the real implementation at least once.

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/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.