@dreki-gg/pi-subagent 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dreki-gg/pi-subagent
 
+## 0.9.2
+
+### Patch Changes
+
+- Tighten subagent prompts and the write-an-agent skill. The skill gains a "Prompt hygiene (anti-rot)" section (invariants over incidents, one owner per fact, every line must change behavior) plus matching review-checklist items, and the reviewer/worker/planner prompts state the consult handoff shape once instead of in three duplicated blocks. No behavior change.
+
 ## 0.9.1
 
 ### Patch Changes

package/extensions/subagent/create-agent.ts

@@ -58,10 +58,7 @@ export function registerCreateAgentCommand(pi: ExtensionAPI) {
       const filePath = path.join(promptsDir, `${name}.md`);
 
       if (fs.existsSync(filePath)) {
-        ctx.ui.notify(
-          `Agent "${name}" already exists at ${filePath}`,
-          'warning',
-        );
+        ctx.ui.notify(`Agent "${name}" already exists at ${filePath}`, 'warning');
         return;
       }
 
@@ -69,16 +66,14 @@ export function registerCreateAgentCommand(pi: ExtensionAPI) {
       fs.mkdirSync(promptsDir, { recursive: true });
 
       // Write the template
-      const content = TEMPLATE
-        .replace(/\{\{name\}\}/g, name)
-        .replace(/\{\{description\}\}/g, description);
+      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',
-      );
+      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(

package/extensions/subagent/handoffs.ts

@@ -39,11 +39,19 @@ interface SectionEntry {
 }
 
 function normalizeWhitespace(value: string): string {
-  return value.replace(/\r/g, '').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+  return value
+    .replace(/\r/g, '')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
 }
 
 function normalizeSectionTitle(title: string): string {
-  return title.trim().toLowerCase().replace(/[\s/]+/g, ' ').replace(/[():]/g, '');
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[\s/]+/g, ' ')
+    .replace(/[():]/g, '');
 }
 
 function splitMarkdownSections(markdown: string): { preamble: string; sections: SectionEntry[] } {
@@ -141,7 +149,10 @@ function extractPaths(text: string): HandoffFileRef[] {
   const files: HandoffFileRef[] = [];
 
   const addPath = (rawPath: string, notes?: string) => {
-    const path = rawPath.trim().replace(/^`|`$/g, '').replace(/[),.:;]+$/g, '');
+    const path = rawPath
+      .trim()
+      .replace(/^`|`$/g, '')
+      .replace(/[),.:;]+$/g, '');
     if (!path.includes('/')) return;
     if (path.startsWith('http://') || path.startsWith('https://')) return;
     if (seen.has(path)) return;
@@ -203,7 +214,9 @@ export function buildHandoffFromResult(input: {
   const riskItems = uniq(extractListItems(getFirstSectionBody(sections, ['Risks'])));
   const openQuestions = uniq([
     ...extractListItems(getFirstSectionBody(sections, ['Open Questions'])),
-    ...toQuestions(extractListItems(getFirstSectionBody(sections, ['Notes', 'Constraints or Unknowns']))),
+    ...toQuestions(
+      extractListItems(getFirstSectionBody(sections, ['Notes', 'Constraints or Unknowns'])),
+    ),
   ]);
   const goal =
     extractParagraph(getFirstSectionBody(sections, ['Goal'])) ??

package/extensions/subagent/list-agents.ts

@@ -37,11 +37,12 @@ export function registerListAgentsTool(
       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';
+        const dirs =
+          agentScope === 'user'
+            ? '~/.pi/agent/prompts'
+            : agentScope === 'project'
+              ? '.pi/prompts'
+              : '~/.pi/agent/prompts and .pi/prompts';
         return {
           content: [
             {
@@ -53,10 +54,7 @@ export function registerListAgentsTool(
         };
       }
 
-      const lines: string[] = [
-        `Available agents (scope: ${agentScope}):`,
-        '',
-      ];
+      const lines: string[] = [`Available agents (scope: ${agentScope}):`, ''];
 
       for (const agent of discovery.agents) {
         lines.push(`### ${agent.name}`);

package/extensions/subagent/run-agent-args.ts

@@ -10,16 +10,18 @@ export interface RunAgentCommandOptions {
 }
 
 function tokenize(input: string): string[] {
-  return input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? [];
+  return (
+    input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? []
+  );
 }
 
 export function formatRunAgentUsage(): string {
   return 'Usage: /run-agent [--scope user|project|both] [--model <id>] [--thinking <level>] [--yes-project-agents] <agent> [task]';
 }
 
-export function parseRunAgentArgs(rawArgs?: string):
-  | { ok: true; options: RunAgentCommandOptions }
-  | { ok: false; error: string } {
+export function parseRunAgentArgs(
+  rawArgs?: string,
+): { ok: true; options: RunAgentCommandOptions } | { ok: false; error: string } {
   const tokens = tokenize(rawArgs?.trim() ?? '');
   const taskTokens: string[] = [];
 

package/extensions/subagent/spawn-utils.ts

@@ -49,12 +49,19 @@ async function writePromptToTempFile(
   return { dir: tmpDir, filePath };
 }
 
-function cleanupTempFiles(
-  tmpPromptPath: string | null,
-  tmpPromptDir: string | null,
-): void {
-  if (tmpPromptPath) try { fs.unlinkSync(tmpPromptPath); } catch { /* ignore */ }
-  if (tmpPromptDir) try { fs.rmdirSync(tmpPromptDir); } catch { /* ignore */ }
+function cleanupTempFiles(tmpPromptPath: string | null, tmpPromptDir: string | null): void {
+  if (tmpPromptPath)
+    try {
+      fs.unlinkSync(tmpPromptPath);
+    } catch {
+      /* ignore */
+    }
+  if (tmpPromptDir)
+    try {
+      fs.rmdirSync(tmpPromptDir);
+    } catch {
+      /* ignore */
+    }
 }
 
 export interface ToolExecutionStartEvent {

package/package.json

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

package/prompts/planner.md

@@ -12,14 +12,10 @@ You must NOT make any changes. Only read, analyze, and plan.
 
 If the task has multiple viable designs, unclear ownership boundaries, or needs sharper decomposition before implementation, you may consult the `advisor` agent with the `subagent` tool.
 
-When consulting `advisor`, send only:
-- current role: `planner`
-- the exact design or decomposition question
-- implicated files or packages
-- the smallest relevant task summary
-- what constraints or trade-offs you already see
-
-Treat `advisor` as a focused second opinion. You still own the plan.
+When consulting `advisor`, send only: your role (`planner`), the exact
+design or decomposition question, the implicated files/packages, the
+smallest relevant task summary, and the constraints or trade-offs you
+already see. Treat it as a focused second opinion — you still own the plan.
 
 Input format you'll receive:
 - Context/findings from a scout agent

package/prompts/reviewer.md

@@ -30,25 +30,10 @@ Rules:
 8. Use `advisor` only when severity, intended behavior, or trade-offs remain unclear after inspection and validation.
 9. You still own the final review judgment. Support agents inform your conclusion; they do not replace it.
 
-When consulting `validator`, send only:
-- current role: `reviewer`
-- the exact bug or behavior claim to validate
-- changed files or symbols involved
-- the smallest relevant goal summary
-- what you already verified from diff/code
-
-When consulting `bug-prover`, send only:
-- current role: `reviewer`
-- the exact claim that now needs a minimal repro
-- files, symbols, tests, or commands already inspected
-- why read-only validation was insufficient
-
-When consulting `advisor`, send only:
-- current role: `reviewer`
-- the exact uncertainty or severity question
-- changed files or symbols involved
-- the smallest relevant goal summary
-- what you verified or could not verify from diff/code
+When consulting any support agent, send only: your role (`reviewer`), the
+exact claim or question, the files/symbols involved, the smallest relevant
+goal summary, and what you already verified from diff/code. For
+`bug-prover`, add why read-only validation was insufficient.
 
 Strategy:
 1. Inspect the diff and understand the reason for the change

package/prompts/worker.md

@@ -12,14 +12,10 @@ Work autonomously to complete the assigned task. Use all available tools as need
 
 If a focused second opinion would reduce risk, you may consult the `advisor` agent with the `subagent` tool. Reserve that for ambiguous architecture tradeoffs, persistent failing tests or unexplained errors, merge conflicts or tangled diffs, and security-sensitive or migration-heavy changes.
 
-When consulting `advisor`, send only:
-- current role: `worker`
-- the exact question
-- touched files or symbols
-- the smallest relevant task summary
-- what you already tried or observed
-
-Treat `advisor` as a second opinion, not a replacement owner. You stay responsible for implementation and the final result.
+When consulting `advisor`, send only: your role (`worker`), the exact
+question, the touched files/symbols, the smallest relevant task summary,
+and what you already tried or observed. Treat it as a second opinion, not a
+replacement owner — you stay responsible for the final result.
 
 Keep the final response compact. It should function as a review packet for downstream agents, not a long implementation diary.
 

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

@@ -59,9 +59,33 @@ Output:
 - Prefer local pi docs before external docs when writing `docs-scout`.
 - Mention validation commands in planner/worker/reviewer when package behavior changes.
 
+## Prompt hygiene (anti-rot)
+
+Prompts are code: unmaintained instructions become technical debt. Apply the
+same doctrine a project applies to its AGENTS.md — durable facts and
+invariants, not narration.
+
+- **Invariants, not incidents.** A rule earned from a field bug must state
+  the durable invariant, never the story ("fixes relocate gaps more often
+  than they close them" — not "remember that PR"). References to tools,
+  tickets, or model quirks of the moment rot first.
+- **One owner per fact.** Anything that drifts (model ids, tool lists,
+  paths) lives in frontmatter or arrives in the caller's task — never
+  restated in the body. A block repeated across prompts is the same fact
+  with N owners: compress it to one convention line per prompt.
+- **Every line changes behavior.** If deleting a line would not change what
+  the agent does, delete it.
+- **Output contracts are APIs.** Downstream agents parse the sections;
+  renaming or reshaping them is a breaking change — evolve additively.
+- **Update on every miss.** When an agent fails in the field, amend the rule
+  that should have caught it — as an invariant, in the same change as the
+  fix. A prompt that never absorbs its misses is rotting silently.
+
 ## 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?
+- Does any line narrate an incident instead of stating its invariant?
+- Is any fact stated here also owned somewhere else?