feat: wire playbook execution engine to create and advance runs through phases

Author: marian2js

packages/contracts/src/index.ts

@@ -505,6 +505,7 @@ export const playbookPhaseSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   expectedArtifacts: z.array(z.string()).optional(),
+  specialistId: z.string().optional(),
 });
 
 export const playbookManifestSchema = z.object({

packages/core/src/core/playbooks/application/artifact-phase-matcher.ts

@@ -0,0 +1,66 @@
+import type { ArtifactRecord } from "../../artifacts/domain/artifact.js";
+
+export interface ArtifactMatchResult {
+  matched: Map<string, ArtifactRecord>;
+  missing: string[];
+}
+
+/**
+ * Tokenize a string into lowercase alphanumeric words.
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 0);
+}
+
+/**
+ * Matches actual artifacts against expected artifact names using fuzzy token overlap.
+ * A match requires at least 50% of the expected name's tokens to appear in the artifact title.
+ * Returns a map of matched expected names → artifact records, and a list of unmatched names.
+ */
+export function matchArtifactsToExpected(
+  artifacts: ArtifactRecord[],
+  expectedNames: string[],
+): ArtifactMatchResult {
+  const matched = new Map<string, ArtifactRecord>();
+  const missing: string[] = [];
+
+  // Track which artifacts have already been claimed to avoid double-matching
+  const claimed = new Set<string>();
+
+  for (const expectedName of expectedNames) {
+    const expectedTokens = tokenize(expectedName);
+    if (expectedTokens.length === 0) {
+      matched.set(expectedName, undefined as unknown as ArtifactRecord);
+      continue;
+    }
+
+    let bestArtifact: ArtifactRecord | null = null;
+    let bestScore = 0;
+
+    for (const artifact of artifacts) {
+      if (claimed.has(artifact.artifactId)) continue;
+
+      const titleTokens = new Set(tokenize(artifact.title));
+      const overlap = expectedTokens.filter((t) => titleTokens.has(t)).length;
+      const score = overlap / expectedTokens.length;
+
+      if (score >= 0.5 && score > bestScore) {
+        bestScore = score;
+        bestArtifact = artifact;
+      }
+    }
+
+    if (bestArtifact) {
+      matched.set(expectedName, bestArtifact);
+      claimed.add(bestArtifact.artifactId);
+    } else {
+      missing.push(expectedName);
+    }
+  }
+
+  return { matched, missing };
+}

packages/core/src/core/playbooks/application/playbook-execution.service.ts

@@ -0,0 +1,215 @@
+import type { OpenGoatPaths } from "../../domain/opengoat-paths.js";
+import type { ArtifactService } from "../../artifacts/application/artifact.service.js";
+import type { RunService } from "../../runs/application/run.service.js";
+import type { RunRecord } from "../../runs/domain/run.js";
+import type { PlaybookRegistryService } from "./playbook-registry.service.js";
+import { matchArtifactsToExpected } from "./artifact-phase-matcher.js";
+
+export interface StartPlaybookOptions {
+  playbookId: string;
+  projectId: string;
+  objectiveId: string;
+}
+
+export interface PhaseProgressResult {
+  advanced: boolean;
+  completed: boolean;
+  run: RunRecord;
+}
+
+export interface PhaseProgress {
+  name: string;
+  description: string;
+  status: "completed" | "current" | "upcoming";
+  specialistId?: string;
+  expectedArtifacts: string[];
+  matchedArtifacts: string[];
+  missingArtifacts: string[];
+}
+
+export interface PlaybookProgress {
+  runId: string;
+  playbookId: string;
+  playbookTitle: string;
+  currentPhase: string;
+  runStatus: string;
+  phases: PhaseProgress[];
+}
+
+interface PlaybookExecutionServiceDeps {
+  runService: RunService;
+  artifactService: ArtifactService;
+  playbookRegistryService: PlaybookRegistryService;
+}
+
+export class PlaybookExecutionService {
+  private readonly runService: RunService;
+  private readonly artifactService: ArtifactService;
+  private readonly playbookRegistryService: PlaybookRegistryService;
+
+  constructor(deps: PlaybookExecutionServiceDeps) {
+    this.runService = deps.runService;
+    this.artifactService = deps.artifactService;
+    this.playbookRegistryService = deps.playbookRegistryService;
+  }
+
+  /**
+   * Start a playbook: creates a run, sets it to running, and initializes the first phase.
+   */
+  async startPlaybook(
+    paths: OpenGoatPaths,
+    options: StartPlaybookOptions,
+  ): Promise<RunRecord> {
+    const manifest = this.playbookRegistryService.getPlaybook(options.playbookId);
+    const firstPhase = manifest.defaultPhases[0];
+
+    if (!firstPhase) {
+      throw new Error(`Playbook "${options.playbookId}" has no phases`);
+    }
+
+    const run = await this.runService.createRun(paths, {
+      projectId: options.projectId,
+      objectiveId: options.objectiveId,
+      playbookId: options.playbookId,
+      title: manifest.title,
+      startedFrom: "action",
+      phase: firstPhase.name,
+      phaseSummary: firstPhase.description,
+    });
+
+    // Transition from draft → running
+    return this.runService.updateRunStatus(paths, run.runId, "running");
+  }
+
+  /**
+   * Check if the current phase's expected artifacts have been produced.
+   * If so, advance to the next phase or complete the run.
+   */
+  async checkPhaseProgress(
+    paths: OpenGoatPaths,
+    runId: string,
+  ): Promise<PhaseProgressResult> {
+    const run = await this.runService.getRun(paths, runId);
+
+    if (!run.playbookId) {
+      throw new Error("Run is not associated with a playbook");
+    }
+
+    const manifest = this.playbookRegistryService.getPlaybook(run.playbookId);
+    const currentPhaseIndex = manifest.defaultPhases.findIndex(
+      (p) => p.name === run.phase,
+    );
+
+    if (currentPhaseIndex === -1) {
+      return { advanced: false, completed: false, run };
+    }
+
+    const currentPhase = manifest.defaultPhases[currentPhaseIndex]!;
+    const expectedArtifacts = currentPhase.expectedArtifacts ?? [];
+
+    // If no expected artifacts, phase is automatically satisfied
+    if (expectedArtifacts.length === 0) {
+      return this.advanceOrComplete(paths, run, manifest, currentPhaseIndex);
+    }
+
+    // Get artifacts for this run
+    const artifactPage = await this.artifactService.listArtifacts(paths, {
+      runId: run.runId,
+    });
+
+    const { missing } = matchArtifactsToExpected(
+      artifactPage.items,
+      expectedArtifacts,
+    );
+
+    if (missing.length > 0) {
+      return { advanced: false, completed: false, run };
+    }
+
+    return this.advanceOrComplete(paths, run, manifest, currentPhaseIndex);
+  }
+
+  /**
+   * Get detailed progress for a playbook run.
+   */
+  async getRunProgress(
+    paths: OpenGoatPaths,
+    runId: string,
+  ): Promise<PlaybookProgress> {
+    const run = await this.runService.getRun(paths, runId);
+
+    if (!run.playbookId) {
+      throw new Error("Run is not associated with a playbook");
+    }
+
+    const manifest = this.playbookRegistryService.getPlaybook(run.playbookId);
+    const currentPhaseIndex = manifest.defaultPhases.findIndex(
+      (p) => p.name === run.phase,
+    );
+
+    // Get all artifacts for the run
+    const artifactPage = await this.artifactService.listArtifacts(paths, {
+      runId: run.runId,
+    });
+
+    const isCompleted = run.status === "completed";
+
+    const phases: PhaseProgress[] = manifest.defaultPhases.map((phase, index) => {
+      const expectedArtifacts = phase.expectedArtifacts ?? [];
+      const { matched, missing } = matchArtifactsToExpected(
+        artifactPage.items,
+        expectedArtifacts,
+      );
+
+      let status: PhaseProgress["status"];
+      if (isCompleted || index < currentPhaseIndex) {
+        status = "completed";
+      } else if (index === currentPhaseIndex) {
+        status = isCompleted ? "completed" : "current";
+      } else {
+        status = "upcoming";
+      }
+
+      return {
+        name: phase.name,
+        description: phase.description,
+        status,
+        specialistId: phase.specialistId,
+        expectedArtifacts,
+        matchedArtifacts: Array.from(matched.keys()),
+        missingArtifacts: missing,
+      };
+    });
+
+    return {
+      runId: run.runId,
+      playbookId: run.playbookId,
+      playbookTitle: manifest.title,
+      currentPhase: run.phase,
+      runStatus: run.status,
+      phases,
+    };
+  }
+
+  private async advanceOrComplete(
+    paths: OpenGoatPaths,
+    run: RunRecord,
+    manifest: { defaultPhases: Array<{ name: string; description: string }> },
+    currentPhaseIndex: number,
+  ): Promise<PhaseProgressResult> {
+    const isLastPhase = currentPhaseIndex === manifest.defaultPhases.length - 1;
+
+    if (isLastPhase) {
+      const completedRun = await this.runService.completeRun(paths, run.runId);
+      return { advanced: false, completed: true, run: completedRun };
+    }
+
+    const nextPhase = manifest.defaultPhases[currentPhaseIndex + 1]!;
+    const advancedRun = await this.runService.advancePhase(paths, run.runId, {
+      phase: nextPhase.name,
+      phaseSummary: nextPhase.description,
+    });
+
+    return { advanced: true, completed: false, run: advancedRun };
+  }
+}

packages/core/src/core/playbooks/index.ts

@@ -1,3 +1,7 @@
 export { PlaybookRegistryService } from "./application/playbook-registry.service.js";
+export { PlaybookExecutionService } from "./application/playbook-execution.service.js";
+export type { StartPlaybookOptions, PhaseProgressResult, PhaseProgress, PlaybookProgress } from "./application/playbook-execution.service.js";
+export { matchArtifactsToExpected } from "./application/artifact-phase-matcher.js";
+export type { ArtifactMatchResult } from "./application/artifact-phase-matcher.js";
 export type { PlaybookManifest, PlaybookSource, PlaybookPhase, GoalType } from "./domain/playbook.js";
 export { BUILTIN_PLAYBOOKS } from "./manifests/index.js";

packages/core/src/core/playbooks/manifests/comparison-page.ts

@@ -25,24 +25,28 @@ export const comparisonPagePlaybook: PlaybookManifest = {
       description:
         "Analyze competitor positioning, messaging themes, strengths, and weaknesses.",
       expectedArtifacts: ["competitor matrix"],
+      specialistId: "market-intel",
     },
     {
       name: "Analyze",
       description:
         "Identify messaging gaps, unoccupied positions, and counter-positioning opportunities.",
       expectedArtifacts: ["messaging gaps"],
+      specialistId: "positioning",
     },
     {
       name: "Draft",
       description:
         "Create comparison page outline with sections, copy angles, and proof points.",
       expectedArtifacts: ["comparison page outline"],
+      specialistId: "seo-aeo",
     },
     {
       name: "Prioritize",
       description:
         "Rank comparison targets by search volume, win rate impact, and content effort.",
       expectedArtifacts: ["priority comparison targets"],
+      specialistId: "seo-aeo",
     },
   ],
   artifactTypes: [

packages/core/src/core/playbooks/manifests/content-sprint.ts

@@ -26,24 +26,28 @@ export const contentSprintPlaybook: PlaybookManifest = {
       description:
         "Define content pillars and research audience pain points, trending topics, and competitor gaps.",
       expectedArtifacts: ["content pillars"],
+      specialistId: "content",
     },
     {
       name: "Ideation",
       description:
         "Generate 10 ranked content ideas with channel, format, and impact reasoning.",
       expectedArtifacts: ["10 content ideas"],
+      specialistId: "content",
     },
     {
       name: "Draft",
       description:
         "Write 3 content briefs and 1 full draft for the highest-impact idea.",
       expectedArtifacts: ["3 content briefs", "1 full draft"],
+      specialistId: "content",
     },
     {
       name: "Repurpose",
       description:
         "Create a repurposing set showing how the draft can be adapted across channels.",
       expectedArtifacts: ["repurposing set"],
+      specialistId: "content",
     },
   ],
   artifactTypes: [

packages/core/src/core/playbooks/manifests/homepage-conversion.ts

@@ -25,6 +25,7 @@ export const homepageConversionPlaybook: PlaybookManifest = {
       description:
         "Analyze homepage across 7 CRO dimensions: value prop clarity, headline effectiveness, CTA placement, visual hierarchy, trust signals, objection handling, friction points.",
       expectedArtifacts: ["CRO audit report"],
+      specialistId: "website-conversion",
     },
     {
       name: "Draft",
@@ -36,17 +37,20 @@ export const homepageConversionPlaybook: PlaybookManifest = {
         "trust section rewrite",
         "objection handling copy",
       ],
+      specialistId: "website-conversion",
     },
     {
       name: "Review",
       description:
         "Present options with before/after framing; collect founder preferences.",
+      specialistId: "cmo",
     },
     {
       name: "Refine",
       description:
         "Deliver final copy and a prioritized page recommendations backlog.",
       expectedArtifacts: ["page recommendations backlog"],
+      specialistId: "website-conversion",
     },
   ],
   artifactTypes: [