@dreki-gg/pi-subagent 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @dreki-gg/pi-subagent
 
+## 0.4.0
+
+### Minor Changes
+
+- [`52d744e`](https://github.com/dreki-gg/pi-extensions/commit/52d744e34f593a7bd6b907d67d5e245ef63b6079) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Improve bundled agent resolution and `/delegate` workflow control in `@dreki-gg/pi-subagent`.
+
+  - Add explicit agent source tracking for bundled, user, and project agents.
+  - Resolve agents with layered precedence: bundled → user → project.
+  - Add `agentScope` support to delegated execution so workflows can opt into user, project, or both agent layers.
+  - Add `/delegate` argument parsing for `--scope`, `--workflow`, and `--yes-project-agents`.
+  - Add a confirmation step before running project-local agents from `/delegate` or the `subagent` tool when UI is available.
+  - Replace the old `subagent-workflows` skill with `spawn-subagents`, which steers the assistant toward conversational `subagent` usage and keeps `/delegate` as an explicit gated workflow option.
+
+## 0.3.1
+
+### Patch Changes
+
+- [`144498f`](https://github.com/dreki-gg/pi-extensions/commit/144498fd9c23cb5060fb5171e56ff722ebf0c4f2) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Fix two bugs in the `subagent` tool surfaced when spawning long-running reviewer agents:
+
+  - **Bun standalone binary spawn failure**: `getPiInvocation` now detects Bun's virtual filesystem paths (`/$bunfs/...`) in `process.argv[1]` and falls back to invoking the compiled binary directly. Previously, spawned subagents would fail with errors like `/$bunfs/root/pi doesn't exist in this environment` because the virtual path was passed verbatim to `spawn`.
+  - **Parallel summary truncation**: `parallel` mode no longer truncates each child agent's final output to 100 characters in the tool result summary. Long reviews from editorial/scout agents are now returned in full so callers don't need to scrape temp files or re-run agents to see their work.
+
 ## 0.3.0
 
 ### Minor Changes
@@ -11,7 +33,7 @@
   - `/delegate` command — synthesize conversation into a task, pick a workflow, execute with scouts/planner/worker/reviewer
   - `/delegate-agents` command — list, customize, or reset bundled agents
   - 6 bundled agents: scout, docs-scout, planner, worker, reviewer, ux-designer
-  - `subagent-workflows` skill for guided orchestration
+  - `spawn-subagents` skill for conversational subagent orchestration
   - 3 prompt templates: implement, scout-and-plan, implement-and-review
 
   ### Bundled agent discovery

package/README.md

@@ -18,9 +18,21 @@ The `subagent` tool supports three modes:
 | Parallel | `{ tasks: [...] }` — multiple agents concurrently |
 | Chain | `{ chain: [...] }` — sequential with `{previous}` placeholder |
 
-## Delegate Command
+## Recommended Usage
 
-After a design/grill session:
+In day-to-day use, the main agent should usually call the `subagent` tool from normal conversation.
+
+Examples:
+- "spawn a scout for the auth code"
+- "run scout and docs-scout in parallel"
+- "have planner make a plan, then worker implement it"
+- "send this to reviewer"
+
+`/delegate` is optional. It exists for rigid gated workflows, plan approval, and explicit workflow control.
+
+## Optional Delegate Command
+
+After a design/grill session, or when you explicitly want a guided workflow:
 
 ```
 /delegate
@@ -32,6 +44,18 @@ Or with an explicit task:
 /delegate implement the auth flow we designed
 ```
 
+Use project-local repo agents:
+
+```
+/delegate --scope project implement the subagent refactor
+```
+
+Pin a workflow and skip the project-agent confirmation prompt:
+
+```
+/delegate --scope project --workflow implement --yes-project-agents improve delegate execution
+```
+
 ### How it works
 
 1. **Synthesize** — extracts goal, decisions, constraints, architecture, intent from conversation
@@ -41,6 +65,14 @@ Or with an explicit task:
 5. **Plan gate** — shows planner output for approval before worker runs
 6. **Summary** — full phase-by-phase report with usage totals
 
+### Delegate Flags
+
+| Flag | Meaning |
+|------|---------|
+| `--scope user|project|both` | Which agent layers to use. Default: `user` |
+| `--workflow <id>` | Skip the picker and force a workflow |
+| `--yes-project-agents` | Disable the confirmation prompt for project-local agents |
+
 ### Workflows
 
 | Workflow | Phases |
@@ -54,7 +86,7 @@ Or with an explicit task:
 
 ## Agent Definitions
 
-Create agent files in `~/.pi/agent/agents/` as markdown with YAML frontmatter:
+Create agent files in `~/.pi/agent/agents/` or `.pi/agents/` as markdown with YAML frontmatter:
 
 ```markdown
 ---
@@ -78,7 +110,9 @@ The package ships with these agents out of the box:
 - `reviewer` — code review
 - `ux-designer` — frontend UI design
 
-User agents in `~/.pi/agent/agents/` override bundled agents by name.
+Resolution order is: bundled → user (`~/.pi/agent/agents/`) → project (`.pi/agents/`). Project agents override user and bundled agents by name.
+
+> Note: pi packages do not currently expose a first-class `agents` manifest. If you mirror package agents into `~/.pi/agent/agents/`, treat those files as managed package artifacts rather than hand-authored overrides.
 
 ### Managing Agents
 
@@ -92,7 +126,7 @@ User agents in `~/.pi/agent/agents/` override bundled agents by name.
 ## Bundled Resources
 
 ### Skill
-- `subagent-workflows` — guides the model on when/how to use subagent orchestration
+- `spawn-subagents` — guides the model on when/how to spawn specialized subagents conversationally
 
 ### Prompt Templates
 - `/implement` — scout → planner → worker

package/extensions/subagent/agents.ts

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import { getAgentDir, parseFrontmatter } from '@mariozechner/pi-coding-agent';
 
 export type AgentScope = 'user' | 'project' | 'both';
+export type AgentSource = 'bundled' | 'user' | 'project';
 
 export interface AgentConfig {
   name: string;
@@ -15,7 +16,7 @@ export interface AgentConfig {
   model?: string;
   thinking?: string;
   systemPrompt: string;
-  source: 'user' | 'project';
+  source: AgentSource;
   filePath: string;
 }
 
@@ -27,7 +28,7 @@ export interface AgentDiscoveryResult {
 /** Bundled agents ship with the package (../../agents relative to extensions/subagent/) */
 const bundledAgentsDir = path.resolve(import.meta.dirname, '..', '..', 'agents');
 
-function loadAgentsFromDir(dir: string, source: 'user' | 'project'): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   const agents: AgentConfig[] = [];
 
   if (!fs.existsSync(dir)) {
@@ -104,7 +105,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
   const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
   // Bundled agents from the package itself (lowest priority)
-  const bundledAgents = loadAgentsFromDir(bundledAgentsDir, 'project');
+  const bundledAgents = loadAgentsFromDir(bundledAgentsDir, 'bundled');
 
   const userAgents = scope === 'project' ? [] : loadAgentsFromDir(userDir, 'user');
   const projectAgents =

package/extensions/subagent/delegate-args.ts

@@ -0,0 +1,84 @@
+import type { AgentScope } from './agents';
+import type { WorkflowId } from './delegate-types';
+
+export interface DelegateCommandOptions {
+  agentScope: AgentScope;
+  workflowId?: WorkflowId;
+  confirmProjectAgents: boolean;
+  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 parseDelegateArgs(rawArgs?: string):
+  | { ok: true; options: DelegateCommandOptions }
+  | { ok: false; error: string } {
+  const tokens = tokenize(rawArgs?.trim() ?? '');
+  const taskTokens: string[] = [];
+
+  let agentScope: AgentScope = 'user';
+  let workflowId: WorkflowId | undefined;
+  let confirmProjectAgents = true;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token === '--scope') {
+      const value = tokens[++i];
+      if (!value || !['user', 'project', 'both'].includes(value)) {
+        return { ok: false, error: `Invalid --scope value.\n\n${formatDelegateUsage()}` };
+      }
+      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()}` };
+      }
+      workflowId = value;
+      continue;
+    }
+
+    if (token === '--yes-project-agents') {
+      confirmProjectAgents = false;
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      return { ok: false, error: `Unknown option: ${token}\n\n${formatDelegateUsage()}` };
+    }
+
+    taskTokens.push(token);
+  }
+
+  return {
+    ok: true,
+    options: {
+      agentScope,
+      workflowId,
+      confirmProjectAgents,
+      explicitTask: taskTokens.join(' ').trim() || undefined,
+    },
+  };
+}

package/extensions/subagent/delegate-executor.ts

@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { withFileMutationQueue } from '@mariozechner/pi-coding-agent';
 import type { Message } from '@mariozechner/pi-ai';
-import { discoverAgents } from './agents';
+import { discoverAgents, type AgentScope } from './agents';
 import type { AgentResult, UsageStats } from './delegate-types';
 
 function emptyUsage(): UsageStats {
@@ -39,14 +39,21 @@ async function writePromptToTempFile(
 
 export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
 
+export interface RunAgentOptions {
+  agentScope?: AgentScope;
+  cwd?: string;
+  onUpdate?: OnPhaseUpdate;
+  phaseName?: string;
+  signal?: AbortSignal;
+}
+
 export async function runAgent(
   cwd: string,
   agentName: string,
   task: string,
-  onUpdate?: OnPhaseUpdate,
-  phaseName?: string,
+  options: RunAgentOptions = {},
 ): Promise<AgentResult> {
-  const { agents } = discoverAgents(cwd, 'user');
+  const { agents } = discoverAgents(cwd, options.agentScope ?? 'user');
   const agent = agents.find((a) => a.name === agentName);
 
   if (!agent) {
@@ -92,7 +99,7 @@ export async function runAgent(
     const exitCode = await new Promise<number>((resolve) => {
       const invocation = getPiInvocation(args);
       const proc = spawn(invocation.command, invocation.args, {
-        cwd,
+        cwd: options.cwd ?? cwd,
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
@@ -128,12 +135,14 @@ export async function runAgent(
             if (msg.errorMessage) result.errorMessage = msg.errorMessage;
           }
 
-          if (onUpdate) onUpdate(phaseName ?? 'unknown', agentName, { ...result });
+          if (options.onUpdate)
+            options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
         }
 
         if (event.type === 'tool_result_end' && event.message) {
           result.messages.push(event.message as Message);
-          if (onUpdate) onUpdate(phaseName ?? 'unknown', agentName, { ...result });
+          if (options.onUpdate)
+            options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
         }
       };
 
@@ -154,6 +163,17 @@ export async function runAgent(
       });
 
       proc.on('error', () => resolve(1));
+
+      if (options.signal) {
+        const killProc = () => {
+          proc.kill('SIGTERM');
+          setTimeout(() => {
+            if (!proc.killed) proc.kill('SIGKILL');
+          }, 5000);
+        };
+        if (options.signal.aborted) killProc();
+        else options.signal.addEventListener('abort', killProc, { once: true });
+      }
     });
 
     result.exitCode = exitCode;
@@ -178,8 +198,7 @@ export async function runParallel(
   cwd: string,
   agentNames: string[],
   task: string,
-  onUpdate?: OnPhaseUpdate,
-  phaseName?: string,
+  options: RunAgentOptions = {},
 ): Promise<AgentResult[]> {
   const MAX_CONCURRENCY = 4;
   const results: AgentResult[] = new Array(agentNames.length);
@@ -191,7 +210,7 @@ export async function runParallel(
       while (true) {
         const current = nextIndex++;
         if (current >= agentNames.length) return;
-        results[current] = await runAgent(cwd, agentNames[current], task, onUpdate, phaseName);
+        results[current] = await runAgent(cwd, agentNames[current], task, options);
       }
     });
 

package/extensions/subagent/index.ts

@@ -31,7 +31,14 @@ import {
 } from '@mariozechner/pi-coding-agent';
 import { Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
 import { Type } from '@sinclair/typebox';
-import { type AgentConfig, type AgentScope, bundledAgentsDir, discoverAgents } from './agents.js';
+import {
+  type AgentConfig,
+  type AgentScope,
+  type AgentSource,
+  bundledAgentsDir,
+  discoverAgents,
+} from './agents.js';
+import { formatDelegateUsage, parseDelegateArgs } from './delegate-args.js';
 import { runAgent, runParallel } from './delegate-executor.js';
 import { buildSynthesisPrompt, extractRecentConversation } from './synthesis.js';
 import type {
@@ -50,6 +57,7 @@ import {
   getFinalText,
   pickWorkflow,
 } from './delegate-ui.js';
+import { getWorkflow, suggestWorkflow } from './workflows.js';
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
@@ -172,7 +180,7 @@ interface UsageStats {
 
 interface SingleResult {
   agent: string;
-  agentSource: 'user' | 'project' | 'unknown';
+  agentSource: AgentSource | 'unknown';
   task: string;
   exitCode: number;
   messages: Message[];
@@ -256,13 +264,19 @@ async function writePromptToTempFile(
 
 function getPiInvocation(args: string[]): { command: string; args: string[] } {
   const currentScript = process.argv[1];
-  if (currentScript && fs.existsSync(currentScript)) {
+
+  // Bun standalone binaries set argv[1] to a virtual FS path (e.g. /$bunfs/root/pi)
+  // that only resolves inside the running Bun process. Skip it — the binary IS the entry point.
+  const isBunVirtualPath = currentScript?.startsWith('/$bunfs/');
+
+  if (currentScript && !isBunVirtualPath && fs.existsSync(currentScript)) {
     return { command: process.execPath, args: [currentScript, ...args] };
   }
 
   const execName = path.basename(process.execPath).toLowerCase();
   const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
   if (!isGenericRuntime) {
+    // Standalone binary (e.g. pi compiled with Bun) — invoke directly
     return { command: process.execPath, args };
   }
 
@@ -719,8 +733,7 @@ export default function (pi: ExtensionAPI) {
         const successCount = results.filter((r) => r.exitCode === 0).length;
         const summaries = results.map((r) => {
           const output = getFinalOutput(r.messages);
-          const preview = output.slice(0, 100) + (output.length > 100 ? '...' : '');
-          return `[${r.agent}] ${r.exitCode === 0 ? 'completed' : 'failed'}: ${preview || '(no output)'}`;
+          return `[${r.agent}] ${r.exitCode === 0 ? 'completed' : 'failed'}: ${output || '(no output)'}`;
         });
         return {
           content: [
@@ -1128,6 +1141,7 @@ export default function (pi: ExtensionAPI) {
     synthesis: string,
     previousOutput: string,
     ctx: ExtensionCommandContext,
+    agentScope: AgentScope,
   ): Promise<{ results: AgentResult[]; output: string; aborted: boolean }> {
     const task = phase.taskTemplate
       .replace(/\{synthesis\}/g, synthesis)
@@ -1140,17 +1154,18 @@ export default function (pi: ExtensionAPI) {
 
     let results: AgentResult[];
     if (phase.kind === 'parallel') {
-      results = await runParallel(
-        cwd,
-        phase.agents,
-        task,
-        (_phaseName, _agentName, _result) => {
+      results = await runParallel(cwd, phase.agents, task, {
+        agentScope,
+        onUpdate: (_phaseName, _agentName, _result) => {
           // Streaming updates happen per-message
         },
-        phase.name,
-      );
+        phaseName: phase.name,
+      });
     } else {
-      const result = await runAgent(cwd, phase.agents[0], task, undefined, phase.name);
+      const result = await runAgent(cwd, phase.agents[0], task, {
+        agentScope,
+        phaseName: phase.name,
+      });
       results = [result];
     }
 
@@ -1168,7 +1183,7 @@ export default function (pi: ExtensionAPI) {
     const output = combineParallelOutputs(results);
     ctx.ui.notify(formatPhaseHeader(phase.name, 'done'), 'info');
 
-    if (phase.requiresConfirmation) {
+    if (phase.requiresConfirmation && ctx.hasUI) {
       const planText = output;
       const proceed = await confirmPlan(ctx, planText);
       if (!proceed) {
@@ -1286,24 +1301,28 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand('delegate', {
-    description: 'Orchestrate subagent workflows — scouts, planners, workers, reviewers',
+    description:
+      'Orchestrate subagent workflows — supports --scope, --workflow, and project-local agents',
     handler: async (args, ctx) => {
-      const explicitTask = args?.trim() || undefined;
+      const parsed = parseDelegateArgs(args);
+      if (!parsed.ok) {
+        ctx.ui.notify(parsed.error, 'warning');
+        return;
+      }
+
+      const { explicitTask, agentScope, workflowId, confirmProjectAgents } = parsed.options;
 
       // Step 1: Synthesize
       const conversation = extractRecentConversation(ctx);
       if (!conversation.trim() && !explicitTask) {
-        ctx.ui.notify(
-          'No conversation context and no task specified. Usage: /delegate [task]',
-          'warning',
-        );
+        ctx.ui.notify(`No conversation context and no task specified.\n\n${formatDelegateUsage()}`, 'warning');
         return;
       }
 
       const prompt = buildSynthesisPrompt(conversation, explicitTask);
       ctx.ui.notify('⏳ Synthesizing task from conversation...', 'info');
 
-      const synthResult = await runAgent(ctx.cwd, 'planner', prompt);
+      const synthResult = await runAgent(ctx.cwd, 'planner', prompt, { agentScope });
       const synthesis = getFinalText(synthResult);
 
       if (!synthesis.trim()) {
@@ -1312,19 +1331,46 @@ export default function (pi: ExtensionAPI) {
       }
 
       // Step 2: Confirm synthesis
-      const synthOk = await confirmSynthesis(ctx, synthesis);
-      if (!synthOk) {
-        ctx.ui.notify('Delegate cancelled.', 'info');
-        return;
+      if (ctx.hasUI) {
+        const synthOk = await confirmSynthesis(ctx, synthesis);
+        if (!synthOk) {
+          ctx.ui.notify('Delegate cancelled.', 'info');
+          return;
+        }
       }
 
       // Step 3: Pick workflow
-      const workflow = await pickWorkflow(ctx, synthesis);
+      const workflow = workflowId
+        ? getWorkflow(workflowId)
+        : ctx.hasUI
+          ? await pickWorkflow(ctx, synthesis)
+          : getWorkflow(suggestWorkflow(synthesis));
       if (!workflow) {
         ctx.ui.notify('Delegate cancelled — no workflow selected.', 'info');
         return;
       }
 
+      if ((agentScope === 'project' || agentScope === 'both') && confirmProjectAgents && ctx.hasUI) {
+        const discovery = discoverAgents(ctx.cwd, agentScope);
+        const requestedProjectAgents = workflow.phases
+          .flatMap((phase) => phase.agents)
+          .map((name) => discovery.agents.find((agent) => agent.name === name))
+          .filter((agent): agent is AgentConfig => agent?.source === 'project');
+
+        if (requestedProjectAgents.length > 0) {
+          const names = Array.from(new Set(requestedProjectAgents.map((agent) => agent.name))).join(', ');
+          const dir = discovery.projectAgentsDir ?? '(unknown)';
+          const ok = await ctx.ui.confirm(
+            'Run project-local agents?',
+            `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+          );
+          if (!ok) {
+            ctx.ui.notify('Delegate cancelled — project-local agents not approved.', 'info');
+            return;
+          }
+        }
+      }
+
       // Step 4: Execute phases
       const state: DelegateState = {
         synthesis,
@@ -1335,10 +1381,17 @@ export default function (pi: ExtensionAPI) {
 
       let previousOutput = '';
 
-      ctx.ui.notify(`Starting workflow: ${workflow.label}`, 'info');
+      ctx.ui.notify(`Starting workflow: ${workflow.label} [${agentScope}]`, 'info');
 
       for (const phaseDef of workflow.phases) {
-        const phaseResult = await executePhase(ctx.cwd, phaseDef, synthesis, previousOutput, ctx);
+        const phaseResult = await executePhase(
+          ctx.cwd,
+          phaseDef,
+          synthesis,
+          previousOutput,
+          ctx,
+          agentScope,
+        );
 
         const phase: PhaseResult = {
           name: phaseDef.name,
@@ -1370,6 +1423,7 @@ export default function (pi: ExtensionAPI) {
         display: true,
         details: {
           workflow: workflow.id,
+          agentScope,
           phaseCount: state.phases.length,
           totalUsage: state.totalUsage,
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets",
   "keywords": [
     "pi-package"

package/skills/spawn-subagents/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: spawn-subagents
+description: Use conversational subagent orchestration with the `subagent` tool. Trigger when the user says spawn, spin up, fan out, parallelize, send to reviewer, use scout/planner/worker, or wants specialized agents to investigate, plan, implement, or review.
+---
+
+Use this skill when the user wants agents spawned conversationally.
+
+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.
+
+Strong triggers:
+- "spawn a scout"
+- "fan this out"
+- "run reviewer on this"
+- "have planner make a plan first"
+- "send docs-scout to check the docs"
+- "parallelize discovery"
+
+Patterns:
+
+## 1. Single specialist
+Use one agent when the task is narrow.
+- `scout` for repo reconnaissance
+- `docs-scout` for docs lookup
+- `planner` for a concrete plan
+- `worker` for implementation
+- `reviewer` for quality/security review
+
+## 2. Parallel recon
+Use parallel mode for noisy discovery.
+- 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.
+1. `scout` and optionally `docs-scout`
+2. `planner`
+3. `worker`
+4. optional `reviewer`
+
+## 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`
+
+Execution rules:
+- Parallelize reconnaissance, 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.
+
+When reporting back:
+- say which subagents ran
+- summarize what each contributed
+- keep the main thread focused on conclusions, not raw logs

package/skills/write-an-agent/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: write-an-agent
+description: Writes or refines concise pi subagent definitions for this repo, keeping each agent under 100 lines with a sharp role, tool policy, and output contract. Use when creating, rewriting, or tightening agent prompts in `.pi/agents/` or `packages/subagent/agents/`.
+---
+
+# Write an Agent
+
+Goal: produce a high-signal agent file in fewer than 100 lines.
+
+## Use this for
+- new repo-local agents in `.pi/agents/`
+- bundled package agents in `packages/subagent/agents/`
+- tightening bloated prompts into a crisp reusable worker
+
+## Design rules
+1. One job only. If the agent does two unrelated things, split it.
+2. One tool policy. Give the minimum tools needed.
+3. One output contract. Tell the next agent exactly what comes back.
+4. Keep the whole file under 100 lines.
+5. If the prompt needs more than 100 lines, write a skill instead.
+
+## File shape
+```md
+---
+name: agent-name
+description: What it does. Use when ...
+tools: read, grep, find, ls
+model: openai/gpt-5.4-mini
+thinking: medium
+---
+
+You are the <agent-name>.
+
+Mission:
+- outcome
+
+Rules:
+1. boundary
+2. boundary
+
+Output:
+## Section
+- exact shape
+```
+
+## Authoring workflow
+1. Name the role.
+2. Write one-sentence description with trigger language: "Use when ...".
+3. Pick the smallest tool list.
+4. Pick a cheap model for scouts, stronger model for planner/reviewer/worker.
+5. Write 3-6 rules max.
+6. Define output sections for handoff.
+7. Count lines. Trim anything decorative.
+
+## Repo conventions
+- Repo-local overrides belong in `.pi/agents/`.
+- Bundled reusable agents belong in `packages/subagent/agents/`.
+- For this repo, default roles are `scout`, `docs-scout`, `planner`, `worker`, `reviewer`.
+- Prefer local pi docs before external docs when writing `docs-scout`.
+- Mention validation commands in planner/worker/reviewer when package behavior changes.
+
+## Review checklist
+- Is the role narrower than a general engineer?
+- Would another agent know exactly when to use it?
+- Are the tools minimal?
+- Is the handoff structured?
+- Is the file under 100 lines?

package/skills/subagent-workflows/SKILL.md

@@ -1,52 +0,0 @@
----
-name: subagent-workflows
-description: Use explicit subagent workflows for planning or implementation after a grill/design session. Runs parallel scouts, then planner, then optional worker/reviewer.
----
-
-Use this skill when the user wants to execute a plan with subagents, parallelize discovery intelligently, or asks to hand work off after a design/grill session.
-
-Principles:
-- Use the `subagent` tool explicitly; do not improvise ad hoc parallelism.
-- Parallelize reconnaissance, not conflicting edits.
-- Prefer one planner synthesis step after parallel scouts.
-- Prefer one worker unless file ownership can be partitioned safely.
-- Use `docs-scout` whenever library/framework docs matter.
-
-Recommended workflows:
-
-## 1. Scout and plan
-Use when the user wants a concrete implementation plan before coding.
-
-Run `subagent` in parallel mode with two tasks:
-- `scout` for codebase reconnaissance
-- `docs-scout` for library/framework docs if docs are relevant
-
-Then run `subagent` in chain or single mode with `planner`, feeding it the scout outputs.
-
-## 2. Implement from a grilled plan
-Use when the design is already clarified and the user wants execution.
-
-Recommended sequence:
-1. Parallel scouts (`scout` + optionally `docs-scout`)
-2. `planner` synthesis
-3. `worker` implementation
-4. Optional `reviewer`
-
-## 3. Review-oriented loop
-Use when the user wants implementation with a final quality pass.
-
-Recommended sequence:
-1. `worker`
-2. `reviewer`
-3. Main agent decides whether to apply fixes directly or run another `worker`
-
-Execution guidance:
-- Keep parallel scouts focused on different concerns.
-- Do not run multiple workers against the same file set unless boundaries are explicit.
-- If docs are required, use `docs-scout` instead of relying on memory.
-- When handing off between subagents, pass the previous output verbatim or clearly summarized.
-
-When reporting back to the user:
-- Say which subagents ran
-- Summarize what each contributed
-- Present the synthesized plan or implementation result clearly