From 2306894a80784df2034ce1c4361451b8b4a2b1a2 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Tue, 29 Sep 2026 14:52:45 -0500 Subject: [PATCH] Load one instruction source in both harnesses Codex reads AGENTS.md. Claude Code reads CLAUDE.md, and only some of its versions and settings also read AGENTS.md. A CLAUDE.md that only imports AGENTS.md makes both harnesses load the same text. A documentation test keeps it a bare import, and the exact package allowlist keeps it out of the npm tarball. AGENTS.md also gains facts that fresh sessions had to rediscover: the check command and its cost, which sibling repository owns the Service API, the Plan format, and Skill packaging, and when to get an independent review through cross-review from either harness. That review covers what machine consumers such as the Skill depend on: the accepted API-contract range and Plan formats, command names and flags, handled error values, and exit statuses. Human-readable detail text and progress lines are left out, because docs/errors.md tells consumers not to branch on them. Naming all output and errors would cover most CLI changes. In firstdraft, a trigger that broad matched 188 of 250 PRs, and 97 of those recorded no review. --- AGENTS.md | 6 ++++++ CLAUDE.md | 1 + docs/README.md | 1 + test/documentation.test.js | 8 ++++++++ 4 files changed, 16 insertions(+) create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index c94ee0f..ac9653c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,12 @@ Start with `docs/README.md` and follow its task routes. Detailed command semanti handled-error recovery in `docs/errors.md`, living release policy in `RELEASING.md`, and dated release observations in `docs/release-history.md`. When behavior changes, update its owning document in the same change. +- Verify with `npm run check`, which takes about 30 seconds. A fresh checkout needs `npm ci --ignore-scripts` first. +- Sibling repositories: `firstdraft/firstdraft` (private) owns the Service API and Plan format; `firstdraft/skills` + owns the Skill and plugin packaging. +- Changes to the accepted API-contract range, accepted Plan formats, command names or flags, handled `error` values, + or exit statuses get an independent review through cross-review: `codex-review` from Claude Code, `$claude-review` + from Codex. - `firstdraft plan compile` defaults to local output in the current directory. GitHub publication requires `--github`; Codespaces is a fallback. Keep Skill callers and recovery instructions aligned with this boundary. - A coordinated release needs explicit approval once. Reuse an existing approval for its named scope; do not ask diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/docs/README.md b/docs/README.md index 6ccc64e..f7a2dcd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,6 +24,7 @@ evidence for implemented behavior; if they contradict a document, surface the co - [release-history.md](release-history.md) preserves dated release observations. Recheck live tags, package versions, and dist-tags before relying on them operationally; publisher configuration is checked when it changes or fails. - The source repository's `AGENTS.md` routes agent work; it should stay compact rather than duplicate these documents. + Its `CLAUDE.md` only imports `AGENTS.md`, so Claude Code and Codex read the same instructions. ## Retrieval quality diff --git a/test/documentation.test.js b/test/documentation.test.js index 0ca902b..336ef04 100644 --- a/test/documentation.test.js +++ b/test/documentation.test.js @@ -40,6 +40,14 @@ test("public documentation avoids unavailable destinations", () => { } }); +test("Claude Code imports the shared agent instructions", () => { + assert.equal( + readFileSync(path.join(repository, "CLAUDE.md"), "utf8"), + "@AGENTS.md\n", + "CLAUDE.md must only import AGENTS.md so both harnesses read one source", + ); +}); + test("documentation entrypoints stay lean and route every public topic", () => { const entrypointBudgets = new Map([ [path.join(repository, "AGENTS.md"), 2_048],