pi-blueprint 0.2.0

package/src/plan-next-command.ts

@@ -0,0 +1,56 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import type { StateRef } from "./types.js";
+import { getNextTask } from "./state-machine.js";
+
+export const COMMAND_NAME = "plan-next";
+
+export async function handlePlanNextCommand(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  stateRef: StateRef,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const state = stateRef.get();
+  if (!state.blueprint) {
+    ctx.ui.notify("No active blueprint.", "info");
+    return;
+  }
+
+  const next = getNextTask(state.blueprint);
+  if (!next) {
+    ctx.ui.notify(
+      state.blueprint.status === "completed"
+        ? "Blueprint is complete."
+        : "No actionable tasks. Some may be blocked or awaiting verification.",
+      "info",
+    );
+    return;
+  }
+
+  const lines = [
+    `Work on blueprint task ${next.id}: ${next.title}`,
+    "",
+    next.description,
+  ];
+
+  if (next.acceptance_criteria.length > 0) {
+    lines.push("", "Acceptance criteria:");
+    for (const c of next.acceptance_criteria) {
+      lines.push(`- ${c}`);
+    }
+  }
+
+  if (next.file_targets.length > 0) {
+    lines.push("", "File targets:");
+    for (const f of next.file_targets) {
+      lines.push(`- ${f}`);
+    }
+  }
+
+  lines.push("", "When done, call the blueprint_update tool to mark this task as completed.");
+
+  pi.sendUserMessage(lines.join("\n"), { deliverAs: "followUp" });
+}

package/src/plan-renderer.ts

