trackfw 3.0.0 → 4.0.0

package/src/integrations/assets/skills/data.md

@@ -0,0 +1,75 @@
+---
+name: trackfw-data-skill
+description: Data pipelines, quality contracts, lakehouse patterns and MLOps.
+---
+
+## Pipeline Design Principles
+
+- **Idempotent**: running a pipeline twice with the same inputs produces the same outputs with
+  no side effects. Idempotency enables safe retries and backfills.
+- **Observable**: every pipeline run emits metrics (rows processed, duration, error count)
+  and structured logs. Silent pipelines hide data quality problems.
+- **Incremental by default**: process only new or changed data; full reloads are expensive and
+  error-prone. Implement watermark or change-data-capture (CDC) patterns.
+- **Testable**: test transformations with deterministic fixtures. A pipeline that cannot be
+  run locally with sample data is hard to debug.
+
+## Data Contracts
+
+A data contract is a versioned schema agreement between a data producer and its consumers.
+Breaking schema changes require a new contract version and a migration window:
+- Define contracts before building pipelines, not after.
+- Validate incoming data against the contract on ingestion; reject or quarantine violations.
+- Version schemas explicitly (SemVer or a sequential version field).
+- Treat a schema change that breaks downstream consumers as a breaking change — the same way
+  an API breaking change is treated.
+
+## ELT / Transformation
+
+- Prefer ELT (Extract, Load, Transform) over ETL when the target system can handle the
+  transformation cost; push compute to where the data lives.
+- SQL transformations with dbt are version-controlled, testable and self-documenting.
+- Model data in layers: raw (landing, immutable), staged (typed, deduplicated), marts
+  (business-aligned aggregations). Never query raw data directly in reports.
+- Materialized models for expensive aggregations; incremental models for large tables.
+
+## Streaming and Real-Time
+
+- Use a durable, partitioned log (Kafka, Pulsar) for event streaming; producers and consumers
+  are decoupled in time and scale independently.
+- Guarantee semantics: at-least-once is the safe default; exactly-once requires coordinated
+  transactions between the broker and the sink.
+- Windowing functions (tumbling, sliding, session) for time-based aggregations in stream
+  processing.
+- Monitor consumer lag continuously; unprocessed lag accumulation is an early warning of
+  a performance or capacity problem.
+
+## Data Quality
+
+- Data quality checks belong in the pipeline, not in the dashboard. Fail fast, fail clearly.
+- Test categories: **schema** (types, nullability, column existence), **integrity** (referential
+  keys, uniqueness), **freshness** (last-updated within expected window), **statistical**
+  (distribution drift, unexpected nulls or zeros).
+- Quarantine rows that fail quality checks rather than silently dropping them; dropped rows
+  hide data completeness problems.
+- SLA: define freshness and completeness SLAs per dataset; alert on SLA breach, not on
+  arbitrary thresholds.
+
+## Lakehouse and Storage
+
+- Store raw data in an open, columnar format (Parquet) in object storage; this decouples
+  compute from storage and avoids vendor lock-in.
+- Table formats (Delta Lake, Apache Iceberg) add ACID transactions, schema evolution and
+  time travel to object storage. Use them for tables that require updates or deletes.
+- Partition large tables by a time dimension and a high-cardinality business key to enable
+  efficient pruning.
+
+## MLOps
+
+- Feature stores decouple feature engineering from model training; online serving and offline
+  training use the same feature definitions (point-in-time correctness).
+- Track every experiment: hyperparameters, dataset version, metrics, artifact location.
+  Reproducibility requires logging, not memory.
+- Model deployment is a software deployment: versioned, tested, monitored, rollback-capable.
+- Monitor model performance in production: data drift, prediction drift, and business metric
+  correlation. Retraining triggers are defined by drift thresholds, not by calendar.

package/src/integrations/assets/skills/dba.md

