@dreki-gg/pi-subagent 0.8.4 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dreki-gg/pi-subagent
 
+## 0.9.0
+
+### Minor Changes
+
+- [`99bc4e7`](https://github.com/dreki-gg/pi-extensions/commit/99bc4e7abb9f468ebd6705a56ed1c2a801dd466e) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add `list_agents` tool and `/create-agent` command to help the LLM discover available agents before spawning and scaffold new project-local agent prompts.
+
 ## 0.8.4
 
 ### Patch Changes

package/extensions/subagent/create-agent.ts

@@ -0,0 +1,98 @@
+/**
+ * /create-agent command — scaffolds a new project-local agent prompt in .pi/prompts/.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+const TEMPLATE = `---
+name: {{name}}
+description: {{description}}
+---
+
+You are the **{{name}}** agent.
+
+## Role
+
+{{description}}
+
+## Guidelines
+
+- Be concise and focused on your assigned task.
+- Use available tools to gather context before acting.
+- Report your findings or output clearly.
+`;
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export function registerCreateAgentCommand(pi: ExtensionAPI) {
+  pi.registerCommand('create-agent', {
+    description:
+      'Create a new project-local agent prompt in .pi/prompts/. Usage: /create-agent <name> [description]',
+
+    handler: async (args, ctx) => {
+      if (!args?.trim()) {
+        ctx.ui.notify(
+          'Usage: /create-agent <name> [description]\n\nCreates a new agent prompt file in .pi/prompts/',
+          'warning',
+        );
+        return;
+      }
+
+      const tokens = args.trim().split(/\s+/);
+      const name = slugify(tokens[0]);
+      const description = tokens.slice(1).join(' ') || `A project-local ${name} agent.`;
+
+      if (!name) {
+        ctx.ui.notify('Invalid agent name.', 'error');
+        return;
+      }
+
+      const promptsDir = path.join(ctx.cwd, '.pi', 'prompts');
+      const filePath = path.join(promptsDir, `${name}.md`);
+
+      if (fs.existsSync(filePath)) {
+        ctx.ui.notify(
+          `Agent "${name}" already exists at ${filePath}`,
+          'warning',
+        );
+        return;
+      }
+
+      // Create directory if needed
+      fs.mkdirSync(promptsDir, { recursive: true });
+
+      // Write the template
+      const content = TEMPLATE
+        .replace(/\{\{name\}\}/g, name)
+        .replace(/\{\{description\}\}/g, description);
+
+      fs.writeFileSync(filePath, content, 'utf-8');
+
+      ctx.ui.notify(
+        `Created agent "${name}" at ${path.relative(ctx.cwd, filePath)}`,
+        'info',
+      );
+
+      // Send a follow-up so the LLM can help refine the prompt
+      pi.sendUserMessage(
+        [
+          `I just created a new project-local agent prompt at \`${path.relative(ctx.cwd, filePath)}\`.`,
+          '',
+          `Agent name: **${name}**`,
+          `Description: ${description}`,
+          '',
+          'The file has a basic template. You can now read and refine the agent prompt to fit your needs.',
+          'Remember to use `agentScope: "both"` or `agentScope: "project"` when spawning this agent.',
+        ].join('\n'),
+        { deliverAs: 'followUp' },
+      );
+    },
+  });
+}

package/extensions/subagent/index.ts

@@ -44,6 +44,8 @@ import type { AgentResult } from './agent-runner-types.js';
 import { getFinalText } from './agent-result-utils.js';
 import { buildHandoffFromResult, renderHandoffForPrompt } from './handoffs.js';
 import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { registerListAgentsTool } from './list-agents.js';
+import { registerCreateAgentCommand } from './create-agent.js';
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
@@ -554,6 +556,9 @@ export default function (pi: ExtensionAPI) {
     return [...items.values()];
   }
 
+  registerListAgentsTool(pi, resolvePackagePaths);
+  registerCreateAgentCommand(pi);
+
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
@@ -564,6 +569,10 @@ export default function (pi: ExtensionAPI) {
       'Default agent scope is "user" (from ~/.pi/agent/prompts).',
       'To enable project-local agents in .pi/prompts, set agentScope: "both" (or "project").',
     ].join(' '),
+    promptGuidelines: [
+      'If you are unsure which agents are available, call list_agents first before using the subagent tool.',
+      'Use /create-agent to scaffold new project-local agent prompts when the user needs a custom agent.',
+    ],
     parameters: SubagentParams,
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/extensions/subagent/list-agents.ts

@@ -0,0 +1,92 @@
+/**
+ * list_agents tool — lets the LLM discover available agents before spawning.
+ */
+
+import type { ExtensionAPI, ResolvedPaths } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { type AgentScope, discoverAgents } from './agents.js';
+import { StringEnum } from '@earendil-works/pi-ai';
+
+export function registerListAgentsTool(
+  pi: ExtensionAPI,
+  resolvePackagePaths: (cwd: string) => Promise<ResolvedPaths | undefined>,
+) {
+  const AgentScopeSchema = StringEnum(['user', 'project', 'both'] as const, {
+    description:
+      'Which agent directories to search. Default: "user". Use "both" to include project-local agents.',
+    default: 'user',
+  });
+
+  pi.registerTool({
+    name: 'list_agents',
+    label: 'List Agents',
+    description:
+      'List available subagent prompts. Call this before spawning agents if you are unsure which agents exist.',
+    promptSnippet: 'List available subagent prompts to discover what agents can be spawned',
+    promptGuidelines: [
+      'Call list_agents before using the subagent tool when you are not certain which agents are available.',
+      'list_agents returns agent names, descriptions, sources, and capabilities.',
+    ],
+    parameters: Type.Object({
+      agentScope: Type.Optional(AgentScopeSchema),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const agentScope: AgentScope = params.agentScope ?? 'user';
+      const resolvedPaths = await resolvePackagePaths(ctx.cwd);
+      const discovery = discoverAgents(ctx.cwd, agentScope, resolvedPaths);
+
+      if (discovery.agents.length === 0) {
+        const dirs = agentScope === 'user'
+          ? '~/.pi/agent/prompts'
+          : agentScope === 'project'
+            ? '.pi/prompts'
+            : '~/.pi/agent/prompts and .pi/prompts';
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `No agents found in scope "${agentScope}". Check ${dirs} for agent prompt files.`,
+            },
+          ],
+          details: { agents: [], scope: agentScope },
+        };
+      }
+
+      const lines: string[] = [
+        `Available agents (scope: ${agentScope}):`,
+        '',
+      ];
+
+      for (const agent of discovery.agents) {
+        lines.push(`### ${agent.name}`);
+        lines.push(`- **Source**: ${agent.source}`);
+        lines.push(`- **Description**: ${agent.description}`);
+        if (agent.model) lines.push(`- **Default model**: ${agent.model}`);
+        if (agent.thinking) lines.push(`- **Default thinking**: ${agent.thinking}`);
+        if (agent.tools) lines.push(`- **Tools**: ${agent.tools.join(', ')}`);
+        if (agent.sessionStrategy) lines.push(`- **Session strategy**: ${agent.sessionStrategy}`);
+        lines.push('');
+      }
+
+      if (discovery.projectPromptsDir) {
+        lines.push(`Project prompts directory: ${discovery.projectPromptsDir}`);
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        details: {
+          agents: discovery.agents.map((a) => ({
+            name: a.name,
+            description: a.description,
+            source: a.source,
+            model: a.model,
+            tools: a.tools,
+          })),
+          scope: agentScope,
+          projectPromptsDir: discovery.projectPromptsDir,
+        },
+      };
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"

package/skills/spawn-subagents/SKILL.md

@@ -114,6 +114,12 @@ Avoid:
 - calling `advisor` when `planner` or `reviewer` already has enough signal to proceed alone
 - sending speculative review findings back for fixes before they are validated when evidence is needed
 
+## 8. Agent discovery and creation
+Use `list_agents` before spawning when you're unsure which agents exist.
+Use `/create-agent <name> [description]` to scaffold a new project-local agent in `.pi/prompts/` when the user needs a custom agent that doesn't exist yet.
+- After creating, read and refine the prompt file to fit the use case.
+- Remember to use `agentScope: "both"` or `"project"` to include project-local agents.
+
 Execution rules:
 - Use `manager` when the task is too large for one prompt but still needs coherent decisions.
 - Use `advisor` for targeted second opinions on tricky or high-risk cases.