ai-fob 1.7.2 → 1.9.0

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");
+		},
+	});
+}

package/assets/pi/prompts/build-phase.md

@@ -0,0 +1,157 @@
+---
+description: Build one phase of a phased high-level plan using the Pi workflow
+argument-hint: "<path to HL plan> <phase number>"
+---
+
+# Build Phase Workflow — Step 0 Only
+
+You are running the Pi re-engineered build-phase workflow.
+
+Current implementation status: **Step 0: Parse & Prepare only**.
+
+Do not proceed to research, planning, validation, build, or final reporting yet. Stop after presenting the Step 0 execution overview.
+
+## Required skill
+
+Load and follow the `FOB-state-context` skill before reading or modifying `specs/STATE.md` or detecting project context.
+
+## Arguments
+
+Raw arguments: `$ARGUMENTS`
+
+Parse into:
+
+- `HL_PLAN_PATH`: first argument
+- `PHASE_NUMBER`: second argument
+
+If either is missing, stop with:
+
+```txt
+Usage: /build-phase <path to HL plan> <phase number>
+```
+
+## Step 0: Parse & Prepare
+
+Perform these tasks directly as the main/orchestrator agent.
+
+### 0.1 Validate inputs
+
+1. Verify `HL_PLAN_PATH` exists.
+2. Verify `HL_PLAN_PATH` is a Markdown file ending in `.md`.
+3. Read the YAML frontmatter.
+4. Verify `PHASE_NUMBER` is an integer.
+5. Verify `PHASE_NUMBER` is within the frontmatter `phases:` count.
+6. If the phase is out of range, stop with:
+
+```txt
+Phase {N} is out of range. This plan has {count} phases (1-{count}).
+```
+
+### 0.2 Derive variables
+
+Compute:
+
+- `SPEC_DIR`: parent directory of `HL_PLAN_PATH`
+- `SPEC_DIR_BASENAME`: basename of `SPEC_DIR`
+- `TASK_NAME`: frontmatter `task:` value
+- `CATEGORY`: frontmatter `category:` value if present
+- `SPEC_NUMBER`: numeric prefix from `SPEC_DIR_BASENAME` if present
+- `PHASE_NAME`: from `### Phase {N}: {Name}` in the HL plan body
+- `PHASE_NAME_KEBAB`: kebab-case of `PHASE_NAME`
+- `PHASE_DIR`: `{SPEC_DIR}/phase{N}_{PHASE_NAME_KEBAB}/`
+- `REFERENCE_DOCUMENTS`: frontmatter `reference-documents:` list, or empty list
+
+### 0.3 Initialize state
+
+Using the `FOB-state-context` skill:
+
+1. Read `specs/STATE.md` if it exists.
+2. If it does not exist, create a minimal valid state file.
+3. Find or create the current task entry matching `TASK_NAME`.
+4. Find or create the `Phase {PHASE_NUMBER}: {PHASE_NAME}` block under that task.
+5. Ensure Step 1 through Step 6 lines exist under the phase block.
+6. Ensure `pre-phase-sha` and `post-build-sha` lines exist.
+7. Mark the task and phase as in-progress (`[~]`) if they are still pending.
+
+For Step 0-only mode, do **not** mark Step 1 started.
+
+### 0.4 Git pre-phase checkpoint
+
+1. Run `git status --porcelain`.
+2. If git is unavailable, set `GIT_AVAILABLE = false` and warn that checkpoint commits are skipped.
+3. If git is available:
+   - Set `GIT_AVAILABLE = true`.
+   - If there are uncommitted changes, commit them with:
+
+     ```txt
+     checkpoint: pre-phase-{PHASE_NUMBER} ({PHASE_NAME_KEBAB})
+     ```
+
+   - Capture `PRE_PHASE_SHA` with `git rev-parse HEAD`.
+   - Record it in the phase block as `pre-phase-sha`.
+
+### 0.5 Extract phase context
+
+From the HL plan, extract and summarize:
+
+- Task Overview, usually Section 1
+- User Stories and Anti-Stories, usually Section 3
+- Current Phase section from Section 4
+- High-Level Approach, usually Section 6
+- Key Considerations, usually Section 7
+- Detailed Specifications, usually Section 8 if present
+
+Do not create Step 1 research artifacts yet.
+
+### 0.6 Read prior phase reports
+
+If `PHASE_NUMBER > 1`:
+
+1. Look for prior phase reports at `{SPEC_DIR}/phase*/phase_completion_report.md` for phases before the current phase.
+2. Extract:
+   - phase number
+   - phase name
+   - status
+   - `## What Was Built`
+   - `## Deviations from HL Plan`
+   - `## Impacts on Future Phases`
+3. Compile a `PRIOR_PHASE_CONTEXT` summary.
+4. Highlight any direct impacts that mention the current phase.
+
+If `PHASE_NUMBER == 1`, set prior phase context to `N/A — this is Phase 1`.
+
+### 0.7 Detect project context and skills
+
+Using the `FOB-state-context` skill:
+
+1. Detect package manager from lock files.
+2. Scan available skill directories for skills matching technologies mentioned in the HL plan and phase section.
+3. Read matched skill files enough to identify skill names and CRITICAL/HIGH rules, if present.
+
+### 0.8 Create phase directory
+
+Create `PHASE_DIR` idempotently.
+
+### 0.9 Present Step 0 execution overview
+
+Print:
+
+```txt
+BUILD PHASE {N} — {PHASE_NAME}
+
+Spec: {SPEC_DIR_BASENAME} ({TASK_NAME})
+Phase Directory: {PHASE_DIR}
+Dependencies: {phase dependencies from HL plan}
+Success Criteria: {count} defined
+Prior Phase Reports: {count read | N/A (Phase 1)}
+Skills Detected: {list or "None"}
+Reference Documents: {count or "None"}
+Resume Status: Step 0 initialized only
+Pre-phase SHA: {PRE_PHASE_SHA | N/A (git unavailable)}
+
+Step 0 complete. Workflow intentionally stopped before Step 1 Research.
+```
+
+## Stop condition
+
+After the overview, stop. Do not spawn sub-agents. Do not create `explorer_findings.md`, `docs_research.md`, `plan_V1.md`, or any later-step artifacts.