@@ -0,0 +1,77 @@
+---
+name: trackfw-dba-skill
+description: Database modeling, query optimization, high availability and vector data patterns.
+---
+
+## Modeling
+
+Choose the data model based on access patterns, not familiarity:
+- **Relational (SQL)**: normalized schemas, foreign key integrity, ACID transactions. Best when
+  relationships are complex and consistency is paramount.
+- **Document**: flexible schema for hierarchical, polymorphic data. Beware of embedding without
+  considering update patterns.
+- **Key-Value / Wide-Column**: for high-throughput reads/writes with simple access patterns.
+  Design the key structure before creating the table — it cannot be changed cheaply.
+- **Graph**: for highly connected data where traversal depth and relationship types vary.
+
+Model for queries, not for purity. A schema that cannot be queried efficiently without
+full-table scans has the wrong design.
+
+## Indexing
+
+- Create indexes to support the actual query patterns in the application; unused indexes
+  consume write overhead and space.
+- Composite indexes: column order matters. The most selective column first, then the columns
+  used in equality filters, then range predicates.
+- Partial indexes (filtered indexes) reduce index size and improve write throughput when a
+  significant fraction of rows never appear in queries.
+- Validate index usage with execution plans (`EXPLAIN ANALYZE`); an index that the optimizer
+  ignores is waste.
+
+## Query Optimization
+
+- Read the execution plan for every slow query; identify table scans, nested loops and
+  sort operations that could be eliminated.
+- Avoid `SELECT *`; project only the columns the application uses.
+- Parameterize queries; never concatenate user input into SQL strings.
+- Push filters as early as possible in query pipelines (aggregations, joins).
+- Analyze and update table statistics regularly; stale statistics cause bad query plans.
+
+## High Availability and Replication
+
+- Define RTO and RPO per service tier before choosing an HA architecture.
+- Read replicas for read-heavy workloads; route analytics queries away from the primary.
+- Point-in-time recovery (PITR) is mandatory for production databases.
+- Test backup restoration on a schedule; a backup that has never been restored is
+  unverified and therefore unreliable.
+- Cross-region replication for disaster recovery; understand replication lag and its
+  impact on read-after-write consistency.
+
+## Cache Integration
+
+- **Cache-aside**: application reads from cache; on miss, reads from database and populates
+  cache. Simple and explicit. Handles cache invalidation at write time.
+- **Write-through**: write to both cache and database atomically. Keeps cache consistent at
+  the cost of write latency.
+- Set TTLs on every cache entry; unbounded cache growth leads to eviction unpredictability.
+- Cache only safe data (no PII without appropriate controls); audit what is cached.
+
+## Vector Databases
+
+For AI/ML retrieval workloads:
+- **Index choice**: HNSW (Hierarchical Navigable Small World) for low-latency ANN search;
+  IVFFlat for higher-recall bulk workloads.
+- **Hybrid search**: combine dense vector search with sparse (BM25) text search using
+  Reciprocal Rank Fusion (RRF). Pure dense search underperforms on keyword-heavy queries.
+- **Reranking**: apply a cross-encoder reranker after initial retrieval to improve top-k
+  precision without the cost of reranking the full corpus.
+- Match the embedding model dimensionality to the index; switching models requires
+  re-embedding the entire corpus.
+
+## Analytics and Columnar Storage
+
+- Columnar engines (ClickHouse, DuckDB, BigQuery) are optimized for aggregations over a
+  subset of columns in large tables; do not use them for OLTP row-level operations.
+- Materialized views pre-aggregate expensive queries; refresh strategy (incremental vs full)
+  depends on freshness requirements and write volume.
+- Partition large tables by time or a high-cardinality dimension to enable partition pruning.

package/src/integrations/assets/skills/frontend.md

