@agentyx/core 0.1.1 → 0.3.0

package/skills/angular-testing/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: angular-testing
+description: Test Angular behavior with appropriate unit, component, and E2E boundaries.
+---
+
+# Angular testing
+
+Test behavior users and callers rely on.
+
+## Scope
+
+Use plain unit tests for pure functions and services. Use component tests for rendered behavior,
+inputs, outputs, and template interaction. Use E2E tests for routing, browser integration, and
+critical user flows.
+
+## Coupling
+
+Avoid tests that depend on private fields, incidental component internals, or exact template
+structure unless that structure is the behavior. Prefer user-visible queries and meaningful state.
+
+## Modern APIs
+
+Use current Angular testing helpers and migrations for standalone components, router tests, and
+signals. Keep setup small so failures point at behavior, not ceremony.

package/skills/api-design/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: api-design
+description: Design small explicit APIs with stable contracts and useful errors.
+---
+
+# API design
+
+Treat every public function, command flag, file format, and exported type as a contract.
+
+## Surface
+
+Expose the smallest surface that solves the current need. Keep helpers private until a real caller
+appears. Avoid making implementation details part of the contract.
+
+## Behavior
+
+Make inputs, outputs, ordering, defaults, and failure modes predictable. If behavior is conditional,
+name the condition directly instead of hiding it behind a vague option.
+
+## Compatibility
+
+When changing an existing contract, look for callers, tests, generated artifacts, and docs. Decide
+whether compatibility matters for the version you are working on, then migrate the whole surface
+consistently.
+
+## Errors
+
+Errors are part of the API. Give expected failures stable types or codes, clear messages, and enough
+context for the caller to recover.

package/skills/api-documentation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: api-documentation
+description: Document interfaces so a caller can use them without reading the source.
+---
+
+# API documentation
+
+The test of interface documentation is whether someone can call it correctly on the first attempt
+without opening the implementation.
+
+## Document the contract
+
+State what the operation does, what it requires, what it guarantees, and what it does not promise.
+Behavior a caller can rely on must be written down; everything else stays free to change.
+
+## Cover errors as first-class
+
+List the failure modes, how they are signalled, and what the caller should do about each. Error
+behavior is the least documented and most needed part of any interface.
+
+## Explain the why, not the what
+
+Restating the signature in prose adds nothing. Explain constraints, units, ownership, lifetimes and
+side effects — the things the type cannot express.
+
+## Generate from the source of truth
+
+Derive reference documentation from the schema, types or annotations that define the interface.
+Hand-maintained copies drift, and a drifted reference misleads with authority.
+
+## Version and describe changes
+
+Say when behavior changed and what callers must do. Migration notes matter more than a changelog
+entry, because they tell the reader what action to take.

package/skills/aria-patterns/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: aria-patterns
+description: Apply ARIA only where native semantics fall short, and keep state accurate.
+---
+
+# ARIA patterns
+
+ARIA changes how assistive technology reports an element. It adds no behavior, so incorrect ARIA is
+worse than none.
+
+## Prefer native semantics
+
+Reach for ARIA only when no native element expresses the pattern. The first rule of ARIA is not to
+use ARIA when markup can do the job.
+
+## Keep state synchronized
+
+Expanded, selected, checked, pressed and disabled states must update whenever the visual state
+changes. Stale ARIA state describes an interface the user is no longer looking at.
+
+## Implement the whole pattern
+
+A composite widget such as a menu, tab set, combobox or dialog has an expected set of roles,
+relationships and keyboard interactions. Adopting the role without the behavior leaves the control
+unusable.
+
+## Manage focus in overlays
+
+Move focus into a dialog when it opens, keep it inside while it is open, and return it to the
+trigger on close. Content behind a modal must be inert to assistive technology as well as to
+pointers.
+
+## Announce changes sparingly
+
+Use live regions for updates the user must know about, such as errors and completions. Announcing
+everything makes the page unusable with a screen reader.

