add docs and AI skills

2026-08-17 18:23:10 +02:00
parent c3d5d3541b
commit 09dcfede46
13 changed files with 506 additions and 0 deletions
@@ -0,0 +1,53 @@
+---
+name: interpret-eftl-language
+description: Interpret the EFTL language specification and turn the repository PDF documentation into explicit lexical, syntactic, structural, attribute, and semantic rules. Use when adding or reviewing EFTL tags, expressions, nesting constraints, ElixForms TAG payloads, examples, diagnostics, or when the documentation and current TypeScript implementation disagree.
+---
+
+# Interpret EFTL Language
+
+Derive a small, testable language contract before changing implementation code.
+
+## Establish the source of truth
+
+Use the sources in this order:
+
+1. Read the relevant section of `docs/elixForms_Doc_EFTL.pdf` for EFTL behavior and examples.
+2. Read `docs/elixForms_EFTLParser_syntax_rels.pdf` for parser relationships and allowed composition.
+3. Read `docs/elixForms_TAG_Sintassi.pdf` for positional `SCHEMAID` and `GETVALUEBYTAG` payloads.
+4. Use [references/eftl-language-reference.md](references/eftl-language-reference.md) as a navigation aid and concise baseline, never as a replacement for a disputed PDF passage.
+5. Treat `src/`, `syntaxes/`, `snippets/`, `examples/`, and `README.md` as the current implementation, not as normative language documentation.
+
+If the PDFs contradict one another or leave a rule unclear, report the ambiguity and preserve it in tests or design notes. Do not silently infer a restrictive diagnostic.
+
+## Produce a rule card
+
+For every construct being changed, record:
+
+- spelling and case-sensitivity;
+- block, bodyless, expression, or comment form;
+- required and optional attributes, value types, defaults, and mutual exclusions;
+- allowed body and parent/child relationships;
+- variable scope, result type, and runtime behavior relevant to static analysis;
+- valid, invalid, and boundary examples;
+- the safest diagnostic when a property cannot be proven statically.
+
+Distinguish syntax errors from semantic warnings. Runtime-only facts such as external TAG values must not become false-positive syntax errors.
+
+## Reconcile with the implementation
+
+Search every support surface before proposing a change:
+
+```powershell
+rg -n "CONSTRUCT|TokenType" src syntaxes snippets examples README.md language-configuration.json
+```
+
+Compare the rule card with:
+
+- `src/tokenizer.ts` for recognition, source positions, and case handling;
+- `src/parser.ts` for nesting and ordering;
+- `src/server.ts` for semantic diagnostics and symbols;
+- `syntaxes/eftl.tmLanguage.json` for highlighting;
+- `language-configuration.json` for brackets, folding, and comments;
+- `snippets/eftl.json`, `examples/`, and `README.md` for user-facing syntax.
+
+Return a change-surface list and explicit acceptance cases. Hand implementation work to `$evolve-eftl-linter` and validation work to `$verify-eftl-linter` when those skills are available.