pi-prompt-template-model 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-04-25
+
+### Added
+- Added `boomerang: true` prompt frontmatter so non-chain templates, including looped templates, can run through prompt-template-model and then collapse their execution context back to the pre-run branch.
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.
+
+### Changed
+- Added `typebox` as a runtime dependency for packaged installs.
+
+## [0.8.2] - 2026-04-21
+
+### Added
+- Added the packaged `prompt-template-authoring` skill for creating and maintaining prompt templates with this extension.
+
+### Changed
+- Tightened the shipped skill guide so it stays short, repo-specific, and aligned with the actual prompt-template runtime.
+
+### Fixed
+- Corrected the shipped skill examples for model fallback vs rotation, argument substitution, deterministic handoff behavior, chain context wording, runtime flag syntax, and prompt discovery rules.
+- Removed the emoji from the skill-loaded renderer so the UI copy matches the extension's plain-text style.
+
+## [0.8.1] - 2026-04-21
+
+### Added
+- Added agent skill `prompt-template-authoring` for writing, managing, and running custom prompt templates. Registered in `package.json` under `pi.skills`.
+
 ## [0.8.0] - 2026-04-21
 
 ### Added

package/README.md

@@ -73,6 +73,7 @@ All fields are optional. Templates that don't use any extension features (no `mo
 | `rotate` | `false` | When `true` and looping, cycle through models in the `model` list instead of using fallback semantics. Thinking levels can also be comma-separated to pair with each model. |
 | `fresh` | `false` | When looping, collapse the conversation between iterations to a brief summary instead of carrying the full context forward. Saves tokens on long loops. |
 | `converge` | `true` | When looping, stop early if an iteration makes no file changes. Set `false` to always run every iteration. |
+| `boomerang` | `false` | After a non-chain prompt finishes, collapse its execution context back to the branch point with a brief summary. Works with loops, including `fresh` loop summaries. Useful for review prompts like `/double-check`. |
 | `worktree` | `false` | When `true`, parallel delegated work runs in separate git worktrees. Valid on chain templates with `parallel()` steps, on delegated prompts with `parallel: N`, and on compare templates via `bestOfN.worktree`. |
 
 ### Delegation
@@ -291,7 +292,7 @@ This repo ships one example compare prompt under `examples/`:
 - `examples/best-of-n.md` installs as `/best-of-n`, runs in the current repo, and shows mixed workers, mixed reviewers, and an optional final apply phase.
 - Smoke test: `/best-of-n smoke test`.
 
