@williambeto/ai-workflow 1.19.0 → 2.1.0

package/src/core/healing/cli-remediation-executor.js

@@ -0,0 +1,151 @@
+import { spawnSync, execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Determines which npm scripts are available in the consumer project.
+ * @param {string} cwd
+ * @returns {Promise<Record<string, string>>}
+ */
+async function readScripts(cwd) {
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(cwd, "package.json"), "utf8"));
+    return pkg.scripts || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Returns the list of files changed since the last commit.
+ * Used to detect whether remediation produced any observable change.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function getChangedFiles(cwd) {
+  try {
+    const output = execSync("git status --short", { cwd, encoding: "utf8" });
+    return output
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Maps an affectedCheck source string to likely npm script names to re-run.
+ * e.g. "check:branchSafety" → [] (no command can fix a branch issue)
+ *      "evidence" with failed test → ["test"]
+ * @param {string[]} affectedChecks
+ * @param {Record<string, string>} scripts
+ * @returns {string[]} ordered list of script names to retry
+ */
+function resolveRetryScripts(affectedChecks, scripts) {
+  const retry = new Set();
+
+  for (const check of affectedChecks) {
+    // Evidence failures → re-run the failing validation scripts
+    if (check === "evidence" || check === "result") {
+      if (scripts.test) retry.add("test");
+      if (scripts.lint) retry.add("lint");
+      if (scripts.build) retry.add("build");
+      if (scripts.typecheck) retry.add("typecheck");
+    }
+    // Specific check types
+    if (check.includes("test")) retry.add("test");
+    if (check.includes("lint")) retry.add("lint");
+    if (check.includes("build")) retry.add("build");
+    if (check.includes("typecheck")) retry.add("typecheck");
+  }
+
+  // Filter to only scripts that actually exist
+  return [...retry].filter((name) => !!scripts[name]);
+}
+
+/**
+ * CLI Remediation Executor — default implementation for `ai-workflow run`.
+ *
+ * Plugs into HealerEngine as the `remediate` function. On each attempt it:
+ *   1. Reads the remediation-request.json to understand what failed
+ *   2. Re-runs the affected npm scripts (lint, test, build, typecheck)
+ *   3. Reports changed files and whether any script now passes
+ *
+ * Design constraints:
+ *   - This executor does NOT modify source code — it only re-runs validation commands.
+ *   - It is effective for transient failures (e.g. flaky tests, stale build artifacts).
+ *   - For structural failures (missing tests, broken implementation), it will exhaust
+ *     its attempt budget and return applied:false, triggering a BLOCKED status.
+ *   - The user is shown clear output on each attempt.
+ *
+ * @param {Object} ctx - Context provided by HealerEngine.run()
+ * @param {number} ctx.attempt
+ * @param {number} ctx.maxAttempts
+ * @param {string} ctx.mode
+ * @param {string} ctx.taskSlug
+ * @param {Object} ctx.result - Current combined validation result
+ * @param {string[]} ctx.affectedChecks
+ * @param {string}  ctx.requestPath - Path to remediation-request.json
+ * @param {string}  cwd - Consumer project working directory (bound via closure)
+ * @returns {Promise<{applied: boolean, changedFiles?: string[], evidenceAdded?: string[], reason?: string}>}
+ */
+export function createCliRemediationExecutor(cwd) {
+  return async function remediationExecutor({ attempt, maxAttempts, mode, affectedChecks, requestPath }) {
+    console.log(`\n[HEALER] Attempt ${attempt}/${maxAttempts} — mode: ${mode}`);
+    console.log(`[HEALER] Affected: ${affectedChecks.join(", ")}`);
+
+    const scripts = await readScripts(cwd);
+    const filesBefore = getChangedFiles(cwd);
+    const toRetry = resolveRetryScripts(affectedChecks, scripts);
+
+    if (toRetry.length === 0) {
+      console.log("[HEALER] No retryable scripts found for the affected checks.");
+      console.log(`[HEALER] Review ${requestPath} for details.`);
+      return {
+        applied: false,
+        reason: `No npm scripts available to address: ${affectedChecks.join(", ")}. Manual remediation required.`
+      };
+    }
+
+    console.log(`[HEALER] Re-running: ${toRetry.map((s) => `npm run ${s}`).join(", ")}`);
+
+    const results = [];
+    let anyPassed = false;
+
+    for (const scriptName of toRetry) {
+      process.stdout.write(`  → npm run ${scriptName} ... `);
+      const result = spawnSync("npm", ["run", scriptName], {
+        cwd,
+        shell: true,
+        encoding: "utf8",
+        timeout: 120000
+      });
+      const passed = result.status === 0;
+      if (passed) anyPassed = true;
+      console.log(passed ? "PASS" : "FAIL");
+      results.push({ script: scriptName, passed, exitCode: result.status });
+    }
+
+    const filesAfter = getChangedFiles(cwd);
+    const changedFiles = filesAfter.filter((f) => !filesBefore.includes(f));
+
+    if (!anyPassed && changedFiles.length === 0) {
+      console.log("[HEALER] No scripts passed and no files changed — remediation had no effect.");
+      return {
+        applied: false,
+        reason: `Re-ran ${toRetry.join(", ")} — all failed. Structural fix required by the implementing agent.`
+      };
+    }
+
+    console.log(`[HEALER] Applied: ${results.filter((r) => r.passed).map((r) => r.script).join(", ") || "none passed"}`);
+    if (changedFiles.length) console.log(`[HEALER] Changed files: ${changedFiles.join(", ")}`);
+
+    return {
+      applied: true,
+      changedFiles,
+      evidenceAdded: anyPassed ? ["validation-output"] : []
+    };
+  };
+}

package/src/core/healing/healer-engine.js

@@ -0,0 +1,179 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { isRecoverableGateFailure } from "../statuses.js";
+
+const MODE_ATTEMPTS = Object.freeze({ quick: 1, standard: 2, full: 3 });
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function collectBlockingFindings(result = {}) {
+  const findings = [];
+  const add = (source, value) => {
+    if (!value || typeof value !== "object") return;
+    const status = value.status || value.overallStatus;
+    if (!["FAIL", "FAIL_QUALITY_GATE", "FAIL_DELEGATION_GATE", "BLOCKED"].includes(status)) return;
+    findings.push({
+      source,
+      status,
+      missing: Array.isArray(value.missing) ? [...value.missing].sort() : [],
+      reason: value.reason || value.summary || ""
+    });
+  };
+
+  add("result", result);
+  add("evidence", result.evidence);
+  add("quality", result.quality);
+  const checks = result.quality?.checks || result.policyValidation?.checks || result.checks || {};
+  for (const [name, check] of Object.entries(checks)) add(`check:${name}`, check);
+  return findings.sort((a, b) => a.source.localeCompare(b.source));
+}
+
+export class HealerEngine {
+  constructor({ cwd, mode = "standard", taskSlug = "implementation", maxAttempts = null } = {}) {
+    this.cwd = cwd;
+    this.mode = MODE_ATTEMPTS[mode] ? mode : "standard";
+    this.taskSlug = taskSlug;
+    this.maxAttempts = maxAttempts ?? MODE_ATTEMPTS[this.mode];
+  }
+
+  get statePath() {
+    return path.join(this.cwd, ".ai-workflow", `healing-state-${this.taskSlug}.json`);
+  }
+
+  fingerprint(result) {
+    return crypto.createHash("sha256").update(stableJson(collectBlockingFindings(result))).digest("hex");
+  }
+
+  blockingCount(result) {
+    return collectBlockingFindings(result).length;
+  }
+
+  affectedChecks(result) {
+    return collectBlockingFindings(result).map((finding) => finding.source);
+  }
+
+  hasProgress(before, after, remediation = {}) {
+    if (!isRecoverableGateFailure(after.overallStatus)) return true;
+    const beforeCount = this.blockingCount(before);
+    const afterCount = this.blockingCount(after);
+    if (afterCount < beforeCount) return true;
+    if (this.fingerprint(before) !== this.fingerprint(after) && (remediation.changedFiles?.length || remediation.evidenceAdded?.length)) return true;
+    return false;
+  }
+
+  async writeState(state) {
+    await fs.mkdir(path.dirname(this.statePath), { recursive: true });
+    await fs.writeFile(this.statePath, JSON.stringify(state, null, 2));
+  }
+
+  async resetState() {
+    try { await fs.unlink(this.statePath); } catch {}
+  }
+
+  async writeRemediationRequest({ attempt, result }) {
+    const requestPath = path.join(this.cwd, ".ai-workflow", "remediation-request.json");
+    await fs.mkdir(path.dirname(requestPath), { recursive: true });
+    const request = {
+      taskSlug: this.taskSlug,
+      executionMode: this.mode,
+      attempt,
+      maxAttempts: this.maxAttempts,
+      status: result.overallStatus,
+      affectedChecks: this.affectedChecks(result),
+      findingsFingerprint: this.fingerprint(result),
+      instruction: "Apply the smallest safe correction for the listed gates, then rerun validation. Do not broaden scope."
+    };
+    await fs.writeFile(requestPath, JSON.stringify(request, null, 2));
+    return requestPath;
+  }
+
+  async run({ initialResult, validate, remediate }) {
+    let current = initialResult;
+    const history = [];
+    const seen = new Set();
+
+    if (!isRecoverableGateFailure(current.overallStatus)) {
+      await this.resetState();
+      return { ...current, remediation: { status: "NOT_REQUIRED", attempts: 0, history } };
+    }
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt += 1) {
+      const fingerprint = this.fingerprint(current);
+      if (seen.has(fingerprint)) {
+        const blocked = { overallStatus: "BLOCKED", reason: "Repeated unresolved finding", previousResult: current };
+        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt - 1, history });
+        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt - 1, history } };
+      }
+      seen.add(fingerprint);
+
+      const requestPath = await this.writeRemediationRequest({ attempt, result: current });
+      if (typeof remediate !== "function") {
+        const blocked = { overallStatus: "BLOCKED", reason: "No remediation executor available", previousResult: current, requestPath };
+        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt - 1, history, requestPath });
+        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt - 1, history, requestPath } };
+      }
+
+      const remediation = await remediate({
+        attempt,
+        maxAttempts: this.maxAttempts,
+        mode: this.mode,
+        taskSlug: this.taskSlug,
+        result: current,
+        affectedChecks: this.affectedChecks(current),
+        requestPath
+      });
+
+      if (!remediation?.applied) {
+        const blocked = { overallStatus: "BLOCKED", reason: remediation?.reason || "Remediation was not applied", previousResult: current, requestPath };
+        history.push({ attempt, before: current.overallStatus, remediation, after: "NOT_RUN", progress: false });
+        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt, history });
+        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt, history } };
+      }
+
+      const next = await validate({ affectedChecks: this.affectedChecks(current), attempt });
+      const progress = this.hasProgress(current, next, remediation);
+      history.push({
+        attempt,
+        before: current.overallStatus,
+        after: next.overallStatus,
+        progress,
+        changedFiles: remediation.changedFiles || [],
+        evidenceAdded: remediation.evidenceAdded || [],
+        affectedChecks: this.affectedChecks(current)
+      });
+      await this.writeState({ status: next.overallStatus, attempts: attempt, history });
+
+      if (!isRecoverableGateFailure(next.overallStatus)) {
+        await this.resetState();
+        return { ...next, remediation: { status: "RESOLVED", attempts: attempt, history } };
+      }
+
+      if (!progress) {
+        return {
+          overallStatus: "BLOCKED",
+          reason: "Remediation made no measurable progress",
+          previousResult: next,
+          remediation: { status: "BLOCKED", attempts: attempt, history }
+        };
+      }
+
+      current = next;
+    }
+
+    return {
+      overallStatus: "BLOCKED",
+      reason: `Quality remediation attempts exhausted for ${this.mode} mode`,
+      previousResult: current,
+      remediation: { status: "BLOCKED", attempts: this.maxAttempts, history }
+    };
+  }
+}
+
+export { MODE_ATTEMPTS, collectBlockingFindings };

