@williambeto/ai-workflow 2.1.0 → 2.2.0

package/README.md

@@ -3,25 +3,33 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@williambeto/ai-workflow)](https://www.npmjs.com/package/@williambeto/ai-workflow)
 
-AI Workflow Kit is an **OpenCode-first** software-delivery workflow for AI-assisted projects. It provides primary agents, specialist skills, proportional workflow modes, executable validation, and optional persisted evidence for full/release/audit work.
+The AI Workflow Kit is an npm/CLI package that installs a suite of agents, commands, skills, policies, and templates to guide a coding agent inside a project.
 
-## Installation
+The central promise is:
 
-### Current public release
+> "Transform a natural language request into a proportionate, safe, and verifiable software delivery."
 
-```bash
-npm install -g @williambeto/ai-workflow@latest
-```
+The workflow the product guarantees is:
 
-### Version 2 controlled rollout
+1. **Request**: Understand the actual request.
+2. **Planning**: Select the execution mode and workflow profile.
+3. **Branch Gate**: Never implement directly on main/master.
+4. **Delegation**: Atlas routes; Astra implements; Sage validates when appropriate; Phoenix remediates within a defined limit.
+5. **Implementation**: Deliver useful code, not just reports.
+6. **Validation**: Run observed validations and relevant tests, blocking false success.
+7. **Evidence**: Summarize changes, validations, and limitations.
 
-Install the current `2.1.0` candidate from the non-default `next` dist-tag:
+In practice, the kit is neither a frontend framework nor a UI library. It is an operational layer for software agents: it installs instructions and guardrails so that the agent can work more effectively inside the user's repository.
+
+## Installation
+
+### Current public release
 
 ```bash
-npm install -g @williambeto/ai-workflow@next
+npm install -g @williambeto/ai-workflow@latest
 ```
 
-To install the exact release directly, use `@williambeto/ai-workflow@2.1.0` after it is published. The `latest` tag remains on the public `1.x` line until explicit promotion.
+Use `latest` for the supported public release. Release notes record exact historical versions when needed.
 
 ## Quick start
 
@@ -30,9 +38,10 @@ mkdir workflow-test && cd workflow-test
 npm init -y
 ai-workflow init --yes
 ai-workflow doctor
+ai-workflow execute "Atlas, list all agents, subagents, skills, and commands in the project. Present them in a table with their name, description, and usage examples."
 ```
 
-Open the project in OpenCode and make a normal request. Atlas classifies the request, selects `quick`, `standard`, or `full`, and routes it to the appropriate owner.
+The CLI receives the natural request, classifies the intent, plans the workflow, switch/creates branch safely, delegates coding tasks to the OpenCode runtime adapter, validates changes, and runs bounded remediation if necessary before outputting the handoff summary.
 
 ## Modes and profiles
 

package/dist-assets/docs/visual-validation-guide.md

@@ -0,0 +1,76 @@
+# Visual E2E Validation & Semantic UX Quality Guide
+
+This guide explains how to extend the **AI Workflow Kit** to automate visual regression testing and UX aesthetic audits using Playwright and multimodal vision LLMs.
+
+---
+
+## 1. Automated Visual E2E Validation
+
+By default, the kit flags UI changes without screenshots as `PASS_WITH_NOTES`. To turn this into a strict, blocking quality gate, you can set up automated visual regression tests.
+
+### Step 1: Install Playwright
+Install Playwright in the consumer project:
+```bash
+npm install -D @playwright/test
+npx playwright install
+```
+
+### Step 2: Configure Visual Regression Specs
+Create a Playwright visual spec (e.g., `tests/visual/landing-page.spec.js`):
+```javascript
+import { test, expect } from '@playwright/test';
+
+test('landing page visual regression', async ({ page }) => {
+  // 1. Navigate to the local server
+  await page.goto('http://localhost:5173');
+
+  // 2. Capture and compare screenshots (Desktop & Mobile viewports)
+  await expect(page).toHaveScreenshot('landing-page-desktop.png', {
+    fullPage: true,
+    maxDiffPixels: 50 // Tolerable pixel variance
+  });
+
+  await page.setViewportSize({ width: 375, height: 812 });
+  await expect(page).toHaveScreenshot('landing-page-mobile.png', {
+    fullPage: true
+  });
+});
+```
+
+### Step 3: Link to the Quality Gate
+Add a `test:visual` script to your `package.json`:
+```json
+{
+  "scripts": {
+    "test:visual": "playwright test tests/visual"
+  }
+}
+```
+During the `QualityGuard` verification phase, the framework runs all test scripts. If a layout shift or visual bug occurs, Playwright will fail, and the kit will transition to `BLOCKED`, preventing implementation changes from being approved.
+
+---
+
+## 2. Semantic and Aesthetic Auditing (Vision LLM)
+
+Subjective quality (color harmony, readable contrast, visual hierarchy) cannot be checked by raw pixel diffs. Multimodal vision models (like Gemini Pro or Claude 3.5 Sonnet) can act as automated **UX Auditors**.
+
+### Architecture Workflow
+```text
+[Astra (Builder)] 
+  └── Generates Page HTML/CSS
+[Playwright Runner] 
+  └── Launches headless browser & takes screenshots
+[Sage (UX Auditor)]
+  └── Sends screenshots to Vision LLM with Design Checklist
+  └── Returns PASS or FAIL_QUALITY_GATE with layout feedback
+```
+
+### Prompt-Based UX Auditor Checklist
+You can configure a specialized `ux-auditor` agent or load a skill containing these rules:
+
+1. **Hierarchy & Composition**: The first fold must look like a cohesive layout. Check that headings, buttons, and graphics do not overlap or look cluttered.
+2. **Color Contrast & Accessibility**: Ensure contrast between text and background is high. Avoid using unstyled bright primary colors (e.g., plain red/blue/green) without proper styling.
+3. **Typography**: Typography must use a modern system (e.g., Google Fonts) instead of browser defaults. Line heights should be balanced.
+4. **Responsiveness**: Verify that the mobile render does not cut off text or overflow horizontally.
+
+If the Vision LLM finds aesthetic defects, it outputs a `FAIL_QUALITY_GATE` status along with coordinates or descriptions of the design bugs, which are then passed to the `HealerEngine` for remediation.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
+  "author": "José Willams",
   "type": "module",
   "private": false,
   "engines": {

package/src/cli.js

@@ -3,17 +3,20 @@ import { runInit } from "./commands/init.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runCollectEvidence } from "./commands/collect-evidence.js";
 import { runMasterOrchestrator } from "./commands/run.js";
+import { runExecute } from "./commands/execute.js";
 
 function printHelp() {
   console.log(`ai-workflow
 
 Usage:
+  ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
   ai-workflow run --spec-path=<path>
   ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--gemini] [--claude] [--codex] [--profile=<profile>]
   ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]
   ai-workflow doctor
 
 Commands:
+  execute           Orchestrate execution of a natural request through the state machine
   run               Proportionate orchestrator with branch safety, validation, and bounded remediation
   init              Install AI workflow defaults (OpenCode). --profile=standard (default) or --profile=full (adds examples)
   collect-evidence  Run observed project validation; persists EVIDENCE.json only for full mode
@@ -26,6 +29,7 @@ function parseFlags(args) {
   const profileEqArg = args.find((arg) => arg.startsWith("--profile="));
   const taskArg = args.find((arg) => arg.startsWith("--task="));
   const modeArg = args.find((arg) => arg.startsWith("--mode="));
+  const requestArg = args.find((arg) => arg.startsWith("--request="));
   const profileIdx = args.indexOf("--profile");
   const profileVal = profileEqArg
     ? profileEqArg.replace("--profile=", "")
@@ -46,7 +50,8 @@ function parseFlags(args) {
     specPath: specPathArg ? specPathArg.replace("--spec-path=", "") : undefined,
     profile: profileVal || undefined,
     taskSlug: taskArg ? taskArg.replace("--task=", "") : undefined,
-    mode: modeArg ? modeArg.replace("--mode=", "") : undefined
+    mode: modeArg ? modeArg.replace("--mode=", "") : undefined,
+    request: requestArg ? requestArg.replace("--request=", "") : undefined
   };
 }
 
@@ -64,6 +69,19 @@ export async function runCli(args) {
     return;
   }
 