@@ -0,0 +1,70 @@
+---
+name: trackfw-frontend-skill
+description: Accessible, performant and internationalizable user interfaces.
+---
+
+## Core Principles
+
+- **Web-first**: design for the browser platform first; native equivalents are additive.
+- **Progressive enhancement**: core functionality works without JavaScript; enhancements layer on top.
+- **Accessibility is not optional**: WCAG 2.2 AA is the minimum bar for every user-facing interface.
+- **Performance is a feature**: Core Web Vitals (LCP < 2.5 s, CLS < 0.1, INP < 200 ms) are
+  production quality gates, not post-launch concerns.
+
+## Component Architecture
+
+Build components at the atomic level (atoms → molecules → organisms → pages). Each component
+has a single, well-defined responsibility. Compose, do not inherit.
+
+Separate concerns clearly:
+- **Data fetching** lives outside components (query layer, data hooks, server components).
+- **State** is as local as possible; lift only when two components genuinely share it.
+- **UI logic** stays in the component; business rules belong in services or server-side code.
+
+## Accessibility (WCAG 2.2 AA)
+
+- Use semantic HTML as the foundation; ARIA supplements, never replaces, semantics.
+- Every interactive element is keyboard-navigable with a visible focus indicator.
+- Color contrast ratio ≥ 4.5:1 for normal text, ≥ 3:1 for large text.
+- Support `prefers-reduced-motion`; do not auto-play animations.
+- Test with at least one screen reader (VoiceOver, NVDA) during development.
+- Integrate `axe-core` in CI to catch regressions automatically.
+
+## Performance
+
+- Lazy-load routes and heavy components; code-split at meaningful boundaries.
+- Optimize images: responsive sizes, modern formats (WebP/AVIF), explicit `width` and `height`
+  to avoid layout shift.
+- Virtual scrolling for lists with more than a few hundred items.
+- Monitor performance budgets in CI with Lighthouse; fail the build on regressions.
+
+## Internationalisation (i18n)
+
+- Externalize all user-visible strings at the start; retrofitting is expensive.
+- Use ICU message format for pluralization and gender rules.
+- RTL layout support requires logical CSS properties (`margin-inline-start` over `margin-left`).
+- Locale-aware date, number and currency formatting — never hand-roll these.
+
+## State Management
+
+Choose the simplest state model that fits the problem:
+- Local component state for ephemeral UI.
+- Server-state cache (e.g., query libraries with stale-while-revalidate) for remote data.
+- Client-side global state only when truly shared across unrelated subtrees.
+- Finite state machines for complex multi-step flows to make impossible states impossible.
+
+## Testing
+
+- Web-first assertions: assert on visible state and accessibility, not internal implementation.
+- Do not use `waitForTimeout`; await stable DOM state or network idle instead.
+- Component tests verify rendered output and user interactions (click, type, submit).
+- E2E tests cover critical paths with real browser automation (Playwright).
+- Visual regression for design-system components.
+
+## Design Systems
+
+- Design tokens (W3C DTCG format) are the single source of truth for spacing, color and
+  typography. Tokens propagate to both design tools and code.
+- Document components in isolation; a component that cannot be demonstrated in isolation
+  is too tightly coupled.
+- Maintain a clear Figma → dev handoff contract; use Dev Mode or equivalent tooling.

package/src/integrations/assets/skills/iac.md

