Refine FieldWorks AI review workflows (#905)

* Add CONTEXT.md to integrate grill-with-docs into planning/OpenSpec flows so ambiguous repo language is clarified before proposal/spec/design/task artifacts are written
* Add experimental AI PR workflow docs and prompts; introduce pr-preflight and
respond-to-review-comments skills; update repo guidance and templates.

---------

Co-authored-by: Jason Naylor <jason_naylor@sil.org>

Author: johnml1135

.github/context/codebase.context.md

@@ -2,8 +2,11 @@
 
 Use these entry points to load context efficiently without scanning the entire repo.
 
-- Onboarding: `.github/AGENTS.md`
+- Shared language and glossary: `CONTEXT.md`
+- Onboarding (canonical anchor): `.github/AGENTS.md`
 - Src catalog (overview of major folders): `.github/src-catalog.md`
+- AI review workflow: `grill-with-docs` for planning language, `.github/instructions/review-analyzer.instructions.md` for review policy, `pr-preflight` for branch/PR readiness, and `respond-to-review-comments` for reviewer feedback.
+- Specialist review agents: `.github/agents/fieldworks.csharp-expert.agent.md`, `.github/agents/fieldworks.winforms-expert.agent.md`, `.github/agents/fieldworks.cpp-expert.agent.md`, and `.github/agents/fieldworks.avalonia-expert.agent.md`.
 - Component guides: `Src/<Folder>/AGENTS.md` (and subfolder AGENTS.md where present)
 - Build system: `build.ps1`, `FieldWorks.proj`, `FieldWorks.sln`, `Build/InstallerBuild.proj`
 - Installer: `FLExInstaller/`
@@ -15,4 +18,4 @@ Use these entry points to load context efficiently without scanning the entire r
 Tips
 - Prefer top-level scripts or FieldWorks.sln over ad-hoc project builds
 - Respect CI checks (commit messages, whitespace) before pushing
-
+- Prefer FieldWorks-specific agents over generic language/framework agents when reviewing this repo

.github/copilot-instructions.md

@@ -16,8 +16,9 @@ desktop application.
   validation, encoding assumptions, buffer lengths, and ownership rules.
 - Verify user-visible UI strings are placed in `.resx` resources and remain
   compatible with Crowdin localization.
-- For C# code, flag C# 8+ syntax and APIs that are not compatible with .NET
-  Framework 4.8 / C# 7.3.
+- For C# code, flag language features newer than the repo default C# 8.0,
+  nullable-reference-type assumptions when nullable is disabled, and APIs that
+  are not compatible with .NET Framework 4.8.
 - For legacy `.csproj` changes, verify new source files are explicitly included
   and test sources are explicitly excluded where production and test trees mix.
 - Require meaningful test or validation evidence for bug fixes, regressions,

.github/instructions/dotnet-framework.instructions.md

@@ -6,50 +6,55 @@ applyTo: '**/*.csproj, **/*.cs'
 # .NET Framework Development
 
 ## Build and Compilation Requirements
-- Always use `msbuild /t:rebuild` to build the solution or projects instead of `dotnet build`
+- Use `./build.ps1` for normal builds and `./test.ps1` for normal test runs.
+- Do not use `dotnet build` for the main repo workflow.
+- Avoid direct `msbuild` or project-only builds unless you are explicitly debugging build infrastructure.
 
 ## Project File Management
 
-### Non-SDK Style Project Structure
-.NET Framework projects use the legacy project format, which differs significantly from modern SDK-style projects:
+### SDK-style net48 projects are common
+Most managed projects in this repo use SDK-style `.csproj` files while still targeting .NET Framework `net48`.
 
-- **Explicit File Inclusion**: All new source files **MUST** be explicitly added to the project file (`.csproj`) using a `<Compile>` element
-  - .NET Framework projects do not automatically include files in the directory like SDK-style projects
-  - Example: `<Compile Include="Path\To\NewFile.cs" />`
+- **Implicit file inclusion is common**: SDK-style projects usually include new `.cs` files automatically.
+- **Check the touched project before editing**: Some projects still carry explicit includes, linked files, designer items, generated code, or custom metadata that must be preserved.
+- **Assembly metadata is managed explicitly**: Keep `GenerateAssemblyInfo` disabled where the project links `CommonAssemblyInfo.cs`.
+- **Preserve project-specific settings**: Keep existing settings for x64, WinExe, WindowsDesktop, COM, resources, warnings-as-errors, and custom MSBuild targets.
+- **Do not normalize projects unnecessarily**: Avoid converting project structure, import style, or target declarations unless that is the task.
 
-- **No Implicit Imports**: Unlike SDK-style projects, .NET Framework projects do not automatically import common namespaces or assemblies
+### Legacy project caveat
+Some non-SDK-style or tool-specific projects may still exist. When you encounter one:
 
-- **Build Configuration**: Contains explicit `<PropertyGroup>` sections for Debug/Release configurations
+- **No implicit imports**: Unlike SDK-style projects, legacy .NET Framework projects may not automatically import common namespaces or assemblies.
+- **Explicit build configuration**: Legacy projects often contain explicit `<PropertyGroup>` sections for Debug/Release configurations.
 
-- **Output Paths**: Explicit `<OutputPath>` and `<IntermediateOutputPath>` definitions
-
-- **Target Framework**: Uses `<TargetFrameworkVersion>` instead of `<TargetFramework>`
-  - Example: `<TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>`
+- Keep explicit `<Compile Include=... />` items and other legacy structure intact.
+- Update the project file only as much as the change requires.
+- Do not assume you can migrate it to SDK-style as part of routine code edits.
 
 ## NuGet Package Management
 - Installing and updating NuGet packages in .NET Framework projects is a complex task requiring coordinated changes to multiple files. Therefore, **do not attempt to install or update NuGet packages** in this project.
 - Instead, if changes to NuGet references are required, ask the user to install or update NuGet packages using the Visual Studio NuGet Package Manager or Visual Studio package manager console.
 - When recommending NuGet packages, ensure they are compatible with .NET Framework or .NET Standard 2.0 (not only .NET Core or .NET 5+).
 
-## C# Language Version is 7.3
-- This project is limited to C# 7.3 features only. Please avoid using:
+## C# Language Version
+- The repo-wide default language version for C# projects is 8.0 via `Directory.Build.props`.
+- Do not introduce features that require a newer language version unless the specific project or repo policy is updated first.
+- Prefer syntax already used in the touched area so edits remain consistent with surrounding code.
+
+### C# 8.0 features available by default
+- Switch expressions and pattern matching enhancements.
+- Using declarations where disposal scope remains clear.
+- Null-coalescing assignment and range/index operators when they improve clarity.
 
-### C# 8.0+ Features (NOT SUPPORTED):
-  - Using declarations (`using var stream = ...`)
-  - Await using statements (`await using var resource = ...`)
-  - Switch expressions (`variable switch { ... }`)
-  - Null-coalescing assignment (`??=`)
-  - Range and index operators (`array[1..^1]`, `array[^1]`)
-  - Default interface methods
-  - Readonly members in structs
-  - Static local functions
-  - Nullable reference types (`string?`, `#nullable enable`)
+### Features not safe to assume repo-wide
+- Nullable reference types are not enabled repo-wide. Do not introduce `string?`, `#nullable enable`, or nullable-flow assumptions unless the project explicitly opts in.
+- File-scoped namespaces are not available under the repo default language version and should not be introduced.
 
 ### C# 9.0+ Features (NOT SUPPORTED):
   - Records (`public record Person(string Name)`)
   - Init-only properties (`{ get; init; }`)
   - Top-level programs (program without Main method)
-  - Pattern matching enhancements
+  - Pattern matching enhancements beyond C# 8
   - Target-typed new expressions (`List<string> list = new()`)
 
 ### C# 10+ Features (NOT SUPPORTED):
@@ -58,17 +63,15 @@ applyTo: '**/*.csproj, **/*.cs'
   - Record structs
   - Required members
 
-### Use Instead (C# 7.3 Compatible):
-  - Traditional using statements with braces
-  - Switch statements instead of switch expressions
-  - Explicit null checks instead of null-coalescing assignment
-  - Array slicing with manual indexing
-  - Abstract classes or interfaces instead of default interface methods
+### Use instead when staying within repo defaults
+  - Block-scoped namespaces
+  - Explicit null checks unless the project has enabled nullable analysis
+  - Established project patterns over newer syntax for its own sake
 
 ## Environment Considerations (Windows environment)
-- Use Windows-style paths with backslashes (e.g., `C:\path\to\file.cs`)
-- Use Windows-appropriate commands when suggesting terminal operations
-- Consider Windows-specific behaviors when working with file system operations
+- FieldWorks builds and managed test runs are Windows-only.
+- On non-Windows hosts, limit work to editing, code search, docs, and specs.
+- When suggesting build or test commands, prefer the repo PowerShell scripts and Windows-oriented workflows.
 
 ## Common .NET Framework Pitfalls and Best Practices