Imported from Dricosr/iforge-edp-values (AGENTS.md). Install upstream with npx skills add Dricosr/iforge-edp-values. Copyright stays with the author.

@.claude/agents/index.md @memory/MEMORY.md @memory/library-conformance-checklist.md

iforge-edp-values - Agent Instructions

Project overview

iforge-edp-values is a cross-platform (Node.js + browser) ESM library for engineering parameter values in AEC/industrial applications. It handles unit conversion, display formatting, fractional inch parsing, and structured validation using mathjs as the underlying unit engine.

• Package: @dricosr/iforge-edp-values
• Source: src/ (ES modules, .mjs files only)
• Spec: spec/en-us/spec.md (English) · spec/pt-br/spec.md (Portuguese mirror)

Language

• All code, comments, variable names, and documentation in English (en-US)
• Commit messages, PR descriptions, issue templates, and changelog entries in English

File conventions

• .mjs extension for all JavaScript source files
• ES6+ syntax: import/export, arrow functions, const/let, optional chaining
• No CommonJS (require, module.exports), no TypeScript
• Source in src/; compiled output in dist/ (git-ignored, generated by npm run build)
• Import dependencies by package name only - never by relative path into node_modules/

Code design

• One file, one responsibility - if a file needs "and" or "or" to describe what it does, split it
• Reuse Object.freezed constants - never recreate equivalent structures at call time
• No duplicate logic - extract shared behavior into src/core/ or src/constants/
• Pure functions, no hidden state, no side effects
• No speculative abstractions - implement only what the current task requires

Dependencies

• Exact versions in package.json - no ^ or ~ prefixes
• Check the latest published version before adding or updating a dependency
• engines.node must track the current stable release (currently >= 24.0.0)

Build

npm run build          # ESM + CJS + IIFE in dist/
npm run test           # all test files
npm run test:visual    # visual tests only
npm run test:coverage  # with coverage report
npx vitest run <file>  # single file (PowerShell only on Windows - see Testing)

The build produces three formats in dist/:

• dist/index.esm.js - tree-shakeable ES module, mathjs external
• dist/index.cjs.js - CommonJS, mathjs external
• dist/index.iife.min.js - self-contained IIFE, mathjs bundled, for <script> tags

prepublishOnly runs tests then build automatically before every npm publish.

Testing

• Tests mirror src/ under tests/, named <module-name>.test.mjs
• Runner: Vitest - import { describe, it, expect } from "vitest"
• Never mock mathjs - test against the real implementation
• Windows: always run Vitest from PowerShell or bash, never cmd.exe - cmd.exe causes a silent TypeError: Cannot read properties of undefined (reading 'config') under Vitest 4.x, completely unrelated to test code
• Hydrate samples and tests together: when adding or modifying a feature, add representative entries to src/samples/ and update tests/ in the same pass
• Use real AEC/industrial values in samples - not arbitrary numbers (e.g. typical pipe spool lengths, common vessel pressures, standard beam spans)

Git and docs

• Never add Co-Authored-By: trailers or any co-author metadata unless the user explicitly requests it
• When editing constants, core functions, or any public API, verify README.md, CONTRIBUTING.md, and CHANGELOG.md are still aligned
• If a function is added, removed, or renamed, update all affected documentation in the same pass
• Add every notable change to CHANGELOG.md under [Unreleased] before finishing
• Decimal separator: . only - never ,; thousands separators not supported

Naming conventions

Agents

implement

Use when implementing or modifying source files in src/ - constants, core functions, or the public index.

Rules:

• Source files live in src/constants/ or src/core/, exported through src/index.mjs
• Never introduce a build step, bundler, or TypeScript
• Spec lives in spec/en-us/spec.md; when editing spec, update both language versions in the same pass
• After any public API change, update README.md, CONTRIBUTING.md, and CHANGELOG.md
• Hydrate samples in src/samples/ and tests in tests/ whenever a feature changes

test

Use when writing, updating, or debugging tests in tests/.

Rules:

• Mirror src/ structure - e.g. tests/core/create-value.test.mjs
• Cover happy path and edge cases for every public function
• Never mock mathjs
• Run npx vitest run from PowerShell and fix all failures before finishing
• Add sample entries to src/samples/ alongside new tests

naming-reviewer

Use when reviewing or standardizing names across src/ - file names, exported symbols, internal identifiers.

Rules:

• Read the full file before proposing anything
• Update every import, export, and call site - never just the declaration
• Never rename if it breaks the public API without explicit user approval
• Never leave src/index.mjs, README.md, CHANGELOG.md, or agent files with stale references

Naming table:

jsdoc-documentor

Use when adding or improving JSDoc in src/ files - @param, @returns, @throws, @typedef, @fileoverview.

Rules:

• Never alter runtime behavior, logic, or structure
• Never convert to TypeScript, rename symbols, or move files
• Only document when at least one is true: the parameter contract is non-obvious, the return shape requires explanation, there is a known throw condition, or a @typedef would remove repeated shape descriptions
• All documentation in English

Slash commands

Response style

• Keep responses short and direct
• No emojis unless explicitly requested
• No trailing summaries of what was just done

Customization sync

Keep these pairs semantically aligned:

• .github/agents/*.agent.md ↔ .claude/agents/*.md
• .github/prompts/*.prompt.md ↔ .claude/commands/*.md
• memory/MEMORY.md and indexed files ↔ the shared rules in this file
• AGENTS.md ↔ .github/copilot-instructions.md (Copilot mirrors inline; AGENTS.md is canonical)