@@ -0,0 +1,90 @@
+---
+name: trackfw-iac-skill
+description: Declarative infrastructure provisioning, state management, policy-as-code and immutability.
+---
+
+## Foundational Principles
+
+Infrastructure as Code means the repository is the authoritative source of truth for every
+provisioned resource. If it is not in code, it does not officially exist.
+
+- **Declarative over imperative**: describe the desired end state; let the tool reconcile.
+- **Idempotent by design**: applying the same configuration twice must produce the same result.
+- **Immutable infrastructure**: replace, do not patch. Mutable drift between nodes is a source
+  of undocumented operational risk.
+- **Least privilege**: every resource receives the minimum permissions required, nothing more.
+  Wildcard actions combined with wildcard resources are forbidden.
+
+## File and Module Structure
+
+Organize files by concern, not by resource count. In Terraform/OpenTofu:
+
+```
+infra/<environment>/
+├── main.tf       # primary resources
+├── variables.tf  # typed, described, validated inputs
+├── outputs.tf    # values consumed by other configurations
+├── versions.tf   # required_version and required_providers (pinned)
+├── locals.tf     # computed values, naming conventions, shared tags
+└── data.tf       # data sources, separate from managed resources
+```
+
+Never put everything in `main.tf`. One file per concern makes diffs reviewable and
+`terraform plan` output readable.
+
+Module decisions:
+- Create a local module when a pattern repeats three or more times in the same project.
+- Prefer a well-maintained registry module over a custom one for complex resources.
+- Always pin module versions: `version = "~> 4.0"`. Unpinned modules are a supply-chain risk.
+
+## State Management
+
+Remote state is mandatory for team and production environments:
+- Store in a managed backend with encryption at rest and distributed locking.
+- Never commit `terraform.tfstate` or `*.tfvars` containing secrets.
+- Use workspaces or separate state files per environment; mixing environments in a single
+  state file is an operational hazard.
+- Enable state file backup and versioning on the storage backend.
+
+## Plan, Review and Apply
+
+```
+1. terraform fmt -check -recursive   # style
+2. terraform validate                 # syntax and provider schema
+3. policy-as-code scan (Checkov, Trivy config)  # security gates
+4. cost estimation (Infracost)        # visibility before apply
+5. terraform plan -out=plan.tfplan    # deterministic plan
+6. human review of plan               # mandatory for production
+7. terraform apply plan.tfplan        # apply the reviewed plan
+```
+
+**Never apply to production without a reviewed, saved plan.** Ad-hoc `terraform apply` in
+production bypasses the review gate and defeats reproducibility.
+
+## Policy-as-Code
+
+Automated policy checks run before `apply`, not after:
+- Reject resources with encryption disabled (storage, databases, secrets).
+- Reject IAM policies with `"*"` on both action and resource simultaneously.
+- Require mandatory tags (environment, team, cost-centre) on all taggable resources.
+- Enforce minimum TLS versions and private endpoint requirements.
+- HIGH and CRITICAL policy violations block the pipeline; they are not warnings.
+
+## Configuration Management (Ansible)
+
+- Every task must be idempotent: running the playbook twice must not change the system on the
+  second run.
+- Use `no_log: true` on every task that handles secrets or credentials.
+- Store secrets in a secrets manager or vault; never in playbook variables or inventory files.
+- Use dynamic inventory sources; never hardcode hostnames or IP addresses.
+- Name every task descriptively; unnamed tasks make failure logs unreadable.
+
+## Anti-Patterns
+
+The following are always wrong:
+- `apply` in production without a human-reviewed plan.
+- Secrets in `.tfvars`, environment variables without a secrets manager, or hardcoded values.
+- `"*"` in both `actions` and `resources` of an IAM statement.
+- Unpinned module or provider versions.
+- `null_resource` or `local-exec` for business logic that a provider resource can handle.
+- Manual changes to resources managed by IaC (infrastructure drift).

package/src/integrations/assets/skills/infra.md

