feat(config): add sourceDir object format for one-source-multi-target sync (#35)

- Support { dir, sourceFile, targetFile } in sourceDir for claude.md
- Enables common/AGENTS.md to sync as both AGENTS.md and CLAUDE.md
- Add getSourceFileOverride/getTargetFileOverride in project-config
- Extend claude-md adapter resolveSource with sourceFileOverride
- Add ResolvedSource.targetName for target filename override
- Update GitRepoSource and DotfileManager to pass/use overrides
- Add tests and documentation

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: lbb00

KNOWLEDGE_BASE.md

@@ -397,6 +397,11 @@ interface ProjectConfig {
 - File-based synchronization for CLAUDE.md-style configuration files.
 - Supports `.md` suffix; resolves `CLAUDE` → `CLAUDE.md` automatically.
 - **User Mode**: `ais claude md add CLAUDE --user` links to `~/.claude/CLAUDE.md`.
+- **sourceDir object format**: Use `common/AGENTS.md` as CLAUDE.md source (one file, multiple targets):
+  ```json
+  { "sourceDir": { "claude": { "md": { "dir": "common", "sourceFile": "AGENTS.md", "targetFile": "CLAUDE.md" } } } }
+  ```
+  Enables syncing the same file to both AGENTS.md (via agentsMd) and CLAUDE.md (via claude-md).
 
 ### 9. Trae Rule Synchronization
 - **Syntax**: `ais trae rules add <ruleName> [alias]`
@@ -687,6 +692,10 @@ ais config repo list
 }
 ```
 
+**sourceDir value formats:**
+- **String** (legacy): `"claude": { "md": ".claude" }` — source directory path
+- **Object**: `"claude": { "md": { "dir": "common", "sourceFile": "AGENTS.md", "targetFile": "CLAUDE.md" } }` — use a different source file and target filename (e.g. map `common/AGENTS.md` → `.claude/CLAUDE.md`)
+
 **Priority Resolution in `getSourceDir()`:**
 
 1. **CLI override** (highest priority) - `-s` parameter, no rootPath prefix
@@ -988,6 +997,32 @@ ais user install
 
 ## Recent Changes
 
+### sourceDir Object Format for One-Source-Multi-Target (2026-03)
+
+**Enables using the same file (e.g. `common/AGENTS.md`) for both AGENTS.md and CLAUDE.md sync.**
+
+**Problem Solved:**
+- Rules repo had `common/AGENTS.md` that should sync to project root as `AGENTS.md` (via agentsMd) and to `.claude/CLAUDE.md` (via claude-md)
+- Previously required duplicate files or manual symlinks
+
+**New sourceDir Object Format:**
+```json
+"claude": {
+  "md": { "dir": "common", "sourceFile": "AGENTS.md", "targetFile": "CLAUDE.md" }
+}
+```
+- `dir`: Source directory (replaces default `.claude`)
+- `sourceFile`: Filename to use as source (e.g. `AGENTS.md` instead of `CLAUDE.md`)
+- `targetFile`: Symlink filename in target (e.g. `CLAUDE.md`)
+
+**Implementation:**
+- `src/project-config.ts` - Added `SourceDirValue` type, `getSourceFileOverride()`, `getTargetFileOverride()`, extended `buildRepoSourceFromNestedStrings` and `getSourceDir()` for object format
+- `src/adapters/claude-md.ts` - Custom `resolveSource` that uses `sourceFileOverride` when set
+- `src/adapters/types.ts` - Extended `resolveSource` signature with optional `options.sourceFileOverride`
+- `src/dotany/types.ts` - Added `targetName` to `ResolvedSource` for target override
+- `src/plugin/git-repo-source.ts` - Pass overrides to resolveSource, return `targetName` when set
+- `src/dotany/manager.ts` - Use `resolved.targetName` when present
+
 ### Command UX Enhancements (2026-03)
 
 - Added Linux-style aliases while keeping backward compatibility:

README.md

@@ -1031,6 +1031,14 @@ Create `ai-rules-sync.json` in your rules repository:
 }
 ```
 
+**Use one file for both AGENTS.md and CLAUDE.md:** If you have `common/AGENTS.md` and want it to sync as both project-root `AGENTS.md` (via `agents-md`) and `.claude/CLAUDE.md` (via `claude md`), use the object format for `claude.md`:
+
+```json
+"claude": {
+  "md": { "dir": "common", "sourceFile": "AGENTS.md", "targetFile": "CLAUDE.md" }
+}
+```
+
 ### Git Commands
 
 **Manage repository directly from CLI:**

README_ZH.md

@@ -1031,6 +1031,14 @@ ais user install
 }
 ```
 
+**同一文件同时作为 AGENTS.md 与 CLAUDE.md：** 若你有 `common/AGENTS.md`，希望它既同步到项目根 `AGENTS.md`（通过 `agents-md`）又同步到 `.claude/CLAUDE.md`（通过 `claude md`），可为 `claude.md` 使用对象格式：
+
+```json
+"claude": {
+  "md": { "dir": "common", "sourceFile": "AGENTS.md", "targetFile": "CLAUDE.md" }
+}
+```
+
 ### Git 命令
 
 **直接从 CLI 管理仓库：**

src/__tests__/claude-md.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { claudeMdAdapter } from '../adapters/claude-md.js';
+import { adapterRegistry } from '../adapters/index.js';
+
+describe('claude-md adapter', () => {
+  it('should have correct basic properties', () => {
+    expect(claudeMdAdapter.name).toBe('claude-md');
+    expect(claudeMdAdapter.tool).toBe('claude');
+    expect(claudeMdAdapter.subtype).toBe('md');
+    expect(claudeMdAdapter.defaultSourceDir).toBe('.claude');
+    expect(claudeMdAdapter.targetDir).toBe('.claude');
+    expect(claudeMdAdapter.mode).toBe('file');
+    expect(claudeMdAdapter.fileSuffixes).toEqual(['.md']);
+  });
+
+  it('should have resolveSource and resolveTargetName hooks', () => {
+    expect(claudeMdAdapter.resolveSource).toBeDefined();
+    expect(claudeMdAdapter.resolveTargetName).toBeDefined();
+  });
+
+  it('should be registered in adapterRegistry', () => {
+    expect(adapterRegistry.get('claude', 'md')).toBe(claudeMdAdapter);
+  });
+
+  describe('resolveSource with sourceFileOverride', () => {
+    let repoDir: string;
+
+    beforeEach(async () => {
+      repoDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ais-claude-md-'));
+    });
+
+    afterEach(async () => {
+      await fs.remove(repoDir);
+    });
+
+    it('should resolve common/AGENTS.md when sourceFileOverride is set', async () => {
+      await fs.ensureDir(path.join(repoDir, 'common'));
+      await fs.writeFile(path.join(repoDir, 'common', 'AGENTS.md'), '# AGENTS.md content');
+
+      const resolved = await claudeMdAdapter.resolveSource!(
+        repoDir,
+        'common',
+        'any-name',
+        { sourceFileOverride: 'AGENTS.md' }
+      );
+
+      expect(resolved.sourceName).toBe('AGENTS.md');
+      expect(resolved.sourcePath).toBe(path.join(repoDir, 'common', 'AGENTS.md'));
+      expect(resolved.suffix).toBe('.md');
+    });
+
+    it('should resolve common/AGENTS.md with nested path', async () => {
+      await fs.ensureDir(path.join(repoDir, 'common'));
+      await fs.writeFile(path.join(repoDir, 'common', 'AGENTS.md'), '# content');
+
+      const resolved = await claudeMdAdapter.resolveSource!(
+        repoDir,
+        'common',
+        'CLAUDE',
+        { sourceFileOverride: 'AGENTS.md' }
+      );
+
+      expect(resolved.sourcePath).toBe(path.join(repoDir, 'common', 'AGENTS.md'));
+    });
+
+    it('should throw when sourceFileOverride points to non-existent file', async () => {
+      await fs.ensureDir(path.join(repoDir, 'common'));
+
+      await expect(
+        claudeMdAdapter.resolveSource!(repoDir, 'common', 'x', { sourceFileOverride: 'MISSING.md' })
+      ).rejects.toThrow(/not found/);
+    });
+
+    it('should use default resolver when no sourceFileOverride', async () => {
+      await fs.ensureDir(path.join(repoDir, '.claude'));
+      await fs.writeFile(path.join(repoDir, '.claude', 'CLAUDE.md'), '# CLAUDE content');
+
+      const resolved = await claudeMdAdapter.resolveSource!(repoDir, '.claude', 'CLAUDE');
+
+      expect(resolved.sourceName).toBe('CLAUDE.md');
+      expect(resolved.sourcePath).toBe(path.join(repoDir, '.claude', 'CLAUDE.md'));
+    });
+  });
+});

src/__tests__/project-config-source-dir.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import fs from 'fs-extra';
 import os from 'os';
 import path from 'path';
-import { getRepoSourceConfig, getSourceDir } from '../project-config.js';
+import { getRepoSourceConfig, getSourceDir, getSourceFileOverride, getTargetFileOverride } from '../project-config.js';
 import type { ProjectConfig, RepoSourceConfig, SourceDirConfig } from '../project-config.js';
 
 describe('project-config source directory resolution', () => {
@@ -79,4 +79,40 @@ describe('project-config source directory resolution', () => {
     const repoConfig = await getRepoSourceConfig(tempDir);
     expect(repoConfig).toEqual({ rootPath: 'project-root' });
   });
+
+  it('should parse sourceDir object format with dir, sourceFile, targetFile', async () => {
+    const config: ProjectConfig = {
+      rootPath: 'rules-root',
+      sourceDir: {
+        claude: {
+          md: { dir: 'common', sourceFile: 'AGENTS.md', targetFile: 'CLAUDE.md' }
+        }
+      }
+    };
+
+    await fs.writeJson(path.join(tempDir, 'ai-rules-sync.json'), config, { spaces: 2 });
+
+    const repoConfig = await getRepoSourceConfig(tempDir);
+    expect(repoConfig.claude?.md).toEqual({ dir: 'common', sourceFile: 'AGENTS.md', targetFile: 'CLAUDE.md' });
+
+    const sourceDir = getSourceDir(repoConfig, 'claude', 'md', '.claude');
+    expect(sourceDir).toBe(path.join('rules-root', 'common'));
+
+    expect(getSourceFileOverride(repoConfig, 'claude', 'md')).toBe('AGENTS.md');
+    expect(getTargetFileOverride(repoConfig, 'claude', 'md')).toBe('CLAUDE.md');
+  });
+
+  it('should return undefined for overrides when sourceDir is string', async () => {
+    const config: ProjectConfig = {
+      sourceDir: {
+        claude: { md: '.claude' }
+      }
+    };
+
+    await fs.writeJson(path.join(tempDir, 'ai-rules-sync.json'), config, { spaces: 2 });
+    const repoConfig = await getRepoSourceConfig(tempDir);
+
+    expect(getSourceFileOverride(repoConfig, 'claude', 'md')).toBeUndefined();
+    expect(getTargetFileOverride(repoConfig, 'claude', 'md')).toBeUndefined();
+  });
 });

src/adapters/base.ts

@@ -24,7 +24,7 @@ export interface AdapterConfig {
     mode: 'directory' | 'file' | 'hybrid';
     fileSuffixes?: string[];
     hybridFileSuffixes?: string[];
-    resolveSource?: (repoDir: string, rootPath: string, name: string) => Promise<any>;
+    resolveSource?: (repoDir: string, rootPath: string, name: string, options?: { sourceFileOverride?: string }) => Promise<any>;
     resolveTargetName?: (name: string, alias?: string, sourceSuffix?: string) => string;
 }
 

src/adapters/claude-md.ts

@@ -1,8 +1,35 @@
-import { SyncAdapter } from './types.js';
+import path from 'path';
+import fs from 'fs-extra';
+import { SyncAdapter, ResolvedSource } from './types.js';
 import { createBaseAdapter, createSingleSuffixResolver, createSuffixAwareTargetResolver } from './base.js';
 
 const SUFFIX = '.md';
 
+/**
+ * Custom resolver that supports sourceFileOverride from rules repo sourceDir.
+ * When sourceDir is { dir: "common", sourceFile: "AGENTS.md" }, resolves common/AGENTS.md
+ * as the source while target remains CLAUDE.md (symlink can have different filename).
+ */
+async function resolveClaudeMdSource(
+  repoDir: string,
+  rootPath: string,
+  name: string,
+  options?: { sourceFileOverride?: string }
+): Promise<ResolvedSource> {
+  if (options?.sourceFileOverride) {
+    const sourcePath = path.join(repoDir, rootPath, options.sourceFileOverride);
+    if (await fs.pathExists(sourcePath)) {
+      return {
+        sourceName: options.sourceFileOverride,
+        sourcePath,
+        suffix: SUFFIX,
+      };
+    }
+    throw new Error(`Source file "${options.sourceFileOverride}" not found at ${path.join(rootPath, options.sourceFileOverride)}`);
+  }
+  return createSingleSuffixResolver(SUFFIX, 'CLAUDE.md')(repoDir, rootPath, name);
+}
+
 /**
  * Adapter for Claude CLAUDE.md file (.claude/CLAUDE.md)
  * Mode: file - links individual .md files from .claude/ directory
@@ -14,6 +41,9 @@ const SUFFIX = '.md';
  * Project mode usage:
  *   ais claude md add CLAUDE
  *   → creates symlink at ./.claude/CLAUDE.md
+ *
+ * Rules repo sourceDir override (use common/AGENTS.md as CLAUDE.md source):
+ *   sourceDir: { claude: { md: { dir: "common", sourceFile: "AGENTS.md" } } }
  */
 export const claudeMdAdapter: SyncAdapter = createBaseAdapter({
   name: 'claude-md',
@@ -25,6 +55,6 @@ export const claudeMdAdapter: SyncAdapter = createBaseAdapter({
   mode: 'file',
   fileSuffixes: [SUFFIX],
 
-  resolveSource: createSingleSuffixResolver(SUFFIX, 'CLAUDE.md'),
+  resolveSource: resolveClaudeMdSource,
   resolveTargetName: createSuffixAwareTargetResolver([SUFFIX])
 });

src/adapters/types.ts

@@ -41,11 +41,13 @@ export interface SyncAdapter {
      * Optional hook to resolve the actual source path.
      * Default behavior: join(repoDir, rootPath, name)
      * For file mode with suffixes, this handles suffix resolution.
+     * @param options.sourceFileOverride - When set (from rules repo sourceDir), use this file instead of name
      */
     resolveSource?(
         repoDir: string,
         rootPath: string,
-        name: string
+        name: string,
+        options?: { sourceFileOverride?: string }
     ): Promise<ResolvedSource>;
 
     /**

src/dotany/manager.ts

@@ -32,10 +32,11 @@ export class DotfileManager {
         // Resolve source
         const resolved = await this.opts.source.resolve(name, { repoUrl, targetDir });
 
-        // Resolve target name (suffix-aware if resolver provided)
-        const targetName = this.opts.resolveTargetName
-            ? this.opts.resolveTargetName(name, alias, resolved.suffix)
-            : (alias || resolved.name);
+        // Resolve target name: use override from source, or suffix-aware resolver, or alias/name
+        const targetName = resolved.targetName
+            ?? (this.opts.resolveTargetName
+                ? this.opts.resolveTargetName(name, alias, resolved.suffix)
+                : (alias || resolved.name));
 
         // Determine target directory
         const targetDirPath = targetDir ? path.normalize(targetDir) : this.opts.targetDir;
@@ -128,9 +129,10 @@ export class DotfileManager {
                 if (this.opts.source.resolveFromManifest) {
                     // Use manifest-aware resolution (supports multi-repo)
                     const resolved = await this.opts.source.resolveFromManifest(entry);
-                    const targetName = this.opts.resolveTargetName
-                        ? this.opts.resolveTargetName(entry.sourceName, alias !== entry.sourceName ? alias : undefined, resolved.suffix)
-                        : (alias !== entry.sourceName ? alias : resolved.name);
+                    const targetName = resolved.targetName
+                        ?? (this.opts.resolveTargetName
+                            ? this.opts.resolveTargetName(entry.sourceName, alias !== entry.sourceName ? alias : undefined, resolved.suffix)
+                            : (alias !== entry.sourceName ? alias : resolved.name));
                     const targetDirPath = entry.meta?.targetDir
                         ? path.normalize(entry.meta.targetDir as string)
                         : this.opts.targetDir;

src/dotany/types.ts

@@ -25,6 +25,8 @@ export interface ResolvedSource {
     path: string;
     /** Detected suffix, if any */
     suffix?: string;
+    /** Override target filename (e.g. when sourceFile maps AGENTS.md -> CLAUDE.md) */
+    targetName?: string;
 }
 
 /** Pluggable manifest persistence interface */