@sayansr26/agent-os 0.5.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "sayan-plugins",
+  "owner": {
+    "name": "Sayan Choudhury",
+    "email": "sayan.choudhury.in@gmail.com"
+  },
+  "metadata": {
+    "description": "Context engineering and agent tooling for Claude Code.",
+    "version": "0.4.0"
+  },
+  "plugins": [
+    {
+      "name": "agent-os",
+      "source": "./plugins/agent-os",
+      "description": "A context-engineered agent system for Claude Code: a durable per-project memory layer, a codebase cartographer that remembers what it mapped, and a coordinated agent set that reads your project's rules instead of hardcoding them.",
+      "category": "workflow",
+      "keywords": [
+        "context-engineering",
+        "memory",
+        "agents",
+        "subagents",
+        "orchestration",
+        "codebase-navigation"
+      ]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,203 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] — 2026-09-15
+
+`agent-os` becomes a cross-tool CLI. The Claude Code plugin is now one target
+among several rather than the whole product.
+
+### Added
+- **`npx @sayansr26/agent-os`** — `init`, `sync`, `check`, `detect`, `audit`,
+  `memory`. Published to npm; no install required. The name is scoped because
+  unscoped `agent-os` collides with an existing `agentos` package under npm's
+  similarity check.
+- **A canonical source** at `.agent-os/` — `config.json`, `AGENTS.md`,
+  `rules/`, `skills/` — compiled outward to each tool in its own schema.
+- **Eight compile targets.** Claude Code and Cline take `paths:` verbatim.
+  Cursor gets `.mdc` with `description`/`globs`/`alwaysApply`. Windsurf gets
+  `trigger:` and a 12,000-character cap. Antigravity gets plain Markdown plus a
+  stated intended scope, because its glob syntax is undocumented and UI-set.
+  Gemini CLI, OpenCode and Kilo have no conditional loading, so they get
+  `AGENTS.md` plus an instructions list, merged into their existing config
+  rather than overwriting it.
+- **`AGENTS.md` for everything else** — read natively by 35+ tools.
+- **Skills compiled to `.agents/skills/`**, which Cursor, Windsurf, Antigravity
+  and Gemini CLI all read, so four vendors are served by one directory. Claude
+  Code and Cline get their own copies.
+- **`check`** exits non-zero when a generated file no longer matches source, so
+  drift fails CI instead of being discovered later.
+- **A compiler self-test** (`npm test`) that scaffolds a throwaway project,
+  compiles all eight targets and asserts each tool's real schema — plus drift
+  detection and merge-not-overwrite. CI additionally installs the packed
+  tarball and runs the CLI from it, because the checkout is not what users get.
+
+### Changed
+- Repository and package renamed from `claude-agent-os` to `agent-os`.
+- Documentation is generic throughout; examples are invented.
+
+### Fixed
+- `check` reported every skill file as drifted immediately after a `sync`. Skill
+  files are read as buffers so a skill can ship a binary asset, rule files are
+  generated as strings, and the two were compared with `!==`. Comparison is now
+  per kind.
+- The audit listed `.cursor/rules/` and `.clinerules` as legacy stores to fold
+  into `CLAUDE.md` and delete, even when `agent-os` had just generated them —
+  advice that would have destroyed the compiled output. Directories whose files
+  all carry the generated banner are now reported as generated, not legacy.
+
+### Notes
+- Hooks are not compiled. Events and control protocols differ per tool with no
+  honest common denominator.
+- The memory layer stays Claude Code only — it is the only target with somewhere
+  to put it. Windsurf has native memories but no documented write path.
+- Roo Code shut down in May 2026 and is not a target. Windsurf is now Devin
+  Desktop, though its `.windsurf/` paths are unchanged.
+
+## [0.4.0] — 2026-09-15
+
+### Added
+- `/agent-os:memory` — inspect, repair and edit what a project remembers: agent
+  memory, Claude Code auto memory and `.claude/rules/`. Script-backed, read-only
+  by default. `--stale` compares each map's `mapped:` date against the last commit
+  touching the file it describes. Arguments: `list`, `show`, `clean`, `forget`,
+  `stale`.
+- `/agent-os:map` — build or refresh the architecture map and per-feature maps,
+  dispatched to `feature-cartographer` so file reads never enter the main
+  conversation. Arguments: `architecture`, `<feature>`, `refresh`.
+- `/agent-os:init` gains `audit` and `settings` arguments.
+- The audit now recommends the extension mechanisms a project could use — nested
+  `CLAUDE.md`, a `PostToolUse` lint hook, a `PreToolUse` guard, the `context7` MCP
+  server, project skills, a project subagent, `Read` deny rules — each gated on
+  evidence in the repository rather than offered as a checklist.
+
+### Notes
+- Three skills with argument dispatch rather than one skill per verb. Skill
+  descriptions load on every turn in every project; eight skills would have cost
+  roughly 2.5 KB resident. Three cost 636 B, taking the plugin from 636 to 786
+  tokens per turn.
+- The settings pass **proposes and never applies**. `permissions.deny` is the
+  guardrail on the agent's own behaviour, and a skill that edits its own
+  guardrails unasked is the thing that setting exists to prevent.
+
+## [0.3.0] — 2026-09-15
+
+The goal is not smaller context. It is that every project **has** an
+architectural memory, so a request like "change the login flow from email to OTP"
+runs off known structure and known conventions instead of rediscovering the
+codebase. Smaller context is the consequence.
+
+### Added
+- **The architecture map.** `_architecture.md` is now first-class in
+  `feature-cartographer`'s memory — stack, layers, where a request enters and how
+  it reaches data, state, network edge, auth model, the files a newcomer reads
+  first. The cartographer reads it before anything else, so a feature question
+  explores a fraction of what it would cold, and must correct it in the same turn
+  when a change contradicts it.
+- **`references/establishing.md`** — build a context layer *from* an existing
+  codebase. The convention-extraction method: find at least three independent
+  examples, read them fully, write down only what all three agree on, note what
+  varies as drift rather than picking a winner, and cite the files. One file is a
+  sample, two is a coincidence, three that agree is a convention.
+- **`references/changing-a-feature.md`** — the workflow for changing code that
+  already exists: cartographer answers *how is it built* → find the nearest
+  precedent → path-scoped rules load themselves → `builder` works from the map and
+  precedent rather than the one-line request → `reviewer` checks against written
+  rules → **the cartographer updates the map in the same turn**.
+- Audit detects stack and source scale, and emits a `MODE`: `TOO-EARLY`,
+  `ESTABLISH`, `MAP`, `MIGRATE` or `MAINTAIN`, which decides what the run is for.
+- Audit recommends the official code intelligence plugin for the detected
+  language, and `Read` deny rules for checked-in generated or vendored paths.
+
+### Changed
+- `init` was a migration tool. On a fresh project it found nothing and had nothing
+  true to write, and the undefined behaviour there invited inventing conventions.
+  `TOO-EARLY` now says so explicitly and builds nothing; `ESTABLISH` builds the
+  layer from the code.
+- The skill defers to Claude Code's own `/init` and `/doctor` for the first
+  `CLAUDE.md` draft instead of duplicating them.
+
+## [0.2.0] — 2026-09-15
+
+### Added
+- `skills/init/scripts/audit.mjs` — the whole audit in one call. The checks are
+  deterministic, so discovering them with a dozen Read and Grep round trips was
+  most of what `init` cost. Read-only, exits 0 on failures so a partial audit
+  still reaches the caller.
+- Detection for unindexed and near-duplicate agent-memory topic files. Found by
+  dogfooding: an agent had written six files for one subject across sessions with
+  only one of them indexed, so five were invisible and kept being rewritten.
+- `scripts/validate-plugin.mjs` and CI. Runs with no auth or network.
+
+### Changed
+- `SKILL.md` 9,563 → 4,391 B. Steps 2–6 moved into `references/`, loaded only
+  when a finding calls for them. A clean project now costs about a tenth of what
+  it did end to end.
+- Agent descriptions rewritten. Descriptions load on every turn in every project;
+  bodies do not. Replacing the `<example>` blocks with dense trigger sentences cut
+  resident context from 4,696 B to 2,545 B — 1,174 → 636 tokens per turn.
+
+### Fixed
+- Agent frontmatter. A scripted edit dropped the closing `---` delimiter in six
+  agents and wrote `—` escapes instead of em dashes, so every field but the
+  filename-derived name was silently dropped at load time. The validator added in
+  this release exists specifically to catch it.
+
+## [0.1.5] — 2026-09-14
+
+### Fixed
+- Every agent now carries an explicit memory protocol: read `MEMORY.md` first,
+  one kebab-case file per subject, index every file in the same turn, merge
+  near-duplicates. Only `feature-cartographer` had this before; the others just
+  said "update your MEMORY.md" and invented a new filename each session.
+
+## [0.1.4] — 2026-09-14
+
+### Added
+- `references/git-permissions.md` — a deny set that blocks every git command
+  which changes the repository while leaving read-only inspection available.
+
+### Changed
+- `init` no longer recommends the broad `Bash(git:*)` form by default. A
+  per-subcommand list is bypassed by `git -C`, `git -c` and
+  `--git-dir`/`--work-tree`, so the reference denies those flag forms too — which
+  is what makes the rest of it hold. What quoting still defeats is documented
+  rather than glossed over.
+
+## [0.1.3] — 2026-09-14
+
+### Changed
+- Documented that `Bash(git commit *)` matches literally on the words before the
+  first `*`, and that deny rules cannot carry allow exceptions.
+
+## [0.1.2] — 2026-09-14
+
+### Changed
+- Skill renamed `memory-bootstrap` → `init`, so `/agent-os:init` works. The
+  description now carries natural-language triggers as well.
+
+## [0.1.1] — 2026-09-14
+
+### Added
+- Machine-layer audit: user-scope agents or skills shadowing plugin components,
+  the same hook registered twice, and whether `permissions.deny` enforces what a
+  `CLAUDE.md` merely states.
+
+## [0.1.0] — 2026-09-14
+
+Initial release: the memory layer, `feature-cartographer`, six coordinated
+agents, the session-resume hook, and the setup skill.
+
+[0.5.0]: https://github.com/sayansr26/agent-os/releases/tag/v0.5.0
+[0.4.0]: https://github.com/sayansr26/agent-os/releases/tag/v0.4.0
+[0.3.0]: https://github.com/sayansr26/agent-os/releases/tag/v0.3.0
+[0.2.0]: https://github.com/sayansr26/agent-os/releases/tag/v0.2.0
+[0.1.5]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.5
+[0.1.4]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.4
+[0.1.3]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.3
+[0.1.2]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.2
+[0.1.1]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.1
+[0.1.0]: https://github.com/sayansr26/agent-os/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sayan Choudhury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# agent-os
+
+**One source of truth for AI coding agent config.** Write your rules once in `.agent-os/`; compile them to Claude Code, Cursor, Cline, Windsurf, Antigravity, Gemini CLI, OpenCode and Kilo — each in the schema that tool actually wants.
+
+[![npm](https://img.shields.io/npm/v/%40sayansr26%2Fagent-os.svg)](https://www.npmjs.com/package/@sayansr26/agent-os)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+```bash
+npx @sayansr26/agent-os init
+```
+
+---
+
+## The problem
+
+Every agent tool invented its own rules format for the same idea.
+
+| Tool | Path | Frontmatter |
+|---|---|---|
+| Claude Code | `.claude/rules/*.md` | `paths: [globs]` |
+| Cline | `.clinerules/*.md` | `paths: [globs]` |
+| Cursor | `.cursor/rules/*.mdc` | `description`, `globs`, `alwaysApply` |
+| Windsurf | `.windsurf/rules/*.md` | `trigger: glob\|always_on`, `globs` |
+| Antigravity | `.agents/rules/*.md` | glob activation is set in the UI — no documented file syntax |
+| Gemini CLI · OpenCode · Kilo | varies | **no conditional loading at all** |
+
+Keep four copies in sync by hand and they drift. Keep one and three tools are wrong.
+
+`agent-os` keeps one, and generates the rest.
+
+---
+
+## How it works
+
+```
+.agent-os/
+├── config.json       which tools to compile for
+├── AGENTS.md         instructions that apply everywhere
+├── rules/
+│   └── api.md        --- description: ... / paths: ["src/api/**"] ---
+└── skills/
+    └── release/SKILL.md
+```
+
+One rule, compiled:
+
+```markdown
+# .agent-os/rules/api.md
+---
+description: API layer conventions
+paths:
+  - "src/api/**"
+---
+One exported function per endpoint. Validate at the boundary.
+```
+
+becomes `.cursor/rules/api.mdc` with `globs:` + `alwaysApply: false`, `.windsurf/rules/api.md` with `trigger: glob`, `.claude/rules/api.md` and `.clinerules/api.md` with `paths:` verbatim, an entry in OpenCode's and Kilo's `instructions` array, and a line under **Path-scoped rules** in a root `AGENTS.md` for everything else.
+
+Skills are simpler: `.agents/skills/` is read by **Cursor, Windsurf, Antigravity and Gemini CLI alike**, so one directory serves four vendors. Claude Code and Cline get their own copies.
+
+---
+
+## Commands
+
+Every command below is `npx @sayansr26/agent-os <command>`. Install it once —
+`npm i -g @sayansr26/agent-os` — and it is just `agent-os <command>`.
+
+| | |
+|---|---|
+| `init` | Detect installed tools, scaffold `.agent-os/`, compile |
+| `sync` | Recompile after editing the source |
+| `check` | Verify nothing drifted. Exits 1 if it has — put this in CI |
+| `detect` | Show which tools this project is set up for |
+| `audit` | Inspect the context layer and report findings |
+| `memory` | Inspect and health-check every memory store |
+
+`--root <dir>` to target another directory, `--dry-run` to preview.
+
+Generated files carry a banner. Edit `.agent-os/`, run `sync`, never edit the output.
+
+---
+
+## What does not port, and why
+
+Being straight about this matters more than the feature list.
+
+**Hooks don't port.** Every tool differs in events *and* control protocol — Cursor returns JSON `permission`, Windsurf uses exit codes, Claude Code uses JSON. There is no honest common denominator, so `agent-os` doesn't invent one.
+
+**Memory doesn't port.** Only Claude Code (auto memory) and Windsurf have native per-session memory. Kilo deprecated its Memory Bank in favour of `AGENTS.md`; Cline's is a community methodology, not a feature. So the architecture map — the thing that makes *"change the login flow from email to OTP"* run off known structure — works in Claude Code and nowhere else yet.
+
+**Antigravity's rules target is best effort.** Its docs state a rule is "simply a Markdown file" and never show frontmatter; glob activation is configured in the Customizations panel. So `agent-os` writes valid Markdown and states the intended scope in a comment, rather than inventing a `globs:` key that may silently do nothing.
+
+---
+
+## The Claude Code plugin
+
+The deeper context-engineering work — the architecture map, seven coordinated agents, per-agent memory, the session-resume hook — ships as a Claude Code plugin in this repo:
+
+```
+/plugin marketplace add sayansr26/agent-os
+/plugin install agent-os@sayan-plugins
+```
+
+That's where the memory layer lives, because Claude Code is currently the only tool with somewhere to put it. The CLI is the cross-tool layer beneath it.
+
+---
+
+## Design rules
+
+Worth stealing even if you never install this.
+
+1. **A rules file without path scoping is an always-on file in disguise.** Scope it or accept the cost.
+2. **Never write down what the code already says.** Directory tours and architecture narration read as valuable, go stale first, and mislead hardest.
+3. **A gotcha is worth ten descriptions.** "X is at Y" is derivable. "X looks like it is at Y but is actually at Z" is not.
+4. **Verbose work belongs in a subagent.** Search results and file dumps should never enter the conversation you are trying to keep.
+5. **Agent memory is project-scoped, not user.** User scope leaks one repo's knowledge into every other repo you open.
+6. **An honest "I could not verify this" beats a confident summary.**
+7. **A rule in an instructions file is context, not enforcement.** If you would be upset when it is broken, it belongs in a permission deny list or a hook as well.
+8. **A deterministic check should be a script, not a conversation.** Line counts and file existence don't need a model to discover them one read at a time.
+9. **Generate, don't duplicate.** Four hand-maintained copies of one convention is four chances to drift.
+
+---
+
+## Requirements
+
+Node 18+. No database, no embeddings, no MCP server, no network calls.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). `node scripts/validate-plugin.mjs` before any PR.
+
+## License
+
+MIT © [Sayan Choudhury](https://github.com/sayansr26)

package/bin/agent-os.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+main(process.argv.slice(2)).catch((e) => {
+  console.error(`\nagent-os: ${e.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sayansr26/agent-os",
+  "version": "0.5.0",
+  "description": "One source of truth for AI coding agent config. Write your rules once; compile them to Claude Code, Cursor, Cline, Windsurf, Antigravity, Gemini CLI, OpenCode and Kilo.",
+  "keywords": [
+    "ai",
+    "agents",
+    "claude-code",
+    "cursor",
+    "cline",
+    "windsurf",
+    "antigravity",
+    "gemini-cli",
+    "opencode",
+    "agents-md",
+    "context-engineering",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/sayansr26/agent-os",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sayansr26/agent-os.git"
+  },
+  "license": "MIT",
+  "author": "Sayan Choudhury",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agent-os": "bin/agent-os.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs",
+    "prepublishOnly": "npm test"
+  }
+}

package/plugins/agent-os/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-os",
+  "description": "A context-engineered agent system for Claude Code. Ships a durable per-project memory layer, a cartographer that maps your codebase once and remembers it, and a coordinated agent set that reads your project's rules rather than hardcoding them.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Sayan Choudhury",
+    "email": "sayan.choudhury.in@gmail.com"
+  },
+  "homepage": "https://github.com/sayansr26/agent-os",
+  "repository": "https://github.com/sayansr26/agent-os",
+  "license": "MIT",
+  "keywords": [
+    "context-engineering",
+    "memory",
+    "agents",
+    "orchestration"
+  ]
+}

package/plugins/agent-os/agents/architect.md

@@ -0,0 +1,77 @@
+---
+name: architect
+description: Design a change before anyone builds it — a new subsystem, a change crossing a service or module boundary, a data model other code will depend on, or a decision expensive to reverse. Produces real options, a recommendation with its cost, and the blast radius. Produces no code.
+tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
+model: inherit
+memory: project
+---
+
+## Memory protocol
+
+Read `MEMORY.md` in your memory directory **before you start**. It is the index
+of everything you have filed here — one line per topic file. If the subject you
+are about to write about is already listed, open that file and **edit it**. Do
+not create a second file under a different name.
+
+When you write:
+
+- **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
+  the `snake_case` variant, never a synonym for a file that already exists.
+  `defect-patterns.md` and `defect_patterns.md` are the same subject and must not
+  both exist.
+- **Add one line to `MEMORY.md` for every topic file you create**, in the same
+  turn. A topic file missing from the index is invisible to you next session: you
+  will not find it, you will write the same knowledge again under a new name, and
+  the two copies will drift.
+- **Keep `MEMORY.md` an index and nothing else.** Only its first 200 lines reach
+  you at startup, so the detail belongs in the topic files.
+- If you find near-duplicate topic files from earlier sessions, merge them into
+  the one whose name fits best, delete the others, and fix the index.
+
+You design. You do not implement, and you do not approve your own designs into
+existence — you hand them to the orchestrator or the user to decide on.
+
+## Ground yourself in this project first
+
+Read `CLAUDE.md`, the relevant `.claude/rules/` files, and your `MEMORY.md`
+before proposing anything. Then read the code that the change would touch — or
+ask for `feature-cartographer` output if it exists.
+
+A design that ignores how this codebase already does things is not a design, it
+is a rewrite proposal in disguise. If you believe the existing pattern is wrong,
+say so explicitly and separately, and let a human decide.
+
+## What a design has to contain
+
+1. **The problem, restated.** In terms of what the system must do, not what the
+   user asked for. If those differ, that is the most valuable thing you will say.
+2. **The constraints that actually bind.** Existing schema, an API you cannot
+   change, a deployment shape, a team convention, a deadline. Name which of these
+   came from the project's rules and which you inferred.
+3. **Two or three real options.** A strawman you obviously dislike is not an
+   option. Each needs its genuine advantage stated.
+4. **A recommendation with its cost.** What this choice makes harder, and what it
+   forecloses. A recommendation with no downside listed has not been thought
+   through.
+5. **The blast radius.** Which files, which modules, which other teams' code.
+6. **What would falsify this.** The thing you would need to learn to change your
+   mind, and how someone could find it out cheaply.
+
+## Keep it proportionate
+
+Most decisions do not need this treatment. If the shape is obvious, say so in two
+lines and hand it straight to the builder — an elaborate design document for a
+one-file change wastes everyone's time and buries the decisions that mattered.
+
+Reach for depth when the decision is expensive to reverse, when it constrains
+code that does not exist yet, or when two reasonable engineers would disagree.
+
+## Record the decision, not the discussion
+
+Write to your `MEMORY.md`: the decision, the date, and the one-line reason. If
+the project keeps ADRs, say so and let the documenter write it there instead —
+do not duplicate a decision into two stores.
+
+Also record decisions that were **rejected** and why. The single most expensive
+thing in a long-lived codebase is re-litigating a settled question because nobody
+wrote down why it was settled.

package/plugins/agent-os/agents/builder.md

@@ -0,0 +1,90 @@
+---
+name: builder
+description: Write or modify application code once the shape is settled. Reads the project's CLAUDE.md and matching .claude/rules/ and enforces them while writing, rather than relying on anyone to remember them. Use for new endpoints, components, modules, or any change to existing logic.
+model: inherit
+memory: project
+---
+
+## Memory protocol
+
+Read `MEMORY.md` in your memory directory **before you start**. It is the index
+of everything you have filed here — one line per topic file. If the subject you
+are about to write about is already listed, open that file and **edit it**. Do
+not create a second file under a different name.
+
+When you write:
+
+- **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
+  the `snake_case` variant, never a synonym for a file that already exists.
+  `defect-patterns.md` and `defect_patterns.md` are the same subject and must not
+  both exist.
+- **Add one line to `MEMORY.md` for every topic file you create**, in the same
+  turn. A topic file missing from the index is invisible to you next session: you
+  will not find it, you will write the same knowledge again under a new name, and
+  the two copies will drift.
+- **Keep `MEMORY.md` an index and nothing else.** Only its first 200 lines reach
+  you at startup, so the detail belongs in the topic files.
+- If you find near-duplicate topic files from earlier sessions, merge them into
+  the one whose name fits best, delete the others, and fix the index.
+
+You write code that looks like it was always part of this codebase.
+
+## The project's rules outrank your instincts
+
+Before writing anything, read `CLAUDE.md` and every `.claude/rules/` file whose
+`paths:` match what you are about to touch. Those rules are the project's
+non-negotiables. Violating one means the task failed and must be redone — they
+are not stylistic preferences you may weigh against your own judgment.
+
+Then read the nearest existing example of what you are about to build and match
+it. Naming, file layout, error handling, how state is reached, how the network is
+called. Consistency with the surrounding code beats every general best practice
+you know.
+
+Your `MEMORY.md` holds what you have learned about building here — the pattern a
+rule file describes but does not show, the helper that already exists so you stop
+writing it again, the registration site that is not where the docs say. Read it.
+
+If a rule and an existing file disagree, the rule wins and the file is a bug.
+Say so; do not silently follow either.
+
+## Writing
+
+- **Edit in place with targeted edits.** Never reconstruct a file from earlier
+  tool output — it may have been truncated and you will silently drop lines.
+- **Read before you write.** Every time, even a file you think you know.
+- **Smallest change that does the job.** Do not refactor adjacent code you were
+  not asked to touch; note it instead and let the user decide.
+- **Land coupled edits together.** An import and its first usage belong in one
+  edit — split across two, the first is an unused import and lint will reject it.
+- **New file or extend an existing one?** Follow the project's size conventions
+  if it has them; otherwise extract rather than growing a file past the point
+  where it is easy to read.
+
+## What you do not do
+
+- Do not run git. Report what changed and let the caller decide.
+- Do not run builds, releases, deploys, or any long-running command unless the
+  project's rules say to, or you were explicitly asked.
+- Do not invent a convention this project has not established. If you had to
+  guess, say which guess you made and why, in your reply — a silent guess becomes
+  a precedent the next agent copies.
+- Do not declare work done. A reviewer sees it first.
+
+## Report
+
+What you changed, file by file, and why. Then, separately and honestly: what you
+were unsure about, what you could not verify, and any rule you had to interpret.
+An accurate account of the uncertain parts is worth more than a confident summary.
+
+## Then write what you learned
+
+Update `MEMORY.md` with things that will still be true for the next build here: a
+helper worth reusing, a pattern the rules imply but do not spell out, a place
+where the obvious approach does not work in this codebase. Skip anything already
+in `CLAUDE.md` or a rule file, anything derivable by reading the code, and
+anything about this specific task.
+
+If you learned something that belongs in the project's own rules rather than your
+private memory, say so in your reply and name the rule file — do not write to
+`.claude/rules/` yourself. The main conversation owns those.