@williambeto/ai-workflow 1.19.1 → 2.2.0

package/packages/ai-workflow/src/commands/doctor.js

@@ -1,168 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { exists, readJson, readJsonc } from "../core/filesystem.js";
-
-const REQUIRED_FILES = [
-  ".ai-workflow.json",
-  ".ai-workflow",
-  "README.workflow.md",
-  ".codex/prompts/README.md",
-  "opencode/README.md"
-];
-
-async function isSymlink(filePath) {
-  try {
-    const stat = await fs.lstat(filePath);
-    return stat.isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
-export async function runDoctor({ cwd }) {
-  let hasFailure = false;
-  let hasWarning = false;
-  let profile = "full";
-  let managedBlocks = [];
-
-  console.log("Doctor report:");
-
-  for (const relativePath of REQUIRED_FILES) {
-    const ok = await exists(path.join(cwd, relativePath));
-
-    if (ok) {
-      console.log(`PASS ${relativePath}`);
-    } else {
-      hasFailure = true;
-      console.log(`FAIL ${relativePath} missing`);
-    }
-  }
-
-  const configPath = path.join(cwd, ".ai-workflow.json");
-  if (await exists(configPath)) {
-    try {
-      const config = await readJson(configPath);
-
-      if (config.mode === "standalone") {
-        console.log("PASS standalone mode enabled");
-      } else {
-        hasWarning = true;
-        console.log("WARN mode is not standalone in .ai-workflow.json");
-      }
-
-      if (typeof config.profile === "string") {
-        profile = config.profile;
-        console.log(`PASS profile detected: ${profile}`);
-      } else {
-        hasWarning = true;
-        console.log("WARN profile is missing in .ai-workflow.json");
-      }
-
-      if (Array.isArray(config.managedBlocks)) {
-        managedBlocks = config.managedBlocks;
-      } else {
-        hasWarning = true;
-        console.log("WARN managedBlocks is missing or invalid in .ai-workflow.json");
-      }
-
-      if (config.compatibility?.codex && (config.compatibility?.opencode || config.compatibility?.claude)) {
-        console.log("PASS compatibility codex+opencode enabled");
-      } else {
-        hasWarning = true;
-        console.log("WARN compatibility flags are incomplete in .ai-workflow.json");
-      }
-
-      if (Array.isArray(config.managedFiles)) {
-        for (const relativePath of config.managedFiles) {
-          const fileExists = await exists(path.join(cwd, relativePath));
-          if (!fileExists) {
-            hasWarning = true;
-            console.log(`WARN managed file missing: ${relativePath}`);
-          }
-        }
-      } else {
-        hasWarning = true;
-        console.log("WARN managedFiles is missing or invalid in .ai-workflow.json");
-      }
-
-      if (Array.isArray(config.managedLinks)) {
-        for (const relativePath of config.managedLinks) {
-          const absolutePath = path.join(cwd, relativePath);
-          const linkExists = await exists(absolutePath);
-          if (!linkExists) {
-            hasWarning = true;
-            console.log(`WARN managed link missing: ${relativePath}`);
-            continue;
-          }
-
-          const isLink = await isSymlink(absolutePath);
-          if (!isLink) {
-            hasWarning = true;
-            console.log(`WARN managed link is not a symlink: ${relativePath}`);
-          }
-        }
-      } else {
-        hasWarning = true;
-        console.log("WARN managedLinks is missing or invalid in .ai-workflow.json");
-      }
-    } catch {
-      hasFailure = true;
-      console.log("FAIL .ai-workflow.json is not valid JSON");
-    }
-  }
-
-  if (profile !== "minimal") {
-    const opencodePath = path.join(cwd, "opencode.jsonc");
-    if (!(await exists(opencodePath))) {
-      hasFailure = true;
-      console.log("FAIL opencode.jsonc missing for operational/full profile");
-    } else {
-      try {
-        const opencodeConfig = await readJsonc(opencodePath);
-        console.log("PASS opencode.jsonc is valid JSONC");
-
-        const needsAgentDefault = managedBlocks.includes("opencode.jsonc:agent.default");
-        if (!needsAgentDefault || opencodeConfig.agent?.default) {
-          console.log("PASS opencode agent.default available");
-        } else {
-          hasFailure = true;
-          console.log("FAIL opencode agent.default missing");
-        }
-
-        const needsStart = managedBlocks.includes("opencode.jsonc:command.start");
-        if (!needsStart || opencodeConfig.command?.start) {
-          console.log("PASS opencode command.start available");
-        } else {
-          hasFailure = true;
-          console.log("FAIL opencode command.start missing");
-        }
-      } catch {
-        hasFailure = true;
-        console.log("FAIL opencode.jsonc is not valid JSONC");
-      }
-    }
-  }
-
-  const packageJsonPath = path.join(cwd, "package.json");
-  if (await exists(packageJsonPath)) {
-    try {
-      const packageJson = await readJson(packageJsonPath);
-      const scripts = packageJson.scripts ?? {};
-
-      if (!scripts.validate) {
-        hasWarning = true;
-        console.log("WARN package.json has no validate script");
-      }
-    } catch {
-      hasFailure = true;
-      console.log("FAIL package.json is not valid JSON");
-    }
-  }
-
-  const finalStatus = hasFailure ? "FAIL" : hasWarning ? "PASS_WITH_NOTES" : "PASS";
-  console.log(`Final status: ${finalStatus}`);
-
-  if (hasFailure) {
-    process.exitCode = 1;
-  }
-}

package/packages/ai-workflow/src/commands/guide.js

@@ -1,194 +0,0 @@
-import readline from "readline";
-
-function ask(rl, question) {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => resolve(answer.trim()));
-  });
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-const TOOLS = [
-  {
-    tool: "OpenCode",
-    icon: "⚡",
-    description: "Best integrated experience — commands, agents, routing built-in",
-    commands: ["/start", "/plan", "/execute", "/review", "/validate", "/ship"],
-    next: "Run `opencode` in your project, then try `/start` to begin.",
-  },
-  {
-    tool: "Codex",
-    icon: "📋",
-    description: "Prompt-driven workflow with explicit manual orchestration",
-    commands: ["codex:start", "codex:plan", "codex:execute", "codex:review", "codex:validate"],
-    next: "Run `codex` in your project, then use the command prompts from `.codex/prompts/`.",
-  },
-];
-
-const WORKFLOW_GOALS = [
-  {
-    id: "new-project",
-    label: "Start a new project",
-    icon: "🆕",
-    hint: "You have a new or empty repository and want to apply the workflow.",
-    steps: [
-      "1. Run `npx @williambeto/ai-workflow init --yes` to install workflow assets",
-      "2. Run `npx @williambeto/ai-workflow doctor` to verify installation",
-      "3. Define the project goal and constraints",
-      "4. Create the first requirement using prompts/01-create-requirement.md",
-      "5. Follow the workflow: spec → plan → PR breakdown → implement → validate",
-    ],
-  },
-  {
-    id: "feature-pr",
-    label: "Deliver a feature or fix",
-    icon: "🔧",
-    hint: "You have a specific feature or bug fix to implement.",
-    steps: [
-      "1. Clarify the requirement: what, who, scope, acceptance criteria",
-      "2. Use /plan (OpenCode) or plan-from-requirement.md (Codex) to create the plan",
-      "3. Break into small PRs with prompts/04-breakdown-prs.md",
-      "4. Implement only PR 1",
-      "5. Review, validate, then continue to next PR",
-    ],
-  },
-  {
-    id: "audit",
-    label: "Audit existing work",
-    icon: "🔍",
-    hint: "You want to review, validate, or audit an existing implementation.",
-    steps: [
-      "1. Use /review (OpenCode) or review-implementation.md (Codex)",
-      "2. Validate with /validate (OpenCode) or validate-work.md (Codex)",
-      "3. Check: lint, typecheck, test, build",
-      "4. Review PR scope and evidence",
-      "5. Approve or request changes",
-    ],
-  },
-  {
-    id: "deploy",
-    label: "Prepare for deployment",
-    icon: "🚀",
-    hint: "You need to review deployment readiness and create a rollback plan.",
-    steps: [
-      "1. Use /deploy (OpenCode) or deploy.md (Codex)",
-      "2. Review environment assumptions",
-      "3. Define smoke tests and rollback plan",
-      "4. Validate pre-deploy checks",
-      "5. Execute with monitoring",
-    ],
-  },
-];
-
-async function printBanner() {
-  console.log("\n⚙️  AI Workflow Kit — Quick Guide\n");
-  console.log("This guide helps you find the right next step based on your goal.");
-  await sleep(200);
-}
-
-async function detectInstalledAssets(cwd) {
-  const fs = await import("node:fs");
-  const checks = [
-    { path: ".codex/prompts/start-project.md", label: "Codex prompts" },
-    { path: "opencode.jsonc", label: "OpenCode config" },
-    { path: ".ai-workflow.json", label: "ai-workflow config" },
-    { path: "AGENTS.md", label: "AGENTS.md" },
-  ];
-  const found = checks.filter((c) => fs.existsSync(c.path));
-  return { found, total: checks.length };
-}
-
-function printGoal(goal) {
-  console.log(`\n${goal.icon} Goal: ${goal.label}`);
-  console.log(`   ${goal.hint}\n`);
-  for (const step of goal.steps) {
-    console.log(`   ${step}`);
-  }
-}
-
-function printTool(tool) {
-  console.log(`\n${tool.icon} Recommended for ${tool.tool}`);
-  console.log(`   ${tool.description}\n`);
-  console.log("   Key commands:");
-  for (const cmd of tool.commands) {
-    console.log(`   - ${cmd}`);
-  }
-  console.log(`\n   → ${tool.next}`);
-}
-
-async function runGuideSession({ cwd, rl }) {
-  await printBanner();
-
-  const { found, total } = await detectInstalledAssets(cwd);
-
-  if (found.length === 0) {
-    console.log("📦 No workflow assets detected. Starting from scratch.\n");
-    console.log("   Run `npx @williambeto/ai-workflow init --yes` first to install assets.\n");
-  } else {
-    console.log(`📋 Detected ${found.length}/${total} workflow assets installed.\n`);
-  }
-
-  console.log("What do you want to do?\n");
-  for (let i = 0; i < WORKFLOW_GOALS.length; i++) {
-    const goal = WORKFLOW_GOALS[i];
-    console.log(`  [${i + 1}] ${goal.icon} ${goal.label}`);
-  }
-  console.log("  [q] Quit guide\n");
-
-  const goalAnswer = await ask(rl, "Choose an option (1-4) or 'q': ");
-  const goalIndex = parseInt(goalAnswer, 10) - 1;
-
-  if (goalAnswer.toLowerCase() === "q") {
-    console.log("\n👍 Run `npx @williambeto/ai-workflow guide` anytime to return here.\n");
-    return;
-  }
-
-  const selectedGoal = WORKFLOW_GOALS[goalIndex];
-  if (!selectedGoal) {
-    console.log("\n⚠️  Invalid option. Run `npx @williambeto/ai-workflow guide` to restart.\n");
-    return;
-  }
-
-  printGoal(selectedGoal);
-
-  console.log("Which tool are you using?\n");
-  for (let i = 0; i < TOOLS.length; i++) {
-    const tool = TOOLS[i];
-    console.log(`  [${i + 1}] ${tool.icon} ${tool.tool}`);
-  }
-  console.log("  [b] Back to goals\n");
-
-  const toolAnswer = await ask(rl, "Choose an option (1-2) or 'b': ");
-  if (toolAnswer.toLowerCase() === "b") {
-    await runGuideSession({ cwd, rl });
-    return;
-  }
-
-  const toolIndex = parseInt(toolAnswer, 10) - 1;
-  const selectedTool = TOOLS[toolIndex];
-  if (!selectedTool) {
-    console.log("\n⚠️  Invalid option. Run `npx @williambeto/ai-workflow guide` to restart.\n");
-    return;
-  }
-
-  printTool(selectedTool);
-
-  console.log("\n📚 Full documentation: docs/npm-consumer-quickstart.md");
-  console.log("   Quick reference: runbooks/quick-start-guide.md\n");
-  console.log("👍 Run `npx @williambeto/ai-workflow guide` anytime to return here.\n");
-}
-
-export async function runGuide({ cwd }) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  try {
-    await runGuideSession({ cwd, rl });
-  } finally {
-    rl.close();
-  }
-}

