@intellectronica/ruler 0.2.18 → 0.3.0

package/README.md

@@ -1,11 +1,27 @@
 # Ruler: Centralise Your AI Coding Assistant Instructions
 
-[![CI](https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg)](https://github.com/intellectronica/ruler/actions/workflows/ci.yml)
-[![npm version](https://badge.fury.io/js/%40intellectronica%2Fruler.svg)](https://badge.fury.io/js/%40intellectronica%2Fruler)
-![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-
-- **GitHub**: [intellectronica/ruler](https://github.com/intellectronica/ruler)
-- **NPM**: [@intellectronica/ruler](https://www.npmjs.com/package/@intellectronica/ruler)
+<table style="width:100%">
+  <tr>
+    <td style="vertical-align: top;">
+      <p>
+        <a href="https://github.com/intellectronica/ruler/actions/workflows/ci.yml"><img src="https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+        <a href="https://www.npmjs.com/package/@intellectronica/ruler"><img src="https://badge.fury.io/js/%40intellectronica%2Fruler.svg" alt="npm version"></a>
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+      </p>
+      <ul>
+        <li><strong>GitHub</strong>: <a href="https://github.com/intellectronica/ruler">intellectronica/ruler</a></li>
+        <li><strong>NPM</strong>: <a href="https://www.npmjs.com/package/@intellectronica/ruler">@intellectronica/ruler</a></li>
+      </ul>
+      <hr />
+      <p>
+        <em>Animation by <a href="https://isaacflath.com/">Isaac Flath</a> of <strong><a href="https://elite-ai-assisted-coding.dev/">Elite AI-Assisted Coding</a></strong></em> ➡︎
+      </p>
+    </td>
+    <td style="vertical-align: top; width:33%;">
+      <img src="img/ruler-short.gif" alt="Ruler demo" style="width:300px; height:auto; display:block;" />
+    </td>
+  </tr>
+</table>
 
 ---
 
@@ -36,24 +52,30 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 
 ## Supported AI Agents
 
-| Agent            | Rules File(s)                                    | MCP Configuration                                   |
+| Agent            | Rules File(s)                                    | MCP Configuration / Notes                           |
 | ---------------- | ------------------------------------------------ | --------------------------------------------------- |
+| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)   |
 | GitHub Copilot   | `.github/copilot-instructions.md`                | `.vscode/mcp.json`                                  |
 | Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                         |
-| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`, `~/.codex/config.json`        |
+| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                                |
 | Jules            | `AGENTS.md`                                      | -                                                   |
-| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`, `~/.cursor/mcp.json`            |
-| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | `~/.codeium/windsurf/mcp_config.json`               |
+| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`                                  |
+| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | -                                                   |
 | Cline            | `.clinerules`                                    | -                                                   |
-| Aider            | `ruler_aider_instructions.md`, `.aider.conf.yml` | `.mcp.json`                                         |
+| Amp              | `AGENTS.md`                                      | -                                                   |
+| Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                         |
 | Firebase Studio  | `.idx/airules.md`                                | -                                                   |
-| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`                            |
-| Gemini CLI       | `GEMINI.md`                                      | `.gemini/settings.json`                             |
+| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`  |
+| Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                             |
 | Junie            | `.junie/guidelines.md`                           | -                                                   |
 | AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                             |
 | Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                                |
-| OpenCode         | `AGENTS.md`                                      | `opencode.json`, `~/.config/opencode/opencode.json` |
+| opencode         | `AGENTS.md`                                      | `opencode.json`  |
 | Goose            | `.goosehints`                                    | -                                                   |
+| Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                               |
+| Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME)    |
+| Warp             | `WARP.md`                                        | -                                                   |
+| Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | -                                                   |
 
 ## Getting Started
 
@@ -80,10 +102,10 @@ npx @intellectronica/ruler apply
 1. Navigate to your project's root directory
 2. Run `ruler init`
 3. This creates:
-   - `.ruler/` directory
-   - `.ruler/instructions.md`: A starter Markdown file for your rules
-   - `.ruler/ruler.toml`: The main configuration file for Ruler
-   - `.ruler/mcp.json`: An example MCP server configuration
+  - `.ruler/` directory
+  - `.ruler/AGENTS.md`: The primary starter Markdown file for your rules
+  - `.ruler/ruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler/mcp.json` no longer scaffolded)
+  - (Optional legacy fallback) If you previously used `.ruler/instructions.md`, it is still respected when `AGENTS.md` is absent. (The prior runtime warning was removed.)
 
 Additionally, you can create a global configuration to use when no local `.ruler/` directory is found:
 
@@ -99,11 +121,18 @@ The global configuration will be created to `$XDG_CONFIG_HOME/ruler` (default: `
 
 This is your central hub for all AI agent instructions:
 
-- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/ruler` and alphabetically concatenated
+- **Primary File Order & Precedence**:
+  1. A repository root `AGENTS.md` (outside `.ruler/`) if present (highest precedence, prepended)
+  2. `.ruler/AGENTS.md` (new default starter file)
+  3. Legacy `.ruler/instructions.md` (only if `.ruler/AGENTS.md` absent; no longer emits a deprecation warning)
+  4. Remaining discovered `.md` files under `.ruler/` (and subdirectories) in sorted order
+- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/ruler` and concatenated in the order above
 - **Concatenation Marker**: Each file's content is prepended with `--- Source: <relative_path_to_md_file> ---` for traceability
 - **`ruler.toml`**: Master configuration for Ruler's behavior, agent selection, and output paths
 - **`mcp.json`**: Shared MCP server settings
 
+This ordering lets you keep a short, high-impact root `AGENTS.md` (e.g. executive project summary) while housing detailed guidance inside `.ruler/`.
+
 ### Best Practices for Rule Files
 
 **Granularity**: Break down complex instructions into focused `.md` files:
@@ -150,7 +179,7 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 | Option                         | Description                                                                                                                                                |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                   |
-| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, augmentcode, kilocode) |
+| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, augmentcode, kilocode, warp) |
 | `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                           |
 | `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true)                                                                                                  |
 | `--no-mcp`                     | Disable applying MCP server configurations                                                                                                                 |
@@ -180,6 +209,12 @@ ruler apply --agents copilot,claude
 ruler apply --agents firebase
 ```
 
+**Apply rules only to Warp:**
+
+```bash
+ruler apply --agents warp
+```
+
 **Use a specific configuration file:**
 
 ```bash
@@ -222,7 +257,7 @@ ruler revert [options]
 | Option                         | Description                                                                                                                                             |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                |
-| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode) |
+| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, warp) |
 | `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                        |
 | `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                             |
 | `--dry-run`                    | Preview changes without actually reverting files                                                                                                        |
@@ -281,6 +316,21 @@ enabled = true
 # Global merge strategy: 'merge' or 'overwrite' (default: 'merge')
 merge_strategy = "merge"
 
+# --- MCP Server Definitions ---
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+
+[mcp_servers.git]
+command = "npx" 
+args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
+
+[mcp_servers.remote_api]
+url = "https://api.example.com"
+
+[mcp_servers.remote_api.headers]
+Authorization = "Bearer your-token"
+
 # --- Global .gitignore Configuration ---
 [gitignore]
 # Enable/disable automatic .gitignore updates (default: true)
@@ -297,7 +347,7 @@ output_path = "CLAUDE.md"
 
 [agents.aider]
 enabled = true
-output_path_instructions = "ruler_aider_instructions.md"
+output_path_instructions = "AGENTS.md"
 output_path_config = ".aider.conf.yml"
 
 # OpenAI Codex CLI agent and MCP config
@@ -337,6 +387,10 @@ enabled = false
 [agents.kilocode]
 enabled = true
 output_path = ".kilocode/rules/ruler_kilocode_instructions.md"
+
+[agents.warp]
+enabled = true
+output_path = "WARP.md"
 ```
 
 ### Configuration Precedence
@@ -349,9 +403,36 @@ output_path = ".kilocode/rules/ruler_kilocode_instructions.md"
 
 MCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.
 
-### `.ruler/mcp.json`
+### TOML Configuration (Recommended)
+
+You can now define MCP servers directly in `ruler.toml` using the `[mcp_servers.<name>]` syntax:
+
+```toml
+# Global MCP behavior
+[mcp]
+enabled = true
+merge_strategy = "merge"  # or "overwrite"
+
+# Local (stdio) server
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+
+[mcp_servers.filesystem.env]
+API_KEY = "your-api-key"
+
+# Remote server
+[mcp_servers.search]
+url = "https://mcp.example.com"
+
+[mcp_servers.search.headers]
+Authorization = "Bearer your-token"
+"X-API-Version" = "v1"
+```
+
+### Legacy `.ruler/mcp.json` (Deprecated)
 
-Define your project's MCP servers:
+For backward compatibility, you can still use the JSON format; a warning is issued encouraging migration to TOML. The file is no longer created during `ruler init`.
 
 ```json
 {
@@ -372,8 +453,37 @@ Define your project's MCP servers:
 }
 ```
 
+### Configuration Precedence
+
+When both TOML and JSON configurations are present:
+1. **TOML servers take precedence** over JSON servers with the same name
+2. **Servers are merged** from both sources (unless using overwrite strategy)
+3. **Deprecation warning** is shown encouraging migration to TOML (warning shown once per run)
+
+### Server Types
+
+**Local/stdio servers** require a `command` field:
+```toml
+[mcp_servers.local_server]
+command = "node"
+args = ["server.js"]
+
+[mcp_servers.local_server.env]
+DEBUG = "1"
+```
+
+**Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):
+```toml
+[mcp_servers.remote_server]  
+url = "https://api.example.com"
+
+[mcp_servers.remote_server.headers]
+Authorization = "Bearer token"
+```
+
+Ruler uses this configuration with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.
 
-Ruler uses this file with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.
+**Home Directory Safety:** Ruler never writes MCP configuration files outside your project root. Any historical references to user home directories (e.g. `~/.codeium/windsurf/mcp_config.json` or `~/.zed/settings.json`) have been removed; only project-local paths are targeted.
 
 **Note for OpenAI Codex CLI:** To apply the local Codex CLI MCP configuration, set the `CODEX_HOME` environment variable to your project’s `.codex` directory:
 ```bash
@@ -391,7 +501,7 @@ Ruler automatically manages your `.gitignore` file to keep generated agent confi
 - Preserves existing content outside this block
 - Sorts paths alphabetically and uses relative POSIX-style paths
 
-### Example `.gitignore` Section
+### Example `.gitignore` Section (sample - actual list depends on enabled agents)
 
 ```gitignore
 # Your existing rules
@@ -406,7 +516,7 @@ node_modules/
 .windsurf/rules/ruler_windsurf_instructions.md
 AGENTS.md
 CLAUDE.md
-ruler_aider_instructions.md
+AGENTS.md
 # END Ruler Generated Files
 
 dist/
@@ -428,7 +538,7 @@ cd your-project
 ruler init
 
 # Edit the generated files
-# - Add your coding guidelines to .ruler/instructions.md
+# - Add your coding guidelines to .ruler/AGENTS.md (or keep adding additional .md files)
 # - Customize .ruler/ruler.toml if needed
 
 # Apply rules to all AI agents
@@ -546,8 +656,20 @@ A: Ruler creates backups with `.bak` extension before overwriting any existing f
 **Q: Can I run Ruler in CI/CD pipelines?**
 A: Yes! Use `ruler apply --no-gitignore` in CI to avoid modifying `.gitignore`. See the GitHub Actions example above.
 
-**Q: How do I migrate from version 0.1.x to 0.2.0?**
-A: Version 0.2.0 is backward compatible. Your existing `.ruler/` directory and `ruler.toml` will continue to work. New features like verbose logging and improved error messages are opt-in.
+**Q: How do I migrate from older versions using `instructions.md`?**
+A: Simply rename `.ruler/instructions.md` to `.ruler/AGENTS.md` (recommended). If you keep the legacy file and omit `AGENTS.md`, Ruler will still use it (without emitting the old deprecation warning). Having both causes `AGENTS.md` to take precedence; the legacy file is still concatenated afterward.
+
+**Q: How does OpenHands MCP propagation classify servers?**
+A: Local stdio servers become `stdio_servers`. Remote URLs containing `/sse` are classified as `sse_servers`; others become `shttp_servers`. Bearer tokens in an `Authorization` header are extracted into `api_key` where possible.
+
+**Q: Where is Zed configuration written now?**
+A: Ruler writes a `settings.json` in the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: "custom"`.
+
+**Q: What changed about MCP initialization?**
+A: `ruler init` now only adds example MCP server sections to `ruler.toml` instead of creating `.ruler/mcp.json`. The JSON file is still consumed if present, but TOML servers win on name conflicts.
+
+**Q: Is Kiro supported?**
+A: Yes. Kiro receives concatenated rules at `.kiro/steering/ruler_kiro_instructions.md`.
 
 ## Development
 
