From 9a572f1789408e6f4b43d191798eb23d0b7722fb Mon Sep 17 00:00:00 2001 From: Martin Galik Date: Sun, 9 Aug 2026 13:32:33 +0200 Subject: [PATCH] Centralize reusable FileMaker workspace guidance --- AGENTS.md | 50 +++++++++++----------- README.md | 12 ++++-- docs/project-contract.md | 16 +++++++ skills/filemaker-naming/SKILL.md | 32 ++++++++++++++ skills/filemaker-naming/agents/openai.yaml | 4 ++ skills/ticket-delivery/SKILL.md | 32 ++++++++++++++ skills/ticket-delivery/agents/openai.yaml | 4 ++ templates/PROJECT.md | 26 +++++++++++ templates/project-AGENTS.md | 15 +------ 9 files changed, 149 insertions(+), 42 deletions(-) create mode 100644 skills/filemaker-naming/SKILL.md create mode 100644 skills/filemaker-naming/agents/openai.yaml create mode 100644 skills/ticket-delivery/SKILL.md create mode 100644 skills/ticket-delivery/agents/openai.yaml create mode 100644 templates/PROJECT.md diff --git a/AGENTS.md b/AGENTS.md index 3f2bf68..65a05c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,34 +1,32 @@ # FileMaker AI Core -This repository contains reusable, client-neutral guidance for FileMaker AI work. It is designed to be consumed by client workspaces as a pinned Git submodule. +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 +## Scope and precedence - Keep this repository free of client names, DDR exports, tickets, production data, credentials, and client-specific business rules. -- Put project facts, confirmed decisions, raw DDR locations, and client communication requirements in the consuming project repository. -- Treat this repository as a baseline, not as permission to overwrite legacy project conventions. - -## Project Integration - -The consuming project's root `AGENTS.md` must direct agents here explicitly and identify the relevant skill. A project normally gives this repository lower priority than: - -1. Confirmed client decisions and current ticket requirements -2. The project's own `AGENTS.md`, notes, and documented conventions -3. Verified current DDR or direct FileMaker inspection -4. This core guidance -5. General FileMaker practice - -## Core Rules - -- Separate confirmed behavior from assumptions and open questions. -- Do not invent business rules, schema details, permissions, or implementation status. +- 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. -- Treat parsed DDR as generated reference data; do not edit it manually. -- Before sharing parsed DDR, run the project's secret-redaction and review process. -- Keep reusable instructions concise and split them into relevant skills instead of growing this file indefinitely. -## Available Skills +## Select the relevant skill -- `skills/ddr-analysis/`: analyze FileMaker DDR safely and evidence-first. -- `skills/filemaker-fmscript/`: create, edit, review, or validate `.fmscript` work using the preserved step catalog and references. -- `skills/ticket-analysis/`: turn a request into confirmed scope, questions, risks, and tests. +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 `.fmscript` generation, edit, review, or syntax question: `skills/filemaker-fmscript/SKILL.md` and the examples it selects +- 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` + +## 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. Do not edit it manually; defer to direct FileMaker verification when the two conflict. +- 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. + +## 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 valid `.fmscript` format. diff --git a/README.md b/README.md index 3ed67b3..a5731a8 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,15 @@ Private, reusable guidance for FileMaker projects that use AI assistants. This repository deliberately contains no client DDR, tickets, production data, credentials, or client-specific rules. Client workspaces consume a pinned version as a Git submodule, usually at `shared/filemaker-ai-core/`. -## Phase 1 status +## Included guidance -The initial structure establishes the shared contract, generic DDR and ticket-analysis placeholders, a ticket-analysis prompt, and project templates. It includes the preserved `filemaker-fmscript` skill with its original examples and references. It intentionally does not yet include a DDR parser wrapper or material copied from a client workspace. +- `ddr-analysis`: evidence-first analysis of parsed FileMaker DDR. +- `ticket-analysis`: confirmed scope, questions, risks, and tests for a FileMaker request. +- `filemaker-fmscript`: the preserved original `.fmscript` skill with its examples and references. +- `filemaker-naming`: client-neutral naming defaults, including Boolean names. +- `ticket-delivery`: concise project-manager replies and billable work reports. + +It intentionally does not include a DDR parser wrapper or material copied from a client workspace. ## Layout @@ -26,4 +32,4 @@ The initial structure establishes the shared contract, generic DDR and ticket-an filemaker-ai-core/ # pinned Git submodule ``` -The project root remains the normal VS Code folder. Its `AGENTS.md` explicitly directs the agent to the core resources when relevant. +The project root remains the normal VS Code folder. Its short `AGENTS.md` directs the agent to a tracked local `PROJECT.md` and then to the core resources. diff --git a/docs/project-contract.md b/docs/project-contract.md index 001cb6c..5b20c29 100644 --- a/docs/project-contract.md +++ b/docs/project-contract.md @@ -2,6 +2,14 @@ Every client AI workspace owns its client context. Keep the project root small, explicit, and safe to open directly in VS Code. +## Instruction layout + +- Root `AGENTS.md`: a short, mandatory router. It tells an agent to read the local `PROJECT.md` and this Core `AGENTS.md` before work. +- `PROJECT.md`: client and project facts, local source priority, repository map, raw DDR location, and organization-specific standards. +- Core skills: task-specific procedures read only when relevant. + +Do not use a filesystem symlink for `PROJECT.md`; track it directly in the client repository. + ## Project-owned material - client name and project scope @@ -11,6 +19,14 @@ Every client AI workspace owns its client context. Keep the project root small, - FileMaker work scripts and project-specific prompts - the location and environment names of raw DDR exports +## Standard workspace map + +- `TICKETS/`: one folder per ticket or workstream, including its source requests, handoffs, analysis, questions, reports, assets, and ticket-specific scripts. +- `FMSCRIPTS/`: tracked complete `.fmscript` files that are not clearly ticket-specific or apply across workstreams. +- `NOTES/`: confirmed knowledge that applies across more than one ticket. +- `DDR-Parsed/`: tracked generated reference material; do not edit it manually. +- sibling `DDR/`: local raw DDR input; never commit it. + ## Core-owned material - generic FileMaker analysis and scripting workflow diff --git a/skills/filemaker-naming/SKILL.md b/skills/filemaker-naming/SKILL.md new file mode 100644 index 0000000..30747dd --- /dev/null +++ b/skills/filemaker-naming/SKILL.md @@ -0,0 +1,32 @@ +--- +name: filemaker-naming +description: Name or review FileMaker fields, variables, parameters, results, scripts, layouts, and related objects without weakening an established legacy convention. Use for new or changed FileMaker names, especially Boolean fields and variables. +--- + +# FileMaker Naming + +## Priority + +1. Preserve the consuming project's confirmed naming standard and existing legacy pattern. +2. For a project that opts into an organization-specific standard, read that standard before proposing a name. +3. Use these client-neutral defaults only where neither of the above decides the name. + +Do not rename existing objects solely to apply these defaults. + +## Boolean names + +Name a Boolean as a positive yes/no question: + +- `is...` for identity or current state, for example `isActive` +- `has...` for possession or inclusion, for example `hasVendorAccess` +- `can...` for permission or capability, for example `canOpen` +- `should...` for intent or a business-rule decision, for example `shouldRetry` + +Avoid vague words such as `flag`, `status`, `check`, or `done`. Avoid negative names such as `isNotActive` or `hasNoAccess`; name the positive state and negate it in the logic where needed. Retain established FileMaker table-occurrence or scope prefixes. + +## Review before proposing a new name + +1. Search the current DDR and project sources for nearby names and scope prefixes. +2. Keep an established family of fields or variables consistent. +3. State the exact proposed name and why it fits the local convention. +4. If evidence conflicts or the business meaning is unclear, ask a concise question instead of guessing. diff --git a/skills/filemaker-naming/agents/openai.yaml b/skills/filemaker-naming/agents/openai.yaml new file mode 100644 index 0000000..a8e9525 --- /dev/null +++ b/skills/filemaker-naming/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "FileMaker Naming" + short_description: "Name FileMaker fields and variables clearly." + default_prompt: "Use $filemaker-naming to review names for new FileMaker fields and variables." diff --git a/skills/ticket-delivery/SKILL.md b/skills/ticket-delivery/SKILL.md new file mode 100644 index 0000000..5cd8fea --- /dev/null +++ b/skills/ticket-delivery/SKILL.md @@ -0,0 +1,32 @@ +--- +name: ticket-delivery +description: Prepare a concise project-manager reply and billable work report for reviewed FileMaker ticket work. Use when summarizing completed or reviewed work for a client, project manager, invoice, or handoff. +--- + +# FileMaker Ticket Delivery + +## Preconditions + +- Read the current ticket, relevant confirmed decisions, and the project's delivery rules. +- For early analysis, label the response as a draft or return only the questions needed to continue. +- Do not describe a proposal, an unverified assumption, or an open dependency as completed implementation. +- Never send, post, or otherwise deliver the reply unless explicitly asked. + +## Project-manager reply + +- Lead with completed work, followed only by unresolved questions or confirmations needed. +- Use concise, practical, client-facing English. Remove internal exploration and unused architecture proposals. +- Distinguish completed work from proposed next steps. +- When useful for verification, give a friendly label followed by the exact FileMaker object name in brackets, for example `Utility Switch [APPROVE::UtilitySwitch]`. +- Include exact layout, script, custom function, or value-list names only when they materially help verification. +- Include FileMaker code only when a calculation or script rule is central to approval. Put it at the end under a concise `KEY CALCULATIONS` or `KEY SCRIPT LOGIC` heading. + +## Short work report + +Create one only when the project requires it or the user requests it. + +- Maximum 450 characters, including title, bullets, and line breaks. +- Start with the ticket number and a short title. +- Use one to three short past-tense bullets describing completed work. +- Exclude code, open questions, testing instructions, and unconfirmed claims. +- Put the report in a fenced `text` block so it is easy to copy. diff --git a/skills/ticket-delivery/agents/openai.yaml b/skills/ticket-delivery/agents/openai.yaml new file mode 100644 index 0000000..a9542cd --- /dev/null +++ b/skills/ticket-delivery/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "FileMaker Ticket Delivery" + short_description: "Prepare concise FileMaker ticket replies and reports." + default_prompt: "Use $ticket-delivery to prepare a concise project-manager reply and work report." diff --git a/templates/PROJECT.md b/templates/PROJECT.md new file mode 100644 index 0000000..c7a9937 --- /dev/null +++ b/templates/PROJECT.md @@ -0,0 +1,26 @@ +# Project Guide + +## Identity + +- Client: +- Project: + +## Local source priority + +List the evidence order for this project. Confirmed client decisions and verified current FileMaker evidence should remain above shared guidance. + +## Repository map + +- Raw DDR: `../DDR/` (local only; never commit) +- Parsed DDR: `DDR-Parsed/` +- Tickets: `TICKETS/` +- Cross-ticket notes: `NOTES/` +- Cross-ticket FileMaker scripts: `FMSCRIPTS/` + +## Additional shared standards + +List any organization-specific shared repository and state exactly when its skills are required. + +## Project-specific rules + +Add only rules that do not apply to every FileMaker project. diff --git a/templates/project-AGENTS.md b/templates/project-AGENTS.md index 573b481..a8c434f 100644 --- a/templates/project-AGENTS.md +++ b/templates/project-AGENTS.md @@ -1,16 +1,5 @@ # AI Workspace -This repository contains client-specific FileMaker AI work. Project evidence and confirmed client decisions take priority over shared guidance. +Before any work, read `PROJECT.md` and `shared/filemaker-ai-core/AGENTS.md`. -## Shared Core - -For generic FileMaker workflow, read `shared/filemaker-ai-core/AGENTS.md` and then the relevant skill. The core does not replace this project's business rules, legacy conventions, or current DDR. - -## Project Sources - -- Tickets: `TICKETS/` -- Confirmed notes: `NOTES/` -- Parsed DDR: `DDR-Parsed/` -- Raw DDR: sibling `../ddr/` - -Record the project-specific source priority, DDR environments, naming standards, required output format, and known business rules below this line. +Confirmed ticket decisions, `PROJECT.md`, and verified current FileMaker evidence take priority over shared guidance. Do not modify `shared/` submodules unless explicitly asked.