@lebronj/pi-suite 0.1.19 → 0.1.20

package/README.md

@@ -15,12 +15,12 @@ pi install npm:pi-web-access
 Or use the bootstrap script to install Pi, configure the team OpenAI-compatible endpoint, install this suite, and set up Bun + qmd for memory search:
 
 ```bash
-curl -fsSL https://registry.npmjs.org/@lebronj/pi-suite/-/pi-suite-0.1.17.tgz | tar -xzO package/scripts/bootstrap.sh | bash
+curl -fsSL https://registry.npmjs.org/@lebronj/pi-suite/-/pi-suite-0.1.20.tgz | tar -xzO package/scripts/bootstrap.sh | bash
 ```
 
 ## What Is Included
 
-- Local extensions: autogoal, goal mode, pet, prompt URL widget, snake, TPS notifications.
+- Local extensions: autogoal, goal mode, update_plan, pet, prompt URL widget, snake, TPS notifications.
 - Prompts: changelog audit, issue analysis, PR review, review workflow, commit workflow, wrap workflow.
 - Skills: provider checklist, Pi capability reference, image-to-editable-PPT workflow.
 - Vendored package: `@jhp/pi-memory`, including qmd search, external curator service, memory/skill-draft versioning, scoped Multica agent roots, review reminders, and local memory/skill self-evolution queues.
@@ -75,6 +75,17 @@ Behavior:
 - Subagents are optional and budgeted; worker subagents must use worktree isolation.
 - Run artifacts are written under `~/.pi/agent/workflow-runs/autogoal-<run-id>/`.
 
+## Update Plan
+
+The `update_plan` tool gives Pi a Codex-style visible execution checklist for non-trivial tasks. It supports `init`, `start`, `done`, `drop`, `rm`, `append`, and `note`, shows active plan progress in the UI, and injects guidance to use it for 3+ step tasks or user-provided checklists.
+
+Useful commands:
+
+```bash
+/plan-status
+/plan-clear
+```
+
 ## Team Model Setup
 
 The bootstrap script can be run with `curl | bash`: it reads the API key from the terminal instead of stdin. It asks for an API key and writes:

package/extensions/update-plan.ts