+  if (command === "execute") {
+    const flags = parseFlags(args.slice(1));
+    const positionals = args.slice(1).filter((arg) => !arg.startsWith("-"));
+    const request = flags.request || positionals.join(" ");
+    await runExecute({
+      cwd: process.cwd(),
+      naturalRequest: request,
+      override: args.includes("--override") ? "authorized-override-token" : undefined,
+      taskSlug: flags.taskSlug
+    });
+    return;
+  }
+
   if (command === "run") {
     await runMasterOrchestrator({
       cwd: process.cwd(),

package/src/commands/execute.js

@@ -0,0 +1,172 @@
+import { RequestClassifier } from "../core/request-classifier.js";
+import { ExecutionPlanner } from "../core/execution-planner.js";
+import { WorkflowStateMachine } from "../core/workflow-state-machine.js";
+import { BranchGate } from "../core/gates/branch-gate.js";
+import { OpenCodeAdapter } from "../core/runtime/opencode-adapter.js";
+import { runCollectEvidence } from "./collect-evidence.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { HandoffEngine } from "../core/handoff/handoff-engine.js";
+import { HealerEngine } from "../core/healing/healer-engine.js";
+import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
+import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32) || "task";
+}
+
+function combineValidation(evidence, quality) {
+  const statuses = [evidence.internalStatus, quality.overallStatus];
+  let overallStatus = "PASS";
+  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
+  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
+  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
+  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
+  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
+  return { overallStatus, evidence, quality };
+}
+
+/**
+ * runExecute - Coordinators natural request execution.
+ */
+export async function runExecute({ cwd, naturalRequest, override, taskSlug: taskSlugOverride }) {
+  if (!naturalRequest || !naturalRequest.trim()) {
+    throw new Error("Missing request. Please provide a natural request string via positional arguments or --request flag.");
+  }
+
+  const taskSlug = taskSlugOverride || slugify(naturalRequest);
+  console.log(`\n[AI WORKFLOW] Executing natural request intake [slug: ${taskSlug}]...\n`);
+
+  const stateMachine = new WorkflowStateMachine();
+
+  // 1. Classification
+  const classifier = new RequestClassifier();
+  const classification = classifier.classify(naturalRequest);
+  console.log(`[CLASSIFIED] Intent: ${classification.intent}, Mode: ${classification.mode}, Profile: ${classification.profile}`);
+  stateMachine.transitionTo("CLASSIFIED");
+
+  // 2. Planning
+  const planner = new ExecutionPlanner({ cwd });
+  const plan = planner.plan(classification, taskSlug);
+  console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
+  stateMachine.transitionTo("PLANNED");
+
+  // 3. Branch Gate
+  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
+  const gateResult = branchGate.check(override, {
+    autoRecover: true,
+    taskSlug,
+    readOnly: !plan.branchNeeded
+  });
+
+  if (gateResult.blocked) {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
+  }
+  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
+  stateMachine.transitionTo("BRANCH_READY");
+
+  // 4. Spec template creation (for full/deep mode)
+  if (plan.specPath) {
+    const fullSpecPath = path.join(cwd, plan.specPath);
+    const specExists = await fs.access(fullSpecPath).then(() => true).catch(() => false);
+    if (!specExists) {
+      await fs.mkdir(path.dirname(fullSpecPath), { recursive: true });
+      const specTemplatePath = path.join(cwd, ".ai-workflow/templates/specs/standard.md");
+      const templateContent = await fs.readFile(specTemplatePath, "utf8").catch(() => {
+        return `# [STANDARD] Specification: ${classification.request}\n\n## Metadata\n\n- ID: SPEC-${taskSlug}\n- Author: Spec-Engineer\n- Status: DRAFT\n- Date: ${new Date().toISOString().split("T")[0]}\n\n## Functional Requirements\n\n- ${classification.request}\n\n## Technical Implementation Plan\n\n### Files to Create/Modify\n\n- \`src/index.js\`\n\n## Acceptance Criteria\n\n- [ ] Implemented successfully\n\n## Testing Strategy\n\n- [ ] Behavior tests pass`;
+      });
+      await fs.writeFile(fullSpecPath, templateContent);
+      console.log(`[EXECUTE] Created DRAFT specification template at: ${plan.specPath}`);
+    }
+  }
+
+  // 5. Delegation
+  stateMachine.transitionTo("DELEGATED");
+  stateMachine.transitionTo("IMPLEMENTING");
+
+  const adapter = new OpenCodeAdapter({ cwd });
+  let promptMsg = classification.request;
+  if (plan.specPath) {
+    promptMsg = `Please review and fill in the specification file at: ${plan.specPath}. Make sure to change the Status field to 'APPROVED' in the Metadata section, and then implement the behavior described.`;
+  }
+
+  const runResult = await adapter.execute(promptMsg, {
+    agent: plan.owner,
+    dangerouslySkipPermissions: true
+  });
+
+  if (!runResult.success) {
+    console.error(`[EXECUTE] OpenCode adapter execution reported failure.`);
+  }
+  stateMachine.transitionTo("IMPLEMENTED");
+
+  // 6. Validation
+  stateMachine.transitionTo("VALIDATING");
+  const validateWorkflow = async () => {
+    const evidence = await runCollectEvidence({
+      cwd,
+      exitOnError: false,
+      taskSlug,
+      mode: plan.mode,
+      profile: plan.profile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+    });
+    const quality = await new QualityGuard({ cwd, taskSlug, mode: plan.mode }).verify();
+    return combineValidation(evidence, quality);
+  };
+
+  let result = await validateWorkflow();
+
+  // 7. Bounded Remediation
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    stateMachine.transitionTo("REMEDIATING");
+    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${plan.mode} remediation.`);
+    const executor = createCliRemediationExecutor(cwd);
+    const healer = new HealerEngine({ cwd, mode: plan.mode, taskSlug });
+    
+    result = await healer.run({
+      initialResult: result,
+      validate: async () => {
+        stateMachine.transitionTo("REVALIDATING");
+        const res = await validateWorkflow();
+        return res;
+      },
+      remediate: executor
+    });
+  }
+
+  if (isTerminalFailure(result.overallStatus)) {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: Validation could not be resolved safely.`);
+  }
+
+  // 8. Finalizer
+  const finalState = result.overallStatus === "PASS"
+    ? "COMPLETED"
+    : result.overallStatus === "PASS_WITH_NOTES"
+      ? "COMPLETED_WITH_NOTES"
+      : "BLOCKED";
+
+  stateMachine.transitionTo(finalState);
+
+  console.log("\n--- Final Handoff ---");
+  const handoffEngine = new HandoffEngine({ cwd });
+  const handoffPath = await handoffEngine.generate({
+    taskId: taskSlug,
+    status: finalState,
+    specPaths: plan.specPath ? [plan.specPath] : [],
+    evidence: result.evidence,
+    nextActions: `Profile ${plan.profile}. Observed execution completed with status ${finalState}.`
+  });
+
+  console.log(`\n[AI WORKFLOW COMPLETE] ${finalState}`);
+  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
+
+  return { ...result, stateHistory: stateMachine.getHistory() };
+}

