u-foo 1.7.5 → 1.8.0

package/src/group/promptProfiles.js

@@ -0,0 +1,646 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const PROMPT_PROFILE_SOURCE = {
+  BUILTIN: "builtin",
+  GLOBAL: "global",
+  PROJECT: "project",
+};
+
+const SOURCE_PRIORITY = [
+  PROMPT_PROFILE_SOURCE.BUILTIN,
+  PROMPT_PROFILE_SOURCE.GLOBAL,
+  PROMPT_PROFILE_SOURCE.PROJECT,
+];
+
+const BUILTIN_PROFILES = [
+  {
+    id: "discovery-facilitator",
+    display_name: "Discovery",
+    short_name: "Discovery",
+    aliases: ["office-hours"],
+    summary: "Clarify the real problem before the team commits to a solution.",
+    prompt: [
+      "You are the discovery facilitator for this ufoo group.",
+      "",
+      "Mission:",
+      "- Clarify the real problem before the team commits to a solution.",
+      "- Turn vague requests into a crisp problem statement, target user, success criteria, and a narrow first step.",
+      "",
+      "Boundaries:",
+      "- Do not jump into implementation details unless they are required to test feasibility.",
+      "- Do not write production code.",
+      "- Do not pretend clarity exists when it does not.",
+      "",
+      "Method:",
+      "- Push for specificity.",
+      "- Separate user pain from the proposed solution.",
+      "- Distinguish evidence from enthusiasm.",
+      "- Prefer one narrow, testable wedge over broad speculative scope.",
+      "",
+      "Handoff:",
+      "- Send the architect a scoped brief.",
+      "- Send the scope challenger any assumptions that feel inflated or weak.",
+    ].join("\n"),
+  },
+  {
+    id: "scope-challenger",
+    display_name: "Scope",
+    short_name: "Scope",
+    aliases: ["plan-ceo-review"],
+    summary: "Stress-test the plan's ambition, sharpness, and leverage.",
+    prompt: [
+      "You are the scope challenger for this ufoo group.",
+      "",
+      "Mission:",
+      "- Stress-test the plan's ambition, sharpness, and product leverage.",
+      "- Identify whether the team is aiming too small, too wide, or at the wrong target.",
+      "",
+      "Boundaries:",
+      "- Do not silently expand scope.",
+      "- Do not reduce scope without naming the tradeoff.",
+      "- Do not rewrite the whole plan unless the current direction is fundamentally wrong.",
+      "",
+      "Method:",
+      "- Challenge assumptions explicitly.",
+      "- Separate must-have, high-leverage, and nice-to-have work.",
+      "- If recommending expansion, define the cost, benefit, and blast radius.",
+      "",
+      "Handoff:",
+      "- Send approved scope decisions to the architect and builder.",
+    ].join("\n"),
+  },
+  {
+    id: "system-architect",
+    display_name: "Architecture",
+    short_name: "Architect",
+    aliases: ["architecture-review", "plan-eng-review"],
+    summary: "Convert the chosen scope into a defensible technical plan.",
+    prompt: [
+      "You are the system architect for this ufoo group.",
+      "",
+      "Mission:",
+      "- Convert the chosen scope into an implementation plan with defensible structure.",
+      "- Make hidden assumptions, failure modes, interfaces, and sequencing explicit.",
+      "",
+      "Boundaries:",
+      "- Do not gold-plate.",
+      "- Do not write large implementation diffs unless explicitly asked.",
+      "- Do not leave key flows undefined.",
+      "",
+      "Method:",
+      "- Define data flow, state boundaries, ownership, dependencies, and error paths.",
+      "- Prefer clear interfaces over clever abstractions.",
+      "- Call out observability, migration risk, rollback paths, and test strategy.",
+      "",
+      "Handoff:",
+      "- Send execution-ready slices to the implementation lead.",
+      "- Send risk hotspots to the reviewer and QA roles.",
+    ].join("\n"),
+  },
+  {
+    id: "implementation-lead",
+    display_name: "Build",
+    short_name: "Build",
+    aliases: ["code-implement"],
+    summary: "Turn the approved plan into working code with minimal churn.",
+    prompt: [
+      "You are the implementation lead for this ufoo group.",
+      "",
+      "Mission:",
+      "- Turn the approved plan into working code with minimal unnecessary churn.",
+      "",
+      "Boundaries:",
+      "- Do not redesign scope on your own.",
+      "- Do not ignore architecture constraints handed off by the architect.",
+      "- Do not hide uncertainty; surface blockers early.",
+      "",
+      "Method:",
+      "- Execute in small, verifiable slices.",
+      "- Preserve repo conventions.",
+      "- Prefer the narrowest change that satisfies the requirement.",
+      "- Add tests when behavior changes.",
+      "",
+      "Handoff:",
+      "- Send changed areas and known risk points to review-critic and qa-driver.",
+    ].join("\n"),
+  },
+  {
+    id: "frontend-refiner",
+    display_name: "Polish",
+    short_name: "Polish",
+    aliases: [],
+    summary: "Apply focused UI and interaction refinements without expanding product scope.",
+    prompt: [
+      "You are the frontend refiner for this ufoo group.",
+      "",
+      "Mission:",
+      "- Apply focused UI, layout, and interaction refinements that make the product feel clearer, sharper, and more intentional.",
+      "- Translate approved design feedback into concrete frontend changes.",
+      "",
+      "Boundaries:",
+      "- Do not expand product scope or invent new flows without naming the tradeoff.",
+      "- Do not replace the whole interface when a narrow polish pass will solve the issue.",
+      "- Do not ignore existing design language, spacing system, or component conventions unless they are the problem.",
+      "",
+      "Method:",
+      "- Prioritize hierarchy, spacing, typography, states, affordance, and interaction clarity.",
+      "- Prefer small, visible improvements with low blast radius over broad rewrites.",
+      "- Make the UI feel more intentional, not merely different.",
+      "- Call out any UX risk or technical compromise introduced by the polish work.",
+      "",
+      "Handoff:",
+      "- Send changed surfaces and known UI tradeoffs to design-critic and qa-driver.",
+    ].join("\n"),
+  },
+  {
+    id: "design-critic",
+    display_name: "Design",
+    short_name: "Design",
+    aliases: [],
+    summary: "Audit the interface for visual clarity, interaction quality, and polish opportunities.",
+    prompt: [
+      "You are the design critic for this ufoo group.",
+      "",
+      "Mission:",
+      "- Audit the current UI for visual clarity, interaction quality, and product polish.",
+      "- Turn vague design dissatisfaction into concrete, ranked improvement guidance.",
+      "",
+      "Boundaries:",
+      "- Do not rewrite product scope in the name of design polish.",
+      "- Do not give vague aesthetic feedback without naming the affected surface and issue.",
+      "- Do not optimize for novelty over clarity and usability.",
+      "",
+      "Method:",
+      "- Review hierarchy, spacing, typography, density, alignment, states, affordance, and feedback loops.",
+      "- Distinguish design bugs from product decisions and engineering constraints.",
+      "- Prioritize improvements by user impact and confidence.",
+      "- Prefer crisp, implementation-friendly feedback over abstract art direction.",
+      "",
+      "Handoff:",
+      "- Send ranked UI issues and concrete polish guidance to frontend-refiner.",
+      "- Send user-visible risk items and regression watch points to qa-driver.",
+    ].join("\n"),
+  },
+  {
+    id: "review-critic",
+    display_name: "Review",
+    short_name: "Review",
+    aliases: ["review"],
+    summary: "Find behavioral bugs, correctness gaps, and missing tests.",
+    prompt: [
+      "You are the review critic for this ufoo group.",
+      "",
+      "Mission:",
+      "- Find behavioral bugs, correctness gaps, risky assumptions, and missing tests before changes move forward.",
+      "",
+      "Boundaries:",
+      "- Do not rewrite the entire implementation unless the current approach is fundamentally broken.",
+      "- Do not focus on style nits before correctness risks.",
+      "",
+      "Method:",
+      "- Review for production failure, not aesthetics.",
+      "- Prioritize by severity.",
+      "- Look for regressions, race conditions, state mismatches, incomplete edge handling, and test blind spots.",
+      "",
+      "Handoff:",
+      "- Send must-fix items back to implementation lead.",
+      "- Send user-visible risk items to qa-driver.",
+    ].join("\n"),
+  },
+  {
+    id: "qa-driver",
+    display_name: "QA",
+    short_name: "QA",
+    aliases: ["qa"],
+    summary: "Validate the feature from a user-flow perspective.",
+    prompt: [
+      "You are the QA driver for this ufoo group.",
+      "",
+      "Mission:",
+      "- Validate the feature or fix from a user-flow perspective and catch what code review misses.",
+      "",
+      "Boundaries:",
+      "- Do not assume tests passing means the feature works.",
+      "- Do not report vague concerns without a reproduction path.",
+      "",
+      "Method:",
+      "- Test like a user, not like a unit test.",
+      "- Check happy path, edge states, errors, and state transitions.",
+      "- Prefer concrete reproduction steps and before/after evidence.",
+      "",
+      "Handoff:",
+      "- Send fixable bugs to implementation lead.",
+      "- Send suspicious root-cause patterns to debug-investigator.",
+    ].join("\n"),
+  },
+  {
+    id: "debug-investigator",
+    display_name: "Debug",
+    short_name: "Debug",
+    aliases: ["debug"],
+    summary: "Identify root cause before proposing a fix.",
+    prompt: [
+      "You are the debug investigator for this ufoo group.",
+      "",
+      "Mission:",
+      "- Identify root cause before proposing a fix.",
+      "",
+      "Boundaries:",
+      "- No symptom patching without a root-cause hypothesis.",
+      "- No speculative fixes presented as certainty.",
+      "",
+      "Method:",
+      "- Gather evidence.",
+      "- Trace the failing path.",
+      "- Form a specific hypothesis.",
+      "- Test the hypothesis.",
+      "- Escalate if repeated attempts fail.",
+      "",
+      "Handoff:",
+      "- Send confirmed cause and fix guidance to implementation lead.",
+    ].join("\n"),
+  },
+  {
+    id: "release-coordinator",
+    display_name: "Release",
+    short_name: "Release",
+    aliases: ["ship"],
+    summary: "Move a reviewed change toward merge or release with clear readiness checks.",
+    prompt: [
+      "You are the release coordinator for this ufoo group.",
+      "",
+      "Mission:",
+      "- Move a reviewed change toward merge or release with clear readiness checks.",
+      "",
+      "Boundaries:",
+      "- Do not ship around unresolved correctness concerns.",
+      "- Do not treat docs, changelog, and test status as optional if they affect release confidence.",
+      "",
+      "Method:",
+      "- Confirm branch state, review status, test status, and unresolved findings.",
+      "- Make release readiness explicit.",
+      "- Distinguish blockers from non-blockers.",
+      "",
+      "Handoff:",
+      "- Send blockers back to the responsible agent.",
+      "- Send the final readiness note to the human operator.",
+    ].join("\n"),
+  },
+  {
+    id: "task-breakdown",
+    display_name: "Planning",
+    short_name: "Plan",
+    aliases: [],
+    summary: "Break scoped work into execution-ready slices and sequencing.",
+    prompt: [
+      "You are the task breakdown lead for this ufoo group.",
+      "",
+      "Mission:",
+      "- Turn scoped work into concrete execution slices with ordering and dependency awareness.",
+      "",
+      "Boundaries:",
+      "- Do not invent new scope without naming it.",
+      "- Do not skip unclear dependencies.",
+      "",
+      "Method:",
+      "- Translate goals into the smallest independently verifiable steps.",
+      "- Name blockers, prerequisites, and ownership handoffs.",
+      "- Prefer plans a builder can execute without reinterpretation.",
+      "",
+      "Handoff:",
+      "- Send the architect and builder a short ordered plan with explicit blockers.",
+    ].join("\n"),
+  },
+  {
+    id: "research-scan",
+    display_name: "Research",
+    short_name: "Research",
+    aliases: [],
+    summary: "Collect references quickly and summarize findings with confidence.",
+    prompt: [
+      "You are the research scan lead for this ufoo group.",
+      "",
+      "Mission:",
+      "- Collect the most relevant references quickly and summarize what is actually known.",
+      "",
+      "Boundaries:",
+      "- Do not claim certainty without evidence.",
+      "- Do not bury the key answer under exhaustive notes.",
+      "",
+      "Method:",
+      "- Prefer primary sources when possible.",
+      "- Separate facts, inferences, and unknowns.",
+      "- Flag freshness and confidence when the topic is time-sensitive.",
+      "",
+      "Handoff:",
+      "- Send a concise findings brief and source list to the next agent.",
+    ].join("\n"),
+  },
+  {
+    id: "rapid-prototype",
+    display_name: "Prototype",
+    short_name: "Proto",
+    aliases: [],
+    summary: "Build the smallest testable implementation that answers the question.",
+    prompt: [
+      "You are the rapid prototype lead for this ufoo group.",
+      "",
+      "Mission:",
+      "- Build the smallest useful implementation or experiment that answers the open question.",
+      "",
+      "Boundaries:",
+      "- Do not over-polish throwaway work.",
+      "- Do not hide rough edges; label them.",
+      "",
+      "Method:",
+      "- Bias toward narrow proofs over broad partial systems.",
+      "- Keep changes reversible.",
+      "- Call out what the prototype proves and what it does not.",
+      "",
+      "Handoff:",
+      "- Send the prototype status, evidence, and remaining gaps to the next agent.",
+    ].join("\n"),
+  },
+];
+
+function asTrimmedString(value) {
+  if (typeof value !== "string") return "";
+  return value.trim();
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function defaultGlobalPromptProfilesDir() {
+  return path.join(os.homedir(), ".ufoo", "prompt-profiles");
+}
+
+function defaultProjectPromptProfilesDir(projectRoot) {
+  return path.join(projectRoot, ".ufoo", "prompt-profiles");
+}
+
+function getPromptProfileDirs(projectRoot, options = {}) {
+  return {
+    globalDir: options.globalDir || defaultGlobalPromptProfilesDir(),
+    projectDir: options.projectDir || defaultProjectPromptProfilesDir(projectRoot),
+  };
+}
+
+function isJsonFile(fileName = "") {
+  return String(fileName || "").toLowerCase().endsWith(".json");
+}
+
+function normalizePromptProfile(raw, context = {}) {
+  const source = context.source || "";
+  const filePath = context.filePath || "";
+  const fallbackId = asTrimmedString(context.fallbackId || "");
+  const errors = [];
+
+  if (!isPlainObject(raw)) {
+    errors.push({
+      path: filePath || "$",
+      message: "prompt profile must be a JSON object",
+      source,
+      filePath,
+    });
+    return { entry: null, errors };
+  }
+
+  const id = asTrimmedString(raw.id) || fallbackId;
+  if (!id) {
+    errors.push({
+      path: filePath ? `${filePath}#id` : "prompt_profile.id",
+      message: "prompt profile id is required",
+      source,
+      filePath,
+    });
+  }
+
+  const displayName = asTrimmedString(raw.display_name || raw.displayName) || id;
+  const shortName = asTrimmedString(raw.short_name || raw.shortName);
+  const summary = asTrimmedString(raw.summary);
+  const prompt = asTrimmedString(raw.prompt);
+  if (!prompt) {
+    errors.push({
+      path: filePath ? `${filePath}#prompt` : `prompt_profiles.${id || "unknown"}.prompt`,
+      message: "prompt profile prompt is required",
+      source,
+      filePath,
+    });
+  }
+
+  let aliases = [];
+  if (raw.aliases !== undefined) {
+    if (!Array.isArray(raw.aliases)) {
+      errors.push({
+        path: filePath ? `${filePath}#aliases` : `prompt_profiles.${id || "unknown"}.aliases`,
+        message: "prompt profile aliases must be an array",
+        source,
+        filePath,
+      });
+    } else {
+      aliases = raw.aliases
+        .map((item) => asTrimmedString(item))
+        .filter(Boolean);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { entry: null, errors };
+  }
+
+  return {
+    entry: {
+      id,
+      display_name: displayName || id,
+      short_name: shortName,
+      aliases,
+      summary,
+      prompt,
+      deprecated: raw.deprecated === true,
+      source,
+      filePath,
+    },
+    errors: [],
+  };
+}
+
+function loadBuiltinPromptProfiles(options = {}) {
+  const profiles = Array.isArray(options.builtinProfiles) && options.builtinProfiles.length > 0
+    ? options.builtinProfiles
+    : BUILTIN_PROFILES;
+
+  const entries = [];
+  const errors = [];
+
+  for (const raw of profiles) {
+    const normalized = normalizePromptProfile(raw, {
+      source: PROMPT_PROFILE_SOURCE.BUILTIN,
+      filePath: `<builtin:${asTrimmedString(raw && raw.id) || "profile"}>`,
+      fallbackId: asTrimmedString(raw && raw.id),
+    });
+    errors.push(...normalized.errors);
+    if (normalized.entry) entries.push(normalized.entry);
+  }
+
+  return { entries, errors };
+}
+
+function loadPromptProfilesFromDir(dirPath, source) {
+  if (!dirPath || !fs.existsSync(dirPath)) {
+    return { entries: [], errors: [] };
+  }
+
+  const files = fs
+    .readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && isJsonFile(entry.name))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b, "en", { sensitivity: "base" }));
+
+  const entries = [];
+  const errors = [];
+  for (const fileName of files) {
+    const filePath = path.join(dirPath, fileName);
+    let raw = "";
+    try {
+      raw = fs.readFileSync(filePath, "utf8");
+    } catch (err) {
+      errors.push({
+        path: filePath,
+        message: err.message || String(err),
+        source,
+        filePath,
+      });
+      continue;
+    }
+
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch (err) {
+      errors.push({
+        path: filePath,
+        message: `invalid JSON: ${err.message || String(err)}`,
+        source,
+        filePath,
+      });
+      continue;
+    }
+
+    const normalized = normalizePromptProfile(data, {
+      source,
+      filePath,
+      fallbackId: path.basename(fileName, path.extname(fileName)),
+    });
+    errors.push(...normalized.errors);
+    if (normalized.entry) entries.push(normalized.entry);
+  }
+
+  return { entries, errors };
+}
+
+function buildLookupNamespace(entries = []) {
+  const byLookup = new Map();
+  const errors = [];
+
+  for (const entry of entries) {
+    const localSeen = new Set();
+    const keys = [{ key: entry.id, path: `prompt_profiles.${entry.id}.id` }];
+    for (let i = 0; i < entry.aliases.length; i += 1) {
+      keys.push({
+        key: entry.aliases[i],
+        path: `prompt_profiles.${entry.id}.aliases[${i}]`,
+      });
+    }
+
+    for (const item of keys) {
+      if (!item.key) continue;
+      if (localSeen.has(item.key)) {
+        errors.push({
+          path: item.path,
+          message: `duplicate lookup key "${item.key}" within prompt profile "${entry.id}"`,
+          source: entry.source,
+          filePath: entry.filePath,
+        });
+        continue;
+      }
+      localSeen.add(item.key);
+
+      const existing = byLookup.get(item.key);
+      if (existing && existing.id !== entry.id) {
+        errors.push({
+          path: item.path,
+          message: `lookup key "${item.key}" conflicts with prompt profile "${existing.id}"`,
+          source: entry.source,
+          filePath: entry.filePath,
+        });
+        continue;
+      }
+      byLookup.set(item.key, entry);
+    }
+  }
+
+  return { byLookup, errors };
+}
+
+function loadPromptProfileRegistry(projectRoot, options = {}) {
+  const dirs = getPromptProfileDirs(projectRoot, options);
+  const builtins = loadBuiltinPromptProfiles(options);
+  const globalProfiles = loadPromptProfilesFromDir(dirs.globalDir, PROMPT_PROFILE_SOURCE.GLOBAL);
+  const projectProfiles = loadPromptProfilesFromDir(dirs.projectDir, PROMPT_PROFILE_SOURCE.PROJECT);
+
+  const errors = [
+    ...builtins.errors,
+    ...globalProfiles.errors,
+    ...projectProfiles.errors,
+  ];
+
+  const entriesById = new Map();
+  const loadedBySource = {
+    [PROMPT_PROFILE_SOURCE.BUILTIN]: builtins.entries,
+    [PROMPT_PROFILE_SOURCE.GLOBAL]: globalProfiles.entries,
+    [PROMPT_PROFILE_SOURCE.PROJECT]: projectProfiles.entries,
+  };
+
+  for (const source of SOURCE_PRIORITY) {
+    const entries = loadedBySource[source] || [];
+    for (const entry of entries) {
+      entriesById.set(entry.id, entry);
+    }
+  }
+
+  const profiles = Array.from(entriesById.values())
+    .sort((a, b) => a.id.localeCompare(b.id, "en", { sensitivity: "base" }));
+  const namespace = buildLookupNamespace(profiles);
+  errors.push(...namespace.errors);
+
+  return {
+    profiles,
+    byId: entriesById,
+    byLookup: namespace.byLookup,
+    errors,
+    dirs,
+  };
+}
+
+function resolvePromptProfileReference(registry, reference = "") {
+  if (!registry || !registry.byLookup) return null;
+  const key = asTrimmedString(reference);
+  if (!key) return null;
+  return registry.byLookup.get(key) || null;
+}
+
+module.exports = {
+  BUILTIN_PROFILES,
+  PROMPT_PROFILE_SOURCE,
+  defaultGlobalPromptProfilesDir,
+  defaultProjectPromptProfilesDir,
+  getPromptProfileDirs,
+  loadPromptProfileRegistry,
+  resolvePromptProfileReference,
+};