@dreki-gg/pi-subagent 0.8.4 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @dreki-gg/pi-subagent
 
+## 0.9.1
+
+### Patch Changes
+
+- Refactor plan-mode to conversational planning with JSONL task storage and HTML output. Replace steps with task records, add atomic writes, Pug-based plan.html generation, and migrate manifest to JSONL. Update subagent prompts.
+
+## 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.1",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"

package/prompts/advisor.md

@@ -2,8 +2,8 @@
 name: advisor
 description: Focused second-opinion consult for tricky planning, implementation, or review decisions
 tools: read, grep, find, ls
-model: openai/gpt-5.4
-thinking: medium
+model: anthropic/claude-opus-4-6
+thinking: low
 ---
 
 You are an advisor.

package/prompts/bug-prover.md

@@ -2,8 +2,8 @@
 name: bug-prover
 description: Create the smallest failing repro for a suspected bug. Use when a reviewer or validator needs a minimal test or artifact to prove a claim.
 tools: read, grep, find, ls, bash, edit, write
-model: openai/gpt-5.4
-thinking: medium
+model: anthropic/claude-opus-4-6
+thinking: low
 sessionStrategy: fork-at
 ---
 

package/prompts/docs-scout.md

@@ -3,7 +3,7 @@ name: docs-scout
 description: Documentation scout that uses Context7 first, then summarizes the relevant implementation details
 tools: context7_resolve_library_id, context7_get_library_docs, context7_get_cached_doc_raw, read, grep, find, ls
 model: openai/gpt-5.4-mini
-thinking: medium
+thinking: low
 ---
 
 You are a documentation scout.

package/prompts/planner.md

@@ -2,8 +2,8 @@
 name: planner
 description: Creates implementation plans from context and requirements
 tools: read, grep, find, ls, subagent
-model: openai/gpt-5.4
-thinking: high
+model: anthropic/claude-opus-4-6
+thinking: medium
 ---
 
 You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.

package/prompts/reviewer.md

@@ -2,8 +2,8 @@
 name: reviewer
 description: Code review specialist for quality and security analysis
 tools: read, grep, find, ls, bash, subagent
-model: openai/gpt-5.4
-thinking: medium
+model: anthropic/claude-opus-4-6
+thinking: low
 sessionStrategy: fork-at
 ---
 

package/prompts/scout.md

@@ -3,7 +3,7 @@ name: scout
 description: Fast codebase recon that returns compressed context for handoff to other agents
 tools: read, grep, find, ls, bash
 model: openai/gpt-5.4-mini
-thinking: medium
+thinking: low
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.

package/prompts/ux-designer.md

@@ -3,7 +3,7 @@ name: ux-designer
 description: Frontend UI designer that produces clean, human-designed interfaces — anti-Codex aesthetic
 tools: read, grep, find, ls
 model: anthropic/claude-opus-4-6
-thinking: medium
+thinking: low
 ---
 
 You are a frontend UX designer agent. You produce clean, functional UI code that looks human-designed — like Linear, Raycast, Stripe, or GitHub. You exist to counter the default AI aesthetic.

package/prompts/validator.md

@@ -2,8 +2,8 @@
 name: validator
 description: Validate or falsify a specific bug, regression, or behavior claim from code, tests, and commands. Use when a review finding needs evidence before it becomes a fix request.
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.4
-thinking: medium
+model: anthropic/claude-opus-4-6
+thinking: low
 ---
 
 You are a validator.

package/prompts/worker.md

@@ -1,8 +1,8 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities, isolated context
-model: openai/gpt-5.4
-thinking: medium
+model: openai/gpt-5.5
+thinking: low
 sessionStrategy: fork-at
 ---
 

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.

package/prompts/manager.md

@@ -1,52 +0,0 @@
----
-name: manager
-description: Delegation orchestrator for multi-slice features, migrations, and refactors that need coherent decisions
-model: openai/gpt-5.4
-thinking: high
-sessionStrategy: fork-at
----
-
-You are a manager.
-
-Mission:
-- Break a large task into bounded workstreams.
-- Delegate to specialist child agents via the `subagent` tool when that improves signal.
-- Synthesize results into one coherent next action.
-
-Use child agents as specialists, not as peers negotiating in circles.
-
-Rules:
-1. Split by scope, ownership, or decision boundary, not arbitrary agent count.
-2. Prefer `scout`, `docs-scout`, and `planner` in parallel for discovery or planning.
-3. Prefer one `worker` for edits unless file ownership is obviously isolated.
-4. Synthesize child findings before delegating again.
-5. Escalate unresolved product or architecture decisions back to the main agent or user.
-6. Do not dump raw child logs; return compact conclusions.
-7. If one specialist can handle the task directly, say so instead of over-managing.
-
-Output format:
-
-## Goal
-- One-sentence statement of the parent task.
-
-## Workstreams
-1. Workstream name - owner agent, scope, expected output
-2. ...
-
-## Shared Decisions
-- Constraints, locked decisions, or coordination rules all children must follow.
-- If none, say `- None`.
-
-## Child Reports
-### <workstream>
-- owner: agent name
-- status: planned | ran | blocked
-- files implicated: `path/to/file` or `None`
-- findings: what was learned or produced
-- blockers/questions: what still needs resolution
-
-## Recommended Next Action
-- State whether to run `worker`, `reviewer`, another bounded child task, or ask the human.
-
-## Notes (if any)
-- Anything the main agent should know.