Imported from justinmchase/uffda (AGENTS.md). Install upstream with npx skills add justinmchase/uffda. Copyright stays with the author.

Uffda agent instructions

Uffda is a Deno-based parser generator for domain specific languages.

These instructions apply to all agent tooling (Cursor, Copilot, and others). Path-scoped authoring guidance also lives in:

• .cursor/rules/ (Cursor)
• .github/instructions/ (GitHub Copilot)

Runtime and dependency conventions

• Prefer Deno-native and Web Platform APIs over Node.js APIs.
• Default to ESM TypeScript.
• Scripting language hard rule: the only acceptable scripting languages in this repository are TypeScript and Deno. Python (and other non-Deno scripting languages) are completely hard-blocked, including in GitHub Actions, composite actions, install helpers, and one-liners. Shell may orchestrate Deno/gh/curl commands, but non-trivial logic MUST live in TypeScript run with Deno.
• Add third-party imports through the imports field in deno.jsonc before using them in source files.
• Prefer JSR packages first. Use npm packages only when there is a clear need.
• Keep the library focused on parser-generation and runtime concerns rather than app-specific frameworks.

Project conventions

• Entry point: mod.ts
• Place implementation code under src/.
• Keep tests next to the modules they cover using the .test.ts suffix.
• For every source file you create or modify under src/, create or update the corresponding *.test.ts file in the same directory.
• Follow the existing Deno validation path: deno fmt, deno lint, and deno task test.
• Prefer deno task pre before committing.
• Keep modules small and composable when adding or refactoring parser logic.

Type modeling conventions

• Prefer discriminated unions that use a kind field with an enum discriminator (for example PatternKind).
• When introducing union guards, follow the existing style used by isPattern: validate object shape and validate kind against the discriminator enum.
• Avoid introducing parallel discriminator properties for the same union (for example, do not add both kind and type/mode for the same purpose).
• Do not put variants in a discriminator enum unless they belong to that union.
• Keep discriminator enums narrow enough that callers do not need to mentally filter out irrelevant members.

Specification authority and change control

Apply this strict authority order when implementing or evaluating behavior:

1. Spec documents (.agents/specifications/**/*.md)
2. Requirement documents (.agents/requirements/**/*.requirement.md)
3. Tests (**/*.test.ts)
4. Implementation code (src/**, mod.ts)

• Specs are intentionally higher level than requirements.
• Requirements refine and make specific behaviors from the spec testable.
• If a behavior change is not already covered in the relevant spec or requirement, update the documentation in the same PR as the implementation.
• Do not silently reinterpret tests or implementation to contradict the spec or requirements.
• If a requested behavior conflicts with existing spec or requirements, ask for clarification before changing lower-authority artifacts.

Specification layout

• Specs live under .agents/specifications/.
• .agents/specifications/README.md is the entry point and index.
• Normative chapters use the {topic}.spec.md naming pattern.
• Requirements live under .agents/requirements/ as {name}.requirement.md.
• Requirement documents should reference the spec file and section they refine.

Validation

After making changes, run:

deno fmt
deno lint
deno task test

Do not cancel these commands; they normally finish quickly.