@intellectronica/ruler 0.3.42 → 0.3.43

package/README.md

@@ -59,7 +59,7 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | AGENTS.md              | `AGENTS.md`                                    | (pseudo-agent ensuring root `AGENTS.md` exists)  | -                         | -                            |
 | GitHub Copilot         | `AGENTS.md`                                    | `.vscode/mcp.json`                               | `.claude/skills/`         | `.github/agents/`            |
 | Claude Code            | `CLAUDE.md`                                    | `.mcp.json`                                      | `.claude/skills/`         | `.claude/agents/`            |
-| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.codex/skills/`          | `.codex/agents/` (`.toml`)   |
+| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.agents/skills/`         | `.codex/agents/` (`.toml`)   |
 | Pi Coding Agent        | `AGENTS.md`                                    | -                                                | `.pi/skills/`             | -                            |
 | Jules                  | `AGENTS.md`                                    | -                                                | -                         | -                            |
 | Cursor                 | `AGENTS.md`                                    | `.cursor/mcp.json`                               | `.cursor/skills/`         | `.cursor/agents/`            |
@@ -514,6 +514,20 @@ Authorization = "Bearer your-token"
 "X-API-Version" = "v1"
 ```
 
+Agent-specific MCP servers can be defined under `[agents.<agent>.mcp_servers.<name>]`.
+They are applied only to that agent and override global servers with the same name:
+
+```toml
+[agents.cursor.mcp_servers.slack]
+url = "https://mcp.slack.com/mcp"
+auth = { CLIENT_ID = "CURSOR_ID" }
+
+[agents.claude.mcp_servers.slack]
+type = "http"
+url = "https://mcp.slack.com/mcp"
+oauth = { clientId = "CLAUDE_ID", callbackPort = 3118 }
+```
+
 ### Legacy `.ruler/mcp.json` (Deprecated)
 
 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`.
@@ -592,7 +606,7 @@ Skills are specialized knowledge packages that extend AI agent capabilities with
   - **Claude Code**: `.claude/skills/`
   - **GitHub Copilot**: `.claude/skills/` (shared with Claude Code)
   - **Kilo Code**: `.claude/skills/` (shared with Claude Code)
-  - **OpenAI Codex CLI**: `.codex/skills/`
+  - **OpenAI Codex CLI**: `.agents/skills/` (shared with Goose, Amp, and Zed)
   - **OpenCode**: `.opencode/skills/`
   - **Pi Coding Agent**: `.pi/skills/`
   - **Goose**: `.agents/skills/`
@@ -661,10 +675,9 @@ If you run Ruler for agents that do not support native skills, Ruler logs a warn
 When skills support is enabled and gitignore integration is active, Ruler automatically adds:
 
 - `.claude/skills/` (for Claude Code, GitHub Copilot, and Kilo Code)
-- `.codex/skills/` (for OpenAI Codex CLI)
+- `.agents/skills/` (for OpenAI Codex CLI, Goose, Amp, and Zed)
 - `.opencode/skills/` (for OpenCode)
 - `.pi/skills/` (for Pi Coding Agent)
-- `.agents/skills/` (for Goose, Amp, and Zed)
 - `.agent/skills/` (for Antigravity)
 - `.factory/skills/` (for Factory Droid)
 - `.vibe/skills/` (for Mistral Vibe)
@@ -678,7 +691,7 @@ to your `.gitignore` file within the managed Ruler block.
 
 ### Requirements
 
-- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.
+- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Zed, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.
 
 ### Validation
 
@@ -722,10 +735,10 @@ ruler apply
 
 # 3. Skills are now available to compatible agents:
 #    - Claude Code, GitHub Copilot & Kilo Code: .claude/skills/my-skill/
-#    - OpenAI Codex CLI: .codex/skills/my-skill/
+#    - OpenAI Codex CLI: .agents/skills/my-skill/ (shared with Goose, Amp & Zed)
 #    - OpenCode: .opencode/skills/my-skill/
 #    - Pi Coding Agent: .pi/skills/my-skill/
-#    - Goose, Amp & Zed: .agents/skills/my-skill/
+#    - Goose, Amp, Zed & OpenAI Codex CLI: .agents/skills/my-skill/
 #    - Antigravity: .agent/skills/my-skill/
 #    - Factory Droid: .factory/skills/my-skill/
 #    - Mistral Vibe: .vibe/skills/my-skill/
