feat(skills): gate local agent delegation experiment

Author: Waishnav

docs/agent-profile-schema.md

@@ -4,16 +4,9 @@ DevSpace local agent profiles are user-owned markdown files with YAML front matt
 They describe how a local coding-agent CLI can be used as a worker under ChatGPT
 supervision.
 
-Profiles are intended to live in:
-
-```text
-~/.devspace/agents/*.md
-```
-
 The packaged files in `examples/agents/` are starter templates only. DevSpace does
-not automatically activate them, copy them into `~/.devspace/agents`, or run their
-commands. Users should copy, review, and edit a template before treating it as an
-active local worker definition.
+not currently parse, load, activate, or run local agent profile definitions. A
+future profile loader can define the user-owned directory for active profiles.
 
 ## Minimal shape
 
@@ -339,7 +332,7 @@ The body is model-facing guidance. Keep it practical and concise.
 
 The current examples do not add:
 
-- `.devspace/agents` parsing.
+- local agent profile parsing.
 - automatic activation of packaged examples.
 - `devspace agents init`.
 - generated available-agent catalogs.

docs/chatgpt-coding-workflow.md

@@ -87,13 +87,13 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `local-agent-delegation` skill, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
+- the bundled `local-agent-delegation` skill when `DEVSPACE_LOCAL_AGENTS=1`, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
 Example local coding-agent profiles are packaged under `examples/agents/` for
-users who want starter templates for `~/.devspace/agents/*.md`. These examples
-are not activated automatically.
+users who want starter templates. These examples are inert: DevSpace does not
+currently parse, load, activate, or run local agent profile definitions.
 
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 
@@ -105,7 +105,9 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 - advertised `SKILL.md` files
 - files under a skill directory after that skill's `SKILL.md` has been read
 
-Set `DEVSPACE_SKILLS=0` to hide skills from workspace output.
+Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
+`DEVSPACE_LOCAL_AGENTS=1` to expose the experimental `local-agent-delegation`
+skill.
 
 ## Tool Names
 

docs/configuration.md

@@ -99,6 +99,7 @@ sessions.
 | Variable | Purpose |
 | --- | --- |
 | `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
+| `DEVSPACE_LOCAL_AGENTS` | Set to `1` to expose the local-agent delegation skill. Experimental and disabled by default. |
 | `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
 | `DEVSPACE_SKILL_PATHS` | Optional comma-separated additional skill directories. |
 
@@ -110,13 +111,13 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `local-agent-delegation` skill, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
+- the bundled `local-agent-delegation` skill when `DEVSPACE_LOCAL_AGENTS=1`, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
 Starter local coding-agent profile templates are available under
-`examples/agents/`. Users can copy them into `~/.devspace/agents/` and edit them
-for their local CLIs. DevSpace does not activate packaged examples automatically.
+`examples/agents/`. These files are inert examples: DevSpace does not currently
+parse, load, activate, or run local agent profile definitions.
 
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 

docs/gotchas.md

@@ -201,13 +201,13 @@ DevSpace looks in standard Agent Skills locations:
 
 It also checks compatibility and custom paths:
 
-- the bundled `local-agent-delegation` skill, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
+- the bundled `local-agent-delegation` skill when `DEVSPACE_LOCAL_AGENTS=1`, unless `~/.devspace/skills/local-agent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
-Packaged local-agent examples under `examples/agents/` are templates only. Copy
-and review a profile before using it from `~/.devspace/agents/`; repo-provided or
-packaged examples should not become runnable worker definitions silently.
+Packaged local-agent examples under `examples/agents/` are inert templates only.
+DevSpace does not currently parse, load, activate, or run local agent profile
+definitions.
 
 Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
 

skills/local-agent-delegation/SKILL.md

@@ -50,15 +50,11 @@ pi -p --mode json "$PROMPT"
 copilot -p "$PROMPT" --output-format json
 ```
 
