@williambeto/ai-workflow 2.3.1 → 2.3.5

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [2.3.2] - 2026-06-19
+
+### Documentation
+- Clarified first-time usage with `npx @williambeto/ai-workflow init`.
+- Clarified local installed-package alias usage with `npx aw init`, `npx aw doctor`, and `npx aw run`.
+
+### Notes
+- No CLI behavior changed.
+- No runtime behavior changed.
+
 ## [2.3.1] - 2026-06-18
 
 ### Fixed

package/README.md

@@ -21,26 +21,30 @@ The workflow the product guarantees is:
 
 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
+## Installation and Usage
 
-### Current public release
+### First-time usage
+
+Use the full package command when running the kit before it is installed in a project:
 
 ```bash
-npm install -g @williambeto/ai-workflow@latest
+npx @williambeto/ai-workflow init
 ```
 
-Use `latest` for the supported public release. Release notes record exact historical versions when needed.
+### Short alias after installation
 
-## Quick start
+After installing AI Workflow Kit in a project, the shorter `aw` binary is available through `node_modules/.bin`:
 
 ```bash
-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."
+npm install -D @williambeto/ai-workflow
+
+npx aw init
+npx aw doctor
+npx aw run "Atlas, list all agents, subagents, skills, and commands in the project. Present them in a table with their name, description, and usage examples."
 ```
 
+The `aw` binary is an alias for the same CLI entrypoint as `ai-workflow`.
+
 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/agents/astra.md

@@ -38,6 +38,7 @@ Astra implements only after branch gate is satisfied. It keeps changes bounded t
 * Run relevant validation after implementation.
 * Preserve existing behavior and unrelated dirty work.
 * Load `frontend-development` and `ui-ux-design` skills only when they apply. Use selected profile as quality guidance.
+* Implement all frontend, backend, or full-stack tasks using framework-native or stack-native paradigms (e.g., framework-native React/Next.js components, Vue/Nuxt files, or project stack paradigms rather than generic standalone HTML/JS prototypes) unless explicitly asked otherwise by the user.
 * Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `PROCEDURE_UI_CHECKLIST.md`.
 
 ## Allowed tools

package/dist-assets/skills/architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: architecture
 description: Skill-backed capability for architectural design and modularity
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Architecture PromptContract

package/dist-assets/skills/backend-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: backend-development
 description: Skill-backed capability for backend APIs, routes, and data persistence
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Backend Development PromptContract

package/dist-assets/skills/deployment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deployment
 description: Skill-backed capability for deployment planning, environments, and validation
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Deployment PromptContract

package/dist-assets/skills/design-principles/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: design-principles
 description: Skill-backed capability for clean, maintainable software design patterns
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Design Principles PromptContract

package/dist-assets/skills/documentation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: documentation
 description: Skill-backed capability for writing and verifying technical documentation
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Documentation PromptContract

package/dist-assets/skills/frontend-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frontend-development
 description: Skill-backed capability for frontend UI components and styles
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Frontend Development PromptContract
@@ -29,6 +29,7 @@ Do not trust:
 ## Constraints
 - Follow accessibility (WCAG/ARIA) guidelines.
 - Support responsive layouts.
+- Deliver UI/frontend artifacts native to the detected or specified project stack (using framework-native or stack-native architectures like React, Vue, Nuxt, WordPress PHP, etc. rather than standalone HTML/JS files) unless explicitly specified otherwise.
 - Do not claim execution without evidence.
 
 ## Allowed tools

package/dist-assets/skills/full-stack-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: full-stack-development
 description: Skill-backed capability for coordinating frontend and backend updates
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Full-Stack Development PromptContract

package/dist-assets/skills/optimize-tokens/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: optimize-tokens
 description: Skill-backed capability for reducing context size and optimizing token economy
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Optimize Tokens PromptContract

package/dist-assets/skills/pr-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pr-workflow
 description: Skill-backed capability for branch gates and pull request verification
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # PR Workflow PromptContract

package/dist-assets/skills/product-discovery/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: product-discovery
 description: Skill-backed capability for project and product discovery work
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Product Discovery PromptContract

