fix: add workflow-agent-claude-code to publish order

小橘 <xiaoju@shazhou.work>

.changeset/pre.json

@@ -1,30 +0,0 @@
-{
-  "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

@@ -0,0 +1,11 @@
+# @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.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",

packages/cli-workflow/src/__tests__/skill.test.ts

@@ -7,9 +7,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import {
   cmdSkillActor,
+  cmdSkillAdapter,
   cmdSkillArchitecture,
   cmdSkillAuthor,
   cmdSkillCli,
+  cmdSkillDeveloper,
   cmdSkillList,
   cmdSkillModerator,
   cmdSkillUser,
@@ -27,6 +29,8 @@ describe("skill commands", () => {
     expect(result).toContain("actor");
     expect(result).toContain("user");
     expect(result).toContain("author");
+    expect(result).toContain("developer");
+    expect(result).toContain("adapter");
     for (const name of result) {
       expect(name).toMatch(/^\S+$/);
     }
@@ -97,6 +101,24 @@ describe("skill commands", () => {
     expect(result.length).toBeGreaterThan(500);
   });
 
+  test("skill developer returns non-empty markdown string", () => {
+    const result = cmdSkillDeveloper();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("Monorepo");
+    expect(result).toContain("CAS");
+    expect(result).toContain("Biome");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill adapter returns non-empty markdown string", () => {
+    const result = cmdSkillAdapter();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("createAgent");
+    expect(result).toContain("AgentContext");
+    expect(result).toContain("frontmatter");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
   test("skill help subcommand is suppressed", () => {
     const output = execFileSync("bun", ["src/cli.ts", "skill", "--help"], {
       cwd: join(__dirname, "..", ".."),
@@ -111,6 +133,8 @@ describe("skill commands", () => {
     expect(output).toContain("actor");
     expect(output).toContain("user");
     expect(output).toContain("author");
+    expect(output).toContain("developer");
+    expect(output).toContain("adapter");
     expect(output).toContain("list");
   });
 });

packages/cli-workflow/src/cli.ts

@@ -18,9 +18,11 @@ import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import {
   cmdSkillActor,
+  cmdSkillAdapter,
   cmdSkillArchitecture,
   cmdSkillAuthor,
   cmdSkillCli,
+  cmdSkillDeveloper,
   cmdSkillList,
   cmdSkillModerator,
   cmdSkillUser,
@@ -513,6 +515,13 @@ skill
     console.log(cmdSkillActor());
   });
 
+skill
+  .command("adapter")
+  .description("Print the adapter reference (building agent adapters)")
+  .action(() => {
+    console.log(cmdSkillAdapter());
+  });
+
 skill
   .command("author")
   .description("Print the author reference (workflow YAML design guide)")
@@ -520,6 +529,13 @@ skill
     console.log(cmdSkillAuthor());
   });
 
+skill
+  .command("developer")
+  .description("Print the developer reference (coding conventions + architecture)")
+  .action(() => {
+    console.log(cmdSkillDeveloper());
+  });
+
 skill
   .command("moderator")
   .description("Print the moderator reference")

packages/cli-workflow/src/commands/skill.ts

@@ -1,8 +1,10 @@
 export {
   generateActorReference as cmdSkillActor,
+  generateAdapterReference as cmdSkillAdapter,
   generateArchitectureReference as cmdSkillArchitecture,
   generateAuthorReference as cmdSkillAuthor,
   generateCliReference as cmdSkillCli,
+  generateDeveloperReference as cmdSkillDeveloper,
   generateModeratorReference as cmdSkillModerator,
   generateUserReference as cmdSkillUser,
   generateYamlReference as cmdSkillYaml,
@@ -16,6 +18,8 @@ const SKILL_NAMES = [
   "actor",
   "user",
   "author",
+  "developer",
+  "adapter",
 ] as const;
 
 export function cmdSkillList(): ReadonlyArray<string> {

packages/workflow-agent-builtin/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @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.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",

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

@@ -0,0 +1,9 @@
+# @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.1.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",

packages/workflow-agent-hermes/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @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/package.json

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

packages/workflow-protocol/CHANGELOG.md

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

packages/workflow-protocol/package.json

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

packages/workflow-util-agent/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @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.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",

packages/workflow-util/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @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.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",

packages/workflow-util/src/adapter-reference.ts

@@ -0,0 +1,163 @@
+export function generateAdapterReference(): string {
+  return `# Adapter Reference
+
+Guide for building a new agent adapter (CLI binary) for the workflow engine.
+
+## What Is an Adapter
+
+An adapter is a CLI command (e.g. \`uwf-hermes\`, \`uwf-builtin\`) that the engine spawns to execute a role. It bridges the workflow engine and an LLM/agent backend. The engine calls it with:
+
+\`\`\`
+uwf-<name> --thread <id> --role <role> --prompt <text>
+\`\`\`
+
+The adapter must produce frontmatter markdown output. The engine handles argument parsing, context building, output extraction, and CAS persistence — you just implement the LLM interaction.
+
+## Quick Start
+
+\`\`\`typescript
+import { createAgent } from "@uncaged/workflow-util-agent";
+import type { AgentContext, AgentRunResult, AgentContinueFn, AgentRunFn } from "@uncaged/workflow-util-agent";
+
+const run: AgentRunFn = async (ctx: AgentContext): Promise<AgentRunResult> => {
+  // 1. Build your prompt from ctx
+  // 2. Call your LLM backend
+  // 3. Return the result
+  return { output: rawMarkdown, detailHash, sessionId };
+};
+
+const continue_: AgentContinueFn = async (sessionId, message, store) => {
+  // Resume an existing session with a correction message
+  return { output: correctedMarkdown, detailHash, sessionId };
+};
+
+const main = createAgent({ name: "my-agent", run, continue: continue_ });
+main();
+\`\`\`
+
+## The \`createAgent\` Factory
+
+\`createAgent(options)\` returns an async \`main()\` function that handles the full lifecycle:
+
+1. Parses CLI args (\`--thread\`, \`--role\`, \`--prompt\`)
+2. Loads \`.env\` from storage root
+3. Builds \`AgentContext\` (thread history, workflow definition, role prompt)
+4. Injects \`outputFormatInstruction\` from the role's frontmatter schema
+5. Calls your \`run(ctx)\` function
+6. Extracts frontmatter from your output via \`tryFrontmatterFastPath()\`
+7. If extraction fails, calls your \`continue(sessionId, correctionMessage, store)\` up to 2 times
+8. Persists the validated output as a CAS step node
+9. Prints the step hash to stdout
+
+You only implement \`run\` and \`continue\`.
+
+## AgentOptions
+
+\`\`\`typescript
+type AgentOptions = {
+  name: string;           // Adapter name (used in step records as "uwf-<name>")
+  run: AgentRunFn;        // Execute a role from scratch
+  continue: AgentContinueFn;  // Resume a session for frontmatter correction
+};
+\`\`\`
+
+## AgentContext
+
+The \`ctx\` object passed to your \`run\` function:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`threadId\` | \`string\` | Thread ULID |
+| \`role\` | \`string\` | Role name being executed |
+| \`edgePrompt\` | \`string\` | Moderator's task instruction for this step |
+| \`workflow\` | \`WorkflowPayload\` | Full workflow definition (roles, graph) |
+| \`start\` | \`StartNodePayload\` | Thread start data (workflow hash, user prompt) |
+| \`steps\` | \`StepContext[]\` | Previous steps with expanded outputs |
+| \`store\` | \`Store\` | CAS store for reading/writing data |
+| \`outputFormatInstruction\` | \`string\` | Frontmatter format instruction (inject into system prompt) |
+| \`isFirstVisit\` | \`boolean\` | True if this role hasn't run before in this thread |
+
+## AgentRunResult
+
+Your \`run\` and \`continue\` functions must return:
+
+\`\`\`typescript
+type AgentRunResult = {
+  output: string;       // Raw markdown with frontmatter (must start with ---)
+  detailHash: string;   // CAS hash of session detail (turn history, metadata)
+  sessionId: string;    // Session ID for potential continue() calls
+};
+\`\`\`
+
+## Building the Prompt
+
+Use helpers from \`@uncaged/workflow-util-agent\`:
+
+| Helper | Purpose |
+|--------|---------|
+| \`buildRolePrompt(roleDef)\` | Assemble Goal/Capabilities/Prepare/Procedure/Output sections |
+| \`buildContinuationPrompt(steps, role, edgePrompt)\` | For re-entry: steps since last visit + edge prompt |
+| \`ctx.outputFormatInstruction\` | Pre-built frontmatter format block (inject into system prompt) |
+
+Typical system prompt structure:
+\`\`\`
+[outputFormatInstruction]
+[rolePrompt from buildRolePrompt()]
+[workflow metadata]
+\`\`\`
+
+## Storing Session Detail
+
+Store your turn history as a CAS merkle DAG for debugging and replay:
+
+\`\`\`typescript
+// Store each turn as a CAS text node
+const turnHash = await store.put(textSchema, { content: turnData });
+
+// Build a detail node referencing all turns
+const detailHash = await store.put(detailSchema, { turns: turnHashes });
+\`\`\`
+
+The \`detailHash\` is preserved from the first \`run()\` call — retry \`continue()\` calls don't overwrite it.
+
+## Registration
+
+Register your adapter in \`~/.uncaged/workflow/config.yaml\`:
+
+\`\`\`yaml
+agents:
+  my-agent:
+    command: uwf-my-agent
+    args: []
+\`\`\`
+
+Use it:
+\`\`\`bash
+uwf thread exec <thread-id> --agent my-agent
+\`\`\`
+
+Or set as default:
+\`\`\`yaml
+defaultAgent: my-agent
+\`\`\`
+
+## Existing Adapters
+
+| Adapter | Package | Backend |
+|---------|---------|---------|
+| \`uwf-hermes\` | \`@uncaged/workflow-agent-hermes\` | Hermes ACP (chat sessions) |
+| \`uwf-builtin\` | \`@uncaged/workflow-agent-builtin\` | Direct OpenAI API (tools + loop) |
+| \`uwf-claude-code\` | \`@uncaged/workflow-agent-claude-code\` | Claude Code CLI |
+
+Study these for patterns on prompt building, session management, and detail storage.
+
+## Checklist
+
+1. Implement \`run(ctx)\` — build prompt, call LLM, return output + detailHash + sessionId
+2. Implement \`continue(sessionId, message, store)\` — resume session for frontmatter correction
+3. Store session detail as CAS nodes (for debugging)
+4. Ensure output starts with \`---\` frontmatter block
+5. Add a \`bin\` entry in \`package.json\` for the CLI command
+6. Register in config.yaml and test with \`uwf thread exec --agent <name>\`
+`;
+}

packages/workflow-util/src/developer-reference.ts

@@ -0,0 +1,140 @@
+export function generateDeveloperReference(): string {
+  return `# Developer Reference
+
+Guide for contributing to the workflow engine codebase.
+
+## Monorepo Structure
+
+\`\`\`
+packages/
+  workflow-protocol/      # Shared types (WorkflowPayload, StepNodePayload, etc.)
+  workflow-util/          # Base32, ULID, logger, frontmatter parsing, skill references
+  workflow-util-agent/    # createAgent factory, context builder, extract pipeline
+  workflow-agent-hermes/  # uwf-hermes CLI (spawns Hermes chat sessions)
+  workflow-agent-builtin/ # uwf-builtin CLI (direct LLM calls via OpenAI API)
+  cli-workflow/           # uwf CLI (moderator, thread/step/cas/config commands)
+\`\`\`
+
+Dependency layers (each only imports from packages above it):
+\`\`\`
+protocol → util → util-agent → agent-hermes / agent-builtin / cli-workflow
+\`\`\`
+
+External CAS: \`@uncaged/json-cas\` (store API, hashing, schema validation) + \`@uncaged/json-cas-fs\` (filesystem backend).
+
+## Coding Conventions
+
+### Functional-first
+
+| Rule | Description |
+|------|-------------|
+| \`type\` over \`interface\` | All type definitions use \`type\` |
+| \`function\` over \`class\` | Pure functions + closures, no class |
+| No \`this\` | Functions must not depend on \`this\` context |
+| No inheritance | No \`extends\`, \`implements\`, \`abstract\` |
+| No optional properties | Use \`T \\| null\` instead of \`?:\` |
+| Immutability first | Use \`Readonly<T>\`, \`as const\`, avoid mutation |
+
+Classes allowed only when required by third-party libraries or for Error subclasses.
+
+### Error Handling
+
+- \`Result<T, E>\` type for expected failures (\`ok\`/\`err\` constructors from \`@uncaged/workflow-util\`)
+- \`throw\` only for unrecoverable bugs
+- No try-catch for flow control
+
+### Async
+
+Always \`async/await\`, never \`.then()\` chains.
+
+### Logging
+
+\`console.*\` is banned (Biome \`noConsole\` rule). Use the structured logger:
+
+\`\`\`typescript
+import { createLogger } from "@uncaged/workflow-util";
+const log = createLogger();
+log("4KNMR2PX", "Loading workflow...");  // 8-char Crockford Base32 tag
+\`\`\`
+
+Each call site gets a unique hand-written tag. \`grep "4KNMR2PX"\` in logs → instant code location.
+
+CLI package (\`@uncaged/cli-workflow\`) may use \`console.log\` for user-facing output with a biome-ignore comment.
+
+### No Dynamic Import
+
+No \`await import()\` in production code. Always static top-level \`import\`. Test files are exempt.
+
+### Naming
+
+- Workflow names: verb-first kebab-case (\`solve-issue\`, \`review-code\`)
+- IDs: Crockford Base32 — CAS hash (XXH64, 13-char), Thread ID (ULID, 26-char)
+
+## Development Workflow
+
+\`\`\`bash
+bun install                 # install all workspace deps
+bun run build               # tsc --build (all packages)
+bun run check               # tsc + biome check + lint-log-tags
+bun run format              # biome format --write
+bun test                    # run all tests
+\`\`\`
+
+Before committing: \`bun run check\` + \`bun test\` must both pass.
+
+### Testing
+
+- \`cli-workflow\`: vitest
+- Other packages: \`bun test\`
+- Test files live in \`__tests__/\` directories
+
+### Publishing
+
+Fixed-mode versioning — all \`@uncaged/*\` packages share the same version number.
+
+\`\`\`bash
+bun changeset               # describe the change
+bun version                 # bump versions + changelogs
+bun release                 # build + test + publish to npmjs
+\`\`\`
+
+## Key Modules
+
+### Moderator (\`cli-workflow/src/moderator/\`)
+
+Status-based graph evaluator. Reads \`graph[lastRole][output.$status]\` to determine the next role. Zero LLM cost.
+
+### Extract Pipeline (\`workflow-util-agent/src/\`)
+
+1. Agent produces frontmatter markdown
+2. \`parseFrontmatterMarkdown()\` extracts YAML frontmatter
+3. \`tryFrontmatterFastPath()\` validates against role's output schema
+4. If fast path fails, retries up to 2 times via agent continue
+5. Validated output stored as CAS node
+
+### createAgent Factory (\`workflow-util-agent/src/run.ts\`)
+
+Shared entry point for all agent CLIs. Handles:
+- Argument parsing (\`--thread\`, \`--role\`, \`--prompt\`)
+- Context building (thread history, workflow definition)
+- Output extraction and CAS persistence
+- Frontmatter retry loop
+
+### CAS Integration
+
+All data is CAS-addressed via \`@uncaged/json-cas\`:
+- \`store.put(schemaHash, data)\` → content hash
+- \`store.get(hash)\` → node
+- \`validate(store, node)\` → schema check
+- Schemas registered at workflow add time
+
+## Commit Convention
+
+\`\`\`
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: workflow | cli | moderator | util-agent | hermes | util | protocol
+\`\`\`
+`;
+}

packages/workflow-util/src/index.ts

@@ -1,8 +1,10 @@
 export { generateActorReference } from "./actor-reference.js";
+export { generateAdapterReference } from "./adapter-reference.js";
 export { generateArchitectureReference } from "./architecture-reference.js";
 export { generateAuthorReference } from "./author-reference.js";
 export { encodeUint64AsCrockford } from "./base32.js";
 export { generateCliReference } from "./cli-reference.js";
+export { generateDeveloperReference } from "./developer-reference.js";
 export { env } from "./env.js";
 export type {
   AgentFrontmatter,

scripts/publish-all.mjs

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