Skip to content

docs(agents): turn the root rules into a short map - #214

Merged
yxflc11 merged 2 commits into
mainfrom
codex/claude-agent-map
Oct 9, 2026
Merged

yxflc11 merged 2 commits into
mainfrom
codex/claude-agent-map

Conversation

@yxflc11

@yxflc11 yxflc11 commented Oct 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

First step of the repository cleanup the owner approved after the repository audit. The root rules become a short map that agents can load on every task.

  • AGENTS.md
    • Rewritten from 124 to 76 lines: a table of where things live, the four workflow skills, which checks to run, and the research, security and working rules in short form.
    • Removes pointers to dated records (the C1→C3 upgrade record, migration history).
    • Removes the stale "the active control plane is Python" statement; it now says the control plane is moving to TS by route group under ADR-0050.
    • The Chinese translation is rewritten to match.
  • CLAUDE.md (new) imports AGENTS.md, so Claude Code loads the same map as Codex.
  • .agents/README (en and zh) shrinks to a pointer; the skill table now lives only in the map.
  • docs/REPOSITORY_MAP (en and zh): the header drops history pointers and the stale control-plane statement.
  • Translations. The owner decided to keep Chinese translations only for user-facing docs, so the rule now names that set. README.ja.md and README.pt-BR.md are deleted (both described an older release).
  • Check. check-developer-entrypoints now fails when the root map exceeds 90 lines, or when CLAUDE.md is missing or does not import @AGENTS.md.

No product code changes. Files that open PRs touch are left alone: OPEN_SOURCE_REUSE, the TS migration records and ci-selection.ts (#212), and docs/PLUGINS (#211). Research records and old plans go in a follow-up PR after #212 merges.

Open-source research

  • Research artifact: Claude UI migration: sidebar lifecycle, unread, audit, settings and notifications #108 and docs/decisions/0020-open-source-first-feature-gate.md
  • Selected upstream/standard: The AGENTS.md convention read by Codex, with a CLAUDE.md that imports it for Claude Code; no library involved
  • Version or commit: Node.js 22 built-ins only; no dependency added or changed
  • License: Not applicable; no third-party source added
  • Decision: keep one short root map shared by every agent, with nested rules and CONTRIBUTING for detail, and enforce its size and the CLAUDE.md import in the existing entry check
  • OpenBot-specific gap: the line budget and the import requirement are OpenBot conventions; research, security and product boundaries keep their meaning
  • Source copied or substantially adapted: no

Checks

  • node --test scripts/check-developer-entrypoints.test.ts: 5 pass. The new test covers the over-budget map, a CLAUDE.md without the import, and a missing CLAUDE.md.
  • npm run docs:check: passed for 600 Markdown files.
  • npm run check (lint on tracked paths): passed.

🤖 Generated with Claude Code

yxflc11 and others added 2 commits October 10, 2026 00:26
AGENTS.md goes from 124 to 76 lines:
- where things live;
- the workflow skills;
- the checks to run;
- the research, security and working rules in brief.

The stale "the active control plane is Python" statement and the pointers to dated records are gone.

CLAUDE.md imports the same map. The entry check now enforces a 90-line budget for the root map and requires the CLAUDE.md import.

Chinese translations are now kept only for user-facing docs, so the outdated Japanese and Portuguese READMEs are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yxflc11
yxflc11 merged commit 2825668 into main Oct 9, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant