Your agent gets a briefing, not a guess

Why this is the same problem as the rest of the product

Documentation moved into the repository because that is where the agents are strongest and where engineers already review changes. It arrived without the review loop it used to have, which is what the rest of Notula is for. It also arrived without any convention an assistant could read. An agent opening your repository can see that there are Markdown files. It cannot see that specifications go in specs/, that every one has a status field, that a decision record is never edited after it is accepted, or that moving a document means moving its comment log with it.

None of that is discoverable and all of it is invisible when broken. So Notula writes it down.

What gets written, and where

1. 01

   notula-agents.md, in the repository

   A description of the workspace: its document types, their fields, and the conventions that hold between them. It is a normal file, committed like any other, so it arrives with a clone and every agent on the team reads the same one.

2. 02

   A pointer from the assistant's own file

   For Claude Code, CLAUDE.md gets an @ import, which is three lines and keeps the briefing in one place. Codex, Cursor and Copilot read AGENTS.md and have no import syntax, so the rules that break silently are written into that file directly rather than referenced.

3. 03

   Only for what is actually there

   A machine with neither tool, in a repository with neither file, is never asked. Nothing is written speculatively.

It never overwrites your instructions

CLAUDE.md and AGENTS.md are files you wrote and care about. Notula owns exactly one block between markers inside them and touches nothing else, so your own instructions are never rewritten, reordered or lost. Settings has a Remove that takes the block back out and leaves the rest of the file as it was.

The window is not the only way in

Everything the application does, the notula command does too, which is what an agent uses when it is working without a person watching.

• notula info

  What this workspace is, and what Notula knows about it.

  Run first. A non-zero exit means the directory is not a Notula workspace, and nothing else will work.

• notula mentions ai

  Comments that name someone. Without a handle, whoever is signing.

  A comment naming @ai is addressed to whichever assistant is reading, so this is an assistant's inbox. It answers to its own name too: notula mentions claude.

• notula status

  What is written here that nobody else can see yet.

  Uncommitted and unpushed work, so an agent can tell what it is about to stand on.

@ai is the part worth reading twice. A comment addressed to @ai is addressed to whichever assistant is reading, so a reviewer can leave a question on a paragraph and an agent can answer it without anyone rewriting the workflow around it.

Two of you in one repository

The failure everybody expects is the agent rewriting a document while it is open in front of you. Notula fetches in the background and marks every document that has moved on, with the name of whoever moved it - a person or an assistant, the same either way. The document on your screen never changes on its own. The change waits above it until you take it, and if you both edited the same paragraph it arrives as a choice between two versions rather than as conflict markers.

That is the same mechanism the rest of the product uses for teammates, which is the point: an agent committing to your repository is a teammate committing to your repository.