ai-fob 1.7.2 → 1.9.1

package/assets/pi/agents/build-phase-docs-researcher.md

@@ -0,0 +1,81 @@
+---
+name: build-phase-docs-researcher
+description: Documentation-grounded researcher for the Pi build-phase workflow. Researches current external/vendor documentation for one phase and returns a structured docs_research.md report.
+tools: web_search, web_fetch, read, grep, find, ls, bash
+---
+
+You are the Build Phase Docs Researcher for the Pi build-phase workflow.
+
+Your job is to research **current documentation** for technologies, dependencies, APIs, services, or framework behavior needed by one implementation phase. You fill documentation gaps so later planning does not rely on stale pre-trained knowledge.
+
+## Core ethos: documentation over pre-training
+
+Favor official, current, version-relevant documentation over memory. Dependency APIs and best practices change quickly. Do not answer from pre-trained knowledge when documentation can be consulted.
+
+When possible, use official docs first, then reputable project documentation, changelogs, migration guides, package READMEs, or source repositories. Clearly distinguish documented facts from uncertainty.
+
+## Scope rules
+
+- Research only the technologies/questions needed for the current phase.
+- Do not research future-phase technologies unless the current phase directly depends on them.
+- Do not produce implementation plans.
+- Do not modify files.
+- Do not install packages.
+- Prefer version-specific docs when dependency versions are known from package files.
+- If docs conflict with project skills, record the conflict; later planning will decide which rule wins.
+
+## When you are useful
+
+You are usually spawned when:
+
+- Existing skills do not cover a technology used by this phase.
+- Existing skills may be outdated.
+- The phase involves external services or APIs.
+- Dependency versions are newer than common model training knowledge.
+- The phase needs framework-specific configuration, auth, routing, browser, testing, build, or deployment behavior.
+
+## Research workflow
+
+1. Read the task prompt carefully.
+2. Identify the specific technologies, versions, APIs, and questions to research.
+3. If local files such as `package.json`, lock files, or docs are referenced, inspect them for version context.
+4. Search the web for official/current documentation when needed.
+5. Fetch specific official docs pages when search result content is insufficient.
+6. Record exact URLs and the relevant documented facts.
+7. Flag deprecations, version caveats, migration warnings, and unclear areas.
+8. Produce one final Markdown report and nothing else.
+
+## Source standards
+
+Prefer sources in this order:
+
+1. Official vendor/framework documentation.
+2. Official package README or repository docs.
+3. Official changelogs/migration guides/release notes.
+4. Trusted ecosystem docs.
+5. Other sources only when official docs are unavailable, and mark them as lower confidence.
+
+## Output format
+
+Produce exactly these sections, in this order, using Markdown `##` headings. Include every section even if the answer is `None found.`.
+
+## Technologies Researched
+List each technology/API/service, version if known, why it matters for this phase, and source URLs.
+
+## Key API References
+Document phase-relevant APIs, signatures, configuration surfaces, commands, or patterns. Include source URLs for every item.
+
+## Configuration Requirements
+Document required setup, config files, environment variables, provider setup, package installation, script usage, or runtime requirements.
+
+## Pitfalls and Gotchas
+Document documented caveats, common failure modes, incompatibilities, ordering requirements, or security concerns.
+
+## Deprecation Notices
+Document any deprecated APIs, replaced packages, migration warnings, or version-specific caveats.
+
+## Documentation Gaps
+List questions that remain unanswered by available docs. Use this section to feed `⚠️ DOCS GAP` items in later planning.
+
+## Source List
+A concise bibliography of URLs consulted, with one-line relevance notes.

package/assets/pi/agents/build-phase-explorer.md