@@ -938,7 +951,81 @@ ruler init
 ruler apply
 ```
 
-### Scenario 2: Complex Projects with Nested Rules
+### Scenario 2: Working with worktrees
+
+When using the default `git add worktree` command (which is also run by agents apps such as Claude code or Codex through the interface), the gitignored files are not copied over. You will need to ask your agent to run `ruler apply` at the start of every session.
+
+As an alternative you can commit your default agents files to source control.
+
+```toml
+# .ruler/ruler.toml
+default_agents = ["claude", "codex"]
+
+[gitignore]
+enabled = false
+```
+
+```ignore
+# Do not ignore AGENTS.md and CLAUDE.md
+/.claude/*
+!/.claude/skills/
+/.codex/*
+!/.codex/skills/
+/.cursor
+/AGENTS.md.bak
+/CLAUDE.md.bak
+```
+
+To avoid having other contributors commit instructions outside of .ruler you can setup a github action to check there is no diff when running `ruler apply` in CI.
+
+```yml
+# .github/workflows/ruler-check/yml
+
+# Verifies the committed agent files (AGENTS.md, CLAUDE.md, skills) match the .ruler/ source.
+# They are committed so a fresh clone/worktree has guidance immediately; this guards against drift.
+name: Ruler guidance in sync
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - 'build/**'
+
+permissions:
+  contents: read
+
+env:
+  CI_NODE_VERSION: 24.15.0
+
+jobs:
+  ruler-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v5
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Verify committed agent files match .ruler/
+        run: |
+          pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp
+          DRIFT="$(git status --porcelain -- AGENTS.md CLAUDE.md .claude/skills .codex/skills)"
+          if [ -n "$DRIFT" ]; then
+            echo "::error::Committed agent files are out of sync with .ruler/. Run 'pnpm dlx @intellectronica/ruler apply --no-gitignore --no-mcp' and commit the result."
+            echo "$DRIFT"
+            git --no-pager diff -- AGENTS.md CLAUDE.md .claude/skills .codex/skills
+            exit 1
+          fi
+          echo "Agent files are in sync with .ruler/."
+```
+
+### Scenario 3: Complex Projects with Nested Rules
 
 For large projects with multiple components or services, enable nested rule loading so each directory keeps its own rules and MCP bundle:
 
@@ -970,13 +1057,13 @@ This creates context-specific instructions for different parts of your project w
 > [!NOTE]
 > The CLI prints "Nested mode is experimental and may change in future releases." the first time nested processing runs. Expect refinements in future versions.
 
-### Scenario 3: Team Standardization
+### Scenario 4: Team Standardization
 
 1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`
 2. Commit the `.ruler` directory to your repository
 3. Team members pull changes and run `ruler apply` to update their local AI agent configurations
 
-### Scenario 4: Project-Specific Context for AI
+### Scenario 5: Project-Specific Context for AI
 
 1. Detail your project's architecture in `.ruler/project_overview.md`
 2. Describe primary data structures in `.ruler/data_models.md`

package/dist/agents/AbstractAgent.js

@@ -52,11 +52,12 @@ class AbstractAgent {
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(absolutePath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+            await (0, FileSystemUtils_1.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules, projectRoot);
     }
     /**
      * Returns the specific key to be used for the server object in MCP JSON.

package/dist/agents/AgentsMdAgent.js

@@ -56,6 +56,7 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
         const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(absolutePath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
         // Add marker comment to the content to identify it as generated
         const contentWithMarker = `<!-- Generated by Ruler -->\n${concatenatedRules}`;
@@ -73,9 +74,9 @@ class AgentsMdAgent extends AbstractAgent_1.AbstractAgent {
         }
         // Backup (only if file existed and backup is enabled) then write new content
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(absolutePath);
+            await (0, FileSystemUtils_1.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, contentWithMarker);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, contentWithMarker, projectRoot);
     }
     getMcpServerKey() {
         // No MCP configuration for this pseudo-agent

package/dist/agents/AiderAgent.js

@@ -67,7 +67,7 @@ class AiderAgent {
         try {
             await fs.access(cfgPath);
             if (backup) {
-                await (0, FileSystemUtils_1.backupFile)(cfgPath);
+                await (0, FileSystemUtils_1.backupFile)(cfgPath, projectRoot);
             }
             const raw = await fs.readFile(cfgPath, 'utf8');
             doc = (yaml.load(raw) || {});
@@ -89,16 +89,17 @@ class AiderAgent {
             doc.read.push(name);
         }
         const yamlStr = yaml.dump(doc);
-        await (0, FileSystemUtils_1.writeGeneratedFile)(cfgPath, yamlStr);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(cfgPath, yamlStr, projectRoot);
     }
     getDefaultOutputPath(projectRoot) {
         return {
             instructions: path.join(projectRoot, 'AGENTS.md'),
             config: path.join(projectRoot, '.aider.conf.yml'),
+            mcp: path.join(projectRoot, '.mcp.json'),
         };
     }
     getMcpServerKey() {
-        return this.agentsMdAgent.getMcpServerKey();
+        return 'mcpServers';
     }
     supportsMcpStdio() {
         return true;

package/dist/agents/AmazonQCliAgent.js

@@ -54,16 +54,18 @@ class AmazonQCliAgent {
             agentConfig?.outputPathInstructions ||
             outputPaths['instructions']);
         // Write rules file to .amazonq/rules/
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(rulesPath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(rulesPath));
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(rulesPath);
+            await (0, FileSystemUtils_1.backupFile)(rulesPath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, concatenatedRules, projectRoot);
         // Handle MCP configuration if enabled and provided
         const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
         if (mcpEnabled && rulerMcpJson) {
             const mcpPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? outputPaths['mcp']);
             const mcpStrategy = agentConfig?.mcp?.strategy ?? 'merge';
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(mcpPath, projectRoot, 'Refusing to write generated file outside project');
             await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(mcpPath));
             let existingMcpConfig = {};
             try {
@@ -79,9 +81,9 @@ class AmazonQCliAgent {
             // Merge the MCP configurations using the standard merge function
             const mergedConfig = (0, merge_1.mergeMcp)(existingMcpConfig, rulerMcpJson, mcpStrategy, 'mcpServers');
             if (backup) {
-                await (0, FileSystemUtils_1.backupFile)(mcpPath);
+                await (0, FileSystemUtils_1.backupFile)(mcpPath, projectRoot);
             }
-            await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(mergedConfig, null, 2));
+            await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(mergedConfig, null, 2), projectRoot);
         }
     }
     getDefaultOutputPath(projectRoot) {

package/dist/agents/AugmentCodeAgent.js

@@ -49,10 +49,11 @@ class AugmentCodeAgent {
     }
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(output);
+            await (0, FileSystemUtils_1.backupFile)(absolutePath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(output, concatenatedRules);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules, projectRoot);
         // AugmentCode does not support MCP servers
         // MCP configuration is ignored for this agent
     }

package/dist/agents/CodexCliAgent.js

@@ -128,7 +128,7 @@ class CodexCliAgent {
             const finalConfig = { ...updatedConfig };
             // @iarna/toml should handle the formatting properly
             const tomlContent = (0, toml_1.stringify)(finalConfig);
-            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent);
+            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent, projectRoot);
         }
     }
     getDefaultOutputPath(projectRoot) {

package/dist/agents/CrushAgent.d.ts

@@ -8,7 +8,7 @@ export declare class CrushAgent implements IAgent {
      * Crush expects "http" for HTTP servers and "sse" for SSE servers, not "remote".
      */
     private transformMcpServersForCrush;
