@agentyx/core 0.2.0 → 0.3.0

package/skills/branching-strategy/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: branching-strategy
+description: Keep branches short-lived and integrate continuously.
+---
+
+# Branching strategy
+
+Merge pain grows superlinearly with divergence. The most effective strategy is the one that keeps
+branches short.
+
+## Keep branches short-lived
+
+Aim for hours or days, not weeks. A long-running branch is an accumulating integration debt, and the
+work it contains is invisible to everyone else until the end.
+
+## Integrate frequently
+
+Bring changes from the main branch into yours regularly rather than resolving everything at the end.
+Frequent small conflicts are trivial; one large conflict is dangerous.
+
+## Decouple deployment from release
+
+Merge incomplete work behind a flag rather than holding it on a branch. Hiding unfinished features at
+runtime is safer than hiding them in version control.
+
+## Protect the main branch
+
+Require review and a green build before merging. The main branch must always be in a releasable
+state, since that is the assumption everything else depends on.
+
+## Pick one convention and hold it
+
+Whether the team rebases or merges matters far less than doing it consistently. Mixed conventions
+produce confusing history and avoidable conflicts.

package/skills/ci-pipelines/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ci-pipelines
+description: Build pipelines that are fast, reproducible and trusted.
+---
+
+# Continuous integration
+
+A pipeline people wait on gets bypassed, and a pipeline people distrust gets ignored. Both failures
+end with broken code in the main branch.
+
+## Fail fast and in order
+
+Run the cheapest checks first: formatting, linting, types, unit tests, then slower integration and
+end-to-end stages. Developers should learn about a trivial mistake in seconds.
+
+## Make builds reproducible
+
+Pin tool versions and use the committed lockfile. A pipeline that passes or fails depending on when
+it ran cannot be used as evidence of anything.
+
+## Keep it fast
+
+Cache dependencies and parallelize independent work. Once feedback takes longer than a short break,
+people stop waiting for it and start merging on hope.
+
+## Never tolerate a red main branch
+
+A failing build on the main branch is the highest priority work for the team. Normalizing red builds
+removes the entire value of the pipeline.
+
+## Gate on what matters
+
+Enforce the checks that protect correctness and security, and keep advisory checks non-blocking. A
+pipeline that blocks on style opinions trains people to skip it.

package/skills/commit-hygiene/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: commit-hygiene
+description: Make each commit a single reviewable change with a useful message.
+---
+
+# Commit hygiene
+
+History is read far more often than it is written — during review, bisection and incident analysis.
+Optimize for those readers.
+
+## One logical change per commit
+
+A commit should do one thing and leave the build working. Mixing a refactor, a fix and a formatting
+pass makes review harder and makes a clean revert impossible.
+
+## Explain why in the message
+
+The diff shows what changed; the message must say why. Summarize the intent in the subject and use
+the body for context, tradeoffs and consequences that are not visible in the code.
+
+## Never commit noise
+
+Keep generated files, dependencies, editor settings and secrets out. Anything committed once stays in
+history even after deletion.
+
+## Separate mechanical from meaningful
+
+Do formatting, renaming and moving in their own commits. A behavioral change hidden inside a
+thousand-line reformat will not be reviewed properly.
+
+## Tidy before sharing
+
+Rewriting local history to produce a coherent sequence is good practice. Rewriting history others
+have pulled is not — once pushed to a shared branch, history is fixed.

package/skills/containerization/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: containerization
+description: Build small, reproducible and non-privileged container images.
+---
+
+# Containerization
+
+An image is a deployment artifact. Build it to be small, identical everywhere and safe to run.
+
+## Build in stages
+
+Compile in a build stage and copy only the artifacts into a minimal runtime image. Shipping compilers
+and development dependencies inflates both image size and attack surface.
+
+## Order layers by volatility
+
+Put rarely changed steps such as dependency installation before frequently changed application code.
+Correct ordering turns most rebuilds into cache hits.
+
+## Pin the base image
+
+Reference an explicit version or digest rather than a moving tag. Rebuilding the same commit must
+produce the same image, and update the base deliberately.
+
+## Never run as root
+
+Create an unprivileged user and drop capabilities. A container is an isolation boundary, not a
+security guarantee, and root inside makes an escape far more valuable.
+
+## Keep configuration and secrets outside
+
+Inject configuration through environment or mounted files at runtime. Baking credentials into an
+image publishes them to everyone who can pull it, permanently.
+
+## Handle signals and report health
+
+Ensure the process receives termination signals so shutdown is graceful, and expose readiness and
+liveness endpoints so orchestrators route traffic correctly.

package/skills/data-modeling/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: data-modeling
+description: Design schemas that make invalid states unrepresentable.
+---
+
+# Data modeling
+
+The schema outlives the application code written against it. Design it so wrong data cannot be
+stored in the first place.
+
+## Constrain in the database
+
+Enforce required fields, uniqueness, foreign keys and value ranges at the storage layer. Application
+checks are bypassed by migrations, admin tools, background jobs and the next service.
+
+## Model the real relationships
+
+Choose cardinality from the domain rather than from current convenience. Discovering that a
+one-to-one is really one-to-many after data exists is among the most expensive corrections available.
+
+## Normalize first, denormalize on evidence
+
+Start from a normalized model and denormalize only for a measured read pattern, accepting the
+duplication cost knowingly. Premature denormalization creates inconsistency that is hard to detect.
+
+## Choose types precisely
+
+Use exact numeric types for money, timezone-aware timestamps for instants, and native types for
+enumerations. Storing everything as text moves validation to every consumer, forever.
+
+## Plan for deletion
+
+Decide early whether records are removed or marked inactive, and how that interacts with foreign
+keys, uniqueness and retention obligations. Retrofitting soft deletion touches every query.

