@williambeto/ai-workflow 2.7.1 → 2.8.1

package/dist-assets/schemas/evidence.schema.json

@@ -35,6 +35,34 @@
         "type": "string"
       }
     },
+    "deliveryChangedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mutationOwner": {
+      "type": ["string", "null"],
+      "enum": ["Astra", "Phoenix", "ControlPlane", null]
+    },
+    "capabilitiesUsed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "deliveryMode": {
+      "enum": ["workspace", "answer-only"]
+    },
+    "deliveryOutcome": {
+      "enum": ["CHANGED", "ALREADY_SATISFIED", "READ_ONLY_RESULT", "PREVIEW_ONLY", "NEEDS_CLARIFICATION", "NOT_DELIVERED"]
+    },
+    "testAction": {
+      "enum": ["reuse", "extend", "add", "none"]
+    },
+    "testReason": {
+      "type": "string"
+    },
     "status": {
       "enum": ["COMPLETED", "COMPLETED_WITH_NOTES", "BLOCKED"]
     },
@@ -104,6 +132,70 @@
     "visualEvidence": {
       "type": ["object", "null"],
       "additionalProperties": true
+    },
+    "workflowId": {
+      "type": "string"
+    },
+    "baseSha": {
+      "type": "string"
+    },
+    "artifactHashes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["draft", "approved", "technicalPlan"],
+      "properties": {
+        "draft": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "approved": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "technicalPlan": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "phaseOrder": {
+      "type": "array",
+      "items": { "enum": ["specification", "planning", "implementation"] }
+    },
+    "confirmedActors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["phase", "requested", "applied"],
+        "properties": {
+          "phase": { "enum": ["specification", "planning", "implementation"] },
+          "requested": { "enum": ["Nexus", "Orion", "Astra"] },
+          "applied": { "enum": ["Nexus", "Orion", "Astra"] }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "deliveryMode": { "const": "workspace" },
+          "deliveryOutcome": { "const": "CHANGED" }
+        },
+        "required": ["deliveryMode", "deliveryOutcome"]
+      },
+      "then": {
+        "required": ["mutationOwner", "commands"],
+        "properties": {
+          "mutationOwner": {
+            "enum": ["Astra", "Phoenix"]
+          },
+          "commands": {
+            "type": "array",
+            "minItems": 1,
+            "contains": {
+              "type": "object",
+              "required": ["kind", "status"],
+              "properties": {
+                "kind": { "not": { "const": "other" } },
+                "status": { "enum": ["PASS", "PASS_WITH_NOTES"] }
+              }
+            }
+          }
+        }
+      }
     }
-  }
+  ]
 }

package/evidence-validator-HS3NTWAB.js

@@ -0,0 +1,8 @@
+import {
+  EvidenceValidator
+} from "./chunk-FNT7DN3N.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  EvidenceValidator
+};
+//# sourceMappingURL=evidence-validator-HS3NTWAB.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.7.1",
+  "version": "2.8.1",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -13,6 +13,18 @@
   "engines": {
     "node": ">=20.11"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.14.0 <23",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10",
+      "onFail": "error"
+    }
+  },
   "keywords": [
     "ai-workflow",
     "opencode",
@@ -41,5 +53,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
-  ]
+  ],
+  "dependencies": {
+    "@opencode-ai/sdk": "1.17.18"
+  }
 }

package/skill-4MEGJ3DO.js

