pi-bmad-flow 0.1.0

package/extensions/bmad-orchestrator/files.ts

@@ -0,0 +1,49 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export function collectMarkdownFiles(dirPath: string): string[] {
+  if (!existsSync(dirPath)) return [];
+
+  const results: string[] = [];
+  for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectMarkdownFiles(fullPath));
+      continue;
+    }
+
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(fullPath);
+    }
+  }
+
+  return results.sort();
+}
+
+export function collectYamlFiles(dirPath: string): string[] {
+  if (!existsSync(dirPath)) return [];
+
+  const results: string[] = [];
+  for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectYamlFiles(fullPath));
+      continue;
+    }
+
+    if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
+      results.push(fullPath);
+    }
+  }
+
+  return results.sort();
+}
+
+export function isDirectory(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/extensions/bmad-orchestrator/gates.ts

@@ -0,0 +1,70 @@
+import type { BmadProjectState } from "./types.js";
+
+export interface GateDecision {
+  level: "lightweight" | "strong";
+  reason: string;
+  commands: string[];
+  evidenceFiles: string[];
+}
+
+function unique<T>(values: T[]): T[] {
+  return Array.from(new Set(values));
+}
+
+export function decideGate(state: BmadProjectState, hasTeaModule: boolean): GateDecision {
+  const story = state.activeStory ?? state.nextReadyStory ?? "";
+  const storyLower = story.toLowerCase();
+  const risky = /(auth|payment|migration|security|infra|public-api|billing|permissions)/.test(storyLower);
+  const nfrSensitive = /(security|payment|public-api|latency|performance|scale|compliance|audit)/.test(storyLower);
+  const uiHeavy = state.inventory.wdsPageSpecFiles.length > 0 && /(dashboard|checkout|profile|form|modal|screen|page|ui|ux)/.test(storyLower);
+  const evidenceFiles = [
+    ...state.inventory.teaReviewFiles,
+    ...state.inventory.teaTraceFiles,
+    ...state.inventory.teaNfrFiles,
+  ].slice(0, 6);
+
+  if (!hasTeaModule) {
+    return {
+      level: risky ? "strong" : "lightweight",
+      reason: risky
+        ? "Story appears high risk, but TEA is not installed. Fall back to code review only."
+        : "Routine scope and no TEA module installed.",
+      commands: [`bmad-code-review ${story}`.trim()],
+      evidenceFiles,
+    };
+  }
+
+  if (risky || nfrSensitive) {
+    return {
+      level: "strong",
+      reason: nfrSensitive
+        ? "Story is risk-sensitive and should go through TEA review, traceability, and NFR assessment."
+        : "Story appears high risk and should go through TEA review and traceability.",
+      commands: unique(
+        [
+          `bmad-code-review ${story}`.trim(),
+          "bmad-testarch-test-review",
+          "bmad-testarch-trace",
+          nfrSensitive ? "bmad-testarch-nfr" : "",
+        ].filter(Boolean),
+      ),
+      evidenceFiles,
+    };
+  }
+
+  if (uiHeavy) {
+    return {
+      level: "lightweight",
+      reason: "UI-heavy story. Use TEA test review plus traceability to keep UX flows covered.",
+      commands: unique([`bmad-code-review ${story}`.trim(), "bmad-testarch-test-review", "bmad-testarch-trace"]),
+      evidenceFiles,
+    };
+  }
+
+  return {
+    level: "lightweight",
+    reason: "Routine scope; standard review plus TEA test review is sufficient.",
+    commands: unique([`bmad-code-review ${story}`.trim(), "bmad-testarch-test-review"]),
+    evidenceFiles,
+  };
+}

package/extensions/bmad-orchestrator/index.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { detectBmadInstall, detectBmadProjectState } from "./detector.js";
+import { registerBmadCommands } from "./commands.js";
+import { decideNextAction } from "./router.js";
+import { registerBmadTool } from "./tool.js";
+import { clearBmadUi, refreshBmadUi } from "./ui.js";
+
+type BmadSessionSnapshot = {
+  event?: string;
+  storyKey?: string;
+  packetMode?: string;
+  gateLevel?: string;
+  nextCommand?: string;
+};
+
+function routeIntent(text: string): string | undefined {
+  const normalized = text.trim().toLowerCase();
+  if (!normalized || normalized.startsWith("/")) return undefined;
+
+  if (/^(what('?s| is) next|what should i do next|bmad next)$/.test(normalized)) return "/bmad-next";
+  if (/^(start (the )?next story|start next|begin next story|pick up the next story)$/.test(normalized)) return "/bmad-start";
+  if (/^(review this( story)?|review current story|run review)$/.test(normalized)) return "/bmad-review";
+  if (/^(gate this( story)?|run gate|quality gate this)$/.test(normalized)) return "/bmad-gate";
+  if (/^(what phase are we in|current phase|bmad phase)$/.test(normalized)) return "/bmad-phase";
+
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function latestBmadSnapshot(entries: unknown[]): BmadSessionSnapshot | undefined {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (!isRecord(entry)) continue;
+    if (entry.type !== "custom" || entry.customType !== "bmad-state") continue;
+    const data = entry.data;
+    if (!isRecord(data)) continue;
+
+    return {
+      event: typeof data.event === "string" ? data.event : undefined,
+      storyKey: typeof data.storyKey === "string" ? data.storyKey : undefined,
+      packetMode: typeof data.packetMode === "string" ? data.packetMode : undefined,
+      gateLevel: typeof data.gateLevel === "string" ? data.gateLevel : undefined,
+      nextCommand: typeof data.nextCommand === "string" ? data.nextCommand : undefined,
+    };
+  }
+
+  return undefined;
+}
+
+export default function bmadOrchestrator(pi: ExtensionAPI): void {
+  const cwd = process.cwd();
+  registerBmadCommands(pi, cwd);
+  registerBmadTool(pi, cwd);
+
+  pi.on("input", async (event) => {
+    if (event.source === "extension") return { action: "continue" };
+    const command = routeIntent(event.text);
+    if (!command) return { action: "continue" };
+    pi.sendUserMessage(command, { source: "extension" });
+    return { action: "handled" };
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const install = detectBmadInstall(cwd);
+    if (!install.installed) {
+      clearBmadUi(ctx);
+      ctx.ui.notify("pi-bmad-flow loaded. BMAD install not detected in this project.", "warning");
+      return;
+    }
+
+    const modules = install.modules.length > 0 ? install.modules.join(", ") : "none";
+    const state = detectBmadProjectState(cwd);
+    const next = decideNextAction(state);
+    refreshBmadUi(ctx, state, next);
+    ctx.ui.notify(`pi-bmad-flow ready. BMAD modules: ${modules}`, "info");
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    const install = detectBmadInstall(cwd);
+    if (!install.installed) return;
+    const state = detectBmadProjectState(cwd);
+    const next = decideNextAction(state);
+    refreshBmadUi(ctx, state, next);
+  });
+
+  pi.on("session_before_compact", async (event, ctx) => {
+    const install = detectBmadInstall(cwd);
+    if (!install.installed) return undefined;
+
+    const state = detectBmadProjectState(cwd);
+    const next = decideNextAction(state);
+    const snapshot = latestBmadSnapshot(ctx.sessionManager.getBranch() as unknown[]);
+
+    const summaryParts = [
+      `BMAD phase: ${state.phase}.`,
+      `Planning artifacts: PRD ${state.inventory.prdFiles.length}, UX ${state.inventory.uxFiles.length}, Architecture ${state.inventory.architectureFiles.length}, Epics ${state.inventory.epicFiles.length}.`,
+      `Delivery state: active story ${state.activeStory ?? "none"}, ready story ${state.nextReadyStory ?? "none"}.`,
+      `Recommended next action: ${next.command} (${next.summary}).`,
+    ];
+
+    if (snapshot?.storyKey) {
+      summaryParts.push(`Latest BMAD session event: ${snapshot.event ?? "unknown"} for story ${snapshot.storyKey}.`);
+    }
+    if (snapshot?.packetMode) {
+      summaryParts.push(`Current packet mode: ${snapshot.packetMode}.`);
+    }
+    if (snapshot?.gateLevel) {
+      summaryParts.push(`Latest gate level: ${snapshot.gateLevel}.`);
+    }
+
+    return {
+      compaction: {
+        summary: summaryParts.join(" "),
+        firstKeptEntryId: event.preparation.firstKeptEntryId,
+        tokensBefore: event.preparation.tokensBefore,
+        details: {
+          bmad: {
+            phase: state.phase,
+            activeStory: state.activeStory,
+            nextReadyStory: state.nextReadyStory,
+            nextCommand: next.command,
+            snapshot,
+          },
+        },
+      },
+    };
+  });
+}

package/extensions/bmad-orchestrator/packets.ts

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { BmadProjectState, StoryPacket } from "./types.js";
+
+const HIGH_RISK_TOKENS = ["auth", "payment", "migration", "security", "infra", "api", "billing", "permissions"];
+const UI_TOKENS = ["ui", "ux", "page", "screen", "dashboard", "form", "modal", "checkout", "profile", "onboarding", "button"];
+const STOP_WORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "into",
+  "user",
+  "story",
+  "epic",
+  "page",
+  "screen",
+  "flow",
+  "this",
+  "that",
+]);
+
+function tokenize(value: string): string[] {
+  return value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 3 && !STOP_WORDS.has(token));
+}
+
+function uniqueTokens(tokens: string[]): string[] {
+  return Array.from(new Set(tokens));
+}
+
+function overlapCount(left: string[], right: string[]): number {
+  const rightSet = new Set(right);
+  return left.filter((token) => rightSet.has(token)).length;
+}
+
+function resolveStoryFile(state: BmadProjectState, storyKey: string): string | undefined {
+  return state.inventory.storyFiles.find((file) => file.toLowerCase().includes(storyKey.toLowerCase()));
+}
+
+function storyContextTokens(state: BmadProjectState, storyKey: string): string[] {
+  const tokens = tokenize(storyKey);
+  const storyFile = resolveStoryFile(state, storyKey);
+  if (storyFile && existsSync(storyFile)) {
+    const content = readFileSync(storyFile, "utf8");
+    tokens.push(...tokenize(content));
+  }
+  return uniqueTokens(tokens);
+}
+
+function isUiRelevant(state: BmadProjectState, storyKey: string, tokens: string[]): boolean {
+  if (state.inventory.wdsPageSpecFiles.length === 0 && state.inventory.wdsDeliveryFiles.length === 0) {
+    return false;
+  }
+
+  if (tokens.some((token) => UI_TOKENS.includes(token))) {
+    return true;
+  }
+
+  const fileMatches = [...state.inventory.wdsPageSpecFiles, ...state.inventory.wdsDeliveryFiles].some((file) => {
+    const fileTokenSet = tokenize(file);
+    return overlapCount(tokens, fileTokenSet) > 0;
+  });
+
+  return fileMatches;
+}
+
+function scoreFile(state: BmadProjectState, storyKey: string, storyTokens: string[], file: string, mode: "lean" | "full"): number {
+  let score = overlapCount(storyTokens, tokenize(file)) * 8;
+
+  if (file.toLowerCase().includes(storyKey.toLowerCase())) score += 120;
+  if (state.inventory.projectContextFiles.includes(file)) score += 60;
+  if (state.inventory.architectureFiles.includes(file)) score += 55;
+  if (state.inventory.wdsDeliveryFiles.includes(file)) score += 70;
+  if (state.inventory.wdsPageSpecFiles.includes(file)) score += 60;
+  if (state.inventory.wdsScenarioFiles.includes(file)) score += 35;
+  if (state.inventory.wdsDesignSystemFiles.includes(file)) score += 25;
+  if (state.inventory.prdFiles.includes(file)) score += 20;
+  if (state.inventory.reviewFiles.includes(file)) score += 15;
+
+  if (mode === "full") {
+    if (state.inventory.teaTraceFiles.includes(file)) score += 25;
+    if (state.inventory.teaReviewFiles.includes(file)) score += 20;
+    if (state.inventory.teaNfrFiles.includes(file)) score += 15;
+  }
+
+  return score;
+}
+
+export function selectPacketMode(state: BmadProjectState): "lean" | "full" {
+  if (!state.hasImplementationArtifacts) return "full";
+  if (!state.nextReadyStory) return "full";
+  if (state.inventory.projectContextFiles.length === 0) return "full";
+
+  const key = state.nextReadyStory.toLowerCase();
+  if (HIGH_RISK_TOKENS.some((token) => key.includes(token))) return "full";
+
+  return "lean";
+}
+
+export function packetHint(mode: "lean" | "full"): string {
+  if (mode === "full") {
+    return "Use full packet mode: include deeper architecture and prior-story intelligence.";
+  }
+  return "Use lean packet mode: include current story, ACs, and minimal architecture context.";
+}
+
+function rankPacketFiles(state: BmadProjectState, storyKey: string, mode: "lean" | "full"): string[] {
+  const storyTokens = storyContextTokens(state, storyKey);
+  const storyMatch = resolveStoryFile(state, storyKey);
+  const uiRelevant = isUiRelevant(state, storyKey, storyTokens);
+  const baseCandidates = [
+    ...state.inventory.projectContextFiles,
+    ...state.inventory.architectureFiles,
+    ...state.inventory.prdFiles,
+    ...state.inventory.reviewFiles,
+  ];
+  const wdsCandidates = uiRelevant
+    ? [
+        ...state.inventory.wdsDeliveryFiles,
+        ...state.inventory.wdsPageSpecFiles,
+        ...state.inventory.wdsScenarioFiles,
+        ...state.inventory.wdsDesignSystemFiles,
+      ]
+    : [];
+  const teaCandidates = [...state.inventory.teaReviewFiles, ...state.inventory.teaTraceFiles, ...state.inventory.teaNfrFiles];
+  const ranked = [...baseCandidates, ...wdsCandidates, ...teaCandidates]
+    .filter((file, index, self) => self.indexOf(file) === index)
+    .map((file) => ({
+      file,
+      score: scoreFile(state, storyKey, storyTokens, file, mode),
+    }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => right.score - left.score)
+    .map((entry) => entry.file);
+
+  return storyMatch ? [storyMatch, ...ranked.filter((file) => file !== storyMatch)] : ranked;
+}
+
+export function buildStoryPacket(state: BmadProjectState, storyKey: string, mode: "lean" | "full"): StoryPacket {
+  const rankedFiles = rankPacketFiles(state, storyKey, mode);
+  const storyTokens = storyContextTokens(state, storyKey);
+  const uiRelevant = isUiRelevant(state, storyKey, storyTokens);
+  const files = mode === "lean" ? rankedFiles.slice(0, uiRelevant ? 6 : 4) : rankedFiles.slice(0, uiRelevant ? 12 : 10);
+  const notes: string[] = [];
+
+  if (uiRelevant) {
+    notes.push("This story appears UI-facing. Include WDS deliveries, page specs, and design-system references.");
+  }
+  if (state.inventory.projectContextFiles.length > 0) {
+    notes.push("Respect project-context conventions before changing architecture or naming patterns.");
+  }
+  if (mode === "full" && state.inventory.teaReviewFiles.length > 0) {
+    notes.push("Prior TEA review artifacts are available and should inform implementation and regression avoidance.");
+  }
+  if (mode === "full") {
+    notes.push("Full packet selected because the story is risky, early-stage, or missing stable project context.");
+  } else {
+    notes.push("Lean packet selected to minimize tokens while preserving local story fidelity.");
+  }
+
+  return {
+    storyKey,
+    mode,
+    files,
+    notes,
+    uiRelevant,
+    generatedAt: new Date().toISOString(),
+  };
+}

package/extensions/bmad-orchestrator/router.ts

@@ -0,0 +1,79 @@
+import type { BmadProjectState } from "./types.js";
+
+export interface NextAction {
+  summary: string;
+  command: string;
+  reason: string;
+}
+
+export function decideNextAction(state: BmadProjectState): NextAction {
+  if (state.inventory.prdFiles.length === 0) {
+    return {
+      summary: "PRD is missing.",
+      command: "bmad-create-prd",
+      reason: "Requirements need to exist before architecture, stories, or implementation can stay coherent.",
+    };
+  }
+
+  if (state.inventory.uxFiles.length === 0) {
+    return {
+      summary: "UX and WDS artifacts are missing.",
+      command: "bmad-create-ux-design",
+      reason: "Create UX direction before story breakdown so UI and flow decisions are explicit.",
+    };
+  }
+
+  if (state.inventory.architectureFiles.length === 0) {
+    return {
+      summary: "Architecture is missing.",
+      command: "bmad-create-architecture",
+      reason: "Technical decisions should be fixed before implementation planning.",
+    };
+  }
+
+  if (state.inventory.epicFiles.length === 0) {
+    return {
+      summary: "Epic and story breakdown is missing.",
+      command: "bmad-create-epics-and-stories",
+      reason: "Implementation should execute from approved stories, not raw planning docs.",
+    };
+  }
+
+  if (!state.hasSprintStatus) {
+    return {
+      summary: "Sprint tracking is not initialized.",
+      command: "bmad-sprint-planning",
+      reason: "Generate sprint-status.yaml before story execution.",
+    };
+  }
+
+  if (state.activeStory) {
+    return {
+      summary: `Story ${state.activeStory} is already in progress.`,
+      command: "bmad-dev-story",
+      reason: "Continue current implementation thread before starting new work.",
+    };
+  }
+
+  if (state.nextReadyStory) {
+    return {
+      summary: `Story ${state.nextReadyStory} is ready to start.`,
+      command: "/bmad-start",
+      reason: "Use orchestrator start flow to create isolated story execution.",
+    };
+  }
+
+  if (state.nextBacklogStory) {
+    return {
+      summary: `Backlog story ${state.nextBacklogStory} is next in queue.`,
+      command: "bmad-create-story",
+      reason: "Prepare the next story file before development starts.",
+    };
+  }
+
+  return {
+    summary: "No backlog or ready stories were found.",
+    command: "bmad-correct-course",
+    reason: "Re-plan or add stories before continuing.",
+  };
+}

package/extensions/bmad-orchestrator/sprint.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { SprintStatus } from "./types.js";
+
+const STORY_KEY_PATTERN = /^\d+-\d+-/;
+
+function parseStatusLine(line: string): { key: string; value: string } | undefined {
+  const match = line.match(/^\s{2}([a-zA-Z0-9._-]+):\s*([a-zA-Z0-9._-]+)\s*$/);
+  if (!match) return undefined;
+  return { key: match[1], value: match[2] };
+}
+
+export function loadSprintStatus(statusPath: string): SprintStatus | undefined {
+  if (!existsSync(statusPath)) return undefined;
+  const content = readFileSync(statusPath, "utf8");
+  const lines = content.split(/\r?\n/);
+
+  const developmentStatus: Record<string, string> = {};
+  const storyOrder: string[] = [];
+  let storyLocation: string | undefined;
+  let inDevelopmentStatus = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (!inDevelopmentStatus && !storyLocation) {
+      const storyLocationMatch = line.match(/^story_location:\s*["']?(.+?)["']?\s*$/);
+      if (storyLocationMatch) {
+        storyLocation = storyLocationMatch[1];
+      }
+    }
+
+    if (!inDevelopmentStatus) {
+      if (line === "development_status:") inDevelopmentStatus = true;
+      continue;
+    }
+
+    if (!line.startsWith("  ") && line.length > 0 && !line.startsWith("#")) break;
+    const parsed = parseStatusLine(line);
+    if (!parsed) continue;
+
+    developmentStatus[parsed.key] = parsed.value;
+    if (STORY_KEY_PATTERN.test(parsed.key)) storyOrder.push(parsed.key);
+  }
+
+  return { developmentStatus, storyOrder, storyLocation };
+}
+
+export function updateStoryStatus(statusPath: string, storyKey: string, nextStatus: string): boolean {
+  if (!existsSync(statusPath)) return false;
+  const content = readFileSync(statusPath, "utf8");
+  const lines = content.split(/\r?\n/);
+
+  let changed = false;
+  let inDevelopmentStatus = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!inDevelopmentStatus) {
+      if (line.trim() === "development_status:") inDevelopmentStatus = true;
+      continue;
+    }
+
+    if (!line.startsWith("  ") && line.trim() !== "") break;
+    const parsed = parseStatusLine(line);
+    if (!parsed || parsed.key !== storyKey) continue;
+    lines[i] = `  ${storyKey}: ${nextStatus}`;
+    changed = true;
+  }
+
+  if (!changed) return false;
+  writeFileSync(statusPath, `${lines.join("\n")}\n`, "utf8");
+  return true;
+}
+
+export function resolveStoryLocation(statusPath: string, sprint?: SprintStatus): string {
+  const fallbackDir = dirname(statusPath);
+  const location = sprint?.storyLocation?.trim();
+  if (!location) return fallbackDir;
+  if (location.startsWith("{")) return fallbackDir;
+  if (location.startsWith("/")) return location;
+  return resolve(dirname(statusPath), location);
+}

package/extensions/bmad-orchestrator/tool.ts

@@ -0,0 +1,78 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { detectBmadInstall, detectBmadProjectState } from "./detector.js";
+import { decideGate } from "./gates.js";
+import { buildStoryPacket, selectPacketMode } from "./packets.js";
+import { decideNextAction } from "./router.js";
+
+export function registerBmadTool(pi: ExtensionAPI, cwd: string): void {
+  pi.registerTool({
+    name: "bmad_orchestrator",
+    label: "BMAD Orchestrator",
+    description: "Inspect BMAD project state and compute next action, story packet, or gate plan from project artifacts.",
+    promptSnippet: "Inspect BMAD artifact state and compute the next action, story packet, or gate path without making the model rescan the filesystem.",
+    promptGuidelines: [
+      "Use this tool when the user asks what BMAD phase the project is in, what to do next, what packet a story needs, or which review and gate workflows should run.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["state", "next", "packet", "gate"] as const),
+      storyKey: Type.Optional(Type.String({ description: "Optional story key for packet generation." })),
+    }),
+    async execute(_toolCallId, params) {
+      const install = detectBmadInstall(cwd);
+      if (!install.installed) {
+        return {
+          content: [{ type: "text", text: "BMAD is not installed in this project." }],
+          details: { installed: false },
+        };
+      }
+
+      const state = detectBmadProjectState(cwd);
+
+      if (params.action === "state") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Phase ${state.phase}. Active story: ${state.activeStory ?? "none"}. Ready story: ${state.nextReadyStory ?? "none"}.`,
+            },
+          ],
+          details: { installed: true, state },
+        };
+      }
+
+      if (params.action === "next") {
+        const next = decideNextAction(state);
+        return {
+          content: [{ type: "text", text: `${next.command}: ${next.summary}` }],
+          details: { installed: true, next, state },
+        };
+      }
+
+      if (params.action === "packet") {
+        const storyKey = params.storyKey ?? state.activeStory ?? state.nextReadyStory;
+        if (!storyKey) {
+          return {
+            content: [{ type: "text", text: "No active or ready story was found for packet generation." }],
+            details: { installed: true, state },
+          };
+        }
+
+        const mode = selectPacketMode(state);
+        const packet = buildStoryPacket(state, storyKey, mode);
+        return {
+          content: [{ type: "text", text: `Packet ${packet.mode} for ${storyKey} with ${packet.files.length} files.` }],
+          details: { installed: true, packet, state },
+        };
+      }
+
+      const storyKey = params.storyKey ?? state.activeStory ?? state.nextReadyStory;
+      const gate = decideGate(state, install.modules.includes("tea"));
+      return {
+        content: [{ type: "text", text: `Gate ${gate.level} for ${storyKey ?? "current scope"}.` }],
+        details: { installed: true, storyKey, gate, state },
+      };
+    },
+  });
+}