-Use exact command templates from user-configured DevSpace agent profiles when they are available. Do not invent provider-specific flags when a profile already defines them.
+Use exact command templates from user-provided instructions when they are available. Do not invent provider-specific flags when the user has already supplied a command shape.
 
-Configured local agent profiles may live in:
+Packaged files under `examples/agents/` are templates only. DevSpace does not currently parse, load, activate, or run local agent profile definitions.
 
-```text
-~/.devspace/agents/*.md
-```
-
-Treat those profiles as user-approved local worker definitions. If no profile exists for a requested agent, use the installed CLI's help output only when needed, then summarize what you found before running it.
+If no command shape exists for a requested agent, use the installed CLI's help output only when needed, then summarize what you found before running it.
 
 ## Background execution
 
@@ -174,14 +170,6 @@ Do not use local agents for destructive actions unless the user explicitly asks.
 
 Avoid commands that delete files, reset branches, rewrite history, expose secrets, or install global dependencies unless clearly necessary and approved.
 
-Do not allow project-provided agent profiles to run automatically unless the user has trusted them.
-
-Prefer user-global profiles from:
-
-```text
-~/.devspace/agents
-```
-
-over repo-provided profiles.
+Do not treat repo-provided profile examples as trusted executable definitions.
 
 Never hide that a local agent was used.

src/cli.ts

@@ -134,14 +134,15 @@ async function runInit({ force }: { force: boolean }): Promise<void> {
       port,
       allowedRoots,
       publicBaseUrl,
+      localAgents: files.config.localAgents,
     };
     const auth = {
       ownerToken: files.auth.ownerToken ?? generateOwnerToken(),
     };
 
     const configPath = writeDevspaceConfig(config);
     const authPath = writeDevspaceAuth(auth);