-    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig): Promise<void>;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
     supportsMcpStdio(): boolean;
     supportsMcpRemote(): boolean;
 }

package/dist/agents/CrushAgent.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CrushAgent = void 0;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 class CrushAgent {
     getIdentifier() {
         return 'crush';
@@ -80,13 +81,17 @@ class CrushAgent {
         }
         return transformedServers;
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         const outputPaths = this.getDefaultOutputPath(projectRoot);
-        const instructionsPath = agentConfig?.outputPath ??
+        const instructionsPath = path.resolve(projectRoot, agentConfig?.outputPath ??
             agentConfig?.outputPathInstructions ??
-            outputPaths['instructions'];
-        const mcpPath = agentConfig?.outputPathConfig ?? outputPaths['mcp'];
-        await fs.writeFile(instructionsPath, concatenatedRules);
+            outputPaths['instructions']);
+        const mcpPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? outputPaths['mcp']);
+        await fs.mkdir(path.dirname(instructionsPath), { recursive: true });
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(instructionsPath, projectRoot);
+        }
+        await (0, FileSystemUtils_1.writeGeneratedFile)(instructionsPath, concatenatedRules, projectRoot);
         // Always transform from mcpServers ({ mcpServers: ... }) to { mcp: ... } for Crush
         let finalMcpConfig = { mcp: {} };
         const strategy = agentConfig?.mcp?.strategy ?? 'merge';
