@agentyx/core 0.1.1 → 0.3.0

package/skills/flaky-tests/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: flaky-tests
+description: Diagnose and fix non-deterministic tests instead of retrying them.
+---
+
+# Flaky tests
+
+A test that passes and fails without a code change destroys trust in the whole suite. Treat it as a
+defect, not as noise.
+
+## Never paper over it
+
+Do not add a retry, a longer timeout or a skip as the fix. Retries hide real race conditions that
+will surface in production, and a skipped test is a deleted test that still costs time to run.
+
+## Find the source of non-determinism
+
+The usual causes are time, ordering, concurrency, shared state, network and randomness. Pin clocks,
+seed randomness, isolate state, and await every asynchronous operation explicitly.
+
+## Reproduce before fixing
+
+Run the test repeatedly, in random order and in parallel until the failure is reliable. A fix applied
+to a failure you cannot reproduce is a guess.
+
+## Quarantine with a deadline
+
+If a flaky test must leave the critical path immediately, record why and when it will be fixed. An
+unbounded quarantine list becomes permanent, and the coverage it represented is silently gone.

package/skills/focused-verification/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: focused-verification
+description: Choose narrow checks while iterating and full required gates before completion.
+---
+
+# Focused verification
+
+Match checks to risk and phase.
+
+## During iteration
+
+Run the smallest check that can fail for the code you just changed. Prefer a focused test, typecheck
+for one package, or a direct command that exercises the behavior.
+
+## Before completion
+
+Run the repository or product gate required for the touched surface. Include manual checks for CLI
+output, generated files, migrations, or UI behavior that automated tests do not cover.
+
+## Reporting
+
+Report the exact checks you ran. If a check fails or cannot be run, say that plainly with the reason.

package/skills/incident-response/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: incident-response
+description: Restore service first, diagnose second, and learn without blame.
+---
+
+# Incident response
+
+During an incident the goal is to stop the harm. Understanding the cause is important, but it comes
+after recovery.
+
+## Mitigate before diagnosing
+
+Roll back, disable the feature flag, shed load or fail over. A full explanation is worth far less
+than a working system, and the evidence will still be there afterwards.
+
+## Assign roles early
+
+Name someone to coordinate and someone to communicate, separate from those investigating. Without
+this split, either the investigation or the communication is dropped.
+
+## Keep a timeline
+
+Record what was observed, what was changed and when, as it happens. Memory reconstructs incidents
+inaccurately, and the timeline is the basis of the review.
+
+## Change one thing at a time
+
+Simultaneous fixes make it impossible to know what worked, and can deepen the outage. Announce each
+change before making it.
+
+## Review without blame
+
+Examine the conditions that let the failure happen and reach production: missing tests, absent
+alerts, unclear ownership. Blaming an individual guarantees the next incident is reported later.

package/skills/infrastructure-as-code/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: infrastructure-as-code
+description: Define infrastructure declaratively, in version control, applied automatically.
+---
+
+# Infrastructure as code
+
+Infrastructure that exists only as manual console changes cannot be reviewed, reproduced or
+recovered.
+
+## Declare the desired state
+
+Describe what the infrastructure should be and let the tool determine the steps. Declarative
+definitions converge from any starting point; imperative scripts assume one.
+
+## Never change production by hand
+
+Manual edits create drift that the next automated apply will undo or conflict with. When an emergency
+forces a manual change, bring it back into code immediately.
+
+## Review the plan before applying
+
+Read the diff of what will be created, changed and destroyed. Replacement of a stateful resource is
+the failure mode that turns a routine change into data loss.
+
+## Isolate environments
+
+Keep separate state and credentials per environment, sharing definitions through parameters rather
+than copies. Shared state is how a staging change reaches production.
+
+## Protect the state and the secrets
+
+Store state remotely with locking and restricted access — it contains sensitive values. Reference
+secrets from a secret manager instead of committing them alongside the definitions.

