// README and documentation conventions: import patterns in examples, emoji preservation, and descriptive text rules. Use when writing or editing README files, package documentation, or code examples in docs.
| name | documentation-conventions |
| description | README and documentation conventions: import patterns in examples, emoji preservation, and descriptive text rules. Use when writing or editing README files, package documentation, or code examples in docs. |
Guidelines for writing and maintaining package documentation and README files.
// ✅ README examples use namespace imports
import * as functions from "@eserstack/functions";
const result = await functions.run(async function* () { /* ... */ });
const pipeline = functions.collect<string, Error>();
import * as pkg from "@eserstack/pkg")"I'll simplify the import for the README" No. Always use the namespace pattern. Sub-path exports are for advanced users, not docs.
"I'll shorten this description to save space" No. Preserve descriptive context. If the original says "guaranteed cleanup", keep it.
See rules.md for complete guidelines with examples.
JavaScript/TypeScript conventions: ES modules, Deno runtime, React patterns, async/await, and type handling. Use when writing .ts, .tsx, or .js files, configuring imports, or building React components.
Development tooling: Deno runtime, JSR package registry, deno.json and package.json configuration, and editor settings. Use when setting up projects, choosing packages, or configuring build tools.
Agent roles, safety rules, file ownership, and cross-package change protocol. Use when AI agents work on this codebase, plan multi-package changes, or need boundary guidance.
Security practices: secrets in env vars, input validation, SSRF prevention, error sanitization, and production hardening. Use when handling authentication, secrets, user input, or preparing production deployments.
System architecture: ES modules, hexagonal architecture, project structure, ADRs, and testing strategy. Use when designing systems, planning directory layout, writing ADRs, or reviewing architecture.
CI/CD operations: GitHub Actions, Kubernetes, ArgoCD, and CI timeout configuration. Use when configuring pipelines, debugging deployments, or working with GitHub Actions. Do NOT use for general development workflow.