-Install them manually from this repo checkout (or from the installed package directory):
+Install it manually from this repo checkout (or from the installed package directory):
 
 ```bash
 PTM_DIR=/path/to/pi-prompt-template-model

package/index.ts

@@ -16,7 +16,7 @@ import {
 	type SubagentOverride,
 } from "./args.js";
 import { parseChainSteps, parseChainDeclaration, type ChainStep, type ChainStepOrParallel, type ParallelChainStep } from "./chain-parser.js";
-import { generateChainStepSummary, generateIterationSummary, didIterationMakeChanges, getIterationEntries, wasIterationAborted } from "./loop-utils.js";
+import { generateBoomerangSummary, generateChainStepSummary, generateIterationSummary, didIterationMakeChanges, getIterationEntries, wasIterationAborted } from "./loop-utils.js";
 import { selectModelCandidate } from "./model-selection.js";
 import { notify, summarizePromptDiagnostics, diagnosticsFingerprint } from "./notifications.js";
 import { preparePromptExecution, renderPromptForResolvedModel } from "./prompt-execution.js";
@@ -56,6 +56,12 @@ interface FreshCollapse {
 	totalIterations: number | null;
 }
 
+interface BoomerangCollapse {
+	targetId: string;
+	task: string;
+	previousSummaries: string[];
+}
+
 interface PendingSkillMessage {
 	customType: "skill-loaded";
 	content: string;
@@ -108,6 +114,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 	let chainActive = false;
 	let loopState: LoopState | null = null;
 	let freshCollapse: FreshCollapse | null = null;
+	let boomerangCollapse: BoomerangCollapse | null = null;
 	let accumulatedSummaries: string[] = [];
 	let lastDiagnostics = "";
 	let storedCommandCtx: ExtensionCommandContext | null = null;
@@ -918,6 +925,26 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		}
 	}
 
+	async function collapseBoomerangPrompt(
+		ctx: ExtensionContext,
+		name: string,
+		targetId: string | null,
+		previousSummaries: string[] = [],
+	) {
+		if (!targetId) {
+			notify(ctx, `Cannot boomerang prompt \`${name}\`: no session entry to return to.`, "warning");
+			return;
+		}
+
+		boomerangCollapse = { targetId, task: name, previousSummaries };
+		try {
+			const result = await ctx.navigateTree(targetId, { summarize: true });
+			if (result.cancelled) notify(ctx, `Boomerang cancelled for prompt \`${name}\``, "warning");
+		} finally {
+			boomerangCollapse = null;
+		}
+	}
+
 	async function runPromptLoop(
 		name: string,
 		cleanedArgs: string,
@@ -942,10 +969,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		let currentThinking = savedThinking;
 		const shouldRestore = initialPrompt.restore;
 		const useFresh = freshFlag || initialPrompt.fresh === true;
+		const shouldBoomerang = initialPrompt.boomerang === true;
 		const effectiveMax = totalIterations ?? UNLIMITED_LOOP_CAP;
 		const isUnlimited = totalIterations === null;
 		const useConverge = converge && initialPrompt.converge !== false;
-		const anchorId = useFresh ? ctx.sessionManager.getLeafId() : null;
+		const anchorId = useFresh || shouldBoomerang ? ctx.sessionManager.getLeafId() : null;
 
 		loopState = { currentIteration: 1, totalIterations };
 		accumulatedSummaries = [];
@@ -955,6 +983,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		let loopErrorState: ExecutionErrorState = { hasError: false, error: undefined };
 		let lastDelegatedText: string | undefined;
 		let loopAborted = false;
+		let boomerangPreviousSummaries: string[] = [];
 
 		try {
 			for (let i = 0; i < effectiveMax; i++) {
@@ -1024,7 +1053,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 					break;
 				}
 
-				if (anchorId && i < effectiveMax - 1) {
+				if (useFresh && anchorId && i < effectiveMax - 1) {
 					freshCollapse = { targetId: anchorId, task: name, iteration: i + 1, totalIterations };
 					const result = await ctx.navigateTree(anchorId, { summarize: true });
 					freshCollapse = null;
@@ -1049,9 +1078,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				"loop",
 			);
 
+			boomerangPreviousSummaries = accumulatedSummaries;
 			loopState = null;
 			pendingSkillMessage = undefined;
 			freshCollapse = null;
+			boomerangCollapse = null;
 			accumulatedSummaries = [];
 			updateLoopStatus(ctx);
 
@@ -1069,6 +1100,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			await ctx.waitForIdle();
 		}
 
+		if (!loopErrorState.hasError && !loopAborted && shouldBoomerang) {
+			await collapseBoomerangPrompt(ctx, name, anchorId, boomerangPreviousSummaries);
+		}
+
 		if (loopErrorState.hasError) {
 			throw loopErrorState.error;
 		}
@@ -1402,6 +1437,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			chainActive = false;
 			loopState = null;
 			freshCollapse = null;
+			boomerangCollapse = null;
 			accumulatedSummaries = [];
 			updateLoopStatus(ctx);
 			if (ctx.hasUI) {
@@ -1549,6 +1585,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		};
 		const savedModel = getCurrentModel(ctx);
 		const savedThinking = pi.getThinkingLevel();
+		const boomerangTargetId = effectivePrompt.boomerang ? ctx.sessionManager.getLeafId() : null;
 		const stepResult = await executePromptStep(
 			effectivePrompt,
 			parseCommandArgs(argsWithoutSubagent),
@@ -1573,6 +1610,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				previousThinking = savedThinking;
 			}
 		}
+
+		if (effectivePrompt.boomerang) {
+			await collapseBoomerangPrompt(ctx, name, boomerangTargetId);
+		}
 	}
 
 	function resetSessionScopedState(ctx: ExtensionContext) {
@@ -1581,6 +1622,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		previousModel = undefined;
 		previousThinking = undefined;
 		runtimeModel = ctx.model;
+		boomerangCollapse = null;
 		toolManager.clearQueue();
 		refreshPrompts(ctx.cwd, ctx);
 	}
@@ -1644,6 +1686,15 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_before_tree", async (event) => {
+		if (boomerangCollapse && event.preparation.targetId === boomerangCollapse.targetId) {
+			const summary = generateBoomerangSummary(event.preparation.entriesToSummarize, boomerangCollapse.task);
+			return {
+				summary: {
+					summary: [...boomerangCollapse.previousSummaries, summary].join("\n\n---\n\n"),
+				},
+			};
+		}
+
 		if (!freshCollapse) return;
 		if (event.preparation.targetId !== freshCollapse.targetId) return;
 

