update from COPILOT.md to AGENTS.md

Roll out beads

Author: johnml1135

.github/copilot-instructions.md .GitHub/AGENTS.md.github/copilot-instructions.md renamed to .GitHub/AGENTS.md

@@ -1,7 +1,7 @@
-# FieldWorks Copilot Instructions
+# FieldWorks Agentic Instructions
 
 ## Purpose & Scope
-- Give Copilot agents a fast, reliable playbook for FieldWorks—what the repo contains, how to build/test, and how to keep documentation accurate.
+- Give AI coding agents a fast, reliable playbook for FieldWorks—what the repo contains, how to build/test, and how to keep documentation accurate.
 - Assume nothing beyond this file and linked instructions; only search the repo when a referenced step fails or is missing.
 
 See `.github/AI_GOVERNANCE.md` for the documentation taxonomy and “source of truth” rules.
@@ -10,7 +10,7 @@ See `.github/AI_GOVERNANCE.md` for the documentation taxonomy and “source of t
 - Product: FieldWorks (FLEx) — Windows-first linguistics suite maintained by SIL International.
 - Languages & tech: C#, C++/CLI, native C++, WiX, PowerShell, XML, JSON, XAML/WinForms.
 - Tooling: Visual Studio 2022 (Desktop workloads), MSBuild Traversal (`FieldWorks.proj`), WiX 3.14.x, NUnit-style tests, Crowdin localization.
-- Docs: `ReadMe.md` → https://github.com/sillsdev/FwDocumentation/wiki for deep dives; `.github/src-catalog.md` + per-folder `COPILOT.md` describe Src/ layout.
+- Docs: `ReadMe.md` → https://github.com/sillsdev/FwDocumentation/wiki for deep dives; `.github/src-catalog.md` + per-folder `AGENTS.md` describe Src/ layout.
 
 ## Core Rules
 - Prefer `./build.ps1`; avoid ad-hoc project builds that skip traversal ordering.
@@ -49,19 +49,19 @@ See `.github/AI_GOVERNANCE.md` for the documentation taxonomy and “source of t
 
 ## Instruction & Prompt Expectations
 - Instruction files live under `.github/instructions/` with `applyTo`, `name`, and `description` frontmatter only; keep content ≤ 200 lines with Purpose/Scope, Key Rules, Examples.
-- Chat modes constrain role-specific behavior (managed/native/installer/technical-writer) and should be referenced when invoking Copilot agents.
+- Chat modes constrain role-specific behavior (managed/native/installer/technical-writer) and should be referenced when invoking agents.
 
 **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.
 
-## COPILOT.md Maintenance
+## AGENTS.md Maintenance
 1. **Detect** stale folders: `python .github/detect_copilot_needed.py --strict --base origin/<branch> --json .cache/copilot/detect.json`.
 2. **Plan** diffs + reference groups: `python .github/plan_copilot_updates.py --detect-json .cache/copilot/detect.json --out .cache/copilot/diff-plan.json`.
 3. **Scaffold** (optional) when a file drifts from the canonical layout: `python .github/scaffold_copilot_markdown.py --folders Src/<Folder>`.
 4. **Apply** the auto change-log from the planner: `python .github/copilot_apply_updates.py --plan .cache/copilot/diff-plan.json --folders Src/<Folder>`.
 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.
-6. **Validate** with `python .github/check_copilot_docs.py --only-changed --fail` (or use `--paths Src/Foo/COPILOT.md` for targeted checks).
+6. **Validate** with `python .github/check_copilot_docs.py --only-changed --fail` (or use `--paths Src/Foo/AGENTS.md` for targeted checks).
 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.
-8. Run `.github/prompts/copilot-folder-review.prompt.md` with the updated plan slice to simulate Copilot review before committing.
+8. Run `.github/prompts/copilot-folder-review.prompt.md` with the updated plan slice to simulate an agent review before committing.
 
 ## CI & Validation Requirements
 - GitHub Actions workflows live under `.github/workflows/`; keep them passing.
@@ -116,3 +116,4 @@ See `.github/AI_GOVERNANCE.md` for the documentation taxonomy and “source of t
 - [ ] Refer back to this guide whenever you need repo-wide ground truth.
 
 
+