package/dist-assets/skills/product-planning/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: product-planning
 description: Skill-backed capability for translating needs into scoped requirements
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Product Planning PromptContract

package/dist-assets/skills/project-memory/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: project-memory
 description: Skill-backed capability for project memory, ADRs, and decision records
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Project Memory PromptContract

package/dist-assets/skills/prompt-engineer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prompt-engineer
 description: Skill-backed capability for refining prompts and instructions
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Prompt Engineering PromptContract

package/dist-assets/skills/qa-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: qa-workflow
 description: Skill-backed capability for quality gates and validation tests
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Quality Assurance PromptContract

package/dist-assets/skills/refactoring/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: refactoring
 description: Skill-backed capability for code refactoring and bug-fixing
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Refactoring and Remediation PromptContract

package/dist-assets/skills/release-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: release-workflow
 description: Skill-backed capability for release management and validation
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Release Workflow PromptContract

package/dist-assets/skills/spec-driven-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-driven-development
 description: Skill-backed capability for converting requirements to testable specs
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Spec-Driven Development PromptContract

package/dist-assets/skills/technical-leadership/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: technical-leadership
 description: Skill-backed capability for high-level technical decisions and reviews
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Technical Leadership PromptContract

package/dist-assets/skills/ui-ux-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-ux-design
 description: Skill-backed capability for user interface and experience design guidelines
-governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # UI-UX Design PromptContract

package/docs/getting-started/upgrading-to-v2.md

@@ -19,10 +19,17 @@ Version `2.x` is a breaking public line from the previous `1.x` line. Test upgra
 
 4. Inspect initialization before applying it:
 
+   For first-time or pre-installation usage:
    ```bash
-   ai-workflow init --dry-run
-   ai-workflow init --yes
-   ai-workflow doctor
+   npx @williambeto/ai-workflow init --dry-run
+   npx @williambeto/ai-workflow init --yes
+   ```
+
+   After installing AI Workflow Kit locally in your project:
+   ```bash
+   npx aw init --dry-run
+   npx aw init --yes
+   npx aw doctor
    ```
 
 ## Main changes in version 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.3.1",
