Sarand/Common-VS2019
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add reusable AI guidance and React package catalog

Browse Source
This commit is contained in:
Andy Howard
2026-10-08 15:38:46 +01:00
parent d3c5ceaf7a
commit c371877210
14 changed files with 279 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/common-dotnet-change/SKILL.md
+16
View File
@@ -0,0 +1,16 @@
---
name: common-dotnet-change
description: Coordinate compatibility and validation for Common-VS library changes affecting BusinessMgr, Sandtrap, or Sandalwood consumers; not a general .NET workflow.
---
# Common .NET Change
Use this workflow only for changes to Common-VS libraries whose compatibility or validation crosses into BusinessMgr, Sandtrap, or Sandalwood. It is not a general .NET build, package, or project-change workflow. It supplements, and does not replace, the relevant repositories' `AGENTS.md` files.
1. Read Common's `AGENTS.md`, `docs/topics.md`, and `docs/component-reviews.md`. Read the corresponding consumer guidance and trackers when a consumer is in scope.
2. Check the Git status of every affected repository before editing. Treat each repository as an independent change set and preserve unrelated work.
3. Identify the changed public surface, direct project references, target frameworks, package ownership, and in-scope consumers. Preserve relative workspace layout and public compatibility unless the task explicitly authorizes a breaking change.
4. For framework upgrades, coordinate dependency order across Common and consumers. Where an atomic move is impractical, prefer a temporary compatible target when practical, migrate consumers, then remove the old target only after no in-scope consumer needs it.
5. Build and test the directly affected Common project first. Then validate each affected consumer using its repository's standard validation entry point (`eng/validate.ps1` where available). Respect platform, workload, database, and Visual Studio tooling requirements; report unavailable validation separately from source failures.
6. If validation requirements or their scope changed, update the owning `eng/validate.ps1` and `eng/README.md`, then run the updated validation.
7. Update the relevant topic and component trackers with concrete changes and validation evidence. Do not claim broader consumer compatibility than the checks establish.
.agents/skills/common-security-change/SKILL.md
+15
View File
@@ -0,0 +1,15 @@
---
name: common-security-change
description: Review security-sensitive changes in Common-VS libraries or their BusinessMgr, Sandtrap, and Sandalwood consumers using the applicable migration records; not a general security workflow.
---
# Security-Sensitive Change
Use this workflow only for security-sensitive changes in Common-VS libraries or their BusinessMgr, Sandtrap, and Sandalwood consumers. It is not a general security checklist for unrelated repositories. Read the relevant repository `AGENTS.md` and trackers, then follow the specific design record for that component rather than treating this checklist as a substitute for it.
1. Identify sensitive data, trust boundaries, callers, persisted values, and independently deployed peers affected by the change.
2. Inspect the component's current design and migration records. For encryption, read `docs/authenticated-encryption-migration.md` and the applicable consumer inventory. Treat superseded analyses as historical, not implementation guidance.
3. Preserve fail-closed behavior. Authentication failures must not fall back to plaintext, weaker formats, or another purpose. Keep expiry, authorization, replay, and one-time-use checks explicit; encryption alone does not provide them.
4. Keep secrets, credentials, tokens, certificates, and machine-specific configuration out of source control and logs. Use environment-specific configuration as documented by the owning repository.
5. Add focused validation for both accepted and rejected cases, including malformed, tampered, wrong-purpose, and compatibility cases that the approved migration requires.
6. Validate each affected repository and consumer. Record deployment ordering, invalidated persisted data, configuration needs, and compatibility consequences in the owned tracker or design record.
.agents/skills/maui-change/SKILL.md
+15
View File
@@ -0,0 +1,15 @@
---
name: maui-change
description: Change the shared SacsMobileMaui project and validate its Sandtrap or Sandalwood consumers; not a workflow for unrelated MAUI apps.
---
# Shared SacsMobileMaui Change
Use this workflow only for `SacsMobileMaui` and its Sandtrap or Sandalwood consumers. For another MAUI application, follow that repository's own instructions.
1. Read Common's `AGENTS.md`, shared trackers, and `SacsMobileMaui/docs/README.md`, `topics.md`, and `component-reviews.md`. Read consumer guidance and trackers if an app is in scope.
2. Check status in every affected repository before editing. Keep shared-library findings in Common or `SacsMobileMaui` trackers and link to them from consumer trackers.
3. Separate platform-independent logic from MAUI and native-handler behavior where the existing design permits. Use focused ordinary NUnit tests for logic that does not require a MAUI host; use the established MAUI host for dispatcher, dialog, and UI-dependent tests.
4. Build the affected target framework and solution where the installed MAUI workloads permit. Windows can validate Windows and Android targets; Apple targets need a compatible Mac and Xcode. Report workload/runtime-pack failures separately from source errors.
5. When a shared API changes, inspect active consumer call sites and validate those consumers. Do not edit consumer repositories unless they are in the requested scope.
6. Update the MAUI and Common trackers with the tested targets, outcomes, and remaining platform limits.
.agents/skills/react-package-selection/SKILL.md
+21
View File
@@ -0,0 +1,21 @@
---
name: react-package-selection
description: Evaluate or recommend dependencies for an existing React application by purpose and project constraints; not source-structure guidance or automatic dependency installation.
---
# React Package Selection
Use this workflow when choosing, comparing, or reviewing packages for a React application. It is not a general rule to add dependencies during feature work. Keep package recommendations separate from the `react-structure` skill, which covers source organization.
1. Read the active repository's `AGENTS.md` and relevant frontend documentation. Inspect its package manifest, lockfile, package manager, React and TypeScript versions, build tool, existing dependencies, and integration constraints before suggesting additions.
2. Clarify the purpose and required capabilities. Check whether the existing stack or platform already provides them; prefer no new dependency when it meets the need.
3. Compare only packages that fit the use case. Evaluate API and React-version compatibility, maintenance and release activity, documentation, accessibility where relevant, security advisories, license, bundle/runtime cost, transitive dependencies, interoperability, testability, and migration or removal cost. Weight criteria according to the project rather than applying a universal score.
4. Verify current claims using primary sources: package and maintainer documentation, release notes or source repository, package registry metadata, and authoritative security advisories. Browse because package versions, support, and advisories change. Cite the sources for material claims and distinguish verified facts from judgment.
5. Present a concise comparison organized by purpose, with a recommendation, viable alternatives, tradeoffs, and any unresolved constraints. Do not treat downloads, stars, or familiarity alone as evidence of suitability. Avoid presenting a package as secure or actively maintained without supporting evidence.
6. Do not change manifests, lockfiles, or install packages as part of an evaluation unless the user asked for implementation. When implementation is requested, follow the repository's package-manager workflow, keep dependency changes scoped, and run its relevant validation.
## Package Catalog
Use [the React package catalog](references/package-catalog.md) as a starting register of packages reported in deployed applications and optional candidates. It is a discovery aid, not an approved stack or a substitute for project-specific evaluation. Read the catalog when a package decision overlaps its entries; recheck changing claims against current primary sources before relying on them.
Keep deployment evidence distinct from package purpose: “Verified” means the package is reported as deployed in a working application. Identify the application and evidence/provenance when known. Separate runtime packages from build, lint, and test tools that support the deployed application but are not shipped to users. Mark unevaluated alternatives “Candidate” and state the concrete use case that would justify review. Add or update entries only when there is a clear React use case; record the review date, constraints, and primary source links for recommendations. Do not turn a candidate into a default or change a project's dependencies without the user's request.
.agents/skills/react-package-selection/references/package-catalog.md
+72
View File
@@ -0,0 +1,72 @@
# React Package Catalog
Purpose-based starting register for evaluating dependencies in React applications. This is not a mandatory stack, security certification, compatibility guarantee, or approval to install packages. Use the [package selection skill](../SKILL.md) and inspect the active application's requirements and dependency versions before making a choice.
## Status and evidence
**Verified** means reported as deployed in a working application. The packages in the verified tables below were supplied by the user as a working deployed stack on 2026-10-08; that provenance is recorded here and has not been independently mapped to a specific repository, release, lockfile, or runtime. For tooling marked **Verified (toolchain)**, the package supports building, linting, or testing that application but is not shipped to end users. Neither label asserts that every package is appropriate for a different application or that a specific version remains current.
“Candidate” means an optional package to evaluate only if the described need exists. Candidate entries below were checked against the linked primary project documentation on 2026-10-08. This is a purpose check, not a full version, security, license, or maintenance audit. Recheck current evidence before adoption.
## Runtime application packages
| Purpose | Package(s) | Status and scope |
|---|---|---|
| UI rendering | `react`, `react-dom` (React 19) | **Verified** — deployed application stack; React component model and browser DOM renderer. |
| Client-side routing | `react-router-dom` (v6) | **Verified** — deployed application stack; URL-driven client navigation. |
| Server data state | `@tanstack/react-query` | **Verified** — deployed application stack; fetching, caching, synchronization, and mutations for server state. |
| HTTP transport | `axios` | **Verified** — deployed application stack; used behind the shared `authClient`. Keep authentication policy and token handling in the shared client rather than duplicating it across call sites. |
| Client/global state | `zustand` | **Verified** — deployed application stack; lightweight client-side stores. Keep server-owned cached data in its server-state layer unless a concrete need justifies duplication. |
| Realtime notifications | `@microsoft/signalr` | **Verified** — deployed application stack; SignalR client for in-app push notifications. |
| Entra ID authentication | `@azure/msal-browser` | **Verified** — deployed application stack; browser sign-in and token acquisition. Treat configuration, scopes, storage, and token flow as security-sensitive. |
| Form state and submission | `react-hook-form` | **Verified** — deployed application stack; form state and submission handling. |
| Runtime schemas and inferred types | `zod` | **Verified** — deployed application stack; schema validation and TypeScript inference. |
| Form/schema integration | `@hookform/resolvers` | **Verified** — deployed application stack; resolver bridge between React Hook Form and Zod. |
| Searchable/multi-select controls | `react-select` | **Verified** — deployed application stack; searchable and multi-select dropdowns. |
| Numeric/currency inputs | `react-number-format` | **Verified** — deployed application stack; formatting numeric entry. Verify locale, precision, and parsing behavior for each domain. |
| Colour selection | `react-color` | **Verified** — deployed application stack; colour-picker UI. |
| Component library | `react-bootstrap` | **Verified** — deployed application stack; Bootstrap-based React components. |
| Styling framework and alias isolation | `bootstrap5` alias for `bootstrap@5` | **Verified** — deployed application stack; Bootstrap 5 SCSS kept separate from Vue's Bootstrap 4. Preserve the package-manager alias and CSS scoping boundary. |
| Icons | `@fortawesome/react-fontawesome`, `@fortawesome/fontawesome-svg-core`, `@fortawesome/free-solid-svg-icons`, `@fortawesome/free-regular-svg-icons` | **Verified** — deployed application stack; React bindings, SVG core, and the listed icon sets. |
| Toast notifications | `react-toastify` | **Verified** — deployed application stack; transient notification UI. |
| Resizable layout panes | `react-resizable-panels` | **Verified** — deployed application stack; resizable split-pane layouts. |
| Conditional class names | `clsx` | **Verified** — deployed application stack; conditional CSS class composition. |
| Data tables | `@tanstack/react-table` | **Verified** — deployed application stack; headless sorting, expansion, and pagination. Supply accessible table markup and UI behavior in the application. |
| Drag and drop | `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/react` | **Verified** — deployed application stack; drag interactions and sortable lists. Keep these as separate package identities when checking compatibility. |
| Node-edge diagrams | `@xyflow/react` | **Verified** — deployed application stack; interactive entity-model and data-lineage graphs. |
| Graph layout | `elkjs` | **Verified** — deployed application stack; automatic layout for React Flow diagrams. |
| In-app diagrams | `mermaid` | **Verified** — deployed application stack; Mermaid diagrams in AI chat. |
| Code/formula/SQL editor | `react-ace`, `ace-builds` | **Verified** — deployed application stack; embedded editors for code, formulas, and SQL. |
| Markdown and GFM rendering | `react-markdown`, `remark-gfm` | **Verified** — deployed application stack; Markdown and GitHub Flavored Markdown rendering for AI chat. Apply an explicit policy for raw HTML and unsafe links. |
| Browser JSX compilation | `sucrase` | **Verified** — deployed application stack; compiles AI-generated JSX in the browser for live dashboards. Treat execution of generated code as a security boundary; compilation alone is not sandboxing. |
| HTML sanitization | `dompurify` | **Verified** — deployed application stack; sanitizes generated HTML before rendering. Keep sanitization at the final HTML trust boundary and configure allowed markup deliberately. |
| Client-side identifiers | `uuid` | **Verified** — deployed application stack; client-side ID generation. |
| Date and time | `moment` | **Verified** — deployed application stack; imported once. Treat as an established dependency, not a default for new code; assess native `Intl`/`Temporal` availability or alternatives against required parsing, timezone, and formatting behavior before migrating. |
## Build, lint, and test packages
| Purpose | Package(s) | Status and scope |
|---|---|---|
| Development server and bundler | `vite`, `@vitejs/plugin-react` | **Verified (toolchain)** — used to develop and build the deployed application; not runtime packages shipped to users. |
| Type checking | `typescript` | **Verified (toolchain)** — used in the deployed application's build/check workflow; compile-time checks do not validate untrusted runtime data. |
| TypeScript linting | `typescript-eslint` (as named in the supplied list) | **Verified (toolchain)** — reported as part of the deployed application's lint toolchain. Confirm the actual installed packages/configuration (commonly `typescript-eslint` and/or `@typescript-eslint/parser` plus `@typescript-eslint/eslint-plugin`) in the manifest and lockfile before editing. It provides ESLint support for TypeScript rather than replacing TypeScript's type checker. |
| Unit/component tests and DOM environment | `vitest`, `@testing-library/*`, `jsdom` | **Verified (toolchain)** — reported as the deployed application's test stack; dev/test dependencies, not runtime-shipped packages. The Testing Library family can include packages with different roles; inspect the manifest to identify the exact installed set. |
## Optional candidates to evaluate
These are additions to consider when the corresponding need exists. They are not reported as deployed or selected for a particular repository.
| Purpose | Candidate package(s) | Evaluate when | Primary documentation |
|---|---|---|---|
| Browser end-to-end testing | `@playwright/test` | User-critical flows need validation in real browsers, beyond unit/component tests. Compare runtime/browser requirements and CI cost with the existing test pipeline. | [Playwright documentation](https://playwright.dev/docs/intro) |
| Network/API mocking | `msw` | Component and integration tests need realistic HTTP behavior shared across tests or development; it intercepts requests without coupling mocks to Axios-specific call sites. | [MSW documentation](https://mswjs.io/docs/) |
| React rules and hook linting | `eslint-plugin-react-hooks` | The application uses ESLint and needs automated enforcement of React's Rules of Hooks and related recommendations. Check the installed ESLint and plugin versions/config format first. | [React repository plugin documentation](https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks), [React lint reference](https://react.dev/reference/eslint-plugin-react-hooks) |
| Automated accessibility checks | `axe-core` | UI tests should catch a subset of detectable accessibility issues. Treat it as an aid to, not a substitute for, keyboard, screen-reader, and manual accessibility review. | [axe-core documentation](https://github.com/dequelabs/axe-core) |
## Overlap and selection notes
- Prefer one clear owner for each kind of state. React Query and Zustand can coexist, but avoid mirroring server cache data in global client stores without a specific requirement.
- Packages in the same broad category can have distinct roles: React Hook Form manages form state, Zod validates data at runtime, and the resolver connects them. Keep the three entries together when reviewing the form stack.
- UI libraries and standalone controls (React Bootstrap, React Select, React Color, React Number Format, toast and pane components) may coexist but should be checked for visual consistency, keyboard support, bundle impact, and Bootstrap version/scoping compatibility.
- A package can appear in more than one purpose discussion when it genuinely spans roles. Keep one canonical status entry above and cross-reference it rather than duplicating conflicting verification claims.
- Reassess packages when the application changes React major version, authentication model, build/test toolchain, deployment constraints, or required accessibility support.
.agents/skills/react-structure/SKILL.md
+30
View File
@@ -0,0 +1,30 @@
---
name: react-structure
description: Choose or review source organization for an existing React application, or when React source organization is explicitly requested; not for feature behavior, framework selection, or build and deployment configuration.
---
# React Project Structure
Use this workflow only when the task concerns source organization in an existing React application, or React source organization is explicitly requested. Confirm the application from project content such as a package manifest declaring `react`/`react-dom` or existing React entry points and components. A stray dependency, documentation mention, or unrelated React file alone does not make the skill relevant.
1. Read the repository's `AGENTS.md` and relevant project documentation. Inspect the existing source tree, package scripts, routes, and import patterns before proposing moves or adding folders.
2. Keep application entry points and composition small. Use `app/` for routing, providers, and application-wide composition when those responsibilities justify the folder; retain conventional entry files such as `main.tsx` where the toolchain expects them.
3. Group cohesive UI and behavior by domain under `features/<feature>/`. Place components, hooks, feature API calls, types, and styles together when they belong to that feature; do not create empty or speculative subfolders.
4. Put code in `shared/` only when it is genuinely used across features or represents application-wide infrastructure such as HTTP clients. Avoid moving code there merely because it is not page-specific.
5. Keep shared assets and other cross-feature resources in an appropriate shared location. Prefer clear ownership and a small number of meaningful boundaries over a folder for every file or technical layer.
6. When restructuring, preserve observable behavior, routing, imports, and intentional side-effect imports such as CSS and polyfills. Update references consistently and avoid unrelated feature changes.
7. Validate with the repository's applicable type-check, tests, lint, and build scripts. Follow the owning repository's instructions for development-server, host integration, and deployment checks rather than inventing generic commands.
An optional starting shape is:
```text
src/
├── app/ # routes, providers, and application composition, if needed
├── features/
│ └── <feature>/ # cohesive feature UI and behavior
├── shared/ # cross-feature UI and infrastructure
├── assets/ # shared source assets, if needed
└── main.tsx # toolchain entry point
```
Adapt this to the current application and its scale; it is a starting point, not a required scaffold.