@@ -0,0 +1,364 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+type PlanStatus = "pending" | "in_progress" | "completed" | "abandoned";
+
+interface PlanItem {
+	content: string;
+	status: PlanStatus;
+	notes?: string[];
+}
+
+interface PlanPhase {
+	name: string;
+	items: PlanItem[];
+}
+
+interface PlanDetails {
+	op: string;
+	phases: PlanPhase[];
+	error?: string;
+}
+
+const PLAN_TOOL_NAME = "update_plan";
+const PLAN_STATE_TYPE = "update-plan-state";
+const WIDGET_KEY = "update-plan";
+
+const PlanOp = StringEnum(["list", "init", "start", "done", "drop", "rm", "append", "note"] as const);
+
+const PlanOperation = Type.Object({
+	op: PlanOp,
+	list: Type.Optional(
+		Type.Array(
+			Type.Object({
+				phase: Type.String({ description: "Phase name" }),
+				items: Type.Array(Type.String({ description: "Task content" }), { minItems: 1 }),
+			}),
+		),
+	),
+	task: Type.Optional(Type.String({ description: "Exact task content" })),
+	phase: Type.Optional(Type.String({ description: "Exact phase name" })),
+	items: Type.Optional(Type.Array(Type.String({ description: "Task content" }), { minItems: 1 })),
+	text: Type.Optional(Type.String({ description: "Note text" })),
+});
+
+const UpdatePlanParams = Type.Object({
+	ops: Type.Array(PlanOperation, { minItems: 1, description: "Ordered plan operations" }),
+});
+
+type PlanOperationInput = {
+	op: "list" | "init" | "start" | "done" | "drop" | "rm" | "append" | "note";
+	list?: Array<{ phase: string; items: string[] }>;
+	task?: string;
+	phase?: string;
+	items?: string[];
+	text?: string;
+};
+
+type UpdatePlanInput = { ops: PlanOperationInput[] };
+
+function cloneItem(item: PlanItem): PlanItem {
+	return {
+		content: item.content,
+		status: item.status,
+		...(item.notes && item.notes.length > 0 ? { notes: [...item.notes] } : {}),
+	};
+}
+
+function clonePhases(phases: PlanPhase[]): PlanPhase[] {
+	return phases.map((phase) => ({ name: phase.name, items: phase.items.map(cloneItem) }));
+}
+
+function countItems(phases: PlanPhase[]): { total: number; done: number; open: number } {
+	let total = 0;
+	let done = 0;
+	let open = 0;
+	for (const phase of phases) {
+		for (const item of phase.items) {
+			total++;
+			if (item.status === "completed") done++;
+			if (item.status === "pending" || item.status === "in_progress") open++;
+		}
+	}
+	return { total, done, open };
+}
+
+function normalizeOpenTask(phases: PlanPhase[]): void {
+	const items = phases.flatMap((phase) => phase.items);
+	const active = items.filter((item) => item.status === "in_progress");
+	for (const item of active.slice(1)) {
+		item.status = "pending";
+	}
+	if (active.length > 0) return;
+	const next = items.find((item) => item.status === "pending");
+	if (next) next.status = "in_progress";
+}
+
+function findPhase(phases: PlanPhase[], name: string | undefined): PlanPhase | undefined {
+	if (!name) return undefined;
+	return phases.find((phase) => phase.name === name);
+}
+
+function findTask(phases: PlanPhase[], content: string | undefined): { phase: PlanPhase; item: PlanItem } | undefined {
+	if (!content) return undefined;
+	for (const phase of phases) {
+		const item = phase.items.find((candidate) => candidate.content === content);
+		if (item) return { phase, item };
+	}
+	return undefined;
+}
+
+function renderTextPlan(phases: PlanPhase[]): string {
+	if (phases.length === 0) return "No active plan.";
+	const lines: string[] = [];
+	for (const phase of phases) {
+		lines.push(`${phase.name}:`);
+		for (const item of phase.items) {
+			const marker = item.status === "completed" ? "[x]" : item.status === "abandoned" ? "[-]" : item.status === "in_progress" ? "[>]" : "[ ]";
+			lines.push(`  ${marker} ${item.content}`);
+			if (item.status === "in_progress" && item.notes && item.notes.length > 0) {
+				for (const note of item.notes.slice(-2)) lines.push(`      note: ${note}`);
+			}
+		}
+	}
+	const counts = countItems(phases);
+	lines.push(``);
+	lines.push(`${counts.done}/${counts.total} completed, ${counts.open} open`);
+	return lines.join("\n");
+}
+
+function renderWidgetLines(ctx: ExtensionContext, phases: PlanPhase[]): string[] | undefined {
+	if (phases.length === 0) return undefined;
+	const th = ctx.ui.theme;
+	const counts = countItems(phases);
+	const lines: string[] = [th.fg("accent", `Plan ${counts.done}/${counts.total}`)];
+	let shown = 0;
+	let hidden = 0;
+	for (const phase of phases) {
+		const openItems = phase.items.filter((item) => item.status === "pending" || item.status === "in_progress");
+		if (openItems.length === 0) continue;
+		if (shown >= 6) {
+			hidden += openItems.length;
+			continue;
+		}
+		lines.push(th.fg("muted", phase.name));
+		for (const item of openItems) {
+			if (shown >= 6) {
+				hidden++;
+				continue;
+			}
+			const marker = item.status === "in_progress" ? th.fg("accent", "[>]") : th.fg("muted", "[ ]");
+			lines.push(`${marker} ${item.content}`);
+			shown++;
+		}
+	}
+	if (hidden > 0) lines.push(th.fg("dim", `... ${hidden} more`));
+	if (counts.open === 0) lines.push(th.fg("success", "All plan items are closed."));
+	return lines;
+}
+
+function updatePlanUi(ctx: ExtensionContext, phases: PlanPhase[]): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.setWidget(WIDGET_KEY, renderWidgetLines(ctx, phases));
+	const counts = countItems(phases);
+	ctx.ui.setStatus(WIDGET_KEY, counts.total > 0 ? ctx.ui.theme.fg("accent", `plan ${counts.done}/${counts.total}`) : undefined);
+}
+
+function applyOperation(phases: PlanPhase[], op: PlanOperationInput): string | undefined {
+	switch (op.op) {
+		case "list":
+			return undefined;
+		case "init": {
+			if (!op.list || op.list.length === 0) return "init requires list";
+			phases.splice(
+				0,
+				phases.length,
+				...op.list.map((phase) => ({
+					name: phase.phase,
+					items: phase.items.map((content, index) => ({ content, status: index === 0 && phases.length === 0 ? "in_progress" : "pending" as PlanStatus })),
+				})),
+			);
+			normalizeOpenTask(phases);
+			return undefined;
+		}
+		case "append": {
+			if (!op.phase) return "append requires phase";
+			if (!op.items || op.items.length === 0) return "append requires items";
+			let phase = findPhase(phases, op.phase);
+			if (!phase) {
+				phase = { name: op.phase, items: [] };
+				phases.push(phase);
+			}
+			phase.items.push(...op.items.map((content) => ({ content, status: "pending" as PlanStatus })));
+			normalizeOpenTask(phases);
+			return undefined;
+		}
+		case "start": {
+			const hit = findTask(phases, op.task);
+			if (!hit) return "start requires an existing task";
+			for (const phase of phases) {
+				for (const item of phase.items) {
+					if (item.status === "in_progress") item.status = "pending";
+				}
+			}
+			hit.item.status = "in_progress";
+			return undefined;
+		}
+		case "done":
+		case "drop": {
+			const status: PlanStatus = op.op === "done" ? "completed" : "abandoned";
+			if (op.task) {
+				const hit = findTask(phases, op.task);
+				if (!hit) return `${op.op} requires an existing task`;
+				hit.item.status = status;
+			} else if (op.phase) {
+				const phase = findPhase(phases, op.phase);
+				if (!phase) return `${op.op} requires an existing phase`;
+				for (const item of phase.items) item.status = status;
+			} else {
+				return `${op.op} requires task or phase`;
+			}
+			normalizeOpenTask(phases);
+			return undefined;
+		}
+		case "rm": {
+			if (!op.task && !op.phase) {
+				phases.splice(0, phases.length);
+				return undefined;
+			}
+			if (op.task) {
+				const hit = findTask(phases, op.task);
+				if (!hit) return "rm requires an existing task";
+				hit.phase.items = hit.phase.items.filter((item) => item !== hit.item);
+			} else if (op.phase) {
+				const index = phases.findIndex((phase) => phase.name === op.phase);
+				if (index < 0) return "rm requires an existing phase";
+				phases.splice(index, 1);
+			}
+			for (let i = phases.length - 1; i >= 0; i--) {
+				if (phases[i].items.length === 0) phases.splice(i, 1);
+			}
+			normalizeOpenTask(phases);
+			return undefined;
+		}
+		case "note": {
+			if (!op.text) return "note requires text";
+			const hit = findTask(phases, op.task);
+			if (!hit) return "note requires an existing task";
+			hit.item.notes = [...(hit.item.notes ?? []), op.text];
+			return undefined;
+		}
+	}
+}
+
+export default function updatePlanExtension(pi: ExtensionAPI): void {
+	let phases: PlanPhase[] = [];
+
+	function restoreFromEntries(ctx: ExtensionContext): void {
+		phases = [];
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "custom" && entry.customType === PLAN_STATE_TYPE) {
+				const data = entry.data as { phases?: PlanPhase[] } | undefined;
+				if (data?.phases) phases = clonePhases(data.phases);
+				continue;
+			}
+			if (entry.type !== "message") continue;
+			const message = entry.message as { role?: string; toolName?: string; details?: unknown; isError?: boolean };
+			if (message.role !== "toolResult" || message.toolName !== PLAN_TOOL_NAME || message.isError) continue;
+			const details = message.details as PlanDetails | undefined;
+			if (details?.phases) phases = clonePhases(details.phases);
+		}
+		updatePlanUi(ctx, phases);
+	}
+
+	pi.on("session_start", async (_event, ctx) => restoreFromEntries(ctx));
+	pi.on("session_tree", async (_event, ctx) => restoreFromEntries(ctx));
+
+	pi.on("before_agent_start", async () => {
+		if (!pi.getActiveTools().includes(PLAN_TOOL_NAME)) return;
+		return {
+			message: {
+				customType: "update-plan-guidance",
+				content: `<update_plan_guidance>\nFor non-trivial tasks with 3+ distinct steps, or when the user provides a checklist/plan, call update_plan before implementation. Keep exactly one open task in_progress, update it immediately after each completed step, and do not use update_plan for trivial one-step requests.\n</update_plan_guidance>`,
+				display: false,
+			},
+		};
+	});
+
+	pi.registerTool({
+		name: PLAN_TOOL_NAME,
+		label: "Update Plan",
+		description:
+			"Maintain a visible execution plan. Use for multi-step tasks: init the plan, mark exactly one task in_progress, and mark tasks done/drop as work proceeds.",
+		promptSnippet: "Maintain a visible execution plan for non-trivial multi-step tasks.",
+		promptGuidelines: [
+			"For tasks with 3+ distinct steps, or when the user provides a checklist, call update_plan with init before doing the work.",
+			"Keep exactly one open task in_progress; mark tasks done immediately after completing them.",
+			"Do not use update_plan for trivial single-step requests.",
+		],
+		parameters: UpdatePlanParams,
+		executionMode: "sequential",
+		async execute(_toolCallId, params: UpdatePlanInput, _signal, _onUpdate, ctx) {
+			let error: string | undefined;
+			for (const op of params.ops) {
+				error = applyOperation(phases, op);
+				if (error) break;
+			}
+			updatePlanUi(ctx, phases);
+			const lastOp = params.ops[params.ops.length - 1]?.op ?? "list";
+			const text = error ? `Error: ${error}` : renderTextPlan(phases);
+			return {
+				content: [{ type: "text", text }],
+				details: { op: lastOp, phases: clonePhases(phases), error } satisfies PlanDetails,
+				isError: error ? true : undefined,
+			};
+		},
+		renderCall(args: UpdatePlanInput, theme: Theme) {
+			const ops = args.ops?.map((op) => op.op).join("+") || "list";
+			return new Text(`${theme.fg("toolTitle", theme.bold("update_plan"))} ${theme.fg("muted", ops)}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme: Theme) {
+			const details = result.details as PlanDetails | undefined;
+			if (!details) {
+				const block = result.content?.find((item) => item.type === "text");
+				return new Text(block?.text ?? "", 0, 0);
+			}
+			if (details.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+			const snapshot = details.phases ?? [];
+			if (snapshot.length === 0) return new Text(theme.fg("dim", "No active plan"), 0, 0);
+			const counts = countItems(snapshot);
+			const lines = [theme.fg("accent", `Plan ${counts.done}/${counts.total}`)];
+			for (const phase of snapshot) {
+				lines.push(theme.fg("muted", phase.name));
+				const items = expanded ? phase.items : phase.items.slice(0, 5);
+				for (const item of items) {
+					const marker = item.status === "completed" ? theme.fg("success", "[x]") : item.status === "abandoned" ? theme.fg("dim", "[-]") : item.status === "in_progress" ? theme.fg("accent", "[>]") : theme.fg("muted", "[ ]");
+					const text = item.status === "completed" || item.status === "abandoned" ? theme.fg("dim", item.content) : item.content;
+					lines.push(`${marker} ${text}`);
+				}
+				if (!expanded && phase.items.length > items.length) lines.push(theme.fg("dim", `... ${phase.items.length - items.length} more`));
+			}
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+
+	pi.registerCommand("plan-status", {
+		description: "Show the current update_plan state",
+		handler: async (_args, ctx) => {
+			restoreFromEntries(ctx);
+			ctx.ui.notify(renderTextPlan(phases), "info");
+		},
+	});
+
+	pi.registerCommand("plan-clear", {
+		description: "Clear the current update_plan state",
+		handler: async (_args, ctx) => {
+			phases = [];
+			pi.appendEntry(PLAN_STATE_TYPE, { phases: [] });
+			updatePlanUi(ctx, phases);
+			ctx.ui.notify("Plan cleared.", "info");
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lebronj/pi-suite",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "JHP's Pi extension suite for team coding workflows",
   "type": "module",
   "keywords": [

package/skills/pi-skill/SKILL.md

@@ -88,10 +88,11 @@ Curator and learning behavior:
 - Expired temporary memories go to `REVIEW.md`, not automatic deletion.
 - Quotas reset when `month` or `reset` rolls over.
 - Mutations are audited to `audit/curator.jsonl`.
-- Session shutdown may extract conservative learning candidates into `REVIEW.md`; they are not injected as normal memory and are not auto-enabled.
+- Session shutdown may extract conservative learning candidates into `REVIEW.md`; `/new` and `/fork` also run a lightweight structured-evidence pass.
 - `memory_curate` scans yesterday's daily log once per content hash into review candidates, then curator lifecycle and proposal rules process those candidates.
-- Repeated candidates can become proposed memory promotions or proposed disabled skill drafts after `memory_curate`.
-- Approval is explicit by default: memory proposals write to memory stores; skill proposals write disabled drafts under the resolved skill draft root.
+- Repeated or high-confidence candidates can become proposed memory promotions or proposed disabled skill drafts after `memory_curate`.
+- Skill-worthy `failure -> edit/action -> validation success` patterns become high-confidence skill candidates from structured tool evidence.
+- Skill drafts default to `auto-draft`: high-quality proposals write disabled drafts under the resolved skill draft root, but memory proposals still require approval.
 - Draft and generated skills stay disabled until `memory_skill_enable` copies their full directories into `skills/enabled`; enabled skills are injected as `<available_skills>` metadata for the current agent.
 - Pi session start can show one pending-review hint; disable with `PI_MEMORY_REVIEW_STARTUP_HINT=0`.
 - Local multi-agent self-evolution supports one Local Curator Manager registry/dirty-root API for many agent roots, plus a manager service that runs `manager-scan` every 6 hours and exits quickly when no root is dirty.
@@ -143,12 +144,16 @@ Useful memory environment variables:
 - `PI_MEMORY_NO_SEARCH=1`: disable per-turn search injection.
 - `PI_MEMORY_SUMMARIZE_TRANSITIONS=1`: also summarize lifecycle transitions such as `/reload`.
 - `PI_MEMORY_LEARNING`: `off`, `review`, or `auto-review`.
-- `PI_MEMORY_SKILL_DRAFTS`: `off` or `review`.
+- `PI_MEMORY_SKILL_DRAFTS`: `off`, `propose`/`review`, or `auto-draft` (default).
+- `PI_MEMORY_SKILL_SEEN_THRESHOLD`: repeated medium-confidence skill candidate threshold; default `2`.
 - `PI_MEMORY_AUTO_APPROVE_MEMORY=1`: automatically approve newly created memory proposals.
 - `PI_MEMORY_AUTO_APPROVE_SKILL_DRAFTS=1`: automatically create newly proposed disabled skill drafts.
 - `PI_MEMORY_CURATOR_STARTUP_HINT=0`: hide the disabled-curator startup hint.
 - `PI_MEMORY_REVIEW_STARTUP_HINT=0`: hide pending review proposal startup hints.
 - `PI_MEMORY_REMOTE_URL` and `PI_MEMORY_REMOTE_TOKEN`: enable Multica candidate/profile/feedback upload and current-agent delivery pull.
+- Local CLI Pi can bind to Multica by setting `MULTICA_WORKSPACE_ID`, `MULTICA_AGENT_ID`, `PI_MEMORY_REMOTE_URL`, and `PI_MEMORY_REMOTE_TOKEN`; it then uses the same agent root/sync loop as a Multica-wrapped Pi agent.
+- `PI_MEMORY_AUTO_SYNC=1`: best-effort automatic pull on session start and upload on session shutdown; narrower aliases are `PI_MEMORY_AUTO_SYNC_PULL_ON_START=1`, `PI_MEMORY_AUTO_SYNC_PULL=1`, `PI_MEMORY_AUTO_SYNC_UPLOAD_ON_SHUTDOWN=1`, and `PI_MEMORY_AUTO_SYNC_UPLOAD=1`.
+- `PI_MEMORY_AUTO_SYNC_PULL_LIMIT`: maximum automatic delivery pull count; default `20`.
 - `PI_EVOLUTION_ENABLED=0`: disable snapshot + git versioning.
 - `PI_EVOLUTION_DIR`: override evolution repo directory; default `~/.pi/agent/evolution`.
 - `PI_EVOLUTION_REMOTE`: optional personal private Git remote; unset by default.
@@ -221,6 +226,16 @@ Goal mode is provided by `goal-mode.ts`.
 - The agent must verify current files/checks before calling `goal({ op: "complete" })`.
 - Useful commands: `/goal show`, `/goal pause`, `/goal resume`, `/goal drop`, `/goal budget <tokens|off>`, `/goal auto on`, `/goal auto off`.
 
+## Update Plan
+
+`update-plan.ts` provides a lightweight Codex-style execution checklist without changing Pi core.
+
+- Tool: `update_plan`.
+- Use it for non-trivial tasks with 3+ distinct steps, user-provided checklists, or explicit plan/progress tracking requests.
+- Operations: `list`, `init`, `start`, `done`, `drop`, `rm`, `append`, and `note`.
+- It keeps phased task state in session history, auto-promotes the next pending task to `in_progress`, and shows widget/footer progress when active.
+- Commands: `/plan-status` shows the current plan; `/plan-clear` clears it.
+
 ## Pet Companion
 
 The pet extension provides a small terminal companion and durable profile.
@@ -233,6 +248,7 @@ The pet extension provides a small terminal companion and durable profile.
 
 ## UI And Utility Extensions
 
+- `update-plan.ts`: registers `update_plan`, `/plan-status`, and `/plan-clear` for visible per-session execution planning.
 - `prompt-url-widget.ts`: detects PR/issue prompt templates, fetches GitHub metadata with `gh`, shows a widget, and names the session when possible.
 - `snake.ts`: `/snake` opens a TUI snake game; `Esc` pauses/saves, `q` quits, arrows/WASD move.
 - `tps.ts`: after each assistant run, shows tokens-per-second and token usage details.