.GitHub/AI_GOVERNANCE.md

@@ -1,27 +1,27 @@
-# Copilot and AI guidance governance
+# AI guidance governance
 
 ## Purpose
-This repo uses a **Copilot-first** documentation strategy:
-- Component knowledge lives with the component (`Src/**/COPILOT.md`).
+This repo uses a **tool-agnostic, agent-first** documentation strategy:
+- Component knowledge lives with the component (`Src/**/AGENTS.md`).
 - A small set of scoped instruction files in `.github/instructions/` provides **prescriptive, enforceable constraints**.
-- `.github/copilot-instructions.md` is the short “front door” that links to the right places.
+- `.github/AGENTS.md` is the short “front door” that links to the right places.
 - Agent definitions in `.github/agents/` and role chatmodes in `.github/chatmodes/` describe **behavior/persona**, not system architecture.
 
 ## Source of truth
-- **Component architecture & entry points**: `Src/<Component>/COPILOT.md`
-- **Repo-wide workflow** (how to build/test, safety constraints): `.github/copilot-instructions.md`
+- **Component architecture & entry points**: `Src/<Component>/AGENTS.md`
+- **Repo-wide workflow** (how to build/test, safety constraints): `.github/AGENTS.md`
 - **Non-negotiable rules** (security, terminal restrictions, installer rules, etc.): `.github/instructions/*.instructions.md`
 
 ## No duplication rule
 - Do not copy component descriptions into `.github/instructions/`.
 - Do not restate rules in multiple places. Prefer linking.
-- If a rule must be enforced by Copilot for a subtree, add a scoped `.instructions.md`; otherwise document it in the relevant `COPILOT.md`.
+- If a rule must be enforced by agents for a subtree, add a scoped `.instructions.md`; otherwise document it in the relevant `AGENTS.md`.
 
 ## What goes where
 
-### `.github/copilot-instructions.md`
+### `.github/AGENTS.md`
 Use for:
-- One-page onboarding for Copilot: build/test commands, repo constraints, and links.
+- One-page onboarding for agents: build/test commands, repo constraints, and links.
 - Pointers to the curated instruction set and the component docs.
 
 ### `.github/instructions/*.instructions.md`
@@ -41,26 +41,31 @@ Use for:
 - `terminal.instructions.md`
 - `testing.instructions.md`
 
-### `Src/**/COPILOT.md`
+### `Src/**/AGENTS.md`
 Use for:
 - Where to start (entry points, key projects, typical workflows).
 - Dependencies and cross-component links.
 - Tests (where they live, how to run them).
 
-Baseline expectations for a component COPILOT doc:
+Baseline expectations for a component agent doc:
 - **Where to start** (projects, primary entry points)
 - **Dependencies** (other components/layers)
 - **Tests** (test projects and the recommended `./test.ps1` invocation)
 
 ### `.github/agents/` and `.github/chatmodes/`
 Use for:
 - Role definitions, boundaries, and tool preferences.
-- Do not put component architecture here; link to the component `COPILOT.md`.
+- Do not put component architecture here; link to the component `AGENTS.md`.
+
+## External standards alignment (post-2025)
+- **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.
+- **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.
 
 ## Adding a new scoped instruction file
 Add a new `.github/instructions/<name>.instructions.md` only when:
 - The guidance is prescriptive (MUST/DO NOT), and
 - It applies broadly or to a subtree, and
 - It would be harmful if Copilot ignored it.
 
-Otherwise, update the appropriate `Src/**/COPILOT.md`.
+Otherwise, update the appropriate `Src/**/AGENTS.md`.
+

.GitHub/agents/fieldworks.avalonia-expert.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "FieldWorks Avalonia UI Expert"
 description: "Avalonia UI specialist agent (XAML + .NET) with a strong bias toward using Context7 for up-to-date Avalonia APIs and patterns. Designed for FieldWorks-style repo constraints: minimal diffs, strong testing discipline, and localization-first UI strings."
-# target: github-copilot  # optional
+# target: universal  # optional
 # model: gpt-5.2-preview  # optional in VS Code
 # tools: ["read", "search", "edit", "terminal", "mcp_io_github_ups_resolve-library-id", "mcp_io_github_ups_get-library-docs"]
 ---