@@ -118,7 +123,11 @@ class CrushAgent {
             }
         }
         if (Object.keys(finalMcpConfig.mcp).length > 0) {
-            await fs.writeFile(mcpPath, JSON.stringify(finalMcpConfig, null, 2));
+            await fs.mkdir(path.dirname(mcpPath), { recursive: true });
+            if (backup) {
+                await (0, FileSystemUtils_1.backupFile)(mcpPath, projectRoot);
+            }
+            await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(finalMcpConfig, null, 2), projectRoot);
         }
     }
     supportsMcpStdio() {

package/dist/agents/FirebenderAgent.js

@@ -60,6 +60,7 @@ class FirebenderAgent {
     }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         const rulesPath = this.resolveOutputPath(projectRoot, agentConfig);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(rulesPath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(rulesPath));
         const firebenderConfig = await this.loadExistingConfig(rulesPath);
         const newRules = this.createRulesFromConcatenatedRules(concatenatedRules, projectRoot);
@@ -69,7 +70,7 @@ class FirebenderAgent {
         if (mcpEnabled && rulerMcpJson) {
             await this.handleMcpConfiguration(firebenderConfig, rulerMcpJson, agentConfig);
         }
-        await this.saveConfig(rulesPath, firebenderConfig, backup);
+        await this.saveConfig(rulesPath, firebenderConfig, backup, projectRoot);
     }
     resolveOutputPath(projectRoot, agentConfig) {
         const outputPaths = this.getDefaultOutputPath(projectRoot);
@@ -135,12 +136,12 @@ class FirebenderAgent {
             return true;
         });
     }
