@cleocode/adapters 2026.5.28 → 2026.5.33

package/dist/providers/claude-code/install.d.ts

@@ -47,17 +47,12 @@ export declare class ClaudeCodeInstallProvider implements AdapterInstallProvider
     /**
      * Ensure CLAUDE.md contains @-references to CLEO instruction files.
      *
-     * Creates CLAUDE.md if it does not exist. Appends any missing references.
+     * Delegates to CAAMP's canonical API which reads the instruction file name
+     * and default references from the provider registry (T1919).
      *
      * @param projectDir - Project root directory
      */
     ensureInstructionReferences(projectDir: string): Promise<void>;
-    /**
-     * Update CLAUDE.md with CLEO @-references.
-     *
-     * @returns true if the file was created or modified
-     */
-    private updateInstructionFile;
     /**
      * Install Claude Code-specific commands to .claude/commands/ in the project.
      *

package/dist/providers/claude-code/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,sBAAsB;CAmD/B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAajG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,sBAAsB;CAmD/B"}

package/dist/providers/cursor/install.d.ts

@@ -53,7 +53,8 @@ export declare class CursorInstallProvider implements AdapterInstallProvider {
     /**
      * Ensure instruction files contain @-references to CLEO.
      *
-     * Updates .cursorrules (legacy) and creates .cursor/rules/cleo.mdc (modern).
+     * Delegates the primary AGENTS.md write to CAAMP's canonical API (T1919) and
+     * also updates cursor-specific MDC + legacy .cursorrules formats.
      *
      * @param projectDir - Project root directory
      */
