An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): default agent docs to AGENTS.md unless --agent claude (#4216)
Joey5a134892a63a
diff --git a/.changeset/agent-docs-default-agents-md.md b/.changeset/agent-docs-default-agents-md.mdnew file mode 100644index 0000000000..82af67211b--- /dev/null+++ b/.changeset/agent-docs-default-agents-md.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx init --features agents` now defaults to creating root `AGENTS.md` — the tool-agnostic standard that Codex/Copilot, Cursor, and most agents read — instead of the Claude-specific `.claude/CLAUDE.md`. Claude output is now opt-in via `--agent claude` (→ `.claude/CLAUDE.md`), and `--agent all` still writes both. Projects with existing agent-doc files are unaffected: init still discovers and updates every file already present, so this only changes the from-scratch default. (#4216)++@josephfarinadiff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjsindex 3d8f2c6d25..e43042bfbc 100644--- a/packages/cli/docs/working-with-ai.doc.mjs+++ b/packages/cli/docs/working-with-ai.doc.mjs@@ -42,13 +42,13 @@ export const docs = {},{type: 'prose',- text: 'If you prefer to target a specific file format:',+ text: 'By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool\'s file instead:',},{type: 'code',lang: 'bash',label: 'Manual options',- code: `npx @astryxdesign/cli init --features agents --agent claude # CLAUDE.md+ code: `npx @astryxdesign/cli init --features agents --agent claude # .claude/CLAUDE.mdnpx @astryxdesign/cli init --features agents --agent cursor # .cursorrulesnpx @astryxdesign/cli init --features agents --agent codex # AGENTS.md (Copilot, Codex, etc.)`,},diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex 257078ec9a..48fbc13917 100644--- a/packages/cli/src/commands/agent-docs.mjs+++ b/packages/cli/src/commands/agent-docs.mjs@@ -12,7 +12,7 @@* - Hermes Agent: .hermes.md or HERMES.md (existing), else AGENTS.md** Auto-detect: discovers existing files and updates them in place.- * Default (no existing files): creates .claude/CLAUDE.md.+ * Default (no existing files): creates AGENTS.md (the tool-agnostic standard).** --agent <tool>: target a specific tool preset (claude, cursor, codex, hermes, all)* --agent-docs-path <path>: explicit file path(s)@@ -511,7 +511,7 @@ export function removeAgentDocs(targetDir) {** Strategy (when no agent/paths specified):* - Discover all existing agent doc files and update them- * - If nothing found, create .claude/CLAUDE.md as default+ * - If nothing found, create AGENTS.md as default (tool-agnostic standard)** @param {string} targetDir* @param {object} [options]@@ -586,14 +586,16 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlreturn written;}- // Nothing exists — create .claude/CLAUDE.md as default (skip if onlyReplace)+ // Nothing exists — create root AGENTS.md as the default (skip if onlyReplace).+ // AGENTS.md is the tool-agnostic standard (Codex/Copilot, Cursor, and most+ // agents read it), so it's the safe default. Claude-specific output is opt-in+ // via `--agent claude` (→ .claude/CLAUDE.md); `--agent all` writes both.if (onlyReplace) return written;- const defaultPath = CLAUDE_DIR_MD;- fs.mkdirSync(path.join(targetDir, '.claude'), {recursive: true});+ const defaultPath = AGENTS_MD;injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {createIfMissing: true,- header: `# CLAUDE.md\n\nProject-specific guidance for AI coding agents.`,+ header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,});written.push(defaultPath);return written;diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjsindex da254035ca..812d5981cf 100644--- a/packages/cli/src/commands/agent-docs.test.mjs+++ b/packages/cli/src/commands/agent-docs.test.mjs@@ -398,18 +398,37 @@ describe('installAgentDocs', () => {);}- it('creates .claude/CLAUDE.md when no agent docs exist', () => {+ it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {setupCorePackage(tmpDir);const written = installAgentDocs(tmpDir);- expect(written).toEqual(['.claude/CLAUDE.md']);- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);- const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');+ expect(written).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);+ // Must NOT create the Claude-specific file by default.+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);+ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');+ expect(content).toContain('# AGENTS.md');expect(content).toContain('<!-- ASTRYX:START -->');});+ it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {+ // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.+ setupCorePackage(tmpDir);+ expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);++ // Explicit Claude: the Claude-specific file, in a fresh project.+ const claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-claude-'));+ setupCorePackage(claudeDir);+ try {+ expect(installAgentDocs(claudeDir, {agent: 'claude'})).toEqual(['.claude/CLAUDE.md']);+ expect(fs.existsSync(path.join(claudeDir, 'AGENTS.md'))).toBe(false);+ } finally {+ fs.rmSync(claudeDir, {recursive: true, force: true});+ }+ });+it('injects into CLAUDE.md at root when it exists', () => {setupCorePackage(tmpDir);fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');@@ -526,12 +545,13 @@ describe('installAgentDocs', () => {expect(content).toContain('Other rules.');});- it('onlyReplace: does not create default .claude/CLAUDE.md when nothing exists', () => {+ it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {setupCorePackage(tmpDir);const written = installAgentDocs(tmpDir, {onlyReplace: true});expect(written).toEqual([]);+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);});});diff --git a/packages/cli/src/commands/interactive-guard.test.mjs b/packages/cli/src/commands/interactive-guard.test.mjsindex fba41b09ed..2fd85690b6 100644--- a/packages/cli/src/commands/interactive-guard.test.mjs+++ b/packages/cli/src/commands/interactive-guard.test.mjs@@ -50,7 +50,7 @@ describe('init is non-interactive by default (no TTY needed)', () => {it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {runCli(['init']);- // init injects into AGENTS.md/CLAUDE.md if present, else creates .claude/CLAUDE.md+ // init injects into existing agent-doc files if present, else creates AGENTS.mdconst candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));expect(doc).toBeTruthy();diff --git a/packages/cli/src/commands/json-contract.test.mjs b/packages/cli/src/commands/json-contract.test.mjsindex 72e6c0cf8d..73364d58f7 100644--- a/packages/cli/src/commands/json-contract.test.mjs+++ b/packages/cli/src/commands/json-contract.test.mjs@@ -61,7 +61,7 @@ afterEach(() => {});describe('--json contract: rejects before side effects', () => {- it('astryx init --json --features agents does not write .claude/CLAUDE.md', () => {+ it('astryx init --json --features agents does not write agent docs', () => {const before = fs.readdirSync(tmpDir);expect(before).toEqual([]);diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsxindex db7fe8a4c0..9c51c2c7e6 100644--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx@@ -7,7 +7,7 @@ import {githubDark} from '@astryxdesign/core/theme/syntax';import {CodeBlock} from '@astryxdesign/core/CodeBlock';const commands = `$ astryx init --features agents-✓ AI agent docs installed → .claude/CLAUDE.md+✓ AI agent docs installed → AGENTS.md$ pnpm astryx component CodeBlock --dense`;export default function CodeBlockTerminal() {