package/skills/keyboard-navigation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: keyboard-navigation
+description: Make every interaction reachable, visible and escapable by keyboard.
+---
+
+# Keyboard navigation
+
+Anything achievable with a pointer must be achievable with a keyboard alone. This is the fastest
+accessibility check available: put the mouse away and use the feature.
+
+## Keep order logical
+
+Tab order should follow the visual and logical reading order. Positive tab index values override
+document order and create sequences nobody can predict — leave them alone.
+
+## Make focus visible
+
+Every focusable element needs a clearly visible focus indicator with sufficient contrast. Removing
+default outlines without replacing them makes the interface unusable for keyboard users.
+
+## Never trap focus unintentionally
+
+Focus must be able to leave every component. Deliberate trapping belongs only in modal dialogs, and
+must always offer an escape.
+
+## Support the expected keys
+
+Enter and Space activate controls, Escape dismisses overlays, and arrow keys move within composite
+widgets such as menus, tabs and grids. Follow platform conventions rather than inventing shortcuts.
+
+## Offer a skip link
+
+Let users bypass repeated navigation to reach main content. Without it, every page begins with the
+same long traversal.

package/skills/legacy-code/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: legacy-code
+description: Work safely in unfamiliar code with weak or missing tests.
+---
+
+# Working with legacy code
+
+Legacy code is code you are afraid to change. The goal of each visit is to leave it slightly less
+frightening than you found it.
+
+## Characterize before changing
+
+When behavior is undocumented and untested, write tests that capture what the code does today, even
+where that looks wrong. Those tests describe reality, and reality is what callers depend on.
+
+## Find a seam
+
+Introduce a boundary where a dependency can be substituted, so a piece becomes testable without
+rewriting the whole. A narrow seam beats a broad refactor performed blind.
+
+## Assume the strangeness has a reason
+
+Odd conditionals and special cases usually encode a real requirement or an old incident. Find out why
+before deleting; unexplained code is not the same as unnecessary code.
+
+## Improve what you touch
+
+Leave the area you worked in better: a name clarified, a test added, dead code removed. Repository-
+wide cleanup campaigns stall, while incremental improvement compounds.
+
+## Do not rewrite by default
+
+A rewrite discards embedded knowledge and restarts the bug-discovery process from zero. Prefer
+strangling the old implementation behind a stable interface, one piece at a time.

package/skills/metrics-and-tracing/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: metrics-and-tracing
+description: Instrument systems so failures are visible before users report them.
+---
+
+# Metrics and tracing
+
+Instrumentation should answer whether the system is healthy, and if not, where it broke.
+
+## Measure what users experience
+
+Track request rate, error rate, latency and saturation at the boundaries users touch. Internal
+counters that no symptom maps to generate noise rather than signal.
+
+## Use percentiles, never averages
+
+Averages conceal the tail where the damage is. Watch the high percentiles, because those are the
+requests people notice and complain about.
+
+## Trace across service boundaries
+
+Distributed traces show where time is spent in a request that crosses processes. In any system of
+more than a couple of services, this is the only practical way to locate latency.
+
+## Alert on symptoms, not causes
+
+Alert when users are affected, and let dashboards explain why. Cause-based alerts fire on conditions
+that are frequently harmless, and their volume trains people to ignore them.
+
+## Make every alert actionable
+
+An alert nobody can act on is noise that erodes attention. Each one needs an owner, a clear
+meaning and a documented first response.

package/skills/parallel-work/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: parallel-work
+description: Split independent coding-agent work safely when tasks do not overlap.
+---
+
+# Parallel work
+
+Use parallel work only for independent tasks with clear boundaries.
+
+Define each task's files, inputs, expected output, and verification. Avoid parallel edits to the
+same files or closely coupled behavior. Integrate deliberately: review outputs, reconcile conflicts,
+run the shared checks, and keep the parent agent responsible for the final result.

package/skills/performance-profiling/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: performance-profiling
+description: Measure before optimizing and confirm the gain after.
+---
+
+# Performance profiling
+
+Optimization without measurement is guesswork that costs readability. Find the bottleneck, then fix
+the bottleneck.
+
+## Measure first
+
+Profile under conditions that resemble production: realistic data volume, realistic concurrency, a
+production build. Development builds and toy datasets hide the actual cost.
+
+## Set a target
+
+Define what fast enough means before starting — a latency budget, a percentile, a throughput figure.
+Without a target, optimization has no finish line.
+
+## Fix the dominant cost
+
+Work on the largest contributor first. An improvement to code that accounts for two percent of
+runtime cannot matter, however large the factor.
+
+## Prefer algorithmic wins
+
+Removing repeated work, unnecessary round trips and quadratic behavior beats micro-optimization.
+Caching is a last resort, not a first move: it adds invalidation as a new class of bug.
+
+## Verify and keep the number
+
+Re-measure after the change and record the result. Track the metric so a regression is caught by the
+build rather than by users.

