filemaker-ai-core/AGENTS.md

FileMaker AI Core

This repository provides reusable, client-neutral guidance for FileMaker AI work. It is normally consumed as a pinned Git submodule by a client workspace.

Scope and precedence

• Keep this repository free of client names, DDR exports, tickets, production data, credentials, and client-specific business rules.
• Read the consuming project's PROJECT.md before applying this guidance. Its confirmed client decisions, documented conventions, and verified current FileMaker evidence take priority over this core.
• Preserve established legacy patterns unless a confirmed requirement deliberately changes them.

Evidence priority

When sources conflict, use this order unless the project's PROJECT.md documents a stricter project-specific rule:

1. Confirmed current client decision in the ticket or project record
2. Verified current FileMaker behavior or current parsed DDR evidence
3. Other confirmed project documentation
4. An organization-specific shared standard explicitly selected by the project
5. This FileMaker Core guidance

Report meaningful conflicts instead of silently resolving them.

Standard repository map

Use these locations for a workspace that follows the standard project layout. A project may document only deviations in PROJECT.md.

• ../DDR/: local raw FileMaker DDR input. Never copy it into the repository or commit it; move it only as part of an explicitly approved filesystem migration.
• TICKETS/: one folder per ticket or workstream. Keep its source requests, handoffs, analysis, questions, reports, assets, and ticket-specific scripts together. Use a scripts/ subfolder when it helps navigation.
• FMSCRIPTS/: default location for tracked .fmscript files. Use it for FileMaker script work unless the user explicitly requests DDRparser text format.
• NOTES/: confirmed knowledge and business rules that apply across more than one ticket.
• DDR-Parsed/: tracked FileMaker reference material generated by DDRparser. Do not manually edit generated definitions outside Scripts/. When a project uses the DDRparser copy-and-paste workflow, edit the affected Scripts/*.txt file in place for Git review, paste it into FileMaker, regenerate the DDR, and verify the round trip.
• ddr-parse.sh: run zsh ddr-parse.sh from the project root to parse the latest DDR into DDR-Parsed/ when an up-to-date reference is needed.

Select the relevant skill

Read only the skill that matches the work; do not load every shared reference by default.

• Ticket, request, email, or handoff: skills/ticket-analysis/SKILL.md
• Current implementation, schema, script, calculation, layout, relationship, security, reporting, or integration analysis: skills/ddr-analysis/SKILL.md
• Any FileMaker script discussion, generation, edit, review, syntax question, or copy-and-paste preparation: use .fmscript by default and read skills/filemaker-fmscript/SKILL.md and the examples it selects.
• When the user explicitly requests DDRparser text format or a DDRparser copy-and-paste workflow, use skills/filemaker-ddr-script/SKILL.md instead.
• New or changed FileMaker object, field, variable, parameter, or result names: skills/filemaker-naming/SKILL.md
• Project-manager reply or short billable work report: skills/ticket-delivery/SKILL.md

Standard workflow

1. Put a new ticket, request, or email in its own TICKETS/<ticket or workstream>/ folder.
2. Analyze it with the relevant shared skill before proposing implementation.
3. Review affected current definitions and dependencies in DDR-Parsed/.
4. Turn unclear business rules into concise confirmation questions rather than assumptions.
5. After implementation and DDR regeneration, re-check affected definitions, calculations, layouts, scripts, and report dependencies.
6. Prepare client-facing delivery only after the work is reviewed or when explicitly requested.

Core rules

• Do not invent business rules, schema details, permissions, or implementation status. Separate confirmed behavior, verified current behavior, proposals, and open questions.
• Use parsed DDR as generated reference data and defer to direct FileMaker verification when the two conflict. The only standard manual-edit exception is an authorized DDRparser-format script change under DDR-Parsed/<solution>/Scripts/; paste it into FileMaker and regenerate the DDR before calling it implemented.
• Keep work practical and minimal. Review affected data, permissions, workflows, layouts, reporting, integrations, and regression risk where relevant.
• Do not make production changes, send client messages, or modify project files unless explicitly asked.
• Do not expose credentials or other sensitive values found in source material.

Implementation simplicity

• Prefer the simplest correct implementation that satisfies the confirmed requirement.
• Implement only currently required behavior. Do not add speculative flexibility, optional features, configuration, extension points, frameworks, or future-proofing.
• Avoid new helper scripts, custom functions, abstractions, files, and layers unless they are immediately needed.
• Keep each business rule in one place. When new or changed logic would otherwise be duplicated, centralize it using the smallest suitable existing structure. Do not refactor unrelated legacy duplication.
• When the same confirmed business rule is used in two or more FileMaker calculations or scripts, centralize it before adding another copy: prefer a calculation field for record-level logic that callers can reference; use a custom function only for genuinely parameterized or cross-context logic. Keep callers as references to that canonical logic. Do not create a shared object for single-use logic or where it would obscure behavior.
• Follow established project and FileMaker patterns unless a confirmed requirement requires a different approach.
• Make only the smallest necessary change. Avoid unrelated refactoring, cleanup, renaming, and formatting changes.
• Add error handling only for expected errors that affect the required workflow. Avoid generic catch-all handling, redundant Get ( LastError ) checks, defensive branches, logging, status variables, and cleanup blocks that do not change the required result.
• Preserve the minimum necessary safeguards for destructive actions, imports, migrations, production changes, security, and data integrity.
• When a requirement is unclear, ask a focused question instead of implementing multiple hypothetical cases or defensive alternatives.
• Add comments only for non-obvious logic, business rules, and required dated change notes.
• Validate only the directly affected behavior with the smallest relevant checks. Do not create additional testing infrastructure unless it is necessary.
• Treat these rules as the default. Confirmed requirements, data safety, and verified existing behavior take priority. If additional complexity is necessary, explain the concrete reason briefly.

Response format

• Do not hard-wrap Markdown prose. Use line breaks only where Markdown structure or meaning requires them.
• Present every FileMaker script snippet, including partial sections, in a fenced text block and use .fmscript format by default. Use DDRparser text format only when the user explicitly requests it.