package/src/core/identity.js

@@ -0,0 +1,43 @@
+export const AGENT_MAP = {
+  "atlas": "Atlas",
+  "nexus": "Nexus",
+  "orion": "Orion",
+  "astra": "Astra",
+  "sage": "Sage",
+  "phoenix": "Phoenix",
+  "architecture": "Architecture-Specialist",
+  "backend-development": "Backend-Engineer",
+  "deployment": "Deployment-Specialist",
+  "design-principles": "Design-Specialist",
+  "documentation": "Docs-Engineer",
+  "frontend-development": "Frontend-Engineer",
+  "full-stack-development": "Full-Stack-Engineer",
+  "optimize-tokens": "Token-Economist",
+  "pr-workflow": "PR-Manager",
+  "product-discovery": "Discovery-Analyst",
+  "product-planning": "Product-Planner",
+  "project-memory": "Memory-Guardian",
+  "prompt-engineer": "Prompt-Engineer",
+  "qa-workflow": "QA-Engineer",
+  "refactoring": "Refactoring-Specialist",
+  "release-workflow": "Release-Specialist",
+  "spec-driven-development": "SDD-Specialist",
+  "technical-leadership": "Technical-Leader",
+  "ui-ux-design": "UI-UX-Engineer"
+};
+
+/**
+ * Returns the canonical (commercial) name for an agent given its internal slug.
+ * Falls back to PascalCase translation if no mapping exists.
+ * @param {string} slug
+ * @returns {string}
+ */
+export function getCanonicalAgentName(slug) {
+  if (AGENT_MAP[slug]) return AGENT_MAP[slug];
+  
+  // Fallback: convert slug-case to PascalCase
+  return slug
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}

