@elyracode/subagents 0.4.8

package/README.md

@@ -0,0 +1,56 @@
+# @elyracode/subagents
+
+Subagent delegation for Elyra -- scout, review, plan, implement, and get second opinions with focused child agents.
+
+## Install
+
+```
+elyra install npm:@elyracode/subagents
+```
+
+## Agents
+
+| Agent | Use when you want... |
+|-------|---------------------|
+| `scout` | Fast codebase recon: files, structure, data flow, risks |
+| `reviewer` | Code review: correctness, tests, edge cases, security, simplicity |
+| `planner` | Implementation plan: concrete steps with file paths |
+| `worker` | Implementation: edits files, validates, follows the plan |
+| `oracle` | Second opinion: challenges assumptions, catches drift |
+| `researcher` | External research: docs, specs, recent changes |
+| `delegate` | General-purpose child agent for ad-hoc tasks |
+
+## Usage
+
+### Natural language
+```
+Use reviewer to review this diff.
+Ask oracle for a second opinion on my plan.
+Use scout to understand the auth flow.
+Run parallel reviewers: one for correctness, one for tests, one for complexity.
+Have worker implement this plan, then run reviewer to check it.
+```
+
+### Commands
+```
+/run scout analyze the authentication flow
+/run reviewer review the changes in the last commit
+/run oracle challenge my current approach
+/parallel reviewer 'check correctness' -> reviewer 'check tests' -> reviewer 'check complexity'
+/agents
+```
+
+### Recommended workflow
+```
+scout -> planner -> worker -> reviewer -> worker (fixes)
+```
+
+## How it works
+
+1. You ask for delegation (naturally or via commands)
+2. Elyra selects the right agent and gives it focused instructions
+3. The agent executes the task with appropriate tool access
+4. Read-only agents (scout, reviewer, planner, oracle) cannot edit files
+5. Results are brought back for synthesis
+
+Each agent is narrow and focused -- one task, one perspective. This produces better results than asking one agent to do everything.

package/extensions/agents.ts

