@codemation/agent-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @codemation/agent-skills
+
+## 0.1.0
+
+### Minor Changes
+
+- [#24](https://github.com/MadeRelevant/codemation/pull/24) [`cf5026a`](https://github.com/MadeRelevant/codemation/commit/cf5026a7c83353bb52d67a17d0b8a9ebceb91704) Thanks [@cblokland90](https://github.com/cblokland90)! - Add a publishable Codemation agent skills package and wire the default and plugin starters to extract the shared skills after install.
+
+## 0.0.18
+
+### Patch Changes
+
+- f0c6878: Introduce Changesets, a single CI status check for branch protection, and the Codemation pre-stable license across published packages.

package/LICENSE

@@ -0,0 +1,37 @@
+Codemation Pre-Stable License
+
+Copyright (c) Made Relevant B.V. All rights reserved.
+
+1. Definitions
+
+   "Software" means the Codemation source code, documentation, and artifacts in this repository and any published npm packages in the Codemation monorepo.
+
+   "Stable Version" means the first published release of the package `@codemation/core` on the public npm registry with version 1.0.0 or higher.
+
+2. Permitted use (before Stable Version)
+
+   Until a Stable Version exists, you may use, copy, modify, and distribute the Software only for non-commercial purposes, including personal learning, research, evaluation, and internal use within your organization that does not charge third parties for access to the Software or a product or service whose primary value is the Software.
+
+3. Restrictions (before Stable Version)
+
+   Until a Stable Version exists, you must not:
+
+   a) Sell, rent, lease, or sublicense the Software or a derivative work for a fee;
+
+   b) Offer the Software or a derivative work as part of a paid product or service (including hosting, support, or consulting) where the Software is a material part of the offering;
+
+   c) Use the Software or a derivative work primarily to generate revenue or commercial advantage for you or others.
+
+   These restrictions apply to all versions published before a Stable Version, even if a later Stable Version is released under different terms.
+
+4. After Stable Version
+
+   The maintainers may publish a Stable Version under different license terms. If they do, those terms apply only to that Stable Version and subsequent releases they designate; they do not automatically apply to earlier pre-stable versions.
+
+5. No warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6. Third-party components
+
+   The Software may include third-party components under their own licenses. Those licenses govern those components.

package/README.md

@@ -0,0 +1,29 @@
+# `@codemation/agent-skills`
+
+Publishable Codemation agent skills packaged as `SKILL.md` directories.
+
+## What this package contains
+
+- shared Codemation skills for CLI usage, workflow authoring, plugin development, credentials, and framework concepts
+- a small extraction CLI that copies the packaged skills into a project-local `.agents/skills` directory
+
+## Install in a project
+
+```bash
+pnpm add -D @codemation/agent-skills
+codemation-agent-skills extract --output .agents/skills/extracted
+```
+
+The starter templates call the extractor automatically after `pnpm install`.
+
+## Published layout
+
+```text
+skills/
+  codemation-cli/
+  codemation-workflow-dsl/
+  codemation-custom-node-development/
+  codemation-plugin-development/
+  codemation-credential-development/
+  codemation-framework-concepts/
+```

