@williambeto/ai-workflow 1.19.1 → 2.2.0

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`);
 }
+

package/src/core/request-classifier.js

@@ -0,0 +1,58 @@
+import { resolveWorkflowProfile, getWorkflowProfile } from "./workflow-profiles.js";
+
+/**
+ * RequestClassifier - Classifies natural requests into structured, testable contracts.
+ */
+export class RequestClassifier {
+  /**
+   * Classifies a natural request.
+   * @param {string} request - The natural language request string.
+   * @returns {Object} Structured classification contract.
+   */
+  classify(request = "") {
+    const text = String(request).trim();
+    if (!text) {
+      throw new Error("Cannot classify an empty request.");
+    }
+
+    // 1. Resolve Profile
+    const profile = resolveWorkflowProfile({ request: text });
+    const profileDef = getWorkflowProfile(profile);
+
+    // 2. Classify Intent
+    const readOnlyPatterns = /\b(analyze|check|inspect|review|find|search|show|list|read|view|verify)\b/i;
+    const isReadOnly = readOnlyPatterns.test(text);
+    const intent = isReadOnly ? "read-only" : "write";
+
+    // 3. Classify Mode
+    let mode = "standard";
+    if (/\b(deep|architectural|migration|major|full|\[deep\])\b/i.test(text)) {
+      mode = "full";
+    } else if (/\b(tiny|small|quick|simple|only\s+update|typo|comment|\[tiny\])\b/i.test(text)) {
+      mode = "quick";
+    }
+
+    // 4. Classify Risk
+    let risk = "medium";
+    if (mode === "full" || profile === "security-review") {
+      risk = "high";
+    } else if (mode === "quick" || intent === "read-only") {
+      risk = "low";
+    }
+
+    const specNeeded = mode === "full" && intent === "write";
+    const validationNeeded = intent === "write";
+
+    return {
+      request: text,
+      profile,
+      owner: profileDef.owner,
+      intent,
+      mode,
+      risk,
+      specNeeded,
+      validationNeeded,
+      skills: [...profileDef.skills]
+    };
+  }
+}

package/src/core/runtime/opencode-adapter.js

@@ -0,0 +1,94 @@
+import { spawn, execSync } from "node:child_process";
+import readline from "node:readline";
+
+/**
+ * OpenCodeAdapter - Real runtime integration with the OpenCode CLI.
+ */
+export class OpenCodeAdapter {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Runs opencode with a prompt and options.
+   * @param {string} message - The message prompt.
+   * @param {Object} options - CLI options (e.g. agent, model, dangerouslySkipPermissions).
+   * @returns {Promise<{success: boolean, commandsRun: string[], eventCount: number}>}
+   */
+  async execute(message, { agent = null, model = null, dangerouslySkipPermissions = false } = {}) {
+    return new Promise((resolve) => {
+      const args = ["run", message, "--format", "json"];
+      if (agent) {
+        args.push("--agent", agent);
+      }
+      if (model) {
+        args.push("--model", model);
+      }
+      if (dangerouslySkipPermissions) {
+        args.push("--dangerously-skip-permissions");
+      }
+
+      console.log(`[RUNTIME] Delegating to OpenCode: opencode ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`);
+
+      const child = spawn("opencode", args, {
+        cwd: this.cwd,
+        shell: true,
+        stdio: ["ignore", "pipe", "inherit"] // Inherit stderr to show warnings directly
+      });
+
+      const rl = readline.createInterface({
+        input: child.stdout,
+        terminal: false
+      });
+
+      const commandsRun = [];
+      let eventCount = 0;
+
+      rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) return;
+
+        try {
+          const event = JSON.parse(trimmed);
+          eventCount++;
+
+          // 1. Stream agent output text in real-time to user
+          if (event.type === "text" && event.part?.text) {
+            process.stdout.write(event.part.text);
+          }
+
+          // 2. Capture tool executions/commands
+          if (event.type === "step_start" && event.part?.toolCalls) {
+            for (const call of event.part.toolCalls) {
+              if (call.name === "run_command" && call.args?.CommandLine) {
+                commandsRun.push(call.args.CommandLine);
+              }
+            }
+          }
+        } catch {
+          // If a line is not valid JSON (e.g. starting/finishing logs), print it directly
+          console.log(trimmed);
+        }
+      });
+
+      child.on("close", (code) => {
+        console.log("\n[RUNTIME] OpenCode finished execution.");
+        resolve({
+          success: code === 0,
+          commandsRun,
+          eventCount
+        });
+      });
+
+      child.on("error", (err) => {
+        console.error(`\n[RUNTIME] Failed to launch opencode: ${err.message}`);
+        resolve({
+          success: false,
+          commandsRun,
+          eventCount: 0,
+          error: err.message
+        });
+      });
+    });
+  }
+}

package/src/core/sdd/validator.js

@@ -0,0 +1,67 @@
+import fs from "node:fs/promises";
+
+/**
+ * SpecValidator - Enforces "No Spec, No Code" rule.
+ * Validates existence, structure, and approval status of specifications.
+ */
+export class SpecValidator {
+  /**
+   * Validates a specification file.
+   * @param {string} filePath - Path to the .md specification file.
+   * @returns {Promise<{valid: boolean, reason?: string, tier?: string}>}
+   */
+  async validate(filePath) {
+    try {
+      const content = await fs.readFile(filePath, "utf8");
+
+      // Check for tiered tier identification
+      let tier = "unknown";
+      if (content.includes("[DEEP]")) tier = "deep";
+      else if (content.includes("[STANDARD]")) tier = "standard";
+      else if (content.includes("[TINY]")) tier = "tiny";
+
+      if (tier === "unknown") {
+        return { valid: false, reason: "Specification tier [DEEP|STANDARD|TINY] not identified in title." };
+      }
+
+      // Check for Metadata section
+      if (!content.includes("## Metadata")) {
+        return { valid: false, reason: "Missing '## Metadata' section.", tier };
+      }
+
+      // Check for Acceptance Criteria section
+      if (!content.includes("## Acceptance Criteria")) {
+        return { valid: false, reason: "Missing '## Acceptance Criteria' section.", tier };
+      }
+
+      // Check for Approved status
+      const lines = content.split("\n");
+      const statusLine = lines.find(l => l.includes("Status:"));
+      
+      if (!statusLine) {
+        return { valid: false, reason: "Missing Status field in Metadata section.", tier };
+      }
+
+      const statusPart = statusLine.split(":")[1]
+        .replace(/[\*_]/g, "") // Remove bold/italic markers
+        .trim()
+        .toUpperCase();
+      
+      // If it contains multiple options separated by |, it's not approved yet
+      if (statusPart.includes("|")) {
+        return { valid: false, reason: "Specification status is a template list. Must be explicitly set to 'APPROVED'.", tier };
+      }
+
+      if (statusPart !== "APPROVED") {
+        return { valid: false, reason: `Specification status is '${statusPart}', but must be 'APPROVED' to proceed.`, tier };
+      }
+
+      return { valid: true, tier };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return { valid: false, reason: `Specification file not found: ${filePath}` };
+      }
+      return { valid: false, reason: `Error reading specification: ${error.message}` };
+    }
+  }
+}

package/src/core/statuses.js

@@ -0,0 +1,29 @@
+export const COMPLETION_STATUSES = Object.freeze([
+  "PASS",
+  "PASS_WITH_NOTES",
+  "FAIL_DELEGATION_GATE",
+  "FAIL_QUALITY_GATE",
+  "FAIL",
+  "BLOCKED",
+  "NOT_RUN"
+]);
+
+export const RECOVERABLE_GATE_STATUSES = Object.freeze([
+  "FAIL_DELEGATION_GATE",
+  "FAIL_QUALITY_GATE"
+]);
+
+export const TERMINAL_FAILURE_STATUSES = Object.freeze([
+  "FAIL",
+  "BLOCKED"
+]);
+
+export function isRecoverableGateFailure(status) {
+  return RECOVERABLE_GATE_STATUSES.includes(status);
+}
+
+export function isTerminalFailure(status) {
+  return TERMINAL_FAILURE_STATUSES.includes(status);
+}
+
+export const COMPLETION_STATUS_TEXT = COMPLETION_STATUSES.join(" | ");

package/src/core/symlink-layout.js

@@ -0,0 +1,93 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function normalize(p) {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * For v3.0.0 "Elite Governance", we want an ULTRA-CLEAN root.
+ * Only "opencode" is symlinked to the root (required for OpenCode discovery).
+ * All other assets stay inside .ai-workflow/.
+ */
+const LINKABLE_ROOTS = new Set([
+  "opencode",
+  ".agents"
+]);
+
+const LINKABLE_FILES = new Set([]);
+
+export function buildSymlinkEntries({ templateFiles, installRoot = ".ai-workflow" }) {
+  const entries = new Map();
+
+  for (const relativePath of Object.keys(templateFiles)) {
+    if (relativePath === "opencode.jsonc") continue;
+
+    const normalized = normalize(relativePath);
+
+    if (LINKABLE_FILES.has(normalized)) {
+      entries.set(normalized, `${installRoot}/${normalized}`);
+      continue;
+    }
+
+    // Match composite paths in LINKABLE_ROOTS (e.g., "docs/policies")
+    for (const rootPath of LINKABLE_ROOTS) {
+      if (normalized === rootPath || normalized.startsWith(`${rootPath}/`)) {
+        entries.set(rootPath, `${installRoot}/${rootPath}`);
+        break;
+      }
+    }
+  }
+
+  return Array.from(entries.entries()).map(([linkPath, targetPath]) => ({ linkPath, targetPath }));
+}
+
+export async function isSymlinkTo(absoluteLinkPath, absoluteTargetPath) {
+  try {
+    const stat = await fs.lstat(absoluteLinkPath);
+    if (!stat.isSymbolicLink()) return false;
+    const currentTarget = await fs.readlink(absoluteLinkPath);
+    const resolved = path.resolve(path.dirname(absoluteLinkPath), currentTarget);
+    return resolved === absoluteTargetPath;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Internal symlink to satisfy opencode.jsonc paths without polluting the root.
+ * Creates .ai-workflow/opencode/skills -> ../.agents/skills
+ */
+export async function setupInternalSymlinks(cwd, installRoot = ".ai-workflow") {
+  const skillsLink = path.join(cwd, installRoot, "opencode/skills");
+  const skillsTarget = path.join(cwd, installRoot, ".agents/skills");
+
+  if (!(await exists(skillsTarget))) return;
+
+  try {
+    const stat = await fs.lstat(skillsLink).catch(() => null);
+    if (stat) {
+      if (stat.isSymbolicLink()) {
+        const current = await fs.readlink(skillsLink);
+        if (current === "../.agents/skills") return;
+        await fs.unlink(skillsLink);
+      } else {
+        return; // File exists, skip
+      }
+    }
+
+    const type = process.platform === "win32" ? "junction" : "dir";
+    await fs.symlink("../.agents/skills", skillsLink, type);
+  } catch {
+    // Silent fail for internal symlink
+  }
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}