coding-agent-adapters 0.2.17 → 0.2.19

package/README.md

@@ -161,6 +161,62 @@ aider.getRecommendedModels({ googleKey: 'AIza...' });
 // { powerful: 'gemini/gemini-3-pro', fast: 'gemini/gemini-3-flash' }
 ```
 
+## Workspace Files & Memory
+
+Each coding agent CLI has its own convention for project-level memory files (instructions the agent reads on startup) and config files. Adapters expose this knowledge so orchestration systems can write context to the correct files before spawning an agent.
+
+### Discovering Workspace Files
+
+```typescript
+import { ClaudeAdapter, AiderAdapter } from 'coding-agent-adapters';
+
+const claude = new ClaudeAdapter();
+claude.getWorkspaceFiles();
+// [
+//   { relativePath: 'CLAUDE.md', type: 'memory', autoLoaded: true, format: 'markdown', ... },
+//   { relativePath: '.claude/settings.json', type: 'config', autoLoaded: true, format: 'json', ... },
+//   { relativePath: '.claude/commands', type: 'config', autoLoaded: false, format: 'markdown', ... },
+// ]
+
+claude.memoryFilePath; // 'CLAUDE.md'
+
+const aider = new AiderAdapter();
+aider.memoryFilePath; // '.aider.conventions.md'
+```
+
+### Per-Adapter File Mappings
+
+| Adapter | Memory File | Config | Other |
+|---------|------------|--------|-------|
+| Claude | `CLAUDE.md` | `.claude/settings.json` | `.claude/commands` |
+| Gemini | `GEMINI.md` | `.gemini/settings.json` | `.gemini/styles` |
+| Codex | `AGENTS.md` | `.codex/config.json` | `codex.md` |
+| Aider | `.aider.conventions.md` | `.aider.conf.yml` | `.aiderignore` |
+
+### Writing Memory Files
+
+Use `writeMemoryFile()` to write instructions into a workspace before spawning an agent. Parent directories are created automatically.
+
+```typescript
+const adapter = new ClaudeAdapter();
+
+// Write to the adapter's default memory file (CLAUDE.md)
+await adapter.writeMemoryFile('/path/to/workspace', `# Project Context
+This is a TypeScript monorepo using pnpm workspaces.
+Always run tests before committing.
+`);
+
+// Append to an existing memory file
+await adapter.writeMemoryFile('/path/to/workspace', '\n## Additional Rules\nUse snake_case.\n', {
+  append: true,
+});
+
+// Write to a custom file (e.g., template-specific context for sub-agents)
+await adapter.writeMemoryFile('/path/to/workspace', '# Task-Specific Context\n...', {
+  fileName: 'TASK_CONTEXT.md',
+});
+```
+
 ## Preflight Check
 
 Before spawning agents, check if the required CLIs are installed:
@@ -218,12 +274,18 @@ Extend `BaseCodingAdapter` to create adapters for other coding CLIs:
 
 ```typescript
 import { BaseCodingAdapter } from 'coding-agent-adapters';