package/bin/codemation-agent-skills.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import process from "node:process";
+import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export class CommandError extends Error {}
+
+export class FileSystemGateway {
+  async copyDirectory(sourcePath, destinationPath) {
+    await cp(sourcePath, destinationPath, { force: true, recursive: true });
+  }
+
+  async createDirectory(targetPath) {
+    await mkdir(targetPath, { recursive: true });
+  }
+
+  async listDirectoryEntries(targetPath) {
+    return readdir(targetPath, { withFileTypes: true });
+  }
+
+  async removePath(targetPath) {
+    await rm(targetPath, { force: true, recursive: true });
+  }
+
+  async statPath(targetPath) {
+    return stat(targetPath);
+  }
+}
+
+export class SkillExtractor {
+  constructor(fileSystem, packageRoot, cwd, stdout) {
+    this.fileSystem = fileSystem;
+    this.packageRoot = packageRoot;
+    this.cwd = cwd;
+    this.stdout = stdout;
+  }
+
+  async extract(outputArgument) {
+    const outputPath = path.resolve(this.cwd, outputArgument);
+    const skillsRoot = path.join(this.packageRoot, "skills");
+
+    await this.fileSystem.createDirectory(outputPath);
+    const packagedEntries = await this.fileSystem.listDirectoryEntries(skillsRoot);
+    const packagedSkillNames = new Set(
+      packagedEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
+    );
+
+    await this.#removeStaleSkillDirectories(outputPath, packagedSkillNames);
+
+    for (const skillName of packagedSkillNames) {
+      const sourcePath = path.join(skillsRoot, skillName);
+      const destinationPath = path.join(outputPath, skillName);
+      await this.fileSystem.removePath(destinationPath);
+      await this.fileSystem.copyDirectory(sourcePath, destinationPath);
+      this.stdout.write(`[codemation-agent-skills] extracted ${skillName}\n`);
+    }
+  }
+
+  async #removeStaleSkillDirectories(outputPath, packagedSkillNames) {
+    let existingEntries;
+    try {
+      existingEntries = await this.fileSystem.listDirectoryEntries(outputPath);
+    } catch {
+      return;
+    }
+
+    for (const entry of existingEntries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (!entry.name.startsWith("codemation-")) {
+        continue;
+      }
+      if (packagedSkillNames.has(entry.name)) {
+        continue;
+      }
+      await this.fileSystem.removePath(path.join(outputPath, entry.name));
+    }
+  }
+}
+
+export class CommandLineParser {
+  constructor(argv) {
+    this.argv = argv;
+  }
+
+  parse() {
+    const [command, ...rest] = this.argv;
+    if (!command || command === "--help" || command === "-h") {
+      return { command: "help" };
+    }
+    if (command !== "extract") {
+      throw new CommandError(`Unknown command "${command}".`);
+    }
+
+    let output = ".agents/skills/extracted";
+    for (let index = 0; index < rest.length; index += 1) {
+      const argument = rest[index];
+      if (argument === "--output") {
+        const value = rest[index + 1];
+        if (!value) {
+          throw new CommandError("Missing value for --output.");
+        }
+        output = value;
+        index += 1;
+        continue;
+      }
+      if (argument === "--help" || argument === "-h") {
+        return { command: "help" };
+      }
+      throw new CommandError(`Unknown argument "${argument}".`);
+    }
+
+    return { command: "extract", output };
+  }
+}
+
+export class CodemationAgentSkillsCli {
+  constructor(argv, cwd, stdout, stderr) {
+    this.argv = argv;
+    this.cwd = cwd;
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.fileSystem = new FileSystemGateway();
+  }
+
+  async run() {
+    try {
+      const parsed = new CommandLineParser(this.argv).parse();
+      if (parsed.command === "help") {
+        this.#writeHelp();
+        return;
+      }
+
+      const packageRoot = path.resolve(import.meta.dirname, "..");
+      const extractor = new SkillExtractor(this.fileSystem, packageRoot, this.cwd, this.stdout);
+      await extractor.extract(parsed.output);
+    } catch (error) {
+      if (error instanceof CommandError) {
+        this.stderr.write(`${error.message}\n\n`);
+        this.#writeHelp();
+        process.exitCode = 1;
+        return;
+      }
+      this.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = 1;
+    }
+  }
+
+  #writeHelp() {
+    this.stdout.write(
+      [
+        "codemation-agent-skills",
+        "",
+        "Usage:",
+        "  codemation-agent-skills extract [--output <path>]",
+        "",
+        "Commands:",
+        "  extract    Copy packaged Codemation skills into a project directory.",
+        "",
+        "Options:",
+        "  --output   Destination directory. Defaults to .agents/skills/extracted.",
+        "",
+      ].join("\n"),
+    );
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await new CodemationAgentSkillsCli(process.argv.slice(2), process.cwd(), process.stdout, process.stderr).run();
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@codemation/agent-skills",
+  "version": "0.1.0",
+  "description": "Reusable agent skills for Codemation projects and plugin development.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Made Relevant B.V.",
+  "homepage": "https://www.maderelevant.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MadeRelevant/codemation",
+    "directory": "packages/agent-skills"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "codemation-agent-skills": "./bin/codemation-agent-skills.mjs"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": [
+    "codemation",
+    "agent",
+    "skills",
+    "cursor",
+    "copilot"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "bin",
+    "skills"
+  ]
+}