package/loop-utils.ts

@@ -88,7 +88,7 @@ function collectSummaryData(entries: SessionEntry[]): CollectedSummaryData {
 	};
 }
 
-function formatSummary(header: string, entries: SessionEntry[]): string {
+function formatSummary(header: string, entries: SessionEntry[], preserveOutcome = false): string {
 	const { filesRead, filesWritten, commandCount, lastAssistantText } = collectSummaryData(entries);
 
 	let summary = header;
@@ -102,9 +102,11 @@ function formatSummary(header: string, entries: SessionEntry[]): string {
 	}
 
 	if (lastAssistantText) {
-		const cleaned = lastAssistantText.replace(/\n+/g, " ").trim();
-		const truncated = cleaned.slice(0, 500);
-		summary += `\nOutcome: ${truncated}${cleaned.length > 500 ? "..." : ""}`;
+		const cleaned = preserveOutcome
+			? lastAssistantText.replace(/\r\n?/g, "\n").trim()
+			: lastAssistantText.replace(/\n+/g, " ").trim();
+		const outcome = preserveOutcome || cleaned.length <= 500 ? cleaned : `${cleaned.slice(0, 500)}...`;
+		summary += `\nOutcome: ${outcome}`;
 	}
 
 	return summary;
@@ -117,6 +119,10 @@ export function generateIterationSummary(entries: SessionEntry[], task: string,
 	return formatSummary(header, entries);
 }
 
+export function generateBoomerangSummary(entries: SessionEntry[], task: string): string {
+	return formatSummary(`[Boomerang]\nTask: "${task}"`, entries, true);
+}
+
 export function generateChainStepSummary(entries: SessionEntry[], stepLabel: string, stepNumber: number): string {
 	return formatSummary(`Step ${stepNumber} — ${stepLabel}:`, entries);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",
@@ -40,6 +40,7 @@
     "tool-manager.ts",
     "template-conditionals.ts",
     "examples",
+    "skills",
     "banner.png",
     "README.md",
     "CHANGELOG.md",
@@ -48,6 +49,9 @@
   "scripts": {
     "test": "tsx --test test/**/*.test.ts"
   },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
   "devDependencies": {
     "@mariozechner/pi-agent-core": "^0.65.0",
     "@mariozechner/pi-ai": "^0.65.0",
@@ -58,6 +62,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/prompt-loader.ts

@@ -74,6 +74,7 @@ export interface PromptWithModel {
 	fresh?: boolean;
 	loop?: number | null;
 	converge?: boolean;
+	boomerang?: boolean;
 	parallel?: number;
 	worktree?: boolean;
 	deterministic?: DeterministicStep;
@@ -303,6 +304,31 @@ function normalizeRotate(
 	return false;
 }
 
+function normalizeBoomerang(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): boolean {
+	if (value === undefined) return false;
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+
+	diagnostics.push(
+		createDiagnostic(
+			"invalid-boomerang",
+			filePath,
+			source,
+			`Using default boomerang=false for ${filePath}: frontmatter field "boomerang" must be true or false.`,
+		),
+	);
+	return false;
+}
+
 function normalizeLoop(
 	value: unknown,
 	filePath: string,
@@ -1643,6 +1669,18 @@ function loadPromptsWithModelFromDir(
 				const fresh = normalizeFresh(frontmatter.fresh, fullPath, source, diagnostics);
 				const loop = normalizeLoop(frontmatter.loop, fullPath, source, diagnostics);
 				const converge = normalizeConverge(frontmatter.converge, fullPath, source, diagnostics);
+				let boomerang = normalizeBoomerang(frontmatter.boomerang, fullPath, source, diagnostics);
+				if (chain && boomerang) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-boomerang-chain",
+							fullPath,
+							source,
+							`Ignoring boomerang in ${fullPath}: frontmatter fields "chain" and "boomerang" cannot be combined.`,
+						),
+					);
+					boomerang = false;
+				}
 				if (loop !== undefined && deterministic !== undefined) {
 					diagnostics.push(
 						createDiagnostic(
@@ -1695,6 +1733,7 @@ function loadPromptsWithModelFromDir(
 					fresh === true ||
 					loop !== undefined ||
 					converge === false ||
+					boomerang === true ||
 					safeParallel !== undefined ||
 					deterministic !== undefined ||
 					hasLineup ||
@@ -1721,6 +1760,7 @@ function loadPromptsWithModelFromDir(
 					fresh: fresh || undefined,
 					loop: loop !== undefined ? loop : undefined,
 					converge: converge === false ? false : undefined,
+					boomerang: boomerang || undefined,
 					parallel: safeParallel,
 					worktree: safeWorktree,
 					deterministic,
@@ -1821,6 +1861,7 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const thinkingValue = prompt.thinkingLevels ? prompt.thinkingLevels.join(",") : prompt.thinking;
 	const thinkingLabel = thinkingValue ? ` ${thinkingValue}` : "";
 	const loopLabel = prompt.loop !== undefined ? ` loop:${prompt.loop === null ? "unlimited" : prompt.loop}` : "";
+	const boomerangLabel = prompt.boomerang ? " boomerang" : "";
 	const subagentLabel = prompt.subagent ? ` subagent:${prompt.subagent === true ? "delegate" : prompt.subagent}` : "";
 	const parallelLabel = prompt.parallel !== undefined ? ` parallel:${prompt.parallel}` : "";
 	const deterministicLabel = prompt.deterministic ? ` deterministic-step:${prompt.deterministic.handoff}` : "";
@@ -1831,7 +1872,7 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const inheritContextLabel = prompt.inheritContext ? " fork" : "";
 	const worktreeLabel = prompt.worktree ? " worktree" : "";
 	const details =
-		`[${modelLabel}${rotateLabel}${thinkingLabel}${skillLabel}${loopLabel}${subagentLabel}${parallelLabel}${deterministicLabel}${workersLabel}${reviewersLabel}${finalApplierLabel}${cwdLabel}${inheritContextLabel}${worktreeLabel}] ${sourceLabel}`;
+		`[${modelLabel}${rotateLabel}${thinkingLabel}${skillLabel}${loopLabel}${boomerangLabel}${subagentLabel}${parallelLabel}${deterministicLabel}${workersLabel}${reviewersLabel}${finalApplierLabel}${cwdLabel}${inheritContextLabel}${worktreeLabel}] ${sourceLabel}`;
 	return prompt.description ? `${prompt.description} ${details}` : details;
 }
 

package/skill-loaded-renderer.ts

@@ -25,7 +25,7 @@ export function renderSkillLoaded(
 	container.addChild(new Spacer(1));
 
 	const box = new Box(1, 1, (text: string) => theme.bg("toolSuccessBg", text));
-	box.addChild(new Text(theme.fg("toolTitle", theme.bold(`⚡ Skill loaded: ${skillName}`)), 0, 0));
+	box.addChild(new Text(theme.fg("toolTitle", theme.bold(`Skill loaded: ${skillName}`)), 0, 0));
 	box.addChild(new Text(theme.fg("toolOutput", `   ${skillPath}`), 0, 0));
 	box.addChild(new Spacer(1));
 

package/skills/prompt-template-authoring/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: prompt-template-authoring
+description: |
+  Write and run custom Pi prompt templates (slash commands) for this extension.
+  Use when creating templates with model selection, deterministic pre-steps,
+  loops, chains, subagents, or best-of-N compare flows.
+---
+
+# Prompt Template Authoring
+
+Use this skill when working on prompt templates for `pi-prompt-template-model`.
+Templates are markdown files that register as slash commands.
+
+## Where Templates Live
+
+- `~/.pi/agent/prompts/` — user prompts (highest priority)
+- `.pi/prompts/` inside a project — project-specific prompts
+
+Extension `examples/` are reference files only. Copy them to a prompt directory to register them.
+
+## Minimal Template
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+---
+Your prompt body here.
+```
+
+Save as `my-command.md`, restart Pi, run `/my-command`. Use `description:` for autocomplete text.
+
+## Model Selection
+
+Omit `model:` to inherit the current session model. Otherwise:
+
+- `model: claude-sonnet-4-20250514` — specific model
+- `model: claude-opus-4, gpt-5.4` — fallback order (tries first, falls back to second if unavailable)
+- `model: claude-opus-4, gpt-5.4` + `rotate: true` — cycle through list on each loop iteration
+
+## Argument Substitution
+
+The prompt body can use placeholders:
+
+- `$@` — all arguments passed to the command
+- `$1`, `$2` — specific positional arguments
+- `${@:1}` — argument 1 and everything after
+
+## Deterministic Steps (Pre-LLM Execution)
+
+Run a command or script before the LLM turn. The model only sees the output if you want it to.
+
+Two equivalent forms. Don't mix them in the same prompt.
+
+**Shorthand form** — top-level keys:
+
+```yaml
+---
+run: git status --short
+handoff: always
+---
+Summarize the repo state.
+```
+
+**Nested form** — under `deterministic:`:
+
+```yaml
+---
+deterministic:
+  run: ./scripts/ship.sh
+  handoff: on-failure
+  timeout: 60000
+---
+Diagnose the failure and suggest a fix.
+```
+
+**Handoff controls when the LLM sees the result:**
+
+- `never` — run, show result, done (no LLM turn)
+- `always` — always hand result to model
+- `on-failure` — only hand off if command exits non-zero
+- `on-success` — only hand off if command exits zero
+
+**Execution forms:**
+
+- `run: command string` — runs via `/bin/bash -lc`
+- `run: {command: git, args: [status], shell: false}` — explicit args, optional shell
+- `script: ./script.sh` or `script: {path: ./script.sh, args: [--fast]}` — run a file
+
+**Constraints:**
+- Only single prompt templates (no `chain`, `loop`, `subagent`, or `parallel`)
+- Runtime flags `--loop`, `--subagent`, `--fork` are rejected for deterministic prompts
+
+## Subagent Delegation
+
+Delegate to another Pi agent instead of running inline:
+
+```yaml
+---
+model: claude-sonnet-4-20250514
+subagent: delegate          # or true, or a specific agent name
+inheritContext: true        # fork conversation context (optional)
+cwd: /absolute/path         # working directory for the subagent (optional)
+parallel: 3                 # run 3 copies in parallel (optional)
+---
+$@
+```
+
+Requires [pi-subagents](https://github.com/nicobailon/pi-subagents/) to be installed.
+
+## Loops
+
+Run the prompt multiple times:
+
+```yaml
+---
+model: claude-sonnet-4-20250514
+loop: 5                     # run exactly 5 times
+converge: true              # stop early if no changes (default)
+fresh: true                 # collapse context between iterations
+---
+$@
+```
+
+Or at runtime: `/command --loop 5`, `/command --loop` (unlimited), or `/command --loop=5 --fresh`.
+
+## Chains
+
+Chain templates declare a reusable pipeline:
+
+```yaml
+---
+chain: analyze -> fix -> test
+chainContext: summary        # pass step summaries to later delegated steps
+---
+$@
+```
+
+Or use `/chain-prompts analyze -> fix -> test` at runtime. Chain templates ignore the body and `model:` field.
+
+## Model Conditionals
+
+Show different content based on which model runs:
+
+```markdown
+<if-model is="anthropic/*">
+Use Claude-specific instructions.
+<else>
+Use default instructions.
+</if-model>
+```
+
+Supports exact IDs, `provider/model-id` pairs, wildcards (`anthropic/*`), and comma-separated combinations.
+
+## Best-of-N Compare
+
+Run multiple workers, aggregate with reviewers, optionally apply final changes:
+
+```yaml
+---
+description: Best-of-N code review
+bestOfN:
+  worktree: true            # required if using finalApplier
+  workers:
+    - model: openai-codex/gpt-5.4-mini:low
+      count: 2
+  reviewers:
+    - model: anthropic/claude-sonnet-4-20250514:medium
+  finalApplier:
+    agent: delegate
+    model: anthropic/claude-sonnet-4-20250514:high
+---
+$@
+```
+
+## Runtime Flags
+
+Override frontmatter at invocation:
+
+- `--model=provider/model-id` — use this model instead
+- `--subagent` / `--subagent=<name>` / `--subagent:<name>` — force delegation
+- `--fork` — force delegation with context fork
+- `--loop N` / `--loop=N` / `--loop` — override loop count (unlimited if bare)
+- `--fresh` — collapse context between iterations
+- `--no-converge` — run all iterations even if no changes
+- `--cwd=/absolute/path` — working directory override when the prompt supports `cwd`
+- `--chain-context` — pass summaries to later delegated chain steps
+- `--worktree` — use git worktrees for parallel delegated work
+
+When stuck, check `README.md` and `examples/best-of-n.md` in this extension.

package/tool-manager.ts

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 import { notify } from "./notifications.js";
 
 export interface ToolManagerDeps {