@@ -0,0 +1,147 @@
+/**
+ * Builtin agent definitions for elyra-subagents.
+ */
+
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	systemPrompt: string;
+	tools?: string[];
+	readOnly?: boolean;
+}
+
+export const BUILTIN_AGENTS: Record<string, AgentDefinition> = {
+	scout: {
+		name: "scout",
+		description: "Fast codebase reconnaissance: files, structure, entry points, data flow, risks",
+		systemPrompt: `You are a codebase scout. Your job is to quickly understand a codebase or specific area of code.
+
+Tasks:
+- Map the file structure and identify key modules
+- Trace data flow and control flow for the requested feature
+- Identify entry points, dependencies, and potential risks
+- Report what you find concisely
+
+Rules:
+- Read files, don't edit them
+- Be fast and focused -- don't analyze everything, focus on what's relevant
+- Report findings in a structured format with file paths
+- Flag anything unusual or risky`,
+		tools: ["read", "grep", "find", "ls", "bash"],
+		readOnly: true,
+	},
+
+	reviewer: {
+		name: "reviewer",
+		description: "Code review: correctness, tests, edge cases, simplicity, security",
+		systemPrompt: `You are a code reviewer. Review the code changes or files for quality.
+
+Check for:
+- Correctness: does the code do what it claims?
+- Tests: are there tests? Do they cover edge cases?
+- Security: SQL injection, XSS, auth bypasses, data leaks
+- Simplicity: is there unnecessary complexity?
+- Performance: obvious N+1 queries, missing indexes, expensive loops
+- Conventions: does it follow project patterns?
+
+Rules:
+- Be specific: reference file paths and line numbers
+- Categorize issues as: critical, warning, suggestion
+- Suggest fixes, not just problems
+- Keep it concise -- no praise, just findings`,
+		tools: ["read", "grep", "find", "ls", "bash"],
+		readOnly: true,
+	},
+
+	planner: {
+		name: "planner",
+		description: "Implementation planning: concrete steps from existing context",
+		systemPrompt: `You are an implementation planner. Create a concrete, actionable plan for the requested change.
+
+Deliverables:
+- Step-by-step implementation plan with file paths
+- Which files to create, modify, or delete
+- Dependencies and order of operations
+- Migration steps if database changes are needed
+- Test strategy
+
+Rules:
+- Read code to understand current state before planning
+- Be specific: include file paths, function names, class names
+- Consider edge cases and error handling
+- Do NOT edit files -- planning only
+- Flag risks and decisions that need human input`,
+		tools: ["read", "grep", "find", "ls", "bash"],
+		readOnly: true,
+	},
+
+	worker: {
+		name: "worker",
+		description: "Implementation: edits files, validates, follows the plan",
+		systemPrompt: `You are an implementation worker. Execute the plan or task by editing code.
+
+Rules:
+- Follow the plan exactly unless you find a problem
+- Edit files carefully and validate changes
+- Run tests or checks after making changes
+- If something is unclear, report it instead of guessing
+- Keep changes minimal and focused on the task
+- Commit nothing -- leave that to the parent session`,
+		tools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+	},
+
+	oracle: {
+		name: "oracle",
+		description: "Second opinion: challenges assumptions, catches drift, recommends safest move",
+		systemPrompt: `You are an oracle -- a critical thinking partner. Your job is to challenge assumptions and find problems before they happen.
+
+Tasks:
+- Review the proposed plan or approach
+- Challenge assumptions: what could go wrong?
+- Identify risks, edge cases, and missed requirements
+- Suggest the safest path forward
+- If a decision is needed, lay out the options with tradeoffs
+
+Rules:
+- Do NOT edit files
+- Be constructive but direct -- no sugarcoating
+- Prioritize: what's the most dangerous assumption?
+- End with a clear recommendation`,
+		tools: ["read", "grep", "find", "ls"],
+		readOnly: true,
+	},
+
+	researcher: {
+		name: "researcher",
+		description: "External research: docs, specs, recent changes, benchmarks",
+		systemPrompt: `You are a researcher. Find accurate, current information from documentation and the web.
+
+Tasks:
+- Search for official documentation on the topic
+- Find recent changes, migration guides, or breaking changes
+- Gather benchmarks or comparisons if relevant
+- Compile a concise research brief with sources
+
+Rules:
+- Prefer official sources over blog posts
+- Note the version/date of information
+- If using read_url_content, fetch the actual docs
+- Be concise: bullet points, not essays
+- Cite your sources`,
+		tools: ["read", "grep", "find", "ls", "bash"],
+		readOnly: true,
+	},
+
+	delegate: {
+		name: "delegate",
+		description: "General-purpose child agent for ad-hoc tasks",
+		systemPrompt: `You are a delegate agent. Execute the task you've been given by the parent session.
+
+Rules:
+- Focus exclusively on the assigned task
+- Report results clearly and concisely
+- If the task is unclear, state what you understood and what's ambiguous
+- Do not take on additional work beyond the task`,
+		tools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+	},
+};

package/extensions/index.ts

