13 added, 66 removed. Audit A to A.
- # Memofs — Agent Rules
+ # 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.
+ This file is the bootstrap for every agent working in this repo, and it is binding, not advisory. **All project knowledge lives in MemoFS — use MCP tools, not this file.** If something you already believe about this codebase isn't confirmed there, treat it as unverified until MemoFS says otherwise.
- ## MemoFS Memory (REQUIRED)
+ ## MemoFS Memory (**REQUIRED** — no exceptions)
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`.
+ At the **start of every task**, agents **MUST**:
- ## Pointers
+ 1. **Load context** — call the MemoFS `context` tool (e.g. `memofs.context`) with the task description to load core memory, notes, and recall, before your first file read or edit this session.
+ 2. **Look up details** — call the MemoFS `recall` tool (e.g. `memofs.recall`) before acting on anything not already covered by loaded context. If you're not certain it's covered, that counts as "not covered" — call it.
+ 3. **Adhere to memory** — treat constraints, decisions, and references returned as binding. If a task conflicts with them, stop and surface the conflict instead of quietly choosing your own approach.
+ 4. **Persist new facts** — before considering any task finished, call the MemoFS `remember` tool (e.g. `memofs.remember`) for every new fact, decision, or constraint discovered along the way — root causes, interface changes, conventions you had to infer.
- - 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/`
+ **MUST NOT:**
+ - Answer questions about this codebase's conventions, architecture, or past decisions from assumption or general knowledge instead of MemoFS.
+ - Skip step 4 because a task felt too small to be worth persisting.
+ - Continue silently if a MemoFS tool errors or is unavailable — stop and tell the user instead of proceeding without memory.
+ **Before ending any task**, confirm: did anything warrant a `recall` call, and did you make it? Did you learn anything new that needs `remember`? Resolve both before finishing.