Skip to content

Commit a8516d7

Browse files
jasonleenaylorjohnml1135
jasonleenaylor
authored and
johnml1135
committed
Modernize .NET tooling and enable AI workflows
- See SDK_MIGRATION.md for details - **64-bit only** architecture enforcement (x86/Win32 removed) - **Registration-free COM** implementation (Native + Managed) - **Unified launcher**: FieldWorks.exe replaced the historical LexText.exe stub across build, installer, and documentation - **MSBuild Traversal SDK** for declarative builds - **Test framework modernization** (RhinoMocks → Moq, NUnit 4 ready) - **Central Package Management (CPM)** via `Directory.Packages.props` - **Unified test runner** (`test.ps1`) for managed and native tests - **Stale DLL detection** via single-pass pre-build validation - **Installer validation tooling** with snapshot-based evidence collection - **Binding redirect cleanup** — eliminated manual `<bindingRedirect>` entries - **Developer environment tooling** (Defender exclusions, dependency verification) - **AGENTS.md documentation convention** for AI agent and developer onboarding
1 parent e4ec0f4 commit a8516d7

File tree

1,423 files changed

+131232
-61103
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,423 files changed

+131232
-61103
lines changed

‎.GitHub/AGENTS.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# FieldWorks Agentic Instructions
2+
3+
## Purpose & Scope
4+
- Give AI coding agents a fast, reliable playbook for FieldWorks—what the repo contains, how to build/test, and how to keep documentation accurate.
5+
- Assume nothing beyond this file and linked instructions; only search the repo when a referenced step fails or is missing.
6+
7+
See `.github/AI_GOVERNANCE.md` for the documentation taxonomy and “source of truth” rules.
8+
9+
## Repository Snapshot
10+
- Product: FieldWorks (FLEx) — Windows-first linguistics suite maintained by SIL International.
11+
- Languages & tech: C#, C++/CLI, native C++, WiX, PowerShell, XML, JSON, XAML/WinForms.
12+
- Tooling: Visual Studio 2022 (Desktop workloads), MSBuild Traversal (`FieldWorks.proj`), WiX 3.14.x, NUnit-style tests, Crowdin localization.
13+
- Docs: `ReadMe.md` → https://github.com/sillsdev/FwDocumentation/wiki for deep dives; `.github/src-catalog.md` + per-folder `AGENTS.md` describe Src/ layout.
14+
15+
## Core Rules
16+
- Prefer `./build.ps1`; avoid ad-hoc project builds that skip traversal ordering.
17+
- Run tests relevant to your change before pushing; do not assume CI coverage.
18+
- For bug fixes, default to TDD (Red-Green-Refactor): write a failing test first, then implement the minimal fix.
19+
- If you need to pause current edits to stay test-first, use `git stash` to hold changes while implementing the tests to fail, then restore with `git stash apply`.
20+
- Keep localization via `.resx` and respect `crowdin.json`; never hardcode translatable strings.
21+
- Avoid COM/registry edits without a test plan.
22+
- Stay within documented tooling—no surprise dependencies or scripts without updating instructions.
23+
- **Terminal commands**: **ALWAYS use `scripts/Agent/` wrapper scripts** for git or file reading requiring pipes/filters. See `.github/instructions/terminal.instructions.md` for the transformation table.
24+
25+
## Build & Test Essentials
26+
- Prerequisites: install VS 2022 Desktop workloads, WiX 3.14.x (pre-installed on windows-latest), Git, LLVM/clangd + standalone OmniSharp (for Serena C++/C# support), and optional Crowdin CLI only when needed.
27+
- Verify your environment: `.\Build\Agent\Verify-FwDependencies.ps1 -IncludeOptional`
28+
- Common commands:
29+
```powershell
30+
# Full traversal build (Debug/x64 defaults)
31+
.\build.ps1
32+
33+
# Run tests
34+
.\test.ps1
35+
```
36+
- Tests: follow `.github/instructions/testing.instructions.md`; use VS Test Explorer or `vstest.console.exe` for managed tests.
37+
- Installer edits must follow `.github/instructions/installer.instructions.md` plus WiX validation before PR.
38+
- Installer builds: use `.\Build\Agent\Setup-InstallerBuild.ps1 -ValidateOnly` to check prerequisites, `-SetupPatch` for patch builds.
39+
40+
## Workflow Shortcuts
41+
| Task | Reference |
42+
| --- | --- |
43+
| Build/test rules | `.github/instructions/build.instructions.md`, `.github/instructions/testing.instructions.md` |
44+
| Debugging | `.github/instructions/debugging.instructions.md` |
45+
| Managed / Native / Installer guidance | `.github/instructions/managed.instructions.md`, `.github/instructions/native.instructions.md`, `.github/instructions/installer.instructions.md` |
46+
| Security & PowerShell rules | `.github/instructions/security.instructions.md`, `.github/instructions/powershell.instructions.md` |
47+
| Guidance governance | `.github/AI_GOVERNANCE.md` |
48+
| **Agent wrapper scripts** | `scripts/Agent/` - build, test, and git helpers for auto-approval |
49+
| Prompts & specs | `.github/prompts/*.prompt.md`, `.github/spec-templates/`, `.github/recipes/` |
50+
| Chat modes | `.github/chatmodes/*.chatmode.md` |
51+
52+
## Instruction & Prompt Expectations
53+
- Instruction files live under `.github/instructions/` with `applyTo`, `name`, and `description` frontmatter only; keep content ≤ 200 lines with Purpose/Scope, Key Rules, Examples.
54+
- Chat modes constrain role-specific behavior (managed/native/installer/technical-writer) and should be referenced when invoking agents.
55+
56+
**Context7 Guidance:** When requesting API references, code examples, or library-specific patterns, consult Context7 first (for example, call `resolve-library-id` then `get-library-docs` or `search-code`). Prefer the Context7 libraries listed in `.vscode/context7-configuration.json` and include the resolved library ID in your prompt when possible. Context7 lookups are considered safe and are configured for auto-approval in this workspace.
57+
58+
## AGENTS.md Maintenance
59+
1. **Detect** stale folders: `python .github/detect_copilot_needed.py --strict --base origin/<branch> --json .cache/copilot/detect.json`.
60+
2. **Plan** diffs + reference groups: `python .github/plan_copilot_updates.py --detect-json .cache/copilot/detect.json --out .cache/copilot/diff-plan.json`.
61+
3. **Scaffold** (optional) when a file drifts from the canonical layout: `python .github/scaffold_copilot_markdown.py --folders Src/<Folder>`.
62+
4. **Apply** the auto change-log from the planner: `python .github/copilot_apply_updates.py --plan .cache/copilot/diff-plan.json --folders Src/<Folder>`.
63+
5. **Edit narrative sections** using the planner JSON (change counts, commit log, `reference_groups`), keeping human guidance short and linking to subfolder docs where possible.
64+
6. **Validate** with `python .github/check_copilot_docs.py --only-changed --fail` (or use `--paths Src/Foo/AGENTS.md` for targeted checks).
65+
7. When documentation exceeds ~200 lines or acts as a parent index, migrate to `.github/templates/organizational-copilot.template.md` and keep the parent doc as a navigation index.
66+
8. Run `.github/prompts/copilot-folder-review.prompt.md` with the updated plan slice to simulate an agent review before committing.
67+
68+
## CI & Validation Requirements
69+
- GitHub Actions workflows live under `.github/workflows/`; keep them passing.
70+
- Local parity checks:
71+
```powershell
72+
# Commit messages (gitlint)
73+
python -m pip install --upgrade gitlint
74+
git fetch origin
75+
gitlint --ignore body-is-missing --commits origin/<base>..
76+
77+
# Whitespace
78+
git log --check --pretty=format:"---% h% s" origin/<base>..
79+
git diff --check --cached
80+
```
81+
- Before PRs, ensure:
82+
- Build + relevant tests succeed locally.
83+
- Installer/config changes validated with WiX tooling.
84+
- Analyzer/lint warnings addressed.
85+
86+
### Build & Test Commands (ALWAYS use the scripts)
87+
```powershell
88+
# Build
89+
.\build.ps1
90+
.\build.ps1 -Configuration Release
91+
.\build.ps1 -BuildTests
92+
93+
# Test
94+
.\test.ps1
95+
.\test.ps1 -TestFilter "TestCategory!=Slow"
96+
.\test.ps1 -TestProject "Src/Common/FwUtils/FwUtilsTests"
97+
.\test.ps1 -NoBuild # Skip build, use existing binaries
98+
99+
# Both scripts automatically:
100+
# - Clean stale obj/ folders and conflicting processes
101+
# - Set up VS environment
102+
```
103+
104+
**DO NOT** use raw `msbuild` directly - let the scripts handle it.
105+
106+
## Where to Make Changes
107+
- Source: `Src/` contains managed/native projects—mirror existing patterns and keep tests near the code (`Src/<Component>.Tests`).
108+
- Installer: `FLExInstaller/` with WiX artifacts.
109+
- Shared headers/libs: `Include/`, `Lib/` (avoid committing large binaries unless policy allows).
110+
- Localization: update `.resx` files; never edit `crowdin.json` unless you understand Crowdin flows.
111+
- Build infrastructure: `Build/` + `Bld/` orchestrate targets/props—change sparingly and document impacts.
112+
113+
## JIRA Integration
114+
115+
**LT-prefixed tickets** (e.g., `LT-22382`) are JIRA issues from `https://jira.sil.org/`.
116+
117+
⚠️ **NEVER browse to `jira.sil.org` URLs** - requires authentication. **ALWAYS use Python scripts:**
118+
119+
```powershell
120+
# Get issue details (inline Python)
121+
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_issues import jira_get_issue; print(jira_get_issue('LT-22382'))"
122+
123+
# Or export your assigned issues to JSON
124+
python .github/skills/jira-to-beads/scripts/export_jira_assigned.py
125+
```
126+
127+
| Scenario | Skill |
128+
|----------|-------|
129+
| Read issue details | `atlassian-readonly-skills` (default) |
130+
| Create/update/comment | `atlassian-skills` (only when user explicitly requests) |
131+
| Bulk import to Beads | `jira-to-beads` |
132+
133+
See `/AGENTS.md` → "Atlassian / JIRA Skills" section for full configuration and details.
134+
135+
## Confidence Checklist
136+
- [ ] Prefer traversal builds over per-project compile hacks.
137+
- [ ] Keep coding style aligned with `.editorconfig` and existing patterns.
138+
- [ ] Validate installer/localization changes before PR.
139+
- [ ] Record uncertainties with `FIXME(<topic>)` and resolve them when evidence is available.
140+
- [ ] Refer back to this guide whenever you need repo-wide ground truth.
141+
142+
143+

‎.GitHub/AI_GOVERNANCE.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# AI guidance governance
2+
3+
## Purpose
4+
This repo uses a **tool-agnostic, agent-first** documentation strategy:
5+
- Component knowledge lives with the component (`Src/**/AGENTS.md`).
6+
- A small set of scoped instruction files in `.github/instructions/` provides **prescriptive, enforceable constraints**.
7+
- `.github/AGENTS.md` is the short “front door” that links to the right places.
8+
- Agent definitions in `.github/agents/` and role chatmodes in `.github/chatmodes/` describe **behavior/persona**, not system architecture.
9+
10+
## Source of truth
11+
- **Component architecture & entry points**: `Src/<Component>/AGENTS.md`
12+
- **Repo-wide workflow** (how to build/test, safety constraints): `.github/AGENTS.md`
13+
- **Non-negotiable rules** (security, terminal restrictions, installer rules, etc.): `.github/instructions/*.instructions.md`
14+
15+
## No duplication rule
16+
- Do not copy component descriptions into `.github/instructions/`.
17+
- Do not restate rules in multiple places. Prefer linking.
18+
- If a rule must be enforced by agents for a subtree, add a scoped `.instructions.md`; otherwise document it in the relevant `AGENTS.md`.
19+
20+
## What goes where
21+
22+
### `.github/AGENTS.md`
23+
Use for:
24+
- One-page onboarding for agents: build/test commands, repo constraints, and links.
25+
- Pointers to the curated instruction set and the component docs.
26+
27+
### `.github/instructions/*.instructions.md`
28+
Use for:
29+
- Prescriptive constraints that must be applied during editing/review.
30+
- Cross-cutting rules that prevent expensive mistakes (security, terminal command restrictions, installer rules, managed/native boundary rules).
31+
32+
**Curated keep set (intentionally small):**
33+
- `build.instructions.md`
34+
- `debugging.instructions.md`
35+
- `installer.instructions.md`
36+
- `managed.instructions.md`
37+
- `native.instructions.md`
38+
- `powershell.instructions.md`
39+
- `repo.instructions.md`
40+
- `security.instructions.md`
41+
- `terminal.instructions.md`
42+
- `testing.instructions.md`
43+
44+
### `Src/**/AGENTS.md`
45+
Use for:
46+
- Where to start (entry points, key projects, typical workflows).
47+
- Dependencies and cross-component links.
48+
- Tests (where they live, how to run them).
49+
50+
Baseline expectations for a component agent doc:
51+
- **Where to start** (projects, primary entry points)
52+
- **Dependencies** (other components/layers)
53+
- **Tests** (test projects and the recommended `./test.ps1` invocation)
54+
55+
### `.github/agents/` and `.github/chatmodes/`
56+
Use for:
57+
- Role definitions, boundaries, and tool preferences.
58+
- Do not put component architecture here; link to the component `AGENTS.md`.
59+
60+
## External standards alignment (post-2025)
61+
- **AGENTS.md**: Supported as a simple, vendor-neutral instruction format by multiple tools (for example, Cursor’s project rules). Use plain Markdown with clear headings and concise rules.
62+
- **MCP (Model Context Protocol)**: Use MCP for tool/data integration rather than vendor-specific plugins; MCP provides a standardized, versioned protocol for AI tool connectivity.
63+
64+
## Adding a new scoped instruction file
65+
Add a new `.github/instructions/<name>.instructions.md` only when:
66+
- The guidance is prescriptive (MUST/DO NOT), and
67+
- It applies broadly or to a subtree, and
68+
- It would be harmful if Copilot ignored it.
69+
70+
Otherwise, update the appropriate `Src/**/AGENTS.md`.
71+

0 commit comments

Comments
 (0)