@@ -0,0 +1,188 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+import { BUILTIN_AGENTS, type AgentDefinition } from "./agents.js";
+
+export default function (elyra: ExtensionAPI): void {
+
+	// -- Tool: subagent --
+	elyra.registerTool({
+		name: "subagent",
+		label: "Delegate to Subagent",
+		description:
+			"Delegate a focused task to a specialized child agent. " +
+			"Available agents: scout (codebase recon), reviewer (code review), " +
+			"planner (implementation planning), worker (implementation), " +
+			"oracle (second opinion), researcher (docs/web research), delegate (general). " +
+			"Use this when a task benefits from focused analysis, parallel review, " +
+			"or a second opinion. Each subagent gets its own context and returns results.",
+		parameters: Type.Object({
+			agent: Type.String({
+				description: "Agent name: scout, reviewer, planner, worker, oracle, researcher, delegate",
+			}),
+			task: Type.String({
+				description: "The specific task to delegate (be clear and detailed)",
+			}),
+			context: Type.Optional(
+				Type.String({
+					description: "Additional context to provide to the subagent (e.g., file contents, previous analysis)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const agentDef = BUILTIN_AGENTS[params.agent];
+			if (!agentDef) {
+				const available = Object.keys(BUILTIN_AGENTS).join(", ");
+				return {
+					content: [{ type: "text", text: `Unknown agent: ${params.agent}. Available: ${available}` }],
+					details: {},
+				};
+			}
+
+			const subagentPrompt = formatSubagentPrompt(agentDef, params.task, params.context);
+
+			return {
+				content: [{
+					type: "text",
+					text: `## Subagent: ${agentDef.name}\n\n` +
+						`**Role**: ${agentDef.description}\n\n` +
+						`**Task**: ${params.task}\n\n` +
+						`**Instructions**: Execute this task following the subagent's role and rules:\n\n` +
+						`${subagentPrompt}\n\n` +
+						`**Allowed tools**: ${agentDef.tools?.join(", ") ?? "all"}\n` +
+						`**Read-only**: ${agentDef.readOnly ? "Yes -- do not edit files" : "No -- can edit files"}\n\n` +
+						`When done, provide a clear summary of findings/results under a "## ${agentDef.name} Report" heading.`,
+				}],
+				details: {
+					agent: agentDef.name,
+					readOnly: agentDef.readOnly ?? false,
+				},
+			};
+		},
+	});
+
+	// -- Tool: parallel_subagents --
+	elyra.registerTool({
+		name: "parallel_subagents",
+		label: "Run Parallel Subagents",
+		description:
+			"Run multiple subagents in parallel on different aspects of a task. " +
+			"Useful for parallel code review (correctness + tests + complexity), " +
+			"parallel research (docs + code), or any task that benefits from multiple focused perspectives. " +
+			"Returns combined results from all agents.",
+		parameters: Type.Object({
+			tasks: Type.Array(
+				Type.Object({
+					agent: Type.String({ description: "Agent name" }),
+					task: Type.String({ description: "Task for this agent" }),
+				}),
+				{ description: "Array of agent+task pairs to run in parallel" },
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const results: string[] = [
+				`# Parallel Subagent Execution (${params.tasks.length} agents)`,
+				"",
+			];
+
+			for (const [index, taskDef] of params.tasks.entries()) {
+				const agentDef = BUILTIN_AGENTS[taskDef.agent];
+				if (!agentDef) {
+					results.push(`## Agent ${index + 1}: ${taskDef.agent} (unknown)`);
+					results.push(`Error: Unknown agent. Available: ${Object.keys(BUILTIN_AGENTS).join(", ")}`);
+					results.push("");
+					continue;
+				}
+
+				const subagentPrompt = formatSubagentPrompt(agentDef, taskDef.task);
+
+				results.push(`## Agent ${index + 1}: ${agentDef.name}`);
+				results.push(`**Role**: ${agentDef.description}`);
+				results.push(`**Task**: ${taskDef.task}`);
+				results.push(`**Allowed tools**: ${agentDef.tools?.join(", ") ?? "all"}`);
+				results.push(`**Read-only**: ${agentDef.readOnly ? "Yes" : "No"}`);
+				results.push("");
+				results.push("**Instructions**:");
+				results.push(subagentPrompt);
+				results.push("");
+				results.push(`Provide results under a "### ${agentDef.name} Report (${index + 1})" heading.`);
+				results.push("");
+				results.push("---");
+				results.push("");
+			}
+
+			results.push("Execute each agent's task. For read-only agents, do not edit files. Synthesize all findings at the end under a ## Summary heading.");
+
+			return {
+				content: [{ type: "text", text: results.join("\n") }],
+				details: { agentCount: params.tasks.length },
+			};
+		},
+	});
+
+	// -- Command: /run --
+	elyra.registerCommand("run", {
+		description: "Run a subagent: /run <agent> <task>",
+		handler: async (args, _ctx) => {
+			const parts = args.trim().split(/\s+/);
+			const agentName = parts[0];
+			const task = parts.slice(1).join(" ");
+
+			if (!agentName) {
+				const agentList = Object.entries(BUILTIN_AGENTS)
+					.map(([name, def]) => `  ${name}: ${def.description}`)
+					.join("\n");
+				elyra.sendUserMessage(`Available subagents:\n${agentList}\n\nUsage: /run <agent> <task>`);
+				return;
+			}
+
+			if (!task) {
+				elyra.sendUserMessage(`/run ${agentName}: please provide a task. Example: /run ${agentName} analyze the auth flow`);
+				return;
+			}
+
+			elyra.sendUserMessage(`Delegate to ${agentName}: ${task}`);
+		},
+	});
+
+	// -- Command: /parallel --
+	elyra.registerCommand("parallel", {
+		description: "Run agents in parallel: /parallel reviewer 'check correctness' -> reviewer 'check tests'",
+		handler: async (args, _ctx) => {
+			if (!args.trim()) {
+				elyra.sendUserMessage(
+					"Usage: /parallel agent1 'task1' -> agent2 'task2'\n\n" +
+					"Example: /parallel reviewer 'check correctness' -> reviewer 'check tests' -> reviewer 'check complexity'",
+				);
+				return;
+			}
+
+			elyra.sendUserMessage(`Run parallel subagents: ${args}`);
+		},
+	});
+
+	// -- Command: /agents --
+	elyra.registerCommand("agents", {
+		description: "List available subagents",
+		handler: async (_args, ctx) => {
+			const agentList = Object.entries(BUILTIN_AGENTS)
+				.map(([name, def]) => `- **${name}**: ${def.description}`)
+				.join("\n");
+			ctx.ui.notify(`Available subagents:\n${agentList}`);
+		},
+	});
+}
+
+function formatSubagentPrompt(agent: AgentDefinition, task: string, context?: string): string {
+	const parts: string[] = [
+		agent.systemPrompt,
+		"",
+		"## Task",
+		task,
+	];
+
+	if (context) {
+		parts.push("", "## Additional Context", context);
+	}
+
+	return parts.join("\n");
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@elyracode/subagents",
+  "version": "0.4.8",
+    "description": "Elyra extension for subagent delegation -- scout, reviewer, planner, worker, oracle, and parallel execution",
+  "type": "module",
+  "keywords": ["elyra-package", "subagents", "delegation", "multi-agent", "parallel", "code-review"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/subagents"
+  },
+  "elyra": {
+    "extensions": ["./extensions/index.ts"],
+    "skills": ["./skills"]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/elyra-subagents/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: elyra-subagents
+description: Delegation patterns for subagent orchestration. Use when the user asks to delegate work, get a second opinion, run code review, scout a codebase, or execute parallel tasks.
+---
+
+# Subagent Delegation Patterns
+
+## Available Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `scout` | Fast codebase reconnaissance: files, structure, entry points, data flow, risks |
+| `reviewer` | Code review: correctness, tests, edge cases, simplicity, security |
+| `planner` | Implementation planning: concrete steps from existing context |
+| `worker` | Implementation: edits files, validates, follows the plan |
+| `oracle` | Second opinion: challenges assumptions, catches drift, recommends safest move |
+| `researcher` | External research: docs, specs, recent changes (uses read_url_content if available) |
+| `delegate` | General-purpose child agent for ad-hoc tasks |
+
+## When to Use Each Agent
+
+- **scout** before you understand the code
+- **researcher** before you trust external facts
+- **planner** before a bigger change
+- **worker** to implement
+- **reviewer** to check
+- **oracle** when the decision feels risky
+
+## Execution Modes
+
+### Single
+```
+Use scout to analyze the authentication flow.
+```
+
+### Parallel
+```
+Run parallel reviewers: one for correctness, one for tests, one for complexity.
+```
+
+### Chain
+```
+Scout the codebase, then plan the refactor, then implement it, then review.
+```
+
+## Orchestration Pattern
+
+The recommended loop for implementation work:
+```
+clarify -> planner -> worker -> reviewer -> worker (fixes)
+```
+
+## Rules
+- Subagents are focused and narrow -- one task per agent
+- Each subagent gets its own context and instructions
+- Results are brought back to the parent for synthesis
+- Subagents do not spawn their own subagents (max depth: 1)