From 6979bcaad8ec68d1ef9cc635cd4d473a4fbb9ab8 Mon Sep 17 00:00:00 2001 From: Ryota Murakami Date: Thu, 22 Oct 2026 19:18:59 +0900 Subject: [PATCH 1/2] docs(agents): AGENTS.md is the single entry point; CLAUDE.md removed (owner, 2026-10-22) The owner asked to merge CLAUDE.md into AGENTS.md and delete it. Claude Code (v2.1.281 or later) and Codex both load AGENTS.md as the project instructions, so the pointer file is no longer needed. - AGENTS.md: an opening paragraph says it is the single operational entry point for every coding agent, and that a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the repository or a directory above it would make Claude Code read that file instead; CLAUDE.md leaves /ship's documentation roots. - README.md: Codex and Claude Code load AGENTS.md; the CLAUDE.md sentence goes. - .gitignore: the CLAUDE.md exception goes. --- .gitignore | 3 +-- AGENTS.md | 4 +++- CLAUDE.md | 5 ----- README.md | 2 +- 4 files changed, 5 insertions(+), 9 deletions(-) delete mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 88c86f61f..b2542b89b 100644 --- a/.gitignore +++ b/.gitignore @@ -16,9 +16,8 @@ extension/coverage/ extension/.fallow/ extension/.eslintcache -# Share this project's agent entry points despite user-global ignore rules +# Share this project's agent entry point despite user-global ignore rules !/AGENTS.md -!/CLAUDE.md # Share only the project compaction hook; keep other local Codex state private. !/.codex/ diff --git a/AGENTS.md b/AGENTS.md index 6f0db722c..3f879db66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # codebook agent instructions +This file is the single operational entry point for every coding agent: Codex and Claude Code (v2.1.281 or later) load it as the project instructions. Keep agent instructions here; a `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the repository or a directory above it makes Claude Code read that file instead of this one. + ## Mandatory entry Before planning, implementation or runtime trials: @@ -45,7 +47,7 @@ The driving agent owns state, cycle selection and completion claims; GStack supp **Chain.** One bounded cycle at a time toward the complete product. After each merge, `/spec` (with the plan reviews the scope needs) writes the next cycle's Issue. Work on a `codex/` branch; keep existing edits; reuse a fitting checkout. Each cycle: review by the local CodeRabbit CLI and `open-code-review-delegate`, `/ship` as a PR, required CI, a separate exact-HEAD gate, then the merge as its own step with `--match-head-commit`. A large cycle may use up to three PRs (`cycle100-pt1`, `cycle100-pt2`, …), each passing reviews, CI and the gate alone, merged in order; the Issue closes after the last. Codex automatic review is off: no Codex cloud step. PR bodies carry no `@coderabbitai ignore` (owner, 2026-10-05). -**Delivery parameters.** The merge is a squash merge: `gh pr merge --squash --match-head-commit `. `/ship`'s documentation candidate (`gstack-docs-candidate snapshot`) takes the kept documents as `--docs` roots: AGENTS.md, CHANGELOG.md, CLAUDE.md, PRODUCT_GOAL.md, README.md, `extension/README.md`, `extension/skills/codebook/SKILL.md` and the v9 PNG. CI packages the extension with `node extension/scripts/package.mjs --out artifacts/packages/codebook.vsix` and checks it with `node extension/scripts/check-package.mjs artifacts/packages/codebook.vsix` (`package.yml`). A release commit changes one test line besides the version files and CHANGELOG.md, the expected version in `extension/scripts/tests/package.test.mjs`; `/ship`'s Step 16 counts that edit as release metadata, not as a change to the reviewed tree. +**Delivery parameters.** The merge is a squash merge: `gh pr merge --squash --match-head-commit `. `/ship`'s documentation candidate (`gstack-docs-candidate snapshot`) takes the kept documents as `--docs` roots: AGENTS.md, CHANGELOG.md, PRODUCT_GOAL.md, README.md, `extension/README.md`, `extension/skills/codebook/SKILL.md` and the v9 PNG. CI packages the extension with `node extension/scripts/package.mjs --out artifacts/packages/codebook.vsix` and checks it with `node extension/scripts/check-package.mjs artifacts/packages/codebook.vsix` (`package.yml`). A release commit changes one test line besides the version files and CHANGELOG.md, the expected version in `extension/scripts/tests/package.test.mjs`; `/ship`'s Step 16 counts that edit as release metadata, not as a change to the reviewed tree. **Background work.** `node extension/scripts/watch-background.mjs` (from the directory Claude Code started in, else with `--project `) lists the current Claude Code session's background tasks and subagents (its `CLAUDE_CODE_SESSION_ID`), each with the time of its last output, and marks those silent for more than 20 minutes; a finished or stopped subagent is never marked, a shell's row stays marked after it ended (its task notification is the authority). Stop a review subagent that has written nothing for 20 minutes and dispatch it again on a narrower scope; dispatch a subagent that the API's safety filter stopped again at once, with the same brief, on the fallback model. While waiting longer than a few minutes, tell the owner what is awaited and since when. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 220a47451..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,5 +0,0 @@ -# codebook - -Read and follow [AGENTS.md](AGENTS.md) before planning, implementation, review, or resuming work. - -It links the final product goal (PRODUCT_GOAL.md), says that the active cycle Issue holds the current state, and states the delivery workflow. Keep that single operational entry point; do not duplicate project state here. diff --git a/README.md b/README.md index a0b419411..6fce6dd06 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Until final acceptance begins, actual-editor development verification uses the o | How do development and review work? | [Delivery](AGENTS.md#delivery) | | What is the current design authority? | [Design target](PRODUCT_GOAL.md#design-target) | -Read [AGENTS.md](AGENTS.md) when starting or resuming work. Claude Code also enters through [CLAUDE.md](CLAUDE.md). PRODUCT_GOAL.md owns the outcomes, AGENTS.md the way of working, and the active cycle Issue the state. +Read [AGENTS.md](AGENTS.md) when starting or resuming work; Codex and Claude Code load it as their project instructions. PRODUCT_GOAL.md owns the outcomes, AGENTS.md the way of working, and the active cycle Issue the state. ## Tracking and continuation From 07e3af05f0a79089f2777a2ba7cff6d1a73ee999 Mon Sep 17 00:00:00 2001 From: Ryota Murakami Date: Thu, 22 Oct 2026 19:24:48 +0900 Subject: [PATCH 2/2] docs(readme): name the files that would make Claude Code read another instructions file (CodeRabbit CLI, minor) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6fce6dd06..d12ee4afc 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Until final acceptance begins, actual-editor development verification uses the o | How do development and review work? | [Delivery](AGENTS.md#delivery) | | What is the current design authority? | [Design target](PRODUCT_GOAL.md#design-target) | -Read [AGENTS.md](AGENTS.md) when starting or resuming work; Codex and Claude Code load it as their project instructions. PRODUCT_GOAL.md owns the outcomes, AGENTS.md the way of working, and the active cycle Issue the state. +Read [AGENTS.md](AGENTS.md) when starting or resuming work; Codex loads it as its project instructions, and so does Claude Code while no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` overrides it. PRODUCT_GOAL.md owns the outcomes, AGENTS.md the way of working, and the active cycle Issue the state. ## Tracking and continuation