Merge pull request 'fix(hermes): add engines.bun, document adapter pattern (#551)' (#552) from fix/551-hermes-bin-engines into main

- Add engines.bun >= 1.0.0 to workflow-agent-hermes package.json
- Update README to explain uwf-hermes is an adapter, not hermes itself
- Update uwf setup --agent help text to mention adapter concept
- Add tests for engines field, shebang, and adapter docs
- Patch uncaged-workflow-cli skill with Agent Adapters section

.changeset/pre.json

@@ -0,0 +1,30 @@
+{
+  "mode": "exit",
+  "tag": "alpha",
+  "initialVersions": {
+    "@uncaged/cli-workflow": "0.4.5",
+    "@uncaged/workflow-agent-cursor": "0.4.5",
+    "@uncaged/workflow-agent-hermes": "0.4.5",
+    "@uncaged/workflow-agent-llm": "0.4.5",
+    "@uncaged/workflow-agent-react": "0.4.5",
+    "@uncaged/workflow-cas": "0.4.5",
+    "@uncaged/workflow-dashboard": "0.1.0",
+    "@uncaged/workflow-execute": "0.4.5",
+    "@uncaged/workflow-gateway": "0.4.5",
+    "@uncaged/workflow-protocol": "0.4.5",
+    "@uncaged/workflow-reactor": "0.4.5",
+    "@uncaged/workflow-register": "0.4.5",
+    "@uncaged/workflow-runtime": "0.4.5",
+    "@uncaged/workflow-template-develop": "0.4.5",
+    "@uncaged/workflow-template-solve-issue": "0.4.5",
+    "@uncaged/workflow-util": "0.4.5",
+    "@uncaged/workflow-util-agent": "0.4.5"
+  },
+  "changesets": [
+    "env-api-unify",
+    "fix-internal-deps",
+    "fix-publish-src",
+    "fix-workspace-deps",
+    "rfc-252-agent-fn"
+  ]
+}

packages/cli-workflow/CHANGELOG.md

@@ -1,11 +0,0 @@
-# @uncaged/cli-workflow
-
-## 0.5.1
-
-### Patch Changes
-
-- Add 5 persona-based skills (actor, user, author, developer, adapter) and fix skill CLI description truncation
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/cli-workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/cli-workflow/src/cli.ts

@@ -564,7 +564,7 @@ program
   .option("--base-url <url>", "OpenAI-compatible API base URL")
   .option("--api-key <key>", "API key")
   .option("--model <name>", "Default model name")
-  .option("--agent <name>", "Default agent alias")
+  .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
   .action(
     (opts: {
       provider?: string;

packages/workflow-agent-builtin/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-agent-builtin
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-builtin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-builtin",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-agent-claude-code/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-agent-claude-code
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-claude-code",
-  "version": "0.5.1",
+  "version": "0.1.0",
   "files": [
     "src",
     "dist",

packages/workflow-agent-hermes/CHANGELOG.md

@@ -1,10 +0,0 @@
-# @uncaged/workflow-agent-hermes
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-hermes/README.md

@@ -1,10 +1,12 @@
 # @uncaged/workflow-agent-hermes
 
-`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
+`uwf-hermes` — an **agent adapter** that bridges the `uwf` workflow engine and the Hermes CLI.
 
 ## Overview
 
-Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
+`uwf-hermes` is an adapter (not the Hermes CLI itself). The `uwf` engine speaks a generic agent protocol (stdin/stdout frontmatter contract); `uwf-hermes` translates that protocol into Hermes ACP (Agent Client Protocol) calls. Other adapters (e.g. `uwf-claude-code`, `uwf-cursor`) do the same for their respective CLIs.
+
+On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
 
 **Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
 

packages/workflow-agent-hermes/__tests__/issue-551.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PKG_ROOT = join(import.meta.dir, "..");
+
+describe("Issue #551 — bin entry & engines", () => {
+  test("package.json declares bun in engines", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    expect(pkg.engines).toBeDefined();
+    expect(pkg.engines.bun).toBeDefined();
+    expect(pkg.engines.bun).toMatch(/^>=?\s*[\d.]+/);
+  });
+
+  test("bin entry file has bun shebang", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    const binPath = pkg.bin["uwf-hermes"];
+    const content = readFileSync(join(PKG_ROOT, binPath), "utf-8");
+    expect(content.startsWith("#!/usr/bin/env bun")).toBe(true);
+  });
+
+  test("README.md explains uwf-hermes is an adapter", () => {
+    const readme = readFileSync(join(PKG_ROOT, "README.md"), "utf-8");
+    expect(readme.toLowerCase()).toContain("adapter");
+    expect(readme).toMatch(/uwf-hermes/);
+    expect(readme).toMatch(/hermes/);
+  });
+});

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",
@@ -42,5 +42,8 @@
   "bugs": {
     "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
   },
+  "engines": {
+    "bun": ">= 1.0.0"
+  },
   "license": "MIT"
 }

packages/workflow-protocol/CHANGELOG.md

@@ -1,3 +0,0 @@
-# @uncaged/workflow-protocol
-
-## 0.5.1

packages/workflow-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-util-agent/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-util-agent
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-util/CHANGELOG.md

@@ -1,7 +0,0 @@
-# @uncaged/workflow-util
-
-## 0.5.1
-
-### Patch Changes
-
-- Add 5 persona-based skills (actor, user, author, developer, adapter) and fix skill CLI description truncation

packages/workflow-util/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

scripts/publish-all.mjs

@@ -21,7 +21,6 @@ const publishOrder = [
   "workflow-util-agent",
   "workflow-agent-hermes",
   "workflow-agent-builtin",
-  "workflow-agent-claude-code",
   "cli-workflow",
 ];