package/src/commands/run.js

@@ -99,6 +99,7 @@ export async function runMasterOrchestrator({ cwd, specPath, override, remediati
     taskId: path.basename(specPath, ".md"),
     status: result.overallStatus,
     specPaths: [specPath],
+    evidence: result.evidence,
     nextActions: `Profile ${workflowProfile}. Observed validation completed. Ready for review or explicitly approved release actions.`
   });
 

package/src/core/execution-planner.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+/**
+ * ExecutionPlanner - Formulates a minimum operational plan based on classification.
+ */
+export class ExecutionPlanner {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Generates an execution plan.
+   * @param {Object} classification - The output of RequestClassifier.
+   * @param {string} taskSlug - Descriptive slug for the task.
+   * @returns {Object} Operational plan contract.
+   */
+  plan(classification, taskSlug = "task") {
+    const remediationLimit = classification.mode === "full" ? 3 : classification.mode === "quick" ? 1 : 2;
+    const branchNeeded = classification.intent === "write";
+    const specPath = classification.specNeeded
+      ? path.join("docs/workflows", taskSlug, "spec.md")
+      : null;
+
+    // Build default expected validations based on the resolved profile
+    const validationsExpected = [];
+    if (classification.validationNeeded) {
+      validationsExpected.push("test");
+      if (classification.profile.startsWith("frontend")) {
+        validationsExpected.push("lint", "build");
+      } else if (classification.profile === "backend-api") {
+        validationsExpected.push("lint");
+      }
+    }
+
+    const restrictions = [
+      "Never commit or push directly to main/master.",
+      "Always execute behavior tests for new or modified behavior."
+    ];
+
+    if (classification.risk === "high") {
+      restrictions.push("Require independent validation review.");
+    }
+
+    return {
+      objective: classification.request,
+      scope: classification.intent === "read-only" ? "Analysis and verification" : "Implementation of requested behavior",
+      restrictions,
+      owner: classification.owner,
+      skills: [...classification.skills],
+      branchNeeded,
+      branchName: branchNeeded ? `feat/${taskSlug}` : null,
+      validationsExpected,
+      remediationLimit,
+      specPath,
+      mode: classification.mode,
+      profile: classification.profile
+    };
+  }
+}

