@dreki-gg/pi-subagent 0.5.0 → 0.7.0

package/extensions/subagent/{delegate-args.ts → run-agent-args.ts}

@@ -1,43 +1,33 @@
 import type { AgentScope } from './agents';
-import type { WorkflowId } from './delegate-types';
 
-export interface DelegateCommandOptions {
+export interface RunAgentCommandOptions {
   agentScope: AgentScope;
-  workflowId?: WorkflowId;
   confirmProjectAgents: boolean;
+  model?: string;
+  thinking?: string;
+  agentName?: string;
   explicitTask?: string;
 }
 
-const WORKFLOW_IDS = new Set<WorkflowId>([
-  'scout-only',
-  'scout-and-plan',
-  'implement',
-  'implement-and-review',
-  'quick-fix',
-  'review',
-]);
-
 function tokenize(input: string): string[] {
   return input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? [];
 }
 
-export function formatDelegateUsage(): string {
-  return [
-    'Usage: /delegate [--scope user|project|both] [--workflow <id>] [--yes-project-agents] [task]',
-    '',
-    'Workflows: scout-only, scout-and-plan, implement, implement-and-review, quick-fix, review',
-  ].join('\n');
+export function formatRunAgentUsage(): string {
+  return 'Usage: /run-agent [--scope user|project|both] [--model <id>] [--thinking <level>] [--yes-project-agents] <agent> [task]';
 }
 
-export function parseDelegateArgs(rawArgs?: string):
-  | { ok: true; options: DelegateCommandOptions }
+export function parseRunAgentArgs(rawArgs?: string):
+  | { ok: true; options: RunAgentCommandOptions }
   | { ok: false; error: string } {
   const tokens = tokenize(rawArgs?.trim() ?? '');
   const taskTokens: string[] = [];
 
   let agentScope: AgentScope = 'user';
-  let workflowId: WorkflowId | undefined;
   let confirmProjectAgents = true;
+  let model: string | undefined;
+  let thinking: string | undefined;
+  let agentName: string | undefined;
 
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
@@ -45,18 +35,27 @@ export function parseDelegateArgs(rawArgs?: string):
     if (token === '--scope') {
       const value = tokens[++i];
       if (!value || !['user', 'project', 'both'].includes(value)) {
-        return { ok: false, error: `Invalid --scope value.\n\n${formatDelegateUsage()}` };
+        return { ok: false, error: `Invalid --scope value.\n\n${formatRunAgentUsage()}` };
       }
       agentScope = value as AgentScope;
       continue;
     }
 
-    if (token === '--workflow') {
-      const value = tokens[++i] as WorkflowId | undefined;
-      if (!value || !WORKFLOW_IDS.has(value)) {
-        return { ok: false, error: `Invalid --workflow value.\n\n${formatDelegateUsage()}` };
+    if (token === '--model') {
+      const value = tokens[++i];
+      if (!value) {
+        return { ok: false, error: `Missing --model value.\n\n${formatRunAgentUsage()}` };
+      }
+      model = value;
+      continue;
+    }
+
+    if (token === '--thinking' || token === '--reasoning-level') {
+      const value = tokens[++i];
+      if (!value) {
+        return { ok: false, error: `Missing ${token} value.\n\n${formatRunAgentUsage()}` };
       }
-      workflowId = value;
+      thinking = value;
       continue;
     }
 
@@ -66,7 +65,12 @@ export function parseDelegateArgs(rawArgs?: string):
     }
 
     if (token.startsWith('--')) {
-      return { ok: false, error: `Unknown option: ${token}\n\n${formatDelegateUsage()}` };
+      return { ok: false, error: `Unknown option: ${token}\n\n${formatRunAgentUsage()}` };
+    }
+
+    if (!agentName) {
+      agentName = token;
+      continue;
     }
 
     taskTokens.push(token);
@@ -76,8 +80,10 @@ export function parseDelegateArgs(rawArgs?: string):
     ok: true,
     options: {
       agentScope,
-      workflowId,
       confirmProjectAgents,
+      model,
+      thinking,
+      agentName,
       explicitTask: taskTokens.join(' ').trim() || undefined,
     },
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.5.0",
-  "description": "Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets",
+  "version": "0.7.0",
+  "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled agents",
   "keywords": [
     "pi-package"
   ],
@@ -26,9 +26,6 @@
     "skills": [
       "./skills"
     ],
-    "prompts": [
-      "./prompts"
-    ],
     "agents": [
       "./agents"
     ]
@@ -44,6 +41,6 @@
     "@mariozechner/pi-agent-core": "*",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   }
 }

package/skills/spawn-subagents/SKILL.md

@@ -5,10 +5,14 @@ description: Use conversational subagent orchestration with the `subagent` tool.
 
 Use this skill when the user wants agents spawned conversationally.
 
+Core rule:
+- Parallelize discovery and verification, not conflicting edits.
+- Prefer one `worker` unless file ownership is clearly partitioned.
+
 Default behavior:
 - Prefer the `subagent` tool directly.
-- Do **not** default to `/delegate`.
-- Use `/delegate` only when the user explicitly wants a gated workflow, workflow picker, or plan approval step.
+- Use `/run-agent` only when the user explicitly wants a direct named-agent run.
+- This package is agent-first: build the needed `single` / `parallel` / `chain` orchestration directly instead of reaching for canned workflow prompts.
 
 Strong triggers:
 - "spawn a scout"
@@ -17,6 +21,11 @@ Strong triggers:
 - "have planner make a plan first"
 - "send docs-scout to check the docs"
 - "parallelize discovery"
+- "coordinate this migration"
+- "break this feature into child workstreams"
+- "ask advisor for a second opinion on this"
+- "validate whether this review finding is real"
+- "prove this bug with a minimal failing test"
 
 Patterns:
 
@@ -27,15 +36,18 @@ Use one agent when the task is narrow.
 - `planner` for a concrete plan
 - `worker` for implementation
 - `reviewer` for quality/security review
+- `validator` to confirm or falsify a specific bug or behavior claim
+- `bug-prover` to create the smallest failing repro when a claim needs proof
+- `advisor` for a focused second opinion on a tricky or high-risk decision
 
 ## 2. Parallel recon
-Use parallel mode for noisy discovery.
+Use parallel mode for noisy discovery, not implementation races.
 - Run `scout` + `docs-scout` in parallel when both code and docs matter.
 - Keep parallel tasks non-overlapping.
 - Return a compact synthesis to the main thread.
 
 ## 3. Plan then implement
-Use chain mode when the user wants safe sequencing.
+Use chain mode when the user wants safe sequencing around one implementing agent.
 1. `scout` and optionally `docs-scout`
 2. `planner`
 3. `worker`
@@ -43,14 +55,74 @@ Use chain mode when the user wants safe sequencing.
 
 ## 4. Review loop
 Use after implementation or when the user asks for a second opinion.
-1. `reviewer`
-2. main agent applies fixes directly or sends focused follow-up to `worker`
+1. `reviewer` inspects the diff and code
+2. if a suspected issue needs evidence, run `validator`
+3. if proof still needs a minimal failing test or repro artifact, run `bug-prover`
+4. only send confirmed, evidenced findings back to `worker`
+
+## 5. Manager pattern
+Use `manager` when the task is too large for one prompt but still needs coherent decisions.
+1. `manager` splits the work into bounded workstreams
+2. `manager` runs `scout`, `docs-scout`, or `planner` in parallel when discovery can be split cleanly
+3. `manager` keeps implementation single-writer by default, handing edits to one `worker` unless ownership is clearly partitioned
+4. `manager` synthesizes child reports before recommending the next action
+
+Good fits:
+- multi-package migrations
+- larger refactors with several discovery threads
+- features spanning backend, UI, and docs that still need shared decisions
+
+## 6. Claim validation and proof
+Use `validator` and `bug-prover` when review claims should be evidenced before they become fix requests.
+
+Good fits:
+- reviewer suspects a regression but needs command/test evidence
+- worker wants to confirm whether an edge case is truly broken
+- a bug claim seems plausible but not yet proven from diff/code alone
+- you want a minimal failing test before authorizing a fix
+
+Flow:
+- `validator` first for read-only verification with code, tests, and focused commands
+- `bug-prover` only when proof needs a new failing test or isolated repro artifact
+- keep repro scope narrow; proving is not fixing
+
+## 7. Targeted advisor consult
+Use `advisor` when the primary owner is still clear, but a tricky question needs a strong second opinion.
+
+Good fits:
+- planner is choosing between multiple designs with different blast radius
+- worker is stuck in a failing test loop or messy migration
+- reviewer is unsure whether a suspected issue is real, intended, or severe
+- the change is security-sensitive or otherwise high risk
+
+Consult packet:
+- current role (`worker`, `planner`, `reviewer`, or `main-agent`)
+- exact question to answer
+- smallest relevant task summary
+- touched files or symbols, if known
+- what has already been tried, verified, or observed
+
+Rules:
+- advisor use is optional, not a default step
+- keep the primary role in charge of the final plan, implementation, or review judgment
+- prefer one clear advisor recommendation over a long brainstorm
+
+Avoid:
+- arbitrary peer-to-peer negotiation loops
+- unbounded swarms
+- multiple workers editing overlapping files
+- 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
 
 Execution rules:
-- Parallelize reconnaissance, not conflicting edits.
+- 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.
+- Use `validator` to confirm a claim before escalating it as a fix.
+- Use `bug-prover` only when confirmation needs a minimal failing test or repro artifact.
+- Parallelize reconnaissance and verification, not conflicting edits.
 - Prefer one `worker` unless file ownership is clearly partitioned.
 - Use `docs-scout` when external library/framework details matter.
-- Pass previous outputs verbatim or as a tight structured summary.
+- Pass a compact handoff or structured summary via `{previous}`, not an unbounded transcript dump.
 
 When reporting back:
 - say which subagents ran

package/extensions/subagent/delegate-types.ts

@@ -1,62 +0,0 @@
-import type { Message } from '@mariozechner/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;
-}
-
-export type WorkflowId =
-  | 'scout-only'
-  | 'scout-and-plan'
-  | 'implement'
-  | 'implement-and-review'
-  | 'quick-fix'
-  | 'review';
-
-export interface WorkflowDefinition {
-  id: WorkflowId;
-  label: string;
-  description: string;
-  phases: PhaseDefinition[];
-}
-
-export type PhaseKind = 'parallel' | 'single';
-
-export interface PhaseDefinition {
-  kind: PhaseKind;
-  name: string;
-  agents: string[];
-  requiresConfirmation?: boolean;
-  taskTemplate: string;
-}
-
-export interface PhaseResult {
-  name: string;
-  kind: PhaseKind;
-  agents: AgentResult[];
-  skipped?: boolean;
-}
-
-export interface DelegateState {
-  synthesis: string;
-  workflow: WorkflowDefinition;
-  phases: PhaseResult[];
-  totalUsage: UsageStats;
-}

package/extensions/subagent/delegate-ui.ts

@@ -1,132 +0,0 @@
-import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
-import type {
-  AgentResult,
-  DelegateState,
-  PhaseResult,
-  UsageStats,
-  WorkflowDefinition,
-} from './delegate-types';
-import { WORKFLOWS, suggestWorkflow } from './workflows';
-
-function formatTokens(count: number): string {
-  if (count < 1000) return count.toString();
-  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-  if (count < 1000000) return `${Math.round(count / 1000)}k`;
-  return `${(count / 1000000).toFixed(1)}M`;
-}
-
-function formatUsage(usage: UsageStats): string {
-  const parts: string[] = [];
-  if (usage.turns) parts.push(`${usage.turns} turns`);
-  if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-  if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-  if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-  if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-  return parts.join(' ');
-}
-
-function getFinalText(result: AgentResult): string {
-  for (let i = result.messages.length - 1; i >= 0; i--) {
-    const msg = result.messages[i];
-    if (msg.role === 'assistant') {
-      for (const part of msg.content) {
-        if (part.type === 'text') return part.text;
-      }
-    }
-  }
-  return '(no output)';
-}
-
-export async function confirmSynthesis(
-  ctx: ExtensionCommandContext,
-  synthesis: string,
-): Promise<boolean> {
-  return ctx.ui.confirm('Delegate — Task Synthesis', `${synthesis}\n\nProceed with this task?`);
-}
-
-export async function pickWorkflow(
-  ctx: ExtensionCommandContext,
-  synthesis: string,
-): Promise<WorkflowDefinition | null> {
-  const suggested = suggestWorkflow(synthesis);
-  const options = WORKFLOWS.map((wf) => {
-    const marker = wf.id === suggested ? ' ← suggested' : '';
-    return `${wf.label}${marker} — ${wf.description}`;
-  });
-
-  const choice = await ctx.ui.select('Delegate — Choose Workflow', options);
-  if (choice === undefined || choice === null) return null;
-
-  const selectedIndex = options.indexOf(choice as string);
-  if (selectedIndex < 0) return null;
-
-  return WORKFLOWS[selectedIndex];
-}
-
-export async function confirmPlan(
-  ctx: ExtensionCommandContext,
-  planText: string,
-): Promise<boolean> {
-  return ctx.ui.confirm('Delegate — Review Plan', `${planText}\n\nContinue with implementation?`);
-}
-
-export function formatPhaseHeader(
-  phaseName: string,
-  status: 'running' | 'done' | 'failed' | 'skipped',
-): string {
-  const icons = { running: '⏳', done: '✓', failed: '✗', skipped: '⊘' };
-  return `${icons[status]} ${phaseName}`;
-}
-
-export function formatAgentResult(result: AgentResult): string {
-  const icon = result.exitCode === 0 ? '✓' : '✗';
-  const output = getFinalText(result);
-  const preview = output.length > 200 ? `${output.slice(0, 200)}...` : output;
-  const usage = formatUsage(result.usage);
-  const model = result.model ? ` [${result.model}]` : '';
-
-  return `${icon} ${result.agent}${model}\n${preview}\n${usage}`;
-}
-
-export function formatPhaseSummary(phase: PhaseResult): string {
-  if (phase.skipped) return `⊘ ${phase.name} — skipped`;
-
-  const header = `── ${phase.name} (${phase.kind}) ──`;
-  const agentSummaries = phase.agents.map(formatAgentResult).join('\n\n');
-  return `${header}\n${agentSummaries}`;
-}
-
-export function formatFullSummary(state: DelegateState): string {
-  const sections = [
-    `── Synthesis ──\n${state.synthesis}`,
-    `── Workflow: ${state.workflow.label} ──`,
-    ...state.phases.map(formatPhaseSummary),
-    `── Usage ──\nTotal: ${formatUsage(state.totalUsage)}`,
-  ];
-
-  return sections.join('\n\n');
-}
-
-export function aggregateUsage(results: AgentResult[]): UsageStats {
-  const total: UsageStats = {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    cost: 0,
-    contextTokens: 0,
-    turns: 0,
-  };
-  for (const r of results) {
-    total.input += r.usage.input;
-    total.output += r.usage.output;
-    total.cacheRead += r.usage.cacheRead;
-    total.cacheWrite += r.usage.cacheWrite;
-    total.cost += r.usage.cost;
-    total.turns += r.usage.turns;
-  }
-  return total;
-}
-
-export { getFinalText };

package/extensions/subagent/workflows.ts

@@ -1,150 +0,0 @@
-import type { WorkflowDefinition, WorkflowId } from './delegate-types';
-
-export const WORKFLOWS: WorkflowDefinition[] = [
-  {
-    id: 'scout-only',
-    label: 'Scout only',
-    description: 'Parallel scouts for exploration — no plan, no implementation',
-    phases: [
-      {
-        kind: 'parallel',
-        name: 'Scouts',
-        agents: ['scout', 'docs-scout'],
-        taskTemplate: '{synthesis}',
-      },
-    ],
-  },
-  {
-    id: 'scout-and-plan',
-    label: 'Scout and plan',
-    description: 'Parallel scouts → planner — produces a plan without implementing',
-    phases: [
-      {
-        kind: 'parallel',
-        name: 'Scouts',
-        agents: ['scout', 'docs-scout'],
-        taskTemplate: '{synthesis}',
-      },
-      {
-        kind: 'single',
-        name: 'Planner',
-        agents: ['planner'],
-        taskTemplate:
-          'Create an implementation plan based on the following context.\n\n## Task\n{synthesis}\n\n## Scout findings\n{previous}',
-      },
-    ],
-  },
-  {
-    id: 'implement',
-    label: 'Implement',
-    description: 'Parallel scouts → planner → worker — full implementation',
-    phases: [
-      {
-        kind: 'parallel',
-        name: 'Scouts',
-        agents: ['scout', 'docs-scout'],
-        taskTemplate: '{synthesis}',
-      },
-      {
-        kind: 'single',
-        name: 'Planner',
-        agents: ['planner'],
-        requiresConfirmation: true,
-        taskTemplate:
-          'Create an implementation plan based on the following context.\n\n## Task\n{synthesis}\n\n## Scout findings\n{previous}',
-      },
-      {
-        kind: 'single',
-        name: 'Worker',
-        agents: ['worker'],
-        taskTemplate:
-          'Implement the following plan.\n\n## Task\n{synthesis}\n\n## Plan\n{previous}',
-      },
-    ],
-  },
-  {
-    id: 'implement-and-review',
-    label: 'Implement and review',
-    description:
-      'Parallel scouts → planner → worker → reviewer — full implementation with code review',
-    phases: [
-      {
-        kind: 'parallel',
-        name: 'Scouts',
-        agents: ['scout', 'docs-scout'],
-        taskTemplate: '{synthesis}',
-      },
-      {
-        kind: 'single',
-        name: 'Planner',
-        agents: ['planner'],
-        requiresConfirmation: true,
-        taskTemplate:
-          'Create an implementation plan based on the following context.\n\n## Task\n{synthesis}\n\n## Scout findings\n{previous}',
-      },
-      {
-        kind: 'single',
-        name: 'Worker',
-        agents: ['worker'],
-        taskTemplate:
-          'Implement the following plan.\n\n## Task\n{synthesis}\n\n## Plan\n{previous}',
-      },
-      {
-        kind: 'single',
-        name: 'Reviewer',
-        agents: ['reviewer'],
-        taskTemplate:
-          'Review the implementation described below.\n\n## Task\n{synthesis}\n\n## Implementation output\n{previous}',
-      },
-    ],
-  },
-  {
-    id: 'quick-fix',
-    label: 'Quick fix',
-    description: 'Worker only — fast, no scouts or planning',
-    phases: [
-      {
-        kind: 'single',
-        name: 'Worker',
-        agents: ['worker'],
-        taskTemplate: '{synthesis}',
-      },
-    ],
-  },
-  {
-    id: 'review',
-    label: 'Review',
-    description: 'Reviewer only — code review of recent changes',
-    phases: [
-      {
-        kind: 'single',
-        name: 'Reviewer',
-        agents: ['reviewer'],
-        taskTemplate: '{synthesis}',
-      },
-    ],
-  },
-];
-
-export function getWorkflow(id: WorkflowId): WorkflowDefinition {
-  const wf = WORKFLOWS.find((w) => w.id === id);
-  if (!wf) throw new Error(`Unknown workflow: ${id}`);
-  return wf;
-}
-
-export function suggestWorkflow(synthesis: string): WorkflowId {
-  const lower = synthesis.toLowerCase();
-
-  const hasReview = /review|audit|check quality|security/.test(lower);
-  const hasFix = /fix|bug|patch|hotfix|quick/.test(lower);
-  const hasImplement = /implement|build|create|add|refactor|migrate/.test(lower);
-  const hasDesign = /design|plan|architect|explore|investigate|scout/.test(lower);
-
-  if (hasFix && !hasImplement && !hasDesign) return 'quick-fix';
-  if (hasReview && !hasImplement && !hasDesign) return 'review';
-  if (hasDesign && !hasImplement) return 'scout-and-plan';
-  if (hasImplement && hasReview) return 'implement-and-review';
-  if (hasImplement) return 'implement';
-
-  return 'implement';
-}

package/prompts/implement-and-review.md

@@ -1,10 +0,0 @@
----
-description: Worker implements, reviewer reviews, worker applies feedback
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "worker" agent to implement: $@
-2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
-3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}.

package/prompts/implement.md

@@ -1,10 +0,0 @@
----
-description: Full implementation workflow - scout gathers context, planner creates plan, worker implements
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "scout" agent to find all code relevant to: $@
-2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
-3. Finally, use the "worker" agent to implement the plan from the previous step (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}.

package/prompts/scout-and-plan.md

@@ -1,9 +0,0 @@
----
-description: Scout gathers context, planner creates implementation plan (no implementation)
----
-Use the subagent tool with the chain parameter to execute this workflow:
-
-1. First, use the "scout" agent to find all code relevant to: $@
-2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
-
-Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.