@soleri/core 2.1.0 → 2.5.0

package/src/playbooks/playbook-registry.ts

@@ -0,0 +1,284 @@
+/**
+ * Playbook Registry
+ *
+ * Matches playbooks to plan context (intent + keywords) and merges
+ * generic + domain tiers into a single MergedPlaybook.
+ *
+ * Resolution order: vault first (user overrides), built-in fallback.
+ */
+
+import type {
+  PlaybookDefinition,
+  PlaybookMatchResult,
+  MergedPlaybook,
+  PlaybookGate,
+  PlaybookTaskTemplate,
+  PlaybookIntent,
+} from './playbook-types.js';
+
+// Built-in generic playbook definitions
+import { tddPlaybook } from './generic/tdd.js';
+import { brainstormingPlaybook } from './generic/brainstorming.js';
+import { codeReviewPlaybook } from './generic/code-review.js';
+import { subagentExecutionPlaybook } from './generic/subagent-execution.js';
+import { systematicDebuggingPlaybook } from './generic/systematic-debugging.js';
+import { verificationPlaybook } from './generic/verification.js';
+
+// =============================================================================
+// SCORING WEIGHTS
+// =============================================================================
+
+/** Points awarded when the plan intent matches a playbook's matchIntents. */
+const INTENT_MATCH_SCORE = 10;
+
+/** Points awarded per keyword hit in the plan text. */
+const KEYWORD_MATCH_SCORE = 5;
+
+/** Minimum total score for a playbook to be considered a match. */
+const MIN_MATCH_SCORE = 5;
+
+// =============================================================================
+// BUILT-IN REGISTRY
+// =============================================================================
+
+const BUILTIN_PLAYBOOKS: PlaybookDefinition[] = [
+  // Generic tier
+  tddPlaybook,
+  brainstormingPlaybook,
+  codeReviewPlaybook,
+  subagentExecutionPlaybook,
+  systematicDebuggingPlaybook,
+  verificationPlaybook,
+];
+
+/**
+ * Get a built-in playbook by ID.
+ */
+export function getBuiltinPlaybook(id: string): PlaybookDefinition | undefined {
+  return BUILTIN_PLAYBOOKS.find((p) => p.id === id);
+}
+
+/**
+ * Get all built-in playbooks.
+ */
+export function getAllBuiltinPlaybooks(): readonly PlaybookDefinition[] {
+  return BUILTIN_PLAYBOOKS;
+}
+
+// =============================================================================
+// MATCHING
+// =============================================================================
+
+/**
+ * Score a playbook against the given intent and text.
+ * Returns 0 if no match, positive score if matched.
+ */
+export function scorePlaybook(
+  playbook: PlaybookDefinition,
+  intent: PlaybookIntent | undefined,
+  text: string,
+): number {
+  let score = 0;
+  const lowerText = text.toLowerCase();
+
+  // Intent match
+  if (intent && playbook.matchIntents.includes(intent)) {
+    score += INTENT_MATCH_SCORE;
+  }
+
+  // Keyword match
+  for (const keyword of playbook.matchKeywords) {
+    if (lowerText.includes(keyword.toLowerCase())) {
+      score += KEYWORD_MATCH_SCORE;
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Find the best matching playbook from a list for the given context.
+ * Returns the highest-scoring playbook above the threshold, or undefined.
+ */
+function findBestMatch(
+  playbooks: PlaybookDefinition[],
+  intent: PlaybookIntent | undefined,
+  text: string,
+  minScore: number = MIN_MATCH_SCORE,
+): { playbook: PlaybookDefinition; score: number } | undefined {
+  let best: { playbook: PlaybookDefinition; score: number } | undefined;
+
+  for (const playbook of playbooks) {
+    const score = scorePlaybook(playbook, intent, text);
+    if (score >= minScore && (!best || score > best.score)) {
+      best = { playbook, score };
+    }
+  }
+
+  return best;
+}
+
+// =============================================================================
+// MERGING
+// =============================================================================
+
+/**
+ * Merge gates from generic and domain playbooks.
+ * Domain gates come after generic gates. No deduplication — they serve different purposes.
+ */
+function mergeGates(generic?: PlaybookDefinition, domain?: PlaybookDefinition): PlaybookGate[] {
+  const gates: PlaybookGate[] = [];
+  if (generic) gates.push(...generic.gates);
+  if (domain) gates.push(...domain.gates);
+  return gates;
+}
+
+/**
+ * Merge task templates from generic and domain playbooks.
+ * Domain templates with the same order position override generic ones of the same taskType.
+ */
+function mergeTaskTemplates(
+  generic?: PlaybookDefinition,
+  domain?: PlaybookDefinition,
+): PlaybookTaskTemplate[] {
+  const genericTemplates = generic?.taskTemplates ?? [];
+  const domainTemplates = domain?.taskTemplates ?? [];
+
+  // Start with generic templates
+  const merged = [...genericTemplates];
+
+  for (const domainTemplate of domainTemplates) {
+    // Check if domain overrides a generic template at the same order + taskType
+    const overrideIndex = merged.findIndex(
+      (g) => g.order === domainTemplate.order && g.taskType === domainTemplate.taskType,
+    );
+
+    if (overrideIndex >= 0) {
+      // Domain overrides generic
+      merged[overrideIndex] = domainTemplate;
+    } else {
+      // Domain adds a new template
+      merged.push(domainTemplate);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Merge tool injections from generic and domain playbooks.
+ * Deduplicated — each tool appears only once.
+ */
+function mergeTools(generic?: PlaybookDefinition, domain?: PlaybookDefinition): string[] {
+  const tools = new Set<string>();
+  if (generic) {
+    for (const tool of generic.toolInjections) tools.add(tool);
+  }
+  if (domain) {
+    for (const tool of domain.toolInjections) tools.add(tool);
+  }
+  return Array.from(tools);
+}
+
+/**
+ * Merge verification criteria from generic and domain playbooks.
+ * All criteria from both tiers — domain typically adds domain-specific checks.
+ */
+function mergeVerification(generic?: PlaybookDefinition, domain?: PlaybookDefinition): string[] {
+  const criteria: string[] = [];
+  if (generic) criteria.push(...generic.verificationCriteria);
+  if (domain) criteria.push(...domain.verificationCriteria);
+  // Deduplicate exact matches
+  return [...new Set(criteria)];
+}
+
+/**
+ * Build a human-readable label for the merged playbook.
+ */
+function buildLabel(generic?: PlaybookDefinition, domain?: PlaybookDefinition): string {
+  if (generic && domain) {
+    return `${domain.title} (extends ${generic.title})`;
+  }
+  if (domain) return domain.title;
+  if (generic) return generic.title;
+  return 'Unknown';
+}
+
+/**
+ * Create a MergedPlaybook from a generic and/or domain match.
+ */
+export function mergePlaybooks(
+  generic?: PlaybookDefinition,
+  domain?: PlaybookDefinition,
+): MergedPlaybook {
+  return {
+    generic,
+    domain,
+    mergedGates: mergeGates(generic, domain),
+    mergedTasks: mergeTaskTemplates(generic, domain),
+    mergedTools: mergeTools(generic, domain),
+    mergedVerification: mergeVerification(generic, domain),
+    label: buildLabel(generic, domain),
+  };
+}
+
+// =============================================================================
+// MAIN API
+// =============================================================================
+
+/**
+ * Match playbooks for a plan based on intent and objective/scope text.
+ *
+ * Resolution:
+ * 1. Search built-in playbooks (vault search is wired separately by the caller)
+ * 2. Find best generic match
+ * 3. Find best domain match
+ * 4. If domain has `extends`, resolve the generic it extends
+ * 5. Merge into MergedPlaybook
+ *
+ * @param intent - The detected intent (BUILD, FIX, REVIEW, etc.)
+ * @param text - The plan objective + scope text to match against
+ * @param vaultPlaybooks - Optional vault-stored playbooks (searched first, override builtins)
+ */
+export function matchPlaybooks(
+  intent: PlaybookIntent | undefined,
+  text: string,
+  vaultPlaybooks?: PlaybookDefinition[],
+): PlaybookMatchResult {
+  // Combine vault (higher priority) and built-in playbooks
+  const allPlaybooks = [...(vaultPlaybooks ?? []), ...BUILTIN_PLAYBOOKS];
+
+  const generics = allPlaybooks.filter((p) => p.tier === 'generic');
+  const domains = allPlaybooks.filter((p) => p.tier === 'domain');
+
+  // Find best domain match first (domain is more specific)
+  const domainMatch = findBestMatch(domains, intent, text);
+
+  // Find best generic match
+  let genericMatch = findBestMatch(generics, intent, text);
+
+  // If domain extends a specific generic, prefer that one
+  if (domainMatch?.playbook.extends) {
+    const extendedGeneric = allPlaybooks.find((p) => p.id === domainMatch.playbook.extends);
+    if (extendedGeneric) {
+      genericMatch = { playbook: extendedGeneric, score: domainMatch.score };
+    }
+  }
+
+  // No match at all
+  if (!genericMatch && !domainMatch) {
+    return { playbook: null };
+  }
+
+  const merged = mergePlaybooks(genericMatch?.playbook, domainMatch?.playbook);
+
+  return {
+    playbook: merged,
+    genericMatch: genericMatch
+      ? { id: genericMatch.playbook.id, source: 'builtin', score: genericMatch.score }
+      : undefined,
+    domainMatch: domainMatch
+      ? { id: domainMatch.playbook.id, source: 'builtin', score: domainMatch.score }
+      : undefined,
+  };
+}

package/src/playbooks/playbook-seeder.ts

@@ -0,0 +1,119 @@
+/**
+ * Playbook Seeder
+ *
+ * Seeds default playbooks into the vault on activation.
+ * Idempotent — only seeds playbooks that don't already exist.
+ * Never overwrites user-modified playbooks.
+ *
+ * Also provides conversion utilities between PlaybookDefinition and
+ * IntelligenceEntry for vault storage.
+ */
+
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { PlaybookDefinition } from './playbook-types.js';
+import { getAllBuiltinPlaybooks } from './playbook-registry.js';
+import type { Vault } from '../vault/vault.js';
+
+/**
+ * Convert a PlaybookDefinition to a vault IntelligenceEntry.
+ *
+ * Field mapping:
+ *   id -> id              title -> title
+ *   'playbook' -> type    category -> domain
+ *   'suggestion' -> severity
+ *   trigger -> context (prefixed with full definition JSON for reconstruction)
+ *   description -> description
+ *   tags -> tags
+ *   steps -> example
+ *   expectedOutcome -> why
+ */
+export function playbookDefinitionToEntry(def: PlaybookDefinition): IntelligenceEntry {
+  // Serialize the full definition as JSON metadata so playbook_match can reconstruct it
+  const metadata = JSON.stringify(def);
+
+  return {
+    id: def.id,
+    type: 'playbook',
+    domain: def.category,
+    title: def.title,
+    severity: 'suggestion',
+    description: def.description,
+    context: `__PLAYBOOK_DEF__${metadata}__END_DEF__\n${def.trigger}`,
+    example: def.steps,
+    why: def.expectedOutcome,
+    tags: def.tags,
+  };
+}
+
+/**
+ * Extract a PlaybookDefinition from a vault IntelligenceEntry.
+ * Returns null if the entry doesn't contain PlaybookDefinition metadata.
+ */
+export function entryToPlaybookDefinition(entry: IntelligenceEntry): PlaybookDefinition | null {
+  if (entry.type !== 'playbook') return null;
+
+  const context = entry.context ?? '';
+  const startMarker = '__PLAYBOOK_DEF__';
+  const endMarker = '__END_DEF__';
+
+  const startIdx = context.indexOf(startMarker);
+  const endIdx = context.indexOf(endMarker);
+
+  if (startIdx < 0 || endIdx < 0) return null;
+
+  try {
+    const json = context.slice(startIdx + startMarker.length, endIdx);
+    const def = JSON.parse(json) as PlaybookDefinition;
+    // Validate it has the essential fields
+    if (!def.id || !def.tier || !def.title) return null;
+    return def;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Seed default built-in playbooks into the vault.
+ * Idempotent — skips playbooks that already exist (never overwrites).
+ */
+export function seedDefaultPlaybooks(vault: Vault): {
+  seeded: number;
+  skipped: number;
+  errors: number;
+  details: Array<{ id: string; action: 'seeded' | 'skipped' | 'error'; reason?: string }>;
+} {
+  const result = {
+    seeded: 0,
+    skipped: 0,
+    errors: 0,
+    details: [] as Array<{ id: string; action: 'seeded' | 'skipped' | 'error'; reason?: string }>,
+  };
+
+  const playbooks = getAllBuiltinPlaybooks();
+
+  for (const playbook of playbooks) {
+    try {
+      // Check if already exists
+      const existing = vault.get(playbook.id);
+      if (existing) {
+        result.skipped++;
+        result.details.push({ id: playbook.id, action: 'skipped', reason: 'already exists' });
+        continue;
+      }
+
+      const entry = playbookDefinitionToEntry(playbook);
+      vault.add(entry);
+      result.seeded++;
+      result.details.push({ id: playbook.id, action: 'seeded' });
+    } catch (error) {
+      result.errors++;
+      result.details.push({
+        id: playbook.id,
+        action: 'error',
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}

package/src/playbooks/playbook-types.ts

@@ -0,0 +1,162 @@
+/**
+ * Playbook Type System
+ *
+ * Two-tier playbook architecture ported from Salvador:
+ * - Generic playbooks: process discipline (TDD, brainstorming, debugging, etc.)
+ * - Domain playbooks: agent-specific workflows that extend generics
+ *
+ * Playbooks compose at plan creation time via the `extends` relationship.
+ * Generic provides the rhythm, domain fills in domain-specific beats.
+ */
+
+// =============================================================================
+// TIERS & INTENTS
+// =============================================================================
+
+export type PlaybookTier = 'generic' | 'domain';
+export type PlaybookIntent = 'BUILD' | 'FIX' | 'REVIEW' | 'PLAN' | 'IMPROVE' | 'DELIVER';
+
+// =============================================================================
+// BRAINSTORM SECTIONS
+// =============================================================================
+
+/**
+ * A structured brainstorming section returned by the brainstorm op.
+ * The LLM uses these to guide design conversation with the user.
+ */
+export interface BrainstormSection {
+  /** Section title (e.g., "Component API", "Color Requirements") */
+  title: string;
+  /** What this section covers */
+  description: string;
+  /** Guiding questions for the user */
+  questions: string[];
+}
+
+// =============================================================================
+// GATES
+// =============================================================================
+
+/**
+ * A gate that must be satisfied at a given lifecycle phase.
+ * Gates inject checkId requirements into the planning lifecycle.
+ */
+export interface PlaybookGate {
+  /** Which lifecycle phase this gate applies to */
+  phase: 'brainstorming' | 'pre-execution' | 'post-task' | 'completion';
+  /** Human-readable requirement description */
+  requirement: string;
+  /** Check type to create/validate */
+  checkType: string;
+}
+
+// =============================================================================
+// TASK TEMPLATES
+// =============================================================================
+
+/**
+ * A task template that the playbook injects into generated plans.
+ * These become PlanTask entries during task splitting.
+ */
+export interface PlaybookTaskTemplate {
+  /** Task type for the generated task */
+  taskType: 'implementation' | 'test' | 'story' | 'documentation' | 'verification';
+  /** Title template — may contain {objective} placeholder */
+  titleTemplate: string;
+  /** Acceptance criteria injected into the task */
+  acceptanceCriteria: string[];
+  /** Tools relevant to this task */
+  tools: string[];
+  /** When this task should execute relative to implementation */
+  order: 'before-implementation' | 'after-implementation' | 'parallel';
+}
+
+// =============================================================================
+// PLAYBOOK DEFINITION
+// =============================================================================
+
+/**
+ * Complete playbook definition — the core data type.
+ * Playbooks are pure data objects with no logic.
+ */
+export interface PlaybookDefinition {
+  /** Unique identifier (e.g., 'generic-tdd', 'domain-component-build') */
+  id: string;
+  /** Which tier this playbook belongs to */
+  tier: PlaybookTier;
+  /** Human-readable title */
+  title: string;
+  /** When to activate — maps to vault entry 'context' field */
+  trigger: string;
+  /** Overview of what this playbook does — maps to vault 'description' field */
+  description: string;
+  /** Step-by-step process — maps to vault 'example' field */
+  steps: string;
+  /** What success looks like — maps to vault 'why' field */
+  expectedOutcome: string;
+  /** ID of generic playbook this extends (domain playbooks only) */
+  extends?: string;
+  /** Free string category (agents define their own domains) */
+  category: string;
+  /** Searchable tags */
+  tags: string[];
+  /** Intents that trigger this playbook */
+  matchIntents: PlaybookIntent[];
+  /** Keywords in plan objective/scope that trigger this playbook */
+  matchKeywords: string[];
+
+  // --- What this playbook injects into plans ---
+
+  /** Brainstorming sections for design exploration (used by brainstorm op) */
+  brainstormSections?: BrainstormSection[];
+
+  /** Lifecycle gates to enforce */
+  gates: PlaybookGate[];
+  /** Task templates to inject during task generation */
+  taskTemplates: PlaybookTaskTemplate[];
+  /** Generic op names to auto-inject into tool chain (not agent-prefixed) */
+  toolInjections: string[];
+  /** Verification criteria for completion gate */
+  verificationCriteria: string[];
+}
+
+// =============================================================================
+// MERGED PLAYBOOK
+// =============================================================================
+
+/**
+ * Result of matching and merging a generic + domain playbook pair.
+ * This is the shape that plan-handler receives after playbook resolution.
+ */
+export interface MergedPlaybook {
+  /** The generic playbook (if matched) */
+  generic?: PlaybookDefinition;
+  /** The domain playbook (if matched) */
+  domain?: PlaybookDefinition;
+  /** Combined gates from both tiers (generic first, then domain) */
+  mergedGates: PlaybookGate[];
+  /** Combined task templates (domain overrides generic where order conflicts) */
+  mergedTasks: PlaybookTaskTemplate[];
+  /** Combined tool injections (deduplicated) */
+  mergedTools: string[];
+  /** Combined verification criteria */
+  mergedVerification: string[];
+  /** Human-readable label for the matched playbook(s) */
+  label: string;
+}
+
+// =============================================================================
+// MATCH RESULT
+// =============================================================================
+
+/**
+ * Result of playbook matching — includes the source of each match.
+ */
+export interface PlaybookMatchResult {
+  /** The merged playbook (null if no match) */
+  playbook: MergedPlaybook | null;
+  /** Which generic matched and why */
+  genericMatch?: { id: string; source: 'vault' | 'builtin'; score: number };
+  /** Which domain matched and why */
+  domainMatch?: { id: string; source: 'vault' | 'builtin'; score: number };
+}