-    const seededSkillPaths = ensureDevspaceDefaultSkills();
+    const seededSkillPaths = config.localAgents ? ensureDevspaceDefaultSkills() : [];
 
     const lines = [
       `Config: ${configPath}`,

src/config.test.ts

@@ -27,8 +27,13 @@ assert.equal(loadConfig({ ...baseEnv, DEVSPACE_MINIMAL_TOOLS: "0" }).toolMode, "
 assert.equal(loadConfig({ ...baseEnv, DEVSPACE_MINIMAL_TOOLS: "1" }).toolMode, "minimal");
 assert.equal(loadConfig(baseEnv).skillsEnabled, true);
 assert.equal(loadConfig(baseEnv).devspaceSkillsDir, join(emptyConfigDir, "skills"));
+assert.equal(loadConfig(baseEnv).localAgents, false);
 assert.equal(loadConfig({ ...baseEnv, DEVSPACE_SKILLS: "0" }).skillsEnabled, false);
 assert.equal(loadConfig({ ...baseEnv, DEVSPACE_SKILLS: "1" }).skillsEnabled, true);
+assert.equal(
+  loadConfig({ ...baseEnv, DEVSPACE_LOCAL_AGENTS: "1" }).localAgents,
+  true,
+);
 
 const seededConfigDir = mkdtempSync(join(tmpdir(), "devspace-seeded-skills-test-"));
 const seededSkillPaths = ensureDevspaceDefaultSkills({ DEVSPACE_CONFIG_DIR: seededConfigDir });
@@ -159,6 +164,7 @@ writeFileSync(
     port: 8787,
     allowedRoots: [process.cwd()],
     publicBaseUrl: "https://devspace.example.com",
+    localAgents: true,
   }),
 );
 writeFileSync(
@@ -172,6 +178,7 @@ const fileConfig = loadConfig({ DEVSPACE_CONFIG_DIR: configDir });
 assert.equal(fileConfig.port, 8787);
 assert.equal(fileConfig.oauth.ownerToken, "persisted-owner-token-long-enough");
 assert.equal(fileConfig.publicBaseUrl, "https://devspace.example.com");
+assert.equal(fileConfig.localAgents, true);
 assert.deepEqual(fileConfig.allowedHosts, [
   "localhost",
   "127.0.0.1",

src/config.ts

@@ -26,6 +26,7 @@ export interface ServerConfig {
   skillsEnabled: boolean;
   skillPaths: string[];
   devspaceSkillsDir: string;
+  localAgents: boolean;
   agentDir: string;
   logging: LoggingConfig;
 }
@@ -237,6 +238,10 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
     skillsEnabled: env.DEVSPACE_SKILLS === undefined ? true : parseBoolean(env.DEVSPACE_SKILLS),
     skillPaths: parsePathList(env.DEVSPACE_SKILL_PATHS),
     devspaceSkillsDir: devspaceSkillsDir(env),
+    localAgents:
+      env.DEVSPACE_LOCAL_AGENTS === undefined
+        ? files.config.localAgents === true
+        : parseBoolean(env.DEVSPACE_LOCAL_AGENTS),
     agentDir: resolve(expandHomePath(env.DEVSPACE_AGENT_DIR ?? files.config.agentDir ?? defaultAgentDir())),
     logging: parseLoggingConfig(env),
   };

src/skills.test.ts

@@ -160,11 +160,25 @@ try {
   assert.equal(loaded.skills.some((skill) => skill.name === "claude-project-skill"), true);
   assert.equal(loaded.skills.some((skill) => skill.name === "project-skill"), false);
   assert.equal(loaded.skills.some((skill) => skill.name === "devspace-local-skill"), true);
-  assert.equal(loaded.skills.some((skill) => skill.name === "local-agent-delegation"), true);
+  assert.equal(loaded.skills.some((skill) => skill.name === "local-agent-delegation"), false);
   assert.equal(loaded.skills.filter((skill) => skill.name === "duplicate-skill").length, 1);
   assert.equal(loaded.skills.some((skill) => skill.name === "hidden-skill"), true);
   assert.equal(loaded.diagnostics.some((diagnostic) => diagnostic.type === "collision"), true);
 
+  const experimentalConfig = loadConfig({
+    DEVSPACE_ALLOWED_ROOTS: projectRoot,
+    DEVSPACE_AGENT_DIR: agentDir,
+    DEVSPACE_LOCAL_AGENTS: "1",
+    DEVSPACE_OAUTH_OWNER_TOKEN: "test-owner-token-that-is-long-enough",
+    PORT: "1",
+  });
+  assert.equal(
+    loadWorkspaceSkills(experimentalConfig, projectRoot).skills.some(
+      (skill) => skill.name === "local-agent-delegation",
+    ),
+    true,
+  );
+
   const duplicateConfig = loadConfig({
     DEVSPACE_ALLOWED_ROOTS: projectRoot,
     DEVSPACE_AGENT_DIR: agentDir,

src/skills.ts

@@ -38,7 +38,9 @@ export function effectiveSkillPaths(config: ServerConfig, cwd: string): string[]
     resolve(cwd, ".agents", "skills"),
     config.devspaceSkillsDir,
     join(config.agentDir, "skills"),
-    hasLocalAgentDelegationSkill(config.devspaceSkillsDir) ? undefined : bundledSkills,
+    config.localAgents && !hasLocalAgentDelegationSkill(config.devspaceSkillsDir)
+      ? bundledSkills
+      : undefined,
   ];
   const defaultPaths = defaultPathCandidates.filter(
     (path): path is string => path !== undefined && existsSync(path),
@@ -61,12 +63,19 @@ function resolveSkillPath(path: string, cwd: string): string {
 export function loadWorkspaceSkills(config: ServerConfig, cwd: string): LoadedSkills {
   if (!config.skillsEnabled) return { skills: [], diagnostics: [] };
 
-  return loadSkills({
+  const result = loadSkills({
     cwd,
     agentDir: config.agentDir,
     skillPaths: effectiveSkillPaths(config, cwd),
     includeDefaults: false,
   });
+
+  if (config.localAgents) return result;
+
+  return {
+    skills: result.skills.filter((skill) => skill.name !== "local-agent-delegation"),
+    diagnostics: result.diagnostics,
+  };
 }
 
 export function resolveSkillReadPath(