package/src/core/gates/branch-gate.js

@@ -63,13 +63,44 @@ export class BranchGate {
     return candidate;
   }
 
+  getCurrentBranch() {
+    try {
+      return this.run("git branch --show-current") || this.run("git symbolic-ref --short HEAD") || "unknown";
+    } catch {
+      try {
+        return this.run("git symbolic-ref --short HEAD") || "unknown";
+      } catch {
+        return "unknown";
+      }
+    }
+  }
+
   /**
    * @param {string} override
-   * @param {{autoRecover?: boolean, taskSlug?: string}} options
+   * @param {{autoRecover?: boolean, taskSlug?: string, readOnly?: boolean}} options
    */
-  check(override = "", { autoRecover = false, taskSlug = "implementation" } = {}) {
+  check(override = "", { autoRecover = false, taskSlug = "implementation", readOnly = false } = {}) {
+    if (readOnly) {
+      const currentBranch = this.getCurrentBranch();
+      return { blocked: false, branch: currentBranch, recovered: false, readOnly: true };
+    }
+
     try {
-      const currentBranch = this.run("git rev-parse --abbrev-ref HEAD");
+      // Enforce fail-closed: verify inside worktree first
+      try {
+        this.run("git rev-parse --is-inside-work-tree");
+      } catch (e) {
+        const reason = "Not inside a Git repository or Git is unavailable. Implementation work is blocked.";
+        this.log(`BLOCKED: ${reason}`);
+        return { blocked: true, branch: "unknown", reason };
+      }
+
+      const currentBranch = this.getCurrentBranch();
+      if (currentBranch === "unknown") {
+        const reason = "Could not determine current Git branch name. Implementation work is blocked.";
+        this.log(`BLOCKED: ${reason}`);
+        return { blocked: true, branch: "unknown", reason };
+      }
       const isProtected = this.protectedBranches.includes(currentBranch);
       if (!isProtected) return { blocked: false, branch: currentBranch, recovered: false };
 
@@ -107,7 +138,9 @@ export class BranchGate {
         reason: `${reason} Enable safe auto-recovery or use AI_OVERRIDE with a concrete justification.`
       };
     } catch (error) {
-      return { blocked: false, branch: "unknown", error: error.message, recovered: false };
+      const reason = `Git command failure on branch gate check: ${error.message}`;
+      this.log(`BLOCKED: ${reason}`);
+      return { blocked: true, branch: "unknown", error: error.message, reason, recovered: false };
     }
   }
 }

package/src/core/handoff/handoff-engine.js

@@ -10,12 +10,12 @@ export class HandoffEngine {
     this.cwd = cwd;
   }
 
-  /**
+   /**
    * Generates a handoff packet.
    * @param {Object} data - Context data.
    * @returns {Promise<string>} The generated packet content.
    */
