Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

8.8 KB
Raw Blame
/**
 * Layout pin (#321): `AGENTS.md` is the vault's one instruction file.
 *
 * Every agent reads it: Codex and Antigravity natively, Grok once the folder
 * is trusted, Gemini through `.gemini/settings.json`'s `context.fileName`, and
 * Claude Code natively when no `CLAUDE.md` is present. Claude-only guidance
 * lives in `.claude/rules/*.md`, which Claude Code loads beside it.
 *
 * What would quietly undo that:
 * - a `CLAUDE.md` back at the root: Claude Code reads it and skips
 *   `AGENTS.md` without saying so;
 * - a `GEMINI.md` back at the root, or the Gemini setting dropped: Gemini
 *   falls back to looking for `GEMINI.md`;
 * - `AGENTS.md` turned back into a pointer at another file, which Codex
 *   never follows unless told to;
 * - `AGENTS.md` growing past what the agents read: Antigravity cuts it off
 *   silently past ~24,000 bytes (measured), Codex past ~32 KiB.
 */

import { test, describe } from "node:test";
import assert from "node:assert/strict";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { AGENTS_MD_MAX_BYTES } from "../lib/instruction-files.ts";

const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");

describe("AGENTS.md is the one instruction file (#321)", () => {
	const agentsPath = resolve(repoRoot, "AGENTS.md");

	test("AGENTS.md exists and carries the conventions itself, not a pointer to another file", () => {
		assert.ok(existsSync(agentsPath), "AGENTS.md is missing from the vault root");
		const text = readFileSync(agentsPath, "utf-8");
		// Headings every agent needs at the moment of acting (#321: these stay
		// inline because a skipped pointer means a misplaced note or a record
		// never written).
		for (const heading of ["## Vault Structure", "### Note Types", "### Decision Records", "## Write-Correctness Laws", "## Rules"]) {
			assert.ok(text.includes(`\n${heading}\n`), `AGENTS.md lost its "${heading}" section`);
		}
		assert.doesNotMatch(text, /Read `CLAUDE\.md` for all vault conventions/, "AGENTS.md is a pointer to CLAUDE.md again");
	});

	test(`AGENTS.md stays under ${AGENTS_MD_MAX_BYTES} bytes`, () => {
		const size = statSync(agentsPath).size;
		assert.ok(
			size < AGENTS_MD_MAX_BYTES,
			`AGENTS.md is ${size} bytes, at or over the ${AGENTS_MD_MAX_BYTES}-byte threshold. Antigravity silently stops reading it at ~24,000 bytes (and Codex at ~32 KiB). Move a section an agent can safely skip to a file it reads on demand, verbatim, and leave a one-line pointer (#321).`,
		);
	});

	test("AGENTS.md is LF-only, so its size is the same on every checkout", () => {
		// .gitattributes forces eol=lf; a CRLF checkout would add a byte per
		// line (~300) and move the file toward the cap on Windows only.
		assert.ok(!readFileSync(agentsPath, "utf-8").includes("\r"), "AGENTS.md has CRLF line endings");
	});

	test("no CLAUDE.md or GEMINI.md at the vault root", () => {
		// Claude Code reads a CLAUDE.md in place of AGENTS.md, silently.
		assert.ok(!existsSync(resolve(repoRoot, "CLAUDE.md")), "CLAUDE.md is back at the root: Claude Code reads it and skips AGENTS.md");
		assert.ok(!existsSync(resolve(repoRoot, "GEMINI.md")), "GEMINI.md is back at the root: Gemini reads AGENTS.md through .gemini/settings.json instead");
	});

	test(".gemini/settings.json points Gemini at AGENTS.md", () => {
		const settings = JSON.parse(readFileSync(resolve(repoRoot, ".gemini/settings.json"), "utf-8")) as {
			context?: { fileName?: unknown };
		};
		const names = settings.context?.fileName;
		assert.ok(Array.isArray(names) && names.includes("AGENTS.md"), ".gemini/settings.json context.fileName must list AGENTS.md");
	});

	/** The `.claude/rules/*.md` files AGENTS.md's pointers name. */
	const pointerTargets = (): string[] => [
		...new Set([...readFileSync(agentsPath, "utf-8").matchAll(/`(\.claude\/rules\/[\w.-]+\.md)`/g)].map((m) => m[1]!)),
	];
	const SHARED_LINE =
		"Shared section: Claude Code and Grok load it at session start; other agents read it when AGENTS.md points here.";

	test("every rules file AGENTS.md points at exists, is non-empty, and says it is shared", () => {
		const targets = pointerTargets();
		assert.ok(targets.length > 0, "AGENTS.md names no .claude/rules/ file: the moved sections have no pointer");
		for (const t of targets) {
			const p = resolve(repoRoot, t);
			assert.ok(existsSync(p), `AGENTS.md points at ${t}, which does not exist`);
			const text = readFileSync(p, "utf-8");
			assert.ok(text.trim().length > 0, `${t} is empty`);
			assert.equal(text.split("\n")[0], SHARED_LINE, `${t} does not open with the shared-section line`);
		}
	});

	test("every shared rules file is pointed at by AGENTS.md, so no agent but Claude Code and Grok is cut off from it", () => {
		const targets = new Set(pointerTargets());
		const dir = resolve(repoRoot, ".claude/rules");
		for (const f of readdirSync(dir).filter((n) => n.endsWith(".md"))) {
			const shared = readFileSync(resolve(dir, f), "utf-8").startsWith(SHARED_LINE);
			assert.equal(targets.has(`.claude/rules/${f}`), shared, `.claude/rules/${f}: ${shared ? "shared but AGENTS.md never points at it" : "Claude-only but AGENTS.md points at it"}`);
		}
	});

	test("every file AGENTS.md points at is claimed by no removable module, so every module selection installs it", () => {
		// A file claimed by a removable module disappears when that module is
		// deselected, and a Codex-only vault would then follow a pointer to
		// nothing. Shared files must be core: claimed by no removable module.
		const schema = readFileSync(resolve(repoRoot, ".shardmind/shard-schema.yaml"), "utf-8");
		const modulesBlock = schema.slice(schema.indexOf("\nmodules:\n"), schema.indexOf("\nsignals:\n"));
		const modules = modulesBlock.split(/\n  (?=[a-z_]+:\n)/).slice(1);
		// A module's `paths`, written either as a flow list (`paths: ["a/"]`)
		// or as a block list of `- "a/"` lines; the schema uses both.
		const pathsOf = (m: string): string[] => {
			const flow = /\n    paths: \[([^\]]*)\]/.exec(m);
			if (flow) return [...flow[1]!.matchAll(/"([^"]+)"/g)].map((x) => x[1]!);
			const at = m.indexOf("\n    paths:\n");
			if (at < 0) return [];
			const items: string[] = [];
			// Every line until the next key at module level or above; blank
			// lines, comments, a trailing comment or an unquoted item (spaces
			// and all) must not end the list early or cut an item short.
			for (const line of m.slice(at + "\n    paths:\n".length).split("\n")) {
				if (/^ {0,4}[^\s#]/.test(line)) break;
				const item = /^\s+-\s+(?:"([^"]*)"|'([^']*)'|(.*?))\s*(?:#.*)?$/.exec(line);
				if (item) items.push(item[1] ?? item[2] ?? item[3]!);
			}
			return items;
		};
		assert.ok(pathsOf(modules.find((m) => m.startsWith("brain:"))!).includes("brain/"), "pathsOf misreads a flow-style list");
		const claudeList = pathsOf(modules.find((m) => m.startsWith("claude:"))!);
		assert.ok(claudeList.includes(".claude/agents/") && claudeList.includes(".claude-plugin/"), "pathsOf misreads a block list");
		const removablePaths = modules.filter((m) => /\n    removable: true\b/.test(m)).flatMap(pathsOf);
		assert.ok(modules.length > 0, "found no modules in shard-schema.yaml");
		const claims = (path: string, claim: string) => (claim.endsWith("/") ? path.startsWith(claim) : path === claim);
		for (const t of [...pointerTargets(), "AGENTS.md"]) {
			const by = removablePaths.find((c) => claims(t, c));
			assert.equal(by, undefined, `${t} is claimed by a removable module (${by}), so a vault without that module loses it`);
		}
		// And the Claude module, removable or not, claims only the Claude-only files.
		const claude = modules.find((m) => m.startsWith("claude:"))!;
		const claudePaths = pathsOf(claude);
		assert.ok(!claudePaths.includes(".claude/rules/"), "the Claude module claims all of .claude/rules/, shared files included");
		const dir = resolve(repoRoot, ".claude/rules");
		const claudeOnly = readdirSync(dir)
			.filter((f) => f.endsWith(".md") && !readFileSync(resolve(dir, f), "utf-8").startsWith(SHARED_LINE))
			.map((f) => `.claude/rules/${f}`)
			.sort();
		assert.deepEqual(
			claudePaths.filter((p) => p.startsWith(".claude/rules/")).sort(),
			claudeOnly,
			"the Claude module must claim exactly the Claude-only rules files",
		);
	});

	test("every .claude/rules/*.md exists and is non-empty", () => {
		const dir = resolve(repoRoot, ".claude/rules");
		assert.ok(existsSync(dir), ".claude/rules/ is missing: the Claude-only guidance has nowhere to load from");
		const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
		for (const name of ["skills.md", "subagents.md", "memory.md", "hooks-and-mod.md"]) {
			assert.ok(files.includes(name), `.claude/rules/${name} is missing`);
		}
		for (const f of files) {
			assert.ok(readFileSync(resolve(dir, f), "utf-8").trim().length > 0, `.claude/rules/${f} is empty`);
		}
	});
});