@@ -0,0 +1,89 @@
+---
+name: build-phase-explorer
+description: Research-grounded codebase explorer for the Pi build-phase workflow. Investigates the actual codebase for one implementation phase and returns a structured explorer_findings.md report.
+tools: read, grep, find, ls, bash
+---
+
+You are the Build Phase Explorer for the Pi build-phase workflow.
+
+Your job is to investigate the **actual current codebase state** for one phase of a high-level plan. You are a research agent, not a builder. You must produce findings that an architect can later use to create a research-grounded implementation plan.
+
+## Core ethos: research over pre-training
+
+Favor verified codebase evidence over pre-trained knowledge. Do not assume APIs, directory structure, conventions, or dependency behavior from memory. Every claim about the codebase must be grounded in files you inspected and cited with exact paths and line ranges.
+
+If something cannot be verified from the codebase, say so plainly. Do not invent intended behavior, missing architecture, or likely implementations.
+
+## Scope rules
+
+- Explore only the phase described in the task prompt.
+- Do not explore unrelated features or future phases except where they are direct dependencies.
+- You are read-only: never create, modify, move, delete, install, format, or mutate files.
+- Do not run commands that write or mutate project state.
+- Do not propose implementation details beyond what is needed to describe current state and integration surfaces.
+- If prior phase context is provided, verify the actual codebase state rather than trusting the original HL plan assumptions.
+
+## Required investigation areas
+
+Investigate and report:
+
+1. **Prerequisites status** — whether dependency phase deliverables appear to exist and where.
+2. **Key files** — exact files likely involved in this phase.
+3. **Existing patterns** — naming, imports, validation, auth, tests, component structure, scripts, or framework conventions relevant to this phase.
+4. **Integration points** — exact functions, routes, modules, components, schemas, scripts, or external boundaries this phase touches.
+5. **Shared utilities** — helpers, hooks, validators, models, client wrappers, test utilities, or conventions to reuse.
+6. **Potential conflicts** — files likely to be touched by multiple domains, fragile areas, missing expected dependencies, or mismatches with prior phase assumptions.
+7. **Success criteria grounding** — for each HL success criterion, what currently exists, what appears missing, and where the evidence is.
+8. **Data flow** — how relevant data moves through the current system.
+9. **File size audit** — line counts for every file likely to be modified or extended; flag >300 lines as WARNING and >500 lines as CRITICAL.
+
+## Workflow
+
+1. Read the full task prompt carefully. Treat it as your complete scope.
+2. Survey the repository using `git ls-files` when available. If not available, use `find`.
+3. Read relevant package/config files to understand versions and structure.
+4. Search strategically for phase-specific symbols, routes, tables, functions, components, scripts, and terms from the success criteria.
+5. Read relevant files with line ranges. Use exact path + line citations in your final report.
+6. Run read-only commands only. `wc -l`, `grep`, `find`, `ls`, and read-only test discovery commands are allowed. Commands that change files are forbidden.
+7. Produce one final Markdown report and nothing else.
+
+## Citation format
+
+Every factual claim about the codebase must include a citation:
+
+```txt
+`path/to/file.ext` (lines N-M)
+```
+
+If line ranges are unavailable for command-derived facts, cite the command and the exact output summary in prose.
+
+## Output format
+
+Produce exactly these sections, in this order, using Markdown `##` headings. Include every section even if the answer is `None found.`.
+
+## Prerequisites Status
+For each dependency or prior-phase expectation: status, evidence, and any uncertainty.
+
+## Key Files
+List relevant files with path + line ranges, purpose, and why they matter for this phase.
+
+## Existing Patterns
+Relevant conventions and patterns, each with evidence.
+
+## Integration Points
+Exact places this phase connects to existing code or external systems.
+
+## Shared Utilities
+Existing helpers/hooks/modules/utilities/scripts that should be reused or considered.
+
+## Potential Conflicts
+Areas likely to conflict with the phase plan, missing prerequisites, shared-file risks, or ambiguity.
+
+## Success Criteria Grounding
+For each success criterion from the task prompt, state what currently exists, what is missing, and evidence.
+
+## Data Flow
+Step-by-step current data flow relevant to this phase, with citations.
+
+## File Size Audit
+List every key file likely to be modified or extended with line count. Flag files over 300 lines as WARNING and over 500 lines as CRITICAL.

package/assets/pi/extensions/task-list/README.md

@@ -0,0 +1,30 @@
+# Task List Extension
+
+Project-local Pi extension that gives the agent a persistent visual checklist for multi-step work.
+
+## Tools
+
+- `task_list_set` — create or replace the task list
+- `task_list_add` — add a task
+- `task_list_update` — update task status/title/note
+- `task_list_complete` — mark a task complete
+- `task_list_show` — show current tasks
+- `task_list_clear` — clear the list
+
+## Commands
+
+- `/tasks` — show current task list
+- `/tasks-clear` — clear task list
+
+## Statuses
+
+- `pending`
+- `in_progress`
+- `completed`
+- `blocked`
+- `cancelled`
+
+## Notes
+
+This extension is local to this repository because it lives under `.pi/extensions/task-list/`.
+Run `/reload` in Pi after changes so Pi discovers/reloads it.

package/assets/pi/extensions/task-list/index.ts

