Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): generate agent cheat sheet from live CLI metadata (#640)

Joeyb1202f56c762
diff --git a/CLAUDE.md b/CLAUDE.md
index 72fe1bf765..b181ba85b3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -119,3 +119,15 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.
|VERIFY: node internal/stylex-capabilities/scan.mjs
<!-- STYLEX-CAPS:END -->
+
+<!-- XDS-CLI:START -->
+XDS v0.0.4|Always run npx xds component <Name> before writing XDS component code.
+npx xds component <Name> props, usage, examples for any component
+npx xds component --list 95 components by category
+npx xds template <name> [path] scaffold page (blank, login, table)
+npx xds swizzle <Name> eject component source (use --gap to report why)
+npx xds upgrade --apply run version migration codemods
+--detail compact|brief less output | --lang dense|zh translation
+RULE: after @xds/core bump, always run npx xds upgrade --apply
+RULE: when swizzling, always use --gap to report missing capabilities
+<!-- XDS-CLI:END -->
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 00ad6ca072..0fadad73aa 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -1,14 +1,16 @@
/**
- * @file agent-docs command — Install/update AGENTS.md and CLAUDE.md
+ * @file agent-docs — Install/update AGENTS.md and CLAUDE.md
*
- * Injects a compressed XDS component index into AGENTS.md and/or CLAUDE.md.
- * Component docs are served via `npx xds component <name>` instead of
- * being copied into the project.
+ * Generates a CLI cheat sheet from actual command metadata and injects
+ * it into AGENTS.md and/or CLAUDE.md. Format optimized for AI coding
+ * agents (Claude, Copilot, Cursor): one line per command, copy-pasteable,
+ * minimal tokens.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {discoverComponents} from '../lib/component-discovery.mjs';
const AGENTS_MD = 'AGENTS.md';
const CLAUDE_MD = 'CLAUDE.md';
@@ -17,28 +19,69 @@ const XDS_MARKER_START = '<!-- XDS:START -->';
const XDS_MARKER_END = '<!-- XDS:END -->';
/**
- * Compressed index for agent docs.
- * Directs agents to use CLI commands for retrieval.
- * When zh=true, outputs a Chinese Simplified version (placeholder: same content for now).
+ * Generate the agent cheat sheet from live CLI metadata.
+ *
+ * Format C (one-liner per command) chosen after testing three formats
+ * against Claude Opus for AI agent usability (scored 5/5).
*/
-export function generateCompressedIndex(version, {zh = false, lang} = {}) {
- // TODO: Replace with actual Chinese Simplified translations
- // For now, zh mode outputs the same English content as a placeholder
- return `${XDS_MARKER_START}
-[XDS v${version}]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.
-|npx xds --detail compact component <Name> Docs (props, usage) — or --source for code
-|npx xds component --list All components by category
-|npx xds docs principles Design rules, anti-patterns, StyleX patterns
-|npx xds docs tokens Token reference (spacing, color, radius, type)
-|npx xds docs theme Theme system: XDSTheme, custom themes, overrides, nesting
-|npx xds template <name> [path] Scaffold page (blank, table, login)
-|npx xds swizzle <Name> --gap "<reason>" Copy component source for customization + file gap report
-|npx xds gap-report --component <Name> --category <cat> --reason "<why>" File gap without swizzle
-|npx xds upgrade Preview API migrations for your version
-|npx xds upgrade --apply Apply codemods to update breaking API changes
-|RULE: After bumping @xds/core version, ALWAYS run npx xds upgrade --apply to migrate breaking API changes.
-|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.
-${XDS_MARKER_END}`;
+export function generateCompressedIndex(version, {coreDir, zh = false, lang} = {}) {
+ const lines = [XDS_MARKER_START];
+
+ lines.push(`XDS v${version}|Always run npx xds component <Name> before writing XDS component code.`);
+
+ // Component count from live discovery
+ let componentCount = '90+';
+ if (coreDir) {
+ try {
+ const comps = discoverComponents(coreDir);
+ let total = 0;
+ for (const list of Object.values(comps)) total += list.length;
+ if (total > 0) componentCount = String(total);
+ } catch {}
+ }
+
+ lines.push(`npx xds component <Name> props, usage, examples for any component`);
+ lines.push(`npx xds component --list ${componentCount} components by category`);
+
+ // Doc topics from live discovery
+ const docsDir = path.join(CLI_ROOT, 'docs');
+ if (fs.existsSync(docsDir)) {
+ for (const file of fs.readdirSync(docsDir).sort()) {
+ const match = file.match(/^(\w+)\.doc\.mjs$/);
+ if (!match) continue;
+ const topic = match[1];
+
+ let desc = topic;
+ try {
+ const fileContent = fs.readFileSync(path.join(docsDir, file), 'utf-8');
+ const descMatch = fileContent.match(/description:\s*['"](.+?)['"]/);
+ if (descMatch) desc = descMatch[1];
+ } catch {}
+
+ lines.push(`npx xds docs ${topic.padEnd(20)} ${desc}`);
+ }
+ }
+
+ // Templates from live discovery
+ const templatesDir = path.join(CLI_ROOT, 'templates');
+ if (fs.existsSync(templatesDir)) {
+ const templates = fs.readdirSync(templatesDir, {withFileTypes: true})
+ .filter(e => e.isDirectory())
+ .map(e => e.name)
+ .sort();
+ if (templates.length > 0) {
+ lines.push(`npx xds template <name> [path] scaffold page (${templates.join(', ')})`);
+ }
+ }
+
+ lines.push(`npx xds swizzle <Name> eject component source (use --gap to report why)`);
+ lines.push(`npx xds upgrade --apply run version migration codemods`);
+ lines.push(`--detail compact|brief less output | --lang dense|zh translation`);
+ lines.push(`RULE: after @xds/core bump, always run npx xds upgrade --apply`);
+ lines.push(`RULE: when swizzling, always use --gap to report missing capabilities`);
+ lines.push(XDS_MARKER_END);
+
+ return lines.join('\n');
}
/**
@@ -98,7 +141,7 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal
*/
export function injectAgentsMd(targetDir, version, {zh = false, lang} = {}) {
const agentsPath = path.join(targetDir, AGENTS_MD);
- const compressedIndex = generateCompressedIndex(version, {zh, lang});
+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});
injectXdsBlock(agentsPath, compressedIndex, {
createIfMissing: true,
header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
@@ -113,7 +156,7 @@ export function injectAgentsMd(targetDir, version, {zh = false, lang} = {}) {
*/
export function injectClaudeMd(targetDir, version, {zh = false, lang} = {}) {
const claudePath = path.join(targetDir, CLAUDE_MD);
- const compressedIndex = generateCompressedIndex(version, {zh, lang});
+ const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});
return injectXdsBlock(claudePath, compressedIndex);
}
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index d02ea33301..32938e2211 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -27,7 +27,7 @@ afterEach(() => {
describe('generateCompressedIndex', () => {
it('includes the version number', () => {
const result = generateCompressedIndex('1.2.3');
- expect(result).toContain('[XDS v1.2.3]');
+ expect(result).toContain('XDS v1.2.3');
expect(result).toContain('<!-- XDS:START -->');
expect(result).toContain('<!-- XDS:END -->');
});
@@ -41,7 +41,7 @@ describe('generateCompressedIndex', () => {
const result = generateCompressedIndex('1.0.0');
expect(result).toContain('npx xds upgrade');
expect(result).toContain('npx xds upgrade --apply');
- expect(result).toContain('ALWAYS run npx xds upgrade --apply to migrate breaking API changes');
+ expect(result).toContain('after @xds/core bump, always run npx xds upgrade --apply');
});
});
@@ -115,7 +115,7 @@ describe('injectAgentsMd', () => {
const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
expect(content).toContain('# AGENTS.md');
expect(content).toContain('<!-- XDS:START -->');
- expect(content).toContain('[XDS v1.0.0]');
+ expect(content).toContain('XDS v1.0.0');
expect(content).toContain('<!-- XDS:END -->');
});
@@ -135,7 +135,7 @@ More stuff.
injectAgentsMd(tmpDir, '2.0.0');
const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('[XDS v2.0.0]');
+ expect(content).toContain('XDS v2.0.0');
expect(content).not.toContain('old content');
expect(content).toContain('Some content.');
expect(content).toContain('More stuff.');
@@ -153,7 +153,7 @@ Existing agent docs.
const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
expect(content).toContain('Existing agent docs.');
expect(content).toContain('<!-- XDS:START -->');
- expect(content).toContain('[XDS v1.0.0]');
+ expect(content).toContain('XDS v1.0.0');
});
});
@@ -168,7 +168,7 @@ describe('injectClaudeMd', () => {
expect(content).toContain('# Claude Config');
expect(content).toContain('Existing rules.');
expect(content).toContain('<!-- XDS:START -->');
- expect(content).toContain('[XDS v1.0.0]');
+ expect(content).toContain('XDS v1.0.0');
});
it('does not create CLAUDE.md when it does not exist', () => {
@@ -192,7 +192,7 @@ Other rules.
injectClaudeMd(tmpDir, '2.0.0');
const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(content).toContain('[XDS v2.0.0]');
+ expect(content).toContain('XDS v2.0.0');
expect(content).not.toContain('old content');
expect(content).toContain('Other rules.');
});