package/skills/codemation-cli/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: codemation-cli
+description: Guides Codemation CLI work for consumer apps and framework-author development. Use when the user asks about `codemation dev`, `build`, `serve web`, `serve worker`, `user create`, `user list`, `--consumer-root`, `.codemation/output`, or consumer versus framework-author mode.
+compatibility: Designed for Codemation repositories and projects that use the Codemation CLI.
+---
+
+# Codemation CLI
+
+## Use this skill when
+
+Use this skill for command selection, local development flow, and CLI troubleshooting in a Codemation app or monorepo.
+
+Do not use this skill for workflow graph design, custom node implementation, or credential modeling unless the CLI command flow is the main question.
+
+## Default approach
+
+1. Confirm whether the user is in a standalone consumer project or the Codemation monorepo.
+2. Prefer `codemation --help` or `codemation <command> --help` before guessing flags.
+3. Explain the shortest command path first, then mention framework-author alternatives only if they matter.
+4. Keep the CLI thin in your mental model: it orchestrates host and runtime packages instead of owning workflow logic itself.
+
+## Command map
+
+- `codemation dev`: default consumer development flow with packaged UI and a stable CLI-owned dev gateway.
+- `codemation dev --watch-framework`: framework-author mode for monorepo work and `next-host` UI HMR.
+- `codemation build`: emits production-oriented consumer output under `.codemation/output/build`.
+- `codemation serve web`: runs the packaged web host for a built or configured consumer app.
+- `codemation serve worker`: starts the queue-backed worker runtime when execution is separated.
+- `codemation user create` and `codemation user list`: local-auth bootstrap and inspection commands.
+
+## Working rules
+
+1. Treat `codemation.config.ts` as the consumer entrypoint.
+2. Mention `.codemation/output` only when build artifacts or runtime bootstrap details matter.
+3. When the user is in the monorepo, distinguish framework-author mode from normal consumer mode explicitly.
+4. When Redis-backed execution is involved, mention the shared PostgreSQL requirement instead of assuming PGlite still fits.
+
+## Read next when needed
+
+- Read `references/command-map.md` for command responsibilities and development-mode guidance.

package/skills/codemation-cli/references/command-map.md

@@ -0,0 +1,62 @@
+# Command Map
+
+## Mental model
+
+- `@codemation/cli` is a thin orchestration layer.
+- It wires command objects and runtime helpers.
+- It does not own workflow definitions, the Next UI implementation, or the engine itself.
+
+## Pick the right mode
+
+### Consumer mode
+
+Use `codemation dev` for a standalone Codemation app.
+
+- The CLI starts the packaged `@codemation/next-host` UI.
+- The CLI owns a stable development gateway.
+- The CLI hot-swaps the in-process API runtime when consumer files change.
+
+### Framework-author mode
+
+Use `codemation dev --watch-framework` when working inside the Codemation monorepo.
+
+- The CLI starts `next dev` for `@codemation/next-host`.
+- The CLI still owns the stable gateway and runtime swapping.
+- This mode is for framework package work, not normal consumer usage.
+
+## Command responsibilities
+
+### `codemation dev`
+
+- default local development flow
+- best for consumer projects
+
+### `codemation build`
+
+- emits build output under `.codemation/output/build`
+- use for production-oriented packaging flows
+
+### `codemation serve web`
+
+- runs the packaged web surface
+- useful when validating runtime wiring outside the dev hot-swap flow
+
+### `codemation serve worker`
+
+- starts the queue-backed worker runtime
+- use when web and worker processes are separated
+
+### `codemation user create`
+
+- creates or updates a local-auth bootstrap user
+- requires local auth and database access
+
+### `codemation user list`
+
+- lists known users through the host query flow
+
+## Environment notes
+
+- PGlite is the zero-setup default for starter apps.
+- When `REDIS_URL` is set, use a shared PostgreSQL `DATABASE_URL`; BullMQ cannot run on PGlite.
+- Use `--consumer-root` when commands need to target a different consumer app root.