.GitHub/agents/fieldworks.cpp-expert.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "FieldWorks C++ Expert"
 description: "Native/C++ (and C++/CLI-adjacent) agent for FieldWorks (FLEx): fixes native build and test failures safely using the repo’s build order (native first), avoids risky interop changes, and validates via test.ps1 -Native and traversal builds."
-# target: github-copilot  # optional
+# target: universal  # optional
 # model: gpt-5.2-preview  # optional in VS Code
 # tools: ["read", "search", "edit", "terminal"]
 ---

.GitHub/agents/fieldworks.csharp-expert.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "FieldWorks C# Expert"
 description: "Specialized C#/.NET (net48) agent for FieldWorks (FLEx): fixes managed test failures efficiently using build.ps1/test.ps1, follows repo conventions, and avoids dotnet build pitfalls in mixed native/managed solutions."
-# target: github-copilot  # optional: enable if you only want this on GitHub
+# target: universal  # optional: enable if you want a tool-specific target
 # model: gpt-5.2-preview  # optional in VS Code; pick from autocomplete if desired
 # tools: ["read", "search", "edit", "terminal"]
 ---
@@ -39,7 +39,7 @@ Your top priorities:
 ## Code and API design guidance (FieldWorks flavor)
 - Prefer internal/private. Avoid widening visibility to satisfy tests.
 - Don’t introduce new abstraction layers unless they clearly reduce duplication and are used immediately.
-- Follow existing patterns in the folder/component (read that folder’s `COPILOT.md` if present).
+- Follow existing patterns in the folder/component (read that folder’s `AGENTS.md` if present).
 - Avoid touching auto-generated code (`*.g.cs`, `*.Designer.cs` unless explicitly required and safe).
 
 ## Common FieldWorks constraints to respect
@@ -66,3 +66,4 @@ Your top priorities:
 - Root cause summary.
 - What changed and why.
 - Tests executed (scoped) and their results.
+

.GitHub/agents/fieldworks.winforms-expert.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "FieldWorks WinForms Expert"
 description: "WinForms-focused agent for FieldWorks (FLEx): safe changes to .NET Framework (net48) WinForms UI, Designer-safe edits, localization via .resx, and efficient test-driven fixes using build.ps1/test.ps1."
-# target: github-copilot  # optional
+# target: universal  # optional
 # model: gpt-5.2-preview  # optional in VS Code
 # tools: ["read", "search", "edit", "terminal"]
 ---

.GitHub/agents/speckit.plan.agent.md

@@ -75,7 +75,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Output OpenAPI/GraphQL schema to `/contracts/`
 
 3. **Agent context update**:
-   - Run `.specify/scripts/powershell/update-agent-context.ps1 -AgentType copilot`
+   - Run `.specify/scripts/powershell/update-agent-context.ps1 -AgentType universal`
    - These scripts detect which AI agent is in use
    - Update the appropriate agent-specific context file
    - Add only new technology from current plan

.GitHub/chatmodes/coding-agent.chatmode.md

@@ -1,8 +1,8 @@
 ---
-description: 'Copilot coding agent mode for autonomous task completion'
+description: 'AI coding agent mode for autonomous task completion'
 tools: ['search', 'editFiles', 'runTasks', 'runTerminal', 'problems', 'testFailure']
 ---
-You are a GitHub Copilot coding agent working autonomously on FieldWorks. You complete tasks end-to-end without human intervention.
+You are an AI coding agent working autonomously on FieldWorks. You complete tasks end-to-end without human intervention.
 
 ## Operating Mode
 - Execute tasks completely—from understanding requirements to validated implementation
@@ -18,7 +18,7 @@ You are a GitHub Copilot coding agent working autonomously on FieldWorks. You co
 
 ## Decision Framework
 1. Read `AGENTS.md` for high-level guidance
-2. Read relevant `COPILOT.md` files in folders you'll modify
+2. Read relevant `AGENTS.md` files in folders you'll modify
 3. Follow `.github/instructions/*.instructions.md` for domain-specific rules
 4. Match existing patterns in the codebase
 5. Validate changes compile and tests pass
@@ -40,4 +40,5 @@ Before marking a task complete:
 - [ ] Relevant tests pass
 - [ ] Whitespace check passes
 - [ ] Changes follow existing patterns
