adminforth AGENTS.md

AGENTS.md

Package manager

All packages and projects in this repo use pnpm and not npm. Howeverer internally (e.g. in codeInjector) adminforth still supports both npm and pnpm style install commands, so users of framework itself can use it with either package manager. But in all dev demo/live demo, plugins, adapters, and documentation, we use pnpm as the standard.

Package names rules

All adapters and plugins always have @adminforth/ prefix in their package name, followed by short lowercase kebab-case plugin/adpater slug.

Every plugin has at least one Docusaurus docs page, which should use the path /docs/tutorial/Plugins/<plugin-slug>/.

Same for adapters, but with /docs/tutorial/Adapters/<adapter-slug>/ path.

Page names in docusarus should be human readabale. We should not use AuditLog but instead we should have Audit Log via whitespace.

General engineering rules

Write code as if the system contracts are already defined and trusted.

Do not add defensive checks “just in case” when the contract, type, schema, backend response, or controlled internal API already guarantees the shape of the data.

Prefer simplicity, clarity, and consistency over paranoia.

Follow these principles strictly:

• DRY
• SOLID
• YAGNI
• Keep code minimal
• Trust typed contracts
• Avoid duplicate validation
• Avoid speculative fallback logic
• Avoid inline regex literals when reused or non-trivial

---

Trust the contract

If backend and frontend are part of the same system, and the backend explicitly guarantees a response shape, do not re-validate every field on the frontend.

Bad:

• backend returns a strict object
• frontend then checks every field for undefined, wrong type, empty string, wrong enum, etc.
• frontend adds fallback branches for impossible states

Good:

• backend owns validation
• shared types or schemas define the contract
• frontend consumes the contract directly
• frontend only handles real UI states, not imaginary protocol corruption