-    async saveConfig(rulesPath, config, backup) {
+    async saveConfig(rulesPath, config, backup, projectRoot) {
         const updatedContent = JSON.stringify(config, null, 2);
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(rulesPath);
+            await (0, FileSystemUtils_1.backupFile)(rulesPath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, updatedContent);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(rulesPath, updatedContent, projectRoot);
     }
     /**
      * Handle MCP server configuration for Firebender.

package/dist/agents/GeminiCliAgent.d.ts

@@ -3,6 +3,7 @@ import { AgentsMdAgent } from './AgentsMdAgent';
 export declare class GeminiCliAgent extends AgentsMdAgent {
     getIdentifier(): string;
     getName(): string;
+    private getContextFileName;
     applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
     getMcpServerKey(): string;
     supportsMcpStdio(): boolean;

package/dist/agents/GeminiCliAgent.js

@@ -37,6 +37,7 @@ exports.GeminiCliAgent = void 0;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getIdentifier() {
         return 'gemini-cli';
@@ -44,13 +45,19 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getName() {
         return 'Gemini CLI';
     }
+    getContextFileName(projectRoot, agentConfig) {
+        const outputPath = agentConfig?.outputPath ?? 'AGENTS.md';
+        return path
+            .relative(projectRoot, path.resolve(projectRoot, outputPath))
+            .replace(/\\/g, '/');
+    }
     async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         // First, perform idempotent write of AGENTS.md via base class
         await super.applyRulerConfig(concatenatedRules, projectRoot, null, {
             outputPath: agentConfig?.outputPath,
         }, backup);
-        // Prepare .gemini/settings.json with contextFileName and MCP configuration
-        const settingsPath = path.join(projectRoot, '.gemini', 'settings.json');
+        // Prepare settings with contextFileName and MCP configuration
+        const settingsPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? path.join('.gemini', 'settings.json'));
         let existingSettings = {};
         try {
             const raw = await fs_1.promises.readFile(settingsPath, 'utf8');
@@ -63,7 +70,7 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
         }
         const updated = {
             ...existingSettings,
-            contextFileName: 'AGENTS.md',
+            contextFileName: this.getContextFileName(projectRoot, agentConfig),
         };
         // Handle MCP server configuration if provided
         const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
@@ -100,8 +107,7 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
                 updated[this.getMcpServerKey()] = stripTypeField(mergedServers);
             }
         }
-        await fs_1.promises.mkdir(path.dirname(settingsPath), { recursive: true });
-        await fs_1.promises.writeFile(settingsPath, JSON.stringify(updated, null, 2));
+        await (0, FileSystemUtils_1.writeGeneratedFile)(settingsPath, JSON.stringify(updated, null, 2), projectRoot);
     }
     // Ensure MCP merging uses the correct key for Gemini (.gemini/settings.json)
     getMcpServerKey() {

package/dist/agents/IAgent.d.ts

@@ -16,6 +16,8 @@ export interface IAgentConfig {
     outputPathConfig?: string;
     /** MCP propagation config for this agent. */
     mcp?: McpConfig;
+    /** Agent-scoped MCP server definitions. */
+    mcpServers?: Record<string, Record<string, unknown>>;
 }
 export interface IAgent {
     /**

package/dist/agents/MistralVibeAgent.js

@@ -109,12 +109,20 @@ class MistralVibeAgent {
             }
             // Read existing TOML config if it exists
             let existingConfig = {};
+            let configExists = false;
             try {
                 const existingContent = await fs_1.promises.readFile(configPath, 'utf8');
+                configExists = true;
                 existingConfig = (0, toml_1.parse)(existingContent);
             }
-            catch {
-                // File doesn't exist or can't be parsed, use empty config
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Missing config starts from an empty config.
+                    existingConfig = {};
+                }
+                else {
+                    throw new Error(`Invalid Mistral config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+                }
             }
             // Create the updated config
             const updatedConfig = { ...existingConfig };
@@ -134,7 +142,10 @@ class MistralVibeAgent {
             // Convert to TOML and write
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const tomlContent = (0, toml_1.stringify)(updatedConfig);
-            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent);
+            if (configExists && backup) {
+                await (0, FileSystemUtils_1.backupFile)(configPath, projectRoot);
+            }
+            await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent, projectRoot);
         }
     }
     /**

package/dist/agents/OpenCodeAgent.d.ts

@@ -3,7 +3,7 @@ export declare class OpenCodeAgent implements IAgent {
     getIdentifier(): string;
     getName(): string;
     getDefaultOutputPath(projectRoot: string): Record<string, string>;
-    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig): Promise<void>;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
     supportsMcpStdio(): boolean;
     supportsMcpRemote(): boolean;
     supportsMcpTimeout(): boolean;

package/dist/agents/OpenCodeAgent.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenCodeAgent = void 0;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 class OpenCodeAgent {
     getIdentifier() {
         return 'opencode';
@@ -49,14 +50,17 @@ class OpenCodeAgent {
             mcp: path.join(projectRoot, 'opencode.json'),
         };
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         const outputPaths = this.getDefaultOutputPath(projectRoot);
         const instructionsPath = path.resolve(projectRoot, agentConfig?.outputPath ??
             agentConfig?.outputPathInstructions ??
             outputPaths['instructions']);
         const mcpPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? outputPaths['mcp']);
         await fs.mkdir(path.dirname(instructionsPath), { recursive: true });
-        await fs.writeFile(instructionsPath, concatenatedRules);
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(instructionsPath, projectRoot);
+        }
+        await (0, FileSystemUtils_1.writeGeneratedFile)(instructionsPath, concatenatedRules, projectRoot);
         if (!rulerMcpJson) {
             return;
         }
@@ -92,7 +96,10 @@ class OpenCodeAgent {
         }
         // Always write the config file, even if MCP is empty
         await fs.mkdir(path.dirname(mcpPath), { recursive: true });
-        await fs.writeFile(mcpPath, JSON.stringify(finalMcpConfig, null, 2));
+        if (backup) {
+            await (0, FileSystemUtils_1.backupFile)(mcpPath, projectRoot);
+        }
+        await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, JSON.stringify(finalMcpConfig, null, 2), projectRoot);
     }
     supportsMcpStdio() {
         return true;

package/dist/agents/QwenCodeAgent.d.ts

@@ -3,6 +3,7 @@ import { AgentsMdAgent } from './AgentsMdAgent';
 export declare class QwenCodeAgent extends AgentsMdAgent {
     getIdentifier(): string;
     getName(): string;
+    private getContextFileName;
     applyRulerConfig(concatenatedRules: string, projectRoot: string, _rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
     getMcpServerKey(): string;
     supportsMcpStdio(): boolean;

package/dist/agents/QwenCodeAgent.js

@@ -37,6 +37,7 @@ exports.QwenCodeAgent = void 0;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 class QwenCodeAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getIdentifier() {
         return 'qwen';
@@ -44,6 +45,12 @@ class QwenCodeAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getName() {
         return 'Qwen Code';
     }
+    getContextFileName(projectRoot, agentConfig) {
+        const outputPath = agentConfig?.outputPath ?? 'AGENTS.md';
+        return path
+            .relative(projectRoot, path.resolve(projectRoot, outputPath))
+            .replace(/\\/g, '/');
+    }
     async applyRulerConfig(concatenatedRules, projectRoot, _rulerMcpJson, agentConfig, backup = true) {
         // First, perform idempotent write of AGENTS.md via base class
         await super.applyRulerConfig(concatenatedRules, projectRoot, null, {
@@ -63,10 +70,9 @@ class QwenCodeAgent extends AgentsMdAgent_1.AgentsMdAgent {
         }
         const updated = {
             ...existingSettings,
-            contextFileName: 'AGENTS.md',
+            contextFileName: this.getContextFileName(projectRoot, agentConfig),
         };
-        await fs_1.promises.mkdir(path.dirname(settingsPath), { recursive: true });
-        await fs_1.promises.writeFile(settingsPath, JSON.stringify(updated, null, 2));
+        await (0, FileSystemUtils_1.writeGeneratedFile)(settingsPath, JSON.stringify(updated, null, 2), projectRoot);
     }
     // Ensure MCP merging uses the correct key for Qwen Code (.qwen/settings.json)
     getMcpServerKey() {

package/dist/agents/RooCodeAgent.js

@@ -69,6 +69,7 @@ class RooCodeAgent {
         // Now handle .roo/mcp.json configuration
         const outputPaths = this.getDefaultOutputPath(projectRoot);
         const mcpPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? outputPaths['mcp']);
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(mcpPath, projectRoot, 'Refusing to write generated file outside project');
         await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(mcpPath));
         // Create base structure with mcpServers
         let finalMcpConfig = {
@@ -122,9 +123,9 @@ class RooCodeAgent {
         }
         // Backup (only if file existed and backup is enabled) then write new content
         if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(mcpPath);
+            await (0, FileSystemUtils_1.backupFile)(mcpPath, projectRoot);
         }
-        await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, newContent);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(mcpPath, newContent, projectRoot);
     }
     supportsMcpStdio() {
         return true;

package/dist/agents/ZedAgent.js

@@ -37,6 +37,7 @@ exports.ZedAgent = void 0;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 /**
  * Zed editor agent adapter.
  * Inherits from AgentsMdAgent to write instructions to AGENTS.md and handles
@@ -57,7 +58,7 @@ class ZedAgent extends AgentsMdAgent_1.AgentsMdAgent {
         // Handle MCP server configuration if enabled and provided
         const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
         if (mcpEnabled && rulerMcpJson) {
-            const zedSettingsPath = path.join(projectRoot, '.zed', 'settings.json');
+            const zedSettingsPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? path.join('.zed', 'settings.json'));
             // Read existing settings
             let existingSettings = {};
             try {
@@ -103,8 +104,7 @@ class ZedAgent extends AgentsMdAgent_1.AgentsMdAgent {
                 };
             }
             // Write updated settings
-            await fs_1.promises.mkdir(path.dirname(zedSettingsPath), { recursive: true });
-            await fs_1.promises.writeFile(zedSettingsPath, JSON.stringify(mergedSettings, null, 2));
+            await (0, FileSystemUtils_1.writeGeneratedFile)(zedSettingsPath, JSON.stringify(mergedSettings, null, 2), projectRoot);
         }
     }
     getMcpServerKey() {

package/dist/constants.d.ts

@@ -15,7 +15,7 @@ export declare function logVerboseInfo(message: string, isVerbose: boolean, dryR
 export declare const SKILLS_DIR = "skills";
 export declare const RULER_SKILLS_PATH = ".ruler/skills";
 export declare const CLAUDE_SKILLS_PATH = ".claude/skills";
-export declare const CODEX_SKILLS_PATH = ".codex/skills";
+export declare const CODEX_SKILLS_PATH = ".agents/skills";
 export declare const OPENCODE_SKILLS_PATH = ".opencode/skills";
 export declare const PI_SKILLS_PATH = ".pi/skills";
 export declare const GOOSE_SKILLS_PATH = ".agents/skills";