+  "version": "2.3.5",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -29,7 +29,8 @@
     "url": "https://github.com/williambeto/ai-workflow/issues"
   },
   "bin": {
-    "ai-workflow": "bin/ai-workflow.js"
+    "ai-workflow": "bin/ai-workflow.js",
+    "aw": "bin/ai-workflow.js"
   },
   "files": [
     "bin",

package/src/commands/execute.js

@@ -327,6 +327,14 @@ export async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverri
       console.log(`\n[FINALIZER BLOCKED] BLOCKED: workspace did not stabilize`);
       console.log(`Final changes detected:`, integrity.changes);
       finalStatus = "FAIL_QUALITY_GATE";
+    } else {
+      // Workspace stabilized, now run Artifact Fidelity Gate
+      const fidelityResult = await finalizer.verifyFidelity(result.evidence?.changedFiles);
+      if (!fidelityResult.passed) {
+        console.log(`\n[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
+        console.log(`Reason: ${fidelityResult.reason}`);
+        finalStatus = "FAIL_QUALITY_GATE";
+      }
     }
 
     const finalState = finalStatus === "PASS"

package/src/core/finalization/finalizer.js

@@ -1,4 +1,7 @@
 import { WorkspaceSnapshot } from "./workspace-snapshot.js";
+import { DeliveryDecisionEngine } from "../validation/delivery-decision-engine.js";
+import { ArtifactFidelityGate } from "../validation/artifact-fidelity-gate.js";
+import { execSync } from "node:child_process";
 
 export class Finalizer {
   constructor({ cwd = process.cwd() } = {}) {
@@ -6,6 +9,42 @@ export class Finalizer {
     this.snapshotManager = new WorkspaceSnapshot({ cwd });
   }
 
+  getChangedFilesFromGit() {
+    try {
+      const files = new Set();
+      // Unstaged changes
+      const diff = execSync("git diff --name-only HEAD", { cwd: this.cwd, encoding: "utf8" });
+      diff.split("\n").map(f => f.trim()).filter(Boolean).forEach(f => files.add(f));
+      
+      // Untracked/staged status
+      const status = execSync("git status --short --untracked-files=all", { cwd: this.cwd, encoding: "utf8" });
+      status.split("\n").forEach(line => {
+        const match = line.match(/^(?:[ MADRCU?!]{2}\s+|[MADRCU?!]\s+)(.+)$/);
+        if (match) {
+          const candidate = match[1].trim();
+          const renamed = candidate.includes(" -> ") ? candidate.split(" -> ").at(-1) : candidate;
+          if (renamed) files.add(renamed);
+        }
+      });
+      return [...files].sort();
+    } catch {
+      return [];
+    }
+  }
+
+  async verifyFidelity(changedFiles = null) {
+    const filesToCheck = changedFiles || this.getChangedFilesFromGit();
+    const decisionEngine = new DeliveryDecisionEngine({ cwd: this.cwd });
+    const deliveryClass = await decisionEngine.determineClass(filesToCheck);
+    const fidelityGate = new ArtifactFidelityGate({ cwd: this.cwd, deliveryClass });
+    const result = await fidelityGate.verify(filesToCheck);
+    return {
+      passed: result.passed,
+      reason: result.reason,
+      deliveryClass
+    };
+  }
+
   /**
    * Compares the current workspace state with a previously captured snapshot.
    * @param {Object} previousSnapshot - The snapshot object captured earlier.

package/src/core/templates.js

@@ -105,35 +105,35 @@ function buildRuntimeFiles({ includeFormalEvidence = false } = {}) {
   if (consumerQuickstart !== null) files["QUICKSTART.md"] = consumerQuickstart;
 
   const policyContent = readPackageFile("dist-assets/docs/architecture-policy.md");
-  if (policyContent !== null) files["docs/architecture-policy.md"] = policyContent;
+  if (policyContent !== null) files["opencode/docs/architecture-policy.md"] = policyContent;
 
   const dpContent = readPackageFile("dist-assets/docs/design-patterns-policy.md");
-  if (dpContent !== null) files["docs/design-patterns-policy.md"] = dpContent;
+  if (dpContent !== null) files["opencode/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;
+  if (visualValidationGuide !== null) files["opencode/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\//, "");
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
     files[targetPath] = content;
   }
 
   const compatibilityDocs = discoverPackageFiles("dist-assets/docs/compatibility");
   for (const [relPath, content] of Object.entries(compatibilityDocs)) {
-    const targetPath = relPath.replace(/^dist-assets\//, "");
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
     files[targetPath] = content;
   }
 
   const qualityReferenceFiles = discoverPackageFiles("dist-assets/docs/references");
   for (const [relPath, content] of Object.entries(qualityReferenceFiles)) {
-    const targetPath = relPath.replace(/^dist-assets\//, "");
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
     files[targetPath] = content;
   }
 
   const workflowProfileFiles = discoverPackageFiles("dist-assets/docs/profiles");
   for (const [relPath, content] of Object.entries(workflowProfileFiles)) {
-    const targetPath = relPath.replace(/^dist-assets\//, "");
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
     files[targetPath] = content;
   }
 
@@ -221,7 +221,7 @@ export function buildAiWorkflowConfig({ profile, managedFiles, managedLinks = []
       agents: ".ai-workflow/opencode/agents",
       commands: ".ai-workflow/opencode/commands",
       skills: ".ai-workflow/opencode/skills",
-      policies: ".ai-workflow/docs/policies",
+      policies: ".ai-workflow/opencode/docs/policies",
       harness: ".ai-workflow/harness",
       schemas: ".ai-workflow/schemas"
     }

package/src/core/validation/artifact-fidelity-gate.js

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export class ArtifactFidelityGate {
+  constructor({ cwd = process.cwd(), deliveryClass } = {}) {
+    this.cwd = cwd;
+    this.deliveryClass = deliveryClass;
+  }
+
+  async verify(changedFiles = []) {
+    if (changedFiles.length === 0) {
+      return { passed: true };
+    }
+
+    if (this.deliveryClass === "framework-native-frontend") {
+      for (const file of changedFiles) {
+        const ext = path.extname(file).toLowerCase();
+        
+        // 1. Forbid adding/modifying HTML files that are not SPA entry points
+        if (ext === ".html" || ext === ".htm") {
+          const basename = path.basename(file).toLowerCase();
+          const isSpaEntry = basename === "index.html" && 
+                             (file === "index.html" || file === "public/index.html" || file === "src/index.html");
+          if (!isSpaEntry) {
+            return {
+              passed: false,
+              reason: `Fidelity Violation: standalone HTML file '${file}' is not permitted in a framework-native frontend project. UI must be implemented within framework components (e.g. React/Vue/Next/Nuxt files) instead of static prototypes.`
+            };
+          }
+
+          // Check if SPA entry imports framework libraries via CDN script tags
+          try {
+            const content = await fs.readFile(path.join(this.cwd, file), "utf8");
+            if (content.includes("unpkg.com") || content.includes("cdnjs.cloudflare.com") || content.includes("cdn.jsdelivr.net")) {
+              if (content.includes("vue") || content.includes("react")) {
+                return {
+                  passed: false,
+                  reason: `Fidelity Violation: SPA entry point '${file}' imports framework library via CDN scripts. Framework dependencies must be installed and resolved locally via npm/package.json.`
+                };
+              }
+            }
+          } catch {
+            // ignore
+          }
+        }
+      }
+    }
+
+    if (this.deliveryClass === "wordpress-php") {
+      for (const file of changedFiles) {
+        const ext = path.extname(file).toLowerCase();
+        if (ext === ".html" || ext === ".htm") {
+          return {
+            passed: false,
+            reason: `Fidelity Violation: standalone HTML file '${file}' is not permitted in a WordPress project. UI templates must be implemented in PHP files within theme or plugin structures.`
+          };
+        }
+      }
+    }
+
+    return { passed: true };
+  }
+}

package/src/core/validation/delivery-decision-engine.js

@@ -0,0 +1,69 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { StackDetector } from "./stack-detector.js";
+
+export class DeliveryDecisionEngine {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+    this.stackDetector = new StackDetector({ cwd });
+  }
+
+  async determineClass(changedFiles = []) {
+    if (changedFiles.length === 0) {
+      return "empty";
+    }
+
+    // 1. Docs check
+    const isDocs = changedFiles.every(file => 
+      file.endsWith(".md") || file.endsWith(".txt") || file.startsWith("docs/")
+    );
+    if (isDocs) {
+      return "docs-only";
+    }
+
+    // 2. Detect project stacks
+    const stacks = await this.stackDetector.detect();
+    
+    // Check package.json for frontend frameworks
+    let usesJsFramework = false;
+    try {
+      const pkgPath = path.join(this.cwd, "package.json");
+      const pkgContent = await fs.readFile(pkgPath, "utf8");
+      const pkg = JSON.parse(pkgContent);
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      
+      const frameworks = ["react", "next", "vue", "nuxt", "svelte", "solid-js", "preact", "quasar", "@angular/core"];
+      usesJsFramework = frameworks.some(fw => deps[fw] !== undefined);
+    } catch {
+      // package.json doesn't exist or is invalid
+    }
+
+    // Check for WordPress
+    const isWordPress = await fs.access(path.join(this.cwd, "wp-config.php")).then(() => true).catch(() => false) ||
+                        await fs.access(path.join(this.cwd, "wp-content")).then(() => true).catch(() => false);
+
+    // Analyze changed files for UI/frontend assets
+    const hasFrontendFiles = changedFiles.some(file => 
+      /\.(html?|css|scss|sass|less|jsx|tsx|vue|svelte)$/i.test(file) ||
+      (/\.js$/i.test(file) && !file.includes("config") && !file.includes("test"))
+    );
+
+    if (isWordPress) {
+      return "wordpress-php";
+    }
+
+    if (usesJsFramework && hasFrontendFiles) {
+      return "framework-native-frontend";
+    }
+
+    if (hasFrontendFiles) {
+      return "standalone-web";
+    }
+
+    if (stacks.includes("python") || stacks.includes("php") || (stacks.includes("node") && !usesJsFramework)) {
+      return "backend-service";
+    }
+
+    return "generic-code";
+  }
+}