@@ -0,0 +1,62 @@
+---
+name: trackfw-infra-skill
+description: Cloud platforms, Kubernetes operations, CI/CD, observability and reliability.
+---
+
+## Kubernetes Operations
+
+- GitOps is the source of truth: cluster state is declared in a repository and reconciled
+  continuously by a controller (ArgoCD, Flux). Manual `kubectl apply` in production is an
+  anti-pattern.
+- Use readiness and liveness probes on every workload; tune them to reflect actual service
+  health, not just process health.
+- Resource requests and limits are mandatory; workloads without them destabilize the
+  node's QoS. Rightsize with Vertical Pod Autoscaler metrics, not guesses.
+- RBAC: least privilege per ServiceAccount. Never use the `cluster-admin` role for workloads.
+- Pod Security Standards (restricted profile) as the default; relax per workload only with
+  documented justification.
+
+## CI/CD
+
+- Pipelines are code: version-controlled, reviewable, tested.
+- Use environment-specific deployment gates; production deployments require explicit approval.
+- Separate build from deploy: the same artifact that passed staging is promoted to production
+  (immutable artifact principle).
+- Reusable workflows reduce duplication; extract common steps (lint, test, scan, notify).
+- Dependency scanning and container image scanning run on every PR, not only on schedule.
+
+## Observability
+
+Instrument with OpenTelemetry as the vendor-neutral standard:
+- **Metrics**: RED method (Rate, Errors, Duration) for services; USE method (Utilization,
+  Saturation, Errors) for resources.
+- **Traces**: distributed trace context propagates across all service calls; sample based on
+  latency or error, not uniformly.
+- **Logs**: structured JSON to stdout; correlate with trace ID.
+- Define SLOs and error budgets before an incident, not during.
+- Golden signals dashboard is the first screen in any incident response.
+
+## Reliability
+
+- Chaos engineering (controlled failure injection) validates reliability assumptions before
+  production incidents do. Start with single-node failures, then dependency outages.
+- Disaster recovery: define RTO and RPO per service tier; test backup restoration on schedule
+  — untested backups are not backups.
+- Multi-AZ for stateful workloads; cross-region only where business continuity justifies cost.
+- Circuit breakers at the service mesh layer protect downstream services from cascading failures.
+
+## Cloud Cost Optimization (FinOps)
+
+- Tag every resource with team, environment and cost centre at provisioning time; retroactive
+  tagging is never complete.
+- Spot/preemptible instances for stateless, fault-tolerant workloads; reserved capacity for
+  predictable baseline load.
+- Rightsizing is a continuous process; review monthly, not quarterly.
+- Cost visibility per team is a prerequisite for accountability.
+
+## Supply Chain Security
+
+- Sign container images with Sigstore/Cosign; verify signatures in admission controllers.
+- Generate SBOM (CycloneDX or SPDX) on every build; store alongside the artifact.
+- Pin base image digests, not tags; floating tags introduce silent updates.
+- Scan dependencies for known CVEs at build time and on a regular schedule.

package/src/integrations/assets/skills/qa.md

@@ -0,0 +1,63 @@
+---
+name: trackfw-qa-skill
+description: Automated testing, quality gates, contract verification and coverage strategy.
+---
+
+## Test Pyramid
+
+Maintain a healthy ratio: approximately 70% unit tests, 20% integration tests, 10% E2E tests.
+Unit tests give fast, precise feedback. Integration tests verify component boundaries and
+database behaviour with real infrastructure. E2E tests cover critical user journeys end-to-end.
+
+Deviating from the pyramid is a deliberate trade-off — document the reason.
+
+## E2E Testing Principles
+
+- **Web-first assertions**: assert on stable, observable state (element visible, text present,
+  URL changed) — never `waitForTimeout`, which is fragile and masks real timing issues.
+- **Cross-browser matrix**: test Chromium, Firefox and WebKit; sharding keeps CI fast.
+- **Real authentication**: use actual credentials stored in `storageState`; mock auth hides
+  permission bugs and token expiry issues that appear in production.
+- **Trace on failure**: attach Playwright trace files to CI artifacts for deterministic replay.
+- **Visual regression**: snapshot tests for design-system components; fail the PR on visual drift.
+
+## Integration Testing
+
+- Integration tests must hit a real database (via Testcontainers or an equivalent ephemeral
+  service). Mocked repositories hide driver/migration mismatches that cause production failures.
+- Seed deterministic fixtures; avoid shared state between tests — parallel runs must not collide.
+
+## Contract Testing
+
+API contracts are a team boundary. Use schema-driven contract testing (e.g., Pact for
+consumer-driven contracts, Spectral for OpenAPI lint) to catch breaking changes before
+deployment, not after.
+
+## Quality Gates
+
+- Coverage thresholds enforced in CI (service layer ≥ 85%); fail the build on regression.
+- Mutation testing score ≥ 80%: a test suite that does not kill mutations gives false
+  confidence.
+- Flaky tests are quarantined immediately; a test with stability score < 95% is either fixed
+  or removed. Flaky tests erode trust in the entire suite.
+- SonarQube or equivalent quality gate on every PR: coverage, duplication, critical issues.
+
+## Bug Hunting
+
+A bug report is only complete when it includes:
+1. Deterministic reproduction steps.
+2. Expected vs. actual behaviour.
+3. Environment (OS, browser, version, test data).
+
+Root-cause analysis must produce a regression test that would have caught the bug before
+it reached production. Fix the test pyramid root cause, not just the symptom.
+
+## Accessibility in QA
+
+Integrate accessibility checks (`axe-core`, Lighthouse a11y) in CI. A WCAG 2.2 AA violation
+is a defect with the same severity as a functional bug.
+
+## Performance Budgets
+
+Define Lighthouse performance budgets per route: LCP, CLS, INP thresholds. Run Lighthouse CI
+on every PR targeting main; block merge on regression.

