stagent 0.1.0

package/src/lib/workflows/blueprints/builtins/meal-planning.yaml

@@ -0,0 +1,73 @@
+id: meal-planning
+name: Meal Planning
+description: Assess goals, create a weekly meal plan, and generate a shopping list
+version: "1.0.0"
+domain: personal
+tags: [health, nutrition, meal-prep, shopping]
+pattern: sequence
+estimatedDuration: "5-10 min"
+difficulty: beginner
+author: stagent
+
+variables:
+  - id: goal
+    type: select
+    label: Health Goal
+    description: Primary nutrition goal
+    required: true
+    default: balanced
+    options:
+      - { value: balanced, label: "Balanced eating" }
+      - { value: weight-loss, label: "Weight loss" }
+      - { value: muscle-gain, label: "Muscle gain" }
+      - { value: energy, label: "More energy" }
+  - id: restrictions
+    type: text
+    label: Dietary Restrictions
+    description: Allergies, preferences, or restrictions
+    required: false
+    placeholder: "e.g., vegetarian, gluten-free, no nuts"
+  - id: days
+    type: number
+    label: Days to Plan
+    description: Number of days to plan meals for
+    required: true
+    default: 7
+    min: 1
+    max: 14
+
+steps:
+  - name: Goal Assessment
+    profileId: health-fitness-coach
+    promptTemplate: |
+      Assess nutritional needs for the goal: {{goal}}
+      {{#if restrictions}}Dietary restrictions: {{restrictions}}{{/if}}
+      Planning for {{days}} days.
+
+      Determine: daily calorie target, macro breakdown (protein/carbs/fat),
+      key nutrients to focus on, and foods to prioritize or avoid.
+    requiresApproval: false
+    expectedOutput: nutrition-plan
+
+  - name: Meal Plan Creation
+    profileId: health-fitness-coach
+    promptTemplate: |
+      Create a {{days}}-day meal plan for the goal: {{goal}}
+      {{#if restrictions}}Restrictions: {{restrictions}}{{/if}}
+
+      Use the nutritional assessment from the previous step.
+      Include breakfast, lunch, dinner, and snacks for each day.
+      Vary meals to avoid repetition. Include prep time estimates.
+    requiresApproval: false
+    expectedOutput: meal-plan
+
+  - name: Shopping List
+    profileId: document-writer
+    promptTemplate: |
+      Generate a complete shopping list from the {{days}}-day meal plan.
+
+      Organize by grocery section (produce, proteins, dairy, pantry, frozen).
+      Combine ingredients across meals to minimize waste.
+      Include quantities and optional budget-friendly substitutions.
+    requiresApproval: true
+    expectedOutput: shopping-list

package/src/lib/workflows/blueprints/builtins/product-research.yaml

@@ -0,0 +1,72 @@
+id: product-research
+name: Product Research
+description: Research options, compare reviews, and get a purchase recommendation
+version: "1.0.0"
+domain: personal
+tags: [shopping, comparison, reviews, recommendation]
+pattern: sequence
+estimatedDuration: "5-15 min"
+difficulty: beginner
+author: stagent
+
+variables:
+  - id: product
+    type: text
+    label: Product Category
+    description: What you're looking to buy
+    required: true
+    placeholder: "e.g., wireless noise-canceling headphones"
+  - id: budget
+    type: text
+    label: Budget Range
+    description: How much you want to spend
+    required: false
+    placeholder: "e.g., $100-300"
+  - id: priorities
+    type: textarea
+    label: Priorities
+    description: What matters most to you
+    required: false
+    placeholder: "e.g., comfort for long flights, good microphone, ANC quality"
+
+steps:
+  - name: Research Options
+    profileId: researcher
+    promptTemplate: |
+      Research the best options for: {{product}}
+      {{#if budget}}Budget: {{budget}}{{/if}}
+      {{#if priorities}}Priorities: {{priorities}}{{/if}}
+
+      Find the top 5-8 options currently available. For each, note:
+      key specs, price, standout features, and known issues.
+    requiresApproval: false
+    expectedOutput: product-list
+
+  - name: Compare Reviews
+    profileId: shopping-assistant
+    promptTemplate: |
+      Compare the top options for: {{product}}
+      {{#if budget}}Budget: {{budget}}{{/if}}
+      {{#if priorities}}Priorities: {{priorities}}{{/if}}
+
+      Analyze reviews and ratings for each option from the research step.
+      Create a comparison table with: price, rating, pros, cons, best for.
+      Identify any deal-breakers or red flags.
+    requiresApproval: false
+    expectedOutput: comparison-table
+
+  - name: Recommendation
+    profileId: shopping-assistant
+    promptTemplate: |
+      Provide a final purchase recommendation for: {{product}}
+      {{#if budget}}Budget: {{budget}}{{/if}}
+      {{#if priorities}}Priorities: {{priorities}}{{/if}}
+
+      Based on the research and comparison, recommend:
+      1. Best overall pick
+      2. Best value pick
+      3. Premium pick (if applicable)
+
+      Explain why each is recommended and who it's best for.
+    requiresApproval: true
+    expectedOutput: recommendation

package/src/lib/workflows/blueprints/builtins/research-report.yaml

@@ -0,0 +1,77 @@
+id: research-report
+name: Research Report
+description: Multi-step research pipeline — gather sources, analyze data, write structured report
+version: "1.0.0"
+domain: work
+tags: [research, analysis, report, writing]
+pattern: sequence
+estimatedDuration: "15-30 min"
+difficulty: intermediate
+author: stagent
+
+variables:
+  - id: topic
+    type: text
+    label: Research Topic
+    description: The main topic or question to research
+    required: true
+    placeholder: "e.g., Impact of AI on healthcare diagnostics"
+  - id: depth
+    type: select
+    label: Research Depth
+    description: How thorough the research should be
+    required: true
+    default: standard
+    options:
+      - { value: quick, label: "Quick overview (5 sources)" }
+      - { value: standard, label: "Standard (10-15 sources)" }
+      - { value: deep, label: "Deep dive (20+ sources)" }
+  - id: audience
+    type: text
+    label: Target Audience
+    description: Who will read this report
+    required: false
+    default: "General technical audience"
+  - id: includeData
+    type: boolean
+    label: Include Data Analysis
+    description: Whether to include statistical analysis section
+    required: false
+    default: false
+
+steps:
+  - name: Research Gathering
+    profileId: researcher
+    promptTemplate: |
+      Research the following topic thoroughly: {{topic}}
+
+      Depth level: {{depth}}
+      {{#if audience}}Target audience: {{audience}}{{/if}}
+
+      Find credible sources, extract key findings, and compile a structured summary
+      with full citations. Focus on recent publications (last 2 years).
+    requiresApproval: false
+    expectedOutput: structured-summary
+
+  - name: Data Analysis
+    profileId: data-analyst
+    promptTemplate: |
+      Analyze the research findings from the previous step about: {{topic}}
+
+      Identify key trends, statistical patterns, and data-driven insights.
+      Create summary statistics and recommend visualization approaches.
+    requiresApproval: false
+    expectedOutput: analysis-report
+    condition: "{{includeData}}"
+
+  - name: Report Writing
+    profileId: document-writer
+    promptTemplate: |
+      Write a comprehensive research report on: {{topic}}
+
+      {{#if audience}}Target audience: {{audience}}{{/if}}
+
+      Use the research findings and {{#if includeData}}data analysis{{/if}} from previous steps.
+      Structure with: Executive Summary, Key Findings, {{#if includeData}}Data Analysis, {{/if}}Recommendations, References.
+    requiresApproval: true
+    expectedOutput: markdown-report

package/src/lib/workflows/blueprints/builtins/sprint-planning.yaml

@@ -0,0 +1,77 @@
+id: sprint-planning
+name: Sprint Planning
+description: Decompose epics into tasks, estimate effort, and create a sprint schedule
+version: "1.0.0"
+domain: work
+tags: [planning, estimation, sprint, project-management]
+pattern: sequence
+estimatedDuration: "10-20 min"
+difficulty: beginner
+author: stagent
+
+variables:
+  - id: goal
+    type: textarea
+    label: Sprint Goal
+    description: What this sprint should achieve
+    required: true
+    placeholder: "e.g., Implement user authentication and profile management"
+  - id: duration
+    type: select
+    label: Sprint Duration
+    description: How long is this sprint
+    required: true
+    default: 2-weeks
+    options:
+      - { value: 1-week, label: "1 week" }
+      - { value: 2-weeks, label: "2 weeks" }
+      - { value: 3-weeks, label: "3 weeks" }
+  - id: teamSize
+    type: number
+    label: Team Size
+    description: Number of developers
+    required: false
+    default: 1
+    min: 1
+    max: 20
+
+steps:
+  - name: Epic Decomposition
+    profileId: project-manager
+    promptTemplate: |
+      Decompose the following sprint goal into actionable tasks:
+
+      Goal: {{goal}}
+      Sprint duration: {{duration}}
+      {{#if teamSize}}Team size: {{teamSize}}{{/if}}
+
+      Break down into epics, then into individual tasks. Each task should be
+      independently completable in 1-3 days. Include dependencies between tasks.
+    requiresApproval: false
+    expectedOutput: task-list
+
+  - name: Estimation
+    profileId: project-manager
+    promptTemplate: |
+      Estimate the effort for each task from the decomposition of: {{goal}}
+
+      Sprint duration: {{duration}}
+      {{#if teamSize}}Team size: {{teamSize}}{{/if}}
+
+      For each task, provide: story points (1/2/3/5/8), time estimate, risk level,
+      and any blockers. Flag tasks that don't fit in the sprint.
+    requiresApproval: false
+    expectedOutput: estimation-report
+
+  - name: Sprint Schedule
+    profileId: project-manager
+    promptTemplate: |
+      Create a sprint schedule from the estimated tasks for: {{goal}}
+
+      Sprint duration: {{duration}}
+      {{#if teamSize}}Team size: {{teamSize}}{{/if}}
+
+      Sequence tasks respecting dependencies. Identify the critical path.
+      Produce a day-by-day schedule with task assignments and milestones.
+    requiresApproval: true
+    expectedOutput: schedule

package/src/lib/workflows/blueprints/builtins/travel-planning.yaml

@@ -0,0 +1,80 @@
+id: travel-planning
+name: Travel Planning
+description: Research destinations, find deals, and build a complete itinerary
+version: "1.0.0"
+domain: personal
+tags: [travel, itinerary, budget, booking]
+pattern: sequence
+estimatedDuration: "10-20 min"
+difficulty: beginner
+author: stagent
+
+variables:
+  - id: destination
+    type: text
+    label: Destination
+    description: Where you want to travel
+    required: true
+    placeholder: "e.g., Tokyo, Japan for 10 days"
+  - id: dates
+    type: text
+    label: Travel Dates
+    description: When you plan to travel
+    required: true
+    placeholder: "e.g., March 15-25, 2026"
+  - id: budget
+    type: select
+    label: Budget Level
+    description: Overall budget per person
+    required: true
+    default: moderate
+    options:
+      - { value: budget, label: "Budget ($50-100/day)" }
+      - { value: moderate, label: "Moderate ($100-250/day)" }
+      - { value: luxury, label: "Luxury ($250+/day)" }
+  - id: interests
+    type: textarea
+    label: Interests
+    description: Activities and experiences you enjoy
+    required: false
+    placeholder: "e.g., food, temples, hiking, nightlife"
+
+steps:
+  - name: Destination Research
+    profileId: travel-planner
+    promptTemplate: |
+      Research travel to: {{destination}}
+      Dates: {{dates}}
+      Budget: {{budget}}
+      {{#if interests}}Interests: {{interests}}{{/if}}
+
+      Cover: best neighborhoods to stay, transport options, must-see attractions,
+      local customs and tips, weather expectations, and safety considerations.
+    requiresApproval: false
+    expectedOutput: research-summary
+
+  - name: Deal Finding
+    profileId: shopping-assistant
+    promptTemplate: |
+      Find the best travel deals for: {{destination}}
+      Dates: {{dates}}
+      Budget: {{budget}}
+
+      Research: flight options, accommodation deals, activity passes,
+      and money-saving tips. Compare prices across budget levels.
+    requiresApproval: false
+    expectedOutput: deal-list
+
+  - name: Itinerary Building
+    profileId: travel-planner
+    promptTemplate: |
+      Create a detailed day-by-day itinerary for: {{destination}}
+      Dates: {{dates}}
+      Budget: {{budget}}
+      {{#if interests}}Interests: {{interests}}{{/if}}
+
+      Use the research and deals from previous steps. Include:
+      daily schedule, meal recommendations, transport between activities,
+      estimated costs per day, and backup options for bad weather.
+    requiresApproval: true
+    expectedOutput: itinerary

package/src/lib/workflows/blueprints/instantiator.ts

@@ -0,0 +1,131 @@
+import { db } from "@/lib/db";
+import { workflows } from "@/lib/db/schema";
+import { getBlueprint } from "./registry";
+import { resolveTemplate, evaluateCondition } from "./template";
+import type { BlueprintVariable, WorkflowBlueprint } from "./types";
+import type { WorkflowStep } from "../types";
+
+interface InstantiateResult {
+  workflowId: string;
+  name: string;
+  stepsCount: number;
+  skippedSteps: string[];
+}
+
+/**
+ * Instantiate a blueprint into a concrete draft workflow.
+ *
+ * 1. Validate all required variables
+ * 2. Resolve {{variable}} in prompt templates
+ * 3. Process {{#if}} conditional blocks
+ * 4. Evaluate step conditions, filter skipped steps
+ * 5. Create workflow with blueprintId lineage
+ */
+export async function instantiateBlueprint(
+  blueprintId: string,
+  variables: Record<string, unknown>,
+  projectId?: string
+): Promise<InstantiateResult> {
+  const blueprint = getBlueprint(blueprintId);
+  if (!blueprint) {
+    throw new Error(`Blueprint "${blueprintId}" not found`);
+  }
+
+  // Validate required variables
+  validateVariables(blueprint.variables, variables);
+
+  // Apply defaults for unset optional variables
+  const resolvedVars = applyDefaults(blueprint.variables, variables);
+
+  // Process steps: resolve templates, evaluate conditions
+  const resolvedSteps: WorkflowStep[] = [];
+  const skippedSteps: string[] = [];
+
+  for (const step of blueprint.steps) {
+    // Check condition — skip if evaluates to falsy
+    if (step.condition && !evaluateCondition(step.condition, resolvedVars)) {
+      skippedSteps.push(step.name);
+      continue;
+    }
+
+    const resolvedPrompt = resolveTemplate(step.promptTemplate, resolvedVars);
+
+    resolvedSteps.push({
+      id: crypto.randomUUID(),
+      name: step.name,
+      prompt: resolvedPrompt,
+      requiresApproval: step.requiresApproval,
+      agentProfile: step.profileId,
+    });
+  }
+
+  if (resolvedSteps.length === 0) {
+    throw new Error("All steps were skipped by conditions — at least one step must remain");
+  }
+
+  // Create the workflow
+  const workflowId = crypto.randomUUID();
+  const now = new Date();
+  const workflowName = resolveTemplate(
+    `${blueprint.name}: {{${blueprint.variables[0]?.id ?? "topic"}}}`,
+    resolvedVars
+  ) || blueprint.name;
+
+  const definition = {
+    pattern: blueprint.pattern,
+    steps: resolvedSteps,
+    _blueprintId: blueprintId,
+  };
+
+  await db.insert(workflows).values({
+    id: workflowId,
+    projectId: projectId ?? null,
+    name: workflowName.slice(0, 100),
+    definition: JSON.stringify(definition),
+    status: "draft",
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  return {
+    workflowId,
+    name: workflowName,
+    stepsCount: resolvedSteps.length,
+    skippedSteps,
+  };
+}
+
+function validateVariables(
+  definitions: BlueprintVariable[],
+  provided: Record<string, unknown>
+): void {
+  const errors: string[] = [];
+
+  for (const def of definitions) {
+    if (def.required) {
+      const value = provided[def.id];
+      if (value === undefined || value === null || value === "") {
+        errors.push(`"${def.label}" is required`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Missing required variables: ${errors.join(", ")}`);
+  }
+}
+
+function applyDefaults(
+  definitions: BlueprintVariable[],
+  provided: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...provided };
+
+  for (const def of definitions) {
+    if (result[def.id] === undefined && def.default !== undefined) {
+      result[def.id] = def.default;
+    }
+  }
+
+  return result;
+}

package/src/lib/workflows/blueprints/registry.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { BlueprintSchema } from "@/lib/validators/blueprint";
+import { getStagentBlueprintsDir } from "@/lib/utils/stagent-paths";
+import type { WorkflowBlueprint } from "./types";
+
+// Use fileURLToPath for ESM compatibility in Next.js
+const BUILTINS_DIR = path.resolve(
+  import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname),
+  "builtins"
+);
+
+const USER_BLUEPRINTS_DIR = getStagentBlueprintsDir();
+
+let blueprintCache: Map<string, WorkflowBlueprint> | null = null;
+
+function scanDirectory(
+  dir: string,
+  isBuiltin: boolean
+): Map<string, WorkflowBlueprint> {
+  const blueprints = new Map<string, WorkflowBlueprint>();
+
+  if (!fs.existsSync(dir)) return blueprints;
+
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+
+    try {
+      const content = fs.readFileSync(path.join(dir, file), "utf-8");
+      const parsed = yaml.load(content);
+      const result = BlueprintSchema.safeParse(parsed);
+
+      if (!result.success) {
+        console.warn(
+          `[blueprints] Invalid blueprint ${file}:`,
+          result.error.issues.map((i) => i.message).join(", ")
+        );
+        continue;
+      }
+
+      blueprints.set(result.data.id, { ...result.data, isBuiltin });
+    } catch (err) {
+      console.warn(`[blueprints] Error loading ${file}:`, err);
+    }
+  }
+
+  return blueprints;
+}
+
+function loadAll(): Map<string, WorkflowBlueprint> {
+  const all = new Map<string, WorkflowBlueprint>();
+
+  // Load built-ins first
+  for (const [id, bp] of scanDirectory(BUILTINS_DIR, true)) {
+    all.set(id, bp);
+  }
+
+  // User blueprints can override built-ins
+  for (const [id, bp] of scanDirectory(USER_BLUEPRINTS_DIR, false)) {
+    all.set(id, bp);
+  }
+
+  return all;
+}
+
+function ensureLoaded(): Map<string, WorkflowBlueprint> {
+  if (!blueprintCache) {
+    blueprintCache = loadAll();
+  }
+  return blueprintCache;
+}
+
+export function getBlueprint(id: string): WorkflowBlueprint | undefined {
+  return ensureLoaded().get(id);
+}
+
+export function listBlueprints(): WorkflowBlueprint[] {
+  return Array.from(ensureLoaded().values());
+}
+
+export function reloadBlueprints(): void {
+  blueprintCache = null;
+}
+
+export function isBuiltinBlueprint(id: string): boolean {
+  const bp = ensureLoaded().get(id);
+  return bp?.isBuiltin ?? false;
+}
+
+export function createBlueprint(yamlContent: string): WorkflowBlueprint {
+  const parsed = yaml.load(yamlContent);
+  const result = BlueprintSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(
+      `Invalid blueprint: ${result.error.issues.map((i) => i.message).join(", ")}`
+    );
+  }
+
+  fs.mkdirSync(USER_BLUEPRINTS_DIR, { recursive: true });
+  const filePath = path.join(USER_BLUEPRINTS_DIR, `${result.data.id}.yaml`);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Blueprint "${result.data.id}" already exists`);
+  }
+
+  fs.writeFileSync(filePath, yamlContent);
+  reloadBlueprints();
+  return { ...result.data, isBuiltin: false };
+}
+
+export function deleteBlueprint(id: string): void {
+  if (isBuiltinBlueprint(id)) {
+    throw new Error("Cannot delete built-in blueprints");
+  }
+
+  const filePath = path.join(USER_BLUEPRINTS_DIR, `${id}.yaml`);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Blueprint "${id}" not found`);
+  }
+
+  fs.unlinkSync(filePath);
+  reloadBlueprints();
+}
+
+/** Get the user blueprints directory path */
+export function getUserBlueprintsDir(): string {
+  return USER_BLUEPRINTS_DIR;
+}

package/src/lib/workflows/blueprints/template.ts

@@ -0,0 +1,58 @@
+/**
+ * Template resolution for blueprint prompt templates.
+ *
+ * Supports:
+ * - {{variable}} — simple substitution
+ * - {{#if variable}}...{{/if}} — conditional blocks
+ */
+
+/**
+ * Resolve all template expressions in a string.
+ */
+export function resolveTemplate(
+  template: string,
+  variables: Record<string, unknown>
+): string {
+  let result = template;
+
+  // Process {{#if variable}}...{{/if}} blocks first
+  result = result.replace(
+    /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,
+    (_match, varName: string, content: string) => {
+      const value = variables[varName];
+      return isTruthy(value) ? content : "";
+    }
+  );
+
+  // Then substitute {{variable}} references
+  result = result.replace(/\{\{(\w+)\}\}/g, (_match, varName: string) => {
+    const value = variables[varName];
+    if (value === undefined || value === null) return "";
+    return String(value);
+  });
+
+  // Clean up multiple consecutive blank lines left by removed conditionals
+  result = result.replace(/\n{3,}/g, "\n\n");
+
+  return result.trim();
+}
+
+/**
+ * Evaluate a condition string (a template expression like "{{variable}}").
+ * Returns true if the resolved value is truthy.
+ */
+export function evaluateCondition(
+  condition: string,
+  variables: Record<string, unknown>
+): boolean {
+  // Strip template syntax to get the variable name
+  const varName = condition.replace(/\{\{|\}\}/g, "").trim();
+  return isTruthy(variables[varName]);
+}
+
+function isTruthy(value: unknown): boolean {
+  if (value === undefined || value === null || value === "" || value === false) {
+    return false;
+  }
+  return true;
+}