package/packages/ai-workflow/src/core/opencode-merge.js

@@ -1,172 +0,0 @@
-import path from "node:path";
-import { exists, readJsonc, writeFileSafe } from "./filesystem.js";
-import { createManagedBackup } from "./backup.js";
-import { readPackageFile } from "./package-assets.js";
-
-const LEGACY_MARKER = "_aiWorkflowManaged";
-
-function loadCanonicalFullConfig() {
-  try {
-    const raw = readPackageFile("opencode.jsonc");
-    if (!raw) return null;
-    const parsed = JSON.parse(raw);
-
-    if (!parsed || typeof parsed !== "object") return null;
-    if (!parsed.agent || !parsed.command) return null;
-
-    if (!parsed.agent.default) {
-      parsed.agent.default = {
-        mode: "primary",
-        description: "Default OpenCode agent for this project",
-        prompt:
-          "You are the default OpenCode agent for this repository. Follow local project docs and validation commands."
-      };
-    }
-
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-function buildManagedConfig(profile = "full") {
-  const canonicalFull = profile === "full" ? loadCanonicalFullConfig() : null;
-  if (canonicalFull) {
-    return canonicalFull;
-  }
-
-  const fullPrimaryAgents =
-    profile === "full"
-      ? {
-          discovery: { mode: "primary", description: "Explore repository context", prompt: "{file:./opencode/agents/discovery.md}" },
-          planner: { mode: "primary", description: "Plan requirement-to-PR flow", prompt: "{file:./opencode/agents/planner.md}" },
-          implementer: { mode: "primary", description: "Implement scoped changes", prompt: "{file:./opencode/agents/implementer.md}" },
-          fixer: { mode: "primary", description: "Fix issues and regressions", prompt: "{file:./opencode/agents/fixer.md}" },
-          reviewer: { mode: "primary", description: "Review implementation quality", prompt: "{file:./opencode/agents/reviewer.md}" },
-          validator: { mode: "primary", description: "Validate with evidence", prompt: "{file:./opencode/agents/validator.md}" },
-          "release-manager": { mode: "primary", description: "Prepare release/deploy steps", prompt: "{file:./opencode/agents/release-manager.md}" },
-          "wordpress-engineer": { mode: "primary", description: "WordPress specialist role", prompt: "{file:./opencode/agents/wordpress-engineer.md}" },
-           "prompt-engineer": { mode: "primary", description: "Prompt/system design role", prompt: "{file:./opencode/agents/prompt-engineer.md}" },
-           "spec-engineer": { mode: "primary", description: "Create and review functional specifications", prompt: "{file:./opencode/agents/spec-engineer.md}" },
-          orchestrator: {
-            mode: "primary",
-            description: "Route work by safe workflow gates",
-            prompt: "{file:./opencode/agents/orchestrator.md}"
-          },
-        }
-      : {};
-
-  const fullSkills =
-    profile === "full"
-      ? {
-          "backend-implementer": { mode: "subagent", description: "Backend implementation specialist", prompt: "{file:./.agents/skills/backend-implementer/SKILL.md}" },
-          "build-and-validate": { mode: "subagent", description: "Build and validation specialist", prompt: "{file:./.agents/skills/build-and-validate/SKILL.md}" },
-          "pr-orchestrator": { mode: "subagent", description: "PR breakdown and flow specialist", prompt: "{file:./.agents/skills/pr-orchestrator/SKILL.md}" },
-          "deploy-engineer": { mode: "subagent", description: "Deploy and release specialist", prompt: "{file:./.agents/skills/deploy-engineer/SKILL.md}" },
-          "docs-writer": { mode: "subagent", description: "Documentation specialist", prompt: "{file:./.agents/skills/docs-writer/SKILL.md}" },
-          "frontend-implementer": { mode: "subagent", description: "Frontend implementation specialist", prompt: "{file:./.agents/skills/frontend-implementer/SKILL.md}" },
-          "interface-design": { mode: "subagent", description: "Interface design specialist", prompt: "{file:./.agents/skills/interface-design/SKILL.md}" },
-          "minimal-context": { mode: "subagent", description: "Minimal-context specialist", prompt: "{file:./.agents/skills/minimal-context/SKILL.md}" },
-          napkin: { mode: "subagent", description: "Project memory specialist", prompt: "{file:./.agents/skills/napkin/SKILL.md}" },
-          "opencode-agent-design": { mode: "subagent", description: "OpenCode agent design specialist", prompt: "{file:./.agents/skills/opencode-agent-design/SKILL.md}" },
-          "playwright-cli": { mode: "subagent", description: "Playwright specialist", prompt: "{file:./.agents/skills/playwright-cli/SKILL.md}" },
-          "product-manager": { mode: "subagent", description: "Product scope specialist", prompt: "{file:./.agents/skills/product-manager/SKILL.md}" },
-          "seo-audit": { mode: "subagent", description: "SEO audit specialist", prompt: "{file:./.agents/skills/seo-audit/SKILL.md}" },
-          "stack-variant-creator": { mode: "subagent", description: "Stack variant specialist", prompt: "{file:./.agents/skills/stack-variant-creator/SKILL.md}" },
-          "tech-lead": { mode: "subagent", description: "Technical lead specialist", prompt: "{file:./.agents/skills/tech-lead/SKILL.md}" },
-          tester: { mode: "subagent", description: "Testing specialist", prompt: "{file:./.agents/skills/tester/SKILL.md}" },
-          "token-economy": { mode: "subagent", description: "Token economy specialist", prompt: "{file:./.agents/skills/token-economy/SKILL.md}" },
-          "vue-nuxt": { mode: "subagent", description: "Vue/Nuxt architecture specialist", prompt: "{file:./.agents/skills/vue-nuxt/SKILL.md}" },
-          "wordpress-engineer": { mode: "subagent", description: "WordPress specialist", prompt: "{file:./.agents/skills/wordpress-engineer/SKILL.md}" }
-        }
-      : {};
-
-  const startAgent = profile === "full" ? "orchestrator" : "default";
-  return {
-    $schema: "https://opencode.ai/config.json",
-    agent: {
-      default: {
-        mode: "primary",
-        description: "Default OpenCode agent for this project",
-        prompt:
-          "You are the default OpenCode agent for this repository. Follow local project docs and validation commands."
-      },
-      ...fullPrimaryAgents,
-      ...fullSkills
-    },
-    command: {
-      start: {
-        description: "Start the local workflow",
-        agent: startAgent,
-        template:
-          "Use repository workflow docs as source of truth and ask for missing context before changes."
-      },
-      ...(profile === "full"
-        ? {
-            ship: { description: "Run end-to-end workflow", agent: "orchestrator", template: "Use orchestrator for gated workflow execution." },
-            plan: { description: "Plan from requirement to PR", agent: "planner", template: "Create requirement/spec/plan outputs with acceptance criteria." },
-            execute: { description: "Implement selected PR", agent: "implementer", template: "Implement one scoped PR with validation evidence." },
-            review: { description: "Review implementation", agent: "reviewer", template: "Review for regressions and acceptance criteria coverage." },
-            validate: { description: "Validate before merge", agent: "validator", template: "Run checks and report evidence-based readiness." }
-          }
-        : {})
-    }
-  };
-}
-
-export async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".ai-workflow-backups", profile = "full" } = {}) {
-  const targetPath = path.join(cwd, "opencode.jsonc");
-  const managed = buildManagedConfig(profile);
-
-  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/core/symlink-layout.js

@@ -1,54 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-function normalize(p) {
-  return p.split(path.sep).join("/");
-}
-
-const LINKABLE_ROOTS = new Set([
-  ".codex",
-  ".agents",
-  "opencode",
-  "prompts",
-  "templates",
-  "schemas",
-  "harness",
-  "checklists",
-  "runbooks"
-]);
-
-const LINKABLE_FILES = new Set(["README.workflow.md"]);
-
-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;
-    }
-
-    const first = normalized.split("/")[0];
-    if (LINKABLE_ROOTS.has(first)) {
-      entries.set(first, `${installRoot}/${first}`);
-    }
-  }
-
-  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;
-  }
-}