package/skills/codemation-credential-development/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: codemation-credential-development
+description: Guides Codemation custom credential development with `defineCredential(...)`, typed sessions, credential testing, and node credential slots. Use when creating or updating custom credentials, credential registrations, or credential-aware custom nodes.
+compatibility: Designed for Codemation apps and plugins that register typed credentials.
+---
+
+# Codemation Credential Development
+
+## Use this skill when
+
+Use this skill for defining new credential types, wiring them into apps or plugins, and teaching nodes to request typed credential sessions.
+
+Do not use this skill for general workflow authoring unless credential slots or runtime sessions are the core problem.
+
+## Core mental model
+
+1. A credential type defines public config, secret material, session creation, and health testing.
+2. Nodes request credentials through named slots instead of hard-coded secrets.
+3. Operators configure concrete credential instances in the UI and bind them to those slots.
+
+## Authoring rules
+
+1. Start with `defineCredential(...)`.
+2. Keep `public` versus `secret` fields intentional.
+3. Make `createSession(...)` return the typed runtime object the node actually needs.
+4. Implement `test(...)` so failure states are explicit before workflow activation.
+5. Register credential types at the app or plugin boundary, not inside random workflow files.
+
+## Node integration
+
+- helper-defined nodes can declare credentials directly in `credentials`
+- class-based nodes can use lower-level credential requirement APIs when needed
+
+## Read next when needed
+
+- Read `references/credential-patterns.md` for schema, registration, and slot guidance.

package/skills/codemation-credential-development/references/credential-patterns.md

@@ -0,0 +1,47 @@
+# Credential Patterns
+
+## Standard shape
+
+Use `defineCredential(...)` to declare:
+
+- `key`
+- `label`
+- optional `description`
+- `public` fields
+- `secret` fields
+- `createSession(...)`
+- `test(...)`
+
+## Registration
+
+Register the credential type from the app or plugin boundary:
+
+- `defineCodemationApp({ credentials: [...] })`
+- `definePlugin({ credentials: [...] })`
+
+## Node slots
+
+Helper-defined nodes can request credentials directly:
+
+```ts
+credentials: {
+  myService: myServiceCredential,
+}
+```
+
+Then the runtime can supply a typed session through the named slot.
+
+## Health and activation
+
+- deploy the workflow and credential type
+- configure a concrete credential instance in the UI
+- run the credential test until it is healthy
+- activate the workflow only when the required slots can resolve correctly
+
+## When to drop lower
+
+Reach for lower-level credential APIs when:
+
+- a class-based node already needs the explicit runtime contract
+- you need advanced host registry behavior
+- helper-based declarations are no longer expressive enough

package/skills/codemation-custom-node-development/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: codemation-custom-node-development
+description: Guides Codemation custom node development with `defineNode(...)`, reusable node modules, credential-aware nodes, and the class-based node fallback for advanced cases. Use when creating or updating custom nodes for apps or plugin packages.
+compatibility: Designed for Codemation apps and plugin packages that define reusable nodes.
+---
+
+# Codemation Custom Node Development
+
+## Use this skill when
+
+Use this skill for reusable custom node work, whether the node lives inside an app or a published plugin package.
+
+Do not use this skill for pure workflow chaining questions unless the node implementation itself is changing.
+
+## Default approach
+
+1. Start with `defineNode(...)`.
+2. Keep the runtime behavior in `run(...)`.
+3. Give the node a stable key and a clear title.
+4. Promote callback-heavy logic into a node when the graph or tests need a stronger boundary.
+
+## Node rules
+
+1. Prefer helper-based nodes first.
+2. Keep nodes deterministic and focused.
+3. Request credentials through named slots instead of hard-coded secrets.
+4. Remember that runtime execution receives batches of items.
+5. Drop to class-based node APIs only when you need constructor-injected collaborators, decorators, or deeper runtime metadata.
+
+## Read next when needed
+
+- Read `references/node-patterns.md` for `defineNode(...)` patterns and packaging guidance.

package/skills/codemation-custom-node-development/references/node-patterns.md

@@ -0,0 +1,50 @@
+# Node Patterns
+
+## Start here
+
+Use `defineNode(...)` when:
+
+- the node logic is straightforward
+- the node belongs to one app or plugin package
+- helper-based credential slots are enough
+
+## Standard helper shape
+
+```ts
+export const uppercaseNode = defineNode({
+  key: "example.uppercase",
+  title: "Uppercase field",
+  input: {
+    field: "string",
+  },
+  run(items, { config }) {
+    return items.map((item) => ({
+      ...item,
+      [config.field]: String(item[config.field as keyof typeof item] ?? "").toUpperCase(),
+    }));
+  },
+});
+```
+
+## When a custom node pays off
+
+Move from an inline callback to a custom node when:
+
+- the workflow graph needs a clear reusable step
+- the logic is shared across workflows
+- tests need a stable module boundary
+- credential or dependency boundaries should be explicit
+
+## Advanced fallback
+
+Reach for class-based node APIs when:
+
+- constructor-injected collaborators are required
+- plugin packaging needs the lower-level runtime contract
+- decorators or persisted metadata need tighter control
+
+## Runtime reminder
+
+- nodes process batches of items
+- keep them deterministic and testable
+- prefer real code paths or in-memory collaborators over heavy mocking