package/src/integrations/assets/skills/security.md

@@ -0,0 +1,74 @@
+---
+name: trackfw-security-skill
+description: Threat modeling, DevSecOps controls, Zero Trust and supply chain security.
+---
+
+## Shift-Left Security
+
+Security controls belong in the development pipeline, not only at the perimeter. The later a
+vulnerability is found, the more expensive it is to fix.
+
+CI pipeline mandatory gates:
+- **SAST** (Static Application Security Testing): scan source code on every PR.
+- **SCA** (Software Composition Analysis): identify vulnerable dependencies; block on HIGH/CRITICAL.
+- **Secrets scanning**: detect committed credentials before they reach the repository.
+- **Container image scanning**: scan base images and final images; fail on HIGH/CRITICAL CVEs.
+- **IaC security**: scan Terraform, Helm and Kubernetes manifests for misconfigurations.
+
+## Threat Modeling
+
+Model threats before writing code for any new feature that handles authentication, authorisation,
+data storage or external integrations. Use STRIDE as the baseline framework:
+
+| Threat | Example |
+|---|---|
+| Spoofing | Forged identity or token |
+| Tampering | Modified request payload |
+| Repudiation | Missing audit trail |
+| Information Disclosure | Over-permissive API response |
+| Denial of Service | Unbounded resource consumption |
+| Elevation of Privilege | Broken access control |
+
+Validate findings against OWASP Top 10 and ASVS (Application Security Verification Standard)
+at the appropriate assurance level for the feature.
+
+## Zero Trust Architecture
+
+- **Never trust, always verify**: authenticate and authorize every request, regardless of network
+  origin. Internal services are not implicitly trusted.
+- **mTLS** between services in a mesh: mutual authentication proves both sides hold valid certificates.
+- **Least privilege at every layer**: IAM roles, Kubernetes RBAC, database users — minimum
+  permissions for the task, nothing more.
+- **JIT (Just-in-Time) access**: elevate privilege for a bounded time window for administrative
+  tasks; revoke automatically.
+
+## Identity and Access Management
+
+- OAuth 2.0 with PKCE for public clients; validate `iss`, `aud` and `exp` on every JWT.
+- RBAC for coarse-grained access; ABAC for attribute-based decisions.
+- Rotate credentials on schedule and on any suspicion of compromise.
+- Secrets management: use a dedicated secrets manager; never hardcode secrets in code,
+  configuration files or environment variables committed to a repository.
+
+## Supply Chain Security
+
+- Generate an SBOM (Software Bill of Materials) in CycloneDX or SPDX format on every build.
+- Sign artifacts and container images (Sigstore/Cosign); verify signatures in admission
+  controllers before deploying to production.
+- Pin dependency versions; review updates in PRs, not silently via floating ranges.
+- Monitor for newly published CVEs against your SBOM continuously, not just at build time.
+
+## API Security
+
+Design APIs with OWASP API Security Top 10 in mind:
+- Broken Object Level Authorization (BOLA) is the most common API vulnerability — validate
+  that the caller has access to the specific object, not just the endpoint.
+- Rate-limiting and input validation are required on every public endpoint.
+- Avoid exposing internal IDs directly; prefer opaque tokens or UUIDs.
+
+## Incident Readiness
+
+- Centralise logs and security events in a SIEM; define alerting thresholds before incidents occur.
+- Maintain and rehearse an incident response playbook; detection-to-containment time (MTTC)
+  is the metric that matters.
+- Conduct a post-incident review (PIR) after every significant security event; update controls.