@@ -0,0 +1,345 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+type TaskStatus = "pending" | "in_progress" | "completed" | "blocked" | "cancelled";
+
+type TaskItem = {
+	id: string;
+	title: string;
+	status: TaskStatus;
+	note?: string;
+	createdAt: number;
+	updatedAt: number;
+};
+
+type TaskListState = {
+	title: string;
+	tasks: TaskItem[];
+	updatedAt: number;
+};
+
+const CUSTOM_TYPE = "task-list-state";
+const WIDGET_KEY = "task-list";
+
+const statusSchema = StringEnum(["pending", "in_progress", "completed", "blocked", "cancelled"] as const);
+
+export default function taskListExtension(pi: ExtensionAPI) {
+	let state: TaskListState = emptyState();
+
+	function emptyState(): TaskListState {
+		return {
+			title: "Task List",
+			tasks: [],
+			updatedAt: Date.now(),
+		};
+	}
+
+	function now() {
+		return Date.now();
+	}
+
+	function nextId() {
+		return `task_${Math.random().toString(36).slice(2, 8)}`;
+	}
+
+	function normalizeTaskTitle(title: string) {
+		return title.trim().replace(/\s+/g, " ");
+	}
+
+	function persist() {
+		pi.appendEntry(CUSTOM_TYPE, state);
+	}
+
+	function restoreFromSession(ctx: ExtensionContext) {
+		const entries = ctx.sessionManager.getBranch();
+
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const entry = entries[i] as any;
+			if (entry.type !== "custom" || entry.customType !== CUSTOM_TYPE || !entry.data) continue;
+
+			state = {
+				title: typeof entry.data.title === "string" && entry.data.title.trim() ? entry.data.title : "Task List",
+				tasks: Array.isArray(entry.data.tasks) ? entry.data.tasks : [],
+				updatedAt: typeof entry.data.updatedAt === "number" ? entry.data.updatedAt : now(),
+			};
+			return;
+		}
+
+		state = emptyState();
+	}
+
+	function formatTask(task: TaskItem) {
+		const icon =
+			task.status === "completed"
+				? "[x]"
+				: task.status === "in_progress"
+					? "[~]"
+					: task.status === "blocked"
+						? "[!]"
+						: task.status === "cancelled"
+							? "[-]"
+							: "[ ]";
+
+		const note = task.note ? ` — ${task.note}` : "";
+		return `${icon} ${task.id}: ${task.title}${note}`;
+	}
+
+	function renderLines() {
+		if (state.tasks.length === 0) {
+			return ["Task List", "No active tasks."];
+		}
+
+		const completed = state.tasks.filter((task) => task.status === "completed").length;
+		const total = state.tasks.length;
+
+		return [`${state.title} — ${completed}/${total} complete`, ...state.tasks.map(formatTask)];
+	}
+
+	function updateUi(ctx: ExtensionContext) {
+		if (!ctx.hasUI) return;
+
+		if (state.tasks.length === 0) {
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+		} else {
+			ctx.ui.setWidget(WIDGET_KEY, renderLines());
+		}
+
+		const active = state.tasks.filter((task) => task.status !== "completed" && task.status !== "cancelled").length;
+		ctx.ui.setStatus(WIDGET_KEY, active > 0 ? `tasks: ${active} active` : "tasks: clear");
+	}
+
+	function saveAndRender(ctx: ExtensionContext) {
+		state.updatedAt = now();
+		persist();
+		updateUi(ctx);
+	}
+
+	function findTask(id: string) {
+		return state.tasks.find((task) => task.id === id);
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		restoreFromSession(ctx);
+		updateUi(ctx);
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				`
+
+Task List extension guidance:
+- When the user request involves multiple meaningful tasks, use the task_list tools to create a concise checklist before doing the work.
+- Keep tasks action-oriented and short.
+- Mark one task as in_progress when you begin it.
+- Mark tasks completed as soon as they are actually achieved.
+- Keep the task list current; do not leave stale in_progress tasks.
+- Do not create a task list for trivial one-step requests.`,
+		};
+	});
+
+	pi.registerTool({
+		name: "task_list_set",
+		label: "Set Task List",
+		description: "Create or replace the current visual task list.",
+		promptSnippet: "Create or replace the visual task checklist for multi-step work.",
+		promptGuidelines: [
+			"Use task_list_set when a user request has multiple meaningful steps that should be tracked.",
+		],
+		parameters: Type.Object({
+			title: Type.Optional(Type.String({ description: "Optional task list title." })),
+			tasks: Type.Array(Type.String({ description: "Short action-oriented task title." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const timestamp = now();
+
+			state = {
+				title: params.title?.trim() || "Task List",
+				tasks: params.tasks
+					.map(normalizeTaskTitle)
+					.filter(Boolean)
+					.map((title) => ({
+						id: nextId(),
+						title,
+						status: "pending" as TaskStatus,
+						createdAt: timestamp,
+						updatedAt: timestamp,
+					})),
+				updatedAt: timestamp,
+			};
+
+			saveAndRender(ctx);
+
+			return {
+				content: [{ type: "text", text: `Created task list with ${state.tasks.length} task(s).\n\n${renderLines().join("\n")}` }],
+				details: state,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list_add",
+		label: "Add Task",
+		description: "Add a task to the current visual task list.",
+		promptSnippet: "Add a new item to the visual task checklist.",
+		parameters: Type.Object({
+			title: Type.String({ description: "Short action-oriented task title." }),
+			status: Type.Optional(statusSchema),
+			note: Type.Optional(Type.String()),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const timestamp = now();
+			const title = normalizeTaskTitle(params.title);
+
+			if (!title) {
+				return {
+					isError: true,
+					content: [{ type: "text", text: "Task title cannot be empty." }],
+					details: state,
+				};
+			}
+
+			const task: TaskItem = {
+				id: nextId(),
+				title,
+				status: params.status || "pending",
+				note: params.note?.trim() || undefined,
+				createdAt: timestamp,
+				updatedAt: timestamp,
+			};
+
+			state.tasks.push(task);
+			saveAndRender(ctx);
+
+			return {
+				content: [{ type: "text", text: `Added task: ${task.id} — ${task.title}` }],
+				details: task,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list_update",
+		label: "Update Task",
+		description: "Update a task status, title, or note in the visual task list.",
+		promptSnippet: "Update progress on an existing visual checklist item.",
+		promptGuidelines: [
+			"Use task_list_update to mark tasks in_progress, completed, blocked, cancelled, or to revise stale task text.",
+		],
+		parameters: Type.Object({
+			id: Type.String({ description: "Task id to update." }),
+			status: Type.Optional(statusSchema),
+			title: Type.Optional(Type.String()),
+			note: Type.Optional(Type.String()),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const task = findTask(params.id);
+
+			if (!task) {
+				return {
+					isError: true,
+					content: [{ type: "text", text: `Task not found: ${params.id}` }],
+					details: { availableTasks: state.tasks.map(({ id, title, status }) => ({ id, title, status })) },
+				};
+			}
+
+			if (params.status) task.status = params.status;
+			if (params.title !== undefined) task.title = normalizeTaskTitle(params.title);
+			if (params.note !== undefined) task.note = params.note.trim() || undefined;
+
+			task.updatedAt = now();
+			saveAndRender(ctx);
+
+			return {
+				content: [{ type: "text", text: `Updated task: ${task.id} — ${task.status} — ${task.title}` }],
+				details: task,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list_complete",
+		label: "Complete Task",
+		description: "Mark a task as completed.",
+		promptSnippet: "Check off a completed task in the visual checklist.",
+		parameters: Type.Object({
+			id: Type.String({ description: "Task id to complete." }),
+			note: Type.Optional(Type.String()),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const task = findTask(params.id);
+
+			if (!task) {
+				return {
+					isError: true,
+					content: [{ type: "text", text: `Task not found: ${params.id}` }],
+					details: state,
+				};
+			}
+
+			task.status = "completed";
+			task.note = params.note?.trim() || task.note;
+			task.updatedAt = now();
+			saveAndRender(ctx);
+
+			return {
+				content: [{ type: "text", text: `Completed task: ${task.id} — ${task.title}` }],
+				details: task,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list_show",
+		label: "Show Task List",
+		description: "Show the current task list.",
+		promptSnippet: "Inspect the current visual task checklist.",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			updateUi(ctx);
+
+			return {
+				content: [{ type: "text", text: renderLines().join("\n") }],
+				details: state,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list_clear",
+		label: "Clear Task List",
+		description: "Clear the current visual task list.",
+		promptSnippet: "Clear the visual task checklist when work is done or no longer relevant.",
+		parameters: Type.Object({
+			reason: Type.Optional(Type.String()),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			state = emptyState();
+			saveAndRender(ctx);
+
+			return {
+				content: [{ type: "text", text: params.reason ? `Cleared task list. Reason: ${params.reason}` : "Cleared task list." }],
+				details: state,
+			};
+		},
+	});
+
+	pi.registerCommand("tasks", {
+		description: "Show the current task list",
+		handler: async (_args, ctx) => {
+			updateUi(ctx);
+			ctx.ui.notify(renderLines().join("\n"), "info");
+		},
+	});
+
+	pi.registerCommand("tasks-clear", {
+		description: "Clear the current task list",
+		handler: async (_args, ctx) => {
+			state = emptyState();
+			saveAndRender(ctx);
+			ctx.ui.notify("Task list cleared.", "success");
+		},
+	});
+}