package/skills/pull-requests/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: pull-requests
+description: Size and present changes so they can actually be reviewed.
+---
+
+# Pull requests
+
+Review quality falls sharply with size. A pull request is a request for someone's attention, so make
+that attention easy to give.
+
+## Keep them small
+
+Prefer a few hundred changed lines over a thousand. Large pull requests receive approval rather than
+review, which is the opposite of the intended effect.
+
+## Do one thing
+
+Cover a single feature, fix or refactor. When a change touches many areas for different reasons,
+split it into a sequence that each stand on their own.
+
+## Write the description for the reviewer
+
+State what changes, why, and what to look at closely. Note what you are unsure about — that is where
+review is most valuable and where reviewers most often stay silent.
+
+## Make it verifiable
+
+Include the tests that prove the change and say how to exercise it manually where that applies. A
+reviewer should not have to reconstruct how you convinced yourself.
+
+## Respond to every comment
+
+Address or explicitly decline each point. Silently ignoring a comment wastes the reviewer's effort
+and discourages careful review next time.

package/skills/query-performance/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: query-performance
+description: Diagnose slow database access with query plans, indexes and access patterns.
+---
+
+# Query performance
+
+Most application slowness is data access. Read the query plan before changing the query.
+
+## Read the plan
+
+The execution plan shows what the database actually does: scans, joins, sorts and row estimates. A
+large gap between estimated and actual rows usually means stale statistics or an unsuitable index.
+
+## Index for the access pattern
+
+Index the columns used to filter, join and order, and put the most selective column first in a
+composite index. Every index costs write throughput and storage, so add them for measured queries
+rather than speculatively.
+
+## Eliminate N+1 access
+
+Loading a collection and then querying once per element is the most common performance defect in
+application code. Fetch related data in a single query or a batched load.
+
+## Fetch only what you need
+
+Select the required columns and paginate large result sets with a stable key. Requesting entire rows
+and filtering in application code moves the work to the slowest place.
+
+## Watch the pool and the transaction
+
+Long transactions hold locks and connections, turning a slow query into a system-wide stall. Keep
+transactions short and do external calls outside them.

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/requesting-code-review/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: requesting-code-review
+description: Request independent review after meaningful implementation.
+---
+
+# Requesting code review
+
+Ask for review when a change affects behavior, public APIs, security, data integrity, or several
+modules.
+
+Provide the requirement, changed files, verification performed, and known risks. Ask the reviewer to
+focus on requirement compliance, correctness, regressions, tests, security, and unnecessary
+complexity. Treat findings as inputs to resolve, not as a substitute for your own judgment.

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/subagent-driven-development/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: subagent-driven-development
+description: Coordinate scoped subagent work when the current provider supports it.
+---
+
+# Subagent-driven development
+
+Use subagents when the task benefits from independent investigation, implementation, or review and
+the current provider supports them.
+
+Give each subagent a narrow objective, relevant context, boundaries, and expected output. Do not
+spawn agents for trivial work. Prefer fresh-context reviewers for meaningful changes. The parent
+agent remains responsible for integration, verification, and the final answer.

package/skills/targeted-exploration/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: targeted-exploration
+description: Explore codebases through search, relevant ranges, and module ownership.
+---
+
+# Targeted exploration
+
+Explore from signal to context.
+
+## Flow
+
+Search for the name, command, schema, error, or behavior. Read the relevant symbol or range. Then
+read nearby callers or tests. Open the whole file when the range does not reveal ownership or
+invariants.
+
+## Search
+
+Prefer structural or code-aware search when available. Use text search for identifiers and output
+strings. Avoid dumping unrelated files into context.
+
+## Stop condition
+
+Stop exploring when you can name the owning module, the expected behavior, the likely change, and
+the checks that will verify it.

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.