AI Agent Playbook for FieldWorks

August 6, 2026 · View on GitHub

Minimal, high-signal guidance for coding agents in this repository.

Non-negotiable defaults

  • Platform is Windows/x64.
  • Build with .\build.ps1.
  • Test with .\test.ps1.
  • Do not bypass repository scripts for normal build/test work.

Critical constraints

  • Native C++ must build before managed projects (enforced by FieldWorks.proj + build.ps1).
  • FieldWorks uses registration-free COM; do not register COM globally and do not add registry hacks.
  • Keep localization in .resx; do not hardcode translatable UI strings.
  • Follow the code-comment standard in .claude/skills/fieldworks-code-commenting/SKILL.md.

Context model

  • Keep shared repo guidance in this file plus the nearest nested AGENTS.md.
  • Consult Docs/lessons/README.md for indexed, human-reviewed lessons from completed, rejected, or retired work before planning in a covered area.
  • GitHub Copilot custom instructions still require .github/copilot-instructions.md and .github/instructions/*.instructions.md.
  • Claude Code reads CLAUDE.md, which imports this file; keep Claude-only workflows under .claude/skills/.
  • Use Src/AGENTS.md, FLExInstaller/AGENTS.md, openspec/AGENTS.md, and .github/AGENTS.md when touching GitHub-specific repo files.

External Dependencies (LibLcm)

FieldWorks is built upon the liblcm (Language & Culture Model) repository, which provides the main data model and FDO (FieldWorks Data Objects) layers used by FieldWorks. The liblcm library is the core FieldWorks model for language and culture data and includes interfaces like IScrFootnoteFactory that FieldWorks consumes. If you cannot find a core data model definition within this workspace, ask for access to the liblcm repository to reference the source.

Serena navigation

  • Prefer Serena symbolic tools for code discovery/navigation before broad file reads.

MCP servers

  • .mcp.json registers the winforms-mcp server (strict JSON — no comments); setup and rationale live in .claude/skills/fieldworks-winapp/references/mcp-setup.md.

Issue tracking and Jira

  • Use GitHub issues/PRs (and Jira when required) for issue workflow.
  • For LT- Jira tickets, use the Atlassian Python skill scripts under .claude/skills/atlassian-readonly-skills/scripts.
  • Do not attempt direct web access to Jira pages from agent tooling.
  • GitHub Copilot for Jira may be used with authenticated Jira Data Center access when the approved service-user/API policy limits which issues are exposed.
  • See .github/copilot-jira-setup.md for setup and secret guidance.

Validation checklist

  1. Run the relevant build/test scripts for touched areas.
  2. Keep edits scoped and avoid unrelated refactors.
  3. Update docs only when behavior/contracts/process changed.