Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix: namespace cursor agent installs

Affaan Mustafae1d6d853f773
diff --git a/README.md b/README.md
index 0d4f6df1b..4cf3fc97e 100644
--- a/README.md
+++ b/README.md
@@ -1133,7 +1133,7 @@ These are not bundled with ECC and are not audited by this repo, but they are wo
## Cursor IDE Support
-ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's native format.
+ECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.
### Quick Start (Cursor)
@@ -1156,11 +1156,17 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm
| Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more |
| Hook Scripts | 16 | Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter |
| Rules | 34 | 9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) |
-| Agents | Shared | Via AGENTS.md at root (read by Cursor natively) |
-| Skills | Shared + Bundled | Via AGENTS.md at root and `.cursor/skills/` for translated additions |
+| Agents | 48 | `.cursor/agents/ecc-*.md` when installed; prefixed to avoid collisions with user or marketplace agents |
+| Skills | Shared + Bundled | `.cursor/skills/` for translated additions |
| Commands | Shared | `.cursor/commands/` if installed |
| MCP Config | Shared | `.cursor/mcp.json` if installed |
+### Cursor Loading Notes
+
+ECC does not install root `AGENTS.md` into `.cursor/`. Cursor treats nested `AGENTS.md` files as directory context, so copying ECC's repo identity into a host project would pollute that project.
+
+Cursor-native loading behavior can vary by Cursor build. ECC installs agents as `.cursor/agents/ecc-*.md`; if your Cursor build does not expose project agents, those files still work as explicit reference definitions instead of hidden global prompt context.
+
### Hook Architecture (DRY Adapter Pattern)
Cursor has **more hook events than Claude Code** (20 vs 8). The `.cursor/hooks/adapter.js` module transforms Cursor's stdin JSON to Claude Code's format, allowing existing `scripts/hooks/*.js` to be reused without duplication.
diff --git a/scripts/lib/cursor-agent-names.js b/scripts/lib/cursor-agent-names.js
new file mode 100644
index 000000000..945771e0e
--- /dev/null
+++ b/scripts/lib/cursor-agent-names.js
@@ -0,0 +1,26 @@
+'use strict';
+
+const path = require('path');
+
+function toCursorAgentFileName(fileName) {
+ if (!fileName || fileName.startsWith('ecc-')) {
+ return fileName;
+ }
+
+ return `ecc-${fileName}`;
+}
+
+function toCursorAgentRelativePath(relativePath) {
+ const segments = String(relativePath || '').split(/[\\/]+/).filter(Boolean);
+ if (segments.length === 0) {
+ return relativePath;
+ }
+
+ const fileName = segments.pop();
+ return path.join(...segments, toCursorAgentFileName(fileName));
+}
+
+module.exports = {
+ toCursorAgentFileName,
+ toCursorAgentRelativePath,
+};
diff --git a/scripts/lib/install-executor.js b/scripts/lib/install-executor.js
index d6676c56f..cee650852 100644
--- a/scripts/lib/install-executor.js
+++ b/scripts/lib/install-executor.js
@@ -3,6 +3,7 @@ const os = require('os');
const path = require('path');
const { execFileSync } = require('child_process');
+const { toCursorAgentRelativePath } = require('./cursor-agent-names');
const { LEGACY_INSTALL_TARGETS, parseInstallArgs } = require('./install/request');
const {
SUPPORTED_INSTALL_TARGETS,
@@ -154,7 +155,13 @@ function addRecursiveCopyOperations(operations, options) {
for (const relativeFile of relativeFiles) {
const sourceRelativePath = path.join(options.sourceRelativeDir, relativeFile);
const sourcePath = path.join(options.sourceRoot, sourceRelativePath);
- const destinationPath = path.join(options.destinationDir, relativeFile);
+ const destinationRelativePath = typeof options.destinationRelativePathTransform === 'function'
+ ? options.destinationRelativePathTransform(relativeFile, sourceRelativePath)
+ : relativeFile;
+ if (!destinationRelativePath) {
+ continue;
+ }
+ const destinationPath = path.join(options.destinationDir, destinationRelativePath);
operations.push(buildCopyFileOperation({
moduleId: options.moduleId,
sourcePath,
@@ -351,6 +358,7 @@ function planCursorLegacyInstall(context) {
sourceRoot: context.sourceRoot,
sourceRelativeDir: path.join('.cursor', 'agents'),
destinationDir: path.join(targetRoot, 'agents'),
+ destinationRelativePathTransform: toCursorAgentRelativePath,
});
addRecursiveCopyOperations(operations, {
moduleId: 'legacy-cursor-install',
diff --git a/scripts/lib/install-targets/cursor-project.js b/scripts/lib/install-targets/cursor-project.js
index 617bbcc09..81e71aefd 100644
--- a/scripts/lib/install-targets/cursor-project.js
+++ b/scripts/lib/install-targets/cursor-project.js
@@ -1,7 +1,9 @@
const fs = require('fs');
const path = require('path');
+const { toCursorAgentFileName } = require('../cursor-agent-names');
const {
+ createFlatFileOperations,
createFlatRuleOperations,
createInstallTargetAdapter,
createManagedOperation,
@@ -149,6 +151,16 @@ module.exports = createInstallTargetAdapter({
}));
}
+ if (sourceRelativePath === 'agents') {
+ return takeUniqueOperations(createFlatFileOperations({
+ moduleId: module.id,
+ repoRoot,
+ sourceRelativePath,
+ destinationDir: path.join(targetRoot, 'agents'),
+ destinationNameTransform: toCursorAgentFileName,
+ }));
+ }
+
if (sourceRelativePath === '.cursor') {
const cursorRoot = path.join(repoRoot, '.cursor');
if (!fs.existsSync(cursorRoot) || !fs.statSync(cursorRoot).isDirectory()) {
diff --git a/scripts/lib/install-targets/helpers.js b/scripts/lib/install-targets/helpers.js
index a39506e1e..bb9a0648d 100644
--- a/scripts/lib/install-targets/helpers.js
+++ b/scripts/lib/install-targets/helpers.js
@@ -181,7 +181,7 @@ function createNamespacedFlatRuleOperations(adapter, moduleId, sourceRelativePat
return operations;
}
-function createFlatRuleOperations({
+function createFlatFileOperations({
moduleId,
repoRoot,
sourceRelativePath,
@@ -242,6 +242,10 @@ function createFlatRuleOperations({
return operations;
}
+function createFlatRuleOperations(options) {
+ return createFlatFileOperations(options);
+}
+
function createInstallTargetAdapter(config) {
const adapter = {
id: config.id,
@@ -342,6 +346,7 @@ function createInstallTargetAdapter(config) {
module.exports = {
buildValidationIssue,
+ createFlatFileOperations,
createFlatRuleOperations,
createInstallTargetAdapter,
createManagedOperation,
diff --git a/tests/lib/install-executor.test.js b/tests/lib/install-executor.test.js
index d5c97baf9..3bc9e698a 100644
--- a/tests/lib/install-executor.test.js
+++ b/tests/lib/install-executor.test.js
@@ -213,7 +213,10 @@ function runTests() {
assert.strictEqual(plan.installRoot, targetRoot);
assert.ok(operationFor(plan, path.join('.cursor', 'rules', 'common-style.md')));
assert.ok(operationFor(plan, path.join('.cursor', 'rules', 'typescript-style.md')));
- assert.ok(operationFor(plan, path.join('.cursor', 'agents', 'planner.md')));
+ assert.ok(operationFor(plan, path.join('.cursor', 'agents', 'ecc-planner.md')));
+ assert.ok(!plan.operations.some(operation => (
+ operation.destinationPath.endsWith(path.join('.cursor', 'agents', 'planner.md'))
+ )));
assert.ok(operationFor(plan, path.join('.cursor', 'skills', 'demo', 'SKILL.md')));
assert.ok(operationFor(plan, path.join('.cursor', 'commands', 'plan.md')));
assert.ok(operationFor(plan, path.join('.cursor', 'hooks', 'hook.js')));
diff --git a/tests/lib/install-targets.test.js b/tests/lib/install-targets.test.js
index 98c021dcd..60476e33c 100644
--- a/tests/lib/install-targets.test.js
+++ b/tests/lib/install-targets.test.js
@@ -202,6 +202,44 @@ function runTests() {
);
})) passed++; else failed++;
+ if (test('plans cursor agents with ecc-prefixed filenames to avoid agent collisions', () => {
+ const repoRoot = path.join(__dirname, '..', '..');
+ const projectRoot = '/workspace/app';
+
+ const plan = planInstallTargetScaffold({
+ target: 'cursor',
+ repoRoot,
+ projectRoot,
+ modules: [
+ {
+ id: 'agents-core',
+ paths: ['agents'],
+ },
+ ],
+ });
+
+ assert.ok(
+ plan.operations.some(operation => (
+ normalizedRelativePath(operation.sourceRelativePath) === 'agents/architect.md'
+ && operation.destinationPath === path.join(projectRoot, '.cursor', 'agents', 'ecc-architect.md')
+ )),
+ 'Should prefix Cursor agent files with ecc-'
+ );
+ assert.ok(
+ !plan.operations.some(operation => (
+ operation.destinationPath === path.join(projectRoot, '.cursor', 'agents', 'architect.md')
+ )),
+ 'Should not write bare Cursor agent filenames'
+ );
+ assert.ok(
+ !plan.operations.some(operation => (
+ normalizedRelativePath(operation.sourceRelativePath) === 'agents'
+ && operation.destinationPath === path.join(projectRoot, '.cursor', 'agents')
+ )),
+ 'Should not plan a whole-directory Cursor agent copy'
+ );
+ })) passed++; else failed++;
+
if (test('plans cursor platform rule files as .mdc and excludes rule README docs', () => {
const repoRoot = path.join(__dirname, '..', '..');
const projectRoot = '/workspace/app';
diff --git a/tests/scripts/install-apply.test.js b/tests/scripts/install-apply.test.js
index 63fde637b..8fcf0c708 100644
--- a/tests/scripts/install-apply.test.js
+++ b/tests/scripts/install-apply.test.js
@@ -136,7 +136,8 @@ function runTests() {
assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'rules', 'common-agents.mdc')));
assert.ok(!fs.existsSync(path.join(projectDir, '.cursor', 'rules', 'common-agents.md')));
assert.ok(!fs.existsSync(path.join(projectDir, '.cursor', 'rules', 'README.mdc')));
- assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'agents', 'architect.md')));
+ assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'agents', 'ecc-architect.md')));
+ assert.ok(!fs.existsSync(path.join(projectDir, '.cursor', 'agents', 'architect.md')));
assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'commands', 'plan.md')));
assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'hooks.json')));
assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'mcp.json')));
diff --git a/tests/scripts/install-readme-clarity.test.js b/tests/scripts/install-readme-clarity.test.js
index a1946ef0a..7affd11f9 100644
--- a/tests/scripts/install-readme-clarity.test.js
+++ b/tests/scripts/install-readme-clarity.test.js
@@ -93,6 +93,21 @@ function runTests() {
);
})) passed++; else failed++;
+ if (test('README documents Cursor agent namespace and loading caveat', () => {
+ assert.ok(
+ readme.includes('`.cursor/agents/ecc-*.md`'),
+ 'README should document the Cursor agent namespace'
+ );
+ assert.ok(
+ readme.includes('Cursor-native loading behavior can vary by Cursor build.'),
+ 'README should avoid overclaiming Cursor agent loading semantics'
+ );
+ assert.ok(
+ readme.includes('ECC does not install root `AGENTS.md` into `.cursor/`.'),
+ 'README should explain why root AGENTS.md is not copied into Cursor context'
+ );
+ })) passed++; else failed++;
+
if (test('README explains plugin-path cleanup and rules scoping', () => {
assert.ok(
readme.includes('remove the plugin from Claude Code'),