-  async generate({ taskId, author, status, specPaths = [], nextActions }) {
+  async generate({ taskId, author, status, specPaths = [], nextActions, evidence = null }) {
     const timestamp = new Date().toISOString();
     
     // 1. Collect Specs content
@@ -33,27 +33,53 @@ export class HandoffEngine {
     // 2. Capture Git Diff
     let gitDiff = "No changes detected.";
     try {
-      gitDiff = execSync("git diff HEAD", { cwd: this.cwd, encoding: "utf8" }).trim() || "No changes detected.";
+      gitDiff = execSync("git diff HEAD", { cwd: this.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || "No changes detected.";
     } catch (err) {
       gitDiff = `[Error capturing diff: ${err.message}]`;
     }
 
-    // 3. Read EVIDENCE.json
+    // 3. Read EVIDENCE.json or use provided in-memory evidence
     let evidenceJson = "{}";
     let evidenceSummary = "No evidence found.";
-    const evidencePath = path.join(this.cwd, "EVIDENCE.json");
-    try {
-      const content = await fs.readFile(evidencePath, "utf8");
-      const data = JSON.parse(content);
+    if (evidence) {
+      const data = typeof evidence === "string" ? JSON.parse(evidence) : evidence;
       evidenceJson = JSON.stringify(data, null, 2);
-      evidenceSummary = `Status: ${data.status}, Commands: ${data.commands?.length || 0}`;
-    } catch (err) {
-      // Optional: don't fail if evidence is missing
+      evidenceSummary = `Status: ${data.status || data.internalStatus || "unknown"}, Commands: ${data.commands?.length || 0}`;
+    } else {
+      const evidencePath = path.join(this.cwd, "EVIDENCE.json");
+      try {
+        const content = await fs.readFile(evidencePath, "utf8");
+        const data = JSON.parse(content);
+        evidenceJson = JSON.stringify(data, null, 2);
+        evidenceSummary = `Status: ${data.status}, Commands: ${data.commands?.length || 0}`;
+      } catch (err) {
+        // Optional: don't fail if evidence is missing
+      }
     }
 
     // 4. Populate Template
-    const templatePath = path.join(import.meta.dirname, "../../../dist-assets/templates/HANDOFF.template.md");
-    let template = await fs.readFile(templatePath, "utf8");
+    const possibleTemplatePaths = [
+      path.join(this.cwd, ".ai-workflow/templates/HANDOFF.template.md"),
+      path.join(this.cwd, ".ai-workflow/harness/handoffs/HANDOFF.template.md"),
+      path.join(import.meta.dirname, "../../../dist-assets/templates/HANDOFF.template.md"),
+      path.join(import.meta.dirname, "../../../assets/templates/HANDOFF.template.md")
+    ];
+
+    let template = null;
+    let lastError = null;
+
+    for (const tPath of possibleTemplatePaths) {
+      try {
+        template = await fs.readFile(tPath, "utf8");
+        break;
+      } catch (err) {
+        lastError = err;
+      }
+    }
+
+    if (!template) {
+      throw new Error(`CRITICAL FAILURE: Could not locate HANDOFF.template.md. Tried paths:\n${possibleTemplatePaths.join("\n")}\nLast error: ${lastError?.message}`);
+    }
 
     const packet = template
       .replace("${TASK_ID}", taskId || "unknown")

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/templates.js

@@ -102,6 +102,9 @@ function buildRuntimeFiles({ includeFormalEvidence = false } = {}) {
   const dpContent = readPackageFile("dist-assets/docs/design-patterns-policy.md");
   if (dpContent !== null) files["docs/design-patterns-policy.md"] = dpContent;
 
+  const visualValidationGuide = readPackageFile("dist-assets/docs/visual-validation-guide.md");
+  if (visualValidationGuide !== null) files["docs/visual-validation-guide.md"] = visualValidationGuide;
+
   const governancePolicies = discoverPackageFiles("dist-assets/docs/policies");
   for (const [relPath, content] of Object.entries(governancePolicies)) {
     const targetPath = relPath.replace(/^dist-assets\//, "");

package/src/core/workflow-state-machine.js

@@ -0,0 +1,46 @@
+/**
+ * WorkflowStateMachine - Enforces state transitions for the AI Workflow loop.
+ */
+export class WorkflowStateMachine {
+  constructor() {
+    this.state = "RECEIVED";
+    this.history = [{ state: this.state, timestamp: new Date().toISOString() }];
+
+    this.validTransitions = {
+      RECEIVED: ["CLASSIFIED", "BLOCKED"],
+      CLASSIFIED: ["PLANNED", "BLOCKED"],
+      PLANNED: ["BRANCH_READY", "BLOCKED"],
+      BRANCH_READY: ["DELEGATED", "BLOCKED"],
+      DELEGATED: ["IMPLEMENTING", "BLOCKED"],
+      IMPLEMENTING: ["IMPLEMENTED", "BLOCKED"],
+      IMPLEMENTED: ["VALIDATING", "BLOCKED"],
+      VALIDATING: ["COMPLETED", "COMPLETED_WITH_NOTES", "REMEDIATING", "BLOCKED"],
+      REMEDIATING: ["REVALIDATING", "BLOCKED"],
+      REVALIDATING: ["COMPLETED", "COMPLETED_WITH_NOTES", "REMEDIATING", "BLOCKED"],
+      COMPLETED: [],
+      COMPLETED_WITH_NOTES: [],
+      BLOCKED: []
+    };
+  }
+
+  /**
+   * Transitions the machine to a new state.
+   * @param {string} newState - The state to transition to.
+   */
+  transitionTo(newState) {
+    const allowed = this.validTransitions[this.state];
+    if (!allowed || !allowed.includes(newState)) {
+      throw new Error(`Invalid state transition: ${this.state} -> ${newState}`);
+    }
+    this.state = newState;
+    this.history.push({ state: this.state, timestamp: new Date().toISOString() });
+  }
+
+  getCurrentState() {
+    return this.state;
+  }
+
+  getHistory() {
+    return [...this.history];
+  }
+}