@dreki-gg/pi-subagent 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- 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

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.0",
+  "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/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.
@@ -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

@@ -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
 ---
 
@@ -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/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
 ---
 
@@ -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?

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.