@@ -602,5 +724,43 @@ MIT
 
 ---
 
+## Development and Testing
+
+### Running Tests
+
+The project includes comprehensive test coverage with unit, integration, and end-to-end tests:
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run integration tests specifically
+npm run test:integration
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Integration Testing
+
+The project includes comprehensive integration tests that validate the complete CLI workflow:
+
+- **`npm run test:integration`**: Runs a full end-to-end integration test that:
+  1. Creates a temporary test directory
+  2. Runs `ruler init` to set up the initial structure
+  3. Creates custom `ruler.toml` with MCP servers (both stdio and remote)
+  4. Creates sample `AGENTS.md` and additional markdown files for concatenation
+  5. Runs `ruler apply` to generate all agent configuration files
+  6. Inspects and validates all generated files contain expected content
+  7. Outputs the content of all generated files for manual verification
+  8. Validates MCP server configurations were properly applied
+
+This integration test ensures the entire CLI workflow functions correctly and can be used for manual testing or CI validation.
+
+---
+
 © Eleanor Berger  
 [ai.intellectronica.net](https://ai.intellectronica.net/)

package/dist/agents/AbstractAgent.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractAgent = void 0;
+const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+/**
+ * Abstract base class for agents that write to a single configuration file.
+ * Implements common logic for applying ruler configuration.
+ */
+class AbstractAgent {
+    /**
+     * Applies the concatenated ruler rules to the agent's configuration.
+     * This implementation handles the common pattern of:
+     * 1. Determining the output path
+     * 2. Ensuring the parent directory exists
+     * 3. Backing up the existing file
+     * 4. Writing the new content
+     */
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
+    agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
+        await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+    }
+    /**
+     * Returns the specific key to be used for the server object in MCP JSON.
+     * Defaults to 'mcpServers' if not overridden.
+     */
+    getMcpServerKey() {
+        return 'mcpServers';
+    }
+    /**
+     * Returns whether this agent supports MCP STDIO servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpStdio() {
+        return false;
+    }
+    /**
+     * Returns whether this agent supports MCP remote servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpRemote() {
+        return false;
+    }
+}
+exports.AbstractAgent = AbstractAgent;

package/dist/agents/AgentsMdAgent.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsMdAgent = void 0;
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+const AbstractAgent_1 = require("./AbstractAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+/**
+ * Pseudo-agent that ensures the concatenated rules are written to root-level `AGENTS.md`.
+ * Does not participate in MCP propagation. Idempotent: only writes (and creates a backup)
+ * when content differs from existing file.
+ */
+class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
+    getIdentifier() {
+        return 'agentsmd';
+    }
+    getName() {
+        return 'AgentsMd';
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, 'AGENTS.md');
+    }
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
+    agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
+        // Read existing content if present and skip write if identical
+        let existing = null;
+        try {
+            existing = await fs_1.promises.readFile(absolutePath, 'utf8');
+        }
+        catch {
+            existing = null;
+        }
+        if (existing !== null && existing === concatenatedRules) {
+            // No change; skip backup/write for idempotency
+            return;
+        }
+        // Backup (only if file existed) then write new content
+        await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+    }
+    getMcpServerKey() {
+        // No MCP configuration for this pseudo-agent
+        return '';
+    }
+}
+exports.AgentsMdAgent = AgentsMdAgent;

package/dist/agents/AiderAgent.js

@@ -35,25 +35,32 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiderAgent = void 0;
 const path = __importStar(require("path"));