package/{packages/ai-workflow/src → src}/core/install-plan.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { getTemplateFiles } from "./templates.js";
 
-export async function createInstallPlan({ cwd, exists, profile }) {
+export async function createInstallPlan({ cwd, exists, profile = "standard" }) {
   const actions = [];
   const templateFiles = getTemplateFiles(profile);
   const installRoot = ".ai-workflow";
@@ -22,10 +22,10 @@ export async function createInstallPlan({ cwd, exists, profile }) {
     });
   }
 
-  const configPath = path.join(cwd, ".ai-workflow.json");
+  const configPath = path.join(cwd, ".ai-workflow/config.json");
   actions.push({
     type: (await exists(configPath)) ? "conflict" : "create",
-    relativePath: ".ai-workflow.json",
+    relativePath: ".ai-workflow/config.json",
     absolutePath: configPath,
     content: null
   });

package/src/core/opencode-merge.js

@@ -0,0 +1,149 @@
+import path from "node:path";
+import { exists, readJsonc, writeFileSafe } from "./filesystem.js";
+import { createManagedBackup } from "./backup.js";
+import { getTemplateFiles } from "./templates.js";
+
+const LEGACY_MARKER = "_aiWorkflowManaged";
+
+const AGENTS = {
+  Atlas: { description: "Router and workflow coordinator for AI Workflow Kit" },
+  Nexus: { description: "Discovery, requirement, scope, and specification owner" },
+  Orion: { description: "Planning, PR sequencing, release, and deployment strategy owner" },
+  Astra: { description: "Implementation owner for incremental, scoped changes" },
+  Sage: { description: "Audit, validation, evidence, and quality gate owner" },
+  Phoenix: { description: "Remediation and regression recovery owner" }
+};
+
+const SUBAGENTS = {
+  "Architecture-Specialist": { description: "Select the simplest architecture that safely satisfies current requirements", skill: "architecture" },
+  "Backend-Engineer": { description: "Support safe PHP/Node/Python backend changes for APIs and persistence", skill: "backend-development" },
+  "Deployment-Specialist": { description: "Plan, review, or validate deployment, release, and production-readiness", skill: "deployment" },
+  "Design-Specialist": { description: "Apply practical design principles to keep solutions simple and maintainable", skill: "design-principles" },
+  "Docs-Engineer": { description: "Write or improve project documentation, READMEs, guides, and prompts", skill: "documentation" },
+  "Frontend-Engineer": { description: "Implement or review frontend changes involving UI, state, routing, and accessibility", skill: "frontend-development" },
+  "Full-Stack-Engineer": { description: "Coordinate frontend and backend changes as one coherent, testable increment", skill: "full-stack-development" },
+  "Token-Economist": { description: "Reduce context size while preserving information required for safe execution", skill: "optimize-tokens" },
+  "PR-Manager": { description: "Plan, implement, review, or validate small pull requests while preserving scope", skill: "pr-workflow" },
+  "Discovery-Analyst": { description: "Clarify ambiguous requests into actionable problem statements and success outcomes", skill: "product-discovery" },
+  "Product-Planner": { description: "Turn clarified needs into scoped requirements with acceptance-ready outcomes", skill: "product-planning" },
+  "Memory-Guardian": { description: "Manage discoverable project memory for durable decisions and recurring corrections", skill: "project-memory" },
+  "Prompt-Engineer": { description: "Expert in creating and refining prompts for AI agents and workflows", skill: "prompt-engineer" },
+  "QA-Engineer": { description: "Design, review, or improve tests, acceptance criteria, and validation evidence", skill: "qa-workflow" },
+  "Refactoring-Specialist": { description: "Improve code/document structure safely while preserving behavior", skill: "refactoring" },
+  "Release-Specialist": { description: "Prepare release readiness decisions with explicit gates and evidence", skill: "release-workflow" },
+  "SDD-Specialist": { description: "Convert approved requirements into explicit, testable specification artifacts", skill: "spec-driven-development" },
+  "Technical-Leader": { description: "Make technical decisions, review architecture, and identify trade-offs", skill: "technical-leadership" },
+  "UI-UX-Engineer": { description: "Improve usability and interface clarity without introducing unnecessary complexity", skill: "ui-ux-design" }
+};
+
+const COMMANDS = {
+  atlas: { description: "Decide safest next step and delegate to the appropriate workflow or agent", agent: "Atlas" },
+  run: { description: "Execute the master orchestration pipeline (Gates, SDD, Implementation, Validation, Healing)", agent: "Atlas" },
+  discover: { description: "Understand the project, gather context, and create initial documentation", agent: "Nexus" },
+  "spec-create": { description: "Create a clear specification before implementation", agent: "Nexus" },
+  "spec-review": { description: "Review a specification and validate scope, risks, criteria, and gaps", agent: "Nexus" },
+  "spec-implement": { description: "Implement an approved specification incrementally", agent: "Astra" },
+  plan: { description: "Plan a task or change, defining steps, risks, and validation", agent: "Orion" },
+  implement: { description: "Implement a small task with defined scope", agent: "Astra" },
+  validate: { description: "Run project validations and collect evidence", agent: "Sage" },
+  audit: { description: "Audit the project, identify issues, and suggest prioritized improvements", agent: "Sage" },
+  "optimize-tokens": { description: "Analyze workflow and context usage; suggest reductions without losing quality or evidence", agent: "Sage" },
+  "update-memory": { description: "Update durable project memory with relevant decisions, constraints, and reusable context", agent: "Nexus" },
+  release: { description: "Prepare delivery with commit, push, PR/merge readiness, changelog, and evidence", agent: "Orion" },
+  deploy: { description: "Publish the project to the defined environment after validation and release readiness", agent: "Orion" }
+};
+
+function buildManagedConfig() {
+  const agent = {};
+  for (const [name, def] of Object.entries(AGENTS)) {
+    agent[name] = {
+      mode: "primary",
+      description: def.description,
+      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`
+    };
+  }
+
+  for (const [name, def] of Object.entries(SUBAGENTS)) {
+    agent[name] = {
+      mode: "subagent",
+      description: def.description,
+      prompt: `{file:./.ai-workflow/opencode/skills/${def.skill}/SKILL.md}`
+    };
+  }
+
+  const command = {};
+  for (const [name, def] of Object.entries(COMMANDS)) {
+    command[name] = {
+      description: def.description,
+      agent: def.agent,
+      template: `{file:./.ai-workflow/opencode/commands/${name}.md}`
+    };
+  }
+
+  return {
+    $schema: "https://opencode.ai/config.json",
+    default_agent: "Atlas",
+    agent,
+    skills: {
+      paths: ["./.ai-workflow/opencode/skills"]
+    },
+    command
+  };
+}
+
+export async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".ai-workflow-backups" } = {}) {
+  const targetPath = path.join(cwd, "opencode.jsonc");
+  const managed = buildManagedConfig();
+
+  if (!(await exists(targetPath))) {
+    await writeFileSafe(targetPath, `${JSON.stringify(managed, null, 2)}\n`);
+    return { changed: true, reason: "created" };
+  }
+
+  let current;
+  try {
+    current = await readJsonc(targetPath);
+  } catch {
+    if (!force) {
+      return { changed: false, reason: "invalid-json (skipped)" };
+    }
+    await createManagedBackup(targetPath, {
+      cwd,
+      backupRoot,
+      maxPerFile: 20
+    });
+    await writeFileSafe(targetPath, `${JSON.stringify(managed, null, 2)}\n`);
+    return { changed: true, reason: "invalid-json (replaced with --force)" };
+  }
+
+  const { [LEGACY_MARKER]: _legacyManaged, ...currentWithoutLegacy } = current;
+
+  const next = {
+    ...currentWithoutLegacy,
+    $schema: current.$schema ?? managed.$schema,
+    ...(managed.mcp
+      ? {
+          mcp: {
+            ...(current.mcp ?? {}),
+            ...managed.mcp
+          }
+        }
+      : {}),
+    agent: {
+      ...(current.agent ?? {}),
+      ...managed.agent
+    },
+    command: {
+      ...(current.command ?? {}),
+      ...managed.command
+    }
+  };
+
+  const changed = JSON.stringify(current) !== JSON.stringify(next);
+  if (!changed) {
+    return { changed: false, reason: "already-up-to-date" };
+  }
+
+  await writeFileSafe(targetPath, `${JSON.stringify(next, null, 2)}\n`);
+  return { changed: true, reason: "merged-managed-sections" };
+}

package/{packages/ai-workflow/src → src}/core/package-assets.js

@@ -14,15 +14,33 @@ let cachedRoot = null;
  * Return the absolute path to the installed package root
  * (the directory containing `.agents/skills/`).
  *
- * This file lives at:  <package-root>/packages/ai-workflow/src/core/package-assets.js
- * Package root is 4 levels up.
+ * It dynamically searches for the package.json belonging to @williambeto/ai-workflow
+ * by climbing up from the current module location.
  */
 export function getPackageRoot() {
   if (cachedRoot) return cachedRoot;
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  // packages/ai-workflow/src/core/ -> ../../../../ = repo/package root
-  cachedRoot = resolve(__dirname, "../../../../");
-  return cachedRoot;
+  let currentDir = dirname(fileURLToPath(import.meta.url));
+
+  while (true) {
+    const pkgPath = resolve(currentDir, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg.name === "@williambeto/ai-workflow") {
+        cachedRoot = currentDir;
+        return cachedRoot;
+      }
+    } catch {
+      // package.json doesn't exist or is invalid, keep climbing
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break; // Reached filesystem root
+    }
+    currentDir = parentDir;
+  }
+
+  throw new Error("Failed to resolve @williambeto/ai-workflow package root physically.");
 }
 
 /**
@@ -96,11 +114,11 @@ export function discoverPackageFiles(baseRelativePath) {
 
 /**
  * Read the SKILL.md for a given skill name, plus any reference files
- * found under a `references/` subdirectory.
+ * found under a directory.
  * Returns a map of { relativePath: content }.
  */
 export function getFullSkillFiles(skillName) {
-  const skillRelPath = `.agents/skills/${skillName}`;
+  const skillRelPath = `dist-assets/skills/${skillName}`;
   const files = discoverPackageFiles(skillRelPath);
   return files;
 }
@@ -110,7 +128,7 @@ export function getFullSkillFiles(skillName) {
  * Returns the content string or null.
  */
 export function getFullAgentContent(agentName) {
-  return readPackageFile(`opencode/agents/${agentName}.md`);
+  return readPackageFile(`dist-assets/agents/${agentName}.md`);
 }
 
 /**
@@ -118,5 +136,6 @@ export function getFullAgentContent(agentName) {
  * Returns the content string or null.
  */
 export function getFullCommandContent(commandName) {
-  return readPackageFile(`opencode/commands/${commandName}.md`);
+  return readPackageFile(`dist-assets/commands/${commandName}.md`);
 }
+