package/assets/pi/skills/FOB-state-context/SKILL.md

@@ -0,0 +1,123 @@
+# FOB State Context
+
+Use this skill when a workflow needs to read, scaffold, update, or summarize project state for FOB-style build workflows.
+
+This skill is required for the Pi build-phase workflow. It defines how the orchestrator manages `specs/STATE.md`, detects project context, and prepares state so later research/build agents can resume safely.
+
+## Core responsibilities
+
+1. Read and update `specs/STATE.md` without destroying unrelated task history.
+2. Maintain nested task → phase → step progress markers.
+3. Record git checkpoint SHAs for phase-level resumability.
+4. Detect package manager and basic project context.
+5. Discover relevant technology/convention skills for the current plan.
+
+## State marker semantics
+
+- `[ ]` means pending / not started.
+- `[~]` means in progress / started but not confirmed complete.
+- `[x]` means completed / output verified.
+
+Never mark a step complete unless the expected artifact or action has been verified.
+
+## Expected phase step names
+
+Every build phase has these six workflow steps:
+
+1. `Step 1 - Research`
+2. `Step 2 - Plan`
+3. `Step 3 - Validate Plan`
+4. `Step 4 - Build`
+5. `Step 5 - Validate Build`
+6. `Step 6 - Report`
+
+Step 0 is orchestration setup and is not represented as a numbered step inside the phase block.
+
+## Required phase metadata lines
+
+Every phase block must include:
+
+```txt
+pre-phase-sha: (pending)
+post-build-sha: (pending)
+```
+
+`pre-phase-sha` is recorded during Step 0. `post-build-sha` is recorded after the build step.
+
+## Standard state operations
+
+### Initialize or repair state file
+
+If `specs/STATE.md` does not exist, create a minimal state file:
+
+```markdown
+# Project State
+
+## Current Tasks
+
+## Completed Tasks
+```
+
+If the file exists, preserve its content and only make targeted updates.
+
+### Initialize task entry
+
+Find the current task line by matching the task name. If it does not exist under `## Current Tasks`, add:
+
+```markdown
+- [~] {TASK_NAME}
+```
+
+If the task line exists with `[ ]`, update it to `[~]` when a phase is initialized.
+
+### Initialize phase entry
+
+Under the matching task line, ensure this block exists:
+
+```markdown
+  - [~] Phase {PHASE_NUMBER}: {PHASE_NAME}
+    - [ ] Step 1 - Research
+    - [ ] Step 2 - Plan
+    - [ ] Step 3 - Validate Plan
+    - [ ] Step 4 - Build
+    - [ ] Step 5 - Validate Build
+    - [ ] Step 6 - Report
+    pre-phase-sha: (pending)
+    post-build-sha: (pending)
+```
+
+If the phase block exists, repair missing step or SHA lines rather than duplicating the phase.
+
+### Mark step start
+
+When a workflow step starts, update its marker from `[ ]` to `[~]`. Also ensure the parent phase and task are marked `[~]` unless already `[x]`.
+
+### Mark step complete
+
+When a workflow step has been verified, update its marker from `[~]` to `[x]`. If all six steps under a phase are `[x]`, mark the phase `[x]`. If all phases under a task are `[x]`, mark the task `[x]` and move it to `## Completed Tasks` with the current date.
+
+### Record SHA
+
+To record a git SHA, replace the value on the matching line inside the current phase block:
+
+```txt
+pre-phase-sha: {sha}
+post-build-sha: {sha}
+```
+
+Do not update SHA lines in other phases.
+
+## Project context detection
+
+Read `references/project-context-detection.md` for package manager detection and skill discovery rules.
+
+## State format reference
+
+Read `references/state-format.md` for examples and exact indentation conventions.
+
+## Important constraints
+
+- Preserve unrelated tasks, completed task history, comments, and manually added notes whenever possible.
+- Do not invent completed state. Completion requires verified output.
+- Prefer small, targeted edits over rewriting the entire state file when possible.
+- If state and artifacts disagree, future resume logic should trust verified artifacts over stale state markers, but Step 0 only needs to initialize and repair the state skeleton.