package/skills/decision-records/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: decision-records
+description: Record significant technical decisions with their context and consequences.
+---
+
+# Decision records
+
+Code shows what was built. A decision record preserves why, which is the part that is otherwise lost
+when people move on.
+
+## Record decisions that are costly to reverse
+
+Write one for choices that shape structure: a datastore, a protocol, a boundary, a framework, a
+significant dependency. Routine or easily reversed choices do not need one.
+
+## Capture the context
+
+State the forces at the time — constraints, deadlines, team size, what was known and what was not. A
+decision that looks wrong later is usually a decision whose context was forgotten.
+
+## Name the alternatives and why they lost
+
+The options rejected carry most of the value. Without them, a future reader re-opens a question that
+was already settled for good reasons.
+
+## State the consequences honestly
+
+Record what the choice makes harder as well as what it makes easier. Acknowledged tradeoffs are what
+let someone recognize later that the tradeoff has stopped being worth it.
+
+## Supersede, never rewrite
+
+When a decision changes, write a new record that replaces the old one and leave the original intact.
+The history of decisions is itself information.

package/skills/dependency-hygiene/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: dependency-hygiene
+description: Keep the dependency graph small, current and pointing one way.
+---
+
+# Dependency hygiene
+
+Every dependency is a commitment: to its API, its release cadence and its own dependencies.
+
+## Justify each addition
+
+Prefer the standard library and existing project dependencies. Adding a package for a function you
+could write in a few lines trades a small cost now for an upgrade obligation forever.
+
+## Keep direction one way
+
+Module dependencies should form a directed acyclic graph. A cycle means the two modules are really
+one, and it blocks testing, reuse and independent change.
+
+## Depend on abstractions at boundaries
+
+Isolate third-party clients behind an interface you own so a replacement touches one place. Apply
+this where the risk is real, not to every import — an indirection layer for its own sake is cost
+without benefit.
+
+## Remove what is unused
+
+Unused dependencies still carry vulnerabilities, install time and upgrade noise. Prune them
+deliberately, since no tool will decide for you that a package is no longer wanted.
+
+## Watch the transitive graph
+
+Direct dependency count understates the real surface. Review what a package brings with it before
+adding it, and prefer libraries with a small, well-maintained tree.

package/skills/dependency-security/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: dependency-security
+description: Vet, pin and update third-party dependencies deliberately.
+---
+
+# Dependency security
+
+Most code shipped in a modern application is code nobody on the team wrote. Treat adding a dependency
+as a security decision.
+
+## Vet before adding
+
+Check maintenance activity, release history, install footprint and transitive dependency count. A
+small utility that pulls in dozens of packages costs more than writing the function yourself.
+
+## Pin and lock
+
+Commit the lockfile and keep ranges narrow for anything security relevant. Reproducible installs are
+what let you tell whether a change came from your code or from a dependency.
+
+## Update on a schedule, not in panic
+
+Apply security patches promptly and take routine updates in small regular batches. Large infrequent
+upgrades are where breakage accumulates and where an urgent patch gets stuck behind unrelated
+changes.
+
+## Audit in CI
+
+Fail the build on known critical vulnerabilities in the dependency tree. Review each advisory for
+exploitability in your context before treating it as urgent.
+
+## Beware install-time execution
+
+Post-install scripts run with your permissions on developer machines and in CI. Disable them where
+the toolchain allows, and know what remains enabled.

package/skills/deployment-safety/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: deployment-safety
+description: Release in small increments with a fast, tested way back.
+---
+
+# Deployment safety
+
+The goal is not to avoid failed deployments but to make them cheap and quickly reversible.
+
+## Deploy small and often
+
+Frequent small releases are safer than infrequent large ones. When a deployment contains one change,
+the cause of any new problem is unambiguous.
+
+## Always have a way back
+
+Know how to roll back before deploying, and test that path. A rollback procedure that has never been
+exercised is an assumption, not a plan.
+
+## Roll out progressively
+
+Expose new versions to a small share of traffic first and widen as signals stay healthy. Most
+failures appear immediately under real traffic, which no staging environment reproduces.
+
+## Separate deploy from release
+
+Ship code dark and enable it with a flag. This decouples the risk of deployment from the risk of the
+feature, and makes disabling instant.
+
+## Watch after shipping
+
+Monitor error rates, latency and business metrics through the rollout, with clear criteria for
+aborting. A deployment is not finished when it completes; it is finished when it is verified healthy.

package/skills/e2e-testing/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: e2e-testing
+description: Write end-to-end tests that are few, critical and stable.
+---
+
+# End-to-end testing
+
+End-to-end tests are the most expensive and most fragile tests in a suite. Spend them on the
+journeys that lose money or trust when they break.
+
+## Select ruthlessly
+
+Cover sign-up, authentication, payment and the core workflow of the product. Do not re-test
+validation rules or edge cases that unit tests already cover.
+
+## Wait for state, never for time
+
+Wait for the condition that proves readiness: an element, a response, a state change. Fixed sleeps
+are the primary source of both flakiness and slow suites.
+
+## Select elements by intent
+
+Target roles, labels and dedicated test identifiers. Selectors built on CSS structure or generated
+class names break on every refactor without any behavior changing.
+
+## Isolate the run
+
+Create the data each test needs and remove it afterwards. Tests that depend on a shared seeded
+environment fail unpredictably as that environment drifts.
+
+## Make failures diagnosable
+
+Capture screenshots, traces and logs on failure. An end-to-end failure without artifacts costs more
+to reproduce than to fix.

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