feat: add developer skill — coding conventions + architecture guide

Adds 'uwf skill developer' for contributors to the workflow engine.
Covers: monorepo structure, dependency layers, functional-first conventions,
error handling, logging with tagged logger, development workflow,
testing, publishing, key modules (moderator, extract pipeline, createAgent).

Refs #541

.gitea/workflows/ci.yml

@@ -22,4 +22,4 @@ jobs:
         run: bun run check
 
       - name: Test
-        run: bun run test
+        run: bun run test:ci

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

@@ -8,9 +8,12 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 import {
   cmdSkillActor,
   cmdSkillArchitecture,
+  cmdSkillAuthor,
   cmdSkillCli,
+  cmdSkillDeveloper,
   cmdSkillList,
   cmdSkillModerator,
+  cmdSkillUser,
   cmdSkillYaml,
 } from "../commands/skill.js";
 
@@ -23,6 +26,9 @@ describe("skill commands", () => {
     expect(result).toContain("yaml");
     expect(result).toContain("moderator");
     expect(result).toContain("actor");
+    expect(result).toContain("user");
+    expect(result).toContain("author");
+    expect(result).toContain("developer");
     for (const name of result) {
       expect(name).toMatch(/^\S+$/);
     }
@@ -72,6 +78,36 @@ describe("skill commands", () => {
     expect(result.length).toBeGreaterThan(200);
   });
 
+  test("skill user returns non-empty markdown string", () => {
+    const result = cmdSkillUser();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("uwf");
+    expect(result).toContain("thread");
+    expect(result).toContain("workflow");
+    expect(result).toContain("Quick Start");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill author returns non-empty markdown string", () => {
+    const result = cmdSkillAuthor();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("frontmatter");
+    expect(result).toContain("graph");
+    expect(result).toContain("$START");
+    expect(result).toContain("$END");
+    expect(result).toContain("$status");
+    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 help subcommand is suppressed", () => {
     const output = execFileSync("bun", ["src/cli.ts", "skill", "--help"], {
       cwd: join(__dirname, "..", ".."),
@@ -84,6 +120,9 @@ describe("skill commands", () => {
     expect(output).toContain("yaml");
     expect(output).toContain("moderator");
     expect(output).toContain("actor");
+    expect(output).toContain("user");
+    expect(output).toContain("author");
+    expect(output).toContain("developer");
     expect(output).toContain("list");
   });
 });

packages/cli-workflow/src/cli.ts

@@ -19,9 +19,12 @@ import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import {
   cmdSkillActor,
   cmdSkillArchitecture,
+  cmdSkillAuthor,
   cmdSkillCli,
+  cmdSkillDeveloper,
   cmdSkillList,
   cmdSkillModerator,
+  cmdSkillUser,
   cmdSkillYaml,
 } from "./commands/skill.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
@@ -511,6 +514,20 @@ skill
     console.log(cmdSkillActor());
   });
 
+skill
+  .command("author")
+  .description("Print the author reference (workflow YAML design guide)")
+  .action(() => {
+    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")
@@ -518,6 +535,13 @@ skill
     console.log(cmdSkillModerator());
   });
 
+skill
+  .command("user")
+  .description("Print the user reference (CLI guide + typical workflows)")
+  .action(() => {
+    console.log(cmdSkillUser());
+  });
+
 skill
   .command("list")
   .description("List all available skill names")

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

@@ -1,12 +1,24 @@
 export {
   generateActorReference as cmdSkillActor,
   generateArchitectureReference as cmdSkillArchitecture,
+  generateAuthorReference as cmdSkillAuthor,
   generateCliReference as cmdSkillCli,
+  generateDeveloperReference as cmdSkillDeveloper,
   generateModeratorReference as cmdSkillModerator,
+  generateUserReference as cmdSkillUser,
   generateYamlReference as cmdSkillYaml,
 } from "@uncaged/workflow-util";
 
-const SKILL_NAMES = ["cli", "architecture", "yaml", "moderator", "actor"] as const;
+const SKILL_NAMES = [
+  "cli",
+  "architecture",
+  "yaml",
+  "moderator",
+  "actor",
+  "user",
+  "author",
+  "developer",
+] as const;
 
 export function cmdSkillList(): ReadonlyArray<string> {
   return [...SKILL_NAMES];

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

@@ -0,0 +1,183 @@
+export function generateAuthorReference(): string {
+  return `# Author Reference
+
+Guide for designing and writing workflow YAML definitions.
+
+## Workflow Structure
+
+\`\`\`yaml
+name: solve-issue              # verb-first kebab-case
+description: "..."             # human-readable summary
+
+roles:                         # named actors
+  planner:
+    description: "..."         # short purpose
+    goal: "..."                # system-level goal for the agent
+    capabilities: [...]        # skill keywords the agent should load
+    procedure: |               # step-by-step instructions
+      1. Do this
+      2. Do that
+    output: "..."              # what the agent should produce
+    frontmatter:               # JSON Schema for structured output
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+          required: [$status, plan]
+        - properties:
+            $status: { const: "failed" }
+            error: { type: string }
+          required: [$status, error]
+
+graph:                         # status-based routing
+  $START:
+    _: { role: planner, prompt: "Analyze the issue." }
+  planner:
+    ready: { role: developer, prompt: "Implement {{{plan}}}." }
+    failed: { role: $END, prompt: "Failed: {{{error}}}" }
+\`\`\`
+
+## Role Definition
+
+| Field | Purpose |
+|-------|---------|
+| \`description\` | Short description for humans and moderator context |
+| \`goal\` | Injected as the agent's system-level objective |
+| \`capabilities\` | Keyword tags — agent loads matching skills before starting |
+| \`procedure\` | Step-by-step instructions the agent follows |
+| \`output\` | Describes what to produce and which \`$status\` values to use |
+| \`frontmatter\` | JSON Schema defining the structured output fields |
+
+### Role Design Principles
+
+- **Single responsibility** — each role does one thing well
+- **Minimal context** — don't overload a role with too many steps; split if needed
+- **Clear status values** — each status should map to a distinct graph edge
+- **Explicit output** — tell the agent exactly what \`$status\` values are valid
+
+## Frontmatter Schema
+
+The \`frontmatter\` field is a standard JSON Schema. It defines the structured fields the agent must output in YAML frontmatter.
+
+### \`$status\` Field
+
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:
+
+\`\`\`yaml
+frontmatter:
+  oneOf:
+    - properties:
+        $status: { const: "done" }
+        result: { type: string }
+      required: [$status, result]
+    - properties:
+        $status: { const: "failed" }
+        error: { type: string }
+      required: [$status, error]
+\`\`\`
+
+### Custom Fields
+
+Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
+
+### Flat Schema (Single Status)
+
+When a role has only one outcome:
+
+\`\`\`yaml
+frontmatter:
+  properties:
+    $status: { const: "done" }
+    summary: { type: string }
+  required: [$status, summary]
+\`\`\`
+
+## Graph Routing
+
+The graph maps each role's \`$status\` values to the next role:
+
+\`\`\`
+graph[role][$status] → { role: nextRole, prompt: edgePrompt }
+\`\`\`
+
+### Special Nodes
+
+| Node | Purpose |
+|------|---------|
+| \`$START\` | Entry point — status key is always \`_\` (unconditional) |
+| \`$END\` | Terminal — thread completes and is archived |
+
+### Edge Prompts
+
+Use triple-brace Mustache (\`{{{field}}}\`) to pass data from the previous step's output:
+
+\`\`\`yaml
+graph:
+  planner:
+    ready: { role: developer, prompt: "Implement plan {{{plan}}} in {{{repoPath}}}." }
+\`\`\`
+
+The fields referenced must exist in the source role's frontmatter schema.
+
+### Loops and Branching
+
+Roles can route back to previous roles (loops) or to different roles based on status (branching):
+
+\`\`\`yaml
+graph:
+  reviewer:
+    approved: { role: tester, prompt: "Run tests." }
+    rejected: { role: developer, prompt: "Fix: {{{comments}}}" }  # loop back
+\`\`\`
+
+### Fail Routing
+
+Route failures to a cleanup role or \`$END\`:
+
+\`\`\`yaml
+graph:
+  developer:
+    done: { role: reviewer, prompt: "Review changes." }
+    failed: { role: cleanup, prompt: "Clean up: {{{error}}}" }
+\`\`\`
+
+## Self-Testing
+
+### Step-by-Step Verification
+
+\`\`\`bash
+# Start a thread directly from YAML file (no registration needed)
+uwf thread start my-workflow.yaml -p "Test prompt"
+
+# Or register first, then start by name
+uwf workflow add my-workflow.yaml
+uwf thread start my-workflow -p "Test prompt"
+
+# Execute one step at a time to verify routing
+uwf thread exec <thread-id>
+
+# Inspect step output
+uwf step list <thread-id>
+uwf step show <step-hash>
+
+# Check the CAS data
+uwf cas get <output-hash>
+\`\`\`
+
+### Validation Checklist
+
+1. Every \`$status\` value in a role's frontmatter has a matching edge in the graph
+2. Every field referenced in edge prompts (\`{{{field}}}\`) exists in the source role's schema
+3. Every role referenced in the graph exists in \`roles\`
+4. \`$START\` has exactly one edge with key \`_\`
+5. At least one path leads to \`$END\`
+6. No orphan roles (defined but never routed to)
+
+## Common Pitfalls
+
+- **Missing graph edge** — if a role can produce \`$status: failed\` but the graph has no \`failed\` edge, the moderator will error
+- **Mustache field mismatch** — referencing \`{{{branch}}}\` in an edge prompt but the source schema has \`branchName\` instead
+- **Overly complex roles** — a role with 20 steps should be split; each role should be completable in one agent turn
+- **No fail path** — always handle failure; route to cleanup or \`$END\`
+`;
+}

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 | agent-kit | hermes | util | protocol
+\`\`\`
+`;
+}

packages/workflow-util/src/index.ts

@@ -1,7 +1,9 @@
 export { generateActorReference } from "./actor-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,
@@ -28,4 +30,5 @@ export { err, ok } from "./result.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
 export type { LogFn, Result } from "./types.js";
 export { extractUlidTimestamp, generateUlid } from "./ulid.js";
+export { generateUserReference } from "./user-reference.js";
 export { generateYamlReference } from "./yaml-reference.js";

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

@@ -0,0 +1,125 @@
+export function generateUserReference(): string {
+  return `# User Reference
+
+Guide for using the uwf CLI to manage workflows and threads.
+
+## Quick Start
+
+\`\`\`bash
+# 1. Configure provider and model
+uwf setup
+
+# 2. Register a workflow
+uwf workflow add my-workflow.yaml
+
+# 3. Start a thread (creates but does not execute)
+uwf thread start my-workflow -p "Build a login page"
+
+# 4. Execute the thread (runs moderator → agent → extract cycles)
+uwf thread exec <thread-id>          # one step
+uwf thread exec <thread-id> -c 10    # up to 10 steps
+uwf thread exec <thread-id> -c 10 --background  # run in background
+\`\`\`
+
+## Concepts
+
+- **Workflow** — YAML definition with roles and a routing graph; stored as a CAS node
+- **Thread** — A running instance of a workflow; a chain of step nodes in CAS
+- **Step** — One moderator → agent → extract cycle; contains the role's structured output
+- **CAS** — Content-addressable store; every artifact is hashed (XXH64, Crockford Base32)
+
+## Setup
+
+\`\`\`
+uwf setup                                          # interactive wizard
+uwf setup --provider <name> --base-url <url> \\
+           --api-key <key> --model <name>           # non-interactive
+           [--agent <name>]                         # optional default agent
+\`\`\`
+
+Config is stored at \`~/.uncaged/workflow/config.yaml\`. Override storage root with \`UNCAGED_WORKFLOW_STORAGE_ROOT\`.
+
+## Workflow Commands
+
+\`\`\`
+uwf workflow add <file>            # register from YAML file
+uwf workflow show <id>             # show by name or CAS hash
+uwf workflow list                  # list all registered workflows
+\`\`\`
+
+You can also pass a file path directly to \`uwf thread start\` without registering first.
+
+## Thread Lifecycle
+
+\`\`\`
+uwf thread start <workflow> -p <prompt>            # create thread
+uwf thread exec <thread-id>                        # execute one step
+               [--agent <cmd>]                     # override agent
+               [-c, --count <n>]                   # run n steps
+               [--background]                      # run in background
+uwf thread show <thread-id>                        # show head pointer
+uwf thread list                                    # list all threads
+               [--status <filter>]                 # idle, running, completed, cancelled, active (comma-separated)
+               [--after <thread-id>]               # pagination: after this thread
+               [--before <thread-id>]              # pagination: before this thread
+               [--skip <n>]                        # skip first n results
+               [--take <n>]                        # limit results
+uwf thread read <thread-id>                        # render context as markdown
+               [--quota <chars>]                   # max output chars (default 4000)
+               [--before <step-hash>]              # pagination
+               [--start]                           # include start step
+uwf thread stop <thread-id>                        # stop background execution
+uwf thread cancel <thread-id>                      # cancel and archive thread
+\`\`\`
+
+### Typical Lifecycle
+
+\`\`\`
+start → exec (repeat) → thread reaches $END → auto-completed
+                       → or: cancel to abort
+\`\`\`
+
+## Step Commands
+
+\`\`\`
+uwf step list <thread-id>         # list all steps
+uwf step show <step-hash>         # show step details
+uwf step fork <step-hash>         # fork thread from a step (branch)
+\`\`\`
+
+Forking creates a new thread that shares history up to the fork point — useful for retrying from a known-good state.
+
+## CAS Commands
+
+\`\`\`
+uwf cas get <hash>                 # read a node (type + payload)
+            [--timestamp]          # include timestamp
+uwf cas put <type-hash> <data>     # store typed JSON, print hash
+uwf cas put-text <text>            # store plain text, print hash
+uwf cas has <hash>                 # check existence
+uwf cas refs <hash>                # list direct references
+uwf cas walk <hash>                # recursive traversal
+uwf cas reindex                    # rebuild type index
+uwf cas schema list                # list schemas
+uwf cas schema get <hash>          # show schema definition
+\`\`\`
+
+## Log Commands
+
+\`\`\`
+uwf log list                       # list log files
+uwf log show                       # show log entries
+           [--thread <id>]         # filter by thread
+           [--process <pid>]       # filter by process
+           [--date <YYYY-MM-DD>]   # filter by date
+uwf log clean --before <date>      # delete old logs
+\`\`\`
+
+## Global Options
+
+\`\`\`
+uwf --format <json|yaml>           # output format (default: json)
+uwf -V, --version                  # print version
+\`\`\`
+`;
+}