@@ -68,6 +69,9 @@ export declare class CursorInstallProvider implements AdapterInstallProvider {
     private updateInstructionFiles;
     /**
      * Update legacy .cursorrules file with @-references.
+     *
+     * References are sourced from the CAAMP provider registry (T1919) rather than
+     * a local constant, keeping this adapter in sync with the single source of truth.
      * Only modifies the file if it already exists (does not create it).
      *
      * @returns true if the file was modified
@@ -78,6 +82,7 @@ export declare class CursorInstallProvider implements AdapterInstallProvider {
      *
      * MDC (Markdown Component) format is Cursor's modern rule file format.
      * Each .mdc file in .cursor/rules/ is loaded as a rule set.
+     * References are sourced from the CAAMP provider registry (T1919).
      *
      * @returns true if the file was created or modified
      */

package/dist/providers/cursor/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA2B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAqBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;CAyC/B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA+B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAsBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpE;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IA+BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;CAyC/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.5.28",
+  "version": "2026.5.33",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -15,9 +15,9 @@
     "@ai-sdk/anthropic": "^3.0.69",
     "@ai-sdk/openai": "^2.0.53",
     "ai": "^6.0.168",
-    "@cleocode/caamp": "2026.5.28",
-    "@cleocode/contracts": "2026.5.28",
-    "@cleocode/paths": "2026.5.28"
+    "@cleocode/caamp": "2026.5.33",
+    "@cleocode/contracts": "2026.5.33",
+    "@cleocode/paths": "2026.5.33"
   },
   "license": "MIT",
   "engines": {
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@types/node": "^22.19.15",
     "vitest": "^4.1.4",
-    "@cleocode/playbooks": "2026.5.28"
+    "@cleocode/playbooks": "2026.5.33"
   },
   "repository": {
     "type": "git",

package/src/__tests__/claude-code-adapter.test.ts

@@ -186,18 +186,18 @@ describe('ClaudeCodeInstallProvider — integration', () => {
     expect(content).toContain('@.cleo/memory-bridge.md');
   });
 
-  it('does not duplicate existing references', async () => {
-    // Pre-seed with the dynamically-resolved reference so dedup logic fires
-    const { getCleoTemplatesTildePath } = await import('../providers/shared/paths.js');
-    const injectionRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
-    const existing = `${injectionRef}\n@.cleo/memory-bridge.md\n`;
-    writeFileSync(join(testDir, 'CLAUDE.md'), existing, 'utf-8');
+  it('is idempotent — calling twice does not duplicate the CAAMP block', async () => {
+    // First call creates the CAAMP-managed block
+    await install.ensureInstructionReferences(testDir);
+    const firstContent = readFileSync(join(testDir, 'CLAUDE.md'), 'utf-8');
+    const firstCount = (firstContent.match(/@~\/.+\/CLEO-INJECTION\.md/g) ?? []).length;
+    expect(firstCount).toBe(1);
 
+    // Second call must be idempotent — CAAMP detects existing block and returns 'intact'
     await install.ensureInstructionReferences(testDir);
-    const content = readFileSync(join(testDir, 'CLAUDE.md'), 'utf-8');
-    // Should not have duplicated lines
-    const injectionCount = (content.match(/@~\/.+\/CLEO-INJECTION\.md/g) ?? []).length;
-    expect(injectionCount).toBe(1);
+    const secondContent = readFileSync(join(testDir, 'CLAUDE.md'), 'utf-8');
+    const secondCount = (secondContent.match(/@~\/.+\/CLEO-INJECTION\.md/g) ?? []).length;
+    expect(secondCount).toBe(1);
   });
 
   it('install returns expected shape', async () => {

package/src/providers/claude-code/__tests__/adapter.test.ts

@@ -49,10 +49,21 @@ vi.mock('node:fs', async (importOriginal) => {
 });
 
 vi.mock('node:fs/promises', () => ({
+  mkdir: vi.fn().mockResolvedValue(undefined),
+  readFile: vi.fn().mockResolvedValue(''),
   writeFile: vi.fn().mockResolvedValue(undefined),
   unlink: vi.fn().mockResolvedValue(undefined),
 }));
 
+vi.mock('@cleocode/caamp', () => ({
+  ensureProviderInstructionFile: vi.fn().mockResolvedValue({
+    filePath: '/tmp/test-project/CLAUDE.md',
+    instructFile: 'CLAUDE.md',
+    action: 'added',
+    providerId: 'claude-code',
+  }),
+}));
+
 describe('ClaudeCodeAdapter', () => {
   let adapter: ClaudeCodeAdapter;
 

package/src/providers/claude-code/install.ts

@@ -21,22 +21,12 @@ import {
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import {
   type InstallHookTemplatesResult,
   installProviderHookTemplates,
 } from '../shared/hook-template-installer.js';
-import { getCleoTemplatesTildePath } from '../shared/paths.js';
-
-/**
- * Lines that should appear in CLAUDE.md to reference CLEO.
- * The CLEO-INJECTION.md path is resolved dynamically to support non-default
- * XDG / OS installation locations (T916).
- */
-const INSTRUCTION_REFERENCES = [
-  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
-  '@.cleo/memory-bridge.md',
-];
 
 /** Resolve the commands directory bundled with this adapter. */
 function getAdapterCommandsDir(): string {
@@ -72,10 +62,11 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
     let instructionFileUpdated = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Ensure CLAUDE.md has @-references
-    instructionFileUpdated = this.updateInstructionFile(projectDir);
+    // Step 1: Ensure CLAUDE.md has @-references via CAAMP canonical API (T1919)
+    const instructionResult = await ensureProviderInstructionFile('claude-code', projectDir, {});
+    instructionFileUpdated = instructionResult.action !== 'intact';
     if (instructionFileUpdated) {
-      details.instructionFile = join(projectDir, 'CLAUDE.md');
+      details.instructionFile = instructionResult.filePath;
     }
 
     // Step 2: Install adapter-provided commands to .claude/commands/
@@ -138,48 +129,13 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
   /**
    * Ensure CLAUDE.md contains @-references to CLEO instruction files.
    *
-   * Creates CLAUDE.md if it does not exist. Appends any missing references.
+   * Delegates to CAAMP's canonical API which reads the instruction file name
+   * and default references from the provider registry (T1919).
    *
    * @param projectDir - Project root directory
    */
   async ensureInstructionReferences(projectDir: string): Promise<void> {
-    this.updateInstructionFile(projectDir);
-  }
-
-  /**
-   * Update CLAUDE.md with CLEO @-references.
-   *
-   * @returns true if the file was created or modified
-   */
-  private updateInstructionFile(projectDir: string): boolean {
-    const claudeMdPath = join(projectDir, 'CLAUDE.md');
-    let content = '';
-    let existed = false;
-
-    if (existsSync(claudeMdPath)) {
-      content = readFileSync(claudeMdPath, 'utf-8');
-      existed = true;
-    }
-
-    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
-
-    if (missingRefs.length === 0) {
-      return false;
-    }
-
-    const refsBlock = missingRefs.join('\n');
-
-    if (existed) {
-      // Append missing references
-      const separator = content.endsWith('\n') ? '' : '\n';
-      content = content + separator + refsBlock + '\n';
-    } else {
-      // Create new CLAUDE.md with references
-      content = refsBlock + '\n';
-    }
-
-    writeFileSync(claudeMdPath, content, 'utf-8');
-    return true;
+    await ensureProviderInstructionFile('claude-code', projectDir, {});
   }
 
   /**

package/src/providers/cursor/__tests__/adapter.test.ts

@@ -17,6 +17,7 @@ vi.mock('node:fs', async (importOriginal) => {
     existsSync: vi.fn((path: string) => {
       if (typeof path === 'string' && path.includes('.cursor')) return true;
       if (typeof path === 'string' && path.includes('.cursorrules')) return false;
+      if (typeof path === 'string' && path.includes('AGENTS.md')) return false;
       return false;
     }),
     readFileSync: vi.fn((path: string) => {
@@ -30,6 +31,22 @@ vi.mock('node:fs', async (importOriginal) => {
   };
 });
 
+vi.mock('node:fs/promises', () => ({
+  mkdir: vi.fn().mockResolvedValue(undefined),
+  readFile: vi.fn().mockResolvedValue(''),
+  writeFile: vi.fn().mockResolvedValue(undefined),
+  unlink: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('@cleocode/caamp', () => ({
+  ensureProviderInstructionFile: vi.fn().mockResolvedValue({
+    filePath: '/tmp/test-project/AGENTS.md',
+    instructFile: 'AGENTS.md',
+    action: 'added',
+    providerId: 'cursor',
+  }),
+}));
+
 describe('CursorAdapter', () => {
   let adapter: CursorAdapter;
 

package/src/providers/cursor/install.ts

@@ -18,6 +18,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import {
   type InstallHookTemplatesResult,
@@ -25,16 +26,6 @@ import {
 } from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-/**
- * Lines that should appear in instruction files to reference CLEO.
- * The CLEO-INJECTION.md path is resolved dynamically to support non-default
- * XDG / OS installation locations (T916).
- */
-const INSTRUCTION_REFERENCES = [
-  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
-  '@.cleo/memory-bridge.md',
-];
-
 /**
  * Install provider for Cursor.
  *
@@ -62,8 +53,12 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     let instructionFileUpdated = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Ensure instruction files have @-references
-    instructionFileUpdated = this.updateInstructionFiles(projectDir);
+    // Step 1: Ensure instruction files have @-references via CAAMP canonical API (T1919).
+    // ensureProviderInstructionFile handles the primary AGENTS.md (registry instructFile);
+    // updateInstructionFiles also manages cursor-specific MDC + legacy .cursorrules formats.
+    const instructionResult = await ensureProviderInstructionFile('cursor', projectDir, {});
+    const cursorFilesUpdated = this.updateInstructionFiles(projectDir);
+    instructionFileUpdated = instructionResult.action !== 'intact' || cursorFilesUpdated;
     if (instructionFileUpdated) {
       details.instructionFiles = this.getUpdatedFileList(projectDir);
     }
@@ -105,7 +100,8 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     if (existsSync(rulesPath)) {
       try {
         const content = readFileSync(rulesPath, 'utf-8');
-        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
+        const injectionRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+        if (content.includes(injectionRef) || content.includes('@.cleo/memory-bridge.md')) {
           return true;
         }
       } catch {
@@ -119,11 +115,13 @@ export class CursorInstallProvider implements AdapterInstallProvider {
   /**
    * Ensure instruction files contain @-references to CLEO.
    *
-   * Updates .cursorrules (legacy) and creates .cursor/rules/cleo.mdc (modern).
+   * Delegates the primary AGENTS.md write to CAAMP's canonical API (T1919) and
+   * also updates cursor-specific MDC + legacy .cursorrules formats.
    *
    * @param projectDir - Project root directory
    */
   async ensureInstructionReferences(projectDir: string): Promise<void> {
+    await ensureProviderInstructionFile('cursor', projectDir, {});
     this.updateInstructionFiles(projectDir);
   }
 
@@ -152,6 +150,9 @@ export class CursorInstallProvider implements AdapterInstallProvider {
 
   /**
    * Update legacy .cursorrules file with @-references.
+   *
+   * References are sourced from the CAAMP provider registry (T1919) rather than
+   * a local constant, keeping this adapter in sync with the single source of truth.
    * Only modifies the file if it already exists (does not create it).
    *
    * @returns true if the file was modified
@@ -163,7 +164,11 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     }
 
     let content = readFileSync(rulesPath, 'utf-8');
-    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+    const cursorRefs = [
+      `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+      '@.cleo/memory-bridge.md',
+    ];
+    const missingRefs = cursorRefs.filter((ref) => !content.includes(ref));
 
     if (missingRefs.length === 0) {
       return false;
@@ -180,6 +185,7 @@ export class CursorInstallProvider implements AdapterInstallProvider {
    *
    * MDC (Markdown Component) format is Cursor's modern rule file format.
    * Each .mdc file in .cursor/rules/ is loaded as a rule set.
+   * References are sourced from the CAAMP provider registry (T1919).
    *
    * @returns true if the file was created or modified
    */
@@ -187,6 +193,10 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     const rulesDir = join(projectDir, '.cursor', 'rules');
     const mdcPath = join(rulesDir, 'cleo.mdc');
 
+    const cursorRefs = [
+      `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+      '@.cleo/memory-bridge.md',
+    ];
     const expectedContent = [
       '---',
       'description: CLEO task management protocol references',
@@ -194,7 +204,7 @@ export class CursorInstallProvider implements AdapterInstallProvider {
       'alwaysApply: true',
       '---',
       '',
-      ...INSTRUCTION_REFERENCES,
+      ...cursorRefs,
       '',
     ].join('\n');