@whamp/pi-pstack 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @whamp/pi-pstack
+
+pstack for Pi: rigorous agent workflows you can parallelize with confidence. Ported from the Cursor pstack plugin.
+
+If you want to go fast, go deep first. pstack helps you write less, but higher quality code. It gives you fearless parallelism: when an agent goes deep and writes good, verifiable code, you can parallelize with confidence. Start multiple agents with `poteto-mode` and trust they will apply rigorous engineering principles to their work.
+
+## Install
+
+```bash
+pi install npm:@whamp/pi-pstack
+```
+
+Or install from the repository, which is the source of truth for this port:
+
+```bash
+git clone https://github.com/Whamp/pi-extensions.git ~/projects/pi-extensions
+cd ~/projects/pi-extensions
+pnpm install --frozen-lockfile
+pi install ~/projects/pi-extensions/packages/pi-pstack
+```
+
+This package is ported from the Cursor pstack plugin by Lauren Tan
+(`LICENSE`).
+
+Requires [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) for the `poteto-agent`, `comment-sicko`, and workflow fan-outs (`how`, `why`, `arena`, `swarm`, `interrogate`, `reflect`).
+
+## Get started
+
+1. Run `/setup-pstack` once to pick which models each role uses (optional; every role inherits the parent session model otherwise).
+2. Use `/poteto-mode` for sticky Poteto Mode. It stays on until `/poteto-mode off`. `/skill:poteto-mode` also enables it.
+3. Run `/pstack off` to hide even the four Discoverable skills (`how`, `why`, `unslop`, `typescript-best-practices`) from the Skill catalog.
+   Off persists in `~/.pi/agent/pstack/models.json`.
+   `/skill:<name>` keeps working.
+   `/pstack on` restores those four, not all 47.
+
+That is it.
+The other skills are Hidden; the mode skill uses them as needed.
+
+## What you get
+
+- **47 skills**, including:
+  - `poteto-mode`: the main entry point. Reads your request, matches one of 23 playbooks (bug fix, perf, feature, refactoring, investigation, shipping, orchestrate, autopilot, and more), copies its steps in verbatim, and routes to the other skills as steps fire. Orchestrate refills one shared worker-and-verifier window as each child settles.
+  - Workflow skills: `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `reflect`, `teach`, `tdd`, `no-comments`, `unslop`, `deslop`, `bro`, `figure-it-out`, `show-me-your-work`, `create-verification-skill`, `maintain-verification-skill`, `automate-me`, `technical-writing`, `typescript-best-practices`.
+  - 23 principle skills (`principle-laziness-protocol`, `principle-model-the-domain`, `principle-prove-it-works`, ...), one rule each, indexed inline by `poteto-mode`.
+- **`ask_user_question`**: one structured preference question with 2-6 listed options. The user can pick those or type a different answer.
+- **2 subagents** (loaded by pi-subagents):
+  - `poteto-agent`: runs poteto's style end to end. Reads `poteto-mode` in full before any work.
+  - `comment-sicko`: read-only comment reviewer that savors deletion. Usually invoked through the `no-comments` skill.
+- **Bundled scripts**: `poteto-mode/scripts/` ships the `orch` coordination CLI (orchestrate playbook) and the `watch-pr` watcher (babysit playbook). Both run under [bun](https://bun.sh).
+
+## Model roles
+
+Per-role model choices live in `~/.pi/agent/pstack/models.json`. Run `/setup-pstack` to write it. The 22 role names and cardinalities are in `skills/setup-pstack/references/MODEL-ROLES.md`. The extension injects the role table only when a role has a real model slug. Default inherit-all injects nothing. `inherit-parent` or `auto` runs on the parent session model.
+
+## Differences from the Cursor plugin
+
+- Hidden skills set `disable-model-invocation: true`, so they stay out of the Skill catalog.
+  `/skill:name` still loads the Skill body.
+  The four Discoverable skills are `how`, `why`, `unslop`, and `typescript-best-practices`.
+- Slash commands are `/skill:<name>` instead of `/name`.
+- Subagent delegation uses pi-subagents. Launch one child with `subagent({ action: "execute", input: { agent, task } })`. Set `input.async: true` for background work. Run parallel or dependent children in one `workflowScript` with stable keys. This package does not ship the `subagent` tool.
+- Session transcripts live under `~/.pi/agent/sessions/` instead of `~/.cursor/projects/`. The active file is `$PI_SESSION_FILE`. Files are grouped by cwd slug (`--<cwd>--`, absolute cwd with `/` replaced by `-`).
+- The benny automation pack is not ported; it depends on Cursor automations. Model roles live in `~/.pi/agent/pstack/models.json`, written by `/setup-pstack` and injected only when a role has a real model slug.
+- `make-bot-ui` is not ported. It is Cursor Grok Bot / routine webhook UI.
+
+## License
+
+MIT

package/agents/comment-sicko.md

@@ -0,0 +1,34 @@
+---
+name: comment-sicko
+description: A deranged comment-hater that savors deletion and condemns workaround code. Read-only review agent; usually invoked through the no-comments skill.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+---
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run the `how` and `why` skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/agents/poteto-agent.md

@@ -0,0 +1,13 @@
+---
+name: poteto-agent
+description: Routing target for /skill:poteto-mode and any request for poteto's style. Reads the poteto-mode skill's SKILL.md in full before any work, including its inline Principles index.
+tools: read, grep, find, ls, bash, edit, write
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+thinking: high
+---
+
+You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full (use `fffind` or `ls` under the pi-pstack package's `skills/poteto-mode/` if it is not already in context) before doing any work, including its inline Principles index. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+
+Execute the assigned task exactly as that skill prescribes: match a playbook, copy its steps in verbatim, cite principles with the decisions they changed, and write the reply clean as you draft it. You own the work; review your own diff and report what changed for the consumer and the maintainer.

package/extensions/pstack/ask-user-question.ts

@@ -0,0 +1,137 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+/** Reserved select item that opens a typed answer instead of a listed option. */
+export const TYPE_DIFFERENT_ANSWER_OPTION = "Type a different answer";
+
+const DONE_OPTION = "Done";
+
+export interface PstackQuestionRequest {
+	question: string;
+	options: string[];
+	allow_multiple?: boolean;
+}
+
+export interface PstackQuestionUi {
+	hasUI: boolean;
+	ui: {
+		select(title: string, options: string[]): Promise<string | undefined>;
+		input(title: string, placeholder?: string): Promise<string | undefined>;
+	};
+}
+
+export interface PstackQuestionAnswer {
+	selections: string[];
+	cancelled: boolean;
+}
+
+function labeledQuestionOptions(options: string[]): string[] {
+	return options.map((option, index) => `${index + 1}. ${option}`);
+}
+
+/** Format the host UI result as the tool's text content. */
+export function formatPstackQuestionAnswer(answer: PstackQuestionAnswer): string {
+	if (!answer.cancelled) {
+		return `Selected: ${answer.selections.join(", ")}`;
+	}
+	if (answer.selections.length > 0) {
+		return `Question cancelled after selecting: ${answer.selections.join(", ")}`;
+	}
+	return "Question cancelled without a selection.";
+}
+
+/** Ask one preference question, always offering a typed answer beside the listed options. */
+export async function askPstackQuestion(
+	request: PstackQuestionRequest,
+	ctx: PstackQuestionUi,
+): Promise<PstackQuestionAnswer> {
+	if (!ctx.hasUI) {
+		throw new Error("Pstack question UI unavailable in this Pi mode");
+	}
+
+	const labels = labeledQuestionOptions(request.options);
+	const remaining = [...labels];
+	const selections: string[] = [];
+
+	while (remaining.length > 0 || request.allow_multiple === true) {
+		const choices = [
+			...(selections.length > 0 ? [DONE_OPTION] : []),
+			...remaining,
+			TYPE_DIFFERENT_ANSWER_OPTION,
+		];
+		const selected = await ctx.ui.select(request.question, choices);
+		if (selected === undefined) {
+			return { selections, cancelled: true };
+		}
+		if (selected === DONE_OPTION) {
+			return { selections, cancelled: false };
+		}
+		if (selected === TYPE_DIFFERENT_ANSWER_OPTION) {
+			const typed = await ctx.ui.input(request.question, "Your answer");
+			if (typed === undefined) {
+				continue;
+			}
+			const answer = typed.trim();
+			if (answer === "") {
+				continue;
+			}
+			selections.push(answer);
+			if (request.allow_multiple !== true) {
+				return { selections, cancelled: false };
+			}
+			continue;
+		}
+
+		const remainingIndex = remaining.indexOf(selected);
+		if (remainingIndex === -1) {
+			throw new Error("Pstack question UI returned an unknown option");
+		}
+		const optionIndex = labels.indexOf(selected);
+		const option = request.options[optionIndex];
+		if (option === undefined) {
+			throw new Error("Pstack question option index is invalid");
+		}
+		selections.push(option);
+		remaining.splice(remainingIndex, 1);
+
+		if (request.allow_multiple !== true) {
+			return { selections, cancelled: false };
+		}
+	}
+
+	return { selections, cancelled: false };
+}
+
+/** Register the model-facing ask_user_question tool on a Pi extension API. */
+export function registerAskUserQuestion(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user_question",
+		label: "Ask User Question",
+		description:
+			"Ask one structured preference or product question with 2-6 choices. The user can pick listed options or type a different answer.",
+		promptSnippet: "Ask a structured preference or product question with selectable options",
+		promptGuidelines: [
+			"Use ask_user_question only for genuine preference or product decisions that available evidence cannot settle.",
+		],
+		executionMode: "sequential",
+		parameters: Type.Object(
+			{
+				question: Type.String({ minLength: 1 }),
+				options: Type.Array(Type.String({ minLength: 1 }), {
+					minItems: 2,
+					maxItems: 6,
+					uniqueItems: true,
+				}),
+				allow_multiple: Type.Optional(Type.Boolean()),
+			},
+			{ additionalProperties: false },
+		),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const answer = await askPstackQuestion(params, ctx);
+			return {
+				content: [{ type: "text", text: formatPstackQuestionAnswer(answer) }],
+				details: answer,
+			};
+		},
+	});
+}

package/extensions/pstack/config.ts

@@ -0,0 +1,55 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DANGEROUS_KEY_PARTS = new Set(["__proto__", "constructor", "prototype"]);
+const MAX_MODEL_KEY_LENGTH = 256;
+const INHERIT_SELECTORS = new Set(["inherit-parent", "auto"]);
+
+/** Resolve the Pi coding-agent directory, expanding PI_CODING_AGENT_DIR and ~. */
+export function getAgentDir(
+	env: NodeJS.ProcessEnv = process.env,
+	home: () => string = homedir,
+): string {
+	const envDir = env.PI_CODING_AGENT_DIR;
+	return envDir ? envDir.replace(/^~(\/|$)/, `${home()}$1`) : join(home(), ".pi", "agent");
+}
+
+/** Path to ~/.pi/agent/pstack/models.json. */
+export function configPath(
+	env: NodeJS.ProcessEnv = process.env,
+	home: () => string = homedir,
+): string {
+	return join(getAgentDir(env, home), "pstack", "models.json");
+}
+
+/** Path to leftover ~/.pi/agent/pstack-models.md. */
+export function legacyMarkdownPath(
+	env: NodeJS.ProcessEnv = process.env,
+	home: () => string = homedir,
+): string {
+	return join(getAgentDir(env, home), "pstack-models.md");
+}
+
+/** True when value is inherit-parent, auto, or a provider/id selector without dangerous segments. */
+export function isSafeModelSelector(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	if (INHERIT_SELECTORS.has(value)) return true;
+	if (!value || value.length > MAX_MODEL_KEY_LENGTH) return false;
+	for (const character of value) {
+		const codePoint = character.codePointAt(0);
+		if (character === "\\" || codePoint === undefined || codePoint <= 0x1f || codePoint === 0x7f)
+			return false;
+	}
+
+	const slash = value.indexOf("/");
+	if (slash <= 0 || slash === value.length - 1) return false;
+
+	const provider = value.slice(0, slash);
+	const id = value.slice(slash + 1);
+	if (!provider || !id) return false;
+
+	for (const part of value.split("/")) {
+		if (!part || DANGEROUS_KEY_PARTS.has(part)) return false;
+	}
+	return true;
+}

package/extensions/pstack/index.ts

@@ -0,0 +1,330 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { configPath, legacyMarkdownPath } from "./config.ts";
+import {
+	canPersistPstackSkillsToggle,
+	formatPstackStatus,
+	pstackSessionStartWarning,
+	pstackSetupSaveKind,
+} from "./pstack-config-status.ts";
+import type { PstackConfigReadResult, PstackConfigWriteResult } from "./pstack-role-config.ts";
+import {
+	backupPstackConfigThenSave,
+	loadPstackRoleConfig,
+	savePstackRoleConfig,
+	savePstackRoleConfigIfUnchanged,
+} from "./pstack-role-config-store.ts";
+import type { PstackRoleConfig } from "./pstack-roles.ts";
+import { systemPromptInjection } from "./pstack-role-prompt.ts";
+import {
+	buildPstackSetupPlan,
+	collectPstackSetupSelections,
+	pstackModelSelectorsFromSession,
+	type PstackScopedModelEntry,
+} from "./pstack-setup-plan.ts";
+import { registerAskUserQuestion } from "./ask-user-question.ts";
+import { stripSkillsByLocationPrefix } from "./skill-strip.ts";
+
+export { systemPromptInjection };
+
+const SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+
+const POTETO_SKILL = "/skill:poteto-mode";
+
+type ModeEntry = {
+	type?: string;
+	customType?: string;
+	data?: { enabled?: unknown };
+};
+
+function sessionEntries(ctx: ExtensionContext): ModeEntry[] {
+	const sm = ctx.sessionManager as {
+		getBranch?: () => ModeEntry[];
+		getEntries: () => ModeEntry[];
+	};
+	return typeof sm.getBranch === "function" ? sm.getBranch() : sm.getEntries();
+}
+
+function lastPotetoEnabled(entries: ModeEntry[]): boolean {
+	let enabled = false;
+	for (const entry of entries) {
+		if (entry.type === "custom" && entry.customType === "pstack-mode") {
+			enabled = Boolean(entry.data?.enabled);
+		}
+	}
+	return enabled;
+}
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error;
+}
+
+function readExactSourceBytes(
+	path: string,
+): { ok: true; bytes: string } | { ok: false; message?: string } {
+	try {
+		const st = lstatSync(path);
+		if (!st.isFile()) return { ok: false, message: `${path} is not a regular file.` };
+		return { ok: true, bytes: readFileSync(path, "utf8") };
+	} catch (error) {
+		if (isErrnoException(error) && error.code === "ENOENT") return { ok: false };
+		return { ok: false, message: `Failed to read ${path}.` };
+	}
+}
+
+function notifyWriteResult(ctx: ExtensionCommandContext, result: PstackConfigWriteResult): void {
+	if (result.ok) {
+		const backup = result.backupPath ? ` Backup: ${result.backupPath}.` : "";
+		ctx.ui.notify(`Wrote ${result.path}.${backup}`, "info");
+		return;
+	}
+	ctx.ui.notify(result.diagnostics.map((diagnostic) => diagnostic.message).join(" "), "error");
+}
+
+function commandScopedModels(
+	ctx: ExtensionCommandContext,
+): readonly PstackScopedModelEntry[] | undefined {
+	if (!("scopedModels" in ctx)) return undefined;
+	const value: unknown = Reflect.get(ctx, "scopedModels");
+	return Array.isArray(value) ? value : undefined;
+}
+
+function sourcePathFor(
+	result: PstackConfigReadResult,
+	jsonPath: string,
+	markdownPath: string,
+): string {
+	return result.source === "markdown" ? markdownPath : jsonPath;
+}
+
+async function persistSetupConfig(input: {
+	ctx: ExtensionCommandContext;
+	loaded: PstackConfigReadResult;
+	config: PstackRoleConfig;
+	jsonPath: string;
+	markdownPath: string;
+	originalBytes?: string;
+	originalReadError?: string;
+}): Promise<void> {
+	const kind = pstackSetupSaveKind(input.loaded);
+	if (kind === "confirm-replace") {
+		const confirmed = await input.ctx.ui.confirm(
+			"Replace pstack config?",
+			"Replace this pstack config? Current warnings and errors will be dropped. A backup is created when a source file exists.",
+		);
+		if (!confirmed) {
+			input.ctx.ui.notify("Setup cancelled. Nothing was written.", "info");
+			return;
+		}
+	}
+	if (kind === "backup-legacy" || kind === "confirm-replace") {
+		if (input.originalBytes === undefined) {
+			input.ctx.ui.notify(
+				input.originalReadError ?? "The source config disappeared. Nothing was written.",
+				"error",
+			);
+			return;
+		}
+		notifyWriteResult(
+			input.ctx,
+			backupPstackConfigThenSave({
+				originalBytes: input.originalBytes,
+				config: input.config,
+				path: input.jsonPath,
+				sourcePath: sourcePathFor(input.loaded, input.jsonPath, input.markdownPath),
+			}),
+		);
+		return;
+	}
+	if (kind === "atomic-v2" && input.originalBytes === undefined) {
+		input.ctx.ui.notify(
+			input.originalReadError ?? "The source config disappeared. Nothing was written.",
+			"error",
+		);
+		return;
+	}
+	notifyWriteResult(
+		input.ctx,
+		savePstackRoleConfigIfUnchanged({
+			config: input.config,
+			path: input.jsonPath,
+			originalBytes: kind === "atomic-v2" ? input.originalBytes : undefined,
+		}),
+	);
+}
+
+/** Register pstack commands, prompt injection, and session status with Pi. */
+export default function pstackExtension(pi: ExtensionAPI): void {
+	registerAskUserQuestion(pi);
+
+	let potetoMode = false;
+
+	function setStatus(ctx: ExtensionContext): void {
+		if (ctx.mode !== "tui") return;
+		ctx.ui.setStatus("pstack-mode", potetoMode ? "pstack: poteto mode" : undefined);
+	}
+
+	function persistMode(enabled: boolean, ctx?: ExtensionContext): void {
+		potetoMode = enabled;
+		pi.appendEntry("pstack-mode", { enabled });
+		if (ctx) setStatus(ctx);
+	}
+
+	pi.on("session_start", async (event, ctx) => {
+		void event;
+		potetoMode = false;
+		potetoMode = lastPotetoEnabled(sessionEntries(ctx));
+		setStatus(ctx);
+		const loaded = loadPstackRoleConfig();
+		if (ctx.mode !== "tui") return;
+		const warning = pstackSessionStartWarning(loaded);
+		if (warning) ctx.ui.notify(warning, "warning");
+	});
+
+	pi.on("input", async (event, ctx) => {
+		if (/^\/skill:poteto-mode(?:\s|$)/.test(event.text)) {
+			persistMode(true, ctx);
+		}
+		return { action: "continue" as const };
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		const loaded = loadPstackRoleConfig();
+		const base = loaded.config.skillsEnabled
+			? event.systemPrompt
+			: stripSkillsByLocationPrefix(event.systemPrompt, SKILLS_DIR).prompt;
+		const extra = systemPromptInjection(loaded.config, potetoMode);
+		return {
+			systemPrompt: extra ? `${base}\n\n${extra}` : base,
+		};
+	});
+
+	pi.registerCommand("poteto-mode", {
+		description:
+			"Enable or disable sticky pstack Poteto Mode. Usage: /poteto-mode [task] | /poteto-mode off",
+		getArgumentCompletions: (prefix) => {
+			const token = prefix.trim().toLowerCase();
+			if (!token || "off".startsWith(token)) {
+				return [{ value: "off", label: "off" }];
+			}
+			return null;
+		},
+		handler: async (args, ctx) => {
+			const raw = args.trim();
+			const token = raw.split(/\s+/)[0]?.toLowerCase() ?? "";
+			if (token === "off" || token === "disable" || token === "stop") {
+				persistMode(false, ctx);
+				ctx.ui.notify("Poteto Mode off.", "info");
+				return;
+			}
+			persistMode(true, ctx);
+			ctx.ui.notify("Poteto Mode on. Stays on until /poteto-mode off.", "info");
+			const payload = `${POTETO_SKILL}${raw ? ` ${raw}` : ""}`;
+			pi.sendUserMessage(
+				payload,
+				ctx.isIdle()
+					? { expandPromptTemplates: true }
+					: { expandPromptTemplates: true, deliverAs: "followUp" },
+			);
+		},
+	});
+
+	pi.registerCommand("setup-pstack", {
+		description: "Map pstack delegation roles to models available in this Pi session.",
+		handler: async (args, ctx) => {
+			void args;
+			if (!ctx.hasUI) {
+				ctx.ui.notify("pstack setup needs a UI. Nothing was written.", "error");
+				return;
+			}
+			const jsonPath = configPath();
+			const markdownPath = legacyMarkdownPath();
+			const loaded = loadPstackRoleConfig(jsonPath, markdownPath);
+			const sourcePath = sourcePathFor(loaded, jsonPath, markdownPath);
+			const original = loaded.source === "missing" ? undefined : readExactSourceBytes(sourcePath);
+			const plan = buildPstackSetupPlan({
+				config: loaded.config,
+				sessionSelectors: pstackModelSelectorsFromSession({
+					scopedModels: commandScopedModels(ctx),
+					availableModels: ctx.modelRegistry.getAvailable(),
+				}),
+			});
+			const next = await collectPstackSetupSelections({
+				config: loaded.config,
+				plan,
+				select: (title, options) => ctx.ui.select(title, options),
+			});
+			if (!next) {
+				ctx.ui.notify("Setup cancelled. Nothing was written.", "info");
+				return;
+			}
+			await persistSetupConfig({
+				ctx,
+				loaded,
+				config: next,
+				jsonPath,
+				markdownPath,
+				originalBytes: original?.ok === true ? original.bytes : undefined,
+				originalReadError: original && original.ok === false ? original.message : undefined,
+			});
+		},
+	});
+
+	pi.registerCommand("pstack", {
+		description:
+			"Show or toggle whether pstack skills are listed in the system prompt. Usage: /pstack [on|off|status]",
+		getArgumentCompletions: (prefix) => {
+			const token = prefix.trim().toLowerCase();
+			const options = ["on", "off", "status"].filter((value) => value.startsWith(token));
+			if (options.length === 0) return null;
+			return options.map((value) => ({ value, label: value }));
+		},
+		handler: async (args, ctx) => {
+			const token = args.trim().toLowerCase();
+			const jsonPath = configPath();
+			const loaded = loadPstackRoleConfig(jsonPath, legacyMarkdownPath());
+			if (token === "" || token === "status") {
+				ctx.ui.notify(formatPstackStatus(loaded), "info");
+				return;
+			}
+			const enabled = token === "on" || token === "enable";
+			if (!enabled && token !== "off" && token !== "disable") {
+				ctx.ui.notify("Usage: /pstack [on|off|status]", "error");
+				return;
+			}
+			if (!canPersistPstackSkillsToggle(loaded)) {
+				ctx.ui.notify(
+					"pstack config is not a clean v2 document. Run /setup-pstack to save changes.",
+					"error",
+				);
+				return;
+			}
+			if (enabled === loaded.config.skillsEnabled) {
+				ctx.ui.notify(
+					enabled
+						? "pstack skills on."
+						: "pstack skills off. Hidden from the model; /skill:<name> still works.",
+					"info",
+				);
+				return;
+			}
+			const saved = savePstackRoleConfig({ ...loaded.config, skillsEnabled: enabled }, jsonPath);
+			if (!saved.ok) {
+				notifyWriteResult(ctx, saved);
+				return;
+			}
+			ctx.ui.notify(
+				enabled
+					? "pstack skills on."
+					: "pstack skills off. Hidden from the model; /skill:<name> still works.",
+				"info",
+			);
+		},
+	});
+}