-- [ ] COPILOT.md updated if contracts changed
+- [ ] AGENTS.md updated if contracts changed
+

.GitHub/instructions/terminal.instructions.md

@@ -8,7 +8,7 @@ description: "Terminal command patterns for auto-approval in FieldWorks"
 
 Commands with pipes (`|`), `&&`, or `2>&1` require manual approval. Use `scripts/Agent/` wrappers instead.
 
-**MCP-first:** When the `ps-tools` MCP server is running, prefer MCP tools (`Git-Search`, `Read-FileContent`, `Invoke-AgentTask`, `build`, `test`, Copilot tools) instead of direct terminal commands. Use wrappers only when MCP is unavailable.
+**MCP-first:** When the `ps-tools` MCP server is running, prefer MCP tools (`Git-Search`, `Read-FileContent`, `Invoke-AgentTask`, `build`, `test`, agent tools) instead of direct terminal commands. Use wrappers only when MCP is unavailable.
 
 ## Transformations
 
@@ -27,4 +27,8 @@ Commands with pipes (`|`), `&&`, or `2>&1` require manual approval. Use `scripts
 | `Git-Search.ps1` | git show/diff/log/grep/blame |
 | `Read-FileContent.ps1` | File reading with filtering |
 
-**Build/test**: Run `.\build.ps1` or `.\test.ps1` directly—they're auto-approvable.
+**Build/test**: Run `.\build.ps1` or `.\test.ps1` directly—they're auto-approvable.
+## Beads CLI (auto-approvable patterns)
+- `br` and `bv --robot-*` commands are auto-approvable **when they do not use pipes, `&&`, or redirection**.
+- Prefer `--json`/`--robot` output and parse in the agent instead of piping to `jq`.
+- `br sync --flush-only` does **not** run git; you must run git commands separately.

.github/option3-plan.md .GitHub/option3-plan.md.github/option3-plan.md renamed to .GitHub/option3-plan.md

@@ -9,10 +9,10 @@ This plan is mothballed for now. It captures the steps to bring our agent workfl
 
 ## Steps
 
-### 1) Copilot CLI and APM scaffold
-- Add `apm.yml` with scripts mapping to our prompts (e.g., `copilot-feature-spec` → feature-spec.prompt.md)
+### 1) Agent CLI and APM scaffold
+- Add `apm.yml` with scripts mapping to our prompts (e.g., `agent-feature-spec` → feature-spec.prompt.md)
 - Include MCP dependencies (e.g., `ghcr.io/github/github-mcp-server`)
-- Document local usage in README: `apm install`, `apm run copilot-feature-spec --param specFile=...`
+- Document local usage in README: `apm install`, `apm run agent-feature-spec --param specFile=...`
 
 ### 2) GitHub Action to run a prompt on PR
 - Create `.github/workflows/agent-workflow.yml`
@@ -26,14 +26,14 @@ This plan is mothballed for now. It captures the steps to bring our agent workfl
 - Maintain a curated list in `.github/context/mcp.servers.md` (to be created when piloting)
 
 ### 4) Security and secrets
-- Use `secrets.COPILOT_CLI_PAT` for Copilot CLI (if needed)
+- Use `secrets.AGENT_CLI_PAT` for agent CLI (if needed)
 - Principle of least privilege for tokens and tool scopes
 - Add a security review checklist for new tools/servers
 
 ### 5) Governance and validation
 - Add a `lint-docs` CI job to verify presence and links for:
   - `.github/instructions/*.instructions.md`
-  - `Src/*/COPILOT.md`
+  - `Src/*/AGENTS.md`
   - `.github/src-catalog.md`
 - Add a `prompt-validate` job: checks frontmatter structure for `.prompt.md`
 
@@ -42,8 +42,9 @@ This plan is mothballed for now. It captures the steps to bring our agent workfl
 - Gather feedback and iterate before enabling write-capable workflows
 
 ## References
-- `.github/copilot-instructions.md` (entry points)
+- `.github/AGENTS.md` (entry points)
 - `.github/prompts/` (agent workflows)
 - `.github/instructions/` (domain rules)
 - `.github/chatmodes/` (role boundaries)
 - `.github/context/` and `.github/memory.md` (signals and decisions)
+