@@ -0,0 +1,211 @@
+import {
+  createManagedBackup
+} from "./chunk-AY33SA5W.js";
+import {
+  BranchGate
+} from "./chunk-AINIR25D.js";
+import {
+  lintSkillFile
+} from "./chunk-YOBY5C72.js";
+import "./chunk-5WRI5ZAA.js";
+
+// src/cli/commands/skill.ts
+import fs from "fs/promises";
+import path from "path";
+import { randomUUID } from "crypto";
+var SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var MAX_SKILL_NAME_LENGTH = 64;
+var BACKUP_ROOT = ".ai-workflow-backups";
+function requireDescription(value) {
+  if (value === void 0 || value.trim().length === 0) {
+    throw new Error("--description requires a non-empty value");
+  }
+  return value.trim();
+}
+function parseSkillCreateArgs(args) {
+  const positionals = [];
+  let description;
+  let descriptionSeen = false;
+  let force = false;
+  let dryRun = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--force") {
+      force = true;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--description") {
+      if (descriptionSeen) throw new Error("--description may only be provided once");
+      const value = args[index + 1];
+      if (value?.startsWith("--")) throw new Error("--description requires a non-empty value");
+      description = requireDescription(value);
+      descriptionSeen = true;
+      index += 1;
+    } else if (arg.startsWith("--description=")) {
+      if (descriptionSeen) throw new Error("--description may only be provided once");
+      description = requireDescription(arg.slice("--description=".length));
+      descriptionSeen = true;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option for skill create: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected positional arguments: ${positionals.slice(1).join(" ")}`);
+  }
+  return { name: positionals[0], description, force, dryRun };
+}
+function isWithin(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function assertWithinWorkspace(workspaceRoot, candidate, label) {
+  if (!isWithin(workspaceRoot, candidate)) {
+    throw new Error(`${label} resolves outside the workspace: ${candidate}`);
+  }
+}
+async function lstatIfExists(targetPath) {
+  try {
+    return await fs.lstat(targetPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function validateExistingDirectory(targetPath, workspaceRoot, label, rejectSymlink = false) {
+  const entry = await lstatIfExists(targetPath);
+  if (!entry) return false;
+  if (rejectSymlink && entry.isSymbolicLink()) {
+    throw new Error(`${label} must not be a symbolic link: ${targetPath}`);
+  }
+  let resolved;
+  try {
+    resolved = await fs.realpath(targetPath);
+  } catch (error) {
+    throw new Error(`Cannot resolve ${label}: ${error.message}`);
+  }
+  assertWithinWorkspace(workspaceRoot, resolved, label);
+  const resolvedEntry = await fs.stat(targetPath);
+  if (!resolvedEntry.isDirectory()) {
+    throw new Error(`${label} must be a directory: ${targetPath}`);
+  }
+  return true;
+}
+async function validateExistingSkillFile(skillFile) {
+  const entry = await lstatIfExists(skillFile);
+  if (!entry) return false;
+  if (entry.isSymbolicLink()) {
+    throw new Error(`SKILL.md must not be a symbolic link: ${skillFile}`);
+  }
+  if (!entry.isFile()) {
+    throw new Error(`SKILL.md must be a regular file: ${skillFile}`);
+  }
+  return true;
+}
+function validateSkillName(name) {
+  if (name.length > MAX_SKILL_NAME_LENGTH || !SKILL_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Invalid skill name '${name}'. Use lowercase kebab-case with at most ${MAX_SKILL_NAME_LENGTH} characters (for example: database-migrations).`
+    );
+  }
+}
+function buildSkillContent(name, description) {
+  const safeDescription = description || `Provides guidelines and instructions for ${name}`;
+  const readableName = name.split("-").map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join(" ");
+  return `---
+name: ${JSON.stringify(name)}
+description: ${JSON.stringify(safeDescription)}
+---
+
+# ${readableName}
+
+## Context
+
+Describe when this skill should be used.
+
+## Instructions
+
+- Add concrete, actionable instructions.
+- Document constraints and prohibited actions.
+
+## Validation
+
+- Define the commands or checks required before completion.
+`;
+}
+async function runSkillCreate(options) {
+  const { cwd, name, description, force = false, dryRun = false } = options;
+  if (!name) {
+    throw new Error('Skill name is required. Usage: ai-workflow skill create <name> [--description="..."] [--dry-run] [--force]');
+  }
+  validateSkillName(name);
+  const normalizedDescription = description === void 0 ? void 0 : requireDescription(description);
+  const workspaceRoot = await fs.realpath(cwd);
+  const agentsDir = path.join(workspaceRoot, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const skillDir = path.join(skillsDir, name);
+  const skillFile = path.join(skillDir, "SKILL.md");
+  assertWithinWorkspace(workspaceRoot, skillFile, "Skill destination");
+  await validateExistingDirectory(agentsDir, workspaceRoot, ".agents directory");
+  await validateExistingDirectory(skillsDir, workspaceRoot, "Skills directory");
+  await validateExistingDirectory(skillDir, workspaceRoot, `Skill directory '${name}'`, true);
+  const skillExists = await validateExistingSkillFile(skillFile);
+  if (skillExists && !force) {
+    throw new Error(`Skill '${name}' already exists at ${skillFile}. Use --force to overwrite.`);
+  }
+  const content = buildSkillContent(name, normalizedDescription);
+  const branchGate = new BranchGate({ cwd: workspaceRoot });
+  const gateResult = branchGate.check("", { taskSlug: `skill-${name}`, readOnly: dryRun });
+  if (gateResult.blocked || gateResult.branch === "unknown") {
+    throw new Error(`[GATE BLOCKED] ${gateResult.reason || "Git is unavailable or the current branch could not be determined."}`);
+  }
+  if (dryRun) {
+    console.log(`[DRY RUN] Would ${skillExists ? "overwrite" : "create"} skill '${name}' at ${skillFile}`);
+    return { status: "dry-run", skillName: name, skillFile, branch: gateResult.branch };
+  }
+  await fs.mkdir(skillDir, { recursive: true });
+  await validateExistingDirectory(agentsDir, workspaceRoot, ".agents directory");
+  await validateExistingDirectory(skillsDir, workspaceRoot, "Skills directory");
+  await validateExistingDirectory(skillDir, workspaceRoot, `Skill directory '${name}'`, true);
+  let backupPath;
+  if (skillExists) {
+    await validateExistingSkillFile(skillFile);
+    const backupRoot = path.join(workspaceRoot, BACKUP_ROOT);
+    await validateExistingDirectory(backupRoot, workspaceRoot, "Backup directory");
+    backupPath = await createManagedBackup(skillFile, { cwd: workspaceRoot, backupRoot: BACKUP_ROOT });
+    assertWithinWorkspace(workspaceRoot, await fs.realpath(backupPath), "Backup file");
+    await validateExistingDirectory(skillDir, workspaceRoot, `Skill directory '${name}'`, true);
+    await validateExistingSkillFile(skillFile);
+    const stagedFile = path.join(skillDir, `.SKILL.md.${randomUUID()}.tmp`);
+    try {
+      await fs.writeFile(stagedFile, content, { encoding: "utf8", flag: "wx" });
+      await validateExistingDirectory(skillDir, workspaceRoot, `Skill directory '${name}'`, true);
+      await fs.rename(stagedFile, skillFile);
+    } finally {
+      await fs.rm(stagedFile, { force: true }).catch(() => {
+      });
+    }
+  } else {
+    try {
+      await fs.writeFile(skillFile, content, { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new Error(`Skill '${name}' already exists at ${skillFile}. Use --force to overwrite.`);
+      }
+      throw error;
+    }
+  }
+  const lintErrors = lintSkillFile(skillFile);
+  if (lintErrors.length > 0) {
+    throw new Error(`Generated skill failed frontmatter lint: ${lintErrors.map((error) => error.message).join("; ")}`);
+  }
+  const status = skillExists ? "overwritten" : "created";
+  console.log(`${status === "created" ? "Created" : "Overwrote"} skill '${name}' at ${skillFile}`);
+  return { status, skillName: name, skillFile, backupPath, branch: gateResult.branch };
+}
+export {
+  parseSkillCreateArgs,
+  runSkillCreate
+};
+//# sourceMappingURL=skill-4MEGJ3DO.js.map

package/skill-frontmatter-linter-FMJADOK4.js

@@ -0,0 +1,14 @@
+import {
+  getDiscoverableSkillPaths,
+  lintSkillFile,
+  parseFrontmatter,
+  runLinter
+} from "./chunk-YOBY5C72.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  getDiscoverableSkillPaths,
+  lintSkillFile,
+  parseFrontmatter,
+  runLinter
+};
+//# sourceMappingURL=skill-frontmatter-linter-FMJADOK4.js.map

package/{validate-A46WUBVZ.js → validate-F3ZH63LI.js}

@@ -3,8 +3,8 @@ import {
   QualityGuard,
   ValidationPlanner,
   VisualVerifier
-} from "./chunk-BDZPUAEX.js";
-import "./chunk-XW747GIG.js";
+} from "./chunk-LD7EHAU2.js";
+import "./chunk-H7GIKXFO.js";
 import "./chunk-5WRI5ZAA.js";
 
 // src/cli/commands/validate.ts
@@ -86,4 +86,4 @@ async function runValidate({
 export {
   runValidate
 };
-//# sourceMappingURL=validate-A46WUBVZ.js.map
+//# sourceMappingURL=validate-F3ZH63LI.js.map