@@ -0,0 +1,70 @@
+import type { Blueprint, Phase, Task } from "./types.js";
+import { isTaskDone } from "./types.js";
+
+export function renderPlanMarkdown(blueprint: Blueprint): string {
+  const lines: string[] = [];
+  lines.push(`# Blueprint: ${blueprint.objective}`);
+  lines.push("");
+  lines.push(`**Status:** ${blueprint.status} | Created: ${formatDate(blueprint.created_at)} | Updated: ${formatDate(blueprint.updated_at)}`);
+
+  for (const phase of blueprint.phases) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(renderPhase(phase, blueprint.active_phase_id));
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function renderPhase(phase: Phase, activePhaseId: string | null): string {
+  const lines: string[] = [];
+  const isActive = phase.id === activePhaseId;
+  const activeTag = isActive ? " (active)" : "";
+
+  const completed = phase.tasks.filter(isTaskDone).length;
+  const total = phase.tasks.length;
+
+  lines.push(`## Phase ${phase.id}: ${phase.title}${activeTag}`);
+  lines.push("");
+  lines.push(`**Status:** ${phase.status} | ${completed}/${total} tasks completed`);
+
+  if (phase.description) {
+    lines.push("");
+    lines.push(phase.description);
+  }
+
+  if (phase.tasks.length > 0) {
+    lines.push("");
+    lines.push("### Tasks");
+    lines.push("");
+    for (const task of phase.tasks) {
+      lines.push(renderTask(task));
+    }
+  }
+
+  if (phase.verification_gates.length > 0) {
+    lines.push("");
+    lines.push("### Verification Gates");
+    lines.push("");
+    for (const gate of phase.verification_gates) {
+      const check = gate.passed ? "x" : " ";
+      lines.push(`- [${check}] ${gate.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderTask(task: Task): string {
+  const check = isTaskDone(task) ? "x" : " ";
+  let annotation = "";
+  if (task.status === "in_progress") annotation = " *(in progress)*";
+  else if (task.status === "blocked") annotation = " *(blocked)*";
+  else if (task.status === "skipped") annotation = " *(skipped)*";
+  return `- [${check}] ${task.id} ${task.title}${annotation}`;
+}
+
+function formatDate(iso: string): string {
+  return iso.slice(0, 10);
+}

package/src/plan-status-command.ts

@@ -0,0 +1,30 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { StateRef } from "./types.js";
+import { isTaskDone } from "./types.js";
+import { renderPlanMarkdown } from "./plan-renderer.js";
+import { getAllTasks } from "./dependency-graph.js";
+
+export const COMMAND_NAME = "plan-status";
+
+export async function handlePlanStatusCommand(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  stateRef: StateRef,
+): Promise<void> {
+  const state = stateRef.get();
+  if (!state.blueprint) {
+    ctx.ui.notify("No active blueprint.", "info");
+    return;
+  }
+
+  const bp = state.blueprint;
+  const allTasks = getAllTasks(bp.phases);
+  const completed = allTasks.filter(isTaskDone).length;
+  const total = allTasks.length;
+  const pct = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  const header = `Progress: ${completed}/${total} tasks (${pct}%)`;
+  const plan = renderPlanMarkdown(bp);
+
+  ctx.ui.notify(`${header}\n\n${plan}`, "info");
+}

package/src/plan-verify-command.ts

@@ -0,0 +1,82 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { StateRef } from "./types.js";
+import { verifyGate, advancePhase } from "./state-machine.js";
+import { runGate } from "./verification.js";
+import { saveBlueprint, appendHistory } from "./storage.js";
+
+export const COMMAND_NAME = "plan-verify";
+
+export async function handlePlanVerifyCommand(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  stateRef: StateRef,
+): Promise<void> {
+  const state = stateRef.get();
+  if (!state.blueprint) {
+    ctx.ui.notify("No active blueprint.", "info");
+    return;
+  }
+
+  const bp = state.blueprint;
+  const phase = bp.phases.find((p) => p.id === bp.active_phase_id);
+  if (!phase) {
+    ctx.ui.notify("No active phase to verify.", "info");
+    return;
+  }
+
+  if (phase.verification_gates.length === 0) {
+    ctx.ui.notify(`Phase ${phase.id} has no verification gates. Advancing.`, "info");
+    const advanced = advancePhase(bp);
+    saveBlueprint(advanced);
+    stateRef.set({ ...state, blueprint: advanced });
+    return;
+  }
+
+  const cwd = state.project?.root ?? process.cwd();
+  let updated = bp;
+  const results: string[] = [];
+
+  for (let i = 0; i < phase.verification_gates.length; i++) {
+    const gate = phase.verification_gates[i]!;
+
+    if (gate.type === "user_approval") {
+      results.push(`- ${gate.description}: requires manual approval (skipped in automated run)`);
+      continue;
+    }
+
+    ctx.ui.notify(`Running: ${gate.description}...`, "info");
+    const result = runGate(gate, cwd);
+    updated = verifyGate(updated, phase.id, i, result.passed, result.passed ? undefined : result.output);
+
+    const status = result.passed ? "PASSED" : "FAILED";
+    results.push(`- ${gate.description}: ${status} (${result.duration_ms}ms)`);
+
+    appendHistory(updated.id, {
+      timestamp: new Date().toISOString(),
+      event: result.passed ? "verification_passed" : "verification_failed",
+      phase_id: phase.id,
+      task_id: null,
+      session_id: state.sessionId,
+      details: `${gate.description}: ${status}`,
+    });
+  }
+
+  const currentPhase = updated.phases.find((p) => p.id === phase.id)!;
+  const allPassed = currentPhase.verification_gates
+    .filter((g) => g.type !== "user_approval")
+    .every((g) => g.passed);
+
+  if (allPassed) {
+    const hasUserApproval = currentPhase.verification_gates.some((g) => g.type === "user_approval" && !g.passed);
+    if (!hasUserApproval) {
+      updated = advancePhase(updated);
+      results.push("\nAll gates passed. Phase advanced.");
+    } else {
+      results.push("\nAutomated gates passed. User approval still required.");
+    }
+  }
+
+  saveBlueprint(updated);
+  stateRef.set({ ...state, blueprint: updated });
+  ctx.ui.notify(`Verification results for Phase ${phase.id}:\n${results.join("\n")}`, "info");
+}

package/src/prompts/blueprint-generate.ts

@@ -0,0 +1,34 @@
+export function getBlueprintGeneratePrompt(objective: string): string {
+  return `You are a senior software architect planning a complex implementation.
+
+## Objective
+${objective}
+
+## Instructions
+
+Analyze the codebase and the objective above, then create a phased construction plan by calling the \`blueprint_create\` tool.
+
+### Plan structure requirements:
+1. Break the work into 2-6 phases, ordered by dependency (foundations first)
+2. Each phase should have 2-8 concrete, agent-sized tasks
+3. Each task must have:
+   - A clear, imperative title (e.g., "Add OAuth2 callback endpoint")
+   - A brief description of what to implement
+   - Acceptance criteria (testable conditions)
+   - File targets (files to create or modify)
+   - Dependencies on other tasks (by task ID, e.g., "1.1", "2.3")
+4. Each phase should have verification gates:
+   - Phase 1 typically: tests_pass
+   - Later phases: tests_pass + typecheck_clean
+   - Final phase: tests_pass + typecheck_clean + user_approval (optional)
+5. Tasks within a phase can depend on other tasks (within or across phases)
+6. Task IDs follow the format "phase.task" (e.g., "1.1", "1.2", "2.1")
+
+### Quality criteria:
+- Each task should be completable in a single agent session
+- Dependencies should be minimal and acyclic
+- Acceptance criteria should be specific and testable
+- File targets should reference real paths in the codebase when possible
+
+Call the \`blueprint_create\` tool with the structured plan.`;
+}

package/src/prompts/phase-context.ts

@@ -0,0 +1,76 @@
+import type { Blueprint, Task } from "../types.js";
+import { isTaskDone } from "../types.js";
+import { getBlockingTasks, getAllTasks } from "../dependency-graph.js";
+
+export function buildPhaseContext(blueprint: Blueprint): string {
+  const lines: string[] = [];
+
+  lines.push(`## Active Blueprint: "${blueprint.objective}"`);
+  lines.push("");
+
+  const activePhase = blueprint.phases.find((p) => p.id === blueprint.active_phase_id);
+  if (!activePhase) {
+    lines.push("No active phase. All phases may be complete or verified.");
+    return lines.join("\n");
+  }
+
+  const completed = activePhase.tasks.filter(isTaskDone).length;
+
+  lines.push(`### Current Phase: Phase ${activePhase.id} - ${activePhase.title}`);
+  lines.push(`Status: ${activePhase.status} | ${completed}/${activePhase.tasks.length} tasks completed`);
+
+  const activeTask = activePhase.tasks.find((t) => t.id === blueprint.active_task_id);
+  if (activeTask) {
+    lines.push("");
+    lines.push(buildTaskContext(activeTask));
+  }
+
+  const blockedTasks = activePhase.tasks.filter((t) => t.status === "blocked");
+  if (blockedTasks.length > 0) {
+    lines.push("");
+    lines.push("### Blocked Tasks");
+    const allTasks = getAllTasks(blueprint.phases);
+    for (const task of blockedTasks) {
+      const blockers = getBlockingTasks(allTasks, task.id);
+      lines.push(`- ${task.id} "${task.title}" - blocked by ${blockers.join(", ")}`);
+    }
+  }
+
+  if (activePhase.verification_gates.length > 0) {
+    lines.push("");
+    lines.push(`### Phase ${activePhase.id} Verification Gates`);
+    for (const gate of activePhase.verification_gates) {
+      const check = gate.passed ? "x" : " ";
+      lines.push(`- [${check}] ${gate.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function buildTaskContext(task: Task): string {
+  const lines: string[] = [];
+  lines.push(`### Current Task: ${task.id} - ${task.title}`);
+
+  if (task.description) {
+    lines.push(task.description);
+  }
+
+  if (task.acceptance_criteria.length > 0) {
+    lines.push("");
+    lines.push("**Acceptance criteria:**");
+    for (const c of task.acceptance_criteria) {
+      lines.push(`- ${c}`);
+    }
+  }
+
+  if (task.file_targets.length > 0) {
+    lines.push("");
+    lines.push("**File targets:**");
+    for (const f of task.file_targets) {
+      lines.push(`- ${f}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/state-machine.ts

@@ -0,0 +1,278 @@
+import type { Blueprint, Phase, Task, TaskStatus, PhaseStatus } from "./types.js";
+import { isTaskDone } from "./types.js";
+import { findBlockedTasks, isTaskReady, getAllTasks } from "./dependency-graph.js";
+
+function updateTask(phase: Phase, taskId: string, patch: Partial<Task>): Phase {
+  return {
+    ...phase,
+    tasks: phase.tasks.map((t) => (t.id === taskId ? { ...t, ...patch } : t)),
+  };
+}
+
+function updatePhase(blueprint: Blueprint, phaseId: string, patch: Partial<Phase>): Blueprint {
+  return {
+    ...blueprint,
+    updated_at: new Date().toISOString(),
+    phases: blueprint.phases.map((p) => (p.id === phaseId ? { ...p, ...patch } : p)),
+  };
+}
+
+function findTask(
+  blueprint: Blueprint,
+  taskId: string,
+): { phase: Phase; task: Task } | null {
+  for (const phase of blueprint.phases) {
+    const task = phase.tasks.find((t) => t.id === taskId);
+    if (task) return { phase, task };
+  }
+  return null;
+}
+
+function findNextTaskInPhase(phase: Phase, allTasks: readonly Task[]): Task | null {
+  for (const task of phase.tasks) {
+    if (task.status === "in_progress") return task;
+  }
+  for (const task of phase.tasks) {
+    if (task.status === "pending" && isTaskReady(allTasks, task.id)) return task;
+  }
+  return null;
+}
+
+function resolveTaskCompletion(
+  blueprint: Blueprint,
+  phaseId: string,
+  taskId: string,
+): Blueprint {
+  let bp = recomputeBlocked(blueprint);
+
+  if (bp.active_task_id === taskId) {
+    const next = getNextTask(bp);
+    bp = { ...bp, active_task_id: next?.id ?? null };
+  }
+
+  const currentPhase = bp.phases.find((p) => p.id === phaseId);
+  if (currentPhase && currentPhase.tasks.every(isTaskDone)) {
+    bp = updatePhase(bp, phaseId, { status: "completed" as PhaseStatus });
+  }
+
+  return bp;
+}
+
+export function startTask(
+  blueprint: Blueprint,
+  taskId: string,
+  sessionId: string,
+): Blueprint {
+  const found = findTask(blueprint, taskId);
+  if (!found) return blueprint;
+
+  const { phase, task } = found;
+  if (isTaskDone(task)) return blueprint;
+
+  const now = new Date().toISOString();
+  const updatedPhase = updateTask(phase, taskId, {
+    status: "in_progress" as TaskStatus,
+    started_at: task.started_at ?? now,
+    session_id: sessionId,
+  });
+
+  let phaseStatus = phase.status;
+  if (phaseStatus === "pending") {
+    phaseStatus = "active";
+  }
+
+  let bp = updatePhase(blueprint, phase.id, {
+    ...updatedPhase,
+    status: phaseStatus,
+    started_at: phase.started_at ?? now,
+  });
+
+  bp = {
+    ...bp,
+    active_phase_id: phase.id,
+    active_task_id: taskId,
+    status: blueprint.status === "draft" ? "active" : blueprint.status,
+  };
+
+  return bp;
+}
+
+export function completeTask(blueprint: Blueprint, taskId: string): Blueprint {
+  const found = findTask(blueprint, taskId);
+  if (!found) return blueprint;
+
+  const { phase, task } = found;
+  if (task.status === "completed") return blueprint;
+
+  const updatedPhase = updateTask(phase, taskId, {
+    status: "completed" as TaskStatus,
+    completed_at: new Date().toISOString(),
+  });
+
+  let bp = updatePhase(blueprint, phase.id, updatedPhase);
+  bp = resolveTaskCompletion(bp, phase.id, taskId);
+
+  const allTasks = getAllTasks(bp.phases);
+  if (allTasks.every(isTaskDone)) {
+    const allVerified = bp.phases.every((p) =>
+      p.verification_gates.length === 0 || p.verification_gates.every((g) => g.passed),
+    );
+    if (allVerified) {
+      bp = { ...bp, status: "completed" };
+    }
+  }
+
+  return bp;
+}
+
+export function skipTask(blueprint: Blueprint, taskId: string): Blueprint {
+  const found = findTask(blueprint, taskId);
+  if (!found) return blueprint;
+
+  const { phase } = found;
+  const updatedPhase = updateTask(phase, taskId, {
+    status: "skipped" as TaskStatus,
+    completed_at: new Date().toISOString(),
+  });
+
+  let bp = updatePhase(blueprint, phase.id, updatedPhase);
+  bp = resolveTaskCompletion(bp, phase.id, taskId);
+
+  return bp;
+}
+
+export function verifyGate(
+  blueprint: Blueprint,
+  phaseId: string,
+  gateIndex: number,
+  passed: boolean,
+  errorMsg?: string,
+): Blueprint {
+  const phase = blueprint.phases.find((p) => p.id === phaseId);
+  if (!phase) return blueprint;
+
+  const gate = phase.verification_gates[gateIndex];
+  if (!gate) return blueprint;
+
+  const now = new Date().toISOString();
+  const updatedGates = phase.verification_gates.map((g, i) =>
+    i === gateIndex
+      ? { ...g, passed, last_checked_at: now, error_message: errorMsg ?? null }
+      : g,
+  );
+
+  return updatePhase(blueprint, phaseId, { verification_gates: updatedGates });
+}
+
+export function advancePhase(blueprint: Blueprint): Blueprint {
+  const currentPhase = blueprint.phases.find((p) => p.id === blueprint.active_phase_id);
+  if (!currentPhase) return blueprint;
+
+  const allGatesPassed =
+    currentPhase.verification_gates.length === 0 ||
+    currentPhase.verification_gates.every((g) => g.passed);
+
+  if (!currentPhase.tasks.every(isTaskDone) || !allGatesPassed) return blueprint;
+
+  let bp = updatePhase(blueprint, currentPhase.id, {
+    status: "verified" as PhaseStatus,
+    completed_at: new Date().toISOString(),
+  });
+
+  const currentIdx = bp.phases.findIndex((p) => p.id === currentPhase.id);
+  const nextPhase = bp.phases[currentIdx + 1];
+
+  if (nextPhase) {
+    bp = {
+      ...bp,
+      active_phase_id: nextPhase.id,
+      active_task_id: null,
+    };
+    const next = getNextTask(bp);
+    if (next) {
+      bp = { ...bp, active_task_id: next.id };
+    }
+  } else {
+    bp = {
+      ...bp,
+      active_phase_id: null,
+      active_task_id: null,
+      status: "completed",
+    };
+  }
+
+  return bp;
+}
+
+export function getNextTask(blueprint: Blueprint): Task | null {
+  const allTasks = getAllTasks(blueprint.phases);
+
+  if (blueprint.active_phase_id) {
+    const phase = blueprint.phases.find((p) => p.id === blueprint.active_phase_id);
+    if (phase) {
+      const found = findNextTaskInPhase(phase, allTasks);
+      if (found) return found;
+    }
+  }
+
+  for (const phase of blueprint.phases) {
+    if (phase.status === "verified") continue;
+    const found = findNextTaskInPhase(phase, allTasks);
+    if (found) return found;
+  }
+
+  return null;
+}
+
+export function recomputeBlocked(blueprint: Blueprint): Blueprint {
+  const allTasks = getAllTasks(blueprint.phases);
+  const blockedIds = new Set(findBlockedTasks(allTasks));
+
+  return {
+    ...blueprint,
+    updated_at: new Date().toISOString(),
+    phases: blueprint.phases.map((phase) => ({
+      ...phase,
+      tasks: phase.tasks.map((task) => {
+        if (isTaskDone(task)) return task;
+        if (blockedIds.has(task.id) && task.status !== "blocked") {
+          return { ...task, status: "blocked" as TaskStatus };
+        }
+        if (!blockedIds.has(task.id) && task.status === "blocked") {
+          return { ...task, status: "pending" as TaskStatus };
+        }
+        return task;
+      }),
+    })),
+  };
+}
+
+export function createBlueprint(
+  id: string,
+  objective: string,
+  projectId: string,
+  phases: readonly Phase[],
+): Blueprint {
+  const now = new Date().toISOString();
+  let bp: Blueprint = {
+    id,
+    objective,
+    project_id: projectId,
+    status: "active",
+    created_at: now,
+    updated_at: now,
+    phases,
+    active_phase_id: phases[0]?.id ?? null,
+    active_task_id: null,
+  };
+  bp = recomputeBlocked(bp);
+  const next = getNextTask(bp);
+  if (next) {
+    bp = { ...bp, active_task_id: next.id };
+  }
+  return bp;
+}
+
+export function abandonBlueprint(blueprint: Blueprint): Blueprint {
+  return { ...blueprint, status: "abandoned", updated_at: new Date().toISOString() };
+}