package/src/integrations/assets/skills/tooling.md

@@ -0,0 +1,80 @@
+---
+name: trackfw-tooling-skill
+description: AI agent design, skill composition, MCP configuration and context economy.
+---
+
+## Agent Design Principles
+
+An agent is effective when its scope, tools and constraints are explicit. Vague instructions
+produce vague behaviour:
+- **Lock the role**: every agent declares its role at the top of its system prompt and does
+  not switch roles mid-session without an explicit handoff.
+- **Declare tools explicitly**: list only the tools the agent needs for its role; an agent
+  with write access that only needs to read is a liability.
+- **Explicit memory scope**: use project-scoped memory for context that belongs to the
+  repository; use global memory only for cross-project preferences.
+- **Restrict scope**: an agent must know what it is forbidden to do (create branches, open PRs,
+  modify configuration outside its domain). Prohibitions are as important as permissions.
+
+## Skill Design
+
+Skills extend agents with domain expertise loaded on demand:
+- **Single responsibility**: one skill per role or domain. A skill that covers both backend
+  and frontend is too broad to be useful without loading the entire file.
+- **Stack-agnostic content**: skills contain principles, patterns and vocabulary that define
+  the role. Stack-specific choices (library names, project configuration) belong in the
+  project's CLAUDE.md, not in a shared skill.
+- **Right size**: 40–90 lines is the target. A 5-line skill teaches nothing; a 300-line
+  skill inflates context on every invocation. Prefer principles over tool lists.
+- **Load on demand**: skills are not always loaded. Design them as self-contained documents
+  that provide value when read in isolation, without assuming other skills are present.
+
+## MCP (Model Context Protocol)
+
+MCP enables agents to interact with external tools and services through a standardised protocol:
+- Define tool schemas precisely: name, description, input schema, output schema.
+- Group related tools in a tool set to reduce context size when only a subset is needed.
+- Prefer tool sets over individual tool registrations when the agent needs more than five tools.
+- Validate MCP server responses before acting on them; a malformed response must not
+  silently corrupt state.
+- Document which MCP servers a configuration depends on; an agent that fails silently because
+  a server is unavailable is hard to debug.
+
+## Prompt Engineering
+
+- **Specificity over length**: a short, specific prompt outperforms a long, vague one.
+  Remove filler instructions that repeat the model's defaults.
+- **Reusable prompt files**: extract repeated prompt patterns into versioned, reviewable files.
+  Treat prompts as code: they have bugs, they drift, they need tests.
+- **Context economy**: every token in context is a cost. Load only the context that is
+  relevant to the current task. Unload when done.
+- **Structured output**: when the downstream consumer is code (not a human), request JSON
+  or a defined schema. Freeform prose is hard to parse reliably.
+
+## Validating Recommendations
+
+Before recommending a tool, configuration option, or API:
+1. Check the official documentation for the current version.
+2. Verify that the feature or flag exists in the version the project is using.
+3. Test in a minimal example before including in a recommendation.
+
+A memory that says "feature X exists" is not the same as "feature X exists now." Models have
+knowledge cutoffs; documentation does not. When in doubt, read the source.
+
+## Human-in-the-Loop
+
+Define checkpoints where human review is mandatory:
+- Irreversible operations (production deploys, data deletions, secret rotation).
+- Operations with significant blast radius (schema migrations, dependency upgrades).
+- Decisions that bifurcate the architecture (new service boundary, new data model).
+
+Agents that can proceed without human input should declare that capability explicitly in their
+design. Agents that are uncertain must ask, not guess.
+
+## Observability for AI Systems
+
+- Log prompts, tool calls, token counts and latency for every agent interaction in production.
+- Monitor for response quality drift: a pipeline that produces correct output today may not
+  produce correct output after a model update.
+- Evaluation datasets: maintain a set of representative inputs with expected outputs; run
+  them on every model or prompt change.

