@lebronj/pi-suite 0.1.18 → 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.18",
+  "version": "0.1.20",
   "description": "JHP's Pi extension suite for team coding workflows",
   "type": "module",
   "keywords": [

package/skills/pi-skill/SKILL.md

@@ -40,8 +40,9 @@ Memory files include:
 - `.curator-state.json`: last curator run state.
 - `.curator-service.json`: external curator service state.
 - `audit/curator.jsonl`: curator audit trail.
-- Resolved skill draft root `<slug>/SKILL.md`: disabled skill drafts created after explicit approval.
+- Resolved skill draft root `<slug>/SKILL.md`: disabled skill drafts created after explicit approval; skill directories may include supporting files alongside `SKILL.md`.
 - Multica agent roots also contain `inbox/`, `shared-cache/`, `skills/generated/`, `profile/`, `feedback/feedback.jsonl`, and `sync_queue/`.
+- Skill share candidates are runnable bundles: `sync_queue/skill-candidates.jsonl` is the queue/manifest, while `sync_queue/skill-candidates/<local_unit_id>/` contains `SKILL.md` plus supporting files.
 
 Memory tools:
 
@@ -55,7 +56,7 @@ Memory tools:
 - `memory_learning_reject`: reject or archive a review candidate/proposal without deleting it.
 - `memory_skill_drafts`: list proposed skill drafts.
 - `memory_skill_list`: list current-agent draft, generated, and enabled memory-managed skills.
-- `memory_skill_enable`: explicitly enable a `draft:<slug>` or `generated:<id>` skill by copying it into `skills/enabled/<skill-name>/` and auditing the action.
+- `memory_skill_enable`: explicitly enable a `draft:<slug>` or `generated:<id>` skill by copying the full skill directory into `skills/enabled/<skill-name>/` and auditing the action.
 - `memory_skill_disable`: remove an enabled skill copy while preserving its draft/generated source.
 - `/memory-skill`: slash command to list/enable/disable current-agent memory-managed skills.
 - `/memory-review`: slash command to list/show/approve/reject/archive pending memory and skill proposals in the current resolved root.
@@ -87,14 +88,16 @@ 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.
-- Draft and generated skills stay disabled until `memory_skill_enable` copies them into `skills/enabled`; enabled skills are injected as `<available_skills>` metadata for the current agent.
+- 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.
 - The local loop also covers share candidate queue, profile generation, sync upload/pull, downflow receive cache, generated skills, enabled skill lifecycle, and feedback JSONL helpers.
+- Skill upload/downflow follows Multica's runnable bundle shape: `content` is `SKILL.md`, `files` are supporting files, and `content_hash` covers both.
 - Server downflow is per-Agent delivery, not broadcast; local receive writes only `inbox/`, `shared-cache/`, or `skills/generated/` and never overwrites formal memory or auto-enables skills.
 - The curator avoids semantic auto-delete/merge; ambiguous learning stays in review first.
 
@@ -141,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.
@@ -219,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.
@@ -231,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.

package/vendor/pi-memory/README.md

@@ -59,6 +59,8 @@ The extension auto-creates the `pi-memory` qmd collection and path contexts on s
   profile/user-profile.md agent-profile.md task-profile.md capability-profile.md
   feedback/feedback.jsonl
   sync_queue/memory-candidates.jsonl skill-candidates.jsonl
+  sync_queue/skill-candidates/<local_unit_id>/SKILL.md   # Runnable upload bundle
+  sync_queue/skill-candidates/<local_unit_id>/**         # Supporting files
 ```
 
 Structured entries are separated by `§` and may start with metadata:
@@ -190,7 +192,7 @@ Approval is explicit by default:
 - `memory_learning_approve` on a memory proposal writes `MEMORY.md`, `USER.md`, or `STATE.md` depending on the proposal target.
 - `memory_learning_approve` on a skill proposal writes the current resolved skill draft root and marks the proposal approved.
 - Skill drafts are disabled. They are not moved into enabled skill directories automatically.
-- `memory_skill_enable` explicitly copies a `draft:<slug>` or `generated:<id>` skill into `skills/enabled/<skill-name>/` and writes `memory/audit/skill-lifecycle.jsonl`.
+- `memory_skill_enable` explicitly copies a full `draft:<slug>` or `generated:<id>` skill directory into `skills/enabled/<skill-name>/` and writes `memory/audit/skill-lifecycle.jsonl`.
 - `memory_skill_disable` removes only the enabled copy; the draft/generated source remains for later review.
 - Enabled skills are injected as available-skill metadata so the agent can read the corresponding `SKILL.md` when the task matches.
 - `memory_learning_reject` marks a candidate or proposal as `rejected` or `archived` without deleting it.
@@ -214,11 +216,11 @@ The package includes local primitives for the full local loop:
 
 - `ensureAgentRoot()` initializes the scoped directory tree.
 - `markCurrentRootDirty()` and `scanDirtyRoots()` implement a single Local Curator Manager registry, manager-level locking, stale lock cleanup, and per-root `.curator.lock` processing.
-- `generateShareCandidatesFromReview()` and `appendEvolutionCandidate()` write governed share candidates to `sync_queue/` and block secret-like payloads.
+- `generateShareCandidatesFromReview()` and `appendEvolutionCandidate()` write governed share candidates to `sync_queue/` and block secret-like payloads. Skill candidates follow Multica's runnable bundle shape: JSONL contains queue metadata plus `content` as `SKILL.md` and `files` as supporting files, while `sync_queue/skill-candidates/<local_unit_id>/` stores the same runnable directory for inspection/upload.
 - `generateProfiles()` writes conservative local profiles for remote matching input.
 - `syncUpload()` / `memory_sync_upload` POST candidates, profiles, and feedback, using a checkpoint to avoid re-uploading prior candidate ids or feedback lines.
 - `syncPull()` / `memory_sync_pull` pull only current-agent deliveries and call `receiveDelivery()`.
-- `receiveDelivery()` writes server downflow only to `inbox/`, `shared-cache/`, or `skills/generated/`; it never overwrites formal memory or enables skills.
+- `receiveDelivery()` writes server downflow only to `inbox/`, `shared-cache/`, or `skills/generated/`; skill deliveries restore `SKILL.md` plus supporting `files`, but never overwrite formal memory or enable skills.
 - `appendFeedbackEvent()` / `memory_feedback` writes injected/used/ignored/success/failure/conflict events to `feedback/feedback.jsonl` for connector upload.
 
 Server delivery is per-agent matching, not broadcast. The local runtime must only pull deliveries for the current `MULTICA_AGENT_ID` and still filter before injection.

package/vendor/pi-memory/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jhp/pi-memory",
-	"version": "0.3.13",
+	"version": "0.3.14",
 	"description": "Pi coding agent extension for structured time-aware memory with qmd-powered search and curator support",
 	"main": "index.ts",
 	"bin": {

package/vendor/pi-memory/src/governance/share-candidates.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { parseEntry } from "../curator-core/metadata.ts";
 import type { MemoryStore } from "../curator-store/types.ts";
 import type { PiAgentEnv } from "../paths/resolve-roots.ts";
@@ -23,9 +25,17 @@ export async function generateShareCandidatesFromReview(memoryStore: MemoryStore
 		}
 		try {
 			const type = parsed.metadata.kind === "skill_promotion" || parsed.metadata.target_hints?.includes("skill") ? "skill" : "memory";
+			const sourcePath = type === "skill" ? sourceSkillDir(parsed.metadata.promotes_to) : undefined;
+			if (type === "skill" && !sourcePath) {
+				result.skipped += 1;
+				continue;
+			}
 			const appended = appendEvolutionCandidate({
 				type,
 				content,
+				name: parsed.metadata.name,
+				description: parsed.metadata.description,
+				source_path: sourcePath,
 				tags: tagsFromEntry(parsed.metadata.tags || parsed.metadata.kind || "memory"),
 				source: "local_curator",
 				suggested_scope: suggestedScope(parsed.metadata.scope),
@@ -66,6 +76,12 @@ function tagsFromEntry(value: string): string[] {
 	return value.split(/[ ,#]+/).map((tag) => tag.trim()).filter(Boolean).slice(0, 8);
 }
 
+function sourceSkillDir(promotesTo: string | undefined): string | undefined {
+	if (!promotesTo || !promotesTo.replace(/\\/g, "/").endsWith("/SKILL.md")) return undefined;
+	const dir = dirname(promotesTo);
+	return existsSync(join(dir, "SKILL.md")) ? dir : undefined;
+}
+
 function suggestedScope(value: string | undefined): "agent" | "workspace" | "project" | "team" | "global" | "agent_type" {
 	if (value === "workspace" || value === "project" || value === "team" || value === "global") return value;
 	return "workspace";

package/vendor/pi-memory/src/skills/lifecycle.ts

@@ -61,7 +61,7 @@ export function enableMemorySkill(input: string, options: { force?: boolean; env
 	if (existsSync(targetPath) && !options.force) throw new Error(`enabled skill '${source.name}' already exists; pass force to replace it`);
 	if (existsSync(targetDir)) rmSync(targetDir, { recursive: true, force: true });
 	mkdirSync(targetDir, { recursive: true });
-	writeFileSync(targetPath, readFileSync(source.path, "utf-8"), "utf-8");
+	copySkillDirectory(dirname(source.path), targetDir);
 	const manifest = {
 		name: source.name,
 		description: source.description,
@@ -166,6 +166,22 @@ function readSkillItem(skillPath: string, kind: SkillLifecycleKind, id = basenam
 	};
 }
 
+function copySkillDirectory(sourceDir: string, targetDir: string): void {
+	for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+		if (entry.isSymbolicLink() || entry.name === ENABLED_MANIFEST) continue;
+		const sourcePath = join(sourceDir, entry.name);
+		const targetPath = join(targetDir, entry.name);
+		if (entry.isDirectory()) {
+			mkdirSync(targetPath, { recursive: true });
+			copySkillDirectory(sourcePath, targetPath);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		mkdirSync(dirname(targetPath), { recursive: true });
+		writeFileSync(targetPath, readFileSync(sourcePath));
+	}
+}
+
 function parseSkillFrontmatter(content: string): SkillFrontmatter | null {
 	if (!content.startsWith("---\n")) return null;
 	const end = content.indexOf("\n---", 4);

package/vendor/pi-memory/src/sync/downflow.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { resolveAgentRoots, type PiAgentEnv } from "../paths/resolve-roots.ts";
 import { detectSensitivity } from "./sensitivity.ts";
 import type { Delivery } from "./schemas.ts";
+import { validateSkillBundleFiles, writeSkillBundle } from "./skill-bundle.ts";
 
 export type ReceiveDeliveryResult = {
 	written: string[];
@@ -29,10 +30,10 @@ export function receiveDelivery(delivery: Delivery, env: PiAgentEnv = process.en
 	mkdirSync(inboxDir, { recursive: true });
 	mkdirSync(generatedDir, { recursive: true });
 	const skillContent = delivery.content.endsWith("\n") ? delivery.content : `${delivery.content}\n`;
-	writeTextIfChanged(join(inboxDir, "SKILL.md"), skillContent);
-	writeTextIfChanged(join(generatedDir, "SKILL.md"), skillContent);
+	const files = validateSkillBundleFiles(delivery.files || []);
+	written.push(...writeSkillBundle(inboxDir, skillContent, files));
+	written.push(...writeSkillBundle(generatedDir, skillContent, files));
 	writeJsonIfChanged(join(inboxDir, "delivery.json"), delivery);
-	written.push(join(inboxDir, "SKILL.md"), join(generatedDir, "SKILL.md"));
 	return { written, accepted: true };
 }
 

package/vendor/pi-memory/src/sync/queue.ts

@@ -1,9 +1,10 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
 import { createHash } from "node:crypto";
 import { resolveAgentRoots, type PiAgentEnv } from "../paths/resolve-roots.ts";
 import { detectSensitivity, redactLocalPaths } from "./sensitivity.ts";
 import type { EvolutionCandidate } from "./schemas.ts";
+import { hashSkillBundle, loadSkillBundle, writeSkillBundle } from "./skill-bundle.ts";
 
 export function appendEvolutionCandidate(input: Omit<EvolutionCandidate, "workspace_id" | "agent_id" | "local_unit_id" | "signature" | "created_at"> & Partial<Pick<EvolutionCandidate, "workspace_id" | "agent_id" | "local_unit_id" | "signature" | "created_at">>, env: PiAgentEnv = process.env): { path: string; candidate: EvolutionCandidate; appended: boolean } {
 	const roots = resolveAgentRoots(env);
@@ -11,30 +12,56 @@ export function appendEvolutionCandidate(input: Omit<EvolutionCandidate, "worksp
 	const workspaceId = input.workspace_id || roots.workspaceId;
 	const agentId = input.agent_id || roots.agentId;
 	if (!workspaceId || !agentId) throw new Error("candidate requires workspace_id and agent_id");
-	const sensitivity = input.sensitivity || detectSensitivity(input.content);
+
+	const skillBundle = input.type === "skill" && input.source_path ? loadSkillBundle(input.source_path) : null;
+	const rawContent = skillBundle?.content ?? input.content;
+	const allSkillContent = skillBundle ? [skillBundle.content, ...skillBundle.files.map((file) => file.content)].join("\n") : rawContent;
+	const sensitivity = input.sensitivity || detectSensitivity(allSkillContent);
 	if (sensitivity === "secret") throw new Error("secret-like content cannot enter sync_queue");
-	const content = sensitivity === "local_path" ? redactLocalPaths(input.content) : input.content;
-	const signature = input.signature || stableHash([input.type, content, input.tags.join(",")].join("\n"));
+	const content = sensitivity === "local_path" ? redactLocalPaths(rawContent) : rawContent;
+	const files = sensitivity === "local_path"
+		? skillBundle?.files.map((file) => ({ ...file, content: redactLocalPaths(file.content) }))
+		: skillBundle?.files;
+	const signature = input.signature || stableHash([input.type, content, files?.map((file) => `${file.path}\0${file.content}`).join("\0") || "", input.tags.join(",")].join("\n"));
+	const localUnitId = input.local_unit_id || `${input.type}_${signature.slice(0, 12)}`;
 	const candidate: EvolutionCandidate = {
 		...input,
 		workspace_id: workspaceId,
 		agent_id: agentId,
-		local_unit_id: input.local_unit_id || `${input.type}_${signature.slice(0, 12)}`,
+		local_unit_id: localUnitId,
 		signature,
 		content,
 		sensitivity,
 		created_at: input.created_at || new Date().toISOString(),
 	};
+	if (skillBundle) {
+		const bundleDir = join(roots.syncQueueDir, "skill-candidates", localUnitId);
+		const written = writeSkillBundle(bundleDir, content, files || []);
+		candidate.name = skillBundle.name;
+		candidate.description = skillBundle.description;
+		candidate.provider = skillBundle.provider;
+		candidate.content_hash = hashSkillBundle(content, files || []);
+		candidate.files = files || [];
+		candidate.bundle_path = relative(roots.syncQueueDir, bundleDir).replace(/\\/g, "/");
+		candidate.source_path = candidate.bundle_path;
+		writeCandidateManifest(join(bundleDir, "candidate.json"), candidate);
+		if (written.length === 0) throw new Error("skill bundle was not written");
+	}
 	const filePath = join(roots.syncQueueDir, input.type === "skill" ? "skill-candidates.jsonl" : "memory-candidates.jsonl");
 	mkdirSync(roots.syncQueueDir, { recursive: true });
 	if (existsSync(filePath)) {
-		const exists = readFileSync(filePath, "utf-8").split("\n").some((line) => line.includes(`\"local_unit_id\":\"${candidate.local_unit_id}\"`));
+		const exists = readFileSync(filePath, "utf-8").split("\n").some((line: string) => line.includes(`\"local_unit_id\":\"${candidate.local_unit_id}\"`));
 		if (exists) return { path: filePath, candidate, appended: false };
 	}
 	appendFileSync(filePath, `${JSON.stringify(candidate)}\n`, "utf-8");
 	return { path: filePath, candidate, appended: true };
 }
 
+function writeCandidateManifest(filePath: string, candidate: EvolutionCandidate): void {
+	mkdirSync(dirname(filePath), { recursive: true });
+	writeFileSync(filePath, `${JSON.stringify(candidate, null, 2)}\n`, "utf-8");
+}
+
 function stableHash(value: string): string {
 	return createHash("sha256").update(value).digest("hex");
 }

package/vendor/pi-memory/src/sync/schemas.ts

@@ -1,6 +1,11 @@
 export type EvolutionUnitType = "memory" | "skill" | "workflow" | "tool_pattern" | "preference";
 export type FeedbackEventType = "injected" | "used" | "ignored" | "success" | "failure" | "conflict";
 
+export type SkillFileData = {
+	path: string;
+	content: string;
+};
+
 export type EvolutionCandidate = {
 	type: EvolutionUnitType;
 	workspace_id: string;
@@ -15,6 +20,13 @@ export type EvolutionCandidate = {
 	sensitivity?: "none" | "local_path" | "personal" | "secret" | "unknown";
 	source_candidate_ids?: string[];
 	created_at: string;
+	name?: string;
+	description?: string;
+	source_path?: string;
+	provider?: "pi";
+	content_hash?: string;
+	files?: SkillFileData[];
+	bundle_path?: string;
 };
 
 export type FeedbackEvent = {
@@ -34,6 +46,12 @@ export type Delivery = {
 	shared_unit_id: string;
 	unit_type: "memory" | "skill";
 	content: string;
+	name?: string;
+	description?: string;
+	files?: SkillFileData[];
+	source_path?: string;
+	provider?: "pi";
+	content_hash?: string;
 	tags?: string[];
 	score?: number;
 	task_types?: string[];

package/vendor/pi-memory/src/sync/skill-bundle.ts

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+export type SkillBundleFile = {
+	path: string;
+	content: string;
+};
+
+export type SkillBundle = {
+	name: string;
+	description: string;
+	content: string;
+	source_path: string;
+	provider: "pi";
+	content_hash: string;
+	files: SkillBundleFile[];
+};
+
+const MAX_SKILL_FILE_SIZE = 1 << 20;
+const MAX_SKILL_BUNDLE_SIZE = 8 << 20;
+const MAX_SKILL_FILE_COUNT = 128;
+
+export function loadSkillBundle(skillDir: string): SkillBundle {
+	const resolvedDir = resolve(skillDir);
+	const skillPath = join(resolvedDir, "SKILL.md");
+	if (!existsSync(skillPath)) throw new Error(`skill bundle requires SKILL.md: ${skillPath}`);
+	const content = readBoundedFile(skillPath);
+	const frontmatter = parseSkillFrontmatter(content);
+	if (!frontmatter.name) throw new Error(`skill SKILL.md must include frontmatter name: ${skillPath}`);
+	const files = collectSkillSupportingFiles(resolvedDir);
+	return {
+		name: frontmatter.name,
+		description: frontmatter.description || "",
+		content,
+		source_path: resolvedDir,
+		provider: "pi",
+		content_hash: hashSkillBundle(content, files),
+		files,
+	};
+}
+
+export function writeSkillBundle(skillDir: string, content: string, files: SkillBundleFile[] = []): string[] {
+	const resolvedDir = resolve(skillDir);
+	const written: string[] = [];
+	const mainPath = join(resolvedDir, "SKILL.md");
+	writeTextIfChanged(mainPath, content.endsWith("\n") ? content : `${content}\n`);
+	written.push(mainPath);
+	for (const file of validateSkillBundleFiles(files)) {
+		const target = join(resolvedDir, file.path);
+		writeTextIfChanged(target, file.content);
+		written.push(target);
+	}
+	return written;
+}
+
+export function validateSkillBundleFiles(files: SkillBundleFile[] = []): SkillBundleFile[] {
+	const valid: SkillBundleFile[] = [];
+	for (const file of files) {
+		const clean = normalizeSkillFilePath(file.path);
+		if (!clean) continue;
+		valid.push({ path: clean, content: String(file.content ?? "") });
+	}
+	return valid.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function hashSkillBundle(content: string, files: SkillBundleFile[]): string {
+	const h = createHash("sha256");
+	h.update(content);
+	for (const file of validateSkillBundleFiles(files)) {
+		h.update(`\0${file.path}\0${file.content}`);
+	}
+	return `sha256:${h.digest("hex")}`;
+}
+
+function collectSkillSupportingFiles(skillDir: string): SkillBundleFile[] {
+	const files: SkillBundleFile[] = [];
+	let totalSize = 0;
+	function walk(dir: string): void {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.isSymbolicLink()) continue;
+			if (isIgnoredSkillEntry(entry.name)) continue;
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				walk(fullPath);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			const rel = normalizeSkillFilePath(relative(skillDir, fullPath));
+			if (!rel) continue;
+			const info = statSync(fullPath);
+			if (info.size > MAX_SKILL_FILE_SIZE) continue;
+			if (files.length >= MAX_SKILL_FILE_COUNT) throw new Error(`local skill exceeds ${MAX_SKILL_FILE_COUNT} files`);
+			totalSize += info.size;
+			if (totalSize > MAX_SKILL_BUNDLE_SIZE) throw new Error(`local skill exceeds ${MAX_SKILL_BUNDLE_SIZE} bytes in total`);
+			files.push({ path: rel, content: readFileSync(fullPath, "utf-8") });
+		}
+	}
+	walk(skillDir);
+	return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function readBoundedFile(filePath: string): string {
+	const info = statSync(filePath);
+	if (info.size > MAX_SKILL_FILE_SIZE) throw new Error(`SKILL.md exceeds ${MAX_SKILL_FILE_SIZE} bytes`);
+	return readFileSync(filePath, "utf-8");
+}
+
+function normalizeSkillFilePath(path: string): string | null {
+	const normalized = path.replace(/\\/g, "/").split("/").filter(Boolean).join("/");
+	if (!normalized || normalized === "." || normalized.startsWith("../") || normalized.includes("/../")) return null;
+	if (normalized.startsWith("/") || normalized.startsWith("~")) return null;
+	if (normalized.toLowerCase() === "skill.md") return null;
+	return normalized;
+}
+
+function isIgnoredSkillEntry(name: string): boolean {
+	if (!name || name.startsWith(".")) return true;
+	switch (name.toLowerCase()) {
+		case "skill.md":
+		case "license":
+		case "license.md":
+		case "license.txt":
+			return true;
+		default:
+			return false;
+	}
+}
+
+function parseSkillFrontmatter(content: string): { name: string; description: string } {
+	if (!content.startsWith("---\n")) return { name: "", description: "" };
+	const end = content.indexOf("\n---", 4);
+	if (end < 0) return { name: "", description: "" };
+	const result: { name: string; description: string } = { name: "", description: "" };
+	for (const line of content.slice(4, end).split("\n")) {
+		const index = line.indexOf(":");
+		if (index < 0) continue;
+		const key = line.slice(0, index).trim();
+		const value = line.slice(index + 1).trim().replace(/^["']|["']$/g, "");
+		if (key === "name") result.name = value;
+		if (key === "description") result.description = value;
+	}
+	return result;
+}
+
+function writeTextIfChanged(filePath: string, value: string): void {
+	mkdirSync(dirname(filePath), { recursive: true });
+	if (existsSync(filePath)) return;
+	writeFileSync(filePath, value, "utf-8");
+}

package/vendor/pi-memory/test/skill-lifecycle.test.ts

@@ -34,6 +34,8 @@ test("enables and disables a draft skill without deleting the draft", () => {
 	const { agentRoot, env } = agentEnv();
 	const draftDir = join(agentRoot, "skills", "drafts", "draft-one");
 	writeSkill(join(draftDir, "SKILL.md"), "draft-one");
+	mkdirSync(join(draftDir, "templates"), { recursive: true });
+	writeFileSync(join(draftDir, "templates", "prompt.md"), "supporting file\n", "utf-8");
 
 	let skills = listMemorySkills(env);
 	assert.equal(skills.drafts.length, 1);
@@ -42,6 +44,7 @@ test("enables and disables a draft skill without deleting the draft", () => {
 	const enabled = enableMemorySkill("draft:draft-one", { env });
 	assert.equal(enabled.enabled.name, "draft-one");
 	assert.equal(existsSync(join(agentRoot, "skills", "enabled", "draft-one", "SKILL.md")), true);
+	assert.equal(existsSync(join(agentRoot, "skills", "enabled", "draft-one", "templates", "prompt.md")), true);
 	assert.equal(existsSync(join(agentRoot, "skills", "drafts", "draft-one", "SKILL.md")), true);
 	assert.match(readFileSync(join(agentRoot, "memory", "audit", "skill-lifecycle.jsonl"), "utf-8"), /"action":"enable"/);
 
@@ -64,11 +67,13 @@ test("enables a generated skill delivery by generated id", () => {
 		shared_unit_id: "unit_skill_1",
 		unit_type: "skill",
 		content: "---\nname: shared-demo\ndescription: Use for tests.\n---\n# Shared Demo\n",
+		files: [{ path: "templates/prompt.md", content: "shared supporting file\n" }],
 	}, env);
 
 	const enabled = enableMemorySkill("generated:unit_skill_1", { env });
 	assert.equal(enabled.source.kind, "generated");
 	assert.equal(enabled.enabled.name, "shared-demo");
+	assert.equal(existsSync(join(agentRoot, "skills", "enabled", "shared-demo", "templates", "prompt.md")), true);
 	assert.equal(existsSync(join(agentRoot, "skills", "enabled", "shared-demo", ".pi-skill-enabled.json")), true);
 	const manifest = readFileSync(join(agentRoot, "skills", "enabled", "shared-demo", ".pi-skill-enabled.json"), "utf-8");
 	assert.match(manifest, /generated:unit_skill_1/);

package/vendor/pi-memory/test/sync-local-loop.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
@@ -48,6 +48,33 @@ test("sync queue writes share candidates and blocks secret-like payloads", () =>
 	}, env), /secret-like content/);
 });
 
+test("skill candidates upload a runnable bundle with supporting files", () => {
+	const { agentRoot, env } = agentEnv();
+	const skillDir = join(agentRoot, "skills", "drafts", "bundle-demo");
+	mkdirSync(join(skillDir, "scripts"), { recursive: true });
+	writeFileSync(join(skillDir, "SKILL.md"), "---\nname: bundle-demo\ndescription: Use bundle demo.\n---\n# Bundle Demo\n", "utf-8");
+	writeFileSync(join(skillDir, "scripts", "run.sh"), "echo bundle\n", "utf-8");
+
+	const result = appendEvolutionCandidate({
+		type: "skill",
+		content: "fallback should be replaced by SKILL.md",
+		source_path: skillDir,
+		tags: ["coding"],
+		source: "local_curator",
+		suggested_scope: "agent_type",
+		status: "candidate",
+	}, env);
+
+	assert.equal(result.appended, true);
+	assert.equal(result.candidate.name, "bundle-demo");
+	assert.equal(result.candidate.files?.[0]?.path, "scripts/run.sh");
+	assert.match(result.candidate.content, /# Bundle Demo/);
+	assert.equal(existsSync(join(agentRoot, "sync_queue", "skill-candidates", result.candidate.local_unit_id, "SKILL.md")), true);
+	assert.equal(existsSync(join(agentRoot, "sync_queue", "skill-candidates", result.candidate.local_unit_id, "scripts", "run.sh")), true);
+	const queue = readFileSync(join(agentRoot, "sync_queue", "skill-candidates.jsonl"), "utf-8");
+	assert.match(queue, /"files":\[\{"path":"scripts\/run.sh"/);
+});
+
 test("downflow receive writes only inbox/cache/generated locations", () => {
 	const { agentRoot, env } = agentEnv();
 	const memoryResult = receiveDelivery({
@@ -67,10 +94,13 @@ test("downflow receive writes only inbox/cache/generated locations", () => {
 		shared_unit_id: "unit_skill_1",
 		unit_type: "skill",
 		content: "---\nname: shared-demo\ndescription: Use for tests.\n---\n# Shared Demo\n",
+		files: [{ path: "scripts/run.sh", content: "echo shared\n" }],
 	}, env);
 	assert.equal(skillResult.accepted, true);
 	assert.equal(existsSync(join(agentRoot, "inbox", "skills", "unit_skill_1", "SKILL.md")), true);
+	assert.equal(existsSync(join(agentRoot, "inbox", "skills", "unit_skill_1", "scripts", "run.sh")), true);
 	assert.equal(existsSync(join(agentRoot, "skills", "generated", "unit_skill_1", "SKILL.md")), true);
+	assert.equal(existsSync(join(agentRoot, "skills", "generated", "unit_skill_1", "scripts", "run.sh")), true);
 	assert.equal(existsSync(join(agentRoot, "skills", "enabled", "unit_skill_1", "SKILL.md")), false);
 });