refactor(skills): replace subagent delegation guidance

Author: Waishnav

skills/subagent-delegation/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: subagents
+description: Delegate focused work to isolated DevSpace coding agents.
+---
+
+Each subagent is headless, has its own context window, cannot see the parent conversation, cannot ask the user, and cannot spawn subagents or workflows. Give every child a self-contained prompt with paths, constraints, and the expected report.
+
+## Choose a target
+
+Prefer a matching named profile from `open_workspace`. Use a raw provider when
+the user names that harness or no profile fits. Choose only profiles and
+providers returned by `open_workspace`.
+
+## Write the brief
+
+Describe the task directly. Include decisions and constraints that exist only
+in the parent conversation. Mention relevant paths or scope when useful. Do not
+repeat project instructions that the child can discover from the repository.
+
+## Run and continue
+
+```bash
+devspace agents run <profile-or-provider> "<brief>"
+devspace agents show <id>
+devspace agents run <id> "<follow-up>"
+devspace agents ls
+```
+
+`run` with a profile or provider starts a child and returns its id. `show`
+reads its latest status and response. `run` with an existing id continues the
+same child session. `ls` lists sessions for the current project.
+
+Do not invoke provider CLIs directly; use `devspace agents` so DevSpace keeps
+session and provider handling consistent.
+
+## Model and effort overrides
+
+Normally omit `--model` and `--effort`. When an exact override is needed, read
+`references/<provider>.md` first. Do not guess values or transfer an effort
+name between providers merely because both use the same word.
+
+```bash
+devspace agents run <target> --model <model> --effort <effort> "<brief>"
+```
+
+## Direct subagent or workflow
+
+Use a direct subagent for one focused delegation or a follow-up with the same
+child. Use a dynamic workflow when the task needs programmed fan-out, stages,
+branching, nesting, or replay.

skills/subagents/SKILL.md

@@ -53,12 +53,12 @@ assert.equal(resolveSubagentsFlag({}, { DEVSPACE_SUBAGENTS: "1" }), true);
 const seededConfigDir = mkdtempSync(join(tmpdir(), "devspace-seeded-skills-test-"));
 const seededSkillPaths = ensureDevspaceDefaultSkills({ DEVSPACE_CONFIG_DIR: seededConfigDir });
 assert.deepEqual(seededSkillPaths, [
-  join(seededConfigDir, "skills", "subagent-delegation", "SKILL.md"),
+  join(seededConfigDir, "skills", "subagents", "SKILL.md"),
   join(seededConfigDir, "skills", "dynamic-workflows", "SKILL.md"),
 ]);
 assert.equal(existsSync(seededSkillPaths[0]), true);
 assert.equal(existsSync(seededSkillPaths[1]), true);
-assert.match(readFileSync(seededSkillPaths[0], "utf8"), /name: subagent-delegation/);
+assert.match(readFileSync(seededSkillPaths[0], "utf8"), /name: subagents/);
 assert.match(readFileSync(seededSkillPaths[1], "utf8"), /name: dynamic-workflows/);
 assert.deepEqual(ensureDevspaceDefaultSkills({ DEVSPACE_CONFIG_DIR: seededConfigDir }), []);
 

src/config.test.ts

@@ -204,7 +204,7 @@ try {
   });
   assert.equal(
     loadWorkspaceSkills(experimentalConfig, projectRoot).skills.some(
-      (skill) => skill.name === "subagent-delegation",
+      (skill) => skill.name === "subagents",
     ),
     true,
   );

src/skills.test.ts

@@ -21,7 +21,8 @@ export interface SkillReadResolution {
   isSkillFile: boolean;
 }
 
-const SUBAGENT_DELEGATION_NAME = "subagent-delegation";
+const SUBAGENTS_NAME = "subagents";
+const LEGACY_SUBAGENT_DELEGATION_NAME = "subagent-delegation";
 const DYNAMIC_WORKFLOWS_NAME = "dynamic-workflows";
 
 function bundledSkillsDir(): string {
@@ -72,7 +73,11 @@ export function loadWorkspaceSkills(config: ServerConfig, cwd: string): LoadedSk
 
   if (config.subagents) return result;
 
-  const gated = new Set<string>([SUBAGENT_DELEGATION_NAME, DYNAMIC_WORKFLOWS_NAME]);
+  const gated = new Set<string>([
+    SUBAGENTS_NAME,
+    LEGACY_SUBAGENT_DELEGATION_NAME,
+    DYNAMIC_WORKFLOWS_NAME,
+  ]);
   return {
     skills: result.skills.filter((skill) => !gated.has(skill.name)),
     diagnostics: result.diagnostics.filter((diagnostic) => {

src/skills.ts

@@ -97,7 +97,7 @@ export function generateOwnerToken(): string {
   return randomBytes(32).toString("base64url");
 }
 
-const DEFAULT_SKILLS = ["subagent-delegation", "dynamic-workflows"] as const;
+const DEFAULT_SKILLS = ["subagents", "dynamic-workflows"] as const;
 
 export function ensureDevspaceDefaultSkills(env: NodeJS.ProcessEnv = process.env): string[] {
   const seeded: string[] = [];