package/skills/auth-patterns/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: auth-patterns
+description: Separate authentication from authorization and enforce both server side.
+---
+
+# Authentication and authorization
+
+Authentication establishes who is calling. Authorization decides what they may do. Conflating the two
+is the most common access-control defect.
+
+## Enforce on the server
+
+Client-side checks are user experience, not security. Every request must be authorized independently
+on the server, whatever the interface already hid.
+
+## Authorize the object, not just the route
+
+Verify that the authenticated principal may act on the specific resource named in the request.
+Route-level checks that skip ownership let one user read another user's data by changing an
+identifier.
+
+## Keep sessions and tokens short
+
+Prefer short-lived tokens with refresh over long-lived credentials. Give every session an expiry, and
+support revocation for logout, password change and suspected compromise.
+
+## Store credentials correctly
+
+Hash passwords with a current memory-hard algorithm and per-user salts. Never encrypt or encode them,
+and never implement the primitive yourself.
+
+## Deny by default
+
+New endpoints require explicit authorization rather than inheriting open access. A permission model
+where forgetting a check means public access will eventually leak data.

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: brainstorming
+description: Clarify ambiguous feature work before committing to an implementation path.
+---
+
+# Brainstorming
+
+Use this before substantial ambiguous design work, not for obvious small edits.
+
+Clarify the objective, constraints, users, architecture implications, alternatives, and acceptance
+criteria. Ask only the questions that change the implementation. Once the shape is clear, summarize
+the chosen direction and the tradeoffs that matter.

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

@@ -0,0 +1,28 @@
+---
+name: code-quality
+description: Keep code clear, local, and purposeful while changing existing systems.
+---
+
+# Code quality
+
+Write code that is easy to inspect and hard to misuse.
+
+## Local fit
+
+Match naming, structure, and error-handling style already used nearby. A change should look like it
+belongs in the module that owns it.
+
+## Purposeful units
+
+Keep functions and modules small enough to understand, but do not split code just to create layers.
+Each helper should name a useful idea or remove meaningful repetition.
+
+## Noise
+
+Delete dead code. Avoid speculative options, unused parameters, and exports nobody needs. Comments
+should explain why a choice exists, not restate what the code says.
+
+## Errors
+
+Handle errors where useful context exists. Preserve the original cause when it helps debugging, and
+return or throw errors with messages a caller can act on.

package/skills/code-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: code-review
+description: Review meaningful changes for correctness, regressions, security, tests, and complexity.
+---
+
+# Code review
+
+Review the behavior first, then the shape.
+
+## Pass
+
+Check requirement compliance, correctness, regressions, security and privacy risks, test coverage,
+API compatibility, and unnecessary complexity. Use file and line references when reporting issues.
+
+## Evidence
+
+Ground findings in code paths, observable behavior, or missing checks. Separate definite bugs from
+questions and assumptions.
+
+## Output
+
+Lead with actionable findings ordered by severity. Keep summaries secondary, and say clearly when
+you found no issues.

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/concise-output/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: concise-output
+description: Communicate technical progress and results compactly without losing important details.
+---
+
+# Concise output
+
+Prefer compact professional communication.
+
+## Keep
+
+Keep commands, paths, failing errors, user-visible behavior changes, decisions that affect risk, and
+important assumptions. Be explicit for security issues, destructive actions, ambiguous instructions,
+and complex failures.
+
+## Cut
+
+Remove filler, obvious narration, repeated summaries, and progress logs that do not change the
+user's understanding. Do not restate the same status in multiple ways.
+
+## Reports
+
+Final reports should say what changed, what was verified, and what remains unverified. Use bullets
+only when they make scanning easier.

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/context-efficient-development/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: context-efficient-development
+description: Develop with targeted discovery, narrow iteration, and complete verification.
+---
+
+# Context-efficient development
+
+Save context by doing the right work in the right order.
+
+## Discovery
+
+Start with targeted search, then read the relevant symbol or range, then the containing module when
+ownership is unclear. Open whole files when needed, not by reflex. Avoid rereading code whose role
+is already understood.
+
+## Iteration
+
+Run the smallest useful command while shaping a change: one test file, one package check, one build
+step. Expand only when the touched surface grows.
+
+## Completion
+
+Before calling work complete, run the project’s required full verification for the affected surface.
+Efficiency reduces waste; it does not reduce correctness.

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/engineering-principles/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: engineering-principles
+description: Apply maintainable software-engineering judgment to non-trivial code changes.
+---
+
+# Engineering principles
+
+Use these principles as judgment, not ceremony.
+
+## Shape
+
+Prefer simple designs with explicit responsibilities. Keep related decisions close together, and
+separate code only when the boundary is real: different reasons to change, different lifetimes, or
+different owners.
+
+Favor composition when it keeps behavior visible. Inheritance, frameworks, service containers, and
+factories earn their place only when they remove concrete complexity.
+
+## Coupling
+
+Minimize what modules need to know about each other. Pass the smallest data a collaborator needs,
+return predictable results, and avoid leaking storage, transport, UI, or provider details through
+domain APIs.
+
+## Correctness
+
+Make invalid states difficult to represent. Use schemas, discriminants, required fields, and
+exhaustive checks where they clarify the model. Fail explicitly when input is invalid instead of
+silently repairing it.
+
+## Maintainability
+
+Optimize for the next person reading the code. A small amount of duplication can be cheaper than an
+abstraction that hides the important difference.