+const AgentsMdAgent_1 = require("./AgentsMdAgent");
 const FileSystemUtils_1 = require("../core/FileSystemUtils");
 const fs = __importStar(require("fs/promises"));
 const yaml = __importStar(require("js-yaml"));
 /**
- * Aider agent adapter (stub implementation).
+ * Aider agent adapter that uses AGENTS.md for instructions and .aider.conf.yml for configuration.
  */
 class AiderAgent {
+    constructor() {
+        this.agentsMdAgent = new AgentsMdAgent_1.AgentsMdAgent();
+    }
     getIdentifier() {
         return 'aider';
     }
     getName() {
         return 'Aider';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
-        const mdPath = agentConfig?.outputPathInstructions ??
-            this.getDefaultOutputPath(projectRoot).instructions;
-        await (0, FileSystemUtils_1.backupFile)(mdPath);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(mdPath, concatenatedRules);
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+        // First perform idempotent AGENTS.md write via composed AgentsMdAgent
+        await this.agentsMdAgent.applyRulerConfig(concatenatedRules, projectRoot, null, {
+            // Preserve explicit outputPath precedence semantics if provided.
+            outputPath: agentConfig?.outputPath ||
+                agentConfig?.outputPathInstructions ||
+                undefined,
+        });
+        // Now handle .aider.conf.yml configuration
         const cfgPath = agentConfig?.outputPathConfig ??
             this.getDefaultOutputPath(projectRoot).config;
         let doc = {};
@@ -69,7 +76,11 @@ class AiderAgent {
         if (!Array.isArray(doc.read)) {
             doc.read = [];
         }
-        const name = path.basename(mdPath);
+        // Determine the actual agents file path (AGENTS.md by default, or custom path)
+        const agentsPath = agentConfig?.outputPath ||
+            agentConfig?.outputPathInstructions ||
+            this.getDefaultOutputPath(projectRoot).instructions;
+        const name = path.basename(agentsPath);
         if (!doc.read.includes(name)) {
             doc.read.push(name);
         }
@@ -78,9 +89,18 @@ class AiderAgent {
     }
     getDefaultOutputPath(projectRoot) {
         return {
-            instructions: path.join(projectRoot, 'ruler_aider_instructions.md'),
+            instructions: path.join(projectRoot, 'AGENTS.md'),
             config: path.join(projectRoot, '.aider.conf.yml'),
         };
     }
+    getMcpServerKey() {
+        return this.agentsMdAgent.getMcpServerKey();
+    }
+    supportsMcpStdio() {
+        return true;
+    }
+    supportsMcpRemote() {
+        return true;
+    }
 }
 exports.AiderAgent = AiderAgent;

package/dist/agents/AmpAgent.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmpAgent = void 0;
+const AgentsMdAgent_1 = require("./AgentsMdAgent");
+class AmpAgent extends AgentsMdAgent_1.AgentsMdAgent {
+    getIdentifier() {
+        return 'amp';
+    }
+    getName() {
+        return 'Amp';
+    }
+}
+exports.AmpAgent = AmpAgent;

package/dist/agents/AugmentCodeAgent.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AugmentCodeAgent = void 0;
 const path = __importStar(require("path"));
 const FileSystemUtils_1 = require("../core/FileSystemUtils");
-const settings_1 = require("../vscode/settings");
 /**
  * AugmentCode agent adapter.
  * Generates ruler_augment_instructions.md configuration file and updates VSCode settings.json with MCP server configuration.
@@ -48,24 +47,23 @@ class AugmentCodeAgent {
     getName() {
         return 'AugmentCode';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
+    agentConfig) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         await (0, FileSystemUtils_1.backupFile)(output);
         await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
-        if (rulerMcpJson) {
-            const settingsPath = (0, settings_1.getVSCodeSettingsPath)(projectRoot);
-            await (0, FileSystemUtils_1.backupFile)(settingsPath);
-            const existingSettings = await (0, settings_1.readVSCodeSettings)(settingsPath);
-            const augmentServers = (0, settings_1.transformRulerToAugmentMcp)(rulerMcpJson);
-            const mergedSettings = (0, settings_1.mergeAugmentMcpServers)(existingSettings, augmentServers, agentConfig?.mcp?.strategy ?? 'merge');
-            await (0, settings_1.writeVSCodeSettings)(settingsPath, mergedSettings);
-        }
+        // AugmentCode does not support MCP servers
+        // MCP configuration is ignored for this agent
     }
     getDefaultOutputPath(projectRoot) {
         return path.join(projectRoot, '.augment', 'rules', 'ruler_augment_instructions.md');
     }
-    getMcpServerKey() {
-        return 'mcpServers';
+    // AugmentCode does not support MCP servers
+    supportsMcpStdio() {
+        return false;
+    }
+    supportsMcpRemote() {
+        return false;
     }
 }
 exports.AugmentCodeAgent = AugmentCodeAgent;