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.
AGENTS.md
+8 -13
View File
@@ -28,22 +28,11 @@ For changes to Common public APIs, target frameworks, packages, or shared behavi
Match the existing C# conventions: tabs, braces on new lines, top-of-file `using` directives, PascalCase public members, and established `Sacs`, `Sa`, `Sam`, and `Sax` prefixes. Follow nearby code where no repository-wide formatter rule exists. Target the framework versions declared in project files. Do not upgrade frameworks or NuGet packages unless explicitly requested.
Across all code files that support `//` line comments, use meaningful section comments instead of solid decorative comment lines. Format a section delimiter as `// --- Caption ---`, where the caption describes the code that follows, such as `Data Members`, `Construction`, `Properties`, `Test Support`, or another context-specific description. `Definitions` is appropriate where the following code declares classes, structs, interfaces, enums, or similar types. Reserve `Utilities` for internal methods that provide relatively simple supporting functionality; use a more specific caption for complex or domain-significant behavior. A delimiter may be followed by explanatory comments when useful. Surround the complete comment block with a blank line so it is visually separate from the preceding and following code; omit only the outside blank line that would otherwise appear directly after an opening brace or directly before a closing brace. Finish the file's main outer class or type block with `// --- The End ---` immediately before its closing brace. Leave nested or internal classes/types comment-free unless the type is complex enough to warrant sections and is at least 32 lines long; `// --- The End ---` is not required for such nested types. Do not add other delimiters where they do not clarify a distinct section. Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file as part of the same edit; small, isolated changes do not require unrelated wholesale reformatting.
For code files that support `//` comments, use meaningful `// --- Caption ---` section delimiters and finish the main outer type with `// --- The End ---`. Apply this to new files and significantly edited files without reformatting unrelated code. Follow the full guidance in [`docs/instructions/file-editing-conventions.md`](docs/instructions/file-editing-conventions.md).
Processes derived from `SaProcess_Base` must actively poll `IsInterrupted` during long-running loops and before expensive or blocking stages, then exit promptly when cancellation is requested.
Use Windows CRLF line endings for C# source, Visual Studio project files, configuration files, PowerShell or command scripts, and general documentation. Use LF for web assets and files commonly consumed by Unix tooling, including SVG, HTML, CSS, JavaScript, shell scripts, and YAML. Follow `.gitattributes` as the authoritative policy. Whenever a file is created or edited, normalize that file to its required line ending as part of the edit, before validation and handoff; do not defer normalization as a separate cleanup step.
New Markdown documents containing tables must include this document-level style so header and data cells are top aligned:
```html
<style>
table th,
table td {
vertical-align: top;
}
</style>
```
For Markdown tables, follow the shared style in [`docs/instructions/file-editing-conventions.md`](docs/instructions/file-editing-conventions.md). Follow the repository's formatter settings and remove imports only when demonstrably unnecessary, preserving intentional side effects. Follow this repository's `.gitattributes` for line endings and normalize each created or edited file before handoff.
## Testing Guidelines
@@ -59,6 +48,12 @@ Treat every affected Git workspace as an independent change set. Check its statu
Read `docs/topics.md` and `docs/component-reviews.md` before starting repository review or follow-up work. Update them when a conversation identifies, starts, completes, or reprioritises work, or when a component is reviewed. Follow the tracking conventions in `docs/README.md` and use ISO `YYYY-MM-DD` dates.
## Reusable Workflows and Instructions
Use `$common-dotnet-change` for Common API, framework, package, or shared-behavior changes that affect sibling consumers. Use `$common-security-change` for authentication, encryption, certificate validation, serialization, or database-query changes. Use `$maui-change` for `SacsMobileMaui` work. The shared library is indexed in [`docs/skills/INDEX.md`](docs/skills/INDEX.md); stable conventions and guidance on selecting or maintaining skills are indexed in [`docs/instructions/INDEX.md`](docs/instructions/INDEX.md). Read only the relevant skill and references for the task.
At a natural handoff (work complete, PR-ready, or review wrapping up), consider whether the conversation exposed a repeated workflow or a lasting guidance gap. If there is concrete reusable value, briefly recommend or make the in-scope skill/instruction update; do not raise one-off fixes or routine minor edits as library candidates. See [`docs/instructions/skill-lifecycle.md`](docs/instructions/skill-lifecycle.md).
## Commit & Pull Request Guidelines
Keep commits focused and use a concise imperative or clear feature/fix summary. Pull requests should describe the behavior changed, affected projects, compatibility implications, and build/test results. Note any required configuration, database, framework, or workload changes.
docs/README.md
+3
View File
@@ -10,6 +10,9 @@ An optional informational overview of sibling workspaces is available in `../../
- `component-reviews.md` records which projects, paths, and classes have been reviewed.
- `authenticated-encryption-migration.md` proposes the shared versioned authenticated-encryption design and migration sequence.
- `legacy-xamarin.md` explains how the retained Xamarin source is isolated from the supported build.
- [`skills/INDEX.md`](skills/INDEX.md) indexes repo-local reusable Codex skills under `.agents/skills/`.
- [`instructions/INDEX.md`](instructions/INDEX.md) indexes shared conventions and skill lifecycle guidance.
- [`instructions/file-editing-conventions.md`](instructions/file-editing-conventions.md) contains the shared source-comment, Markdown-table, and line-ending rules.
## Project Trackers
docs/instructions/INDEX.md
+16
View File
@@ -0,0 +1,16 @@
# Shared Instructions
This folder contains stable conventions and guidance that help people navigate the reusable skill library. Repository-specific requirements remain in each repository's `AGENTS.md`; workflow procedures belong in `.agents/skills/`.
## Instruction Groups
- [`file-editing-conventions.md`](file-editing-conventions.md) — shared source section comments, Markdown table styling, and line endings.
- [`development-conventions.md`](development-conventions.md) — cross-repository change boundaries.
- [`skill-lifecycle.md`](skill-lifecycle.md) — when to use, recommend, add, or update a skill and how to keep instructions maintainable.
## Related Indexes
- [`../skills/INDEX.md`](../skills/INDEX.md) — available Common skills.
- `../../AGENTS.md` — Common repository instructions.
Read only the guidance relevant to the current task. Do not turn this index into a requirement to load every document before every change.
docs/instructions/development-conventions.md
+9
View File
@@ -0,0 +1,9 @@
# Shared Development Conventions
Use [`file-editing-conventions.md`](file-editing-conventions.md) for source section comments, Markdown table styling, and line endings.
## Cross-Repository Boundaries
Common, BusinessMgr, Sandtrap, and Sandalwood are separate Git workspaces. Check and report each affected repository independently. Preserve sibling project-reference layout. Keep shared findings in the Common or `SacsMobileMaui` trackers and link to them from consumer trackers instead of duplicating the analysis.
The repository-owned `AGENTS.md` is authoritative for its workspace. The parent `VS2022/AGENTS.md` is an informational map only.
docs/instructions/file-editing-conventions.md
+38
View File
@@ -0,0 +1,38 @@
# File Editing Conventions
This document collects shared conventions that apply while editing source and documentation files. Each repository's `AGENTS.md` keeps a short, actionable summary; this file holds the full rules. Repository-specific instructions and `.gitattributes` remain authoritative for their own scope.
## Code Section Comments
For code files that support `//` comments, use meaningful section delimiters in the form `// --- Caption ---`, where the caption describes the code that follows. Examples include `Data Members`, `Construction`, `Properties`, `Test Support`, and `Definitions` for declarations. Reserve `Utilities` for relatively simple internal helpers; use a more specific caption for complex or domain-significant behavior. A delimiter may have explanatory comments when useful.
Separate the complete comment block from surrounding code with blank lines, except directly inside opening or closing braces. Finish the file's main outer class or type with `// --- The End ---` immediately before its closing brace. Leave nested or internal types comment-free unless they are complex and at least 32 lines long; `// --- The End ---` is not required for nested types.
Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file. Small, isolated changes do not require unrelated wholesale reformatting, and section delimiters should only mark distinct sections that improve readability.
## Markdown Tables
Every new Markdown document that contains a table must include this document-level style near the top so table headers and cells align to the top:
```html
<style>
table th,
table td {
vertical-align: top;
}
</style>
```
Preserve the style in existing Markdown documents that contain tables. Add it when a substantive edit introduces a table into a document that does not already have it.
## Formatting and Import Cleanup
Follow the repository's `.editorconfig`, solution settings, and established Visual Studio conventions where available. Use Visual Studio's formatter or the repository's approved equivalent on the changed selection or file when practical. Avoid broad formatting changes to unrelated code, and do not reformat generated, vendored, minified, or otherwise excluded files.
Remove `using` directives, imports, includes, or equivalent declarations only when they are demonstrably unnecessary. Consider language and build semantics: imports can run module initialization, load CSS or polyfills, register components, provide extension methods, or affect generated or conditional code. In JavaScript and React, preserve intentional bare side-effect imports such as CSS, polyfills, and setup modules. If an import exists only for tests, put it in test code rather than leaving a production placeholder for hypothetical future use. Keep a non-obvious intentional import only with a short comment or other clear explanation.
After cleanup, use the applicable formatter or analyzer to confirm the result where practical, and run the validation required by the affected repository and change.
## Line Endings
Follow the repository's `.gitattributes` as the authority for working-tree line endings. For file types without an explicit ending policy, preserve the file's existing convention and match nearby files; do not introduce mixed endings or normalize unrelated files. Whenever a file is created or edited, ensure that file has its required line endings before validation and handoff.
docs/instructions/skill-lifecycle.md
+21
View File
@@ -0,0 +1,21 @@
# Skill Lifecycle and Selection
## When to Use a Skill
Use a skill when its `description` matches the task and it provides a repeatable workflow, validation sequence, or domain context. Repository `AGENTS.md` files should name skills conditionally for work that needs them. Do not require unrelated skills or load every reference by default.
## When to Recommend a Skill
Recommend adding or updating reusable guidance when a task or review reveals a recurring multi-step procedure, repeated agent/user friction, a stable validation sequence, or a lasting policy gap. Prefer a focused skill over a broad catch-all. Keep always-applicable policy in the owning `AGENTS.md`; keep stable explanatory material in `docs/instructions/`; keep task workflows in a skill.
## When to Raise It in a Conversation
Check for a worthwhile library improvement at natural handoff points: when requested work is complete, a change is ready for PR review, or a PR review/merge discussion is wrapping up. Raise it briefly in the completion summary or handoff, with the proposed file and reason. Do not interrupt implementation for a speculative candidate, and do not suggest an update for a one-off fix or routine minor change. If the improvement is clearly in scope, make it and summarize it; otherwise recommend it for a follow-up.
The goal is a useful, low-noise library, not a checklist item in every conversation. A high-impact policy gap can justify one recommendation even before a pattern repeats; ordinary workflow skills should be based on demonstrated reuse.
## When to Add or Update a Skill
Create a repo-local directory at `.agents/skills/<skill-name>/` with a `SKILL.md` containing front matter `name` and a concise `description` that says both what the workflow does and when it applies. Keep the main workflow short. Put optional supporting material in `references/`, executable helpers in `scripts/`, and reusable examples/templates in `assets/`.
Update a skill when its selection conditions, required steps, validation commands, or referenced policy change. Check all links and ensure the skill does not duplicate or contradict `AGENTS.md` or an owned design record. Record significant library changes in the Common topic tracker and index.
docs/skills/INDEX.md
+13
View File
@@ -0,0 +1,13 @@
# Reusable Skills
This index describes repo-local Codex skills stored in `../.agents/skills/`. Each skill contains a `SKILL.md` manifest with its use conditions and workflow; supporting material belongs in that skill's `references/`, `scripts/`, or `assets/` folders.
## Skills
- [`common-dotnet-change`](../../.agents/skills/common-dotnet-change/SKILL.md) — for Common-VS library changes that affect BusinessMgr, Sandtrap, or Sandalwood compatibility and validation; not general .NET work.
- [`common-security-change`](../../.agents/skills/common-security-change/SKILL.md) — for security-sensitive changes in Common-VS and its listed consumers, using their owned migration records; not unrelated repositories.
- [`maui-change`](../../.agents/skills/maui-change/SKILL.md) — for `SacsMobileMaui` and its Sandtrap or Sandalwood consumers; not unrelated MAUI apps.
- [`react-structure`](../../.agents/skills/react-structure/SKILL.md) — for source-organization decisions in an existing React application, or when React source organization is explicitly requested; not feature behavior, framework selection, or build/deployment configuration.
- [`react-package-selection`](../../.agents/skills/react-package-selection/SKILL.md) — for evaluating or recommending packages for an existing React application; does not install dependencies or provide source-structure guidance. Its [package catalog](../../.agents/skills/react-package-selection/references/package-catalog.md) distinguishes the user-reported deployed stack from optional candidates.
These are initial candidates derived from existing repository guidance and review trackers. Refine them when they prove too broad, duplicate always-applicable repository policy, or lack a repeatable workflow.
docs/topics.md
+2 -1
View File
@@ -7,7 +7,7 @@ table td {
}
</style>
Last updated: 2026-10-06
Last updated: 2026-10-08
## Prioritised Topics to Be Actioned
@@ -41,6 +41,7 @@ Last updated: 2026-10-06
| Topic | Date noted | Date started | Date completed | Outcome |
|---|---|---|---|---|
| Establish initial reusable skill and instruction library | 2026-10-08 | 2026-10-08 | 2026-10-08 | Added candidate workflows for coordinated Common .NET changes, security-sensitive changes, and shared MAUI changes under `.agents/skills/`, with explicit repository and consumer scope in skill descriptions and the index. Added `react-structure` for source-organization tasks in existing React applications or when explicitly requested, and `react-package-selection` for package evaluation; indexed both and added a purpose-based package catalog that marks user-reported deployed packages as verified, separates build/test tooling from runtime dependencies, and keeps optional additions as unevaluated candidates. Added shared file-editing conventions for source comments, formatting, safe import cleanup, Markdown tables, and line endings alongside skill lifecycle instructions. Linked the indexes from Common guidance and referenced applicable workflows and instructions from BusinessMgr, Sandtrap, Sandalwood, and Saraband guidance. |
| Extract paired business object projects | 2026-10-06 | 2026-10-06 | 2026-10-06 | Created `SacsBusinessBase` and `SacsBusinessDbas` and moved the complete `CodeTypes`, `Diary`, `Interfaces`, `ItemData`, `ItemDocs`, `ItemOptions`, `ReferenceData`, `Security`, and `UpdateLog` folders. Preserved namespaces and `net10.0`; added project references to Common's CodeTypes consumer and all BusinessMgr projects that referenced the original libraries. Moved reserved-word handling to `DbUtil` to remove the StandardDbas-to-Security dependency. Common and BusinessMgr Debug builds pass; Common unit tests pass 185/185, BusinessMgr Control passes 15/15, and Portal passes 13/13. The new database project package audit reports no vulnerable packages. Sandalwood's Windows build passes. Sandtrap's Windows build still fails on `SamThreadUtil.InvokeOnMainThread`, outside this extraction. |
| Complete primary `SaProcess_Base` lifecycle protections | 2026-09-08 | 2026-09-08 | 2026-09-17 | A single lifecycle guard now rejects overlapping inline and asynchronous starts in either direction. A read-only interruption record preserves the first reason (manual request, cancellation request, or `OperationCanceledException`) until the next run resets it. `StopProcessAsync` now selects token cancellation for an asynchronous worker or a manual interruption request for an inline worker, then awaits completion. Cancellation is retained after asynchronous task-data cleanup, `OperationCanceledException` becomes cancellation rather than an error, and the async worker always runs its cleanup even if cancellation occurs before its delegate begins. Twelve focused tests cover successful execution, both overlap directions, pre-start cancellation, both stop modes, timeout retention, interruption reasons, cooperative cancellation, cancellation exceptions, and callback lock safety. No production `RunAsync()` call sites were found across Common, BusinessMgr, Sandtrap, or Sandalwood. Deferred work is limited to disposal/status semantics and derived-process cooperative polling. |
| Replace legacy CBC encryption with authenticated encryption | 2026-09-08 | 2026-09-16 | 2026-09-16 | Implemented the `SACSENC2.` AES-GCM envelope with fresh nonces, 16-byte authentication tags, and purpose-bound associated data. Removed active CBC, fixed/session IVs, legacy reads, and plaintext fallback. Retained existing in-code keys by explicit decision. Thirty focused Common tests and BusinessMgr consumer tests cover the new behavior; see [`authenticated-encryption-migration.md`](authenticated-encryption-migration.md). |