package/src/integrations/assets/skills/ux.md

@@ -0,0 +1,70 @@
+---
+name: trackfw-ux-skill
+description: User-centred design, design systems, accessibility and usability validation.
+---
+
+## User-Centred Design
+
+Design starts with understanding users, not with wireframes. Before sketching, establish:
+- **Who** are the users? (personas, JTBD — Jobs to Be Done)
+- **What** are they trying to accomplish? (user journey, task analysis)
+- **Where** does the current experience fail? (pain points, drop-off analysis)
+
+Design Thinking cycle: Empathize → Define → Ideate → Prototype → Test. The cycle is
+iterative; return to earlier phases when testing invalidates assumptions.
+
+## Prototyping
+
+Prototypes are for learning, not for pride. Build the cheapest prototype that can answer the
+design question:
+- **Low-fidelity** (sketch, wireframe): validates information architecture and flow.
+- **High-fidelity** (interactive prototype): validates micro-interactions and visual language.
+- **Discardable prototypes**: isolated from production code; exist to prove a concept, not
+  to ship. Remove them before the production implementation goes to review.
+
+## Accessibility (WCAG 2.2 AA Minimum)
+
+Accessibility is a legal requirement in many jurisdictions and a quality attribute in all:
+- Color contrast ≥ 4.5:1 for body text; ≥ 3:1 for large text and UI components.
+- All interactive elements are keyboard-operable with a visible focus indicator.
+- ARIA landmarks structure the page for assistive technology; do not use ARIA to override
+  broken semantics — fix the semantics first.
+- `prefers-reduced-motion`: disable or reduce animations for users who opt out.
+- Every form field has a programmatically associated label.
+- Test with a real screen reader; automated tools (axe-core) catch ~30–40% of issues.
+
+## Usability Heuristics
+
+Apply Nielsen's 10 heuristics as a review lens, not a checklist:
+- **Visibility of system status**: users always know what is happening.
+- **Match with the real world**: language and concepts match the user's mental model.
+- **User control and freedom**: support undo and clear exit paths.
+- **Consistency**: same words, same icons, same placement across the product.
+- **Error prevention**: design to make errors impossible before handling them gracefully.
+
+## Design Systems
+
+A design system is a product that serves the product team:
+- **Design tokens** (W3C DTCG format): spacing, colour, typography as named variables.
+  Tokens are the contract between design and code.
+- **Atomic Design**: atoms (button, input) → molecules (form field) → organisms (card) →
+  templates → pages. Each level composes from the level below.
+- Document components in isolation with rendered examples, props API and accessibility notes.
+- A component that cannot be demonstrated without application context is too tightly coupled.
+
+## Validation and Metrics
+
+A design is a hypothesis until tested with users:
+- **A/B testing**: one variable, measurable success criterion, sufficient sample size.
+  Do not run experiments without a pre-registered hypothesis.
+- **Usability testing**: five users reveal the majority of critical usability problems.
+  Recruit from the actual target audience, not convenience.
+- **Quantitative signals**: task completion rate, time on task, error rate, NPS/CSAT.
+- **Qualitative signals**: think-aloud sessions, session replays, support ticket themes.
+
+## Responsive and Adaptive Design
+
+- Mobile-first: design and test the constrained layout first; expand to wider viewports.
+- Touch targets ≥ 48 dp (CSS equivalent) for all interactive elements on touch surfaces.
+- Fluid typography with `clamp()` to eliminate breakpoint-driven font size jumps.
+- Content-driven breakpoints, not device-driven; break where the layout breaks.