@dreki-gg/pi-subagent 0.6.0 → 0.8.0

package/docs/plans/05_advisor-routing.plan.md

@@ -0,0 +1,244 @@
+---
+name: "Advisor / smart-friend routing"
+overview: "Add a bundled `advisor` role and lightweight escalation guidance so strong primary agents in `@dreki-gg/pi-subagent` can ask for focused second opinions on tricky cases without turning every task into a swarm. This slice is about capability routing, not replacing the main worker."
+todo:
+  - id: "advisor-routing-1"
+    task: "Add a bundled `advisor` agent with a focused consultative contract: diagnose, suggest next investigation, and surface risks without taking ownership of implementation"
+    status: done
+  - id: "advisor-routing-2"
+    task: "Teach bundled worker/planner/reviewer prompts when to call the advisor and what context to send"
+    status: done
+  - id: "advisor-routing-3"
+    task: "Add a reusable prompt entry point and docs examples for advisor-assisted workflows"
+    status: done
+---
+
+# Goal
+
+Introduce a lightweight advisor pattern so primary agents can consult a strong second opinion for hard cases while keeping a single primary owner of the work.
+
+# Context
+
+- Parent rationale: we want capability routing and targeted escalation, not a default “everyone talks to everyone” swarm.
+- Module root: `packages/subagent`
+- This slice should work with the current package architecture and should not depend on a new runtime mode.
+- Keep the advisor narrowly scoped: diagnose, redirect, highlight risk, or suggest the next question. The advisor should not silently become another worker.
+
+## What exists
+
+Current relevant file tree on disk:
+
+- `packages/subagent/prompts/planner.md`
+- `packages/subagent/prompts/reviewer.md`
+- `packages/subagent/prompts/worker.md`
+- `packages/subagent/prompts/docs-scout.md`
+- `packages/subagent/prompts/implement.md`
+- `packages/subagent/prompts/implement-and-review.md`
+- `packages/subagent/README.md`
+- `packages/subagent/extensions/subagent/index.ts`
+- `packages/subagent/extensions/subagent/agent-runner.ts`
+- `packages/subagent/skills/spawn-subagents/SKILL.md`
+- `packages/subagent/skills/write-an-agent/SKILL.md`
+
+Actual current state on disk:
+
+- There is no bundled `advisor` agent in `packages/subagent/prompts/`.
+- There is no advisor-oriented prompt template in `packages/subagent/prompts/`.
+- The current bundled roles are:
+  - `planner` for planning (`packages/subagent/prompts/planner.md`)
+  - `worker` for implementation (`packages/subagent/prompts/worker.md`)
+  - `reviewer` for verification (`packages/subagent/prompts/reviewer.md`)
+  - plus `scout`, `docs-scout`, and `ux-designer`
+- The package runner already supports spawned agents consulting tools as needed:
+  - in `packages/subagent/extensions/subagent/index.ts:325-328`, `runSingleAgent()` passes `--tools` only when frontmatter declares them
+  - in `packages/subagent/extensions/subagent/agent-runner.ts:73-76`, `runAgent()` behaves the same way
+  - therefore bundled agents with omitted `tools:` can keep access to the broader tool surface, including `subagent`
+- The current prompt contracts do **not** teach any role when to escalate:
+  - `planner.md` only says to produce a concrete plan
+  - `worker.md` only says to complete the task autonomously
+  - `reviewer.md` only says to review the diff / files
+- The `spawn-subagents` skill recommends specialists and review loops, but does not mention an advisor or “consult when tricky” routing rule.
+
+# API inventory
+
+## Existing agent prompt contracts that may invoke advisor
+
+From `packages/subagent/prompts/planner.md`:
+
+```md
+You are a planning specialist.
+You must NOT make any changes. Only read, analyze, and plan.
+```
+
+From `packages/subagent/prompts/worker.md`:
+
+```md
+You are a worker agent with full capabilities.
+Work autonomously to complete the assigned task. Use all available tools as needed.
+```
+
+From `packages/subagent/prompts/reviewer.md`:
+
+```md
+You are a senior code reviewer.
+Analyze code for quality, security, and maintainability.
+```
+
+## Existing subagent entry shapes available to an advisor pattern
+
+From the `subagent` tool surface:
+
+```ts
+// single consult
+{ agent: 'advisor', task: '...' }
+
+// consult inside a chain
+{ chain: [{ agent: 'worker', task: '...' }, { agent: 'advisor', task: '... {previous} ...' }] }
+
+// focused parallel consults
+{ tasks: [{ agent: 'advisor', task: '...' }, { agent: 'docs-scout', task: '...' }] }
+```
+
+## Proposed advisor contract
+
+The advisor should return guidance the caller can act on immediately:
+
+```md
+## Assessment
+- what looks tricky / risky / ambiguous
+
+## What to inspect next
+- concrete files, commands, or questions
+
+## Recommendation
+- best next action for the caller
+
+## Risks
+- what could still go wrong
+```
+
+The advisor should not claim to have implemented or verified anything it did not actually inspect.
+
+# Tasks
+
+## 1. Add a bundled `advisor` agent with a focused consultative contract
+
+### Files
+- Create `packages/subagent/prompts/advisor.md`
+
+### What to add
+Create a concise bundled agent whose sole job is to provide focused second-opinion guidance.
+
+### Required behavior
+- Work from the caller’s question plus any provided handoff.
+- Ask the caller to investigate specific files / commands when the answer depends on context the advisor has not yet inspected.
+- Surface hidden risks or better approaches.
+- Avoid taking over implementation.
+- Prefer decisive recommendations over brainstorming lists.
+
+### Frontmatter guidance
+- Use an existing strong model already in package conventions (default to `openai/gpt-5.4` unless there is a strong reason to diversify).
+- Keep the prompt under ~100 lines per `packages/subagent/skills/write-an-agent/SKILL.md`.
+- Omit `tools:` only if you want the advisor to have broad access; otherwise keep the tool list minimal and read-oriented.
+
+### Suggested prompt rules
+1. Diagnose the hard part, not the whole task from scratch.
+2. If more repo context is needed, say exactly what to inspect next.
+3. Return a recommendation the caller can act on immediately.
+4. Do not implement code or rewrite plans unless explicitly asked.
+
+## 2. Teach bundled prompts when to call the advisor and what context to send
+
+### Files
+- Modify `packages/subagent/prompts/worker.md`
+- Modify `packages/subagent/prompts/planner.md`
+- Modify `packages/subagent/prompts/reviewer.md`
+
+### What to change
+Add small, explicit escalation rules to the existing bundled roles.
+
+### Recommended escalation triggers
+- `worker`
+  - ambiguous architecture tradeoff
+  - persistent failing tests or unexplained errors
+  - merge conflicts / tangled diffs
+  - security-sensitive or migration-heavy changes
+- `planner`
+  - multiple viable designs with materially different blast radius
+  - unclear ownership boundaries across packages
+  - need for sharper decomposition before implementation
+- `reviewer`
+  - uncertainty whether an issue is real vs. intended
+  - suspected deeper architectural problem beyond the current diff
+  - need for a second opinion on severity
+
+### Required context to send when consulting advisor
+Keep the consult lightweight:
+- current role (`worker` / `planner` / `reviewer`)
+- the exact question
+- touched files / symbols if known
+- the smallest relevant task summary
+- what has already been tried or observed
+
+### Notes
+- Do not tell every role to always call the advisor. This is an escalation path, not a mandatory step.
+- Keep the primary role in charge; the advisor should inform decisions, not replace ownership.
+
+## 3. Add a reusable prompt entry point and docs examples for advisor-assisted workflows
+
+### Files
+- Create `packages/subagent/prompts/consult-advisor.md`
+- Modify `packages/subagent/README.md`
+- Modify `packages/subagent/skills/spawn-subagents/SKILL.md`
+
+### What to add
+Create a simple prompt template that encourages focused advisor consultation without changing core workflow semantics.
+
+### Suggested prompt shape
+
+```md
+Use the subagent tool to consult the `advisor` agent about: $@
+
+The advisor should:
+1. identify the hard part
+2. suggest the next investigation or decision
+3. surface concrete risks
+4. return a recommendation, not a full implementation
+```
+
+### README / skill updates
+- Add `advisor` to the bundled agent list once shipped.
+- Add one example such as:
+  - “ask advisor whether this migration should be split before sending it to worker”
+  - “have worker consult advisor on the failing test loop”
+- In `spawn-subagents`, add guidance that advisor use is optional and should be reserved for tricky or high-risk cases.
+
+# Files to create
+
+- `packages/subagent/prompts/advisor.md`
+- `packages/subagent/prompts/consult-advisor.md`
+
+# Files to modify
+
+- `packages/subagent/prompts/worker.md` — add narrow escalation guidance
+- `packages/subagent/prompts/planner.md` — add narrow escalation guidance
+- `packages/subagent/prompts/reviewer.md` — add narrow escalation guidance
+- `packages/subagent/README.md` — document the new advisor role and one or two examples
+- `packages/subagent/skills/spawn-subagents/SKILL.md` — explain when to use advisor vs. planner/reviewer
+
+# Testing notes
+
+- If this remains markdown-only, there is no TypeScript validation requirement.
+- Manually test one focused consult, such as a planner or worker asking advisor a hard question, and verify:
+  - the advisor returns a recommendation rather than trying to own the full task
+  - the caller stays in charge of implementation or review
+  - the exchange is shorter and more targeted than a full additional workflow
+- If you introduce any helper TS module later to render consult packets, run `bun run --filter '@dreki-gg/pi-subagent' typecheck`.
+
+# Patterns to follow
+
+- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:46-67` — keep the new agent narrow, concise, and output-contract-driven
+- `packages/subagent/prompts/planner.md:9-38` — example of a specialist planner role that the advisor should complement, not replace
+- `packages/subagent/prompts/reviewer.md:10-37` — example of a verifier role that may occasionally need escalation
+- `packages/subagent/prompts/worker.md:9-26` — example of a primary owner role that should remain in charge after consulting advisor
+- `packages/subagent/skills/spawn-subagents/SKILL.md:23-58` — existing specialist-selection guidance to extend with optional escalation

package/extensions/subagent/agent-result-utils.ts

@@ -0,0 +1,12 @@
+import type { AgentResult } from './agent-runner-types.js';
+
+export function getFinalText(result: AgentResult): string {
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const msg = result.messages[i];
+    if (msg.role !== 'assistant') continue;
+    for (const part of msg.content) {
+      if (part.type === 'text') return part.text;
+    }
+  }
+  return '(no output)';
+}

package/extensions/subagent/agent-runner-types.ts

@@ -0,0 +1,23 @@
+import type { Message } from '@earendil-works/pi-ai';
+
+export interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+export interface AgentResult {
+  agent: string;
+  task: string;
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}

package/extensions/subagent/agent-runner.ts

@@ -0,0 +1,90 @@
+import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
+import { discoverAgents, type AgentScope } from './agents.js';
+import type { AgentResult } from './agent-runner-types.js';
+import { emptyUsage, spawnPiAgent } from './spawn-utils.js';
+
+export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
+
+export interface RunAgentOptions {
+  agentScope?: AgentScope;
+  cwd?: string;
+  model?: string;
+  thinking?: string;
+  onUpdate?: OnPhaseUpdate;
+  phaseName?: string;
+  signal?: AbortSignal;
+  resolvedPaths?: ResolvedPaths;
+}
+
+export async function runAgent(
+  cwd: string,
+  agentName: string,
+  task: string,
+  options: RunAgentOptions = {},
+): Promise<AgentResult> {
+  const { agents } = discoverAgents(cwd, options.agentScope ?? 'user', options.resolvedPaths);
+  const agent = agents.find((a) => a.name === agentName);
+
+  if (!agent) {
+    const available = agents.map((a) => a.name).join(', ') || 'none';
+    return {
+      agent: agentName,
+      task,
+      exitCode: 1,
+      messages: [],
+      stderr: `Unknown agent: "${agentName}". Available: ${available}.`,
+      usage: emptyUsage(),
+    };
+  }
+
+  const selectedModel = options.model ?? agent.model;
+  const selectedThinking = options.thinking ?? agent.thinking;
+
+  const result: AgentResult = {
+    agent: agentName,
+    task,
+    exitCode: 0,
+    messages: [],
+    stderr: '',
+    usage: emptyUsage(),
+    model: selectedModel,
+  };
+
+  const spawnResult = await spawnPiAgent({
+    cwd: options.cwd ?? cwd,
+    agentName: agent.name,
+    task,
+    systemPrompt: agent.systemPrompt,
+    model: selectedModel,
+    thinking: selectedThinking,
+    tools: agent.tools,
+    signal: options.signal,
+    onMessage: () => {
+      // Copy accumulated state for the phase update callback
+      if (options.onUpdate) {
+        result.messages = spawnResult.messages;
+        result.usage = spawnResult.usage;
+        result.model = spawnResult.model ?? result.model;
+        result.stopReason = spawnResult.stopReason;
+        result.errorMessage = spawnResult.errorMessage;
+        options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
+      }
+    },
+    onToolResult: () => {
+      if (options.onUpdate) {
+        result.messages = spawnResult.messages;
+        options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
+      }
+    },
+  });
+
+  result.exitCode = spawnResult.exitCode;
+  result.messages = spawnResult.messages;
+  result.stderr = spawnResult.stderr;
+  result.usage = spawnResult.usage;
+  result.model = spawnResult.model ?? result.model;
+  result.stopReason = spawnResult.stopReason;
+  result.errorMessage = spawnResult.errorMessage;
+
+  return result;
+}

package/extensions/subagent/agents.ts

@@ -1,21 +1,18 @@
 /**
  * Agent discovery and configuration
  *
- * Supports two discovery strategies:
- * 1. Package-resolved: Uses pi's ResolvedPaths.agents from the package manager
- *    when available (pi forks with first-class agents resource support).
- *    Package agents are resolved, filtered, and toggleable via pi config.
- * 2. Legacy: Manual filesystem discovery from bundled, user, and project dirs.
- *    Used as fallback when ResolvedPaths.agents is not available.
+ * Uses pi's ResolvedPaths.prompts from the package manager to discover
+ * agent prompts from installed packages. User and project prompts are
+ * discovered from the filesystem and override package prompts by name.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getAgentDir, parseFrontmatter } from '@mariozechner/pi-coding-agent';
-import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
+import { getAgentDir, parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
 
 export type AgentScope = 'user' | 'project' | 'both';
-export type AgentSource = 'bundled' | 'user' | 'project' | 'package';
+export type AgentSource = 'user' | 'project' | 'package';
 export type AgentSessionStrategy = 'inline' | 'fork-at';
 
 export interface AgentConfig {
@@ -32,12 +29,9 @@ export interface AgentConfig {
 
 export interface AgentDiscoveryResult {
   agents: AgentConfig[];
-  projectAgentsDir: string | null;
+  projectPromptsDir: string | null;
 }
 
-/** Bundled agents ship with the package (../../agents relative to extensions/subagent/) */
-const bundledAgentsDir = path.resolve(import.meta.dirname, '..', '..', 'agents');
-
 function parseSessionStrategy(value?: string): AgentSessionStrategy | undefined {
   if (!value) return undefined;
   const normalized = value.trim().toLowerCase();
@@ -106,10 +100,10 @@ function isDirectory(p: string): boolean {
   }
 }
 
-function findNearestProjectAgentsDir(cwd: string): string | null {
+function findNearestProjectPromptsDir(cwd: string): string | null {
   let currentDir = cwd;
   while (true) {
-    const candidate = path.join(currentDir, '.pi', 'agents');
+    const candidate = path.join(currentDir, '.pi', 'prompts');
     if (isDirectory(candidate)) return candidate;
 
     const parentDir = path.dirname(currentDir);
@@ -119,18 +113,14 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 }
 
 /**
- * Load agents from package-manager resolved paths (enabled only).
- * This is called with pre-resolved paths from an async context.
+ * Load agents from package-manager resolved prompt paths (enabled only).
  */
-export function loadAgentsFromResolvedPaths(resolvedPaths: ResolvedPaths): AgentConfig[] {
-  // Check if the agents field exists (compatibility with upstream pi)
-  const agentResources = (resolvedPaths as unknown as Record<string, unknown>).agents;
-  if (!agentResources || !Array.isArray(agentResources)) {
-    return [];
-  }
+function loadAgentsFromResolvedPaths(resolvedPaths: ResolvedPaths): AgentConfig[] {
+  const promptResources = (resolvedPaths as unknown as Record<string, unknown>).prompts;
+  if (!Array.isArray(promptResources)) return [];
 
   const agents: AgentConfig[] = [];
-  for (const resource of agentResources) {
+  for (const resource of promptResources) {
     if (!resource.enabled) continue;
     const agent = loadAgentFromFile(resource.path, 'package');
     if (agent) agents.push(agent);
@@ -169,21 +159,28 @@ function loadAgentFromFile(filePath: string, source: AgentSource): AgentConfig |
   };
 }
 
-export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-  const userDir = path.join(getAgentDir(), 'agents');
-  const projectAgentsDir = findNearestProjectAgentsDir(cwd);
-
-  // Bundled agents from the package itself (lowest priority)
-  const bundledAgents = loadAgentsFromDir(bundledAgentsDir, 'bundled');
+/**
+ * Discover agents from package-resolved prompts, user, and project directories.
+ *
+ * Priority: package (lowest) → user → project (highest, overrides by name).
+ */
+export function discoverAgents(
+  cwd: string,
+  scope: AgentScope,
+  resolvedPaths?: ResolvedPaths,
+): AgentDiscoveryResult {
+  const userDir = path.join(getAgentDir(), 'prompts');
+  const projectPromptsDir = findNearestProjectPromptsDir(cwd);
 
+  const packageAgents = resolvedPaths ? loadAgentsFromResolvedPaths(resolvedPaths) : [];
   const userAgents = scope === 'project' ? [] : loadAgentsFromDir(userDir, 'user');
   const projectAgents =
-    scope === 'user' || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, 'project');
+    scope === 'user' || !projectPromptsDir ? [] : loadAgentsFromDir(projectPromptsDir, 'project');
 
-  // Priority: bundled (lowest) → user → project (highest, overrides by name)
   const agentMap = new Map<string, AgentConfig>();
 
-  for (const agent of bundledAgents) agentMap.set(agent.name, agent);
+  // Package agents are lowest priority
+  for (const agent of packageAgents) agentMap.set(agent.name, agent);
 
   if (scope === 'both') {
     for (const agent of userAgents) agentMap.set(agent.name, agent);
@@ -194,48 +191,5 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
     for (const agent of projectAgents) agentMap.set(agent.name, agent);
   }
 
-  return { agents: Array.from(agentMap.values()), projectAgentsDir };
-}
-
-/**
- * Discover agents with package-resolved paths merged in.
- * Package-resolved agents (from pi.agents in installed packages) are loaded
- * at lowest priority, then overridden by bundled, user, and project agents.
- *
- * Falls back to discoverAgents() when resolvedPaths is not provided or
- * does not contain the agents field (upstream pi compatibility).
- */
-export function discoverAgentsWithPackages(
-  cwd: string,
-  scope: AgentScope,
-  resolvedPaths?: ResolvedPaths,
-): AgentDiscoveryResult {
-  const base = discoverAgents(cwd, scope);
-
-  if (!resolvedPaths) return base;
-
-  const packageAgents = loadAgentsFromResolvedPaths(resolvedPaths);
-  if (packageAgents.length === 0) return base;
-
-  // Package agents are lowest priority: existing agents override by name
-  const agentMap = new Map<string, AgentConfig>();
-  for (const agent of packageAgents) agentMap.set(agent.name, agent);
-  for (const agent of base.agents) agentMap.set(agent.name, agent);
-
-  return { agents: Array.from(agentMap.values()), projectAgentsDir: base.projectAgentsDir };
-}
-
-export { bundledAgentsDir };
-
-export function formatAgentList(
-  agents: AgentConfig[],
-  maxItems: number,
-): { text: string; remaining: number } {
-  if (agents.length === 0) return { text: 'none', remaining: 0 };
-  const listed = agents.slice(0, maxItems);
-  const remaining = agents.length - listed.length;
-  return {
-    text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join('; '),
-    remaining,
-  };
+  return { agents: Array.from(agentMap.values()), projectPromptsDir };
 }