+import type { AgentFileDescriptor, InstallationInfo, ModelRecommendations } from 'coding-agent-adapters';
 import type { SpawnConfig, ParsedOutput, LoginDetection, AutoResponseRule } from 'pty-manager';
 
 export class CursorAdapter extends BaseCodingAdapter {
   readonly adapterType = 'cursor';
   readonly displayName = 'Cursor';
 
+  readonly installation: InstallationInfo = {
+    command: 'npm install -g cursor-cli',
+    docsUrl: 'https://cursor.sh/docs',
+  };
+
   // Set to false if the CLI uses text prompts instead of TUI menus
   override readonly usesTuiMenus = false;
 
@@ -231,6 +293,16 @@ export class CursorAdapter extends BaseCodingAdapter {
     { pattern: /accept terms/i, type: 'tos', response: 'y', responseType: 'text', description: 'Accept TOS', safe: true, once: true },
   ];
 
+  getWorkspaceFiles(): AgentFileDescriptor[] {
+    return [
+      { relativePath: '.cursor/rules', description: 'Project rules', autoLoaded: true, type: 'memory', format: 'markdown' },
+    ];
+  }
+
+  getRecommendedModels(): ModelRecommendations {
+    return { powerful: 'claude-sonnet-4', fast: 'gpt-4o-mini' };
+  }
+
   getCommand(): string { return 'cursor'; }
   getArgs(config: SpawnConfig): string[] { return ['--cli']; }
   getEnv(config: SpawnConfig): Record<string, string> { return {}; }

package/dist/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var promises = require('fs/promises');
+var path = require('path');
 var ptyManager = require('pty-manager');
 
 // src/base-coding-adapter.ts
@@ -8,6 +10,17 @@ var BaseCodingAdapter = class extends ptyManager.BaseCLIAdapter {
    * Coding agent CLIs use TUI menus that require arrow-key navigation.
    */
   usesTuiMenus = true;
+  /**
+   * The primary memory file for this CLI (the one it reads for project instructions).
+   * Returns the relativePath of the first 'memory' type file from getWorkspaceFiles().
+   */
+  get memoryFilePath() {
+    const memoryFile = this.getWorkspaceFiles().find((f) => f.type === "memory");
+    if (!memoryFile) {
+      throw new Error(`${this.displayName} adapter has no memory file defined`);
+    }
+    return memoryFile.relativePath;
+  }
   /**
    * Get credentials from config
    */
@@ -101,6 +114,26 @@ Docs: ${this.installation.docsUrl}`
     content = content.trim();
     return content;
   }
+  /**
+   * Write content to this agent's memory file in a workspace.
+   * Creates parent directories as needed.
+   *
+   * @param workspacePath - Absolute path to the workspace root
+   * @param content - The memory/instructions content to write
+   * @param options - Optional: custom fileName, append mode
+   * @returns The absolute path of the written file
+   */
+  async writeMemoryFile(workspacePath, content, options) {
+    const relativePath = options?.fileName ?? this.memoryFilePath;
+    const fullPath = path.join(workspacePath, relativePath);
+    await promises.mkdir(path.dirname(fullPath), { recursive: true });
+    if (options?.append) {
+      await promises.appendFile(fullPath, content, "utf-8");
+    } else {
+      await promises.writeFile(fullPath, content, "utf-8");
+    }
+    return fullPath;
+  }
 };
 
 // src/claude-adapter.ts
@@ -173,6 +206,31 @@ var ClaudeAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "CLAUDE.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".claude/settings.json",
+        description: "Project-scoped settings (allowed tools, permissions)",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      },
+      {
+        relativePath: ".claude/commands",
+        description: "Custom slash commands directory",
+        autoLoaded: false,
+        type: "config",
+        format: "markdown"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "claude-sonnet-4-20250514",
@@ -379,6 +437,31 @@ var GeminiAdapter = class extends BaseCodingAdapter {
       once: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "GEMINI.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".gemini/settings.json",
+        description: "Project-scoped settings (tool permissions, sandbox config)",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      },
+      {
+        relativePath: ".gemini/styles",
+        description: "Custom style/persona definitions directory",
+        autoLoaded: false,
+        type: "config",
+        format: "markdown"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "gemini-3-pro",
@@ -659,6 +742,31 @@ var CodexAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "AGENTS.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: "codex.md",
+        description: "Additional project context file",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".codex/config.json",
+        description: "Project-scoped Codex configuration",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "o3",
@@ -1032,6 +1140,31 @@ var AiderAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: ".aider.conventions.md",
+        description: "Project conventions and instructions read on startup (--read flag)",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".aider.conf.yml",
+        description: "Project-scoped Aider configuration (model, flags, options)",
+        autoLoaded: true,
+        type: "config",
+        format: "yaml"
+      },
+      {
+        relativePath: ".aiderignore",
+        description: "Gitignore-style file listing paths Aider should not edit",
+        autoLoaded: true,
+        type: "rules",
+        format: "text"
+      }
+    ];
+  }
   getRecommendedModels(credentials) {
     if (credentials?.anthropicKey) {
       return {