package/skills/codemation-framework-concepts/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: codemation-framework-concepts
+description: Explains Codemation package boundaries, runtime concepts, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, or runtime modes.
+compatibility: Designed for Codemation apps, plugins, and framework contributors.
+---
+
+# Codemation Framework Concepts
+
+## Use this skill when
+
+Use this skill to explain package ownership, runtime shape, and the boundary between consumer code and framework code.
+
+Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin implementation guidance when the user already knows the concept they need.
+
+## Core map
+
+1. `@codemation/core` owns the engine, runtime contracts, and workflow DSL foundations.
+2. `@codemation/host` adds config loading, persistence, credentials, APIs, and scheduler wiring.
+3. `@codemation/next-host` owns the framework UI.
+4. `@codemation/cli` runs local development, build, serve, and user commands.
+5. Consumer apps define `codemation.config.ts` and workflow files.
+
+## Important concepts
+
+- workflows define behavior
+- triggers start runs
+- nodes process items
+- items carry workflow data
+- credentials provide typed runtime resources
+- activation is framework-managed and happens in the UI
+
+## Runtime rule of thumb
+
+1. Start with the minimum setup.
+2. Move to shared PostgreSQL and Redis when execution needs separate worker infrastructure.
+3. Keep workflow code stable while the runtime shape grows around it.
+
+## Read next when needed
+
+- Read `references/architecture-map.md` for package ownership and runtime-mode guidance.

package/skills/codemation-framework-concepts/references/architecture-map.md

@@ -0,0 +1,47 @@
+# Architecture Map
+
+## Main packages
+
+- `@codemation/core`: engine, workflow DSL foundations, runtime contracts, planning, execution
+- `@codemation/host`: config loading, persistence, credentials, scheduler wiring, API surface
+- `@codemation/next-host`: framework-owned operator UI
+- `@codemation/cli`: `dev`, `build`, `serve web`, `serve worker`, and user commands
+
+## Where app code lives
+
+In a normal Codemation app, most user code lives in:
+
+- `codemation.config.ts`
+- `src/workflows/**/*.ts`
+- optional custom node modules or packages
+- optional credential registrations
+
+## Minimum setup
+
+Use the minimum setup when:
+
+- you are starting a new app
+- one process is enough
+- local PGlite is fine
+- fast local iteration matters more than shared worker infrastructure
+
+## Production setup
+
+Move to the production shape when:
+
+- web and worker processes should be separate
+- workflows are long-running or bursty
+- you need shared staging or production infrastructure
+- queue-backed execution is a better fit than inline execution
+
+That usually means:
+
+- PostgreSQL instead of embedded PGlite
+- Redis for queue-backed execution
+- BullMQ-backed scheduling
+
+## Activation flow
+
+- deploy the workflow definition and any supporting plugin changes
+- configure and test credentials in the UI
+- activate the workflow only when the environment is ready

package/skills/codemation-plugin-development/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: codemation-plugin-development
+description: Guides Codemation plugin package development, including `definePlugin(...)`, plugin sandboxes, custom nodes, custom credentials, and publishable plugin package structure. Use when building or updating a Codemation plugin package or the plugin starter template.
+compatibility: Designed for Codemation plugin packages and the Codemation plugin starter template.
+---
+
+# Codemation Plugin Development
+
+## Use this skill when
+
+Use this skill for published plugin packages, plugin starter work, and sandbox-driven plugin development.
+
+Do not use this skill for ordinary consumer workflow-only changes unless the work needs plugin packaging or reusable extension boundaries.
+
+## Default approach
+
+1. Treat `codemation.plugin.ts` as the plugin composition root.
+2. Register custom credentials and custom nodes from explicit modules.
+3. Keep the sandbox app small and useful so plugin behavior is testable immediately.
+4. Prefer helper-based node and credential definitions first, then drop to class-based APIs only when needed.
+
+## Plugin rules
+
+1. Export a plugin with `definePlugin(...)`.
+2. Keep plugin registration separate from node and credential implementation modules.
+3. Use the sandbox app to exercise the plugin right away.
+4. Keep the package publishable like a normal npm package.
+
+## Common plugin pieces
+
+- `codemation.plugin.ts`: plugin registration and sandbox app
+- `src/nodes/*`: custom node definitions
+- `src/credentialTypes/*`: custom credential definitions
+- `src/index.ts`: package exports
+
+## Read next when needed
+
+- Read `references/plugin-structure.md` for package layout and node-versus-credential guidance.

