Immutable. This exact content is served forever at /api/v1/blob/cdeab7ed966ffd5f.
# Memofs — Agent Rules This file is the bootstrap for agents working in this repo. **All project knowledge lives in MemoFS** — use MCP tools, not this file. ## MemoFS Memory (REQUIRED) This repo uses MemoFS as its single source of truth for project knowledge. At the **start of every task**, agents MUST: 1. **Load context** — call the MemoFS `context` tool (e.g. `memofs.context`) with the task description to load core memory, notes, and recall. 2. **Look up details** — use the MemoFS `recall` tool (e.g. `memofs.recall`) for specific lookups when context is insufficient. 3. **Adhere to memory** — follow constraints, decisions, and references returned. 4. **Persist new facts** — store discovered facts/decisions via the MemoFS `remember` tool (e.g. `memofs.remember`). ## Behavioral Rules - **Do not** add new npm dependencies without evaluating if an existing package already covers the need - **Do not** use `console.log` in production code — use structured logging or remove it - **Do not** commit secrets, API keys, or environment values — use `.env` files that are gitignored - **Do not** run `pnpm build` during a code-editing session unless you are explicitly validating production correctness - **Do not** add `prettier` — it has been removed; all formatting goes through Biome - **Do not** use `@repo/` for public OSS packages — that scope is for internal tooling only - **Do not** copy-paste tsdown options into new packages — import `pkgConfig` from `@repo/tsdown` instead - **DRY & SSOT everywhere**: Enforce Single Source of Truth and Don't-Repeat-Yourself across the **entire workspace**. Do not duplicate knowledge, logic, constants, or copy that already lives elsewhere — extract to a shared module, type, or constant and import it. - **Always use** the `technical-writer` skill when writing package READMEs and user facing documentation. - **Never commit gitignored files.** Before any `git add` or `git commit`, run `git status` and verify every staged file is tracked. If a file is gitignored (check `.gitignore`), it must never be committed — not even with `git add -f`. When in doubt, `git check-ignore <path>` tells you if a path is ignored. ## General Rules - **If the task is not simple and relates to understanding the existing codebase, always start with docs/CONTEXT.md** - **⚠️ Always use** the `code-review` skill to review your plan implementation after completing the plan (all checkboxes are checked). - **⚠️ Always use** the `security-reviewer` skill to review code for security vulnerabilities after code review. - **⚠️ Do not** add ADR or WF/ticket namings to code documentation. This covers TSDoc/JSDoc on exported APIs and type fields, file-header comments, `describe`/`it` test names, and inline comments. Reference the *behavior or contract* (e.g. "drift detection", "5-minute TTL with manifest persistence", "code anchoring"), never the internal doc number (no `ADR-0022`, `ticket #68`, `Batch-6 default #3`, `§B4`, `ADR 0009 Component 4`). Rationale: ADRs/WFs/tickets live in gitignored paths (`docs/adr/`, `docs/architecture/`, `docs/CONTEXT.md`) that a public reader following such a citation would hit a 404; code docs (`packages/**/*.ts`, including tests) are tracked and public. If a future reader needs the design rationale, they find it via the git-ignored internal docs, not via a code comment that 404s. - **⚠️ Never track internal docs or the cloud app in git.** The following paths are gitignored (`.gitignore`) and must never be `git add`-ed (including `git add -f`): - `docs/adr/` — ADRs (internal architecture decisions) - `docs/architecture/` — decisions log, locked specs, execution plan, archive - `docs/CONTEXT.md` — the working glossary - `apps/cloud/` — the cloud app (the SaaS; does not exist in this OSS repo — lives in the private `memofs-cloud` repo) These are local-only working artifacts. If a file in one of these paths is already tracked, untrack it with `git rm --cached <path>` (keeps the file on disk). Never link to these paths from public/tracked files (READMEs, CONTRIBUTING, GOVERNANCE, package READMEs, `examples/`, `apps/docs/`) — a public reader will hit a 404. ## Agent skills ### Issue tracker GitHub Issues at `memo-fs/memofs` (via the `gh` CLI). Specs and tickets publish as issues; ADRs cited by bare number, never as internal-path links. See `docs/agents/issue-tracker.md`. ### Domain docs Single-context — one `docs/CONTEXT.md` + one `docs/adr/` shared by all 14 packages. Local `docs/architecture/spec-*.md` + `tickets-*.md` are grilling records (gitignored); GitHub Issues are the live contract. See `docs/agents/domain.md`. ## Pointers - Workspace rules: [.agents/rules](./.agents/rules) - [monorepo-structure.md](./.agents/rules/monorepo-structure.md): The official directory structure of the MemoFS monorepo. - [package-naming.md](./.agents/rules/package-naming.md): Scope conventions (`@memofs` vs `@repo`) and package naming requirements. - [package-boundaries.md](./.agents/rules/package-boundaries.md): Rules governing imports and dependencies between different packages and zones (core vs optional). - [package-build-rules.md](./.agents/rules/package-build-rules.md): Guidelines for building packages with `tsdown` and standard export maps. - [adding-new-package.md](./.agents/rules/adding-new-package.md): Checklist/steps for adding a new package to the monorepo. - [code-style.md](./.agents/rules/code-style.md): Biome formatting guidelines, tab indentation, double quotes, and JSDoc requirements. - [typescript-rules.md](./.agents/rules/typescript-rules.md): Coding rules for strict TS, ESM, and type exports. - [technology-stack.md](./.agents/rules/technology-stack.md): Tooling checklist (pnpm, Vitest, Node requirements, etc.). - [development-commands.md](./.agents/rules/development-commands.md): Crucial scripts to install, lint, test, and build. - [git-conventions.md](./.agents/rules/git-conventions.md): Conventions for branching and conventional commit formats. - [testing.md](./.agents/rules/testing.md) / [testing-requirements.md](./.agents/rules/testing-requirements.md): Unit testing instructions using Vitest. - [core-concepts.md](./.agents/rules/core-concepts.md): High-level architectural overview of MemoFS memory layers. - Global skills: `~/.agents/skills/`