package/skills/codemation-plugin-development/references/plugin-structure.md

@@ -0,0 +1,38 @@
+# Plugin Structure
+
+## Minimal package shape
+
+```text
+codemation.plugin.ts
+src/
+  credentialTypes/
+  nodes/
+  index.ts
+```
+
+## Composition root
+
+Use `codemation.plugin.ts` as the single place that:
+
+- calls `definePlugin(...)`
+- registers the plugin's credentials
+- registers the plugin's nodes
+- defines a small sandbox app through `defineCodemationApp(...)`
+
+## Node guidance
+
+- start with `defineNode(...)` for simple reusable nodes
+- keep runtime logic close to the node definition
+- move to class-based node APIs when you need constructor-injected collaborators or deeper runtime metadata
+
+## Credential guidance
+
+- start with `defineCredential(...)`
+- build typed sessions in `createSession(...)`
+- implement `test(...)` so operators can validate configuration before activation
+
+## Publishability
+
+- keep the package build output and plugin entry explicit
+- treat the plugin as a normal npm package
+- installing the package in a Codemation app should be enough for the common auto-discovery flow

package/skills/codemation-workflow-dsl/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: codemation-workflow-dsl
+description: Guides Codemation workflow authoring with the fluent Workflow DSL. Use when creating or updating `workflow("...")` definitions, triggers, `.map(...)`, `.node(...)`, branch flow, item handling, or `.build()` chains in `src/workflows`.
+compatibility: Designed for Codemation apps and plugins that author workflows with the fluent DSL.
+---
+
+# Codemation Workflow DSL
+
+## Use this skill when
+
+Use this skill for authoring or reviewing workflow definitions built with `workflow("...")`.
+
+Do not use this skill for CLI-only troubleshooting or deep host architecture questions unless they directly affect workflow authoring.
+
+## Core mental model
+
+1. A workflow definition describes how items move from a trigger through downstream steps.
+2. The fluent authoring chain is the normal starting point for Codemation apps.
+3. Finish fluent workflow definitions with `.build()`.
+4. Think in batches of items, not single-record callbacks.
+
+## Authoring rules
+
+1. Prefer the fluent `workflow(...)` chain for app-local workflow files.
+2. Keep workflow files focused on orchestration and named steps.
+3. Use custom nodes when a callback grows into reusable product logic.
+4. Remember that node execution receives batches of items, even when examples look single-item.
+
+## Typical flow
+
+1. Start with `workflow("wf.example.id")`.
+2. Name the workflow with `.name(...)`.
+3. Add a trigger such as `.manualTrigger(...)`.
+4. Add transformations or nodes in execution order.
+5. End with `.build()`.
+
+## Read next when needed
+
+- Read `references/builder-patterns.md` for item-flow rules and fluent authoring patterns.

package/skills/codemation-workflow-dsl/references/builder-patterns.md

@@ -0,0 +1,44 @@
+# Builder Patterns
+
+## Standard workflow shape
+
+```ts
+export default workflow("wf.example.id")
+  .name("Example")
+  .manualTrigger("Start", {
+    step: "start",
+  })
+  .map("Transform", (item) => ({
+    ...item,
+    transformed: true,
+  }))
+  .build();
+```
+
+## Use the fluent DSL by default
+
+- import `workflow` from `@codemation/host`
+- keep the file under `src/workflows`
+- export the built workflow definition as the default export when following starter patterns
+
+## Item rules
+
+- workflow data flows as items
+- items usually carry `json` data and optional `binary` data
+- runtime nodes receive batches of items, not just one record
+- author workflow steps with batching in mind
+
+## When to move beyond callbacks
+
+Promote inline callbacks into custom nodes when:
+
+- the logic is reused across workflows
+- the workflow graph needs clearer names
+- credentials or collaborators need explicit boundaries
+- the callback has become hard to test in isolation
+
+## Relationship to the engine
+
+- the fluent DSL is the friendly authoring surface
+- `@codemation/core` still owns planning, execution, continuation, and runtime contracts
+- host and node packages add the surrounding product capabilities